net.sf.adf.acl
Class ACLMessage

java.lang.Object
  net.sf.adf.acl.ACLMessage

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

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

A FIPA ACL message contains a set of one or more message parameters. Precisely which parameters are needed for effective agent communication will vary according to the situation; the only parameter that is mandatory in all ACL messages is the performative, although it is expected that most CL messages will also contain sender, receiver and content parameters.

If an agent does not recognize or is unable to process one or more of the parameters or parameter values, it can reply with the appropriate not-understood message.

The full set of FIPA ACL message parameters is shown bellow without regard to their specific encodings in an implementation.

FIPA ACL Message Parameters by type

• Type of communicative acts: performative
• Participant in communication: sender, receiver, reply-to
• Content of message: content
• Description of Content: language, encoding, ontology
• Control of conversation: protocol, conversation-id, reply-with, in-reply-to, reply-by

TODO: Add support for Object Content TODO: Add support for XML Content TODO: document the non-standard extensions: Object Content, Byte Content

Author:

Catalin Hritcu

See Also:

FIPA00061: FIPA ACL Message Structure Specification, Serialized Form

Constructor Summary

ACLMessage(Performative p)

Method Summary

java.lang.Object	clone()
ACLMessage	createReply() create a new Message that is a reply to this message.
byte[]	getByteSequenceContent()
java.lang.String	getContent() This parameter denotes the content of the message; equivalently denotes the object of the action.
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() The conversation-id parameter introduces an expression which is used to identify the ongoing sequence of communicative acts that together form a conversation.
java.lang.String	getEncoding() This parameter denotes the specific encoding of the content language expression.
java.lang.String	getInReplyTo() The in-reply-to parameter denotes an expression that references an earlier action to which this message is a reply.
java.lang.String	getLanguage() This parameter denotes the language in which the content parameter is expressed, for example SL, CCL, KIF or RDF.
java.lang.String	getOntology() This parameter denotes the ontology used to give a meaning to the symbols in the content expression.
Performative	getPerformative() The performative parameter denotes the type of the communicative act of the ACL message as defied by FIPA00037.
java.lang.String	getProtocol() This parameter denotes the interaction protocol that the sending agent is employing with this ACL message.
java.util.Set<AID>	getReceiverSet() The receiver parameter denotes the identity of the intended recipients of the message.
java.util.Date	getReplyByDate() The reply-by parameter denotes a time and/or date expression which indicates the latest time by which the sending agent would like to receive a reply.
long	getReplyByMillis() The reply-by parameter denotes a time and/or date expression which indicates the latest time by which the sending agent would like to receive a reply.
java.lang.String	getReplyByString() The reply-by parameter denotes a time and/or date expression which indicates the latest time by which the sending agent would like to receive a reply.
java.util.Set<AID>	getReplyToSet() The reply-to parameter indicates that subsequent messages in this conversation thread are to be directed to the agent named in the reply-to parameter, instead of to the agent named in the sender parameter.
java.lang.String	getReplyWith() The reply-with parameter introduces an expression that will be used by the responding agent to identify this message.
AID	getSender() The sender parameter denotes the identity of the sender of the message, i.e.
java.util.Properties	getUserDefinedProperties() Every FIPA implementation is free to include user-defined message parameters other than the FIPA ACL message parameters specified by FIPA00061.
void	reset()
void	setByteSequenceContent(byte[] content)
void	setContent(java.lang.String content) This parameter denotes the content of the message; equivalently denotes the object of the action.
void	setContentObject(java.io.Serializable s) This method sets the content of this ACLMessage to a Java object.
void	setConversationId(java.lang.String conversationId) The conversation-id parameter introduces an expression which is used to identify the ongoing sequence of communicative acts that together form a conversation.
void	setEncoding(java.lang.String encoding) This parameter denotes the specific encoding of the content language expression.
void	setInReplyTo(java.lang.String inReplyTo) The in-reply-to parameter denotes an expression that references an earlier action to which this message is a reply.
void	setLanguage(java.lang.String language) This parameter denotes the language in which the content parameter is expressed, for example SL, CCL, KIF or RDF.
void	setOntology(java.lang.String ontology) This parameter denotes the ontology used to give a meaning to the symbols in the content expression.
void	setPerformative(Performative p) The performative parameter denotes the type of the communicative act of the ACL message as defied by FIPA00037.
void	setProtocol(java.lang.String protocol) This parameter denotes the interaction protocol that the sending agent is employing with this ACL message.
void	setReplyBy(java.util.Date date) The reply-by parameter denotes a time and/or date expression which indicates the latest time by which the sending agent would like to receive a reply.
void	setReplyBy(long millis) The reply-by parameter denotes a time and/or date expression which indicates the latest time by which the sending agent would like to receive a reply.
void	setReplyBy(java.lang.String str) The reply-by parameter denotes a time and/or date expression which indicates the latest time by which the sending agent would like to receive a reply.
void	setReplyWith(java.lang.String replyWith) The reply-with parameter introduces an expression that will be used by the responding agent to identify this message.
void	setSender(AID sender) The sender parameter denotes the identity of the sender of the message, i.e.
java.lang.String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ACLMessage

