    All Packages  Class Hierarchy  This Package  Previous  Next  Index

# Class JavaAgent.agent.MessageHandler

    java.lang.Object
       |
       +----JavaAgent.agent.MessageHandler

public class MessageHandler
extends Object

Object which handles all message transmissions for an Agent, maintains the link to the CommInterface. When the agent makes a call to sendMessage(), the message is put in the outgoing buffer. Similarly, when the CommInterface receives a message, it is put in the incoming buffer. Both the outgoing and incoming buffers are instances of MessageBuffer, which provides for synchronized access to the stored messages. Instances of TransmitterThread and ReceiverThread pull messages out of the buffers for either transmission by the CommInterface or processing.

Message transmission is normally serialized using the pending_transmission flag (i.e. receipt of transmission for each message is secured before the next message is sent). The releasePending() method can be called to allow for non-serialized message transmission, this done with address retrieval (the current message must release the pending flag so that the address retrieval message can actually be sent).

Message processing is not serialized: as each message is pulled off the buffer a separate thread is started to process the message. Serialized processing can be accomplished by rewriting the ReceiverThread class. When a message is finally sent it is put in a rotating transmitted messages buffer, the same is done for received messages.

Copyright (c) 1995, H. Robert Frost, Stanford University. All rights reserved.

Copyright (c) 1996, H. Robert Frost, Enterprise Integration Technologies, Inc. All rights reserved.

