Agent System POND 1.2 (28.2.2002)

PkgAgentSystem
Class Conversation

java.lang.Object
  |
  +--PkgAgentSystem.Conversation
All Implemented Interfaces:
Cloneable, Serializable
Direct Known Subclasses:
ExperienceExchangeConversation, TerminateAgentConversation

public abstract class Conversation
extends Object
implements Serializable, Cloneable

A conversation with a single or any number of other agents. Each time a message is received, the method handleMessage is called, which should handle the incoming message (and probably send a message in return or end the conversation). When a conversation is started, this method is called once with the parameter null.

Subclasses must be declared as public classes and must declare public final static long conversationTypeID=.... Only the value may and must change (unique values required, at least for all conversations a single agents knows and uses). Otherwise the type of the conversation cannot be retrieved by this class.

Incoming messages starting a new conversation are handled by cloning the prototype. It is therefore necessary to override clone() if structured members are contained in the conversation.

Version:
1.0, 1.7.2000
Author:
Michael Sonntag
See Also:
AgentBase, Serialized Form

Field Summary
static long conversationTypeID
          The ID for this type of conversation.
protected  boolean uniquePartner
          If true, this conversation has only a single partner.
 
Constructor Summary
protected Conversation(AgentBase myAgent)
          Creates a new conversation of a certain agent.
protected Conversation(AgentBase myAgent, AgentIdentity counterpart)
          Creates a new conversation of a certain agent with another agent.
 
Method Summary
protected  void broadcastMessage(BroadcastMessage msg)
          Sends a broadcast to all other local agents.
protected  void endConversation()
          Stops this conversation.
protected  void fillInConversationData(MessageType msg)
          Fills in the necessary data if it is missing and otherwise verifies it.
protected  AgentBase getAgent()
          Returns the agent this conversation belongs to.
 long getConversationTypeID()
           
protected  long getCounterpartConvID()
          Returns the conversation ID of this conversation for the counterpart agent.
protected  AgentIdentity getCounterpartIdentity()
          Returns the identity of the counterpart agent.
 long getOwnConvID()
          Returns the conversation ID of this conversation for this agent.
protected  boolean handleMessage(MessageType msg)
          Handle the message.
protected  boolean isInitiator()
          Returns true if this agent initiated the conversation.
 boolean isRunning()
          Check whether this conversation is currently active.
 Conversation newConversation(AgentIdentity counterpart)
          Creates a new conversation based on this one through cloning.
 Conversation newConversation(AgentIdentity counterpart, boolean asInitiator)
          Creates a new conversation based on this one through cloning.
protected  void sendMessage(Message msg)
          Sends a message to another agent.
protected  void setCounterpartConvID(long counterpartConvID)
          Sets the conversation ID of this conversation for the counterpart agent.
protected  void setCounterpartIdentity(AgentIdentity other)
          Sets the identity of the counterpart agent.
protected  void setInitiator(boolean asInitiator)
          Sets this instance as the initiator of the conversation.
protected  void setOwnConvID(long newID)
          Modifies our own serial ID for this conversation.
protected  void setShouldArchive(boolean shouldArchive)
          Sets the archivation status for this conversation.
protected  boolean shouldArchive()
          Returns whether this conversation should be archived after termination or not.
protected  boolean startConversation()
          Starts this conversation.
 void waitEnded()
          Blocks until this conversation has ended (endConversation() was called).
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

uniquePartner

protected boolean uniquePartner
If true, this conversation has only a single partner.

conversationTypeID

public static final long conversationTypeID
The ID for this type of conversation.

A identical field MUST be declared in EACH subclass!

Only the value may and must change (unique values required, at least for all conversations a single agents knows and uses).
Constructor Detail

Conversation

protected Conversation(AgentBase myAgent)
Creates a new conversation of a certain agent. No counterpart is set, the current agent is not the initiator and it will not be archived after terminating.
Parameters:
serialID - the ID of this conversation
myAgent - the agent this conversation belongs to

Conversation

protected Conversation(AgentBase myAgent,
                       AgentIdentity counterpart)
Creates a new conversation of a certain agent with another agent. The current agent is the initiator and it will not be archived after terminating.
Parameters:
serialID - the ID of this conversation
myAgent - the agent this conversation belongs to
couterpart - the other agent with which this conversation takes place
Method Detail

