com.prosyst.mprm.admin.operations

Interface Operation

public interface Operation

Represents management operation tracked by mPRM. This interface defines methods for monitoring and controlling the state of the executed operation and the result of execution. Management operations can be defined in two ways - by procedure text written in management script language or by array of Command objects. Applications can define arbitrary commands and command processors which will execute them.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	STATUS_DEFINED Operation is defined but is not scheduled for execution.
static java.lang.String	STATUS_FINISHED Operation has finished its execution.
static java.lang.String	STATUS_RUNNING Operation is running.
static java.lang.String	STATUS_SCHEDULED Operation is scheduled for execution, but is not started yet.

Method Summary

Modifier and Type	Method and Description
void	addOperationListener(OperationListener listener) Registers application defined listener which will be notified for status changes in the scope of this operation.
void	cancel() Interrupts execution of the operation.
void	delete() Deletes information about this operation.
Command	getCommand() Returns a Command executed by this operation or null if the operation is defined by script text.
java.lang.String	getContextPath() Returns target device or group of devices which are affected by the management operation.
long	getDelayTolerance() Returns the delay tolerance for this operation.
int	getErrorRepliesNumber() Returns devices that have replied error while executing the operation.
Enumerator	getErrorResults() Returns list of OperationResult objects for devices that have replied errors and corresponding error messages.
java.util.Date	getFinishTime() Returns the time when the operation finished.
<any>	getInvolvedDevices() Returns involved devices identifiers
int	getInvolvedDevicesNumber() Returns the number of devices this operation is executing over.
java.lang.String	getName() Returns user defined name of the operation.
java.lang.String	getOperationId() Returns unique identifier of the operation.
int	getPendingEvaluationDevicesNumber() Returns the number of devices on which the operation filters have still not been evaluated to decide if they are involved in the operation.
int	getPeriod() Returns the time period of the periodic operation in minutes.
OperationPermanentOptions	getPermanentOptions() Returns the permanent options for this operation.
java.lang.String	getProcedureText() Returns the procedure text of the operation or null if the operation is defined by a set of Command objects.
java.util.Dictionary<java.lang.String,java.lang.Object>	getProperties()
java.util.Date	getStartTime() Returns the time when the operation has been started.
java.lang.String	getStatus() Returns current status of this management operation.
java.lang.String	getStatusRemark() The result of this method indicates whether the operation status returned by the getStatus() method certainly indicates the real status of this operation or this status is possibly incorrect because of some reason.
<any>	getSuccessReplies() Returns list of ControlUnitID objects for devices this operation is finished successfully
int	getSuccessRepliesNumber() Returns the number of devices where this operation has been successfully executed.
int	getWarningRepliesNumber() Returns the number of devices that have replied warning while executing the operation.
Enumerator	getWarningResults() Returns list of OperationResult objects for devices that have replied errors and corresponding warning messages.
boolean	isFixedRate() Checks if this periodic operation is in fixed-rate execution mode.
boolean	isPending(java.lang.String deviceType, java.lang.String deviceId) Checks if this operation is pending for execution for a given device.
boolean	isPeriodic() Returns if this operation is executed over the involved devices periodically with a given time interval.
boolean	isPermanent() Deprecated. As of mPRM 3.3, the preferred way is to use the extended functionality method getPermanentOptions().
void	removeOperationListener(OperationListener listener) Unregisters operation listener.
void	retry() Re-executes operation over the devices which have replied with errors.
void	retry(CommandResultListener commandResultListener) Re-executes operation over the devices which have replied with errors.
void	retry(java.lang.String deviceType, java.lang.String deviceId) Re-executes operation over the devices which have replied with errors.
void	schedule(java.util.Date startTime) Schedules the operation for execution on the supplied date/time.
void	schedule(java.util.Date startTime, CommandResultListener commandResultListener) Schedules the operation for execution on the supplied date/time.
void	setDelayTolerance(int delayMinutes) Sets the permissible delay for a scheduled starting of operations.
void	setFixedRate(boolean fixedRate) Sets fixed-rate or fixed-delay execution mode for periodic operations.
void	setPeriod(int minutes) Sets/unsets the operation as periodical, specifying the execution period in minutes.
void	setPermanent(boolean permanent) Deprecated. As of mPRM 3.3, the preferred way is to use the extended functionality method setPermanent(OperationPermanentOptions).
void	setPermanent(OperationPermanentOptions options) Sets permanent options for this operation.
void	setProperties(java.util.Dictionary<java.lang.String,java.lang.Object> properties)
void	start() Starts execution of the operation.
void	start(CommandResultListener commandResultListener) Starts execution of the operation.

