org.licas.autonomic

## Class AM_Module

- java.lang.Object
- - org.licas.autonomic.AM_Module

- Direct Known Subclasses:
    AM_AnalyzeDefault, AM_ExecuteDefault, AM_MonitorDefault, AM_PlanDefault

      public abstract class AM_Module
      extends java.lang.Object

  Interface for implementing a basic autonomic manager module. These modules are stored in and used by an `AutonomicManager`. An autonomic manager can be used to implement a self-monitoring system. In this case, separate MAPE modules can be implemented to monitor, analyze, plan, or execute the plan, based on the input that each module receives. The rules or results of this control loop can be determined by a policy document that should be included with each module implementation. The default versions however can perform some automatic processing by themselves, without an additional policy document.

  As part of a typical process, on receiving its input, the module will process the information based on the implemented code, compare that with the policy and return a `MessageInfo` object with the appropriate reply. Each base service is wrapped by an autonomic manager with a default monitor module. You can change this through the admin script for the service. The default modules will only queue the messages and return them to the service upon request. It now also stores some basic metrics or stats. Therefore, any information sent to the default manager is returned in exactly the same format.

  If you implement and add new modules, they might check for errors, for example, and then change what gets returned if something suspicious is found. If any derived module implements this interface, then this process will be consistent throughout the whole control loop.

  Author:
    Kieran Greer

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.lang.String` | `adminKey` Admin key for full access to the autonomic manager methods
    `protected AutoEngine` | `autoEngine`
    `protected AutonomicManager` | `autoMan` The parent autonomic manager
    `protected MessageInfo` | `evaluationMessage` A message representing the immediate last evaluation process
    `protected PasswordHandler` | `passwordHandler` The parent service's password handler
    `protected org.licas_xml.abs.Element` | `policy` The policy document.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AM_Module(Service serviceObj, PasswordHandler passwordHandler)` Create a new instance of AM_Module.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected MessageInfo` | `evaluationMessage()` Get a newly created message from the module, representing its evaluation and result of the immediate last process.
    `protected abstract java.util.ArrayList<KeyValue>` | `process(MessageInfo messageInfo)` Process the data and return the result.
    `protected void` | `setAutonomicManager(AutonomicManager thisAutoMan)` Set the parent autonomic manager.
    `void` | `setPolicy(org.licas_xml.abs.Element document)` Set the policy for the monitor.

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

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

- - ### Field Detail

    - #### adminKey

          protected java.lang.String adminKey

      Admin key for full access to the autonomic manager methods

    - #### policy

          protected org.licas_xml.abs.Element policy

      The policy document. This is an XML script that can represent anything, but needs to be understood by the module that uses it.

    - #### evaluationMessage

          protected MessageInfo evaluationMessage

      A message representing the immediate last evaluation process

    - #### autoMan

          protected AutonomicManager autoMan

      The parent autonomic manager

    - #### autoEngine

          protected AutoEngine autoEngine

    - #### passwordHandler

          protected PasswordHandler passwordHandler

      The parent service's password handler

  - ### Constructor Detail

    - #### AM_Module

          public AM_Module(Service serviceObj,
                           PasswordHandler passwordHandler)

      Create a new instance of AM_Module. You can only use the `AutoEngine` if the `AutonomicManager` wraps a licas `Service`-derived object.
      Parameters:
        `serviceObj` - the service object wrapped by the autonomic manager.
        `passwordHandler` - the service's password handler, for the auto script engine.

  - ### Method Detail

    - #### setAutonomicManager

          protected void setAutonomicManager(AutonomicManager thisAutoMan)

      Set the parent autonomic manager.
      Parameters:
        `thisAutoMan` - the value of autoMan.

    - #### setPolicy

          public void setPolicy(org.licas_xml.abs.Element document)
                         throws java.lang.Exception

      Set the policy for the monitor.
      Parameters:
        `document` - the policy document.
      Throws:
        `java.lang.Exception` - any error.

    - #### process

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

      Process the data and return the result. this default version will evaluate the message, using any declared default method, to determine if it matches with the policy. As this is only one monitoring implementation version, it is possible that you will need to override this method to implement a more application-specific one, but it will provide some flexibility, as it can be configured through the `setEventRuleAction` method, for example.
      Parameters:
        `messageInfo` - the message to evaluate.
      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. Each action is a list of `KeyValue` objects that can include a `Const`.`REPLY` object and `AiConst`.`EFFECTOR` method XML description, or other objects. These are typically all included with each action message, where they have to be identified by the related key value.
      Throws:
        `java.lang.Exception` - any error.

    - #### evaluationMessage

          protected MessageInfo evaluationMessage()

      Get a newly created message from the module, representing its evaluation and result of the immediate last process.
      Returns:
        the value of evaluationMessage.