fipaos.agent.conversation
Interface Conversation

All Known Implementing Classes:
LightweightConversationImpl, ConversationImpl

public interface Conversation
extends Cloneable, DatabaseObject, Serializable

This interface represents the notion of a Conversation which is comprised of
several Message's, the order of which follow a certain protocol
(e.g. FIPA-Request). The methods it provides allow retrieval of information
about the conversation.


Field Summary
 final static intAGENT_ACTION_REQ
          Conversation requires Agent interaction - This is generally the state
whenever the latest message in the conversation is from an Agent other
than the owner of the Conversation object, and the conversation update
hasn't been propogated to a ConversationListener
 final static intCONVERSATION_END
          Conversation has ended - This state is entered once the last message in
the conversation has been received, or the last message recieved has timed-out.
 final static intNO_AGENT_ACTION_REQ
          Conversation requires no Agent interaction - This is generally the state
whenever the last message that was part of a conversation was sent by
the Agent that owns this Conversation object, or a conversation update
has already been forwarded to the ConversationListener for the latest
update
 final static intWAIT_BEFORE_END
          Wait for response before ending conversation - Indicates that a reply-by
time was specified on the last message in the conversation, so this
is a special case of NO_AGENT_ACTION_REQ.

Method Summary
 ACLgetACL(int index)
          Pass-back the latest message in this conversation
 StringgetConversationID()
          Gets the conversation ID of the conversation
 EnvelopegetEnvelope(int index)
          Get the Envelope of the latest message received
 ACLgetFilledInACL()
          Method to produce a filled in ACL - e.g.
 intgetLatestMessageIndex()
          Pass back the index of the latest message in the conversation
 ListgetNextMessages()
          Method to discover what types of messages can be sent next
 ListgetNextPerformatives()
          Method to discover what performatives are allowed next in the protocol.
 StringgetProtocol()
          Method to get the protocol this Conversation is following
 StringgetSender(int index)
          Gets the sender of the message at the specified index
 AgentIDgetSenderAID(int index)
          Gets the sender of the message at the specified index
 intgetState()
          Method to retrieve the state of the conversation (e.g.
 longgetTimeOut()
          Method to get the time at which the last message will time out
 longgetTimeStamp(int index)
          Method to retrieve the time stamp of a given message

Methods inherited from interface fipaos.skill.db.DatabaseObject
getObjectID

Field Detail

AGENT_ACTION_REQ

public final static int AGENT_ACTION_REQ
Conversation requires Agent interaction - This is generally the state
whenever the latest message in the conversation is from an Agent other
than the owner of the Conversation object, and the conversation update
hasn't been propogated to a ConversationListener

CONVERSATION_END

public final static int CONVERSATION_END
Conversation has ended - This state is entered once the last message in
the conversation has been received, or the last message recieved has timed-out.
In the former case, the last message could either have
a performative that was defined in the protocol as an end-point, or
a "not-understood" was received, indicating the implicit end of the conversation

NO_AGENT_ACTION_REQ

public final static int NO_AGENT_ACTION_REQ
Conversation requires no Agent interaction - This is generally the state
whenever the last message that was part of a conversation was sent by
the Agent that owns this Conversation object, or a conversation update
has already been forwarded to the ConversationListener for the latest
update

WAIT_BEFORE_END

public final static int WAIT_BEFORE_END
Wait for response before ending conversation - Indicates that a reply-by
time was specified on the last message in the conversation, so this
is a special case of NO_AGENT_ACTION_REQ. Generally if the timeout expires
the Conversation will move into the CONVERSATION_END state
Method Detail

getACL

public ACL getACL(int index)
Pass-back the latest message in this conversation

getConversationID

public String getConversationID()
Gets the conversation ID of the conversation
Returns: The String representation of the Conversation's
ID, or null if one has not been assigned

getEnvelope

public Envelope getEnvelope(int index)
Get the Envelope of the latest message received

getFilledInACL

public ACL getFilledInACL()
Method to produce a filled in ACL - e.g. sender, conversation ID and
protocol fields will be set appropriately for the conversation
Returns: The filled in ACL object

getLatestMessageIndex

public int getLatestMessageIndex()
Pass back the index of the latest message in the conversation
Returns: Index of the latest message, or -1 if there are no messages
in this conversation

getNextMessages

public List getNextMessages()
Method to discover what types of messages can be sent next
Returns: A list of possible ACLMessage's which could be sent next, or
return an empty list if none can

getNextPerformatives

public List getNextPerformatives()
Method to discover what performatives are allowed next in the protocol.
Returns: A list of performatives, or an empty list if no messages can be sent next

getProtocol

public String getProtocol()
Method to get the protocol this Conversation is following

getSender

public String getSender(int index)
Gets the sender of the message at the specified index
Parameters:
index - The index of the message to retrieve
Returns: The name of the sender of the message at the given index, or
null if no such message exists

getSenderAID

public AgentID getSenderAID(int index)
Gets the sender of the message at the specified index
Parameters:
index - The index of the message to retrieve
Returns: The id of the sender of the message at the given index, or
null if no such message exists

getState

public int getState()
Method to retrieve the state of the conversation (e.g. does the conversation
require agent input)
Returns: One of NO_AGENT_ACTION_REQ, AGENT_ACTION_REQ or CONVERSATION_END

getTimeOut

public long getTimeOut()
Method to get the time at which the last message will time out
Returns: The time the message will time out in milliseconds since 1/1/1970 0:00 GMT,
or -1 if there is no timeout associated with the last message

getTimeStamp

public long getTimeStamp(int index)
Method to retrieve the time stamp of a given message
Parameters:
index - The index of the message for which to retrieve the timestamp
Returns: The time the message was added in milliseconds since 1/1/1970 0:00 GMT,
or -1 if no such message exists