com.prosyst.mprm.admin.operations

Interface OperationManager

public interface OperationManager

Represents the main service for administering operations in mPRM.

Method Summary

Modifier and Type	Method and Description
void	addCommandResultListener(CommandResultListener commandResultListener, java.lang.String[] commandTypes) Adds a listener that shall receive command return results.
void	addOperationListener(OperationListener listener) Adds operation listener, which will be notified when an operation event occurs.
void	addOperationListener(OperationListener listener, boolean listenForHiddenOperations) Adds operation listener, which will be notified when an operation event occurs.
Operation	createOperation(java.lang.String operationName, Command command, java.lang.String contextPath) Creates an Operation object initialized by argument values.
Operation	createOperation(java.lang.String operationName, java.lang.String procedureText, java.lang.String contextPath) Creates an Operation object initialized by argument values.
OperationFilter	createOperationFilter(java.lang.String operationFilter) Creates an OperationFilter object for filtered listing of operations.
void	executeOperation(java.lang.String contextPath, Command command, boolean persistent) Executes the supplied management command(s) over a given sub-group of devices.
void	executeOperation(java.lang.String contextPath, Command command, boolean persistent, CommandResultListener commandResultListener) Executes the supplied management command(s) over a given sub-group of devices.
void	executeOperation(java.lang.String operationName, java.lang.String contextPath, Command command, boolean persistent, CommandResultListener commandResultListener) Executes the supplied management command(s) over a given sub-group of devices.
void	executeOperationSync(java.lang.String deviceType, java.lang.String deviceId, Command command, CommandResultListener commandResultListener) Executes a command over a given device synchronously.
Operation	getOperation(java.lang.String operationId) Returns an Operation object identified by the value of the passed argument.
PendingCommand[]	getPendingCommands(java.lang.String deviceType, java.lang.String deviceId) Returns the list of the management commands, pending for execution for the device specified by the arguments pair deviceType, deviceId.
PendingCommand[]	getPendingCommands(java.lang.String deviceType, java.lang.String deviceId, java.lang.String operationId) Returns the list of the management commands for given device within a given operation.
java.lang.String[]	getPendingOperationIds(java.lang.String deviceType, java.lang.String deviceId) Returns the list of the management operations, pending for execution for that device.
<any>	listFinishedOperations(java.lang.String deviceType, java.lang.String deviceId)
Enumerator	listOperations() Returns an enumerator of Operation objects for all management operations currently tracked by the mPRM.
boolean	match(ControlUnitID controlUnitId, java.lang.String controlUnitFilter) Checks if control unit matches a filter.
boolean	matchStateVariables(java.util.Dictionary stateVariables, java.lang.String filter) Checks if a set of state variables matches a control unit filter.
void	removeCommandResultListener(CommandResultListener commandResultListener) Removes a command return results listener.
void	removeOperationListener(OperationListener listener) Removes operation listener.
void	removePendingCommand(java.lang.String deviceType, java.lang.String deviceId, java.lang.String commandId) Removes pending command for given device.
void	removePendingOperation(java.lang.String deviceType, java.lang.String deviceId, java.lang.String operationId) Removes pending operation for given device.

Method Detail

listOperations

Enumerator listOperations()
                   throws ManagementException

Returns an enumerator of Operation objects for all management operations currently tracked by the mPRM. If no operations are tracked by the mPRM, null is returned.

Returns:

an Enumerator of Operation objects.

Throws:

ManagementException - if a system error occurs.

createOperationFilter

OperationFilter createOperationFilter(java.lang.String operationFilter)
                               throws ManagementException

Creates an OperationFilter object for filtered listing of operations. Once created the object could be used multiple times for retrieving operations satisfying its criteria.

Parameters:

operationFilter - filter criteria given in the form of mPRM management script.

Returns:

OperationFilter.

Throws:

ManagementException - if a system error occurs.

getOperation

Operation getOperation(java.lang.String operationId)
                throws ManagementException

Returns an Operation object identified by the value of the passed argument. If there is no such management operation null is returned.

Parameters:

operationId - identifier of the operation.

Returns:

Operation object representing management operation.

Throws:

ManagementException - if a system error occurs.

createOperation

Operation createOperation(java.lang.String operationName,
                          java.lang.String procedureText,
                          java.lang.String contextPath)
                   throws ManagementException

Creates an Operation object initialized by argument values. This method does not execute the operation. It just creates a reference object that can be started scheduled for future execution or accept specific operations settings before the actual trigger.

Parameters:

operationName - display name of the operation. This argument is optional.

procedureText - operation commands given as management script procedure. This argument can be null if the operation will be defined by adding Command objects.

contextPath - specifies target device or group of devices where the operation command generated by the procedure text will be executed. null means that all devices will execute the operation.

