Package jade.lang.acl

Class ACLMessage

  • All Implemented Interfaces:
    Serializable, Serializable, Cloneable
    Direct Known Subclasses:
    Message, OntoACLMessage
    public class ACLMessage
extends Object
implements Cloneable, Serializable
    The class ACLMessage implements an ACL message compliant to the FIPA 2000 "FIPA ACL Message Structure Specification" (fipa000061) specifications. All parameters are couples keyword: value. All keywords are private final String. All values can be set by using the methods set and can be read by using the methods get.

    Warning: since JADE 3.1 an exception might be thrown during the serialization of the ACLMessage parameters (with exception of the content of the ACLMessage) because of a limitation to 65535 in the total number of bytes needed to represent all the characters of a String (see also java.io.DataOutput#writeUTF(String)).

    The methods setByteSequenceContent() and getByteSequenceContent() allow to send arbitrary sequence of bytes over the content of an ACLMessage.

    The couple of methods setContentObject() and getContentObject() allow to send serialized Java objects over the content of an ACLMessage. These method are not strictly FIPA compliant so their usage is not encouraged.

    Version:
    $Date$ $Revision$
    Author:
    Fabio Bellifemine - CSELT
    See Also:
    FIPA Spec, Serialized Form

    • Field Detail

      • ACCEPT_PROPOSAL

        public static final int ACCEPT_PROPOSAL
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • AGREE

        public static final int AGREE
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • CANCEL

        public static final int CANCEL
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • CFP

        public static final int CFP
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • CONFIRM

        public static final int CONFIRM
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • DISCONFIRM

        public static final int DISCONFIRM
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • FAILURE

        public static final int FAILURE
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • INFORM

        public static final int INFORM
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • INFORM_IF

        public static final int INFORM_IF
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • INFORM_REF

        public static final int INFORM_REF
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • NOT_UNDERSTOOD

        public static final int NOT_UNDERSTOOD
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • PROPOSE

        public static final int PROPOSE
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • QUERY_IF

        public static final int QUERY_IF
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • QUERY_REF

        public static final int QUERY_REF
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • REFUSE

        public static final int REFUSE
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • REJECT_PROPOSAL

        public static final int REJECT_PROPOSAL
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • REQUEST

        public static final int REQUEST
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • REQUEST_WHEN

        public static final int REQUEST_WHEN
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • REQUEST_WHENEVER

        public static final int REQUEST_WHENEVER
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • SUBSCRIBE

        public static final int SUBSCRIBE
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • PROXY

        public static final int PROXY
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • PROPAGATE

        public static final int PROPAGATE
        constant identifying the FIPA performative
        See Also:
        Constant Field Values

      • UNKNOWN

        public static final int UNKNOWN
        constant identifying an unknown performative
        See Also:
        Constant Field Values

      • IGNORE_FAILURE

        public static final String IGNORE_FAILURE
        User defined parameter key specifying, when set to "true", that if the delivery of a message fails, no failure handling action must be performed.
        See Also:
        Constant Field Values

      • DONT_NOTIFY_FAILURE

        public static final String DONT_NOTIFY_FAILURE
        User defined parameter key specifying, when set to "true", that if the delivery of a message fails, no FAILURE notification has to be sent back to the sender. This differs from IGNORE_FAILURE since it does not inhibit the delivery failure handling mechanism (based on the NOTIFY_FAILURE VCommand) at all, but just the delivery of the automatic AMS FAILURE reply.
        See Also:
        Constant Field Values

      • TRACE

        public static final String TRACE
        User defined parameter key specifying that the JADE tracing mechanism should be activated for this message.
        See Also:
        Constant Field Values

      • NO_CLONE

        public static final String NO_CLONE
        User defined parameter key specifying that this message does not need to be cloned by the message delivery service. This should be used ONLY when the message object will not be modified after being sent
        See Also:
        Constant Field Values

      • SYNCH_DELIVERY

        public static final String SYNCH_DELIVERY
        User defined parameter key specifying that this message must be delivered synchronously. It should be noticed that when using synchronous delivery message order is not guaranteed.
        See Also:
        Constant Field Values

      • REAL_SENDER

        public static final String REAL_SENDER
        User defined parameter key specifying the AID of the real sender of a message. This is automatically set by the MessagingService when posting a message where the sender field is different than the real sender.
        See Also:
        Constant Field Values

      • SF_TIMEOUT

        public static final String SF_TIMEOUT
        User defined parameter key specifying that this message must be stored for a given timeout (in ms) in case it is sent to/from a temporarily disconnected split container. After that timeout a FAILURE message will be sent back to the sender.
        0 means store and forward disabled -1 means infinite timeout
        See Also:
        Constant Field Values

      • AMS_FAILURE_AGENT_NOT_FOUND

        public static final String AMS_FAILURE_AGENT_NOT_FOUND
        AMS failure reasons
        See Also:
        Constant Field Values

      • AMS_FAILURE_FOREIGN_AGENT_UNREACHABLE

        public static final String AMS_FAILURE_FOREIGN_AGENT_UNREACHABLE
        See Also:
        Constant Field Values

      • AMS_FAILURE_FOREIGN_AGENT_NO_ADDRESS

        public static final String AMS_FAILURE_FOREIGN_AGENT_NO_ADDRESS
        See Also:
        Constant Field Values

    • Constructor Detail

      • ACLMessage

        public ACLMessage()
        Deprecated.
        Since every ACL Message must have a message type, you should use the new constructor which gets a message type as a parameter. To avoid problems, now this constructor silently sets the message type to not-understood.
        See Also:
        ACLMessage(int)

      • ACLMessage

        public ACLMessage​(int perf)
        This constructor creates an ACL message object with the specified performative. If the passed integer does not correspond to any of the known performatives, it silently initializes the message to not-understood.

    • Method Detail

      • getAllPerformativeNames

        public static String[] getAllPerformativeNames()
        Returns the list of the communicative acts as an array of String.

      • setSender

        public void setSender​(AID s)
        Writes the :sender slot. Warning: no checks are made to validate the slot value.
        Parameters:
        source - The new value for the slot.
        See Also:
        getSender()

      • addReceiver

        public void addReceiver​(AID r)
        Adds a value to :receiver slot. Warning: no checks are made to validate the slot value.
        Parameters:
        r - The value to add to the slot value set.

      • removeReceiver

        public boolean removeReceiver​(AID r)
        Removes a value from :receiver slot. Warning: no checks are made to validate the slot value.
        Parameters:
        r - The value to remove from the slot value set.
        Returns:
        true if the AID has been found and removed, false otherwise

      • clearAllReceiver

        public void clearAllReceiver()
        Removes all values from :receiver slot. Warning: no checks are made to validate the slot value.

      • addReplyTo

        public void addReplyTo​(AID dest)
        Adds a value to :reply-to slot. Warning: no checks are made to validate the slot value.
        Parameters:
        dest - The value to add to the slot value set.

      • removeReplyTo

        public boolean removeReplyTo​(AID dest)
        Removes a value from :reply_to slot. Warning: no checks are made to validate the slot value.
        Parameters:
        dest - The value to remove from the slot value set.
        Returns:
        true if the AID has been found and removed, false otherwise

      • clearAllReplyTo

        public void clearAllReplyTo()
        Removes all values from :reply_to slot. Warning: no checks are made to validate the slot value.

      • setPerformative

        public void setPerformative​(int perf)
        set the performative of this ACL message object to the passed constant. Remind to use the set of constants (i.e. INFORM, REQUEST, ... ) defined in this class

      • setContent

        public void setContent​(String content)
        Writes the :content slot. Warning: no checks are made to validate the slot value.

        Notice that, in general, setting a String content and getting back a byte sequence content - or viceversa - does not return the same value, i.e. the following relation does not hold getByteSequenceContent(setByteSequenceContent(getContent().getBytes())) is equal to getByteSequenceContent()

        Parameters:
        content - The new value for the slot.
        See Also:
        getContent(), setByteSequenceContent(byte[]), jade.lang.acl.ACLMessage#setContentObject(Serializable s)

      • setByteSequenceContent

        public void setByteSequenceContent​(byte[] byteSequenceContent)
        Writes the :content slot. Warning: no checks are made to validate the slot value.

        Notice that, in general, setting a String content and getting back a byte sequence content - or viceversa - does not return the same value, i.e. the following relation does not hold getByteSequenceContent(setByteSequenceContent(getContent().getBytes())) is equal to getByteSequenceContent()

        Parameters:
        byteSequenceContent - The new value for the slot.
        See Also:
        setContent(String s), getByteSequenceContent(), jade.lang.acl.ACLMessage#setContentObject(Serializable s)

      • setContentObject

        public void setContentObject​(Serializable s)
                      throws IOException
        This method sets the content of this ACLMessage to a Java object. It is not FIPA compliant so its usage is not encouraged. For example:
         ACLMessage msg = new ACLMessage(ACLMessage.INFORM);
 Date d = new Date(); 
 try{
  msg.setContentObject(d);
 }catch(IOException e){}
        Parameters:
        s - the object that will be used to set the content of the ACLMessage.
        Throws:
        IOException - if an I/O error occurs.

      • getContentObject

        public Serializable getContentObject()
                              throws UnreadableException
        This method returns the content of this ACLMessage when they have been written via the method setContentObject. It is not FIPA compliant so its usage is not encouraged. For example to read Java objects from the content 
         ACLMessage msg = blockingReceive();
 try{
  Date d = (Date)msg.getContentObject();
 }catch(UnreadableException e){}
        Returns:
        the object read from the content of this ACLMessage
        Throws:
        UnreadableException - when an error occurs during the decoding.

      • setReplyWith

        public void setReplyWith​(String reply)
        Writes the :reply-with slot. Warning: no checks are made to validate the slot value.
        Parameters:
        reply - The new value for the slot.
        See Also:
        getReplyWith()

      • setInReplyTo

        public void setInReplyTo​(String reply)
        Writes the :in-reply-to slot. Warning: no checks are made to validate the slot value.
        Parameters:
        reply - The new value for the slot.
        See Also:
        getInReplyTo()

      • setEncoding

        public void setEncoding​(String str)
        Writes the :encoding slot. Warning: no checks are made to validate the slot value.
        Parameters:
        str - The new value for the slot.
        See Also:
        getEncoding()

      • setLanguage

        public void setLanguage​(String str)
        Writes the :language slot. Warning: no checks are made to validate the slot value.
        Parameters:
        str - The new value for the slot.
        See Also:
        getLanguage()

      • setOntology

        public void setOntology​(String str)
        Writes the :ontology slot. Warning: no checks are made to validate the slot value.
        Parameters:
        str - The new value for the slot.
        See Also:
        getOntology()

      • setReplyByDate

        public void setReplyByDate​(Date date)
        Writes the :reply-by slot. Warning: no checks are made to validate the slot value.
        Parameters:
        date - The new value for the slot.
        See Also:
        getReplyByDate()

      • setProtocol

        public void setProtocol​(String str)
        Writes the :protocol slot. Warning: no checks are made to validate the slot value.
        Parameters:
        str - The new value for the slot.
        See Also:
        getProtocol()

      • setConversationId

        public void setConversationId​(String str)
        Writes the :conversation-id slot. Warning: no checks are made to validate the slot value.
        Parameters:
        str - The new value for the slot.
        See Also:
        getConversationId()

      • getAllReceiver

        public Iterator getAllReceiver()
        Reads :receiver slot.
        Returns:
        An Iterator containing the Agent IDs of the receiver agents for this message.

      • getAllReplyTo

        public Iterator getAllReplyTo()
        Reads :reply_to slot.
        Returns:
        An Iterator containing the Agent IDs of the reply_to agents for this message.

      • getSender

        public AID getSender()
        Reads :sender slot.
        Returns:
        The value of :senderslot.

      • getPerformative

        public static String getPerformative​(int perf)
        Returns the string corresponding to the integer for the performative
        Returns:
        the string corresponding to the integer for the performative; "NOT-UNDERSTOOD" if the integer is out of range.

      • getInteger

        public static int getInteger​(String perf)
        Returns the integer corresponding to the performative

      • getPerformative

        public int getPerformative()
        return the integer representing the performative of this object
        Returns:
        an integer representing the performative of this object

      • hasByteSequenceContent

        public boolean hasByteSequenceContent()
        This method allows to check if the content of this ACLMessage is a byteSequence or a String
        Returns:
        true if it is a byteSequence, false if it is a String

      • getContent

        public String getContent()
        Reads :content slot.

        Notice that, in general, setting a String content and getting back a byte sequence content - or viceversa - does not return the same value, i.e. the following relation does not hold getByteSequenceContent(setByteSequenceContent(getContent().getBytes())) is equal to getByteSequenceContent()

        Returns:
        The value of :content slot.
        See Also:
        setContent(String), getByteSequenceContent(), getContentObject()

      • getByteSequenceContent

        public byte[] getByteSequenceContent()
        Reads :content slot.

        Notice that, in general, setting a String content and getting back a byte sequence content - or viceversa - does not return the same value, i.e. the following relation does not hold getByteSequenceContent(setByteSequenceContent(getContent().getBytes())) is equal to getByteSequenceContent()

        Returns:
        The value of :content slot.
        See Also:
        getContent(), setByteSequenceContent(byte[]), getContentObject()

      • getReplyWith

        public String getReplyWith()
        Reads :reply-with slot.
        Returns:
        The value of :reply-withslot.

      • getInReplyTo

        public String getInReplyTo()
        Reads :reply-to slot.
        Returns:
        The value of :reply-toslot.

      • getEncoding

        public String getEncoding()
        Reads :encoding slot.
        Returns:
        The value of :encodingslot.

      • getLanguage

        public String getLanguage()
        Reads :language slot.
        Returns:
        The value of :languageslot.

      • getOntology

        public String getOntology()
        Reads :ontology slot.
        Returns:
        The value of :ontologyslot.

      • getReplyBy

        public String getReplyBy()
        Deprecated.
        Since the value of this slot is a Date by definition, then the getReplyByDate should be used that returns a Date
        Reads :reply-by slot.
        Returns:
        The value of :reply-byslot, as a string.

      • getReplyByDate

        public Date getReplyByDate()
        Reads :reply-by slot.
        Returns:
        The value of :reply-byslot, as a Date object.

      • getProtocol

        public String getProtocol()
        Reads :protocol slot.
        Returns:
        The value of :protocolslot.

      • getConversationId

        public String getConversationId()
        Reads :conversation-id slot.
        Returns:
        The value of :conversation-idslot.

      • addUserDefinedParameter

        public void addUserDefinedParameter​(String key,
                                    String value)
        Add a new user defined parameter to this ACLMessage. Notice that according to the FIPA specifications, the keyword of a user-defined parameter must not contain space inside. Note that the user does not need to (and shall not) add the prefix "X-" to the keyword. This is automatically added by the StringACLCodec.
        Parameters:
        key - the property key.
        value - the property value

      • getUserDefinedParameter

        public String getUserDefinedParameter​(String key)
        Searches for the user defined parameter with the specified key. The method returns null if the parameter is not found.
        Parameters:
        key - the parameter key.
        Returns:
        the value in this ACLMessage with the specified key value.

      • getAllUserDefinedParameters

        public Properties getAllUserDefinedParameters()
        Return all user defined parameters of this ACLMessage in form of a Properties object

      • setAllUserDefinedParameters

        public void setAllUserDefinedParameters​(Properties userDefProps)
        Replace all user defined parameters of this ACLMessage with the specified Properties object.

      • removeUserDefinedParameter

        public boolean removeUserDefinedParameter​(String key)
        Removes the key and its corresponding value from the list of user defined parameters in this ACLMessage.
        Parameters:
        key - the key that needs to be removed
        Returns:
        true if the property has been found and removed, false otherwise

      • clearUserDefinedParameter

        public Object clearUserDefinedParameter​(String key)
        Removes the key and its corresponding value from the list of user defined parameters in this ACLMessage.
        Parameters:
        key - the key that needs to be removed
        Returns:
        the value to which the key had been mapped or null if the key was not present

      • setPostTimeStamp

        public void setPostTimeStamp​(long time)

      • getPostTimeStamp

        public long getPostTimeStamp()

      • setEnvelope

        public void setEnvelope​(Envelope e)
        Attaches an envelope to this message. The envelope is used by the ACC for inter-platform messaging.
        Parameters:
        e - The Envelope object to attach to this message.
        See Also:
        jade.lang.acl#getEnvelope(), jade.lang.acl#setDefaultEnvelope()

      • setDefaultEnvelope

        public void setDefaultEnvelope()
        Writes the message envelope for this message, using the :sender and :receiver message slots to fill in the envelope.
        See Also:
        jade.lang.acl#setEnvelope(Envelope e), jade.lang.acl#getEnvelope()

      • getEnvelope

        public Envelope getEnvelope()
        Reads the envelope attached to this message, if any.
        Returns:
        The envelope for this message.
        See Also:
        jade.lang.acl#setEnvelope(Envelope e), jade.lang.acl#setDefaultEnvelope()

      • toString

        public String toString()
        Convert an ACL message to its string representation. This method writes a representation of this ACLMessage into a character string. If the content is a bytesequence, then it is automatically converted into Base64 encoding.
        Overrides:
        toString in class Object
        Returns:
        A String representing this message.

      • shortToString

        public String shortToString()

      • clone

        public Object clone()
        Clone an ACLMessage object.
        Overrides:
        clone in class Object
        Returns:
        A copy of this ACLMessage object. The copy must be casted back to ACLMessage type before being used.

      • shallowClone

        public ACLMessage shallowClone()
        Normal clone() method actually perform a deep-clone of the ACLMessage object. This method instead clones the ACLMessage object itself but not the objects pointed to by the ACLMessage fields.
        Returns:
        A new ACLMessage whose fields points to the same object as the original ACLMessage object

      • reset

        public void reset()
        Resets all the message slots.

      • createReply

        public ACLMessage createReply()
        create a new ACLMessage that is a reply to this message. In particular, it sets the following parameters of the new message: receiver, language, ontology, protocol, conversation-id, in-reply-to, reply-with. The programmer needs to set the communicative-act and the content. Of course, if he wishes to do that, he can reset any of the fields.
        Returns:
        the ACLMessage to send as a reply

      • createReply

        public ACLMessage createReply​(int performative)

      • getAllIntendedReceiver

        public Iterator getAllIntendedReceiver()
        retrieve the whole list of intended receivers for this message.
        Returns:
        An Iterator over all the intended receivers of this message taking into account the Envelope ":intended-receiver" first, the Envelope ":to" second and the message ":receiver" last.