com.codemonster.surinam.export.framework
Interface ServiceDirectoryAdmin

All Known Implementing Classes:

ServiceDirectoryImpl

public interface ServiceDirectoryAdmin

This is the administrative API for the ServiceDirectory. This API will allow you to completely manage contracts and implementations.

Registration applies to Contracts and means to make it available in the ServiceDirectory and to assign it a default implementation.

Retirement applies to Contracts and makes them no longer visible in the directory.

Assignment applies to ProviderImplementations and takes the given ManagedService object and assigns it to one or more Contracts, thus making it available to be called from clients.

Recall applies to ProviderImplementations which have been assigned to service contracts. Their assignment is said to be 'recinded' and they are recalled to where they came from.

First of all, there are no registered services that have no implementations; however, this simply means that when a service is registered, a default implementation is provided. Doing this causes the service to be known but unavailable.

See Also:

ServiceDirectory

Method Summary

void	activateService(Class serviceClassName) This is an administrative request to the service implementation to come 'online'.
boolean	bindImplementation(Class className, ManagedService impl) Here, we store the given impl for this service interface.
void	deactivateService(Class serviceClassName) This will be an administrative request to the service to deactiveate its implementation (i.e.'offline').
Set<Class>	getAllServices() This is an easy way to acquire the list of known services, including both Entry Points and Service Points.
Object	getProviderImplementation(VersionedProviderImplementationName versionedProviderImplementationName) This method will allow external threads to build their own compound versionedProviderImplementationName that identifies a versioned implementation class and get a reference to that impl class.
ManagedService	getUnvalidatedService(Class clazz) Like a 'staff only' doorway in a business, this is a "special case" accessor for a Managed Service in that it only throws an exception if the service is unknown.
boolean	isBoundImplementation(ManagedService managedService) This method will scan the collection of held implementations to see if there's a match.
void	registerContractWithDefaultBinding(Class serviceName) This is a simplified method that allows for the registration of just the contract definition which will be backed by a non-functional default implementation.
void	reset() This method will cause the Service Directory to flush all its internal mappings and reset its state to what it was when it was first created.
void	retireContract(Class serviceName) Retiring a contract means that it is removed from the directory, including releasing the organization implementation if there was one and it is not servicing any other contracts.
void	unbindServiceImplementation(Class serviceName) Unbinding an implementation will set the given service to the default placeholder.

Method Detail

registerContractWithDefaultBinding

void registerContractWithDefaultBinding(Class serviceName)

This is a simplified method that allows for the registration of just the contract definition which will be backed by a non-functional default implementation.

Parameters:

serviceName - This is the name of the fq class name to register as a software contract.

retireContract

void retireContract(Class serviceName)

Retiring a contract means that it is removed from the directory, including releasing the organization implementation if there was one and it is not servicing any other contracts. Note that doing this will cause all clients to begin throwing UnknownServiceExceptions.

Parameters:

serviceName - This is the fq class name of the contract to be removed from the directory.

isBoundImplementation

boolean isBoundImplementation(ManagedService managedService)

This method will scan the collection of held implementations to see if there's a match.

Parameters:

managedService - The instance being searched for.

Returns:

Returns true or false depending on whether the instance has been found.

bindImplementation

boolean bindImplementation(Class className,
                           ManagedService impl)
                           throws ServiceBindingException

Here, we store the given impl for this service interface. At some point this could optionally become a pool or a list of impl objects that all implement the same interface and managers or selectors will decide which get used.

Note that this method supports registration of unbound service contracts by accepting a null value for the implementation and a placeholder will be supplied internally.

Parameters:

className - This is the class for the interface that defines the service contract.

impl - This is the implementation instance for this interface which must extend the Adapter or

Returns:

returns false if there was a problem completing the task.

Throws:

ServiceBindingException - Thrown if there is a problem with the assignment.

unbindServiceImplementation

void unbindServiceImplementation(Class serviceName)

Unbinding an implementation will set the given service to the default placeholder. A check is then made to see if this implementation is providing processing logic for any other service points and if it is found to no longer be used, it is removed from the collection of known service implementations as well.

Parameters:

serviceName - The service class for the service point for which we wish to remove the impl.

activateService

void activateService(Class serviceClassName)

This is an administrative request to the service implementation to come 'online'. There is no guarantee that this will happen, it's just a request.

Parameters:

serviceClassName - The contract that the impl was supposed to be supporting.

deactivateService

void deactivateService(Class serviceClassName)

This will be an administrative request to the service to deactiveate its implementation (i.e.'offline'). There is no guarantee that this will happen but it should be extremely rare for this not to succeed.

Parameters:

serviceClassName - This is the contract key class that points to the organization implementation to be deactivated.

getProviderImplementation

Object getProviderImplementation(VersionedProviderImplementationName versionedProviderImplementationName)
                                 throws UnknownImplementationException

This method will allow external threads to build their own compound versionedProviderImplementationName that identifies a versioned implementation class and get a reference to that impl class. This is useful if you want to register an existing instance to service an additional contract. This would happen in cases where an implementation supports multiple contracts and may already be in service for one or more of them. The implication in this is that there may be additional code paths that are not being used in the instance until invocations on another contract start coming in.

Parameters:

versionedProviderImplementationName - This is the key that will be used to indentify and acquire the impl object.

Returns:

Returns the object of the given class, of the given version if it exists.

Throws:

UnknownImplementationException - Thrown if the key doesn't match any known implementation.

getUnvalidatedService

ManagedService getUnvalidatedService(Class clazz)
                                     throws UnknownServiceException

Like a 'staff only' doorway in a business, this is a "special case" accessor for a Managed Service in that it only throws an exception if the service is unknown. It will deliver a service even if the implementation reports that the service state is UNAVAILABLE. This is important for certain activities such as dependency injection of service proxies while the service is not yet available to service requests. If not already apparent, this method should be used with care and understanding since the object you get may not even be functional.

Parameters:

clazz - The class of the service you wish to acquire the implementation object for.

Returns:

Returns an object that implements the ManagedService interface in an unknown state of readiness.

Throws:

UnknownServiceException - Thrown if the service is not registered.

getAllServices

Set<Class> getAllServices()

This is an easy way to acquire the list of known services, including both Entry Points and Service Points.

Returns:

Returns a list of known services contracts.

reset

void reset()

This method will cause the Service Directory to flush all its internal mappings and reset its state to what it was when it was first created.