com.codemonster.surinam.core.framework
Class ServiceFinderImpl

java.lang.Object
  com.codemonster.surinam.core.framework.ServiceFinderImpl

All Implemented Interfaces:

ServiceFinder, InterceptorLifecycle

public class ServiceFinderImpl
extends Object
implements ServiceFinder

Constructor Summary

ServiceFinderImpl(ServiceBlock serviceBlock)

Method Summary

Object	getService(Class serviceContractClass) This is the primary method, by which, a client will acquire a proxy reference that it can use to consume a registered service.
Object	getService(Class serviceContractClass, ServiceInvocationRouter invocationRouter) This is the primary method, by which, a client will acquire a proxy reference that it can use to consume a registered service.
Object	getService(String serviceContractClassName) Recognizing the difficulties in making the distinction between identical class objects loaded in conflicting loader contexts, we simply asking for the service based on the fully-qualified string where the internal directory will resolve the FQN to the correct class instance.
Object	getService(String serviceContractClassName, ServiceInvocationRouter invocationRouter) Recognizing the difficulties in making the distinction between identical class objects loaded in conflicting loader contexts, we simply asking for the service based on the fully-qualified string where the internal directory will resolve the FQN to the correct class instance.
Class	getServiceClass(String serviceContractClassName) Because fully-qualified class names also include loader information, Class objects from different loaders are not the same, in some circumstances, class loader problems can be the result of a polluted runtime environment, it is recommended that you acquire a class reference directly from the Finder itself since it will return the exact reference that the Service Block is using.
ManagedService	getStaticService(Class serviceContractClass) Takes a Contract Class object and returns the associated Service.
ManagedService	getStaticService(String serviceContractClassName) Takes a fully-qualified string name of the Contract Class and returns the associated service object.
void	invalidateReferences() This callback is for routing interceptors to know that they should flush any references to services they might be holding on to.
boolean	isRegisteredContract(String serviceContractClassName) For situations where you wish to see if a given Service Contract is actually registered with the Service Block, we provide this simple query.
void	setServiceBlock(ServiceBlock serviceBlock) standard setter

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServiceFinderImpl

public ServiceFinderImpl(ServiceBlock serviceBlock)

Method Detail

getService

public Object getService(Class serviceContractClass,
                         ServiceInvocationRouter invocationRouter)
                  throws UnknownServiceException,
                         UnavailableServiceException,
                         ClassNotFoundException

This is the primary method, by which, a client will acquire a proxy reference that it can use to consume a registered service. This differs from the simpler 'getService' method in that you can pass in an instance of an InvocationHandler to control how the proxy finds and eventually makes the invocation.

Note that rather than directly instantiate the class locally and possibly end up with a reference to a class from the wrong loader, it takes a class instance. You should acquire the class reference from the finder method specifically for this purpose.

Note that the return needs to be of type Object to conform to Java's proxy mechanism.

Specified by:

getService in interface ServiceFinder

Parameters:

serviceContractClass - This is the class object of the service contract(interface) that the client wants to use. This interface will be mated with an object that can perform all service-management-related activities.

invocationRouter - This is an implementation of the InvocationHandler interface designed to replace the standard Surinam InvocationRouter that the proxy uses.

Returns:

Returns an object that implements the given interface and can be used as if it was a local object.

Throws:

UnknownServiceException - This will be thrown when the requested interface is unknown to the system, usually because the service was never installed or registered.

UnavailableServiceException - This is thrown if the service is known but a usable organization object cannot be found.

ClassNotFoundException - Thrown if there's a problem with the service name given.

See Also:

ServiceFinder.getServiceClass(java.lang.String)

getService

public Object getService(Class serviceContractClass)
                  throws UnknownServiceException,
                         UnavailableServiceException,
                         ClassNotFoundException

This is the primary method, by which, a client will acquire a proxy reference that it can use to consume a registered service. The resulting proxy will use a standard Surinam InvocationRouter.

Note that it takes a class instance; rather than directly instantiate the class locally and possibly end up with a reference to a class in the wrong loader, you should acquire the class reference from the finder method specifically for this purpose.

Note that the return needs to be of type Object to conform to Java's proxy mechanism.

Specified by:

getService in interface ServiceFinder

Parameters:

serviceContractClass - This is the class object of the service contract(interface) that the client wants to use. This interface will be mated with an object that can perform all service-management-related activities.

Returns:

Returns an object that implements the given interface and can be used as if it was a local object.

Throws:

UnknownServiceException - This will be thrown when the requested interface is unknown to the system, usually because the service was never installed or registered.

UnavailableServiceException - This is thrown if the service is known but a usable organization object cannot be found.

ClassNotFoundException - Thrown if there's a problem with the service name given.

See Also:

ServiceFinder.getServiceClass(java.lang.String)

getService

public Object getService(String serviceContractClassName)
                  throws UnknownServiceException,
                         ClassNotFoundException,
                         UnavailableServiceException

Recognizing the difficulties in making the distinction between identical class objects loaded in conflicting loader contexts, we simply asking for the service based on the fully-qualified string where the internal directory will resolve the FQN to the correct class instance. However, if you are not structuring your application correctly, you can still get class cast failures due to loader issues. You cannot assume that all Class references are equal, particularly if they refer to Class objects from different loaders; this is also true of interfaces.

