org.licas.autonomic

## Class AutonomicManager

- java.lang.Object
- - java.lang.Thread
  - - org.licas.module.LicasModule
    - - org.licas.module.FrameworkModule
      - - org.licas.module.ServiceModule
        - - org.licas.ServiceWrapper
          - - org.licas.autonomic.AutonomicManager

- All Implemented Interfaces:
    java.lang.Runnable, ServiceDef, ServiceWrapperDef
  Direct Known Subclasses:
    AutonomicManagerDefault

      public abstract class AutonomicManager
      extends ServiceWrapper

  This is the abstract base class that should be extended to implement an autonomic manager. The autonomic manager can be used to allow a service to autonomously (or independently) monitor itself, with regard to errors in its interaction with its environment. This base class defines the methods that can be used to implement an autonomic manager with a self-control loop and a message queue. The modules that process the information then implement the `AM_Module` interface. In this case, separate modules should be implemented to monitor, analyze, plan, or execute the plan, based on the input that each module receives. Each module should be controlled by a policy that can be entered as an XML document. On receiving its input, the module will process the information based on the policy and return a `MessageInfo` object with the appropriate reply. If all of the modules implement this interface then this process will be consistent through the whole control loop.
  Author:
    Kieran Greer

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class java.lang.Thread

      `java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected AM_Module` | `analyzer` Analysis module.
    `protected AutoEngine` | `autoEngine`
    `protected static boolean` | `CONVERSATIONEXISTS`
    `protected AM_Module` | `executor` Execution module.
    `protected boolean` | `isConfigured` Set to true when this manager has been configured.
    `protected MessageQueue` | `messageQueue` List of messages received by this manager.
    `protected AM_Module` | `monitor` Monitor module.
    `protected static boolean` | `NEWCONVERSATION`
    `protected AM_Module` | `planner` Planner module.
    `protected MessageQueue` | `quarantineQueue` List of messages quarantined by this manager.

    - ### Fields inherited from class org.licas.ServiceWrapper

      `metrics, setStructures`

    - ### Fields inherited from class org.licas.module.ServiceModule

      `shutDown`

    - ### Fields inherited from class org.licas.module.FrameworkModule

      `passwordHandler, service, serviceType`

    - ### Fields inherited from class org.licas.module.LicasModule

      `jarFile, syncOn, uuid`

    - ### Fields inherited from class java.lang.Thread

      `MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AutonomicManager(Auto theService)` Creates a new instance of AutonomicManager.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `addManagerModule(java.lang.String moduleType, java.lang.String moduleClass, java.util.ArrayList<java.lang.Object> params, java.util.ArrayList<java.lang.String> theJarUris)` Add a new module to the manager - monitor, analyze, plan or execute.
    `void` | `addMessage(MessageInfo messageInfo, java.lang.String theAdminKey)` Add a message to the queue for a particular communication thread.
    `abstract void` | `addPolicy(java.lang.String policyType, org.licas_xml.abs.Element document)` Add a new policy to the auto manager.
    `protected boolean` | `checkCommID(java.lang.String commID, java.lang.Object clientURI, boolean tryNew)` Check if the communication ID can be added as new, or if it already exists.
    `protected java.lang.Object` | `getClientURI(java.lang.String communicationID)` Get the client URI associated with a communication ID.
    `MessageQueue` | `getMessageQueue(java.lang.String theAdminKey)` Get the message queue.
    `MessageInfo` | `getNextMessage(java.lang.String theAdminKey, boolean remove)` Get the next message in the queue.
    `MessageQueue` | `getQuarantineMessageQueue(java.lang.String theAdminKey)` Get the quarantined message queue.
    `void` | `interrupt()` This method is re-implemented here to allow the thread to be shut down.
    `boolean` | `isAuto()` Return true if the stored object is derived from the licas `Auto` object.
    `boolean` | `isService()` Return true if the stored object is derived from the licas `Service` object.
    `abstract void` | `monitor(MessageInfo theMessage, java.lang.String theAdminKey)` Monitor the first message of a conversation to check for irregular values.
    `protected abstract void` | `monitorMessage(MessageInfo theMessage, java.lang.String theAdminKey)` Monitor a message using a MAPE control loop.
    `protected void` | `removeCommID(java.lang.String communicationID)` Remove the communication ID reference from the Service, or stored `obj` reference.
    `void` | `returnLastMessage(java.lang.String theAdminKey, MessageInfo nextMessage)` Return the message to the start of the message queue and update all other message lists.
    `void` | `setConfigured()` Call to indicate that the manager has now been configured
    `boolean` | `storesLegacy()` Return true if the stored object is legacy code, false if a licas service.

    - ### Methods inherited from class org.licas.ServiceWrapper

      `addCommunicationID, addMetrics, canAccess, canAccess, canAccess, canAccessTemp, copyFromService, copyToService, execute, getDescription, getFullPath, getMetrics, getObjClass, getObjService, getPassword, getPassword, getPassword, getService, getService, getServiceGrade, getWorkInfo, interrupt, invokeObj, reflectionMethods, run, setObjService, setParent, setServerPassword, setServiceGrade, threadAliveState`

    - ### Methods inherited from class org.licas.module.ServiceModule

      `getShutDown, setShutDown, setShutDown`

    - ### Methods inherited from class org.licas.module.FrameworkModule

      `getPasswordHandler, getPasswordHandler, getServerPassword, getServicePassword, getServiceType, isAdminKey, setServiceDetails, setServiceType`

    - ### Methods inherited from class org.licas.module.LicasModule

      `getJarFile, getUUID, loadObject, setJarFile, setUUID`

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

      `activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield`

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

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

    - ### Methods inherited from interface org.licas.def.ServiceDef

      `getServiceType, getUUID, isAdminKey, setJarFile, setServiceType, setUUID`

