com.ls.lars.communication
Class Message

java.lang.Object
  |
  +--com.ls.lars.communication.Message
All Implemented Interfaces:
Cloneable, Comparable, Serializable
Direct Known Subclasses:
GroupMessage, MulticastMessage, ServiceMessage, SingleMessage

public abstract class Message
extends Object
implements Serializable, Comparable, Cloneable

Message object for the communication between the agents.

Note, that the Message object is not synchronized!

Standard for naming message services:

This standard is needed for automatic registration of "interpret"-methods in agents.

Version:
$Revision: 1.32 $
Author:
Last modified by $Author: ODrugan $
See Also:
Serialized Form

Field Summary
static String ADDRESS_CONFIG
          used as sender address, if this message was read from a config file
static String ADDRESS_LARS_INTERNAL
          used as receiver or sender address, if this message is used only lars internal
static short EXPIRE_HOPS_DEFAULT
          default value: how many hops a Message is allowed to do, before it expires
static String MESSAGE_TYPE_GROUP
          identifies a SingleMessage in a Map- or XML-representation of the message
static String MESSAGE_TYPE_MULTICAST
          identifies a SingleMessage in a Map- or XML-representation of the message
static String MESSAGE_TYPE_SERVICE_BROADCAST
          identifies a ServiceBroadcastMessage in a Map- or XML-representation of the message
static String MESSAGE_TYPE_SERVICE_SINGLE
          identifies a ServiceSingleMessage in a Map- or XML-representation of the message
static String MESSAGE_TYPE_SINGLE
          identifies a SingleMessage in a Map- or XML-representation of the message
static short PRIORITY_HIGH
          maximum priority for a message
static short PRIORITY_LOW
          lowest priority for a message
static short PRIORITY_NORMAL
          normal (default) priority for a message
static short PRIORITY_SYSTEM
          system priority: DO NOT USE THIS for agents!
static String PRIORITY_TEXT_HIGH
          identifies a high message priority
static String PRIORITY_TEXT_LOW
          identifies a low message priority
static String PRIORITY_TEXT_NORMAL
          identifies a normal message priority
static String SERVICE_UNKNOWN
          used as service, if this message's service is unset
static String TAG_CONTENT
          string that represent the "content"
static String TAG_CURRENT_HOPS
          string that represent the "currentHops"
static String TAG_EXPIRE_HOPS
          string that represent the "expireHops"
static String TAG_FORWARDED_BY
          string that represent the "forwardedBy"
static String TAG_IN_REPLY_TO
          string that represent the "inReplyTo"
static String TAG_MESSAGE
          string that represent the "mesage"
static String TAG_PRIORITY
          string that represent the "priority"
static String TAG_QUALITY_OF_SERVICE
          string that represent the "qualityOfService"
static String TAG_REPLY_COUNTER
          string that represent the "replyCounter"
static String TAG_REPLY_WITH
          string that represent the "replyWith"
static String TAG_SENDER
          string that represent the "sender"
static String TAG_SENT_TIME
          string that represent the "sentTime"
static String TAG_SERVICE
          string that represent the "service"
static String TAG_TYPE
          string that represent the "type"
 
Constructor Summary
protected Message(Map messageHash)
          Creates a message object from a Map.
protected Message(String service, Object content)
          sets all fields of a message including the content object
 
Method Summary
 Object clone()
          Returns a new message that is the clone of this message.
 int compareTo(Object other)
          Compares this message to another Object.
protected static Message createMessage(Map messageMap)
          Creates a message object from a Map by calling different constructors depending on the specified message type.
 SingleMessage createReply(String service, Object content)
          Creates a new SingleMessage object, which is a reply to the message from which is invoked.
 Object getContent()
          Returns the content of this message.
 short getCurrentHops()
          returns the number of hops this message already did
 short getExpireHops()
          returns the number of hops this message is allowed to do before it expires
 List getForwardedBy()
          returns an unmodifiable list of all forwarders or null, if the message wasn't forwarded
 String getInReplyTo()
          returns the inReplyTo field of this message
 short getPriority()
          returns the priority of this message
 int getQualityOfService()
          returns the qualityOfService field of this message
 String getReplyWith()
          returns the replyWith field of this message
 String getSender()
          returns the name of this sender agent
 long getSentTime()
          returns the time, when this message was sent (in ms since 01.01.1970)
 String getService()
          returns the service of this message
 boolean hasInvalidSender()
          Rudimentary checks this message, if it contains an invalid sender address.
 void hop()
          Counts a message hop.
 void increasePriority()
          Increases the priority of this message to avoid starvation.
protected abstract  Map inheritorToMap()
          returns a new map containing the message-inheritor specific fields (usually the type and the recipient, which is a group or an agent name or ...)