public ACLMessage(Performative p)

Method Detail

clone

public java.lang.Object clone()

Overrides:

clone in class java.lang.Object

createReply

public ACLMessage createReply()

create a new Message 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 Message to send as a reply

getByteSequenceContent

public byte[] getByteSequenceContent()

getContent

public java.lang.String getContent()

This parameter denotes the content of the message; equivalently denotes the object of the action. The meaning of the content of any ACL message is intended to be interpreted by the receiver of the message. This is particularly relevant for instance when referring to referential expressions, whose interpretation might be different for the sender and the receiver.

Note: Most ACL messages require a content expression. Certain ACL message types, such as cancel, have an implicit content, especially in cases of using the conversation-id or in-reply-to parameters.

Returns:

A string representing the content of this message.

getContentObject

public java.io.Serializable getContentObject()
                                      throws java.io.IOException,
                                             java.lang.ClassNotFoundException

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(Exception e) {
     // handle Exceptions
 }
 

* @return the object read from the content of this ACLMessage

Throws:

UnreadableException - when an error occurs during the decoding.

java.io.IOException

java.lang.ClassNotFoundException

getConversationId

public java.lang.String getConversationId()

The conversation-id parameter introduces an expression which is used to identify the ongoing sequence of communicative acts that together form a conversation.

It is required the usage of globally unique values for the conversation-id parameter in order to allow the participants to distinguish between several concurrent conversations. A simple mechanism to ensure uniqueness is the concatenation of the globally unique identifier of the sender agent to an identifier (for example, a progressive number) that is unique within the scope of the sender agent itself.

Note: An agent may tag ACL messages with a conversation identifier to manage its communication strategies and activities. Typically this will allow an agent to identify individual conversations with multiple agents. It will also allow agents to reason across historical records of conversations.

Returns:

A string representing the conversation-id of this message.

getEncoding

public java.lang.String getEncoding()

This parameter denotes the specific encoding of the content language expression.

Note: The content expression might be encoded in several ways. The encoding parameter is optionally used to specify this encoding to the recipient agent. If the encoding parameter is not present, the encoding will be specified in the message envelope that encloses the ACL message.

Returns:

A string representing the encoding of this message.

getInReplyTo

public java.lang.String getInReplyTo()

The in-reply-to parameter denotes an expression that references an earlier action to which this message is a reply.

Returns:

A string representing the in-reply-to parameter of this message.

See Also:

getReplyWith(), setReplyWith()

getLanguage

public java.lang.String getLanguage()

This parameter denotes the language in which the content parameter is expressed, for example SL, CCL, KIF or RDF.

Note: The ACL content parameter is expressed in a formal language. This field may be omitted if the agent receiving the message can be assumed to know the language of the content expression.

Returns:

A string representing the language of this message.

See Also:

FIPA00007: FIPA Content Languages Specification (Deprecated), FIPA00008: FIPA SL Content Language Specification, FIPA00009: FIPA CCL Content Language Specification, FIPA00010: FIPA KIF Content Language Specification, FIPA00011: FIPA RDF Content Language Specification

getOntology

public java.lang.String getOntology()

This parameter denotes the ontology used to give a meaning to the symbols in the content expression.

Note: The ontology parameter is used in conjunction with the language parameter to support the interpretation of the content expression by the receiving agent. In many situations, the ontology parameter will be commonly understood by the agent community and so this message parameter may be omitted.

Returns:

A string representing the ontology of this message.

getPerformative

public Performative getPerformative()

The performative parameter denotes the type of the communicative act of the ACL message as defied by FIPA00037.

Note: The performative parameter is a required parameter of all ACL messages.

Returns:

An integer constant identifying the performative of this message.

See Also:

FIPA Communicative Act Library Specification

getProtocol

public java.lang.String getProtocol()

This parameter denotes the interaction protocol that the sending agent is employing with this ACL message. Some standard FIPA interaction protocols are: Request, Query, Request When, Contract Net, Subscribe, Propose, Auction etc.

