jade.lang.acl
Class MessageTemplate

java.lang.Object
  |
  +--jade.lang.acl.MessageTemplate
All Implemented Interfaces:
java.io.Serializable, Serializable

public class MessageTemplate
extends java.lang.Object
implements Serializable

A pattern for matching incoming ACL messages. This class allows to build complex slot patterns to select ACL messages. These patterns can then be used in receive() operations. This class provide one method for each attribute of an ACLMessage, that can be combined using the logic operators to create more complex patterns. A user can also create an application-specific pattern. In this case he has to implement the MatchExpression interface, writing the application specific match() method. Then an instance of that class can be used as parameter of the MessageTemplate constructor to define the application specific MessageTemaplate.

Version:
$Date: 2003/11/20 10:55:37 $ $Revision: 2.15 $
Author:
Giovanni Rimassa - Universita' di Parma, Tiziana Trucco - Telecom Italia Lab S.p.A.
See Also:
Agent.receive(MessageTemplate mt), Serialized Form

Nested Class Summary
static interface MessageTemplate.MatchExpression
          This interface must be overriden in order to define an application specific MessageTemplate.
 
Constructor Summary
MessageTemplate(MessageTemplate.MatchExpression e)
          Public constructor to use when the user needs to define an application specific pattern.
 
Method Summary
static MessageTemplate and(MessageTemplate op1, MessageTemplate op2)
          Logical and between two MessageTemplate objects.
 boolean match(ACLMessage msg)
          Matches an ACL message against this MessageTemplate object.
static MessageTemplate MatchAll()
          This Factory Method returns a message template that matches any message.
static MessageTemplate MatchContent(java.lang.String value)
          This Factory Method returns a message template that matches any message with a given :content slot.
static MessageTemplate MatchConversationId(java.lang.String value)
          This Factory Method returns a message template that matches any message with a given :conversation-id slot.
static MessageTemplate MatchCustom(ACLMessage msg, boolean matchPerformative)
          This Factory Method returns a message template that matches ACL messages against a given one, passed as parameter.
static MessageTemplate MatchEncoding(java.lang.String value)
          This Factory Method returns a message template that matches any message with a given :encoding slot.
static MessageTemplate MatchInReplyTo(java.lang.String value)
          This Factory Method returns a message template that matches any message with a given :in-reply-to slot.
static MessageTemplate MatchLanguage(java.lang.String value)
          This Factory Method returns a message template that matches any message with a given :language slot.
static MessageTemplate MatchOntology(java.lang.String value)
          This Factory Method returns a message template that matches any message with a given :ontology slot.
static MessageTemplate MatchPerformative(int value)
          This Factory Method returns a message template that matches any message with a given performative.
static MessageTemplate MatchProtocol(java.lang.String value)
          This Factory Method returns a message template that matches any message with a given :protocol slot.
static MessageTemplate MatchReceiver(AID[] values)
          This Factory Method returns a message template that matches any message with a given :receiver slot.
static MessageTemplate MatchReplyByDate(java.util.Date value)
          This Factory Method returns a message template that matches any message with a given :reply-by slot.
static MessageTemplate MatchReplyTo(AID[] values)
          This Factory Method returns a message template that matches any message with a given :reply-to slot.
static MessageTemplate MatchReplyWith(java.lang.String value)
          This Factory Method returns a message template that matches any message with a given :reply-with slot.
static MessageTemplate MatchSender(AID value)
          This Factory Method returns a message template that matches any message with a given :sender slot.
static MessageTemplate not(MessageTemplate op)
          Logical not of a MessageTemplate object.
static MessageTemplate or(MessageTemplate op1, MessageTemplate op2)
          Logical or between two MessageTemplate objects.
 java.lang.String toString()
          Retrieve a string representation of this message template.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

MessageTemplate

public MessageTemplate(MessageTemplate.MatchExpression e)
Public constructor to use when the user needs to define an application specific pattern.

Method Detail

MatchAll

public static MessageTemplate MatchAll()
This Factory Method returns a message template that matches any message.

Returns:
A new MessageTemplate matching any given value.

MatchSender

public static MessageTemplate MatchSender(AID value)
This Factory Method returns a message template that matches any message with a given :sender slot.

Parameters:
value - The value the message slot will be matched against.
Returns:
A new MessageTemplate matching the given value.

MatchReceiver

public static MessageTemplate MatchReceiver(AID[] values)
This Factory Method returns a message template that matches any message with a given :receiver slot.

Parameters:
values - An array of Agent IDs against which the value of the message slot will be matched.
Returns:
A new MessageTemplate matching the given value.

MatchContent

public static MessageTemplate MatchContent(java.lang.String value)
This Factory Method returns a message template that matches any message with a given :content slot.

Parameters:
value - The value the message slot will be matched against.
Returns:
A new MessageTemplate matching the given value.

MatchReplyWith

