fipaos.agent.conversation.standard
Class ConversationImpl

java.lang.Object
  |
  +--fipaos.agent.conversation.standard.ConversationImpl
All Implemented Interfaces:
java.lang.Cloneable, Conversation, DatabaseObject, java.io.Serializable
Direct Known Subclasses:
FIPAAuctionDutch, FIPAAuctionEnglish, FIPABrokering, FIPAContractNet, FIPAIteratedContractNet, FIPAPropose, FIPAQuery, FIPARecruiting, FIPARequest, FIPARequestWhen, FIPASubscribe, NoProtocol, RuntimeProtocol

public abstract class ConversationImpl
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable, DatabaseObject, Conversation

This class 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, as well as validation of the protocol the conversation is following. This class cannot be instantiated directly, the static method getConversation() should be used to obtain a Conversation instance which will follow the required protocol. Protocol definitions are defined in concrete sub-classes, which map from protocol name to class name as such:

  • "fipa-request" --> protocol.FIPARequest
  • "fipa-iterated-contract-net" --> protocol.FIPAIteratedContractNet
  • The class name is relative to the package in which this object resides. The sub-class must also define a public static Object[] called __protocol which contains details of the protocol to be followed. The list should contain a list of tuples which follow this format:

    { String performative [, Object conv_state], Integer participant [, Object[] sub_nodes] }

    The performative is the type of message recieved at that part of the protocol, the conv_state is the conversation state when that performative is recieved (one of NO_AGENT_ACTION_REQ or AGENT_ACTION_REQ, and if none is given CONVERSATION_END is assumed). The participant number identifies which participant in the conversation should be sending that message (the numbers used should be consistent throughout the messages according to the protocol requirements). The sub_nodes array can contain a list of the same format to define what messages should be expected after the one defined by the current list has been received (hence the whole protocol can be defined recursively).

    See Also:
    Serialized Form

    Inner Class Summary
    static class ConversationImpl.ConversationProtocol
              Class to contain information about the protocol to be used.
     
    Field Summary
    protected  AgentID _agent_id
              Agent-id of the Agent to whom this belongs
    protected  java.lang.String _protocol
              Name of the protocol this conversation is following
    protected  ConversationImpl.ConversationProtocol _protocol_tree
              Protocol that conversations of this type should follow (tree like structure for quick access)
    static int AGENT_ACTION_REQ
              Conversation requires Agent interaction
    static int CONVERSATION_END
              Conversation has ended
    static int NO_AGENT_ACTION_REQ
              Conversation requires no Agent interaction
    static int WAIT_BEFORE_END
              Wait for response before ending conversation
     
    Constructor Summary
    protected ConversationImpl()
              Generalised constructor
     
    Method Summary
     void addMessage(Message msg)
              Method to add a message to the conversation - sets conversation state to updated as well.
     java.lang.Object clone()
              Clone method to make duplicates of this Conversation object
     ACL getACL(int index)
              Pass-back the latest message in this conversation
    static ConversationImpl getConversation(java.lang.String protocol, AgentID agent_name)
              Method to dynamically load a Conversation instance which follows the given protocol and belongs to the given Agent
    static ConversationImpl getConversation(java.lang.String protocol, java.lang.String agent_name)
              Method to dynamically load a Conversation instance which follows the given protocol and belongs to the given Agent
     java.lang.String getConversationID()
              Gets the conversation ID of the conversation
     Envelope getEnvelope(int index)
              Get the Envelope of the latest message received
     ACL getFilledInACL()
              Method to produce a filled in ACL - e.g.
     int getLatestMessageIndex()
              Pass back the index of the latest message in the conversation
     ACLMessage getMessage(int index)
              Deprecated. The ACLMessage object is no longer supported - please use the getACL() and getEnvelope() methods instead
     java.util.List getNextMessages()
              Method to discover what types of messages can be sent next
     java.util.List getNextPerformatives()
              Method to discover what performatives are allowed next in the protocol.
     java.lang.String getObjectID()
              Method to get unique identifier of this DatabaseObject
     java.lang.String getProtocol()
              Method to get the protocol this Conversation is following
     java.lang.String getSender(int index)
              Gets the sender of the message at the specified index
     AgentID getSenderAID(int index)
              Gets the sender of the message at the specified index
     int getState()
              Method to retrieve the state of the conversation (e.g.
     long getTimeOut()
              Method to get the time at which the last message will time out
     long getTimeStamp(int index)
              Method to retrieve the time stamp of a given message
    static void main(java.lang.String[] args)
              Used for testing.
    static void testAddMessages(ConversationImpl conv, java.lang.String[] data, boolean cont)
               
    static void testAddMessages(java.lang.String protocol, java.lang.String[] data, boolean cont)
               
    static ConversationImpl testPopulate(ACLMessage acl, java.lang.String protocol)
              
    Returns a Conversation object populated with the passed ACLMessage.
     java.lang.String toString()
              Overrides default toString()
     
    Methods inherited from class java.lang.Object
    equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
     

    Field Detail

    CONVERSATION_END

    public static final int CONVERSATION_END
    Conversation has ended

    NO_AGENT_ACTION_REQ

    public static final int NO_AGENT_ACTION_REQ
    Conversation requires no Agent interaction

    AGENT_ACTION_REQ

    public static final int AGENT_ACTION_REQ
    Conversation requires Agent interaction

    WAIT_BEFORE_END

    public static final int WAIT_BEFORE_END
    Wait for response before ending conversation

    _protocol_tree

    protected ConversationImpl.ConversationProtocol _protocol_tree
    Protocol that conversations of this type should follow (tree like structure for quick access)

    _agent_id

    protected AgentID _agent_id
    Agent-id of the Agent to whom this belongs

    _protocol

    protected java.lang.String _protocol
    Name of the protocol this conversation is following
    Constructor Detail

    ConversationImpl

    protected ConversationImpl()
    Generalised constructor
    Method Detail

    getConversation

    public static ConversationImpl getConversation(java.lang.String protocol,
                                                   java.lang.String agent_name)
                                            throws UnknownProtocolException,
                                                   ParserException
    Method to dynamically load a Conversation instance which follows the given protocol and belongs to the given Agent
    Parameters:
    protocol - FIPA protocol name, null for generic NoProtocol conversation object
    agent_name - AgentID of the Agent on the local machine who is involved in this conversation
    Returns:
    The appropriate instance of Conversation for the protocol given
    Throws:
    UnknownProtocolException - Thrown if a Conversation class cannot be loaded for the given class

    getConversation

    public static ConversationImpl getConversation(java.lang.String protocol,
                                                   AgentID agent_name)
                                            throws UnknownProtocolException
    Method to dynamically load a Conversation instance which follows the given protocol and belongs to the given Agent
    Parameters:
    protocol - FIPA protocol name, null for generic NoProtocol conversation object
    agent_name - AgentID of the Agent on the local machine who is involved in this conversation
    Returns:
    The appropriate instance of Conversation for the protocol given
    Throws:
    UnknownProtocolException - Thrown if a Conversation class cannot be loaded for the given class

    getLatestMessageIndex

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

    getACL

    public ACL getACL(int index)
    Pass-back the latest message in this conversation
    Specified by:
    getACL in interface Conversation

    getEnvelope

    public Envelope getEnvelope(int index)
    Get the Envelope of the latest message received
    Specified by:
    getEnvelope in interface Conversation

    getMessage

    public ACLMessage getMessage(int index)
    Deprecated. The ACLMessage object is no longer supported - please use the getACL() and getEnvelope() methods instead

    Method to retrieve the ACLMessage with the given index in the conversation (e.g. first message has an index of 0, second 1 etc...). The messages are ordered based upon the order they are added to the Conversation.
    Parameters:
    index - The index of the message to retrieve
    Returns:
    The ACLMessage at the given index, or null if a message with that index doesn't exist

    getSender

    public java.lang.String getSender(int index)
    Gets the sender of the message at the specified index
    Specified by:
    getSender in interface Conversation
    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
    Specified by:
    getSenderAID in interface Conversation
    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

    getTimeStamp

    public long getTimeStamp(int index)
    Method to retrieve the time stamp of a given message
    Specified by:
    getTimeStamp in interface Conversation
    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

    getTimeOut

    public long getTimeOut()
    Method to get the time at which the last message will time out
    Specified by:
    getTimeOut in interface Conversation
    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

    getNextPerformatives

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

    getNextMessages

    public java.util.List getNextMessages()
    Method to discover what types of messages can be sent next
    Specified by:
    getNextMessages in interface Conversation
    Returns:
    A list of possible ACL's which could be sent next, or return an empty list if none can

    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
    Specified by:
    getFilledInACL in interface Conversation
    Returns:
    The filled in ACL object

    getProtocol

    public java.lang.String getProtocol()
    Method to get the protocol this Conversation is following
    Specified by:
    getProtocol in interface Conversation

    getConversationID

    public java.lang.String getConversationID()
    Gets the conversation ID of the conversation
    Specified by:
    getConversationID in interface Conversation
    Returns:
    The String representation of the Conversation's ID, or null if one has not been assigned

    getState

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

    getObjectID

    public java.lang.String getObjectID()
    Method to get unique identifier of this DatabaseObject
    Specified by:
    getObjectID in interface DatabaseObject

    toString

    public java.lang.String toString()
    Overrides default toString()
    Overrides:
    toString in class java.lang.Object

    clone

    public java.lang.Object clone()
    Clone method to make duplicates of this Conversation object
    Overrides:
    clone in class java.lang.Object
    Returns:
    An independant copy of this Conversation object
    Throws:
    java.lang.CloneNotSupportedException - Thrown if the object cannot be cloned

    addMessage

    public void addMessage(Message msg)
                    throws ProtocolErrorException,
                           InvalidConversationIDException,
                           ConversationFinishedException
    Method to add a message to the conversation - sets conversation state to updated as well.
    Parameters:
    mess - The Message to be added
    Throws:
    ProtocolErrorException - Thrown when the message to be added doesn't follow the correct protocol
    InvalidConversationIDException - Thrown when the conversation ID of the ACLMessage is different to that of the conversation
    ConversationFinishedException - Thrown when the conversation has been finished

    testAddMessages

    public static void testAddMessages(java.lang.String protocol,
                                       java.lang.String[] data,
                                       boolean cont)
                                throws java.lang.Throwable

    testAddMessages

    public static void testAddMessages(ConversationImpl conv,
                                       java.lang.String[] data,
                                       boolean cont)

    testPopulate

    public static ConversationImpl testPopulate(ACLMessage acl,
                                                java.lang.String protocol)

    Returns a Conversation object populated with the passed ACLMessage.
    Is useful during testing for creating populated Conversations.
    Parameters:
    acl - The ACLMessage to populate the Conversation with.
    protocol - A String identifying the protocol object to create.

    main

    public static void main(java.lang.String[] args)
                     throws java.lang.Throwable
    Used for testing.