PkgAgentSystem
Class Conversation

java.lang.Object
  |
  +--PkgAgentSystem.Conversation

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.

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 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(Message 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.
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	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

getAgent

protected AgentBase getAgent()

Returns the agent this conversation belongs to.

Returns:

the agent of this conversation

handleMessage

protected boolean handleMessage(Message 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

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

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

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. 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.

Parameters:

msg - the message to send

broadcastMessage

protected void broadcastMessage(BroadcastMessage msg)
                         throws MessageException

Sends a broadcast to all other local agents. The sender must be the agent of this conversation. The srcConversation ID must be the one of this conversation.

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()