public static MessageTemplate MatchReplyWith(java.lang.String value)
This Factory Method returns a message template that matches any message with a given :reply-with slot.

Parameters:
value - The value the message slot will be matched against.
Returns:
A new MessageTemplate matching the given value.

MatchInReplyTo

public static MessageTemplate MatchInReplyTo(java.lang.String value)
This Factory Method returns a message template that matches any message with a given :in-reply-to slot.

Parameters:
value - The value the message slot will be matched against.
Returns:
A new MessageTemplate matching the given value.

MatchReplyTo

public static MessageTemplate MatchReplyTo(AID[] values)
This Factory Method returns a message template that matches any message with a given :reply-to slot.

Parameters:
values - An array of Agent IDs against which the value of the message slot will be matched.
Returns:
A new MessageTemplate matching the given value.

MatchLanguage

public static MessageTemplate MatchLanguage(java.lang.String value)
This Factory Method returns a message template that matches any message with a given :language slot.

Parameters:
value - The value the message slot will be matched against.
Returns:
A new MessageTemplate matching the given value.

MatchEncoding

public static MessageTemplate MatchEncoding(java.lang.String value)
This Factory Method returns a message template that matches any message with a given :encoding slot.

Parameters:
value - The value the message slot will be matched against.
Returns:
A new MessageTemplate matching the given value.

MatchOntology

public static MessageTemplate MatchOntology(java.lang.String value)
This Factory Method returns a message template that matches any message with a given :ontology slot.

Parameters:
value - The value the message slot will be matched against.
Returns:
A new MessageTemplate matching the given value.

MatchReplyByDate

public static MessageTemplate MatchReplyByDate(java.util.Date value)
This Factory Method returns a message template that matches any message with a given :reply-by slot.

Parameters:
value - The Date the message slot will be matched against.
Returns:
A new MessageTemplate matching the given value.

MatchProtocol

public static MessageTemplate MatchProtocol(java.lang.String value)
This Factory Method returns a message template that matches any message with a given :protocol slot.

Parameters:
value - The value the message slot will be matched against.
Returns:
A new MessageTemplate matching the given value.

MatchConversationId

public static MessageTemplate MatchConversationId(java.lang.String value)
This Factory Method returns a message template that matches any message with a given :conversation-id slot.

Parameters:
value - The value the message slot will be matched against.
Returns:
A new MessageTemplate matching the given value.

MatchPerformative

public static MessageTemplate MatchPerformative(int value)
This Factory Method returns a message template that matches any message with a given performative.

Parameters:
value - The value the message slot will be matched against.
Returns:
A new MessageTenplatematching the given value.

MatchCustom

public static MessageTemplate MatchCustom(ACLMessage msg,
                                          boolean matchPerformative)
This Factory Method returns a message template that matches ACL messages against a given one, passed as parameter. The following algorithm is used: When the given ACLMessage has a non null slot, subsequent messages must have the same slot value in that slot to have a match. When the given ACLMessage has a null slot, subsequent messages can have any value for that slot and still match the template. In short, a null value for a slot means don't care.

Parameters:
msg - The ACLMessage used to build a custom message template.
matchPerformative - a bool value. When true, the performative of the msg will be considered as a part of the template (i.e. the message template will match only ACL messages with the same performativa as msg). When , the performative of msg is ignored and the resulting message template will not consider it when matching messages.
Returns:
A new MessageTemplate, matching the given message according to the above algorithm.

and

public static MessageTemplate and(MessageTemplate op1,
                                  MessageTemplate op2)
Logical and between two MessageTemplate objects. This method creates a new message template that is matched by those ACL messages matching both message templates given as operands.

Parameters:
op1 - The first and operand.
op2 - The second and operand.
Returns:
A new MessageTemplate object.
See Also:
or(MessageTemplate op1, MessageTemplate op2)

or

public static MessageTemplate or(MessageTemplate op1,
                                 MessageTemplate op2)
Logical or between two MessageTemplate objects. This method creates a new message template that is matched by those ACL messages matching any of the two message templates given as operands.

Parameters:
op1 - The first or operand.
op2 - The second or operand.
Returns:
A new MessageTemplate object.
See Also:
and(MessageTemplate op1, MessageTemplate op2)

not

public static MessageTemplate not(MessageTemplate op)
Logical not of a MessageTemplate object. This method creates a new message template that is matched by those ACL messages not matching the message template given as operand.

Parameters:
op - The not operand.
Returns:
A new MessageTemplate object.

match

public boolean match(ACLMessage msg)
Matches an ACL message against this MessageTemplate object.

Parameters:
msg - The ACLMessage to check for matching.
Returns:
true if the ACL message matches this template, false otherwise.

toString

public java.lang.String toString()
Retrieve a string representation of this message template.

Overrides:
toString in class java.lang.Object
Returns:
A string describing the syntactic structure of this message template.


JADE