- - ### Field Detail

    - #### NEWCONVERSATION

          protected static boolean NEWCONVERSATION

    - #### CONVERSATIONEXISTS

          protected static boolean CONVERSATIONEXISTS

    - #### monitor

          protected AM_Module monitor

      Monitor module.

    - #### analyzer

          protected AM_Module analyzer

      Analysis module.

    - #### planner

          protected AM_Module planner

      Planner module.

    - #### executor

          protected AM_Module executor

      Execution module.

    - #### messageQueue

          protected MessageQueue messageQueue

      List of messages received by this manager.

    - #### quarantineQueue

          protected MessageQueue quarantineQueue

      List of messages quarantined by this manager.

    - #### autoEngine

          protected AutoEngine autoEngine

    - #### isConfigured

          protected boolean isConfigured

      Set to true when this manager has been configured.

  - ### Constructor Detail

    - #### AutonomicManager

          public AutonomicManager(Auto theService)
                           throws java.lang.Exception

      Creates a new instance of AutonomicManager.
      Parameters:
        `theService` - the service to monitor.
      Throws:
        `java.lang.Exception` - any error.

  - ### Method Detail

    - #### monitor

          public abstract void monitor(MessageInfo theMessage,
                                       java.lang.String theAdminKey)
                                throws PasswordException,
                                       LicasException,
                                       java.lang.Exception

      Monitor the first message of a conversation to check for irregular values. The message must not be recognised locally with a stored comm id.
      Parameters:
        `theMessage` - the message that the service has produced / received.
        `theAdminKey` - the admin key for the parent service.
      Throws:
        `PasswordException` - if the admin key is incorrect.
        `LicasException` - if the communication ID is not part of a current conversation.
        `java.lang.Exception` - any error.

    - #### monitorMessage

          protected abstract void monitorMessage(MessageInfo theMessage,
                                                 java.lang.String theAdminKey)
                                          throws PasswordException,
                                                 LicasException,
                                                 java.lang.Exception

      Monitor a message using a MAPE control loop. This occurs after the message has been added to the queue and retrieved for processing. In this case, the message must be recognised as part of an existing conversation, from its comm ID.
      Parameters:
        `theMessage` - the message that the service has produced / received.
        `theAdminKey` - the admin key for the parent service.
      Throws:
        `PasswordException` - if the admin key is incorrect.
        `LicasException` - if the communication ID is not part of a current conversation.
        `java.lang.Exception` - any error.

    - #### addManagerModule

          public abstract void addManagerModule(java.lang.String moduleType,
                                                java.lang.String moduleClass,
                                                java.util.ArrayList<java.lang.Object> params,
                                                java.util.ArrayList<java.lang.String> theJarUris)
                                         throws java.lang.Exception

      Add a new module to the manager - monitor, analyze, plan or execute.
      Parameters:
        `moduleType` - the type of module.
        `moduleClass` - the class name of the module to be loaded.
        `params` - initialisation parameters.
        `theJarUris` - uris from which the remote object can be loaded, only if needed.
      Throws:
        `java.lang.Exception` - any error.

    - #### addPolicy

          public abstract void addPolicy(java.lang.String policyType,
                                         org.licas_xml.abs.Element document)
                                  throws java.lang.Exception

      Add a new policy to the auto manager.
      Parameters:
        `policyType` - the type of policy.
        `document` - the policy document.
      Throws:
        `java.lang.Exception` - any error.

    - #### isService

          public boolean isService()

      Return true if the stored object is derived from the licas `Service` object.
      Returns:
        true in this case.

    - #### isAuto

          public boolean isAuto()

      Return true if the stored object is derived from the licas `Auto` object.
      Returns:
        true in this case.

    - #### storesLegacy

          public boolean storesLegacy()

      Return true if the stored object is legacy code, false if a licas service.
      Specified by:
        `storesLegacy` in interface `ServiceWrapperDef`
      Overrides:
        `storesLegacy` in class `ServiceWrapper`
      Returns:
        false here.

    - #### addMessage

          public void addMessage(MessageInfo messageInfo,
                                 java.lang.String theAdminKey)
                          throws PasswordException,
                                 LicasException,
                                 java.lang.Exception

      Add a message to the queue for a particular communication thread. In this case, the message must be recognised as part of an existing conversation, from its comm ID. If the comm ID is `null`, then an exception is thrown. If it new, then the message is added to a quarantine list and an exception is thrown.
      Parameters:
        `messageInfo` - the message to add.
        `theAdminKey` - the admin key for the parent service.
      Throws:
        `PasswordException` - if the admin key is incorrect.
        `LicasException` - if the comm ID is not already stored, as it is then not part of a conversation.
        `java.lang.Exception` - any error.

    - #### getNextMessage

          public MessageInfo getNextMessage(java.lang.String theAdminKey,
                                            boolean remove)

      Get the next message in the queue.
      Parameters:
        `theAdminKey` - the admin key for the parent service.
        `remove` - if true also remove the message.
      Returns:
        the first message in the queue.

    - #### returnLastMessage

          public void returnLastMessage(java.lang.String theAdminKey,
                                        MessageInfo nextMessage)

      Return the message to the start of the message queue and update all other message lists.
      Parameters:
        `nextMessage` - the message to add again.
        `theAdminKey` - the service's service key.

    - #### getMessageQueue

          public MessageQueue getMessageQueue(java.lang.String theAdminKey)

      Get the message queue.
      Parameters:
        `theAdminKey` - the admin key for the parent service.
      Returns:
        the message queue for the service of this manager.

    - #### getQuarantineMessageQueue

          public MessageQueue getQuarantineMessageQueue(java.lang.String theAdminKey)

      Get the quarantined message queue.
      Parameters:
        `theAdminKey` - the admin key for the parent service.
      Returns:
        the quarantined message queue for the service of this manager.

    - #### getClientURI

          protected java.lang.Object getClientURI(java.lang.String communicationID)

      Get the client URI associated with a communication ID.
      Parameters:
        `communicationID` - the communication ID.
      Returns:
        the clientURI stored in the messageinfo object.

    - #### removeCommID

          protected void removeCommID(java.lang.String communicationID)

      Remove the communication ID reference from the Service, or stored `obj` reference.
      Parameters:
        `communicationID` - the communication ID.

    - #### checkCommID

          protected boolean checkCommID(java.lang.String commID,
                                        java.lang.Object clientURI,
                                        boolean tryNew)
                                 throws java.lang.Exception

      Check if the communication ID can be added as new, or if it already exists. The `tryNew` parameter sets the condition with the following rules:
      1. If true then try to add the conversation key as new and throw an exception if it already exists.
      2. If false then check that the conversation key is part of an existing conversation and throw an exception if it is new.
      3. The exception to this is a general 'service-level' ID that ends with `Service` or `Fault` and is allowed for any case.
      Parameters:
        `commID` - the communication ID to check.
        `clientURI` - the client URI representation.
        `tryNew` - true if check for new entry, or false for an existing conversation.
      Returns:
        true if condition is OK, false otherwise.
      Throws:
        `java.lang.Exception` - any error.

    - #### setConfigured

          public void setConfigured()

      Call to indicate that the manager has now been configured

    - #### interrupt

          public void interrupt()

      This method is re-implemented here to allow the thread to be shut down.
      Overrides:
        `interrupt` in class `java.lang.Thread`