org.jlab.coda.cMsg
Class cMsgMessage

java.lang.Object
  extended by org.jlab.coda.cMsg.cMsgMessage
All Implemented Interfaces:
java.lang.Cloneable
Direct Known Subclasses:
cMsgMessageFull

public class cMsgMessage
extends java.lang.Object
implements java.lang.Cloneable

This class implements a message in the cMsg messaging system. Each cMsgMessage object contains many different fields. The most complex field (and thus deserving a full explanation) is the compound payload. In short, the payload allows the text field of the message to store messages of arbitrary length and complexity. All types of ints (1,2,4,8 bytes), 4,8-byte floats, strings, binary, whole messages and arrays of all these types can be stored and retrieved from the compound payload. These methods are thread-safe.

Although XML would be a format well-suited to this task, cMsg should stand alone - not requiring an XML parser to work. It takes more memory and time to decode XML than a simple format. Thus, a simple, easy-to-parse format was developed to implement this interface.

Following is the text format of a complete compound payload (where [nl] means newline). Each payload consists of a number of items. The very first line is the number of items in the payload. That is followed by the text representation of each item. The first line of each item consists of 5 entries.

Note that there is only 1 space or newline between all entries. The only exception to the 1 space spacing is between the last two entries on each "header" line (the line that contains the item_name). There may be several spaces between the last 2 entries on these lines.

    item_count[nl]

for string items:

    item_name   item_type   item_count   isSystemItem?   item_length[nl]
    string_length_1[nl]
    string_characters_1[nl]
     .
     .
     .
    string_length_N[nl]
    string_characters_N

for binary (converted into text) items:

    item_name   item_type   original_binary_byte_length   isSystemItem?   item_length[nl]
    string_length   endian[nl]
    string_characters[nl]

for primitive type items:

    item_name   item_type   item_count   isSystemItem?   item_length[nl]
    value_1   value_2   ...   value_N[nl]

A cMsg message is formatted as a compound payload. Each message has a number of fields (payload items).

for message items:

                                                                            _
    item_name   item_type   item_count   isSystemItem?   item_length[nl]   /
    message_1_in_compound_payload_text_format[nl]                         <  field_count[nl]
        .                                                                  \ list_of_payload_format_items
        .                                                                   -
        .
    message_N_in_compound_payload_text_format[nl]

Notice that this format allows a message to store a message which stores a message which stores a message, ad infinitum. In other words, recursive message storing. The item_length in each case is the length in bytes of the rest of the item (not including the newline at the end). Note that accessor methods can return null objects.

Version:
1.0
Author:
Elliott Wolin, Carl Timmer

Field Summary
static int allFields
          When converting text to message fields, convert all fields.
static int expandedPayload
          If the message has a compound payload, is the payload only in text form or has it been expanded into a hashtable of real objects? Is stored in the 7th bit of info.
static int hasPayload
          Does the message have a compound payload? -- is stored in 6th bit of info.
static int isBigEndian
          Is the byte array data in big endian form? -- stored in 4th bit of info.
static int isGetRequest
          Is message a sendAndGet request? -- stored in 1st bit of info.
static int isGetResponse
          Is message a response to a sendAndGet? -- stored in 2nd bit of info.
static int isNullGetResponse
          Is message null response to a sendAndGet? -- stored in 3rd bit of info.
static int payloadFieldsOnly
          When converting text to message fields, only convert non-system fields.
static int systemFieldsOnly
          When converting text to message fields, only convert system fields.
static int wasSent
          Has the message been sent over the wire? -- is stored in 5th bit of info.
 
Constructor Summary
cMsgMessage()
          The constructor for a blank message.
cMsgMessage(cMsgMessage msg)
          The constructor which copies a given message.
 
