com.prosyst.mprm.admin.rule

Interface RuleEngine

public interface RuleEngine

The RuleEngine service provides functionality for appointing and monitoring of Task executions and automation Rules over the mPRM System and devices managed by mPRM.

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 created/deleted Rules in the system Tasks, changes in Task as well as changes in Rules states.
void	addTaskListener(TaskListener taskListener, java.util.Map<java.lang.String,java.lang.Object> listenerProps) Registers Task listener for receiving event notifications about launched Tasks, changes in Task progress, etc.
Rule	createRule(java.lang.String ruleDef) Creates a Rule by given JSON-encoded Rule definition.
Rule	createRule(java.lang.String ruleDisplayName, Scope scope, Trigger trigger, ExecOptions options, java.lang.String actionScript) Creates a Rule with given attributes - display name, execution scope, trigger definition, execution options and groovy script text.
RuleBuilder	createRuleBuilder(java.lang.String ruleName) Returns RuleBuilder service for convenient building of a Rule via multiple set-methods.
TaskBuilder	createTaskBuilder(java.lang.String taskName) Returns TaskBuilder service for convenient building of a Task via multiple set-methods.
void	fireAllRules() Fires all Rules that have TriggerEvent.getTriggerMode() equal to TriggerMode#MANAUL in some of their TriggerElements.
EventsMetadata[]	getEventsMetadata() Provides metadata information about the available events dedicated for triggering of Rules with functional event trigger - FunctionalEventTrigger.
DeviceExecItem	getExecItem(java.lang.String execItemId) Retrieves a partial execution report - DeviceExecItem - by given execution item id.
Rule	getRule(java.lang.String ruleId) Retrieves a Rule by given Rule Id.
Task	getTask(java.lang.String taskId) Retrieves a Task by given Task Id.
Task	launchTask(java.lang.String taskDef) Launches a Task by given JSON-encoded Task definition.
Task	launchTask(java.lang.String displayName, Scope scope, ExecOptions options, java.lang.String actionScript) Launches a Task with given attributes - display name, execution scope, execution options and groovy script text.
<any>	listExecutionsForDevice(java.lang.String deviceType, java.lang.String deviceId, DeviceExecStatus.State execStatusFilter) Retrieves all execution items for a given device.
<any>	listRules() Retrieves all Rule available in mPRM.
FilteredSet<Rule>	listRules(java.lang.String ruleFilter) Retrieves all Rules available in mPRM that satisfy given filtering criteria.
<any>	listRulesForDevice(java.lang.String deviceType, java.lang.String deviceId, DeviceExecStatus.State execStatusFilter) Retrieves all Rules and respective execution status for a given device.
<any>	listTasks() Retrieves all Tasks available in mPRM.
FilteredSet<Task>	listTasks(java.lang.String taskFilter) Retrieves all Tasks available in mPRM that satisfy given filtering criteria.
<any>	listTasksForDevice(java.lang.String deviceType, java.lang.String deviceId, DeviceExecStatus.State execStatusFilter, boolean freeTasks) Retrieves all Tasks and respective execution status for a given device.
void	removeRuleListener(RuleListener ruleListener) Unregisters Rule listener.
void	removeTaskListener(TaskListener taskListener) Unregisters Task listener.

Method Detail

launchTask

Task launchTask(java.lang.String displayName,
                Scope scope,
                ExecOptions options,
                java.lang.String actionScript)
         throws ManagementException

Launches a Task with given attributes - display name, execution scope, execution options and groovy script text.

Parameters:

displayName - user-friendly display name of the Task.

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

options - defines the execution options of the Task. Note, that the only options applicable for the Task executions are ExecOptions#overlap(com.prosyst.mprm.admin.rule.ExecOptions.Overlapping) and {@link ExecOptions#timeConstraint(com.prosyst.mprm.rule.time.constraint.TimeConstraint)}. All other options defined in @link {@link ExecOptions} class (including those two) are applicable for Rules.

actionScript - the Task action provided as groovy script.

Returns:

a Task object representing the launched Task.

Throws:

ManagementException - if system error occurs.

java.lang.IllegalArgumentException - if Task parameters are inconsistent or not correct.

launchTask

Task launchTask(java.lang.String taskDef)
         throws ManagementException

Launches a Task by given JSON-encoded Task definition. TODO: example!

Parameters:

taskDef - JSON-encoded Task definition containing all elements from launchTask(String, Scope, ExecOptions, String)

Returns:

a Task object representing the launched Task.

Throws:

ManagementException - if system error occurs.

java.lang.IllegalArgumentException - if Task parameters are inconsistent or not correct.

createTaskBuilder

TaskBuilder createTaskBuilder(java.lang.String taskName)
                       throws ManagementException

Returns TaskBuilder service for convenient building of a Task via multiple set-methods.

Parameters:

taskName - display name of the new Task.

Returns:

service for building a Task.

Throws:

ManagementException - if system error occurs.

getTask

Task getTask(java.lang.String taskId)
      throws ManagementException

Retrieves a Task by given Task Id.

Parameters:

taskId - task id.

Returns:

a Task object representing the current monitoring state of the requested Task or null if Task with the provided Task Id does not exist.

Throws:

ManagementException - if system error occurs.

listTasks

<any> listTasks()
         throws ManagementException

Retrieves all Tasks available in mPRM.

Returns:

a list of Task objects representing the monitoring state of each retrieved Task.

