fipaos.agent.conversation.standard
Class ConversationImpl

Direct Known Subclasses:
FIPAAuctionDutch, FIPAAuctionEnglish, FIPABrokering, FIPAContractNet, FIPAIteratedContractNet, FIPAPropose, FIPAQuery, FIPARecruiting, FIPARequest, FIPARequestWhen, FIPASubscribe, NoProtocol, RuntimeProtocol

public abstract class ConversationImpl
implements Cloneable, Conversation, DatabaseObject, Serializable

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




    Inner Class Summary
     public static classConversationImpl.ConversationProtocol
              Class to contain information about the protocol to be
    used.
     (package private) classConversationImpl.MessageDetails
              Class to contain information about a message

    Field Summary
     (package private) Object_serialised
              Helps to indicate if this is a deserialised object
     final static intAGENT_ACTION_REQ
              Conversation requires Agent interaction
     final static intCONVERSATION_END
              Conversation has ended
     final static intNO_AGENT_ACTION_REQ
              Conversation requires no Agent interaction
     final static intWAIT_BEFORE_END
              Wait for response before ending conversation

    Method Summary
     synchronized voidaddMessage(Message msg)
              Method to add a message to the conversation - sets conversation state
    to updated as well.
     synchronized Objectclone()
              Clone method to make duplicates of this Conversation object
     (package private) synchronized ConversationImplcloneAndResetUpdate()
              Creates a copy of this Conversation object, and sets the update state
    to false
     ACLgetACL(int index)
              Pass-back the latest message in this conversation
     static ConversationImplgetConversation(String protocol, String agent_name)
              Method to dynamically load a Conversation instance which follows the
    given protocol and belongs to the given Agent
     static ConversationImplgetConversation(String protocol, AgentID agent_name)
              Method to dynamically load a Conversation instance which follows the
    given protocol and belongs to the given Agent
     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.
     StringgetObjectID()
              Method to get unique identifier of this DatabaseObject
     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
     synchronized 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
     (package private) synchronized booleanisUpdated()
              Checks if the conversation has been updated.
     static voidmain(String[] args)
              Used for testing.
     (package private) synchronized voidremoveReferences()
              Sets all references to null to aid garbage collection - ONLY USE WHEN
    OBJECT HAS BEEN FINISHED WITH!
     (package private) synchronized voidresetUpdate()
              Resets the update flag to false.
     (package private) voidsetConversationID(String conv_id)
              Sets the conversation ID of the Conversation - should only be
    called directly after creation of a Conversation object from
    the ConversationManagerImpl
     static voidtestAddMessages(String protocol, String[] data, boolean cont)
               
     static voidtestAddMessages(ConversationImpl conv, String[] data, boolean cont)
               
     static ConversationImpltestPopulate(ACLMessage acl, String protocol)
              
    Returns a Conversation object populated with the passed ACLMessage.
     StringtoString()
              Overrides default toString()

    Field Detail

    _serialised

    Object _serialised
    Helps to indicate if this is a deserialised object

    AGENT_ACTION_REQ

    public final static int AGENT_ACTION_REQ
    Conversation requires Agent interaction

    CONVERSATION_END

    public final static int CONVERSATION_END
    Conversation has ended

    NO_AGENT_ACTION_REQ

    public final static int NO_AGENT_ACTION_REQ
    Conversation requires no Agent interaction

    WAIT_BEFORE_END

    public final static int WAIT_BEFORE_END
    Wait for response before ending conversation
    Method Detail

    addMessage

    public synchronized void addMessage(Message msg)
    throws fipaos.agent.conversation.ProtocolErrorException,
    fipaos.agent.conversation.InvalidConversationIDException,
    fipaos.agent.conversation.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

    clone

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

    cloneAndResetUpdate

    synchronized ConversationImpl cloneAndResetUpdate()
    Creates a copy of this Conversation object, and sets the update state
    to false
    Returns: A copy of the current Conversation, with update state set to false

    getACL

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

    getConversation

    public static ConversationImpl getConversation(String protocol, String agent_name)
    throws fipaos.agent.conversation.UnknownProtocolException,
    fipaos.parser.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(String protocol, AgentID agent_name)
    throws fipaos.agent.conversation.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

    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 ACL'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

    getObjectID

    public String getObjectID()
    Method to get unique identifier of this DatabaseObject

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

    isUpdated

    synchronized boolean isUpdated()
    Checks if the conversation has been updated.
    Returns: True if the conversation has been updated

    main

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

    removeReferences

    synchronized void removeReferences()
    Sets all references to null to aid garbage collection - ONLY USE WHEN
    OBJECT HAS BEEN FINISHED WITH!

    resetUpdate

    synchronized void resetUpdate()
    Resets the update flag to false.

    setConversationID

    void setConversationID(String conv_id)
    Sets the conversation ID of the Conversation - should only be
    called directly after creation of a Conversation object from
    the ConversationManagerImpl
    Parameters:
    conv_id - The Conversation ID that this Conversation object should use

    testAddMessages

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

    testAddMessages

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

    testPopulate

    public static ConversationImpl testPopulate(ACLMessage acl, 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.

    toString

    public String toString()
    Overrides default toString()

    Association Links

    to Class fipaos.agent.conversation.standard.ConversationImpl.ConversationProtocol

    Not-understood generic node

    to Class fipaos.agent.conversation.standard.ConversationImpl.ConversationProtocol

    Protocol that conversations of this type should follow (tree like
    structure for quick access)

    to Class fipaos.agent.conversation.standard.ConversationImpl.ConversationProtocol

    Current position in the protocol (null if conversation is empty)

    to Class java.lang.Object

    Helps to indicate if this is a deserialised object

    to Class java.util.List

    Contains the list of MessageDetails

    to Class fipaos.ont.fipa.fipaman.AgentID

    Agent-id of the Agent to whom this belongs

    to Class fipaos.ont.fipa.fipaman.AgentID

    Other Agent in the conversations

    to Class java.lang.String

    Conversation ID of this Conversation

    to Class java.lang.String

    Name of the protocol this conversation is following