Method Summary
 void addPayloadItem(cMsgPayloadItem item)
          Adds an item to the payload.
 void addSenderToHistory(java.lang.String name)
          Adds a name to the history of senders of this message (in the payload).
 void clearPayload()
          Clears the payload of all user-added items.
 java.lang.Object clone()
          Cloning this object does not pass on the context except for the value of reliableSend and copies the byte array if it exists.
 cMsgMessage copy()
          Creates a complete copy of this message.
 void copyPayload(cMsgMessage msg)
          Copy only the payload of the given message, overwriting the existing payload.
 byte[] getByteArray()
          Get byte array of message.
 int getByteArrayEndian()
          Get endianness of the byte array data.
 int getByteArrayLength()
          Get byte array length of data of interest.
 int getByteArrayOffset()
          Get byte array index to data of interest.
 cMsgMessageContextInterface getContext()
          Gets the object containing information about the context of the callback receiving this message.
 java.lang.String getDomain()
          Get domain this message exists in.
 int getHistoryLengthMax()
          Gets the maximum number of entries this message keeps of its history of various parameters.
 int getInfo()
          Gets information compacted into a bit pattern.
 java.lang.String getItemsText()
          This method creates a string of all the payload items concatonated.
 cMsgPayloadItem getPayloadItem(java.lang.String name)
          Get a single, named payload item.
 java.util.Map<java.lang.String,cMsgPayloadItem> getPayloadItems()
          Gets an unmodifiable (read only) hashmap of all payload items.
 java.util.Set<java.lang.String> getPayloadNames()
          Get the set of payload item names (may be empty set).
 int getPayloadSize()
          Get the number of items in the payload.
 java.lang.String getPayloadText()
          Gets the String representation of the compound payload of this message.
 java.lang.String getReceiver()
          Get message receiver.
 java.lang.String getReceiverHost()
          Get message receiver's host computer.
 int getReceiverSubscribeId()
          Get receiver subscribe id.
 java.util.Date getReceiverTime()
          Get time message was received.
 java.lang.String getSender()
          Get message sender.
 java.lang.String getSenderHost()
          Get message sender's host computer.
 java.util.Date getSenderTime()
          Get time message was sent.
 int getSenderToken()
          Get sender's token.
 java.lang.String getSubject()
          Get subject of message.
 int getSysMsgId()
          Get system id of message.
 java.lang.String getText()
          Get text of message.
 java.lang.String getType()
          Get type of message.
 int getUserInt()
          Get user supplied integer.
 java.util.Date getUserTime()
          Get user supplied time.
 int getVersion()
          Gets the version number of this message which is the same as that of the cMsg software package that created it.
 boolean hasPayload()
          Does this message have a payload?
protected  void hasPayload(boolean hp)
          Set the "has-a-compound-payload" bit of a message.
 boolean isGetRequest()
          Is this message a "sendAndGet" request?
 boolean isGetResponse()
          Is this message a response to a "sendAndGet" message?
 boolean isNullGetResponse()
          Is this message a null response to a "sendAndGet" message?
 void makeNullResponse(cMsgMessage msg)
          Converts existing message to null response of supplied message.
 void makeResponse(cMsgMessage msg)
          Converts existing message to response of supplied message.
 boolean needToSwap()
          This method specifies whether the endian value of the byte array is little endian or not.
 cMsgMessage nullResponse()
          Creates a proper response message to this message which was sent by a client calling sendAndGet.
 void payloadPrintout(int level)
          This method prints out the message payload in a readable form.
 boolean removePayloadItem(cMsgPayloadItem item)
          Remove an item from the payload.
 boolean removePayloadItem(java.lang.String name)
          Remove an item from the payload.
 cMsgMessage response()
          Creates a proper response message to this message which was sent by a client calling sendAndGet.
 void setByteArray(byte[] b)
          Set byte array of message.
 void setByteArray(byte[] b, int offset, int length)
          Set byte array of message by copying the array argument.
 void setByteArrayEndian(int endian)
          Set endianness of the byte array data.
 void setByteArrayLength(int length)
          Set byte array length of data of interest.
 void setByteArrayNoCopy(byte[] b)
          Set byte array of message to the given argument without copying the byte array itself - only the reference is copied.
 void setByteArrayNoCopy(byte[] b, int offset, int length)
          Set byte array of message to the given argument without copying the byte array itself - only the reference is copied.
 void setByteArrayOffset(int offset)
          Set byte array index to data of interest.
protected  int setFieldsFromText(java.lang.String text, int flag)
          This routine takes a string representation of the whole compound payload, including the system (hidden) fields of the message, as it gets sent over the network and converts it into the standard message payload.
 void setGetResponse(boolean getResponse)
          Specify whether this message is a response to a "sendAndGet" message.
 void setHistoryLengthMax(int historyLengthMax)
          Sets the maximum number of entries this message keeps of its history of various parameters.
 void setNullGetResponse(boolean nullGetResponse)
          Specify whether this message is a null response to a "sendAndGet" message.
 void setSubject(java.lang.String subject)
          Set subject of message.
 void setText(java.lang.String text)
          Set text of message.
 void setType(java.lang.String type)
          Set type of message.
 void setUserInt(int userInt)
          Set message sender's id.
 void setUserTime(java.util.Date time)
          Set time.
 java.lang.String toString()
          This method converts the message to a printable string in XML format.
 void updatePayloadText()
          This method creates a string representation of the whole compound payload and the hidden system fields (currently fields describing the history of the message bding sent) of the message and stores it in the payloadText member.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