Field Detail

STATUS_DEFINED

static final java.lang.String STATUS_DEFINED

Operation is defined but is not scheduled for execution.

See Also:

Constant Field Values

STATUS_SCHEDULED

static final java.lang.String STATUS_SCHEDULED

Operation is scheduled for execution, but is not started yet.

See Also:

Constant Field Values

STATUS_RUNNING

static final java.lang.String STATUS_RUNNING

Operation is running.

See Also:

Constant Field Values

STATUS_FINISHED

static final java.lang.String STATUS_FINISHED

Operation has finished its execution.

See Also:

Constant Field Values

Method Detail

getOperationId

java.lang.String getOperationId()
                         throws ManagementException

Returns unique identifier of the operation. It is generated by the mPRM.

Returns:

operation id

Throws:

ManagementException - if a system error occurs.

getName

java.lang.String getName()

Returns user defined name of the operation. This attribute is optional. If the operation has no name the method returns null.

Returns:

operation name.

getStatus

java.lang.String getStatus()
                    throws ManagementException

Returns current status of this management operation. It is one of STATUS_DEFINED, STATUS_SCHEDULED, STATUS_RUNNING or STATUS_FINISHED constants.

Returns:

status of the operation.

Throws:

ManagementException - if a system error occurs.

getStatusRemark

java.lang.String getStatusRemark()
                          throws ManagementException

The result of this method indicates whether the operation status returned by the getStatus() method certainly indicates the real status of this operation or this status is possibly incorrect because of some reason. Usually, incorrect status is returned when a Management Server included into the operation scope is not currently online and there is no information obtained from this Management Server about this operation. Such situation may reflect with denoting a wrong number of involved devices.

Returns:

null if all the operation info is successfully obtained from all Management Servers in the operation scope

Throws:

ManagementException - if a system error occurs.

getProcedureText

java.lang.String getProcedureText()
                           throws ManagementException

Returns the procedure text of the operation or null if the operation is defined by a set of Command objects.

Returns:

procedure text which this operation executes.

Throws:

ManagementException - if a system error occurs.

getContextPath

java.lang.String getContextPath()
                         throws ManagementException

Returns target device or group of devices which are affected by the management operation.

Returns:

path of the target device or device group.

Throws:

ManagementException - if a system error occurs.

getCommand

Command getCommand()
            throws ManagementException

Returns a Command executed by this operation or null if the operation is defined by script text.

Returns:

Command object.

Throws:

ManagementException - if a system error occurs.

setPermanent

void setPermanent(boolean permanent)
           throws ManagementException

Deprecated. As of mPRM 3.3, the preferred way is to use the extended functionality method setPermanent(OperationPermanentOptions).

Sets/unsets the operation as permanent. The operation shall be executed not only over the devices registered with the mPRM in operation start time, but also over the devices which will be registered in the future.

Parameters:

permanent - if set to true the operation will become permanent.

Throws:

ManagementException - if a system error occurs.

isPermanent

boolean isPermanent()
             throws ManagementException

Deprecated. As of mPRM 3.3, the preferred way is to use the extended functionality method getPermanentOptions().

Returns if the operation is permanent. Permanent operations are executed not only over the devices registered with the mPRM in operation start time, but also over the devices which will be registered in the future.

Returns:

true if the operation is permanent.

Throws:

ManagementException - if a system error occurs.

setPermanent

void setPermanent(OperationPermanentOptions options)
           throws ManagementException

Sets permanent options for this operation.

Parameters:

options - permanent options

Throws:

ManagementException - if a system error occurs.

getPermanentOptions

OperationPermanentOptions getPermanentOptions()
                                       throws ManagementException

Returns the permanent options for this operation.

Returns:

the permanent options for this operation.

Throws:

ManagementException - if a system error occurs.

getStartTime

java.util.Date getStartTime()
                     throws ManagementException

Returns the time when the operation has been started. If the operation has not been started yet, null is returned.

