jade.lang.acl
Class ACLMessage

java.lang.Object
  |
  +--jade.lang.acl.ACLMessage
Direct Known Subclasses:
OntoACLMessage

public class ACLMessage
extends java.lang.Object
implements java.lang.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.

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: 2003/03/19 11:16:50 $ $Revision: 2.23 $
Author:
Fabio Bellifemine - CSELT
See Also:
FIPA Spec, Serialized Form

Field Summary
static int ACCEPT_PROPOSAL
          constant identifying the FIPA performative
static int AGREE
          constant identifying the FIPA performative
static int CANCEL
          constant identifying the FIPA performative
static int CFP
          constant identifying the FIPA performative
static int CONFIRM
          constant identifying the FIPA performative
static int DISCONFIRM
          constant identifying the FIPA performative
static int FAILURE
          constant identifying the FIPA performative
static int INFORM
          constant identifying the FIPA performative
static int INFORM_IF
          constant identifying the FIPA performative
static int INFORM_REF
          constant identifying the FIPA performative
static int NOT_UNDERSTOOD
          constant identifying the FIPA performative
static int PROPAGATE
          constant identifying the FIPA performative
static int PROPOSE
          constant identifying the FIPA performative
static int PROXY
          constant identifying the FIPA performative
static int QUERY_IF
          constant identifying the FIPA performative
static int QUERY_REF
          constant identifying the FIPA performative
static int REFUSE
          constant identifying the FIPA performative
static int REJECT_PROPOSAL
          constant identifying the FIPA performative
static int REQUEST
          constant identifying the FIPA performative
static int REQUEST_WHEN
          constant identifying the FIPA performative
static int REQUEST_WHENEVER
          constant identifying the FIPA performative
static int SUBSCRIBE
          constant identifying the FIPA performative
static int UNKNOWN
          constant identifying an unknown performative
 
Constructor Summary
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.
ACLMessage(int perf)
          This constructor creates an ACL message object with the specified performative.
 
Method Summary
 void addReceiver(AID r)
          Adds a value to :receiver slot.
 void addReplyTo(AID dest)
          Adds a value to :reply-to slot.
 void addUserDefinedParameter(java.lang.String key, java.lang.String value)
          Add a new user defined parameter to this ACLMessage.
 void clearAllReceiver()
          Removes all values from :receiver slot.
 void clearAllReplyTo()
          Removes all values from :reply_to slot.
 java.lang.Object clone()
          Clone an ACLMessage object.
 ACLMessage createReply()
          create a new ACLMessage that is a reply to this message.
 Iterator getAllIntendedReceiver()
           
static java.lang.String[] getAllPerformativeNames()
          Returns the list of the communicative acts as an array of String.
 Iterator getAllReceiver()
          Reads :receiver slot.
 Iterator getAllReplyTo()
          Reads :reply_to slot.
 Properties getAllUserDefinedParameters()
          get a clone of the data structure with all the user defined parameters
 byte[] getByteSequenceContent()
          Reads :content slot.
 java.lang.String getContent()
          Reads :content slot.
 java.io.Serializable getContentObject()
          This method returns the content of this ACLMessage when they have been written via the method setContentObject.
 java.lang.String getConversationId()
          Reads :conversation-id slot.
 java.lang.String getEncoding()
          Reads :encoding slot.
 Envelope getEnvelope()
          Reads the envelope attached to this message, if any.
 java.lang.String getInReplyTo()
          Reads :reply-to slot.
static int getInteger(java.lang.String perf)
          Returns the integer corresponding to the performative
 java.lang.String getLanguage()
          Reads :language slot.
 java.lang.String getOntology()
          Reads :ontology slot.
 int getPerformative()
          return the integer representing the performative of this object
static java.lang.String getPerformative(int perf)
          Returns the string corresponding to the integer for the performative
 java.lang.String getProtocol()
          Reads :protocol slot.
 java.lang.String getReplyBy()
          Deprecated. Since the value of this slot is a Date by definition, then the getReplyByDate should be used that returns a Date
 java.util.Date getReplyByDate()
          Reads :reply-by slot.
 java.lang.String getReplyWith()
          Reads :reply-with slot.
 AID getSender()
          Reads :sender slot.
 java.lang.String getUserDefinedParameter(java.lang.String key)
          Searches for the user defined parameter with the specified key.
 boolean hasByteSequenceContent()
          This method allows to check if the content of this ACLMessage is a byteSequence or a String
 boolean removeReceiver(AID r)
          Removes a value from :receiver slot.
 boolean removeReplyTo(AID dest)
          Removes a value from :reply_to slot.
 boolean removeUserDefinedParameter(java.lang.String key)
          Removes the key and its corresponding value from the list of user defined parameters in this ACLMessage.
 void reset()
          Resets all the message slots.
 void setByteSequenceContent(byte[] content)
          Writes the :content slot.
 void setContent(java.lang.String content)
          Writes the :content slot.
 void setContentObject(java.io.Serializable s)
          This method sets the content of this ACLMessage to a Java object.
 void setConversationId(java.lang.String str)
          Writes the :conversation-id slot.
 void setDefaultEnvelope()
          Writes the message envelope for this message, using the :sender and :receiver message slots to fill in the envelope.
 void setEncoding(java.lang.String str)
          Writes the :encoding slot.
 void setEnvelope(Envelope e)
          Attaches an envelope to this message.
 void setInReplyTo(java.lang.String reply)
          Writes the :in-reply-to slot.
 void setLanguage(java.lang.String str)
          Writes the :language slot.
 void setOntology(java.lang.String str)
          Writes the :ontology slot.
 void setPerformative(int perf)
          set the performative of this ACL message object to the passed constant.
 void setProtocol(java.lang.String str)
          Writes the :protocol slot.
 void setReplyByDate(java.util.Date date)
          Writes the :reply-by slot.
 void setReplyWith(java.lang.String reply)
          Writes the :reply-with slot.
 void setSender(AID s)
          Writes the :sender slot.
 java.lang.String toString()
          Convert an ACL message to its string representation.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ACCEPT_PROPOSAL

