com.codemonster.surinam.export.framework
Interface ServiceBlockAdmin

All Known Implementing Classes:

ServiceBlockImpl

public interface ServiceBlockAdmin

This is the powerful administrative API, through which, direct manipulation of the Service Block can be achieved. One of the primary parameters are Blueprint objects which are part of the logical Surinam "Blueprint Model". Blueprints are held by the BlueprintManager, which is part of the ServiceBlock and holds the meta information used to 'weave' the Service Graph and bring services online at runtime. The blueprint model and is useful for handling the relatively lightweight nature of most model-related queries, the ServiceBlock Model also wraps the local Service Directory where all the instance references and mappings to actual implementations are maintained.

Note that as of version 2.0, when manipulating the block programmatically, you will need to cause the proxies to update their references when you are finished moving things around.

Method Summary

void	bindProviderImplementation(ImplementationBlueprint blueprint) This will create, register and assign a new organization implementation to the given contract.
ReentrantReadWriteLock	getActionLock() This is for when we need to lock down all activities on a block while an update that contains multiple steps that need to be atomic.
BlueprintManager	getBlueprintMgr()
Class	getContractClass(String contractClassName) This is shared with the ServiceBlock since it is used internally by the Blueprint Manager.
ServiceDirectory	getServiceDirectory() This accessor delivers the block's internal ServiceDirectory implementation.
ServiceDirectoryAdmin	getServiceDirectoryAdmin() Simple accessor for times when we need access to the ServiceDirectory's administrative interface.
GreedyClassLoader	getServiceLoader() In order to generate the proxies, we need access to the class loader.
void	injectRequiredServices(ImplementationBlueprint blueprint)
void	invalidateReferences() This method is to be called at the end of Graph Reshaping event.
void	registerContract(ContractBlueprint svcContract) This will register a new contract for use in the application.
void	registerEntryPoint(EntryPointBlueprint entryPoint) An entry point is just like a normal service except that the contract class is expected to be taken from the parent loader and not locally.
void	reset() This method will cause the Service Block to flush all its internal structures and reset its state to what it was when it was first created.
void	retireEntryPoint(String entryPointName) This will strike the contract from the Service Directory, clients will begin to receive UnknownServiceExceptions and this action will also free the organization implementation that was servicing the contract if there was one.
void	retireServiceContract(String contractName) This will remove the contract from the Service Directory, clients will begin to receive UnknownServiceExceptions and this action will also free the implementation that was servicing the contract if there is one.
void	setBlueprintMgr(BlueprintManager blueprintMgr) Normally this is not used.
void	synchronizeBindings() This administrative process causes the BlueprintManager to clear out its implementation bindings and rebuild them all so that the BPM and the Service Directory are in synch with each other.
void	unbindServiceImplementation(String contractName) This will unbind the Provider Implementation from the given Service Contract, clients will begin to receive ServiceUnavailableExceptions as the Contract will be assigned the default implementation.

Method Detail

synchronizeBindings

void synchronizeBindings()
                         throws ClassNotFoundException

This administrative process causes the BlueprintManager to clear out its implementation bindings and rebuild them all so that the BPM and the Service Directory are in synch with each other.

Throws:

ClassNotFoundException - thrown of there is a problem with the synchronization, which involves some class lookup activities. If this should happen, it is very bad.

getContractClass

Class getContractClass(String contractClassName)
                       throws ClassNotFoundException

This is shared with the ServiceBlock since it is used internally by the Blueprint Manager.

Parameters:

contractClassName - the FQ name of the contract class.

Returns:

returns the Class instance that the ServiceDirectory is using in the Service Block.

Throws:

ClassNotFoundException - thrown if the class canno be found.

getServiceDirectory

ServiceDirectory getServiceDirectory()

This accessor delivers the block's internal ServiceDirectory implementation.

Returns:

Returns an object that implements the ServiceDirectory interface that is being used by the ServiceBlock.

getServiceDirectoryAdmin

ServiceDirectoryAdmin getServiceDirectoryAdmin()

Simple accessor for times when we need access to the ServiceDirectory's administrative interface.

Returns:

Returns the service directory object that implements the administrative interface.

getServiceLoader

GreedyClassLoader getServiceLoader()

In order to generate the proxies, we need access to the class loader.

Returns:

Returns our instance of a GreedyClassLoader which is our top-level loader for loading Service Contracts. This is not the class loader used for loading service implementations as each implementation will have its own dedicated loader for that.

getBlueprintMgr

BlueprintManager getBlueprintMgr()

Returns:

returns the ServiceBlock's Blueprint Manager.

setBlueprintMgr

void setBlueprintMgr(BlueprintManager blueprintMgr)

Normally this is not used.

Parameters:

blueprintMgr - sets the ServiceBlock's Blueprint Manager.

registerContract

void registerContract(ContractBlueprint svcContract)
                      throws MalformedURLException,
                             ClassNotFoundException

This will register a new contract for use in the application.

Parameters:

svcContract - This is a blueprint for a service contract.

Throws:

MalformedURLException - This will include classpath definitions which may be malformed.

ClassNotFoundException - The specified class may not be found.

registerEntryPoint

void registerEntryPoint(EntryPointBlueprint entryPoint)
                        throws MalformedURLException,
                               ClassNotFoundException

An entry point is just like a normal service except that the contract class is expected to be taken from the parent loader and not locally. This is to ensure that the Service Block Entry Point is callable externally. Normally, this would simply mean that the Contract's interface is a well-known interface (like HttpServlet or Runnable) or that you have a fixed interface defined in the wrapping application.

Parameters:

entryPoint - This is a blueprint that specifies the details of this entry point.

Throws:

MalformedURLException - This will include classpath definitions which may be malformed.

ClassNotFoundException - The specified class may not be found.

bindProviderImplementation

void bindProviderImplementation(ImplementationBlueprint blueprint)
                                throws ClassNotFoundException,
                                       MissingInterfaceException,
                                       InstantiationException,
                                       UnknownServiceException,
                                       MissingAnnotationException,
                                       IllegalAccessException,
                                       DependencyInjectionException,
                                       BindingDeclarationError

This will create, register and assign a new organization implementation to the given contract. If the impl already exists, that one will be used. We handle instantiation internally since the requesting thread may live in a different classloader and managing this hierarchy is the responsibility of the framework.

Parameters:

blueprint - This is the meta object that provides the spec for building the implementation.

Throws:

ClassNotFoundException - Thrown if the class specified in the blueprint cannot be found.

MissingInterfaceException - Thrown if the implementation does not implement the required interfaces.

InstantiationException - Thrown if there is a failure creating the organization implementation.

UnknownServiceException - Thrown if the given contract class is not registered.

MissingAnnotationException - Thrown if the organization implementation does not have the required annotations.

IllegalAccessException - An attempt will be made to instantiate a new instance of the specified implementation, this could fail.

DependencyInjectionException - The framework will try to inject any services that it depends on. If any of those services are unavailable, injection will not be attempted. If the service is available but the attempt to inject via the specified method should fail the exception is also thrown.

BindingDeclarationError - Thrown when the binding declaration is broken.

injectRequiredServices

void injectRequiredServices(ImplementationBlueprint blueprint)
                            throws ClassNotFoundException,
                                   DependencyInjectionException,
                                   IllegalAccessException

Parameters:

blueprint - This is the service Blueprint that contains meta-information on injected services.

Throws:

ClassNotFoundException - Thrown if the class specified in the blueprint cannot be found.

DependencyInjectionException - The framework will try to inject any services that it depends on. If any of those services are unavailable, injection will not be attempted. If the service is available but the attempt to inject via the specified method should fail the exception is also thrown.

IllegalAccessException - An attempt will be made to instantiate a new instance of the specified

retireEntryPoint

void retireEntryPoint(String entryPointName)

This will strike the contract from the Service Directory, clients will begin to receive UnknownServiceExceptions and this action will also free the organization implementation that was servicing the contract if there was one. Note that this will also free up these objects for garbage collection.

Parameters:

entryPointName - This is the name of the EntryPoint to be retired.

retireServiceContract

void retireServiceContract(String contractName)

This will remove the contract from the Service Directory, clients will begin to receive UnknownServiceExceptions and this action will also free the implementation that was servicing the contract if there is one. Note that this may also free up these objects for garbage collection.

Parameters:

contractName - This is the Contract name to be retired.

unbindServiceImplementation

void unbindServiceImplementation(String contractName)

This will unbind the Provider Implementation from the given Service Contract, clients will begin to receive ServiceUnavailableExceptions as the Contract will be assigned the default implementation. Note that this may also free up these objects for garbage collection.

Parameters:

contractName - This is the Contract name whose current implementation is to be unbound.

reset

void reset()

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

getActionLock

ReentrantReadWriteLock getActionLock()

This is for when we need to lock down all activities on a block while an update that contains multiple steps that need to be atomic. The expectation is that this would be important for anyone writing Service Block management wrappers similar to the ServiceBlockCommander. Note that due to the lock having its own management methods, there's no reason for a method to release the lock.

Returns:

Returns the lock that is required for batch processing with the Service Block.

invalidateReferences

void invalidateReferences()

This method is to be called at the end of Graph Reshaping event. Since there is no way to know when calling code is finished making changes, the onus is on the caller to say when it is done so that the proxies can be notified accordingly (they will want to refresh their references).