Any ACL message that contains a non-null value for the protocol parameter is considered to belong to a conversation and it is required to respect the following rules:

• the initiator of the protocol must assign a non-null value to the conversation-id parameter,
• all responses to the message, within the scope of the same interaction protocol, should contain the same value for the conversation-id parameter, and,
• the timeout value in the reply-by parameter must denote the latest time by which the sending agent would like to have received the next message in the protocol flow (not be confused with the latest time by which the interaction protocol should terminate).

Note: The protocol parameter defines the interaction protocol in which the ACL message is generated. This parameter is optional; however, developers are advised that employing ACL without the framework of an interaction protocol (and thus directly using the ACL semantics to control the agent’s generation and interpretation of ACL messages) is an extremely ambitious undertaking.

Returns:

A string representing the protocol of this message.

See Also:

FIPA00026: FIPA Request Interaction Protocol Specification, FIPA00027: FIPA Query Interaction Protocol Specification, FIPA00028: FIPA Request When Interaction Protocol Specification, FIPA00029: FIPA Contract Net Interaction Protocol Specification, FIPA00030: FIPA Iterated Contract Net Interaction Protocol Specification, FIPA00031: FIPA English Auction Interaction Protocol Specification, FIPA00032: FIPA Dutch Auction Interaction Protocol Specification, FIPA00033: FIPA Brokering Interaction Protocol Specification, FIPA00034: FIPA Recruiting Interaction Protocol Specification, FIPA00035: FIPA Subscribe Interaction Protocol Specification, FIPA00036: FIPA Propose Interaction Protocol Specification, FIPA00025: FIPA Interaction Protocol Library Specification (Deprecated)

getReceiverSet

public java.util.Set<AID> getReceiverSet()

The receiver parameter denotes the identity of the intended recipients of the message.

The receiver parameter may be a single agent or a set of agents. The latter corresponds to the situation where the message is multicast. Pragmatically, the semantics of this multicast is that the sender intends the message for each recipient of the CA encoded in the message. For example, if an agent performs an inform act with a set of three agents as receiver, it denotes that the sender intends each of these agents to come to believe the content of the message.

Note:Ordinarily, the receiver parameter will be a part of every ACL message. It is only permissible to omit the receiver parameter if the message recipient can be reliably inferred from context, or in special cases such as the embedded ACL message in proxy and propagate.

Returns:

A java.util.Set<AID> containing the AIDs of the recipients of this message. The set is backed up by the underlying message so changes made to this set will transmit to the message.

getReplyByDate

public java.util.Date getReplyByDate()

The reply-by parameter denotes a time and/or date expression which indicates the latest time by which the sending agent would like to receive a reply.

Notes: The time will be expressed according to the sender's view of the time on the sender's platform. The reply message can be identified in several ways: as the next sequential message in an interaction protocol, through the use of the reply-with parameter, through the use of a conversation-id and so forth. The way that the reply message is identified is determined by the agent implementer.

Returns:

A java.util.Date representing the reply-by parameter of this message.

getReplyByMillis

public long getReplyByMillis()

The reply-by parameter denotes a time and/or date expression which indicates the latest time by which the sending agent would like to receive a reply.

Notes: The time will be expressed according to the sender's view of the time on the sender's platform. The reply message can be identified in several ways: as the next sequential message in an interaction protocol, through the use of the reply-with parameter, through the use of a conversation-id and so forth. The way that the reply message is identified is determined by the agent implementer.

Returns:

The number of milliseconds since January 1, 1970, 00:00:00 GMT representing the reply-by parameter of this message.

getReplyByString

public java.lang.String getReplyByString()

The reply-by parameter denotes a time and/or date expression which indicates the latest time by which the sending agent would like to receive a reply.

Notes: The time will be expressed according to the sender's view of the time on the sender's platform. The reply message can be identified in several ways: as the next sequential message in an interaction protocol, through the use of the reply-with parameter, through the use of a conversation-id and so forth. The way that the reply message is identified is determined by the agent implementer.

Returns:

A String representing the reply-by parameter of this message.

getReplyToSet

public java.util.Set<AID> getReplyToSet()

The reply-to parameter indicates that subsequent messages in this conversation thread are to be directed to the agent named in the reply-to parameter, instead of to the agent named in the sender parameter.

Returns:

A java.util.Set<AID> containing the AIDs of the agents to which subsequent messages in this conversation thread are to be directed. The set is backed up by the underlying message so changes made to this set will transmit to the message.

getReplyWith

public java.lang.String getReplyWith()

The reply-with parameter introduces an expression that will be used by the responding agent to identify this message.

