org.mbs.services.cu.spi
Interface ControlUnitFactory

All Known Implementing Classes:

DefaultControlUnitFactory

public interface ControlUnitFactory

This interface may be registered as an OSGi service in order to make more then one resources of the same type manageable through the Control Unit abstraction. The ControlUnitFactory services should not be used directly by the applications. Instead application access ControlUnitAdmin service, which delegates the requests to the appropriate ControlUnitFactory or ManagedControlUnit service. ControlUnitFactories are suitable for representing variable number of resources with similar characteristics. An advantage is that it is not necessary to permanently hold Control Unit instance for every resource, because the corresponding wrapper may be created on demand.
ControlUnitAdmin service is responsible for tracking all ControlUnitFactory services registered in the service registry of the framework.
One ControlUnitFactory may be responsible for providing ControlUnit instances of exacly one type. It is not allowed to have more then one factory for the same type and it is not allowed to have both ControlUnitFactory and ManagedControlUnit services for the same ControlUnit type. To be properly handled by the Control Unit Admin the ControlUnitFactory service must be registered with property ControlConstants.TYPE with value of type String specifying the type of the Control Unit instances exported by this factory. Optionally the registration properties may contain property ControlConstants.PARENT_TYPE with value of type String or String[] specifying the type(s) of parent control units in the control unit hierarchy. Factories wich support versioning of their control units' type should additionaly register with the property ControlConstants.VERSION with value of type String.

Method Summary

java.lang.String	createControlUnit(java.lang.String constructorID, java.lang.Object arguments) Explicitly creates control unit and returns the id of the newly created control unit.
void	destroyControlUnit(java.lang.String controlUnitID) Explicitly removes control unit instance with a given id.
java.lang.String[]	findControlUnits(java.lang.String finderID, java.lang.Object arguments) Returns ids of the control units satisfying the finder method and the supplied argument(s).
ControlUnit	getControlUnit(java.lang.String controlUnitID) Returns the ControlUnit object, identified by the given id.
java.lang.String[]	getControlUnits(java.lang.String parentControlUnitType, java.lang.String parentControlUnitID) Returns ids of the control unit instances which are children of a control unit with a given type and id.
java.lang.String[]	getParents(java.lang.String childControlUnitID, java.lang.String parentControlUnitType) Returns the ids of the parents of a given control unit specified by its id.
java.lang.Object	invokeAction(java.lang.String controlUnitID, java.lang.String actionID, java.lang.Object arguments) Executes the specified action over a control unit with specified id.
java.lang.String[]	listControlUnits() Returns the ids of all control units currently exported by this factory.
java.lang.Object	queryStateVariable(java.lang.String controlUnitID, java.lang.String stateVariableID) Queries a control unit with a specified id for the value of the specified state variable.
void	setControlUnitCallback(CUAdminCallback adminCallback) Supplies the Control Unit admin callback interface to the implementation of the ControlUnitFactory service.

Method Detail

setControlUnitCallback

void setControlUnitCallback(CUAdminCallback adminCallback)

Supplies the Control Unit admin callback interface to the implementation of the ControlUnitFactory service.
This method is invoked by the Control Unit Admin bundle with a non-null argument after registration of the ControlUnitFactory service or after startup of the Control Unit Admin for already registered factories.
It is supposed that the Control Unit Factory will assign this reference to a instance variable and use it later to notify the Control Unit Admin for creation or removal or Control Unit instances, attaching/detaching of Control Units to/from given parent and for changes in state variables.
The method is invoked with a null argument during unregistration of the ControlUnitFactory service or when the Control Unit Admin is stopped.

Parameters:

adminCallback - reference to the control unit callback interface or null if previously set reference is not longer valid.

getControlUnit

ControlUnit getControlUnit(java.lang.String controlUnitID)

Returns the ControlUnit object, identified by the given id. If there is no such control unit maintained by this factory, null is returned.

Parameters:

controlUnitID - the id of the requested control unit

Returns:

ControlUnit object with the given id.

getControlUnits

java.lang.String[] getControlUnits(java.lang.String parentControlUnitType,
                                   java.lang.String parentControlUnitID)

Returns ids of the control unit instances which are children of a control unit with a given type and id. Supplying null as arguments to this method results in returning only control units exported by this factory which have no parent.

Parameters:

parentControlUnitType - type of the parent control unit

parentControlUnitID - id of the parent control unit

