org.licas.autonomic.script

## Class AutoEngine

- java.lang.Object
- - org.licas.autonomic.script.AutoEngine

-     public class AutoEngine
      extends java.lang.Object

  This is a default implementation of an engine that can be used to interpret and execute the provided default script, possibly for the autonomic manager or one of its modules, or for an autonomous service in general. The script can be made up of a number of `AutoEngineInfo` objects that get processed in order. Evaluation takes place through the `process` method, where the `MessageInfo` object should pass a `ArrayList` of parameter values to pass to the evaluation method. This is partially dynamic, where a parameter list be specified as a `KeyValue` set, where the key can be the actual variable name in the method or class itself. This can then be matched to the auto engine method script that defines what parameters are required. It can include the parameter or variable name that should be used, where `AiConst`.`QUERY` is reserved for the `input` variable of this class and `REPLY` is reserved for the evaluator reply. If any name is missing, then it does not have to be added.

  So a specific list of variable names will use only those variables and can include or omit anything specified/not specified. If a list of objects is passed, they are used in that order. If the list is replaced by a single object, then only that single value gets added.

  Author:
    Kieran Greer

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected org.dcs.query_process.Script_Engine` | `engine` The engine to return the script elements in order.
    `protected ObjectsMap` | `objectsMap` List of all named entities in the script, referenced by their unique public id.
    `protected org.dcs.query_process.model.Script_Process` | `process` The process model to execute.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AutoEngine(Service thisParent, PasswordHandler thisPasswordHandler)` Create a new instance of AutoEngine.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected AutoOut` | `executeScriptElement(AutoEngineInfo rootInfo)` Execute the script element if appropriate and then return the result.
    `protected MessageInfo` | `getAutoQueueMessage(org.dcs.query_process.model.activity.Script_Auto scriptAuto)` Get the first message in the auto manager's queue, retrieved using the specified function.
    `protected PasswordHandler` | `getPasswordHandler()` Get the password handler.
    `org.dcs.query_process.Script_Engine` | `getScriptEngine()` Get the script engine that processes and returns script elements in order.
    `boolean` | `hasProcess()` Return true if the engine has a process script loaded, false otherwise.
    `AutoOut` | `invokeMethod(AutoEngineInfo rootInfo, java.util.ArrayList<KeyValue> paramList)` Invoke the method in the `autoInfo` object, making variable replacements first.
    `boolean` | `isFinished()` Return true if there are no further script elements to process.
    `java.util.ArrayList<KeyValue>` | `process(MessageInfo messageInfo)` Process the script data and return the result.
    `void` | `resetEventRuleAction()` Reset the already created event-rule-action script part so that it can be run again.
    `void` | `setEventRuleAction(org.licas_xml.abs.Element policyElem)` Parse the event-rule-action script part and create the related objects.
    `void` | `setParent(Service thisParent)` Set the parent service.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### engine

          protected org.dcs.query_process.Script_Engine engine

      The engine to return the script elements in order.

    - #### process

          protected org.dcs.query_process.model.Script_Process process

      The process model to execute.

    - #### objectsMap

          protected ObjectsMap objectsMap

      List of all named entities in the script, referenced by their unique public id. Key is the id and value is the script element converted into its object instance.

  - ### Constructor Detail

    - #### AutoEngine

          public AutoEngine(Service thisParent,
                            PasswordHandler thisPasswordHandler)

      Create a new instance of AutoEngine. Parameters can be null if not used.
      Parameters:
        `thisParent` - the parent service. This is required if the `this` keyword is used.
        `thisPasswordHandler` - the parent password handler.

  - ### Method Detail

    - #### hasProcess

          public boolean hasProcess()

      Return true if the engine has a process script loaded, false otherwise.
      Returns:
        true if process is not null, false otherwise.

    - #### isFinished

          public boolean isFinished()
                             throws java.lang.Exception

      Return true if there are no further script elements to process.
      Returns:
        true if at the end of the process stack. If the loop stack still has elements, then these would normally be processed.
      Throws:
        `java.lang.Exception` - any error.

    - #### setEventRuleAction

          public void setEventRuleAction(org.licas_xml.abs.Element policyElem)
                                  throws java.lang.Exception

      Parse the event-rule-action script part and create the related objects.
      Parameters:
        `policyElem` - the policy section of the script.
      Throws:
        `java.lang.Exception` - any error.

    - #### resetEventRuleAction

          public void resetEventRuleAction()
                                    throws java.lang.Exception

      Reset the already created event-rule-action script part so that it can be run again.
      Throws:
        `java.lang.Exception` - any error.

    - #### process

          public java.util.ArrayList<KeyValue> process(MessageInfo messageInfo)
                                                throws java.lang.Exception

      Process the script data and return the result. This default version will evaluate the message and execute any method using invocation. It will also replace named or tagged variables with actual instances from the parameter list included in the input `messageInfo` object. A BPEL-like script is used, but it is limited.
      Parameters:
        `messageInfo` - the message to evaluate. In this case it should be a `ArrayList` of parameter values (as `KeyValue`) as the message (`messageInfo.getMessage()`) that then update the method parameters. It can be `null` if there are no additional parameter values.
      Returns:
        the result of the monitoring. Note that this should not change the input message and is a list of actions to carry out in sequence, as `KeyValue` pairs.
      Throws:
        `java.lang.Exception` - any error.

    - #### executeScriptElement

          protected AutoOut executeScriptElement(AutoEngineInfo rootInfo)

      Execute the script element if appropriate and then return the result. This is probably the saved effector actions list, as `AutoEngineInfo` objects.
      Parameters:
        `rootInfo` - the root info object for execution.
      Returns:
        the value of effOutput.

    - #### invokeMethod

          public AutoOut invokeMethod(AutoEngineInfo rootInfo,
                                      java.util.ArrayList<KeyValue> paramList)
                               throws LicasException,
                                      java.lang.Exception

      Invoke the method in the `autoInfo` object, making variable replacements first. From that object, the `evaluator` is used to execute the `method`. The evaluation can be compared to the `function`. The `input` can be used to replace a tagged `Const`.`QUERY` parameter and so should be an XML element. If the reply is OK, the autoInfo `effOutput` is returned as the next set of actions.
      Parameters:
        `rootInfo` - the root process script for execution.
        `paramList` - an external set of `KeyValue` objects that can replace named or tagged fields in the method parameter lists. If empty or no match, then nothing gets changed.
      Returns:
        the result of the evaluation. This is the `effector list` of the input parameter if the evaluation is true, or an empty list if it is false. Evaluating to true can include matching exactly to an XML description, or just have any result, for example, by using a `checkReply` method.
      Throws:
        `LicasException` - for a licas-specific mapping problem.
        `java.lang.Exception` - any error.

    - #### getAutoQueueMessage

          protected MessageInfo getAutoQueueMessage(org.dcs.query_process.model.activity.Script_Auto scriptAuto)

      Get the first message in the auto manager's queue, retrieved using the specified function.
      Parameters:
        `scriptAuto` - description of the message to retrieve.
      Returns:
        the message if it exists, or null if there are none, or there is no parent service or queue.

    - #### setParent

          public void setParent(Service thisParent)

      Set the parent service.
      Parameters:
        `thisParent` - the parent service.

    - #### getScriptEngine

          public org.dcs.query_process.Script_Engine getScriptEngine()

      Get the script engine that processes and returns script elements in order.
      Returns:
        the value of engine.

    - #### getPasswordHandler

          protected PasswordHandler getPasswordHandler()

      Get the password handler.
      Returns:
        the value of passwordHandler.