com.codemonster.surinam.export.framework
Interface ServiceBlock

All Known Implementing Classes:

ServiceBlockImpl

public interface ServiceBlock

This is the primary Service Block interface designed to give some limited visibility into the general Service Block functions. This simplified interface provides all the methods necessary to work with the services, particularly if you are using Action Documents for your runtime management model. For access to the service block's deeper API, use the ServiceBlockAdmin API which will let you programmatically manage your block if you need more fine-grained controls or want to do something custom.

In this case, we are passing the current class loader as the block's parent loader and null.
Passing the current loader is standard procedure for instantiating a Service Block because
we want our entry points to be visible locally and from inside the block. Additionally, passing
the 'null' means we are not adding anything new to the class path (also SOP).

ServiceBlock serviceBlock = new ServiceBlockImpl(thisLoader, null);

Method Summary

Class	getContractClass(String contractClassName) This method will return a reference to the Class object that has been loaded from within the service block context.
ServiceFinder	getServiceFinder() Once you have a Service Block, you can acquire a Service Finder which will help acquire proper references to Entry Points (from outside the SB) and services from inside the SB (if you are writing a service).
ManagedService	getStaticService(Class contractClass) 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.
boolean	isRegisteredContract(String contractClassName) Simple query to see if a contract is registered or not.

Method Detail

isRegisteredContract

boolean isRegisteredContract(String contractClassName)

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

Parameters:

contractClassName - This is the class object for the Service Contract interface.

Returns:

Returns a boolean indicating whether this is a known Service Contract.

getServiceFinder

ServiceFinder getServiceFinder()

Once you have a Service Block, you can acquire a Service Finder which will help acquire proper references to Entry Points (from outside the SB) and services from inside the SB (if you are writing a service). Remember that finders are tied to service blocks and provide the service proxies that are required for runtime dynamics. Normally, the only services used at runtime should come from a finder object unless you want references to static services that will never change implementations.

Returns:

Returns a ServiceFinder instance that is tied to this block.

getContractClass

Class getContractClass(String contractClassName)
                       throws ClassNotFoundException

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.

Parameters:

contractClassName - This is the fqclass name of the Class object to acquire.

Returns:

Returns a Class object that the fq string name converts to in the Service Block context.

Throws:

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

getStaticService

ManagedService getStaticService(Class contractClass)
                                throws UnavailableServiceException,
                                       UnknownServiceException

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.

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 className)
                                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:

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