The reply-with parameter is designed to be used to follow a conversation thread in a situation where multiple dialogues occur simultaneously. For example, if agent i sends to agent j a message which contains: reply-with <expr>. Agent j will respond with a message containing: in-reply-to <expr>.

Returns:

A string representing the reply-with parameter of this message.

getSender

public AID getSender()

The sender parameter denotes the identity of the sender of the message, i.e. the agent which performs the communicative act giving rise to this ACL message.

Note:The sender parameter will be a parameter of most ACL messages. It is possible to omit the sender parameter if, for example, the agent sending the ACL message wishes to remain anonymous.

Returns:

The AID of the sender of this message.

getUserDefinedProperties

public java.util.Properties getUserDefinedProperties()

Every FIPA implementation is free to include user-defined message parameters other than the FIPA ACL message parameters specified by FIPA00061. The semantics of these user-defined parameters is not defined by FIPA, and FIPA compliance does not require any particular interpretation of these parameters. The prefatory string "X-" must be used for the names of these non-FIPA standard additional parameters.

Notes: The keyword of a user-defined parameter must not contain space inside.

The user must not add the prefix "X-" to the keyword. This is automatically added by the StringACLCodec.

Returns:

A java.util.Properties object containing the user-defined properties of this message. Changes can be made to this object and they will transmit to the underlying message.

reset

public void reset()

setByteSequenceContent

public void setByteSequenceContent(byte[] content)

setContent

public void setContent(java.lang.String content)

This parameter denotes the content of the message; equivalently denotes the object of the action. The meaning of the content of any ACL message is intended to be interpreted by the receiver of the message. This is particularly relevant for instance when referring to referential expressions, whose interpretation might be different for the sender and the receiver.

Note: Most ACL messages require a content expression. Certain ACL message types, such as cancel, have an implicit content, especially in cases of using the conversation-id or in-reply-to parameters.

Warning: no checks are made to validate the content value.

Parameters:

content - A string representing the content of this message.

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) {
    // handle IOException
 }
 

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.

setConversationId

public void setConversationId(java.lang.String conversationId)

The conversation-id parameter introduces an expression which is used to identify the ongoing sequence of communicative acts that together form a conversation.

It is required the usage of globally unique values for the conversation-id parameter in order to allow the participants to distinguish between several concurrent conversations. A simple mechanism to ensure uniqueness is the concatenation of the globally unique identifier of the sender agent to an identifier (for example, a progressive number) that is unique within the scope of the sender agent itself.

Note: An agent may tag ACL messages with a conversation identifier to manage its communication strategies and activities. Typically this will allow an agent to identify individual conversations with multiple agents. It will also allow agents to reason across historical records of conversations.

Parameters:

conversationId - A string representing the conversation-id of this message.

setEncoding

public void setEncoding(java.lang.String encoding)

This parameter denotes the specific encoding of the content language expression.

Note: The content expression might be encoded in several ways. The encoding parameter is optionally used to specify this encoding to the recipient agent. If the encoding parameter is not present, the encoding will be specified in the message envelope that encloses the ACL message.

Parameters:

encoding - A string representing the encoding of this message.

setInReplyTo

public void setInReplyTo(java.lang.String inReplyTo)

The in-reply-to parameter denotes an expression that references an earlier action to which this message is a reply.

Parameters:

inReplyTo - A string representing the in-reply-to parameter of this message.

See Also:

getReplyWith(), setReplyWith()

setLanguage

public void setLanguage(java.lang.String language)

This parameter denotes the language in which the content parameter is expressed, for example SL, CCL, KIF or RDF.

Note: The ACL content parameter is expressed in a formal language. This field may be omitted if the agent receiving the message can be assumed to know the language of the content expression.

See Also:

FIPA00007: FIPA Content Languages Specification (Deprecated), FIPA00008: FIPA SL Content Language Specification, FIPA00009: FIPA CCL Content Language Specification, FIPA00010: FIPA KIF Content Language Specification, FIPA00011: FIPA RDF Content Language Specification

setOntology

public void setOntology(java.lang.String ontology)

This parameter denotes the ontology used to give a meaning to the symbols in the content expression.

Note: The ontology parameter is used in conjunction with the language parameter to support the interpretation of the content expression by the receiving agent. In many situations, the ontology parameter will be commonly understood by the agent community and so this message parameter may be omitted.

Parameters:

ontology - A string representing the ontology of this message.

setPerformative

public void setPerformative(Performative p)

The performative parameter denotes the type of the communicative act of the ACL message as defied by FIPA00037.

Note: The performative parameter is a required parameter of all ACL messages.

Parameters:

performative - An integer identifying the FIPA performative to be set to this message. Remember to use the set of constants provided by this class.

See Also:

FIPA Communicative Act Library Specification

setProtocol

public void setProtocol(java.lang.String protocol)

This parameter denotes the interaction protocol that the sending agent is employing with this ACL message. Some standard FIPA interaction protocols are: Request, Query, Request When, Contract Net, Subscribe, Propose, Auction etc.

Any ACL message that contains a non-null value for the protocol parameter is considered to belong to a conversation and it is required to respect the following rules:

• the initiator of the protocol must assign a non-null value to the conversation-id parameter,
• all responses to the message, within the scope of the same interaction protocol, should contain the same value for the conversation-id parameter, and,
• the timeout value in the reply-by parameter must denote the latest time by which the sending agent would like to have received the next message in the protocol flow (not be confused with the latest time by which the interaction protocol should terminate).

Note: The protocol parameter defines the interaction protocol in which the ACL message is generated. This parameter is optional; however, developers are advised that employing ACL without the framework of an interaction protocol (and thus directly using the ACL semantics to control the agent’s generation and interpretation of ACL messages) is an extremely ambitious undertaking.

See Also:

FIPA00026: FIPA Request Interaction Protocol Specification, FIPA00027: FIPA Query Interaction Protocol Specification, FIPA00028: FIPA Request When Interaction Protocol Specification, FIPA00029: FIPA Contract Net Interaction Protocol Specification, FIPA00030: FIPA Iterated Contract Net Interaction Protocol Specification, FIPA00031: FIPA English Auction Interaction Protocol Specification, FIPA00032: FIPA Dutch Auction Interaction Protocol Specification, FIPA00033: FIPA Brokering Interaction Protocol Specification, FIPA00034: FIPA Recruiting Interaction Protocol Specification, FIPA00035: FIPA Subscribe Interaction Protocol Specification, FIPA00036: FIPA Propose Interaction Protocol Specification, FIPA00025: FIPA Interaction Protocol Library Specification (Deprecated)

setReplyBy

public void setReplyBy(java.util.Date date)

The reply-by parameter denotes a time and/or date expression which indicates the latest time by which the sending agent would like to receive a reply.

Notes: The time will be expressed according to the sender's view of the time on the sender's platform. The reply message can be identified in several ways: as the next sequential message in an interaction protocol, through the use of the reply-with parameter, through the use of a conversation-id and so forth. The way that the reply message is identified is determined by the agent implementer.

Parameters:

replyBy - A java.util.Date representing the reply-by parameter of this message.

setReplyBy

public void setReplyBy(long millis)

The reply-by parameter denotes a time and/or date expression which indicates the latest time by which the sending agent would like to receive a reply.

Notes: The time will be expressed according to the sender's view of the time on the sender's platform. The reply message can be identified in several ways: as the next sequential message in an interaction protocol, through the use of the reply-with parameter, through the use of a conversation-id and so forth. The way that the reply message is identified is determined by the agent implementer.

Parameters:

replyBy - The number of milliseconds since January 1, 1970, 00:00:00 GMT representing the reply-by parameter of this message.

setReplyBy

public void setReplyBy(java.lang.String str)
                throws java.lang.IllegalArgumentException

The reply-by parameter denotes a time and/or date expression which indicates the latest time by which the sending agent would like to receive a reply.

Notes: The time will be expressed according to the sender's view of the time on the sender's platform. The reply message can be identified in several ways: as the next sequential message in an interaction protocol, through the use of the reply-with parameter, through the use of a conversation-id and so forth. The way that the reply message is identified is determined by the agent implementer.

Parameters:

replyBy - A java.util.Date representing the reply-by parameter of this message.

Throws:

java.lang.IllegalArgumentException

setReplyWith

public void setReplyWith(java.lang.String replyWith)

The reply-with parameter introduces an expression that will be used by the responding agent to identify this message.

The reply-with parameter is designed to be used to follow a conversation thread in a situation where multiple dialogues occur simultaneously. For example, if agent i sends to agent j a message which contains: reply-with <expr>. Agent j will respond with a message containing: in-reply-to <expr>.

Parameters:

replyWith - A string representing the reply-with parameter of this message.

setSender

public void setSender(AID sender)

The sender parameter denotes the identity of the sender of the message, i.e. the agent which performs the communicative act giving rise to this ACL message.

Note:The sender parameter will be a parameter of most ACL messages. It is possible to omit the sender parameter if, for example, the agent sending the ACL message wishes to remain anonymous.

Parameters:

sender - The AID of the sender of this message.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

See Also:

FIPA ACL Message Representation in String Specification