setInitiator

protected void setInitiator(boolean asInitiator)
Sets this instance as the initiator of the conversation.

getAgent

protected AgentBase getAgent()
Returns the agent this conversation belongs to.
Returns:
the agent of this conversation

handleMessage

protected boolean handleMessage(MessageType msg)
Handle the message. Must be overridden in subclasses, which provide their own protocol. Subclasses must call this implementation first before doing their own handling.
Parameters:
msg - the message to handle
Returns:
true if this message was handled.

getOwnConvID

public long getOwnConvID()
Returns the conversation ID of this conversation for this agent.
Returns:
the local conversation ID

setOwnConvID

protected void setOwnConvID(long newID)
Modifies our own serial ID for this conversation. Should only be called under special circumstances (Needed e. g. for sub-protocols).
Parameters:
newID - the new ID for this conversation
See Also:
getOwnConvID()

getCounterpartConvID

protected long getCounterpartConvID()
Returns the conversation ID of this conversation for the counterpart agent.
Returns:
the remote conversation ID

setCounterpartConvID

protected void setCounterpartConvID(long counterpartConvID)
Sets the conversation ID of this conversation for the counterpart agent. Only possible if the counterpart conversation ID is not already set.
Parameters:
counterpartConvID - the conversation ID of the other agent
See Also:
getCounterpartConvID()

setCounterpartIdentity

protected void setCounterpartIdentity(AgentIdentity other)
Sets the identity of the counterpart agent. Only possible if the counterpart is not already set.
Parameters:
other - the identity of the remote agent
See Also:
getCounterpartIdentity()

getCounterpartIdentity

protected AgentIdentity getCounterpartIdentity()
Returns the identity of the counterpart agent.
Returns:
the identity of the remote agent

newConversation

public Conversation newConversation(AgentIdentity counterpart)
Creates a new conversation based on this one through cloning.
Parameters:
counterpart - the counterpart of the conversation (might be null)
Returns:
a new conversation with the provided ID and counterpart

newConversation

public Conversation newConversation(AgentIdentity counterpart,
                                    boolean asInitiator)
Creates a new conversation based on this one through cloning.
Parameters:
counterpart - the counterpart of the conversation (might be null)
asInitiator - whether we are the initiator or not
Returns:
a new conversation with the provided ID and counterpart

startConversation

protected boolean startConversation()
Starts this conversation.
Returns:
true on any error (return value from handleMessage(null))

endConversation

protected void endConversation()
Stops this conversation. If it is marked for archiving, it is added to the conversation archive of the agent. All threads waiting for the conversation to terminate are notified.

shouldArchive

protected boolean shouldArchive()
Returns whether this conversation should be archived after termination or not.
Returns:
true if the conversation should be archived

setShouldArchive

protected void setShouldArchive(boolean shouldArchive)
Sets the archivation status for this conversation.
Parameters:
shouldArchive - if true this conversation will be archived after termination

sendMessage

protected void sendMessage(Message msg)
                    throws MessageException
Sends a message to another agent.
Parameters:
msg - the message to send

broadcastMessage

protected void broadcastMessage(BroadcastMessage msg)
                         throws MessageException
Sends a broadcast to all other local agents.
Parameters:
msg - the message to send

isRunning

public boolean isRunning()
Check whether this conversation is currently active.
Returns:
true if this conversation has been started but has not yet ended

waitEnded

public void waitEnded()
Blocks until this conversation has ended (endConversation() was called). Can NOT be interrupted!

isInitiator

protected boolean isInitiator()
Returns true if this agent initiated the conversation.
Returns:
true if this agent initiated the conversation

getConversationTypeID

public final long getConversationTypeID()

fillInConversationData

protected void fillInConversationData(MessageType msg)
Fills in the necessary data if it is missing and otherwise verifies it. The sender must be the agent of this conversation. If this conversation has a counterpart, the recipient of the message must be this agent and the conversation ID of the counterpart has to be the same as in the message. The srcConversation ID must be the one of this conversation.

Agent System POND 1.2 (28.2.2002)

Submit a bug

Copyright 2001,2002 Michael Sonntag & Institute for Information Processing and Microprocessor Technology (FIM), Johannes-Kepler-University Linz, Altenbergerstr. 69, A-4040 Linz, Austria.