isGetRequest

public static final int isGetRequest
Is message a sendAndGet request? -- stored in 1st bit of info. This is only for internal use.

See Also:
Constant Field Values

isGetResponse

public static final int isGetResponse
Is message a response to a sendAndGet? -- stored in 2nd bit of info. This is only for internal use.

See Also:
Constant Field Values

isNullGetResponse

public static final int isNullGetResponse
Is message null response to a sendAndGet? -- stored in 3rd bit of info. This is only for internal use.

See Also:
Constant Field Values

isBigEndian

public static final int isBigEndian
Is the byte array data in big endian form? -- stored in 4th bit of info. This is only for internal use.

See Also:
Constant Field Values

wasSent

public static final int wasSent
Has the message been sent over the wire? -- is stored in 5th bit of info. This is only for internal use.

See Also:
Constant Field Values

hasPayload

public static final int hasPayload
Does the message have a compound payload? -- is stored in 6th bit of info. This is only for internal use.

See Also:
Constant Field Values

expandedPayload

public static final int expandedPayload
If the message has a compound payload, is the payload only in text form or has it been expanded into a hashtable of real objects? Is stored in the 7th bit of info. This is only for internal use.

See Also:
Constant Field Values

systemFieldsOnly

public static final int systemFieldsOnly
When converting text to message fields, only convert system fields.

See Also:
Constant Field Values

payloadFieldsOnly

public static final int payloadFieldsOnly
When converting text to message fields, only convert non-system fields.

See Also:
Constant Field Values

allFields

public static final int allFields
When converting text to message fields, convert all fields.

See Also:
Constant Field Values
Constructor Detail

cMsgMessage

public cMsgMessage()
The constructor for a blank message.


cMsgMessage

public cMsgMessage(cMsgMessage msg)
The constructor which copies a given message.

Parameters:
msg - message to be copied
Method Detail

clone

public java.lang.Object clone()
Cloning this object does not pass on the context except for the value of reliableSend and copies the byte array if it exists.

Overrides:
clone in class java.lang.Object
Returns:
a cMsgMessage object which is a copy of this message

copy

public cMsgMessage copy()
Creates a complete copy of this message.

Returns:
copy of this message.

response

public cMsgMessage response()
                     throws cMsgException
Creates a proper response message to this message which was sent by a client calling sendAndGet.

Returns:
message with the response fields properly set.
Throws:
cMsgException - if this message was not sent from a "sendAndGet" method call

nullResponse

public cMsgMessage nullResponse()
                         throws cMsgException
Creates a proper response message to this message which was sent by a client calling sendAndGet. In this case, the response message is marked as a null response.

Returns:
message with the response fields properly set so original sender gets a null response
Throws:
cMsgException - if this message was not sent from a "sendAndGet" method call

makeResponse

public void makeResponse(cMsgMessage msg)
Converts existing message to response of supplied message.

Parameters:
msg - message this message will be made a response to

makeNullResponse

public void makeNullResponse(cMsgMessage msg)
Converts existing message to null response of supplied message.

Parameters:
msg - message this message will be made a null response to

getHistoryLengthMax

public int getHistoryLengthMax()
Gets the maximum number of entries this message keeps of its history of various parameters.

Returns:
the maximum number of entries this message keeps of its history of various parameters

setHistoryLengthMax

public void setHistoryLengthMax(int historyLengthMax)
                         throws cMsgException
Sets the maximum number of entries this message keeps of its history of various parameters. Setting this quantity to zero effectively turns off keeping any history.

Parameters:
historyLengthMax - the maximum number of entries this message keeps of its history of various parameters
Throws:
cMsgException - if historyLengthMax is < 0 or > historyLengthAbsoluteMax

getSysMsgId

public int getSysMsgId()
Get system id of message. Irrelevant to the user, used only by the system.

Returns:
system id of message.

getDomain

public java.lang.String getDomain()
Get domain this message exists in.

Returns:
domain message exists in.

isGetResponse

public boolean isGetResponse()
Is this message a response to a "sendAndGet" message?

Returns:
true if this message is a response to a "sendAndGet" message.

setGetResponse

public void setGetResponse(boolean getResponse)
Specify whether this message is a response to a "sendAndGet" message.

Parameters:
getResponse - true if this message is a response to a "sendAndGet" message

isNullGetResponse

public boolean isNullGetResponse()
Is this message a null response to a "sendAndGet" message?

Returns:
true if this message is a null response to a "sendAndGet" message

setNullGetResponse

public void setNullGetResponse(boolean nullGetResponse)
Specify whether this message is a null response to a "sendAndGet" message.

