jade.lang.acl
Class ACLMessage

java.lang.Object
  |
  +--jade.lang.acl.ACLMessage

public class ACLMessage
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

The class ACLMessage implements an ACL message compliant to the FIPA 97 specs. 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.

Notice that the get methods never return null, rather they return an empty String.

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

Author:
Fabio Bellifemine - CSELT
See Also:
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.
ACLMessage(java.lang.String type)
          Deprecated. It increases the probability of error when the passed String does not belong to the set of performatives supported by FIPA. This constructor creates an ACL message object with the specified type. To avoid problems, the constructor ACLMessage(int) should be used instead.
 
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.
static java.util.List getAllPerformatives()
          Returns the list of the communicative acts.
 java.util.Iterator getAllReceiver()
          Reads :receiver slot.
 java.util.Iterator getAllReplyTo()
          Reads :reply_to slot.
 java.util.Properties getAllUserDefinedParameters()
          get a clone of the data structure with all the user defined parameters
 java.lang.String getContent()
          Reads :content slot.
 java.io.Serializable getContentObject()
          This method returns the content of this ACLMessage after decoding according to Base64.
 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()
          Reads :reply-by slot.
 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 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 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 setReplyBy(java.lang.String str)
          Writes the :reply-by 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.
 void toText(java.io.Writer w)
          Writes an ACL message object on a stream as a character string.
 
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(String type)

ACLMessage

public ACLMessage(java.lang.String type)
Deprecated. It increases the probability of error when the passed String does not belong to the set of performatives supported by FIPA. This constructor creates an ACL message object with the specified type. To avoid problems, the constructor ACLMessage(int) should be used instead.
Parameters:
type - The type of the communicative act represented by this message.
See Also:
ACLMessage(int type)

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

getAllPerformatives

public static java.util.List getAllPerformatives()
Returns the list of the communicative acts.

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.

In order to transport serialized Java objects, or arbitrary sequence of bytes (i.e. something different from a Java String) over an ACL message, it is suggested to use the method ACLMessage.setContentObject() instead.

Parameters:
content - The new value for the slot.
See Also:
getContent(), 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 after decoding according to Base64. It is not FIPA compliant so its usage is not encouraged. For example to read Java objects from the content (when they have been written by using the setContentOnbject() method):
 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()

setReplyBy

public void setReplyBy(java.lang.String str)
Writes the :reply-by slot. Warning: no checks are made to validate the slot value.
Parameters:
str - The new value for the slot, as ISO8601 time.
See Also:
getReplyBy()

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 java.util.Iterator getAllReceiver()
Reads :receiver slot.
Returns:
An Iterator containing the Agent IDs of the receiver agents for this message.

getAllReplyTo

public java.util.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

getContent

public java.lang.String getContent()
Reads :content slot.

It is sometimes useful to transport serialized Java objects, or arbitrary sequence of bytes (i.e. something different from a Java String) over an ACL message. See getContentObject().

Returns:
The value of :content slot.
See Also:
setContent(String), 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()
Reads :reply-by slot.
Returns:
The value of :reply-byslot, as a string.
See Also:
setReplyBy(String).

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 start with the String ":X-". If it does not, then this 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 java.util.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

toText

public void toText(java.io.Writer w)
Writes an ACL message object on a stream as a character string. This method allows to write a string representation of an ACLMessage object onto a character stream.
Parameters:
w - A Writer object to write the message onto.

clone

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

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.
Returns:
A String representing this message.
Overrides:
toString in class java.lang.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