Returns:

the sub-control units of the specified control unit.

listControlUnits

java.lang.String[] listControlUnits()

Returns the ids of all control units currently exported by this factory.

Returns:

control unit ids or null, if the factory exports no units

findControlUnits

java.lang.String[] findControlUnits(java.lang.String finderID,
                                    java.lang.Object arguments)
                                    throws java.lang.Exception

Returns ids of the control units satisfying the finder method and the supplied argument(s). The ControlUnitFactory may optionally define in its metadata one or more methods for filtering of control units. This methods are called finders are specified in the metadata definition for particular type of Control Units. A finder is defined as a special class of action with identifier starting with "$find.". Every finder method may have different number and/or type of arguments, specified in the metadata and implemented by the corresponding ControlUnitFactory.
If there are no control units that satisfies the finder condition the method returns null.

Parameters:

finderID - the id of the finder method. Must start with "$find.".

arguments - the finder argument(s). If the argument is only one this is the argument itself. If the arguments are more then one, the value must be a Object[] and arguments are retrieved from that array.

Returns:

the sub-control units of the specified control unit.

Throws:

java.lang.Exception - if an error occures while searching control units.

java.lang.IllegalArgumentException - if this factory does not have finder with the supplied Id or the arguments number and/or types do not match the finder arguments.

getParents

java.lang.String[] getParents(java.lang.String childControlUnitID,
                              java.lang.String parentControlUnitType)

Returns the ids of the parents of a given control unit specified by its id. This method returns only ids of the control units for a specified parent type.

Parameters:

childControlUnitID - id of the child unit

parentControlUnitType - type of the returned parent units

Returns:

ids of parent units or null, if the given control unit has no parents of the specified type

queryStateVariable

java.lang.Object queryStateVariable(java.lang.String controlUnitID,
                                    java.lang.String stateVariableID)

Queries a control unit with a specified id for the value of the specified state variable.

Parameters:

controlUnitID - the id of the control unit provided by this factory

stateVariableID - the id of the variable

Returns:

value of the variable

invokeAction

java.lang.Object invokeAction(java.lang.String controlUnitID,
                              java.lang.String actionID,
                              java.lang.Object arguments)
                              throws java.lang.Exception

Executes the specified action over a control unit with specified id.

Parameters:

controlUnitID - the id of the control unit

actionID - the id of the action

arguments - the input argument(s). If the argument is only one this is the argument itself. If the arguments are more then one, the value must be a Object[] and arguments are retrieved from that array.

Returns:

the output argument(s) or null if the action does not return value.

Throws:

java.lang.Exception - if an error occures while executing action.

java.lang.IllegalArgumentException - if this factory does not have action with the supplied Id or the arguments number and/or types do not match the action arguments.

createControlUnit

java.lang.String createControlUnit(java.lang.String constructorID,
                                   java.lang.Object arguments)
                                   throws java.lang.Exception

Explicitly creates control unit and returns the id of the newly created control unit. The ControlUnitFactory may optionally define in its metadata one or more methods for creating of new control units. These methods are called constructors and are specified in the the metadata definition for the particular type of Control Units. A constructor is defined as a special class of action with identifier starting with "$create.". Every constructor method may have different number and/or types of arguments, specified in the metadata and implemented by the corresponding ControlUnitFactory.

Parameters:

constructorID - the id of the constructors. Must start with "$create.".

arguments - - the 'constructors' argument(s). If the argument is only one this is the argument itself. If the arguments are more then one, the value must be a Object[] and arguments are retrieved from that array.

Returns:

the id of the newly created control unit.

Throws:

java.lang.Exception - if an error occures while creating Control Unit.

java.lang.IllegalArgumentException - if this factory does not have contructor with the supplied Id or the arguments number and/or types do not match the contructor arguments.

destroyControlUnit

void destroyControlUnit(java.lang.String controlUnitID)
                        throws java.lang.Exception

Explicitly removes control unit instance with a given id. Some type of control units may not support explicit removing of the resources represented by the corresponsing control units. In that case this method throws IllegalArgumentException. Support for explicit destoying of Control Units is specified in the control unit metadata by presense of an action with id "$destroy".

Parameters:

controlUnitID - control unit id.

Throws:

java.lang.Exception - if an error occures while destroying of the Control Unit.

java.lang.IllegalArgumentException - if this factory does not support explicit destroy of the control units.