Returns:

operation starting date/time.

Throws:

ManagementException - if a system error occurs.

getFinishTime

java.util.Date getFinishTime()
                      throws ManagementException

Returns the time when the operation finished. If the operation has not finished yet then null is returned.

Returns:

operation finish date/time.

Throws:

ManagementException - if a system error occurs.

isPeriodic

boolean isPeriodic()
            throws ManagementException

Returns if this operation is executed over the involved devices periodically with a given time interval.

Returns:

true if operation is defined as periodic.

Throws:

ManagementException - if a system error occurs.

getPeriod

int getPeriod()
       throws ManagementException

Returns the time period of the periodic operation in minutes. If this operation is not periodic, -1 will be returned.

Returns:

period in minutes.

Throws:

ManagementException - if a system error occurs.

setPeriod

void setPeriod(int minutes)
        throws ManagementException

Sets/unsets the operation as periodical, specifying the execution period in minutes.

Parameters:

minutes - the execution period in minutes. Setting this argument to 0 disables periodical execution.

Throws:

ManagementException - if a system error occurs.

setFixedRate

void setFixedRate(boolean fixedRate)
           throws ManagementException

Sets fixed-rate or fixed-delay execution mode for periodic operations. In fixed-rate execution, each execution is scheduled relative to the scheduled start time. If an execution is delayed for any reason (such as temporary stopping of the mPRM or the system is too busy), two or more executions will occur in rapid succession to "catch up." Fixed-rate execution is appropriate for recurring activities that are sensitive to absolute time, such as ringing a chime every hour on the hour, or running scheduled maintenance every day at a particular time. Finally, fixed-rate execution is appropriate for scheduling multiple repeating timer tasks that must remain synchronized with respect to one another.

The opposite of fixed-rate is the fixed-delay execution. In fixed-delay execution, each execution is scheduled relative to the actual execution time of the previous execution. If an execution is delayed for any reason subsequent executions will be delayed as well.

The default behavior of periodical operations is fixed-delay. This method enables defining of fixed-rate periodic operations by invoking it with true parameter.

Parameters:

fixedRate - true sets this generator as fixed-rate, false sets it as fixed-delay (the default).

Throws:

ManagementException - if the generator is already started.

isFixedRate

boolean isFixedRate()

Checks if this periodic operation is in fixed-rate execution mode.

Returns:

true if fixed-rate execution mode, false if fixed-delay.

See Also:

setFixedRate(boolean)

setDelayTolerance

void setDelayTolerance(int delayMinutes)
                throws ManagementException

Sets the permissible delay for a scheduled starting of operations. If starting of operation delays more than the specified by this method time, the execution will be skipped at all. The delay tolerance may be defined only for fixed-rate periodic operations and is useful when the periodical task associated with the operation must be executed in a particular absolute time or not executed at all. By default the permissible delay interval is equal to the period, i.e. it only ensures that several sequential events are not overlapped. This method only sets the object attribute for the delay tolerance with the passed value.

Parameters:

delayMinutes - permissible delay interval in minutes.

Throws:

ManagementException - if the generator is already started.

getDelayTolerance

long getDelayTolerance()

Returns the delay tolerance for this operation.

Returns:

delay tolerance in minutes.

See Also:

setDelayTolerance(int)

getInvolvedDevicesNumber

int getInvolvedDevicesNumber()
                      throws ManagementException

Returns the number of devices this operation is executing over.

Returns:

number of involved by the operation devices.

Throws:

ManagementException - if a system error occurs.

getPendingEvaluationDevicesNumber

int getPendingEvaluationDevicesNumber()
                               throws ManagementException

Returns the number of devices on which the operation filters have still not been evaluated to decide if they are involved in the operation. Operation filters are not evaulated against a given device, if the command interpreter for the operation commands denote this device is currently not ready to execute them.

Returns:

number of pending evaluation device for this operation.

Throws:

ManagementException - if a system error occurs.

getSuccessRepliesNumber

int getSuccessRepliesNumber()
                     throws ManagementException

Returns the number of devices where this operation has been successfully executed.

Returns:

number of devices finished with success.

Throws:

ManagementException - if a system error occurs.

getErrorRepliesNumber

int getErrorRepliesNumber()
                   throws ManagementException

Returns devices that have replied error while executing the operation.

