com.prosyst.mprm.admin.rule

Interface Rule

public interface Rule

Represents a Rule.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Rule.State Defines possible Rule states.

Method Summary

Modifier and Type	Method and Description
void	addRuleListener(RuleListener ruleListener, java.util.Map<java.lang.String,java.lang.Object> listenerProps) Registers Rule listener for receiving event notifications about the current Rule.
void	addTaskListener(TaskListener taskListener, java.util.Map<java.lang.String,java.lang.Object> listenerProps) Registers Task listener for receiving event notifications about Task launched by the current Rule.
void	delete() Deletes the Rule.
void	disable() Disables the Rule.
void	disable(boolean cancelRuleTasks) Disables the Rule.
void	enable() Enables the Rule.
void	fire() Fires the Rule manually.
java.lang.String	getActionScript() Returns the groovy script defining the action for this Rule.
java.lang.String	getDisplayName() Returns the user-friendly display name of this Rule.
ExecOptions	getExecOptions() Returns the execution options of this Rule.
int	getInvolvedDevicesCount(DeviceExecStatus.State deviceExecState) Calculates the count of involved devices with given execution status in this Rule.
DeviceRuleStatus	getInvolvedDeviceState(java.lang.String deviceType, java.lang.String deviceId) Returns the execution status of a given device within this Rule.
java.util.Date	getNextTimeTrigger() Calculates the time at which this Rule will be fired for the next time by its TimerTrigger.
java.util.Map<java.lang.String,java.lang.Object>	getProperties() Returns custom properties assigned to this Rule.
java.lang.Object	getProperty(java.lang.String key) Gets the value of a Rule property by property name.
java.lang.String	getRuleId() Returns the id of this Rule.
Scope	getScope() Returns the Rule scope.
Rule.State	getState() Returns the state of this Rule.
java.lang.String	getStateDescription() May return a text message explaining the Rule state.
java.lang.String	getTextRepresentation() Returns the JSON-representation of the Rule definition.
Trigger	getTrigger() Returns the Rule trigger.
int	getTriggersCount() Tells how many times this Rule has been triggered.
java.lang.String	getUser() Returns the user-name of the user created this Rule.
<any>	listInvolvedDevices(DeviceExecStatus.State deviceExecState) Retrieves a list of all involved devices into this Rule with the respective execution status for each device.
FilteredSet<Task>	listLaunchedTasks(java.lang.String taskFilter) Retrieves all Tasks originating from that Rule that satisfy given filtering criteria.
FilteredSet<Task>	listLaunchedTasksForDevice(java.lang.String deviceType, java.lang.String deviceId, java.lang.String taskFilter) Retrieves all Tasks originating from that Rule that include a given device, possible filtered by some Tasks criteria.
void	modify(java.lang.String ruleDef) Modifies existing Rule.
void	modify(java.lang.String ruleDisplayName, Scope scope, Trigger trigger, ExecOptions options, java.lang.String actionScript) Modifies existing Rule.
void	removeRuleListener(RuleListener ruleListener) Unregisters Rule listener.
void	removeTaskListener(TaskListener taskListener) Unregisters Task listener.
void	retryDevice(java.lang.String deviceType, java.lang.String deviceId) Retries the rule over the device with the given device type and device id.
void	retryDevices(DeviceExecStatus.State[] statusFilter) Retries the rule over the devices whose status satisfies the given status filter.
void	setProperties(java.util.Map<java.lang.String,java.lang.Object> properties, boolean append) Sets the custom Rule properties.
void	setProperty(java.lang.String key, java.lang.Object value) Sets custom Rule property.

Method Detail

getNextTimeTrigger

java.util.Date getNextTimeTrigger()
                           throws ManagementException

Calculates the time at which this Rule will be fired for the next time by its TimerTrigger. Note that this method is not applicable when no TimerTrigger is defined in this Rule.

Returns:

the time at which the Rule will be fired by timer.

Throws:

ManagementException - if system error occurs.

getState

Rule.State getState()
             throws ManagementException

Returns the state of this Rule.

Returns:

Rule state.

Throws:

ManagementException - if system error occurs.

getStateDescription

java.lang.String getStateDescription()
                              throws ManagementException

May return a text message explaining the Rule state. For instance: "Rule failed to enable, Reason: some reason" for Rules in state Rule.State.FAILED_TO_ENABLE.

Returns:

text description of the Rule state.

Throws:

ManagementException - if system error occurs.

getTriggersCount

int getTriggersCount()
              throws ManagementException

Tells how many times this Rule has been triggered. The triggers count corresponds to number of Tasks originating from that Rule.

Returns:

trigger count.

Throws:

ManagementException - if system error occurs.

listInvolvedDevices

<any> listInvolvedDevices(DeviceExecStatus.State deviceExecState)
                   throws ManagementException

Retrieves a list of all involved devices into this Rule with the respective execution status for each device. A device is considered involved into the Rule, if it is involved in at least one Task originated from that Rule. The execution status of an involved device is considered as follows:

DeviceExecStatus.State.RUNNING if the device is in running status in at least one Task originated from that Rule. Otherwise, the device is considered finished and the finish status (DeviceExecStatus.State.FINISHED_SUCCESS, DeviceExecStatus.State.FINISHED_ERROR, DeviceExecStatus.State.FINISHED_SUCCESS or DeviceExecStatus.State.FINISHED_CANCELED) corresponds to the finish status from the latest Task (originating from that Rule) the has been involved in.

Parameters:

deviceExecState - filter on the execution status for the retrieved involved devices. For example, there could be retrieved only devices that have finished the Rule execution with error (use: DeviceExecStatus.State.FINISHED_ERROR) or devices that have finished with any status (use: DeviceExecStatus.State.FINISHED) or completely all involved devices regardless of the execution status (use: DeviceExecStatus.State#FINISHED_ANY)

Returns:

a list of DeviceExecStatus objects representing the execution status of a single involved device.

Throws:

ManagementException - if system error occurs.

getInvolvedDeviceState

DeviceRuleStatus getInvolvedDeviceState(java.lang.String deviceType,
                                        java.lang.String deviceId)
                                 throws ManagementException

Returns the execution status of a given device within this Rule.

Parameters:

deviceType - device type.

deviceId - device id.

Returns:

execution status.

Throws:

ManagementException - if system error occurs.

getInvolvedDevicesCount

int getInvolvedDevicesCount(DeviceExecStatus.State deviceExecState)
                     throws ManagementException

Calculates the count of involved devices with given execution status in this Rule.

Parameters:

deviceExecState - filter on the execution status for the counted involved devices. For example, there could be counted only devices that have finished the Task execution with error (use: DeviceExecStatus.State.FINISHED_ERROR) or devices that have finished with any status (use: DeviceExecStatus.State.FINISHED) or completely all involved devices regardless of the execution status (use: DeviceExecStatus.State#FINISHED_ANY)

Returns:

a involved devices count.

Throws:

ManagementException - if system error occurs.

listLaunchedTasks

FilteredSet<Task> listLaunchedTasks(java.lang.String taskFilter)
                             throws ManagementException

Retrieves all Tasks originating from that Rule that satisfy given filtering criteria.

Parameters:

taskFilter - a filter in mPRM-Filter syntax over the Task attributes.
Example: ((errorCount > 0 | state == 2) & (ruleId != "R5K2A92DX8J" | !(action includes "myService.myMethod()")))
The attribute names in the filtering conditions can be some of:

state - integer value corresponding to the Task status as follows:
0 - DEFINED
1 - RUNNING
2 - FINISHED
3 - FAILED_TO_LAUNCH

stateDescription - string value corresponding to the state description.

launchTime - long value corresponding to the Task launch time given as milliseconds since 1 Jan 1970.

finishTime - long value corresponding to the Task finish time given as milliseconds since 1 Jan 1970.

involvedCount - integer value corresponding the the number of involved devices in the Task.

successCount - integer value corresponding the the number of successfully finished devices in the Task.

warningCount - integer value corresponding the the number of devices finished with warning in the Task.

errorCount - integer value corresponding the the number of devices finished with error in the Task.

cancelCount - integer value corresponding the the number of devices finished with warning in the Task.

isPaused - boolean value that is true when the execution is paused die to time constraint restrictions.

nextResume - corresponds to resume time (in milliseconds since 1 Jan 1970) if the Task is currently paused.

nextPause - corresponds to next pause time (in milliseconds since 1 Jan 1970) if the Task is currently not paused.

taskId - string value corresponding to the task id.

ruleId - string value corresponding to the rule id if the Task originates from a Rule trigger.

user - string value corresponding to the user name of the user that has launched the Task.

action - string value corresponding to groovy script of the Task action.

displayName - string value corresponding Task display name. *

Returns:

a FilteredSet from which the list of Tasks satisfying the filter could be listed (see: FilteredSet.list()) and arbitrary Tasks (potentially caught by events) could be matched if they satisfy the filtering criteria of the FilteredSet. See FilteredSet.match(Object).

Throws:

ManagementException - if system error occurs.

listLaunchedTasksForDevice

FilteredSet<Task> listLaunchedTasksForDevice(java.lang.String deviceType,
                                             java.lang.String deviceId,
                                             java.lang.String taskFilter)
                                      throws ManagementException

Retrieves all Tasks originating from that Rule that include a given device, possible filtered by some Tasks criteria.

Parameters:

deviceType -

deviceId -

taskFilter -

Returns:

Throws:

ManagementException

getRuleId

java.lang.String getRuleId()

Returns the id of this Rule.

Returns:

Rule Id.

getScope

Scope getScope()

Returns the Rule scope.

Returns:

Rule scope.

getTrigger

Trigger getTrigger()

Returns the Rule trigger.

Returns:

Rule trigger.

getExecOptions

ExecOptions getExecOptions()

Returns the execution options of this Rule.

Returns:

execution options.

getActionScript

java.lang.String getActionScript()

Returns the groovy script defining the action for this Rule.

Returns:

groovy action script.

getDisplayName

java.lang.String getDisplayName()

Returns the user-friendly display name of this Rule.

Returns:

Rule display name.

getUser

java.lang.String getUser()
                  throws ManagementException

Returns the user-name of the user created this Rule.

Returns:

user name.

Throws:

ManagementException - if system error occurs.

enable

void enable()
     throws ManagementException

Enables the Rule. Once enabled, the Rule turns into state Rule.State.ENABLED and may be triggered either manually or automatically regarding its defined triggers.

Throws:

ManagementException - if system error occurs.

disable

void disable()
      throws ManagementException

Disables the Rule. Once disabled, the Rule turns into state Rule.State.DISABLED and cannot be triggered any more in this state. Invoking this method has the same effect as invoking the disable(boolean) method with argument true, i.e., all running Tasks originating from that Rule will be automatically canceled.

Throws:

ManagementException - if system error occurs.

disable

void disable(boolean cancelRuleTasks)
      throws ManagementException

Disables the Rule. Once disabled, the Rule turns into state Rule.State.DISABLED and cannot be triggered any more in this state.

Parameters:

cancelRuleTasks - specifies whether all running Tasks originating from that Rule to be directly canceled or should be left to complete normally. If Tasks are left to finish normally then Rule statistics (involved/finished devices, etc.) may continue to change as long as Tasks reflecting those statistics are still be working. But in any case - no new Tasks will be anymore triggered as Rule is in state Rule.State.DISABLED.

Throws:

ManagementException - if system error occurs.

delete

void delete()
     throws ManagementException

Deletes the Rule.

Throws:

ManagementException - if system error occurs.

modify

void modify(java.lang.String ruleDisplayName,
            Scope scope,
            Trigger trigger,
            ExecOptions options,
            java.lang.String actionScript)
     throws ManagementException

Modifies existing Rule. In order to be modified the Rule must not be in state Rule.State.ENABLED. After modification, any previous execution information relate to that Rule (Tasks, number of involved, finished devices, etc.) will be cleaned.

Parameters:

ruleDisplayName - user-friendly display name of the Rule.

scope - defines the initial execution scope of the Rule. The Rule could be system-scoped or device-scoped and could cover arbitrary set of respective targets.

trigger - defines the triggering criteria for the Rule.

options - defines the execution options of the Rule.

actionScript - the Rule action provided as groovy script.

Throws:

ManagementException - if system error occurs.

modify

void modify(java.lang.String ruleDef)
     throws ManagementException

Modifies existing Rule. In order to be modified the Rule must not be in state Rule.State.ENABLED. After modification, any previous execution information relate to that Rule (Tasks, number of involved, finished devices, etc.) will be cleaned.

Parameters:

ruleDef - JSON-encoded Rule definition of the modified Rule. For details in the JSON definition, refer to RuleEngine.createRule(String) method.

Throws:

ManagementException - if system error occurs.

fire

void fire()
   throws ManagementException

Fires the Rule manually. When Rule is fired manually, only the TriggerElements which are mode TriggerMode#MANAUL are evaluated and if any of their conditions is satisfied the Rule gets triggered.

Throws:

ManagementException - if system error occurs.

addTaskListener

void addTaskListener(TaskListener taskListener,
                     java.util.Map<java.lang.String,java.lang.Object> listenerProps)
              throws ManagementException

Registers Task listener for receiving event notifications about Task launched by the current Rule.

Parameters:

taskListener - user-implemented listener interface.

listenerProps - registration properties of the Task listener. Here filtering on the desired event types could be supplied using TaskListener.TASK_EVENT_FILTER as a key and array of TaskEventType-s as a value.

Throws:

ManagementException - if system error occurs.

removeTaskListener

void removeTaskListener(TaskListener taskListener)

Unregisters Task listener.

Parameters:

taskListener - user-implemented listener interface.

addRuleListener

void addRuleListener(RuleListener ruleListener,
                     java.util.Map<java.lang.String,java.lang.Object> listenerProps)
              throws ManagementException

Registers Rule listener for receiving event notifications about the current Rule.

Parameters:

listenerProps - registration properties of the Rule listener. Here filtering on the desired event types could be supplied using RuleListener.RULE_EVENT_FILTER as a key and array of RuleEventType-s as a value.

Throws:

ManagementException - if system error occurs.

removeRuleListener

void removeRuleListener(RuleListener ruleListener)

Unregisters Rule listener.

Parameters:

ruleListener - user-implemented listener interface.

getTextRepresentation

java.lang.String getTextRepresentation()

Returns the JSON-representation of the Rule definition. This method the opposite of RuleEngine.createRule(String). It exports the Rule as portable JSON text that can be used further in creating a copy of this Rule via the RuleEngine.createRule(String) method.

Returns:

JSON-representation of the Rule definition.

getProperties

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

Returns custom properties assigned to this Rule. Rule properties can be assigned via the setProperties(Map, boolean) and setProperty(String, Object) methods.

Returns:

Rule properties.

Throws:

ManagementException

setProperties

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

Sets the custom Rule properties.

Parameters:

properties - Rule properties.

append - if true the supplied properties will be appended/added to any properties currently existing for this Rule, otherwise any existing properties will be fully replaced by the supplied ones.

Throws:

ManagementException - if system error occurs.

getProperty

java.lang.Object getProperty(java.lang.String key)
                      throws ManagementException

Gets the value of a Rule property by property name.

Parameters:

key - property name

Returns:

property value.

Throws:

ManagementException

setProperty

void setProperty(java.lang.String key,
                 java.lang.Object value)
          throws ManagementException

Sets custom Rule property.

Parameters:

key - property name.

value - property value.

Throws:

ManagementException - if system error occurs.

retryDevices

void retryDevices(DeviceExecStatus.State[] statusFilter)
           throws ManagementException

Retries the rule over the devices whose status satisfies the given status filter.

Parameters:

statusFilter -

Throws:

ManagementException

retryDevice

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

Retries the rule over the device with the given device type and device id.

Parameters:

deviceType -

deviceId -

Throws:

ManagementException