protected abstract  String inheritorToString()
          returns a well formatted string containing the message-inheritor specific fields (usually the type and the recipient, which is a group or an agent name or ...)
 boolean isExpired()
          checks expiration of this message regarding the number of hops (Messengers, the Message passed on it's way) compared to the number of allowed hops
 boolean isSent()
          checks, if thie message was already sent
 void setExpireHops(short expireHops)
          sets the number of hops this message is allowed to do before it expires
 void setInReplyTo(String inReplyTo)
          Sets a inReplyTo for this request message.
 void setPriority(short priority)
          sets a new priority for this message
 void setPriority(String priority)
          Sets a new priority for this message.
 void setQualityOfService(int qualityOfService)
          Sets the qualityOfService tag of this message.
 void setQualityOfService(String qualityOfService)
          Sets the qualityOfService tag of this message.
 void setReplyWith(String replyWith)
          sets a replyWith for this request message
 void setSystemPriority()
          Do not use this method for sending Messages between agents - this method sets the highest available priority a message can obtain and is reserved for lars-internal Messages only.
 Map toMap()
          returns the complete message as a Map
 String toString()
          Returns a well formatted string of this message.
 String toStringWithContent()
          Returns a well formatted string of this message including (if existent) the content.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

TAG_MESSAGE

public static final String TAG_MESSAGE
string that represent the "mesage"

TAG_SERVICE

public static final String TAG_SERVICE
string that represent the "service"

TAG_TYPE

public static final String TAG_TYPE
string that represent the "type"

TAG_SENDER

public static final String TAG_SENDER
string that represent the "sender"

TAG_FORWARDED_BY

public static final String TAG_FORWARDED_BY
string that represent the "forwardedBy"

TAG_REPLY_WITH

public static final String TAG_REPLY_WITH
string that represent the "replyWith"

TAG_IN_REPLY_TO

public static final String TAG_IN_REPLY_TO
string that represent the "inReplyTo"

TAG_REPLY_COUNTER

public static final String TAG_REPLY_COUNTER
string that represent the "replyCounter"

TAG_PRIORITY

public static final String TAG_PRIORITY
string that represent the "priority"

TAG_QUALITY_OF_SERVICE

public static final String TAG_QUALITY_OF_SERVICE
string that represent the "qualityOfService"

TAG_SENT_TIME

public static final String TAG_SENT_TIME
string that represent the "sentTime"

TAG_CURRENT_HOPS

public static final String TAG_CURRENT_HOPS
string that represent the "currentHops"

TAG_EXPIRE_HOPS

public static final String TAG_EXPIRE_HOPS
string that represent the "expireHops"

TAG_CONTENT

public static final String TAG_CONTENT
string that represent the "content"

PRIORITY_SYSTEM

public static final short PRIORITY_SYSTEM
system priority: DO NOT USE THIS for agents!

PRIORITY_HIGH

public static final short PRIORITY_HIGH
maximum priority for a message

PRIORITY_NORMAL

public static final short PRIORITY_NORMAL
normal (default) priority for a message

PRIORITY_LOW

public static final short PRIORITY_LOW
lowest priority for a message

PRIORITY_TEXT_HIGH

public static final String PRIORITY_TEXT_HIGH
identifies a high message priority

PRIORITY_TEXT_NORMAL

public static final String PRIORITY_TEXT_NORMAL
identifies a normal message priority

PRIORITY_TEXT_LOW

public static final String PRIORITY_TEXT_LOW
identifies a low message priority

EXPIRE_HOPS_DEFAULT

public static final short EXPIRE_HOPS_DEFAULT
default value: how many hops a Message is allowed to do, before it expires

MESSAGE_TYPE_SINGLE

public static final String MESSAGE_TYPE_SINGLE
identifies a SingleMessage in a Map- or XML-representation of the message

MESSAGE_TYPE_SERVICE_SINGLE

public static final String MESSAGE_TYPE_SERVICE_SINGLE
identifies a ServiceSingleMessage in a Map- or XML-representation of the message

MESSAGE_TYPE_SERVICE_BROADCAST

public static final String MESSAGE_TYPE_SERVICE_BROADCAST
identifies a ServiceBroadcastMessage in a Map- or XML-representation of the message

MESSAGE_TYPE_GROUP

public static final String MESSAGE_TYPE_GROUP
identifies a SingleMessage in a Map- or XML-representation of the message

MESSAGE_TYPE_MULTICAST

public static final String MESSAGE_TYPE_MULTICAST
identifies a SingleMessage in a Map- or XML-representation of the message

ADDRESS_CONFIG

public static final String ADDRESS_CONFIG
used as sender address, if this message was read from a config file

ADDRESS_LARS_INTERNAL

public static final String ADDRESS_LARS_INTERNAL
used as receiver or sender address, if this message is used only lars internal

SERVICE_UNKNOWN

public static final String SERVICE_UNKNOWN
used as service, if this message's service is unset
Constructor Detail

Message

protected Message(String service,
                  Object content)
           throws InvalidArgumentException
sets all fields of a message including the content object
Parameters:
service - service of the message
content - content of the message as a hash
Throws:
InvalidArgumentException - if given service is null or empty or contains only whitespace characters

Message

protected Message(Map messageHash)
           throws InvalidArgumentException
Creates a message object from a Map.
Note: For security reasons this constructor is package private.
Parameters:
messageHash - a map with (at least) service, sender and content key.
Throws:
InvalidArgumentException - if given messageHash is null or if any of the required values do not fulfill the needs of a message (e.g. the service/content/sender is not specified)
Method Detail

createMessage

protected static Message createMessage(Map messageMap)
                                throws InvalidArgumentException
Creates a message object from a Map by calling different constructors depending on the specified message type. The default type, that is used, if not type is specified, is SingleMessage
Note: For security reasons this "factory" is package private.
Parameters:
messageMap - A map with (at least) type, service and sender key. If there is no priority specified, the default priority will be set.
Returns:
newly generated message object containing the attributes from the given map
Throws:
InvalidArgumentException - if given messageMap is null or if any of the required values do not fulfill the needs of the specific message type (e.g. the service/sender is not specified)

clone

public Object clone()
Returns a new message that is the clone of this message.

Warning: If the content is an instance of Collection, the content of the new message is exactly the same Object as the source message's content. Therefore modifying one message's content will result in a modification of the copied content.

Overrides:
clone in class Object
Returns:
a clone of this message instance
See Also:
Object.clone()

getService

public final String getService()
returns the service of this message
Returns:
Service of this message

getSender

public final String getSender()
returns the name of this sender agent
Returns:
name of this sender agent

getForwardedBy

public List getForwardedBy()
returns an unmodifiable list of all forwarders or null, if the message wasn't forwarded
Returns:
unmodifiable list of all forwarders (may be null!)

setReplyWith

public final void setReplyWith(String replyWith)
                        throws InvalidArgumentException,
                               ProgrammingException
sets a replyWith for this request message
Parameters:
replyWith - reply ID to use when answering to this message
Throws:
InvalidArgumentException - if given replyId is null or empty or contains only whitespace characters
ProgrammingException - if this message was already sent

getReplyWith

public final String getReplyWith()
returns the replyWith field of this message
Returns:
replyWith field of this message (may be null!)

setInReplyTo

public final void setInReplyTo(String inReplyTo)
                        throws ProgrammingException
Sets a inReplyTo for this request message. Do not use this method, if you have an original message, whereon you can call createReply() upon!
Parameters:
inReplyTo - reply ID to use for this message (answer), may be null
Throws:
ProgrammingException - if this message was already sent

getInReplyTo

public final String getInReplyTo()
returns the inReplyTo field of this message
Returns:
inReplyTo field of this message (may be null!)

setQualityOfService

public void setQualityOfService(int qualityOfService)
                         throws ProgrammingException
Sets the qualityOfService tag of this message.
Parameters:
qualityOfService - specifies, in which cases the systems needs to send a reply to this message
Throws:
ProgrammingException - if this message was already sent
See Also:
QualityOfService

setQualityOfService

public void setQualityOfService(String qualityOfService)
Sets the qualityOfService tag of this message. If the qualityOfService argument is null, the method returns without modifying anything. Otherwise the value of this.qualityOfService is determined with help of Integer.parseInt(qualityOfService).
Parameters:
qualityOfService - specifies, in which cases the systems needs to send a reply to this message
See Also:
QualityOfService

getQualityOfService

public final int getQualityOfService()
returns the qualityOfService field of this message
Returns:
qualityOfService field of this message

setPriority

public final void setPriority(short priority)
                       throws InvalidArgumentException
sets a new priority for this message
Parameters:
priority - new priority for this message, e.g. PRIORITY_LOW
Throws:
InvalidArgumentException - if given priority is negative
See Also:
PRIORITY_LOW, PRIORITY_NORMAL, PRIORITY_HIGH

setSystemPriority

public final void setSystemPriority()
Do not use this method for sending Messages between agents - this method sets the highest available priority a message can obtain and is reserved for lars-internal Messages only.

setPriority

public final void setPriority(String priority)
                       throws InvalidArgumentException
Sets a new priority for this message.
Note: If the given priority is null, the method does nothing.
Parameters:
priority - new priority for this message
Throws:
InvalidArgumentException - if given priority is neither parseable to a short nor PRIORITY_HIGH nor PRIORITY_NORMAL nor PRIORITY_LOW nor null
See Also:
PRIORITY_TEXT_LOW, PRIORITY_TEXT_NORMAL, PRIORITY_TEXT_HIGH, PRIORITY_LOW, PRIORITY_NORMAL, PRIORITY_HIGH

getPriority

public final short getPriority()
returns the priority of this message
Returns:
priority of this message

getSentTime

public final long getSentTime()
returns the time, when this message was sent (in ms since 01.01.1970)
Returns:
time, when this message was sent (-1, if message is unsent yet)

getCurrentHops

public final short getCurrentHops()
returns the number of hops this message already did
Returns:
number of hops this message already did

setExpireHops

public final void setExpireHops(short expireHops)
                         throws ProgrammingException
sets the number of hops this message is allowed to do before it expires
Parameters:
expireHops - number of hops this message is allowed to do
Throws:
ProgrammingException - if this message was already sent

getExpireHops

public final short getExpireHops()
returns the number of hops this message is allowed to do before it expires
Returns:
number of hops this message is allowed to do

getContent

public final Object getContent()
Returns the content of this message.
Note, that the receiver of a message needs to know the type of the content of that message and cast it himself, e.g. try { contentMap = (Map) message.getContent(); } catch (ClassCastException ccex) { ... [ do whatever needed ] ... }
Returns:
Content object of this message

createReply

public final SingleMessage createReply(String service,
                                       Object content)
                                throws InvalidArgumentException,
                                       ProgrammingException
Creates a new SingleMessage object, which is a reply to the message from which is invoked. Therefore it sets the sender of this message as receiver of the new message, sets the inReplyTo field of the new message to this.replyWith and increasees the reply counter of this message by 1.
Parameters:
service - specifies the new service
content - body of the message
Returns:
message object that is the reply to the current message
Throws:
InvalidArgumentException - if given service is null or empty or contains only whitespace characters
ProgrammingException - if this message was not yet sent

hasInvalidSender

public final boolean hasInvalidSender()
Rudimentary checks this message, if it contains an invalid sender address. A sender address is assumed to be invalid, if any of the following cases is true: sender ...
Returns:
true, if one of the cases above evaluates to true; false else

hop

public final void hop()
               throws MessageException
Counts a message hop. This method is to be called each time this message is sent or forwarded by any component of the lars system.
Throws:
MessageException - if this message has passed too many messengers (hop counter is expired)
See Also:
isExpired()

increasePriority

public final void increasePriority()
Increases the priority of this message to avoid starvation. (This method is called in Messenger.getInboxMessage for each Message, that is in the inbox of that Messenger.)

inheritorToMap

protected abstract Map inheritorToMap()
returns a new map containing the message-inheritor specific fields (usually the type and the recipient, which is a group or an agent name or ...)
Returns:
Message-inheritor specific fields as a Map

toMap

public Map toMap()
returns the complete message as a Map
Returns:
complete message as a Map

isExpired

public final boolean isExpired()
checks expiration of this message regarding the number of hops (Messengers, the Message passed on it's way) compared to the number of allowed hops
Returns:
true, if Message is expired; false else

isSent

public final boolean isSent()
checks, if thie message was already sent
Returns:
true, if Message is expired; false else

compareTo

public final int compareTo(Object other)
                    throws ClassCastException
Compares this message to another Object.

Note: This comparision is not consistent with the equals method - it is possible, that two messages that are not equal (in the way Message.equals() determines equality) may get a return value of 0, if their priority is the same and their sentTime (in milliseconds since 01.01.1970) is the same, too (though this case is very unlikely to happen ;-).

Specified by:
compareTo in interface Comparable
Parameters:
other - object to this should be compared to
Returns:
A negative integer, zero, or a positive integer as this message is less than, equal to, or greater than the argument. The first comparision criteria is the message priority, the second one is the time, when the message got sent. (If a Message is yet unsent, this is treated as a maximum value for the second sort criteria.)
Throws:
ClassCastException - if the given object is not a message, because messages are only comparable to other messages

inheritorToString

protected abstract String inheritorToString()
returns a well formatted string containing the message-inheritor specific fields (usually the type and the recipient, which is a group or an agent name or ...)
Returns:
Message-inheritor specific fields as a well-formatted string

toString

public final String toString()
Returns a well formatted string of this message.
Note, that the content attribute of the message is only logged if the systems log level is TRACE5.
Overrides:
toString in class Object
Returns:
well formatted string of this message
See Also:
SystemLogger

toStringWithContent

public final String toStringWithContent()
Returns a well formatted string of this message including (if existent) the content.
Returns:
well formatted string of this message