com.codemonster.surinam.controller
Interface Action

All Known Implementing Classes:

AbstractContractOperationAction, AbstractOperationAction, BindImplementationAction, RegisterContractAction, RegisterEntryPointAction, RetireContractAction, UnbindContractAction

public interface Action

This is the common interface for all supported 'Actions.' Actions are object representations of operations that make up an Action Document. These operations will fall into different categories as subclasses, refer to them for more details.

Method Summary

void	apply(ServiceBlock serviceBlock) This is the primary execution point for all ServiceBlock actions.
String	getName() We want to be able to discern which operation is being performed by subclasses of this object.
Iterator<ServiceToFieldInjectionPair>	getRequiredServices() Get a list of fully qualified Contracts that this action requires.
void	injectServices(ServiceBlock serviceBlock) This callback method is used to inject the ServiceBlock that the action will have access to in order to perform its work.

Method Detail

getName

String getName()

We want to be able to discern which operation is being performed by subclasses of this object.

Returns:

Returns the name of the action being performed.

getRequiredServices

Iterator<ServiceToFieldInjectionPair> getRequiredServices()

Get a list of fully qualified Contracts that this action requires. Contract actions will normally be empty but implementations could have a quite a few.

Returns:

Returns a list of services, upon which, this service depends.

apply

void apply(ServiceBlock serviceBlock)
           throws MalformedURLException,
                  ClassNotFoundException,
                  IllegalAccessException,
                  MissingAnnotationException,
                  UnknownServiceException,
                  MissingInterfaceException,
                  DependencyInjectionException,
                  InstantiationException,
                  BindingDeclarationError

This is the primary execution point for all ServiceBlock actions. Not all operations will throw all of these exceptions but we wanted a unified interface for these actions to allow the code to handle a broad ranged of actions and still be able to respond in a fine-grained manner.

Note that if you aren't interested in fine-grained exceptions, all Surinam exceptions extend SurinamException, so you could just trap that along with the Java exceptions separately. Or catching Exception should do the trick.

Parameters:

serviceBlock - The ServiceBlock that the actions will be given access to.

Throws:

MalformedURLException - Thrown if one of the classpath segments are malformed.

ClassNotFoundException - Thrown if the FQ class cannot be found on the classpath.

IllegalAccessException - If you do not have access or permission to execute this method.

MissingAnnotationException - The class is missing a required annotation.

UnknownServiceException - The Service Contract is unknown to the system.

MissingInterfaceException - A required interface has not been extended.

DependencyInjectionException - Attempts to inject resources as requested has failed.

InstantiationException - The Service Block is not able to instantiate an instance of this class.

BindingDeclarationError - Thrown if there is a binding failure.

injectServices

void injectServices(ServiceBlock serviceBlock)
                    throws ClassNotFoundException,
                           DependencyInjectionException,
                           IllegalAccessException

This callback method is used to inject the ServiceBlock that the action will have access to in order to perform its work. Needless to say, Actions can be supremely powerful and therefore need to be trusted entities. This callback will probably be a NOP for all actions except implementations.

Parameters:

serviceBlock - The ServiceBlock that the actions will be given access to.

Throws:

DependencyInjectionException - Thrown if injection fails.

ClassNotFoundException - Thrown if the class cannot be found; usually a classpath or packaging issue.

IllegalAccessException - Thrown if there is a loader or hierarchy failure.