com.codemonster.surinam.mgmt.impl
Class ServiceBlockImpl

java.lang.Object
  com.codemonster.surinam.mgmt.impl.ServiceBlockImpl

All Implemented Interfaces:

ServiceBlock, ServiceBlockAdmin

public class ServiceBlockImpl
extends Object
implements ServiceBlock, ServiceBlockAdmin

This is the implementation of the service block. It represents one of the most visible objects in the Surinam framework... the ServiceBlock.

Constructor Summary

ServiceBlockImpl(ClassLoader parentLoader)
A convenience constructor that initializes with an empty class path.

ServiceBlockImpl(ClassLoader parentLoader, URL[] classpath)
We start out by allocating the application's class loader and makes it a child of the given loader.

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 className) This method will return a reference to the Class object that has been loaded from within the service block context.
ServiceDirectory	getServiceDirectory() For those times when a client might want to query the directory for more than simply asking for implementations, we allow clients to hold references to the service directory.
ServiceDirectoryAdmin	getServiceDirectoryAdmin() Simple accessor for times when we need access to the ServiceDirectory's administrative interface.
ServiceFinder	getServiceFinder() If you have a Service Block, you can acquire the Finder.
GreedyClassLoader	getServiceLoader() In order to generate the proxies, we need access to the class loader.
ManagedService	getStaticService(Class className) Takes a contract class object and returns the associated service object.
ManagedService	getStaticService(String className) Takes a fully-qualified string name of the contract class and returns the associated service object.
void	injectRequiredServices(ImplementationBlueprint blueprint)
void	invalidateReferences() This method is to be called at the end of Graph Reshaping event.
boolean	isRegisteredContract(String contractName) Simple query to see if a contract is registered or not.
void	registerContract(ContractBlueprint contractBlueprint) 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 contractName) 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	setServiceDirectory(ServiceDirectory svcDirectory) standard setter.
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 serviceName) 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.

Methods inherited from class java.lang.Object

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

Constructor Detail

ServiceBlockImpl

public ServiceBlockImpl(ClassLoader parentLoader)

A convenience constructor that initializes with an empty class path.

Parameters:

parentLoader - The class loader of the parent process/context.

ServiceBlockImpl

public ServiceBlockImpl(ClassLoader parentLoader,
                        URL[] classpath)

We start out by allocating the application's class loader and makes it a child of the given loader. We also create the ServiceDirectory object and keep a cast reference to it for the admin interface.

Parameters:

parentLoader - The class loader of the parent process/context.

classpath - This is an array of URL objects that point to jar files to be included in this block's classpath.

Method Detail

synchronizeBindings

public final 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.

Specified by:

synchronizeBindings in interface ServiceBlockAdmin

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.

setServiceDirectory

public final void setServiceDirectory(ServiceDirectory svcDirectory)

standard setter.

Parameters:

svcDirectory - Service Directory instance.

getServiceFinder

public final ServiceFinder getServiceFinder()

If you have a Service Block, you can acquire the Finder.

Specified by:

getServiceFinder in interface ServiceBlock

Returns:

Returns a ServiceFinder instance that is tied to this block.

getServiceDirectory

public final ServiceDirectory getServiceDirectory()

For those times when a client might want to query the directory for more than simply asking for implementations, we allow clients to hold references to the service directory.

Specified by:

getServiceDirectory in interface ServiceBlockAdmin

Returns:

The application's ServiceDirectory instance.

getServiceDirectoryAdmin

public final ServiceDirectoryAdmin getServiceDirectoryAdmin()

Description copied from interface: ServiceBlockAdmin

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

Specified by:

getServiceDirectoryAdmin in interface ServiceBlockAdmin

Returns:

Returns the admin interface for the Service Directory.

isRegisteredContract

public final boolean isRegisteredContract(String contractName)

Description copied from interface: ServiceBlock

Simple query to see if a contract is registered or not. This is essentially the same method as is found on the Service Directory.

Specified by:

isRegisteredContract in interface ServiceBlock

Parameters:

contractName - String name of the Contract being queried.

Returns:

Returns whether or not the given Contract is registered with the Service Directory.

getContractClass

public final Class getContractClass(String className)

Description copied from interface: ServiceBlock

This method will return a reference to the Class object that has been loaded from within the service block context. This is important because identical classes are discriminated by the class loader information. When using an API that requires a class object to be passed in to the Service Block as a match key, they will not be equal if they are from different class loaders.

Specified by:

getContractClass in interface ServiceBlock

Specified by:

getContractClass in interface ServiceBlockAdmin

Parameters:

className - String name of the Contract Class being queried.

Returns:

Returns the Contract Class that is known to the Service Block.

Throws:

UnknownServiceException

getStaticService

public final ManagedService getStaticService(Class className)

Takes a contract class object and returns the associated service object. 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 ServiceBlock

Parameters:

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

Returns:

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

getStaticService

public final ManagedService getStaticService(String className)
                                      throws 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 ServiceBlock

Parameters:

className - fq name of the service contract.

Returns:

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

Throws:

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

getServiceLoader

public final GreedyClassLoader getServiceLoader()

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

Specified by:

getServiceLoader in interface ServiceBlockAdmin

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

public final BlueprintManager getBlueprintMgr()

Specified by:

getBlueprintMgr in interface ServiceBlockAdmin

Returns:

returns the ServiceBlock's Blueprint Manager.

setBlueprintMgr

public void setBlueprintMgr(BlueprintManager blueprintMgr)

Normally this is not used.

Specified by:

setBlueprintMgr in interface ServiceBlockAdmin

Parameters:

blueprintMgr - sets the ServiceBlock's Blueprint Manager.

registerContract

public void registerContract(ContractBlueprint contractBlueprint)
                      throws MalformedURLException,
                             ClassNotFoundException

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

Specified by:

registerContract in interface ServiceBlockAdmin

Parameters:

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

public final 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.

Specified by:

registerEntryPoint in interface ServiceBlockAdmin

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.

unbindServiceImplementation

public final void unbindServiceImplementation(String serviceName)

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.

Specified by:

unbindServiceImplementation in interface ServiceBlockAdmin

Parameters:

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

bindProviderImplementation

public final void bindProviderImplementation(ImplementationBlueprint blueprint)
                                      throws ClassNotFoundException,
                                             MissingInterfaceException,
                                             InstantiationException,
                                             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.

Specified by:

bindProviderImplementation in interface ServiceBlockAdmin

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.

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

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

Specified by:

injectRequiredServices in interface ServiceBlockAdmin

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

UnknownServiceException

retireEntryPoint

public void retireEntryPoint(String contractName)

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.

Specified by:

retireEntryPoint in interface ServiceBlockAdmin

Parameters:

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

retireServiceContract

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

Specified by:

retireServiceContract in interface ServiceBlockAdmin

Parameters:

contractName - This is the Contract name to be retired.

reset

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

Specified by:

reset in interface ServiceBlockAdmin

getActionLock

public ReentrantReadWriteLock getActionLock()

Description copied from interface: ServiceBlockAdmin

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.

Specified by:

getActionLock in interface ServiceBlockAdmin

Returns:

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

invalidateReferences

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

Specified by:

invalidateReferences in interface ServiceBlockAdmin