Parameters:
nullGetResponse - true if this message is a null response to a "sendAndGet" message

isGetRequest

public boolean isGetRequest()
Is this message a "sendAndGet" request?

Returns:
true if this message is a "sendAndGet" request

getInfo

public int getInfo()
Gets information compacted into a bit pattern. This method is not useful to the general user and is for use only by system developers.

Returns:
integer containing bit pattern of information

getVersion

public int getVersion()
Gets the version number of this message which is the same as that of the cMsg software package that created it.

Returns:
version number of message.

getSubject

public java.lang.String getSubject()
Get subject of message.

Returns:
subject of message.

setSubject

public void setSubject(java.lang.String subject)
Set subject of message.

Parameters:
subject - subject of message.

getType

public java.lang.String getType()
Get type of message.

Returns:
type of message.

setType

public void setType(java.lang.String type)
Set type of message.

Parameters:
type - type of message.

getText

public java.lang.String getText()
Get text of message.

Returns:
text of message.

setText

public void setText(java.lang.String text)
Set text of message.

Parameters:
text - text of message.

getUserInt

public int getUserInt()
Get user supplied integer.

Returns:
user supplied integer.

setUserInt

public void setUserInt(int userInt)
Set message sender's id.

Parameters:
userInt - message sender's id.

getUserTime

public java.util.Date getUserTime()
Get user supplied time.

Returns:
user supplied time.

setUserTime

public void setUserTime(java.util.Date time)
Set time.

Parameters:
time - time.

getByteArray

public byte[] getByteArray()
Get byte array of message.

Returns:
byte array of message.

setByteArray

public void setByteArray(byte[] b)
Set byte array of message. If the byte array is null, both the offset and length get set to 0.

Parameters:
b - byte array of message.

setByteArray

public void setByteArray(byte[] b,
                         int offset,
                         int length)
                  throws cMsgException
Set byte array of message by copying the array argument. If the byte array is null, both the offset and length get set to 0.

Parameters:
b - byte array of message.
offset - index into byte array to bytes of interest.
length - number of bytes of interest.
Throws:
cMsgException - if length, offset, or offset+length is out of array bounds

setByteArrayNoCopy

public void setByteArrayNoCopy(byte[] b)
Set byte array of message to the given argument without copying the byte array itself - only the reference is copied. If the byte array is null, both the offset and length get set to 0.

Parameters:
b - byte array of message.

setByteArrayNoCopy

public void setByteArrayNoCopy(byte[] b,
                               int offset,
                               int length)
                        throws cMsgException
Set byte array of message to the given argument without copying the byte array itself - only the reference is copied. If the byte array is null, both the offset and length get set to 0.

Parameters:
b - byte array of message.
offset - index into byte array to bytes of interest.
length - number of bytes of interest.
Throws:
cMsgException - if length, offset, or offset+length is out of array bounds

getByteArrayLength

public int getByteArrayLength()
Get byte array length of data of interest. This may be smaller than the total length of the array if the user is only interested in a portion of the array.

Returns:
length of byte array's data of interest.

setByteArrayLength

public void setByteArrayLength(int length)
                        throws cMsgException
Set byte array length of data of interest. This may be smaller than the total length of the array if the user is only interested in a portion of the array. If the byte array is null, all non-negative values are accepted.

Parameters:
length - of byte array's data of interest.
Throws:
cMsgException - if length or offset+length is out of array bounds

getByteArrayOffset

public int getByteArrayOffset()
Get byte array index to data of interest. This may be non-zero if the user is only interested in a portion of the array.

Returns:
index to byte array's data of interest.

setByteArrayOffset

public void setByteArrayOffset(int offset)
                        throws cMsgException
Set byte array index to data of interest. This may be non-zero if the user is only interested in a portion of the array. If the byte array is null, all non-negative values are accepted.

Parameters:
offset - index to byte array's data of interest.
Throws:
cMsgException - if offset or offset+length is out of array bounds

getByteArrayEndian

public int getByteArrayEndian()
Get endianness of the byte array data.

Returns:
endianness of byte array's data (either cMsgConstants.endianBig or cMsgConstants.endianLittle)

setByteArrayEndian

public void setByteArrayEndian(int endian)
                        throws cMsgException
Set endianness of the byte array data. Accepted values are:

Parameters:
endian - endianness of the byte array data
Throws:
cMsgException - if argument invalid value

needToSwap

public boolean needToSwap()
This method specifies whether the endian value of the byte array is little endian or not. Since the Java JVM is big endian on all platforms, if the array is big endian it returns false indicating that there is no need to swap data. If the array is little endian then it returns true.