Returns:

number of devices replied with errors

Throws:

ManagementException - if a system error occurs.

getWarningRepliesNumber

int getWarningRepliesNumber()
                     throws ManagementException

Returns the number of devices that have replied warning while executing the operation.

Returns:

number of devices replied with warnings

Throws:

ManagementException - if a system error occurs.

getErrorResults

Enumerator getErrorResults()
                    throws ManagementException

Returns list of OperationResult objects for devices that have replied errors and corresponding error messages.

Returns:

an Enumerator of OperationResult objects. If there are no error results, null is returned.

Throws:

ManagementException - if a system error occurs.

getWarningResults

Enumerator getWarningResults()
                      throws ManagementException

Returns list of OperationResult objects for devices that have replied errors and corresponding warning messages.

Returns:

Enumerator of OperationResult objects. If there are no warning results, null is returned.

Throws:

ManagementException - if a system error occurs.

getSuccessReplies

<any> getSuccessReplies()
                 throws ManagementException

Returns list of ControlUnitID objects for devices this operation is finished successfully

Returns:

an Enumerator of ControlUnitID objects. If there are no successfully finished devices, null is returned.

Throws:

ManagementException - if a system error occurs.

getInvolvedDevices

<any> getInvolvedDevices()
                  throws ManagementException

Returns involved devices identifiers

Returns:

an Enumerator of ControlUnitID objects. If there are no involved devices, null is returned.

Throws:

ManagementException - if a system error occurs.

start

void start()
    throws ManagementException

Starts execution of the operation.

Throws:

ManagementException - if a system error occurs.

start

void start(CommandResultListener commandResultListener)
    throws ManagementException

Starts execution of the operation.

Parameters:

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 be deactivated invoking the OperationManager.removeCommandResultListener(CommandResultListener) method.

Throws:

ManagementException - if a system error occurs.

schedule

void schedule(java.util.Date startTime)
       throws ManagementException

Schedules the operation for execution on the supplied date/time.

Parameters:

startTime - the operation start time.

Throws:

ManagementException - if a system error occurs.

schedule

void schedule(java.util.Date startTime,
              CommandResultListener commandResultListener)
       throws ManagementException

Schedules the operation for execution on the supplied date/time.

Parameters:

startTime - the operation start time.

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 be deactivated invoking the OperationManager.removeCommandResultListener(CommandResultListener) method.

Throws:

ManagementException - if a system error occurs.

cancel

void cancel()
     throws ManagementException

Interrupts execution of the operation.

Throws:

ManagementException - if a system error occurs.

delete

void delete()
     throws ManagementException

Deletes information about this operation.

Throws:

ManagementException - if a system error occurs.

retry

void retry()
    throws ManagementException

Re-executes operation over the devices which have replied with errors.

Throws:

ManagementException - if a system error occurs.

retry

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

Re-executes operation over the devices which have replied with errors.

Throws:

ManagementException - if a system error occurs.

retry

void retry(CommandResultListener commandResultListener)
    throws ManagementException

Re-executes operation over the devices which have replied with errors.

Parameters:

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 be deactivated invoking the OperationManager.removeCommandResultListener(CommandResultListener) method.

Throws:

ManagementException - if a system error occurs.

addOperationListener

void addOperationListener(OperationListener listener)
                   throws ManagementException

Registers application defined listener which will be notified for status changes in the scope of this operation.

Parameters:

listener - the listener object.

Throws:

ManagementException - if a system error occurs.

removeOperationListener

void removeOperationListener(OperationListener listener)

Unregisters operation listener.

Parameters:

listener - the listener object.

isPending

boolean isPending(java.lang.String deviceType,
                  java.lang.String deviceId)
           throws ManagementException

Checks if this operation is pending for execution for a given device.

Parameters:

deviceType - device type.

deviceId - device id.

Returns:

true if this operation is pending for execution for the device specified by the pair of parameters deviceType and deviceId, false otherwise.

Throws:

ManagementException - if system error occurs.

setProperties

void setProperties(java.util.Dictionary<java.lang.String,java.lang.Object> properties)
            throws ManagementException

Throws:

ManagementException

getProperties

java.util.Dictionary<java.lang.String,java.lang.Object> getProperties()
                                                               throws ManagementException

Throws:

ManagementException