Throws:

ManagementException - if system error occurs.

listTasks

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

Retrieves all Tasks available in mPRM 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#listTasks()) 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.

listTasksForDevice

<any> listTasksForDevice(java.lang.String deviceType,
                         java.lang.String deviceId,
                         DeviceExecStatus.State execStatusFilter,
                         boolean freeTasks)
                  throws ManagementException

Retrieves all Tasks and respective execution status for a given device.

Parameters:

deviceType - device type.

deviceId - device id.

execStatusFilter - execution status filter.

freeTasks - value of true specifies that only Task executions not bound to any Rule should be retrieved, while value of false specifies all task executions to be retrieved (including those bound to rules).

Returns:

a list of DeviceTaskStatus objects - one for each Task the given device is involved in.

Throws:

ManagementException - if system error occurs.

listExecutionsForDevice

<any> listExecutionsForDevice(java.lang.String deviceType,
                              java.lang.String deviceId,
                              DeviceExecStatus.State execStatusFilter)
                       throws ManagementException

Retrieves all execution items for a given device.

Parameters:

deviceType - device type.

deviceId - device id.

execStatusFilter - execution status filter.

Returns:

a list of DeviceExecItem objects - one for each execution the given device is involved in.

Throws:

ManagementException - if system error occurs.

getExecItem

DeviceExecItem getExecItem(java.lang.String execItemId)
                    throws ManagementException

Retrieves a partial execution report - DeviceExecItem - by given execution item id.

Parameters:

execItemId - execution item id.

Returns:

partial execution report.

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 launched Tasks, changes in Task progress, etc.

Parameters:

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.

createRule

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

Creates a Rule with given attributes - display name, execution scope, trigger definition, execution options and groovy script text.

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.

Returns:

a Rule object representing the created Rule.

Throws:

ManagementException - if system error occurs.

java.lang.IllegalArgumentException - if Rule parameters are inconsistent or not correct.

createRule

Rule createRule(java.lang.String ruleDef)
         throws ManagementException

Creates a Rule by given JSON-encoded Rule definition. TODO: example!

Parameters:

ruleDef - JSON-encoded Rule definition containing all elements from createRule(String, Scope, Trigger, ExecOptions, String)

Returns:

a Rule object representing the created Rule.

Throws:

ManagementException - if system error occurs.

java.lang.IllegalArgumentException - if Rule parameters are inconsistent or not correct.

createRuleBuilder

RuleBuilder createRuleBuilder(java.lang.String ruleName)
                       throws ManagementException

Returns RuleBuilder service for convenient building of a Rule via multiple set-methods.

Parameters:

rulesName - display name of the new Task.

Returns:

service for building a Rule.

Throws:

ManagementException - if system error occurs.

getRule

Rule getRule(java.lang.String ruleId)
      throws ManagementException

Retrieves a Rule by given Rule Id.

Parameters:

ruleId - task id.

Returns:

a Rule object representing the current monitoring state of the requested Rule or null if Rule with the provided Rule Id does not exist.

Throws:

ManagementException - if system error occurs.

listRules

<any> listRules()
         throws ManagementException

Retrieves all Rule available in mPRM.

Returns:

a list of Rule objects representing the monitoring state of each retrieved Rule.

Throws:

ManagementException - if system error occurs.

listRules

FilteredSet<Rule> listRules(java.lang.String ruleFilter)
                     throws ManagementException

Retrieves all Rules available in mPRM that satisfy given filtering criteria.

Parameters:

ruleFilter - a filter in mPRM-Filter syntax over the Rule 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 - ENABLED
2 - DISABLED
3 - FAILED_TO_ENABLE

stateDescription - string value corresponding to the state description.

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

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

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

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

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

nextTimeTrigger - corresponds to next trigger time (in milliseconds since 1 Jan 1970) if the Rule has a timer trigger.

ruleId - string value corresponding to the rule id.

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

actionScript - 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 Rules satisfying the filter could be listed (see: FilteredSet#listRules())and arbitrary Rules (potentially caught by events) could be matched if they satisfy the current filtering criteria of the FilteredSet. See FilteredSet#match(Rule).

Throws:

ManagementException - if system error occurs.

listRulesForDevice

<any> listRulesForDevice(java.lang.String deviceType,
                         java.lang.String deviceId,
                         DeviceExecStatus.State execStatusFilter)
                  throws ManagementException

Retrieves all Rules and respective execution status for a given device.

Parameters:

deviceType - device type.

deviceId - device id.

execStatusFilter - execution status filter.

Returns:

a list of DeviceRuleStatus objects - one for each Rule the given device is involved in.

Throws:

ManagementException - if system error occurs.

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 created/deleted Rules in the system Tasks, changes in Task as well as changes in Rules states.

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.

fireAllRules

void fireAllRules()
           throws ManagementException

Fires all Rules that have TriggerEvent.getTriggerMode() equal to TriggerMode#MANAUL in some of their TriggerElements.

Throws:

ManagementException - if system error occurs.

getEventsMetadata

EventsMetadata[] getEventsMetadata()
                            throws ManagementException

Provides metadata information about the available events dedicated for triggering of Rules with functional event trigger - FunctionalEventTrigger. The metadata is organized hierarchically to facilitate the good-ordering of potentially many possible events.

Returns:

list of available metadata trees.

Throws:

ManagementException - if system error occurs.