Returns:
true if byte array is little endian, else false

getSender

public java.lang.String getSender()
Get message sender.

Returns:
message sender.

getSenderHost

public java.lang.String getSenderHost()
Get message sender's host computer.

Returns:
message sender's host computer.

getSenderTime

public java.util.Date getSenderTime()
Get time message was sent.

Returns:
time message sent.

getSenderToken

public int getSenderToken()
Get sender's token. Used to track asynchronous responses to messages requesting responses from other clients. Irrelevant to the user, used only by the system.

Returns:
sender's token

getReceiver

public java.lang.String getReceiver()
Get message receiver.

Returns:
message receiver.

getReceiverHost

public java.lang.String getReceiverHost()
Get message receiver's host computer.

Returns:
message receiver's host computer.

getReceiverTime

public java.util.Date getReceiverTime()
Get time message was received.

Returns:
time message received.

getReceiverSubscribeId

public int getReceiverSubscribeId()
Get receiver subscribe id.

Returns:
receiver subscribe id.

getContext

public cMsgMessageContextInterface getContext()
Gets the object containing information about the context of the callback receiving this message.

Returns:
object containing information about the context of the callback receiving this message

toString

public java.lang.String toString()
This method converts the message to a printable string in XML format. Any binary data is encoded in the base64 format.

Overrides:
toString in class java.lang.Object
Returns:
message as XML String object

copyPayload

public void copyPayload(cMsgMessage msg)
Copy only the payload of the given message, overwriting the existing payload.

Parameters:
msg - message to copy payload from

getPayloadText

public java.lang.String getPayloadText()
Gets the String representation of the compound payload of this message.

Returns:
creator of this message.

hasPayload

public boolean hasPayload()
Does this message have a payload?

Returns:
true if message has payload, else false.

hasPayload

protected void hasPayload(boolean hp)
Set the "has-a-compound-payload" bit of a message.

Parameters:
hp - boolean which is true if msg has a compound payload, else is false (no payload)

getPayloadItems

public java.util.Map<java.lang.String,cMsgPayloadItem> getPayloadItems()
Gets an unmodifiable (read only) hashmap of all payload items.

Returns:
a hashmap of all payload items.

clearPayload

public void clearPayload()
Clears the payload of all user-added items.


addPayloadItem

public void addPayloadItem(cMsgPayloadItem item)
Adds an item to the payload.

Parameters:
item - item to add to payload

addSenderToHistory

public void addSenderToHistory(java.lang.String name)
Adds a name to the history of senders of this message (in the payload). This method only keeps historyLengthMax number of the most recent names. This method is reserved for system use only.

Parameters:
name - name of sender to add to the history of senders

removePayloadItem

public boolean removePayloadItem(cMsgPayloadItem item)
Remove an item from the payload.

Parameters:
item - item to remove from the payload
Returns:
true if item removed, else false

removePayloadItem

public boolean removePayloadItem(java.lang.String name)
Remove an item from the payload.

Parameters:
name - name of the item to remove from the payload
Returns:
true if item removed, else false

getPayloadItem

public cMsgPayloadItem getPayloadItem(java.lang.String name)
Get a single, named payload item.

Parameters:
name - name of item to retrieve
Returns:
payload item if it exists, else null

getPayloadNames

public java.util.Set<java.lang.String> getPayloadNames()
Get the set of payload item names (may be empty set).

Returns:
set of payload item names

getPayloadSize

public int getPayloadSize()
Get the number of items in the payload.

Returns:
number of items in the payload

updatePayloadText

public void updatePayloadText()
This method creates a string representation of the whole compound payload and the hidden system fields (currently fields describing the history of the message bding sent) of the message and stores it in the payloadText member. This string is used for sending the payload over the network.


getItemsText

public java.lang.String getItemsText()
This method creates a string of all the payload items concatonated.

Returns:
resultant string if successful

setFieldsFromText

protected int setFieldsFromText(java.lang.String text,
                                int flag)
                         throws cMsgException
This routine takes a string representation of the whole compound payload, including the system (hidden) fields of the message, as it gets sent over the network and converts it into the standard message payload. This overwrites any existing payload and may set system fields as well depending on the given flag.

Parameters:
text - string sent over network to be unmarshalled
flag - if systemFieldsOnly, set system msg fields only, if payloadFieldsOnly set payload msg fields only, and if allFields set both
Returns:
index index pointing just past last character in text that was parsed
Throws:
cMsgException - if the text is in a bad format or the text arg is null

payloadPrintout

public void payloadPrintout(int level)
This method prints out the message payload in a readable form. Simpler than XML.

Parameters:
level - level of indentation (0 = normal)