Throws:

ManagementException - if a system error occurs.

createOperation

Operation createOperation(java.lang.String operationName,
                          Command command,
                          java.lang.String contextPath)
                   throws ManagementException

Creates an Operation object initialized by argument values. This method does not execute the operation. It just creates a reference object that can be started scheduled for future execution or accept specific operations settings before the actual trigger.

Parameters:

operationName - display name of the operation. This argument is optional.

command - operation command(s).

contextPath - specifies target device or group of devices where the operation command will be executed. null means that all devices will execute the operation.

Throws:

ManagementException - if a system error occurs.

addOperationListener

void addOperationListener(OperationListener listener)
                   throws ManagementException

Adds operation listener, which will be notified when an operation event occurs.

Parameters:

listener - application defined operation listener.

Throws:

ManagementException - if a system error occurs.

addOperationListener

void addOperationListener(OperationListener listener,
                          boolean listenForHiddenOperations)
                   throws ManagementException

Adds operation listener, which will be notified when an operation event occurs.

Parameters:

listener - application defined operation listener.

listenForHiddenOperations - flag indicating whether the listener should receive events for hidden operations as well.

Throws:

ManagementException - if a system error occurs.

removeOperationListener

void removeOperationListener(OperationListener listener)

Removes operation listener.

Parameters:

listener - application defined operation listener.

executeOperation

void executeOperation(java.lang.String contextPath,
                      Command command,
                      boolean persistent)
               throws ManagementException

Executes the supplied management command(s) over a given sub-group of devices. The devices can be additionally filtered supplying ConditionalCommand as a command argument. This method has similar semantics as createOperation("name", command, contextPath).start() but the operation is not accessible as an Operation object and therefore it cannot be listed and managed as operations created through the createOperation(String, com.prosyst.mprm.commands.Command, String) method. In addition the persistent argument determines whether the command should be enqueued for later execution if the device is not currently connected. The Operations created with createOperation(String, com.prosyst.mprm.commands.Command, String) are always 'persistent'.

Parameters:

contextPath - specifies target device or group of devices which will execute the operation. Supplying null is equivalent with the root of the group hierarchy.

command - operation command(s).

persistent - if true the command will be enqueued for those devices which are not online. If false and operation cannot not be executed immediately the execution will finish with error.

Throws:

ManagementException - if a system error occurs.

executeOperation

void executeOperation(java.lang.String contextPath,
                      Command command,
                      boolean persistent,
                      CommandResultListener commandResultListener)
               throws ManagementException

Executes the supplied management command(s) over a given sub-group of devices. The devices can be additionally filtered supplying ConditionalCommand as a command argument. This method has similar semantics as createOperation(name, command, contextPath).start() but the operation is not accessible as an Operation object and therefore it cannot be listed and managed as operations created through the createOperation(String, com.prosyst.mprm.commands.Command, String) method. In addition the persistent argument determines whether the command should be enqueued for later execution if the device is not currently connected. The Operations created with createOperation(String, com.prosyst.mprm.commands.Command, String) are always persistent.

Parameters:

contextPath - specifies target device or group of devices which will execute the operation. Supplying null is equivalent with the root of the group hierarchy.

command - operation command(s).

persistent - if true the command will be enqueued for those devices which are not online. If false and operation cannot not be executed immediately the execution will finish with error.

commandResultListener - listener that shall receive command return results within this operation. This listener is automatically deactivated when the operation execution completes, but it can be explicitly deactivated through the Control.removeCommandResultListener method. However, it is always better the command result listener to be removed, when all expected results are received.

Throws:

ManagementException - if a system error occurs.

executeOperation

void executeOperation(java.lang.String operationName,
                      java.lang.String contextPath,
                      Command command,
                      boolean persistent,
                      CommandResultListener commandResultListener)
               throws ManagementException

Executes the supplied management command(s) over a given sub-group of devices. The devices can be additionally filtered supplying ConditionalCommand as a command argument. This method has similar semantics as createOperation(name, command, contextPath).start() but the operation is not accessible as an Operation object and therefore it cannot be listed and managed as operations created through the createOperation(String, com.prosyst.mprm.commands.Command, String) method. In addition the persistent argument determines whether the command should be enqueued for later execution if the device is not currently connected. The Operations created with createOperation(String, com.prosyst.mprm.commands.Command, String) are always persistent.

Parameters:

operationName - display name of the operation. This argument is optional. Supplying null is equivalent with the root of the group hierarchy.

contextPath - specifies target device or group of devices which will execute the opreation. Supplying null is equivalent with the root of the group hierarchy.

command - operation command(s).

persistent - if true the command will be enqueued for those devices which are not online. If false and operation cannot not be executed immediately the execution will finish with error.

