com.codemonster.surinam.export.core
Interface ServiceFinder

All Superinterfaces:

InterceptorLifecycle

All Known Implementing Classes:

ServiceFinderImpl

public interface ServiceFinder
extends InterceptorLifecycle

The serviceFinder interface is how clients find the service references that they can use at runtime. Service Implementations that also wish to consume other service API, should hold a reference to this object internally. Subclasses will also need to support lifecycle callbacks which will help interceptors maintain any held references. This happens automatically when working with Action Documents but if you are manipulating the Service Block programmatically, you will need to make the call to the block via its admin interface to invalidate the references. This will cause the block to trigger the call back to the Finder which keeps track of all the proxies it created and notifies them that they need to update their references as they may be invalid.

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 contractClass) 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.
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.

Methods inherited from interface com.codemonster.surinam.export.lifecycle.InterceptorLifecycle

invalidateReferences

Method Detail

isRegisteredContract

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.

Parameters:

serviceContractClassName - The name of the Service Contract target.

Returns:

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

getServiceClass

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.

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).

getService

Object getService(Class serviceContractClass)
                  throws UnavailableServiceException,
                         UnknownServiceException,
                         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.

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:

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.

See Also:

getServiceClass(java.lang.String)

getService

Object getService(Class serviceContractClass,
                  ServiceInvocationRouter invocationRouter)
                  throws UnavailableServiceException,
                         UnknownServiceException,
                         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.

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:

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.

See Also:

getServiceClass(java.lang.String)

getService

Object getService(String serviceContractClassName)
                  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.

Parameters:

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

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.

getService

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.

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.

getStaticService

ManagedService getStaticService(Class contractClass)
                                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.

Parameters:

contractClass - 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

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.

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.