org.licas.autonomic

## Class MessageQueue

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

-     public class MessageQueue
      extends java.lang.Object

  This class stores lists of messages for processing by the system. The messages can be accessed in an ordered manner or based on communication ID. When an autonomic component receives a message, it can put it onto a message queue if it is wrapped inside of an `AutonomicManager`. The `Auto.messageReply(...)` method will do this automatically. The manager then has full access to all messages and can use its control loop to process them and try to detect errors or faults.
  Author:
    Kieran Greer

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `MessageQueue()` Create a new instance of MessageQueue

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addMessage(MessageInfo messageInfo)` Add a new message to the list.
    `protected MessageInfo` | `copyConversationMessage(java.lang.String commID, int position)` Get a copy of the specified message in the specified conversation.
    `protected java.util.ArrayList<MessageInfo>` | `copyMessageInterval(long startTime, long endTime)` Get a copy of all messages time stamped between the two time intervals.
    `MessageInfo` | `getAndRemoveMessageAt(int index)` Get the message at position `index` in the queue and remove the message from all queues.
    `MessageInfo` | `getAndRemoveNextMessage()` Get the next message in the queue and remove the message from all queues.
    `MessageInfo` | `getAndRemoveNextMessageName(java.lang.String methodName)` Get the next message in the queue relating to a particular method name.
    `MessageInfo` | `getAndRemoveNextMessageTime(long timeStamp)` Get the next message in the queue relating to a particular time interval.
    `MessageInfo` | `getAndRemoveNextMessageTime(long startTimeStamp, long endTimeStamp)` Get the next message in the queue relating to a particular time interval.
    `protected java.util.ArrayList<java.lang.String>` | `getCommIDs()` Get the lit of current communication IDs.
    `protected int` | `getConversationLength(java.lang.String commID)` Get the number of messages related to a particular communication ID.
    `MessageInfo` | `getMessageAt(int index)` Get the message at position `index` in the queue, but keep the message in all queues.
    `MessageInfo` | `getNextMessage()` Get the next message in the queue, but keep the message in all queues.
    `boolean` | `isEMpty()` Return true if the message queue is empty, meaning no message in the queue.
    `int` | `queueSize()` Get the size of the message queue.
    `void` | `removeAllMessages(java.lang.String commID)` Remove all messages, from both lists, with the specified communication ID.
    `protected void` | `returnLastMessage(MessageInfo nextMessage)` Return the message to the start of the message queue and update all other message lists.

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

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

- - ### Constructor Detail

    - #### MessageQueue

          public MessageQueue()

      Create a new instance of MessageQueue

  - ### Method Detail

    - #### getCommIDs

          protected java.util.ArrayList<java.lang.String> getCommIDs()

      Get the lit of current communication IDs.
      Returns:
        the key list for the messageComms structure.

    - #### addMessage

          public void addMessage(MessageInfo messageInfo)

      Add a new message to the list. The message is added to the end of the message queue and also the related conversation.
      Parameters:
        `messageInfo` - a full `MessageInfo` description. The unique communication ID is required.

    - #### isEMpty

          public boolean isEMpty()

      Return true if the message queue is empty, meaning no message in the queue.
      Returns:
        true if empty.

    - #### queueSize

          public int queueSize()

      Get the size of the message queue.
      Returns:
        the size of messageQueue.

    - #### getMessageAt

          public MessageInfo getMessageAt(int index)

      Get the message at position `index` in the queue, but keep the message in all queues.
      Parameters:
        `index` - index of the message to retrieve.
      Returns:
        the message at position `index` in the queue, or null if out of range.

    - #### getNextMessage

          public MessageInfo getNextMessage()

      Get the next message in the queue, but keep the message in all queues.
      Returns:
        the next message in the queue.

    - #### getAndRemoveMessageAt

          public MessageInfo getAndRemoveMessageAt(int index)

      Get the message at position `index` in the queue and remove the message from all queues.
      Parameters:
        `index` - index of the message to retrieve.
      Returns:
        the message at position `index` in the queue, or null if out of range.

    - #### getAndRemoveNextMessage

          public MessageInfo getAndRemoveNextMessage()

      Get the next message in the queue and remove the message from all queues.
      Returns:
        the next message in the queue.

    - #### getAndRemoveNextMessageTime

          public MessageInfo getAndRemoveNextMessageTime(long startTimeStamp,
                                                         long endTimeStamp)

      Get the next message in the queue relating to a particular time interval. Return the first message that lies inside the time interval. This also automatically removes the message from all queues.
      Parameters:
        `startTimeStamp` - the start time interval for the message.
        `endTimeStamp` - the end time interval for the message.
      Returns:
        the next message in the queue.

    - #### getAndRemoveNextMessageTime

          public MessageInfo getAndRemoveNextMessageTime(long timeStamp)

      Get the next message in the queue relating to a particular time interval. This is an exact time stamp, probably relating to only one message. This also automatically removes the message from all queues.
      Parameters:
        `timeStamp` - the exact timestamp for the message.
      Returns:
        the next message in the queue.

    - #### getAndRemoveNextMessageName

          public MessageInfo getAndRemoveNextMessageName(java.lang.String methodName)

      Get the next message in the queue relating to a particular method name. This must be a `MethodInfo` object and it also automatically removes the message from all queues.
      Parameters:
        `methodName` - the name of the method to retrieve.
      Returns:
        the next message in the queue with the specified name.

    - #### removeAllMessages

          public void removeAllMessages(java.lang.String commID)

      Remove all messages, from both lists, with the specified communication ID.
      Parameters:
        `commID` - the message communication ID.

    - #### returnLastMessage

          protected void returnLastMessage(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.

    - #### getConversationLength

          protected int getConversationLength(java.lang.String commID)

      Get the number of messages related to a particular communication ID.
      Parameters:
        `commID` - the communication ID.
      Returns:
        the number of messages in the related message queue, or 0 if there are no messages.

    - #### copyConversationMessage

          protected MessageInfo copyConversationMessage(java.lang.String commID,
                                                        int position)

      Get a copy of the specified message in the specified conversation. This returns a copy that does not change the original message queue, but the message itself can be changed by the calling program. Use `getAndRemoveMessage` to retrieve the message and also remove it from the queue.
      Parameters:
        `commID` - the communication ID.
        `position` - the position of the message in the communication queue.
      Returns:
        a copy of the specified message.

    - #### copyMessageInterval

          protected java.util.ArrayList<MessageInfo> copyMessageInterval(long startTime,
                                                                         long endTime)

      Get a copy of all messages time stamped between the two time intervals. This returns a copy that does not change the original message queue, but the message itself can be changed by the calling program. Use `getAndRemoveMessage` to retrieve the message and also remove it from the queue.
      Parameters:
        `startTime` - the start of the time interval.
        `endTime` - the end of the time interval.
      Returns:
        a copy of the specified message.