public static final int ACCEPT_PROPOSAL
constant identifying the FIPA performative

AGREE

public static final int AGREE
constant identifying the FIPA performative

CANCEL

public static final int CANCEL
constant identifying the FIPA performative

CFP

public static final int CFP
constant identifying the FIPA performative

CONFIRM

public static final int CONFIRM
constant identifying the FIPA performative

DISCONFIRM

public static final int DISCONFIRM
constant identifying the FIPA performative

FAILURE

public static final int FAILURE
constant identifying the FIPA performative

INFORM

public static final int INFORM
constant identifying the FIPA performative

INFORM_IF

public static final int INFORM_IF
constant identifying the FIPA performative

INFORM_REF

public static final int INFORM_REF
constant identifying the FIPA performative

NOT_UNDERSTOOD

public static final int NOT_UNDERSTOOD
constant identifying the FIPA performative

PROPOSE

public static final int PROPOSE
constant identifying the FIPA performative

QUERY_IF

public static final int QUERY_IF
constant identifying the FIPA performative

QUERY_REF

public static final int QUERY_REF
constant identifying the FIPA performative

REFUSE

public static final int REFUSE
constant identifying the FIPA performative

REJECT_PROPOSAL

public static final int REJECT_PROPOSAL
constant identifying the FIPA performative

REQUEST

public static final int REQUEST
constant identifying the FIPA performative

REQUEST_WHEN

public static final int REQUEST_WHEN
constant identifying the FIPA performative

REQUEST_WHENEVER

public static final int REQUEST_WHENEVER
constant identifying the FIPA performative

SUBSCRIBE

public static final int SUBSCRIBE
constant identifying the FIPA performative

PROXY

public static final int PROXY
constant identifying the FIPA performative

PROPAGATE

public static final int PROPAGATE
constant identifying the FIPA performative

UNKNOWN

public static final int UNKNOWN
constant identifying an unknown performative
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 java.lang.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(java.lang.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[]), setContentObject(Serializable s)

setByteSequenceContent

public void setByteSequenceContent(byte[] 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:
setContent(String s), getByteSequenceContent(), setContentObject(Serializable s)

setContentObject

public void setContentObject(java.io.Serializable s)
                      throws java.io.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:
java.io.IOException - if an I/O error occurs.

getContentObject

public java.io.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 deconding.

setReplyWith

public void setReplyWith(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.util.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(java.lang.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(java.lang.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.
See Also:
setSender(AID).

getPerformative

public static java.lang.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(java.lang.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 java.lang.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(), ObjectInputStream

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:
setContent(String), getContent(), getContentObject(), ObjectInputStream

getReplyWith

public java.lang.String getReplyWith()
Reads :reply-with slot.
Returns:
The value of :reply-withslot.
See Also:
setReplyWith(String).

getInReplyTo

public java.lang.String getInReplyTo()
Reads :reply-to slot.
Returns:
The value of :reply-toslot.
See Also:
setInReplyTo(String).

getEncoding

public java.lang.String getEncoding()
Reads :encoding slot.
Returns:
The value of :encodingslot.
See Also:
setEncoding(String).

getLanguage

public java.lang.String getLanguage()
Reads :language slot.
Returns:
The value of :languageslot.
See Also:
setLanguage(String).

getOntology

public java.lang.String getOntology()
Reads :ontology slot.
Returns:
The value of :ontologyslot.
See Also:
setOntology(String).

getReplyBy

public java.lang.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.
See Also:
jade.lang.acl.ACLMessage#setReplyBy(String)., getReplyByDate().

getReplyByDate

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

getProtocol

public java.lang.String getProtocol()
Reads :protocol slot.
Returns:
The value of :protocolslot.
See Also:
setProtocol(String).

getConversationId

public java.lang.String getConversationId()
Reads :conversation-id slot.
Returns:
The value of :conversation-idslot.
See Also:
setConversationId(String).

addUserDefinedParameter

public void addUserDefinedParameter(java.lang.String key,
                                    java.lang.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 and must start with the String "X-". If it does not, then the encoding method adds the prefix silently!
Parameters:
key - the property key.
value - the property value

getUserDefinedParameter

public java.lang.String getUserDefinedParameter(java.lang.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()
get a clone of the data structure with all the user defined parameters

removeUserDefinedParameter

public boolean removeUserDefinedParameter(java.lang.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

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, jade.lang.acl

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, jade.lang.acl

getEnvelope

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

toString

public java.lang.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 java.lang.Object
Returns:
A String representing this message.

clone

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

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

getAllIntendedReceiver

public Iterator getAllIntendedReceiver()
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.