RESTRICTED RIGHTS LEGEND: Use, duplication or disclosure by the Government is subject to restrictions as set forth in subparagraph(c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and in similar clauses in the FAR and NASA FAR supplement.

This software is bound by the terms and conditions listed in the attached LICENSE file.

##

comm
  Mechanism through which messages are sent and received.
current_message
  KQMLmessage which is currently being interpreted, or null if no message is being interpreted.
incoming
  Buffer for received messages waiting to be processed.
last_message
  Is this the last message which needs to be send before termination?
messages_in
  Storage for received messages.
messages_out
  Storage for transmitted messages.
outgoing
  Buffer for messages waiting to be sent.
output_buffer
  Buffer for messages waiting to be sent.
parent
  Agent whose Resources are managed.
receiver
  Thread which pulls messages from the incoming MessageBuffer and calls the specified Interpreter object for interpretation.
transmission_pending
  Is there a message currently being sent?
transmitter
  Thread which pulls messages from the outgoing MessageBuffer and calls the CommInterface for transmission.

##

MessageHandler(Agent)
  Creates a new MessageHandler.

##

addSystemMessage(String)
  Sends a system message to the agent.
addSystemMessage(String, Exception)
  Sends a system message to the agent w/ exception.
currentMessage()
  Returns the message currently being interpreted, returns null if no message is being interpreted.
getReceivedMessages()
  Returns a Vector of received messages, if more than MESSAGE_STORAGE number have been received, only returns the most recent.
getSentMessages()
  Returns a Vector of transmitted messages, if more than MESSAGE_STORAGE number have been sent, only returns the most recent.
initiateTermination()
  Called when the executable class which contains the Agent terminates.
interpretingMessage()
  Returns true if the Agent is currently interpreting a message.
interpretMessage(KQMLmessage)
  Called by the ReceiverThread to interpret a specific message.
invalidateAddress()
  Called when the current address has been invalidated.
isPending()
  This method will block until there is no longer a transmission pending.
receiveMessage(KQMLmessage)
  Called by the associated CommInterface when a KQMLmessage is received.
releasePending()
  Sets the transmission_pending flag to false.
resourceChanged(String)
  Called when a non-Resource object has changed.
saveMessage(Vector, KQMLmessage)
  Saves the message in the given storage.
sendMessage(KQMLmessage)
  Called to send a given KQMLmessage.
sendResult(KQMLmessage, boolean, String)
  Called by the associated CommInterface to report the success of a sendMessage call.
sendToComm(KQMLmessage)
  Called by the TransmitterThread to send a message.
setComm(CommInterface)
  Sets the CommInterface for the MessageHandler and creates and starts the TransmitterThread.
terminate()
  Called when the last termination message has been sent.

##

parent

     protected Agent parent

  Agent whose Resources are managed.

comm

     protected CommInterface comm

  Mechanism through which messages are sent and received. The CommInterface must be intialized and assigned in the AgentContext which contains the Agent.

outgoing

     protected MessageBuffer outgoing

  Buffer for messages waiting to be sent.

transmitter

     protected TransmitterThread transmitter

  Thread which pulls messages from the outgoing MessageBuffer and calls the CommInterface for transmission.

incoming

     protected MessageBuffer incoming

  Buffer for received messages waiting to be processed.

receiver

     protected ReceiverThread receiver

  Thread which pulls messages from the incoming MessageBuffer and calls the specified Interpreter object for interpretation.

current_message

     protected KQMLmessage current_message

  KQMLmessage which is currently being interpreted, or null if no message is being interpreted.

messages_in

     protected Vector messages_in

  Storage for received messages. Rolling buffer of size defined by MESSAGE_STORAGE. Type KQMLmessage.

messages_out

     protected Vector messages_out

  Storage for transmitted messages. Rolling buffer of size defined by MESSAGE_STORAGE. Type KQMLmessage.

output_buffer

     protected Vector output_buffer

  Buffer for messages waiting to be sent.

last_message

     protected KQMLmessage last_message

  Is this the last message which needs to be send before termination?

transmission_pending

     protected boolean transmission_pending

  Is there a message currently being sent?

##

MessageHandler

     public MessageHandler(Agent parent)

  Creates a new MessageHandler. Creates and starts the ReceiverThread.

  Parameters:
    parent - Agent which this handler represents.

##

setComm

     public void setComm(CommInterface comm)

  Sets the CommInterface for the MessageHandler and creates and starts the TransmitterThread.

  Parameters:
    comm - CommInterface which performs the low-level message transmission.

resourceChanged

     public void resourceChanged(String resource)

  Called when a non-Resource object has changed.

  Parameters:
    type - Type of resource.

addSystemMessage

     public void addSystemMessage(String message)

  Sends a system message to the agent.

  Parameters:
    message - The system message to output.

addSystemMessage

     public void addSystemMessage(String message,
                                  Exception e)

  Sends a system message to the agent w/ exception.

  Parameters:
    message - The system message to output.
    e - Exception which generated the message, may be null.

interpretingMessage

     public boolean interpretingMessage()

  Returns true if the Agent is currently interpreting a message.

  Returns:
    true if a message is being interpreted.

currentMessage

     public KQMLmessage currentMessage()

  Returns the message currently being interpreted, returns null if no message is being interpreted.

sendMessage

     public void sendMessage(KQMLmessage message)

  Called to send a given KQMLmessage. Inserts the message in the outgoing buffer.

  Parameters:
    message - The KQMLmessage to send.

sendToComm

     protected void sendToComm(KQMLmessage message)

  Called by the TransmitterThread to send a message. Calls the sendMessage() method of the CommInterface.

  Parameters:
    message - KQMLmessage to send.

saveMessage

     protected void saveMessage(Vector storage,
                                KQMLmessage message)

  Saves the message in the given storage. Only keep the most recent MESSAGE_STORAGE messages.

  Parameters:
    storage - The storage Vector.
    message - Message to save.

getSentMessages

     public Vector getSentMessages()

  Returns a Vector of transmitted messages, if more than MESSAGE_STORAGE number have been sent, only returns the most recent.

  Returns:
    Vector of KQMLmessages.

getReceivedMessages

     public Vector getReceivedMessages()

  Returns a Vector of received messages, if more than MESSAGE_STORAGE number have been received, only returns the most recent.

  Returns:
    Vector of KQMLmessages.

isPending

     public synchronized void isPending()

  This method will block until there is no longer a transmission pending.

releasePending

     public synchronized void releasePending()

  Sets the transmission_pending flag to false.

sendResult

     public void sendResult(KQMLmessage message,
                            boolean status,
                            String reason)

  Called by the associated CommInterface to report the success of a sendMessage call.

  Parameters:
    message - The KQMLmessage which the CommInterface was asked to send.
    status - True if the message transmission was successful, false if otherwise.
    reason - String with detailed reason.

receiveMessage

     public void receiveMessage(KQMLmessage message)

  Called by the associated CommInterface when a KQMLmessage is received. The message is handled based on the Interpreter for the message content. Content language is considered within the Interpreter handler.

  Parameters:
    message - The KQMLmessage which was received.

interpretMessage

     protected void interpretMessage(KQMLmessage message)

  Called by the ReceiverThread to interpret a specific message.

invalidateAddress

     public void invalidateAddress()

  Called when the current address has been invalidated. Sends an invalidate address message to the ANS.

terminate

     public void terminate()

  Called when the last termination message has been sent.

initiateTermination

     public void initiateTermination()

  Called when the executable class which contains the Agent terminates. The agent sends a remove-address message to the ANS.

    All Packages  Class Hierarchy  This Package  Previous  Next  Index