public abstract class MLMessage extends Object implements Cloneable, Describable
Copyright: Copyright 2003-2014, Knowledge Science Group, University of Calgary. Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. The Knowledge Science Group makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.
Modifier and Type | Class and Description |
---|---|
static class |
MLMessage.Languages |
Modifier and Type | Field and Description |
---|---|
(package private) static Map<String,Class<?>> |
knownSubclasses |
private static String |
markupLanguage
String used to determine if the message being sent is using XML or strict KQML.
|
protected TreeMap<String,String> |
parameters
Stores all of the parameters this message contains (including "performative").
|
Constructor and Description |
---|
MLMessage()
Constructor
|
MLMessage(String... list)
Constructs a message from an array of Strings, which is interpreted as key/value
pairs.
|
Modifier and Type | Method and Description |
---|---|
MLMessage |
clone() |
private <T> void |
conditionalMove(Vector<T> parameters,
Vector<T> sortedParameters,
T parameter)
If the
parameter given exists in parameters ,
move it from parameters to sortedParameters . |
static MLMessage |
constructBasicProxyMessage(MLMessage message,
URLDescriptor sender,
URLDescriptor proxyReciever,
URLDescriptor finalReciever) |
static MLMessage |
constructProxyMessage(MLMessage message,
URLDescriptor sender,
URLDescriptor proxyReciever,
String finalRecieverDescription) |
static MLMessage |
constructReplyTo(MLMessage m,
String replyWith,
URLDescriptor originator)
|
String |
displayString() |
boolean |
equals(MLMessage o) |
boolean |
equals(Object o) |
Pair<URLDescriptor,MLMessage> |
extractBasicProxyInformation()
Attempts to decode the proxy information from the content field into a
URLDescriptor and an MLMessage . |
static Pair<URLDescriptor,MLMessage> |
extractBasicProxyInformation(String contents)
Attempts to decode the proxy information from the string provided into a
URLDescriptor and an MLMessage . |
Pair<String,MLMessage> |
extractProxyInformation()
|
static Pair<String,MLMessage> |
extractProxyInformation(String contents)
|
static MLMessage |
fromString(String text) |
abstract void |
fromStringLocal(String source) |
Act |
getAct()
Returns the value from the act field of the message as an Act object.
|
Object |
getContent() |
String |
getConversationID()
Returns the value from the conversation-id field as a string
|
URLDescriptor |
getFrom()
Returns a
URLDescriptor from the REPLY-TO field; but if the REPLY-TO field is empty or missing
returns the value from the SENDER field. |
String |
getFromString()
Returns the contents of the REPLY-TO field; but if the REPLY-TO field is empty or missing
returns the value from the SENDER field.
|
int |
getIntParameter(String key,
int defaultValue) |
long |
getLongParameter(String key,
int defaultValue) |
static String |
getMarkupLanguage()
Simple accessor function for the markupLanguage field.
|
static MLMessage |
getNewMLMessage()
Method for creating a new MLMessage of the default type (see setMarkupLanguage()).
|
static MLMessage |
getNewMLMessage(String... list)
Method for creating a new MLMessage depending on the messageType.
|
static MLMessage |
getNewMLMessageType(String markupLanguage)
Method for creating a new MLMessage depending on the messageType.
|
static MLMessage |
getNewMLMessageType(String markupLanguage,
String... list)
Method for creating a new MLMessage depending on the messageType.
|
String |
getParameter(String key)
Retrieves a parameter of this message.
|
Object |
getParameter(String key,
Class<?> cls) |
PerformDescriptor |
getPerformDescriptorParameter(String key) |
PerformDescriptor |
getPerformDescriptorParameter(String key,
PerformDescriptor defaultValue) |
int |
getPriority() |
URLDescriptor |
getReceiver()
Returns a
URLDescriptor from the RECEIVER field. |
URLDescriptor |
getReplyTo()
Returns the contents of the REPLY-TO field; but if the REPLY-TO field is empty or missing
returns the value from the SENDER field.
|
URLDescriptor |
getSender()
Returns a
URLDescriptor from the SENDER field. |
Vector<String> |
getSortedParameterList()
Returns a list of all message parameters other than ML.PERFORMATIVE in
the correct order.
|
Status |
getStatusParameter(String key) |
Status |
getStatusParameter(String key,
Status defaultValue) |
long |
getTimeout()
Returns the value from the reply-by field of the message as a long.
|
long |
getTimeout(AbstractProcess agent)
Returns the value from the reply-by field of the message as a long.
|
URLDescriptor |
getTo()
Returns a
URLDescriptor from the TO field; but if the TO field is empty or missing or contains a '*'
returns the value from the RECIEVER field. |
URLDescriptor |
getURLParameter(String key) |
URLDescriptor |
getURLParameter(String key,
URLDescriptor defaultValue) |
int |
hashCode() |
boolean |
hasPriority() |
boolean |
isAddressedTo(URLDescriptor url) |
boolean |
isBroadcast()
Determines if this this mask is a broadcast message (designated
to all possible recipients, i.e.
|
boolean |
isReplyTo(MLMessage original) |
Set<String> |
keySet() |
static String |
longToTextDate(long val) |
Enumeration<String> |
parameters()
Retrieve a list of all parameters specified in this message.
|
String |
peekAct() |
String |
popAct()
Pops off an act
|
static String |
prettyfy(String key,
String value)
Utility method to returns an appropriate field value for the given key and value for use
with pretty print format.
|
Act |
pushAct(String token) |
void |
removeParameter(String key)
Removes the given parameter from the message.
|
void |
reset() |
MLMessage |
reverseDirection() |
void |
setContent(Object object,
MLMessage.Languages language) |
private static void |
setIf(MLMessage m,
String key,
String newVal)
Sets the parameter of the message only if the given string is not
null . |
static void |
setMarkupLanguage(String markup)
Simple set function to change the markup language to be used.
|
void |
setParameter(String parameter,
String value)
Sets a parameter in the message.
|
void |
setParameters(Map<?,?> list) |
void |
setParameters(Map<?,?> list,
String performativeConstraint,
String actConstraint,
PolicyAgentInterface agent) |
MLMessage |
setParameters(String... list)
Adds a parameters to a MLMessage from an array of Strings, which is
interpreted as key/value pairs.
|
void |
setPriority(int priority) |
private void |
swap(String tag1,
String tag2) |
String |
toString()
Abstract Methods
|
abstract String |
toString(boolean prettyPrint) |
private static String markupLanguage
protected TreeMap<String,String> parameters
public MLMessage()
public MLMessage(String... list)
list
- a String array of keys and values as alternating elementsException
- if a key is null or there's an odd number of elements in the arraypublic MLMessage clone()
clone
in interface Describable
clone
in class Object
public MLMessage reverseDirection()
public static MLMessage constructReplyTo(MLMessage m, String replyWith, URLDescriptor originator)
ML.AGREE
reply MLMessage
using the input MLMessage
m. The new message is a copy of m with the following exceptions:
ML.PERFORMATIVE
is removed -- you have to set it yourself. (formally set to ML.AGREE
)
ML.ACT
set to m's ML.PERFORMATIVE
pushed onto m's original ML.ACT
ML.SENDER
set to: if originator is not null then originator
else the value of m's ML.RECEIVER
ML.RECEIVER
set to: if m's is not null, then m's
ML.REPLY_TO
else m's ML.SENDER
ML.IN_REPLY_TO
set to: in m's ML.REPLY_WITH
is set, then m's
ML.REPLY_WITH
else it is left unfilled (absent)
ML.REPLY_WITH
set to: if replyWith is not null, then the value
of replyWith else it is left unfilled (absent)
ML.RECIPIENTS
ML.REPLY_TO
ML.FROM
m
- The MLMessage
to be used a model to construct the reply toreplyWith
- The value to put in the ML.REPLY_WITH
feild if the returnoriginator
- The URL of the agent sending the returnMLMessage
that is a proper ML.AGREE
reply to mpublic static Pair<URLDescriptor,MLMessage> extractBasicProxyInformation(String contents)
URLDescriptor
and an MLMessage
.contents
- The string containing the encoded proxy information.URLDescriptor
and an MLMessage
if extraction was successful; null
otherwise.public static MLMessage constructProxyMessage(MLMessage message, URLDescriptor sender, URLDescriptor proxyReciever, String finalRecieverDescription)
public static MLMessage constructBasicProxyMessage(MLMessage message, URLDescriptor sender, URLDescriptor proxyReciever, URLDescriptor finalReciever)
public static Pair<String,MLMessage> extractProxyInformation(String contents)
public Pair<URLDescriptor,MLMessage> extractBasicProxyInformation()
URLDescriptor
and an MLMessage
.contents
- The string containing the encoded proxy information.URLDescriptor
and an MLMessage
if extraction was successful; null
otherwise.private static void setIf(MLMessage m, String key, String newVal)
null
.m
- The message to conditionally modify.key
- The name of tghe parameter to conditionally change.newVal
- The new value of the parameter.public boolean equals(Object o)
equals
in class Object
equals(Object)
, EXCEPT the :REPLY-BY field (that is, the :REPLY-BY field is ignored).public boolean equals(MLMessage o)
o
- the "other" message.equals(Object)
, EXCEPT the :REPLY-BY field (that is, the :REPLY-BY field is ignored).public static String getMarkupLanguage()
public static void setMarkupLanguage(String markup) throws MLTypeException
markup
- contains the specified language to be used, either XML or KQML.MLTypeException
- if markup is anything other than "XML" or a registered
markup language (from preferences or from a detected subtype of MLMessage
.public static MLMessage getNewMLMessageType(String markupLanguage) throws MLTypeException
markupLanguage
- Determines if the MLMessage is an XMLMessage, or a KQMLMessageIllegalOperationException
MLTypeException
public static MLMessage getNewMLMessageType(String markupLanguage, String... list) throws MLTypeException
markupLanguage
- Determines if the MLMessage is an XMLMessage, or a KQMLMessageIllegalOperationException
MLTypeException
public static MLMessage getNewMLMessage(String... list)
markupLanguage
- Determines if the MLMessage is an XMLMessage, or a KQMLMessageIllegalOperationException
public void reset()
public static MLMessage getNewMLMessage()
public void setParameter(String parameter, String value)
setParameter
in interface Describable
parameter
- name of the parameter to set/addvalue
- string value to associate with the parameterpublic MLMessage setParameters(String... list)
list
- a String array of keys and values as alternating elementsException
- if a key is null or there's an odd number of elements in the arraypublic void setParameters(Map<?,?> list, String performativeConstraint, String actConstraint, PolicyAgentInterface agent) throws IllegalArgumentException
IllegalArgumentException
public void setParameters(Map<?,?> list)
public String getParameter(String key)
getParameter
in interface Describable
key
- String indication which parameter to retrieve.public Object getParameter(String key, Class<?> cls) throws ParseException
ParseException
public URLDescriptor getURLParameter(String key) throws ParseException, ClassCastException
ParseException
ClassCastException
public URLDescriptor getURLParameter(String key, URLDescriptor defaultValue)
public PerformDescriptor getPerformDescriptorParameter(String key) throws Exception
Exception
public PerformDescriptor getPerformDescriptorParameter(String key, PerformDescriptor defaultValue)
public int getIntParameter(String key, int defaultValue)
public long getLongParameter(String key, int defaultValue)
public void removeParameter(String key)
key
- String indicating which parameter to remove.public Enumeration<String> parameters()
public Set<String> keySet()
keySet
in interface Describable
public Vector<String> getSortedParameterList()
MLMessage.toString()
,
xmlmessage.dtd
private <T> void conditionalMove(Vector<T> parameters, Vector<T> sortedParameters, T parameter)
parameter
given exists in parameters
,
move it from parameters
to sortedParameters
.parameters
- The Vector to move the
parameter
from.
sortedParameters
- The Vector
to move the
parameter
to if it was in parameters
.parameter
- The String
that is to be moved from
parameters
to sortedParameters
.public static String longToTextDate(long val)
public String displayString()
toString(boolean)
public abstract String toString(boolean prettyPrint)
public static String prettyfy(String key, String value)
key
- value
- public abstract void fromStringLocal(String source) throws MLMessageFormatException
MLMessageFormatException
public static MLMessage fromString(String text) throws MLMessageFormatException
MLMessageFormatException
public URLDescriptor getFrom() throws URLDescriptorException
URLDescriptor
from the REPLY-TO field; but if the REPLY-TO field is empty or missing
returns the value from the SENDER field.URLDescriptorException
- if a URLDescriptor cannot be constructed from the one in the messageURLDescriptor
,
URLDescriptorException
public String getFromString()
public URLDescriptor getReplyTo() throws URLDescriptorException
URLDescriptorException
- if a URLDescriptor cannot be constructed from the one in the messageURLDescriptor
,
URLDescriptorException
public URLDescriptor getTo() throws URLDescriptorException
URLDescriptor
from the TO field; but if the TO field is empty or missing or contains a '*'
returns the value from the RECIEVER field.URLDescriptorException
- if a URLDescriptor cannot be constructed from the one in the messageURLDescriptor
,
URLDescriptorException
public URLDescriptor getSender() throws URLDescriptorException
URLDescriptor
from the SENDER field.URLDescriptorException
- if a URLDescriptor cannot be constructed from the one in the messageURLDescriptor
,
URLDescriptorException
public URLDescriptor getReceiver() throws URLDescriptorException
URLDescriptor
from the RECEIVER field.URLDescriptorException
- if a URLDescriptor cannot be constructed from the one in the messageURLDescriptor
,
URLDescriptorException
public Object getContent() throws ParseException, ClassNotFoundException
ParseException
ClassNotFoundException
public void setContent(Object object, MLMessage.Languages language)
public long getTimeout()
getTimeout(AbstractProcess)
public long getTimeout(AbstractProcess agent)
agent
- getTimeout()
public String getConversationID()
public Act getAct()
public Act pushAct(String token)
the
- new act to "push" onto the existing actpublic String popAct()
public String peekAct()
public boolean isReplyTo(MLMessage original)
public boolean hasPriority()
public int getPriority()
public void setPriority(int priority)
public boolean isBroadcast()
public boolean isAddressedTo(URLDescriptor url)