org.mbs.services.cu
Interface ControlUnitAdmin

public interface ControlUnitAdmin

Represents the facade of the Control Unit Admin layer. This interface is available as a service in the OSGi registry and may be used by the applications to manage all Control Units exported in the OSGi framework. There must be exactly one such service registered in the OSGi framework.

See Also:

ControlUnit

Method Summary

java.lang.String	createControlUnit(java.lang.String controlUnitType, java.lang.String constructorID, java.lang.Object arguments) Explicitly creates control unit instance of a specified type using a supplied constructor and returns the id of the newly created control unit.
void	destroyControlUnit(java.lang.String controlUnitType, java.lang.String controlUnitID) Explicitly removes control unit instance with a given type and id.
java.lang.String[]	findControlUnits(java.lang.String controlUnitType, java.lang.String finderID, java.lang.Object arguments) Returns ids of the control units with a given type and satisfying a given finder method with the supplied argument(s).
ControlUnit	getControlUnit(java.lang.String controlUnitType, java.lang.String controlUnitID) Returns the Control Unit of a specified type and with a specified id.
java.lang.String[]	getControlUnitTypes() Returns all distinct types of control units currently exported in the framework.
java.lang.String	getControlUnitTypeVersion(java.lang.String controlUnitType) Returns the current version for given type of control units currently exported in the framework.
java.lang.String[]	getParentControlUnits(java.lang.String childControlUnitType, java.lang.String childControlUnitID, java.lang.String parentControlUnitType) Returns ids of the exported control units of givent type that are parents of a control units with a given type and id.
java.lang.String[]	getParentControlUnitTypes(java.lang.String childControlUnitType) Returns types of the exported control units that may be parents of a control units with a given type.
java.lang.String[]	getSubControlUnits(java.lang.String parentControlUnitType, java.lang.String parentControlUnitID, java.lang.String childControlUnitType) Returns ids of children of a control unit specified by a given type and id.
java.lang.String[]	getSubControlUnitTypes(java.lang.String parentControlUnitType) Returns types of the exported control units that may be children of a control units with a given type.
java.lang.Object	invokeAction(java.lang.String controlUnitType, java.lang.String controlUnitID, java.lang.String actionID, java.lang.Object arguments) Executes a given action over a control unit with a given id.
java.lang.Object	queryStateVariable(java.lang.String controlUnitType, java.lang.String controlUnitID, java.lang.String stateVariableID) Queries a control unit with a given type and id for the value of a given state variable.

Method Detail

getControlUnitTypes

java.lang.String[] getControlUnitTypes()

Returns all distinct types of control units currently exported in the framework.

Returns:

array of Control Unit types or null, if there are no Control Unit types exported in the framework.

getControlUnitTypeVersion

java.lang.String getControlUnitTypeVersion(java.lang.String controlUnitType)

Returns the current version for given type of control units currently exported in the framework.

Parameters:

controlUnitType - control unit type

Returns:

type, or null, if the give type has no version

Throws:

java.lang.IllegalArgumentException - if there is no such type of units exported in the framework

findControlUnits

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

Returns ids of the control units with a given type and satisfying a given finder method with the supplied argument(s). Supported finder methods are specific to the type of the control unit and are specified in the control unit metadata as a special class of actions with identifier starting with "$find.". Every finder method may have different number and/or type of arguments which are also specified in the metadata.
Supplying null as finderId and arguments to method returns all ids of all control units of the specified by the cuType type. Otherwise the exact searching of the Control Units is delegated to the ControlUnitFactory for this control unit type. Therefore invoking this method with non-null as finderId and arguments is not supported for finding control units exported by ManagedControlUnit services.
If there are no control units that satisfies the finder condition the method returns null.

Parameters:

controlUnitType - type of control units to find

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:

array of ControlUnit identifiers.

Throws:

java.lang.Exception - if an error occurs 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.

getControlUnit

ControlUnit getControlUnit(java.lang.String controlUnitType,
                           java.lang.String controlUnitID)

Returns the Control Unit of a specified type and with a specified id.

Parameters:

controlUnitType - the type of the Control Unit

controlUnitID - the id of the Control Unit

Returns:

ControlUnit identified by the specified (controlUnitType, controlUnitId) pair or null if there is not such control unit exported in the framework.

getSubControlUnits

java.lang.String[] getSubControlUnits(java.lang.String parentControlUnitType,
                                      java.lang.String parentControlUnitID,
                                      java.lang.String childControlUnitType)

Returns ids of children of a control unit specified by a given type and id. Method returns only control units of a specified sub-type. If parentCUType == parentCUId == null this method returns unit of the given subCUType which have no parent.

Parameters:

parentControlUnitType - the type of the parent Control Unit.

parentControlUnitID - the id of the parent Control Unit.

childControlUnitType - the type of the child Control Units.

Returns:

an array of child control units.

getParentControlUnitTypes

java.lang.String[] getParentControlUnitTypes(java.lang.String childControlUnitType)

Returns types of the exported control units that may be parents of a control units with a given type.

Parameters:

childControlUnitType - child unit type

Returns:

parent types or null if the given control unit may have no parents

getParentControlUnits

java.lang.String[] getParentControlUnits(java.lang.String childControlUnitType,
                                         java.lang.String childControlUnitID,
                                         java.lang.String parentControlUnitType)

Returns ids of the exported control units of givent type that are parents of a control units with a given type and id.

Parameters:

childControlUnitType - child unit type

childControlUnitID - child unit id

parentControlUnitType - parent units type

Returns:

parent types or null if the given control unit has no parents of the given type

createControlUnit

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

Explicitly creates control unit instance of a specified type using a supplied constructor and returns the id of the newly created control unit. Supported ways for creating a control unit are specific to the type of the control unit and are specified in the corresponding metadata definition. For every control unit type there may be defined zero, one or more constructors. A constructor is defined as a special class of action with identifier starting with "$create.". Every constructor may have different number and/or types of arguments which are also defined in the metadata.
The exact creation of the Control Unit is delegated to the ControlUnitFactory of this control unit type. Therefore this method is not supported for control units exported by ManagedControlUnit services.

Parameters:

controlUnitType - - the type of the Control Unit.

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 occurs while creating Control Unit.

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

destroyControlUnit

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

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

Parameters:

controlUnitType - - the type of the Control Unit.

controlUnitID - - controlUnitId control unit id.

Throws:

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

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

getSubControlUnitTypes

java.lang.String[] getSubControlUnitTypes(java.lang.String parentControlUnitType)

Returns types of the exported control units that may be children of a control units with a given type.

Parameters:

parentControlUnitType - parent control unit type

Returns:

array of the child control unit types.

queryStateVariable

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

Queries a control unit with a given type and id for the value of a given state variable.

Parameters:

controlUnitType - the type of the control unit

controlUnitID - the id of the control unit

stateVariableID - the id of the variable

Returns:

value of the variable

invokeAction

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

Executes a given action over a control unit with a given id.

Parameters:

controlUnitType - the type of the control unit

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 occurs while executing action.

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