commandResultListener - listener that shall receive command return results within this operation. This listener is automatically deactivated when the operation execution completes, but it can be explicitly deactivated through the Control.removeCommandResultListener method. However, it is always better the command result listener to be removed, when all expected results are received.

Throws:

ManagementException - if a system error occurs.

addCommandResultListener

void addCommandResultListener(CommandResultListener commandResultListener,
                              java.lang.String[] commandTypes)
                       throws ManagementException

Adds a listener that shall receive command return results.

Parameters:

commandResultListener - the listener object.

commandTypes - denotes types of commands this listener is interested in.

Throws:

ManagementException - if an error occurs.

removeCommandResultListener

void removeCommandResultListener(CommandResultListener commandResultListener)

Removes a command return results listener.

Parameters:

commandResultListener - the listener object to be deactivated.

getPendingOperationIds

java.lang.String[] getPendingOperationIds(java.lang.String deviceType,
                                          java.lang.String deviceId)
                                   throws ManagementException

Returns the list of the management operations, pending for execution for that device. getPendingCommands(String, String, String) method could be used for obtaining the actual pending commands within a concrete operation.

Returns:

an array of operation identifiers, being executed from a device or an empty array if no operations, being executed are listed.

Throws:

ManagementException - if system error occurs.

getPendingCommands

PendingCommand[] getPendingCommands(java.lang.String deviceType,
                                    java.lang.String deviceId,
                                    java.lang.String operationId)
                             throws ManagementException

Returns the list of the management commands for given device within a given operation. The returned commands are within the operation specified by operationId, and are pending for execution by the device specified by the arguments pair deviceType, deviceId.

Parameters:

deviceType - device type.

deviceId - device id.

operationId - specifies the operation, that retrieved pending commands should be executed within. Specifying a null value for that parameter returns all pending commands for the specified device.

Returns:

an array of the pending commands or an empty array if no commands are pending for that device.

Throws:

ManagementException - if a system error occurs.

getPendingCommands

PendingCommand[] getPendingCommands(java.lang.String deviceType,
                                    java.lang.String deviceId)
                             throws ManagementException

Returns the list of the management commands, pending for execution for the device specified by the arguments pair deviceType, deviceId.

Parameters:

deviceType - device type.

deviceId - device id.

Returns:

an array of the pending commands or an empty array if no commands are pending for that device.

Throws:

ManagementException - if a system error occurs.

removePendingOperation

void removePendingOperation(java.lang.String deviceType,
                            java.lang.String deviceId,
                            java.lang.String operationId)
                     throws ManagementException

Removes pending operation for given device.

Parameters:

deviceType - device type of the device for which the pending operation to be removed.

deviceId - device id of the device for which the pending operation to be removed.

operationId - id of the operation to be removed.

Throws:

ManagementException - if system error occurs.

removePendingCommand

void removePendingCommand(java.lang.String deviceType,
                          java.lang.String deviceId,
                          java.lang.String commandId)
                   throws ManagementException

Removes pending command for given device.

Parameters:

deviceType - device type of the device for which the pending command to be removed.

deviceId - device id of the device for which the pending command to be removed.

commandId - id of the command to be removed.

Throws:

ManagementException - if system error occurs.

executeOperationSync

void executeOperationSync(java.lang.String deviceType,
                          java.lang.String deviceId,
                          Command command,
                          CommandResultListener commandResultListener)
                   throws ManagementException

Executes a command over a given device synchronously.

Parameters:

deviceType - device type.

deviceId - device id.

command - Command object defining the command to be executed.

commandResultListener - listener that should receive results within this execution. As this method executes operation synchronously, the supplied result listener shall receive all command return results before this method exits.

Throws:

ManagementException - if a system error occurs.

match

boolean match(ControlUnitID controlUnitId,
              java.lang.String controlUnitFilter)
       throws ManagementException

Checks if control unit matches a filter.

Parameters:

controlUnitId - id of the control unit to be matched.

controlUnitFilter - control unit filter.

Returns:

true if the control unit identified by the supplied control unit id matches the supplied filter, false otherwise.

Throws:

ManagementException - if a system error occurs.

matchStateVariables

boolean matchStateVariables(java.util.Dictionary stateVariables,
                            java.lang.String filter)
                     throws ManagementException

Checks if a set of state variables matches a control unit filter.

Parameters:

stateVariables - contains the set of state variables to be matched. The keys in the supplied Dictionary must be the state variable ids, and the dictionary values must be the respective state variable values.

filter - control unit filter.

Returns:

true if the supplied set of state variables matches the supplied control unit filter, false otherwise.

Throws:

ManagementException - if a system error occurs.

listFinishedOperations

<any> listFinishedOperations(java.lang.String deviceType,
                             java.lang.String deviceId)
                      throws ManagementException

Throws:

ManagementException