Note that the return needs to be of type Object to conform to Java's proxy mechanism.

Specified by:

getService in interface ServiceFinder

Parameters:

serviceContractClassName - This is the name of the Service Contract Class.

Returns:

Returns the Service object that is bound to the given Contract.

Throws:

UnknownServiceException - This will be thrown when the requested interface is unknown to the system, usually because the service was never installed or registered.

ClassNotFoundException - Thrown if there's a problem with the service name given.

UnavailableServiceException - This is thrown if the service is known but a usable organization object cannot be found.

getService

public Object getService(String serviceContractClassName,
                         ServiceInvocationRouter invocationRouter)
                  throws UnavailableServiceException,
                         UnknownServiceException,
                         ClassNotFoundException

Recognizing the difficulties in making the distinction between identical class objects loaded in conflicting loader contexts, we simply asking for the service based on the fully-qualified string where the internal directory will resolve the FQN to the correct class instance. However, if you are not structuring your application correctly, you can still get class cast failures due to loader issues. You cannot assume that all Class references are equal, particularly if they refer to Class objects from different loaders; this is also true of interfaces.

Note that the return needs to be of type Object to conform to Java's proxy mechanism.

Specified by:

getService in interface ServiceFinder

Parameters:

serviceContractClassName - This is the name of the Service Contract Class.

invocationRouter - This is an implementation of the InvocationHandler interface designed to the replace the standard Surinam InvocationRouter that the proxy uses.

Returns:

Returns the Service object that is bound to the given Contract.

Throws:

UnavailableServiceException - This is thrown if the service is known but a usable organization object cannot be found.

UnknownServiceException - This will be thrown when the requested interface is unknown to the system, usually because the service was never installed or registered.

ClassNotFoundException - Thrown if there's a problem with the service name given.

isRegisteredContract

public boolean isRegisteredContract(String serviceContractClassName)

For situations where you wish to see if a given Service Contract is actually registered with the Service Block, we provide this simple query.

Specified by:

isRegisteredContract in interface ServiceFinder

Parameters:

serviceContractClassName - The name of the Service Contract target.

Returns:

Returns whether or not this Contract is known to the Service Directory.

getServiceClass

public Class getServiceClass(String serviceContractClassName)
                      throws ClassNotFoundException

Because fully-qualified class names also include loader information, Class objects from different loaders are not the same, in some circumstances, class loader problems can be the result of a polluted runtime environment, it is recommended that you acquire a class reference directly from the Finder itself since it will return the exact reference that the Service Block is using. Then that reference can be used for requesting a service in a rigorous manner.

Specified by:

getServiceClass in interface ServiceFinder

Parameters:

serviceContractClassName - This is the String class name of the Contract, for which, we want an implementation that we can use.

Returns:

Returns the class instance being used by the ServiceBlock as a Contract key.

Throws:

ClassNotFoundException - Thrown if there is a class loader problem (usually in the meta-data).

getStaticService

public ManagedService getStaticService(Class serviceContractClass)
                                throws UnavailableServiceException,
                                       UnknownServiceException

Takes a Contract Class object and returns the associated Service. Since this method takes a class object that will be matched in the Service Block, this class needs to be one that is acquired via the block's 'getContractClass()' method. This will ensure that the class is known to the block.

Note: This method returns a reference to the actual implementation object, which would be slightly more efficient at the expense of dynamic invocation and runtime upgradability. Dynamic runtime services should be acquired via the ServiceFinder and not directly from the ServiceBlock.

Specified by:

getStaticService in interface ServiceFinder

Parameters:

serviceContractClass - The fully-qualified class name of the service contract.

Returns:

Returns a ManagedService object that can be cast to the given contract type.

Throws:

UnavailableServiceException - This is thrown if the service reports that it is unavailable.

UnknownServiceException - Thrown if the service is unknown to the block.

getStaticService

public ManagedService getStaticService(String serviceContractClassName)
                                throws UnavailableServiceException,
                                       UnknownServiceException,
                                       ClassNotFoundException

Takes a fully-qualified string name of the Contract Class and returns the associated service object. This method essentially combines the steps of two other ServiceBlock methods, one to acquire the class from the Service Block and the second to pass in the class to get the service implementation.

Note: This method returns a reference to the actual implementation object, which would be slightly more efficient at the expense of dynamic invocation and runtime upgradability. Dynamic runtime services should be acquired via the ServiceFinder and not directly from the ServiceBlock.

Specified by:

getStaticService in interface ServiceFinder

Parameters:

serviceContractClassName - fq name of the service contract.

Returns:

Returns a ManagedService object that can be cast to the given contract type.

Throws:

UnavailableServiceException - Thrown if the service reports that it is unavailable.

UnknownServiceException - Thrown if the service is unknown to the block.

ClassNotFoundException - Thrown if the given class doesn't map to anything in the Service Block.

setServiceBlock

public void setServiceBlock(ServiceBlock serviceBlock)

standard setter

Parameters:

serviceBlock - The service block instance for the Finder to use.

invalidateReferences

public void invalidateReferences()

This callback is for routing interceptors to know that they should flush any references to services they might be holding on to. They may or may not reacquire a new reference at that time (they could choose a lazy-loading strategy).

Specified by:

invalidateReferences in interface InterceptorLifecycle