cMsgMessage

java.lang.Object
- org.jlab.coda.cMsg.cMsgMessage

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

cMsgMessageFull
```
public class cMsgMessage
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable
```
This class implements a message in the cMsg messaging system. Each cMsgMessage object contains many different fields. User-settable fields include a time, an int, a text, and a binary array field. However, the most complex field (and thus deserving a full explanation) is the compound payload. In short, the payload allows a string to store messages of arbitrary length and complexity. All types of ints (1,2,4,8 bytes, BigInteger), 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, it takes more time and memory to decode XML than a simple format. Thus, a simple, easy-to-parse format was developed to implement the payload. A side benefit is no external XML parsing package is needed.

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 (arrays of) 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 (arrays of) binary (converted into text) items:
```
    item_name   item_type   item_count   isSystemItem?   item_length[nl]
    string_length_1   original_binary_byte_length_1   endian_1[nl]
    string_characters_1[nl]
     .
     .
     .
    string_length_N   original_binary_byte_length_N   endian_N[nl]
    string_characters_N
```
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

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`allFields` When converting text to message fields, convert all fields.
`(package private) boolean`	`byteArrayCopied` Was the byte array copied in or only a reference assigned?
`protected byte[]`	`bytes` Byte array of message.
`protected cMsgMessageContextInterface`	`context` Object giving info about callback environment.
`protected static java.text.SimpleDateFormat`	`dateFormatter` Object to format and parse date strings.
`protected java.lang.String`	`domain` Message exists in this domain.
`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.
`protected int`	`info` Condensed information stored in bits.
`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 from a responder? -- stored in 3rd bit of info.
`protected java.util.concurrent.ConcurrentHashMap<java.lang.String,cMsgPayloadItem>`	`items` List of payload items.
`protected int`	`length` Length of byte array elements to use.
`protected boolean`	`noHistoryAdditions` If true, do NOT add current sender to message history in payload.
`static int`	`nullGetServerResponse` Does local server have no subscriber to send from sendAndGet? Is stored in 8rd bit of info.
`protected int`	`offset` Offset into byte array of first element.
`static int`	`payloadFieldsOnly` When converting text to message fields, only convert non-system fields.
`protected java.lang.String`	`payloadText` String representation of the entire payload (including hidden system payload items).
`protected java.lang.String`	`receiver` Name of message receiver.
`protected java.lang.String`	`receiverHost` Host receiver is running on.
`protected long`	`receiverTime` Time message was received in milliseconds from midnight GMT, Jan 1st, 1970.
`protected boolean`	`reliableSend` Should the message be sent with a reliable method (TCP) or is an unreliable method (UDP) ok?
`protected int`	`reserved` Class member reserved for future use.
`protected java.lang.String`	`sender` Name of message sender (must be unique in some domains).
`protected java.lang.String`	`senderHost` Host sender is running on.
`protected long`	`senderTime` Time message was sent in milliseconds from midnight GMT, Jan 1st, 1970.
`protected int`	`senderToken` Field used by domain server in implementing "sendAndGet".
`protected java.lang.String`	`subject` Subject of message.
`protected int`	`sysMsgId` Unique message intVal created by cMsg system.
`static int`	`systemFieldsOnly` When converting text to message fields, only convert system fields.
`protected java.lang.String`	`text` Text of message.
`protected java.lang.String`	`type` Type of message.
`protected int`	`userInt` Integer supplied by user.
`protected long`	`userTime` Time supplied by user in milliseconds from midnight GMT, Jan 1st, 1970.
`protected int`	`version` Version number of cMsg.
`static int`	`wasSent` Has the message been sent over the wire? -- is stored in 5th bit of info.

Constructor Summary

Constructors
Constructor and Description

cMsgMessage()
The constructor for a blank message.

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

Constructors
Constructor and Description
`cMsgMessage()` The constructor for a blank message.
`cMsgMessage(cMsgMessage msg)` The constructor which copies a given message.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`java.lang.String`	`addHistoryToPayloadText(java.lang.String sendersName, java.lang.String sendersHost, long sendersTime)` This method creates a string representation out of the existing payload text and the given history parameters made into payload items together.
`void`	`addPayloadItem(cMsgPayloadItem item)` Adds an item to 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 and copies the byte array if it exists.
`cMsgMessage`	`copy()` Creates a complete copy of this message.
`static void`	`copy(cMsgMessage src, cMsgMessage dst)` This method turns the destination message into a complete copy of the source message.
`void`	`copyPayload(cMsgMessage msg)` Copy only the payload of the given message, overwriting the existing payload.
`(package private) java.lang.String`	`createPayloadText(java.util.Map<java.lang.String,cMsgPayloadItem> map)` This method creates a string representation out of a given map of payload items with names as keys.
`(package private) static java.lang.String`	`escapeAllForXML(java.lang.String s)` This method escapes the chars <, >, " for putting strings into XML.
`(package private) static java.lang.String`	`escapeCdataForXML(java.lang.String s)` This method escapes CDATA constructs which will appear inside of XML CDATA sections.
`(package private) static java.lang.String`	`escapeQuotesForXML(java.lang.String s)` This method escapes the " char for putting strings into XML.
`protected void`	`expandPayload()` If this message is unexpanded (has a non-null payloadText field but no items in its payload hashmap), then expand the payload text into a hashmap containing all cMsgPayloadItems.
`byte[]`	`getByteArray()` Get byte array of message.
`int`	`getByteArrayEndian()` Get endianness of the byte array data.
`int`	`getByteArrayLength()` Get byte array length of region of interest.
`int`	`getByteArrayLengthFull()` Get full length of the byte array or 0 if it is null.
`int`	`getByteArrayOffset()` Get byte array index to region 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.
`java.util.Date`	`getReceiverTime()` Get time message was received.
`boolean`	`getReliableSend()` Gets whether the send will be reliable (default, TCP) or will be allowed to be unreliable (UDP).
`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 intVal 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.
`(package private) static int`	`hexStrToInt(java.lang.String hex, boolean zeroSup)` Method to convert 8 hex characters into a int value.
`(package private) static long`	`hexStrToLong(java.lang.String hex, boolean zeroSup)` Method to convert 16 hex characters into a long value.
`(package private) static short`	`hexStrToShort(java.lang.String hex, boolean zeroSup)` Method to convert 4 hex characters into a short value.
`protected boolean`	`isExpandedPayload()` Does this message have a payload that consists of objects in a hashmap (ie.
`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?
`protected boolean`	`isNullGetServerResponse()` Is this message a result of the local server having no subscribers to the send part of a sendAndGet?
`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.
`boolean`	`noHistoryAdditions()` Does the message record sender history (assuming history length max is not exceeded)?
`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.
`java.lang.String`	`payloadToString()` This method converts the message payload to a printable string in XML format.
`boolean`	`removePayloadItem(cMsgPayloadItem item)` Remove an item from the payload.
`boolean`	`removePayloadItem(java.lang.String name)` Remove an item from the payload.
`void`	`resetByteArrayLength()` Reset the byte array length to the full length of the array or zero if there is none.
`void`	`resetPayload()` Clears the payload of all items including system items.
`cMsgMessage`	`response()` Creates a proper response message to this message which was sent by a client calling sendAndGet.
`void`	`setByteArray(byte[] b)` Copy byte array into message.
`void`	`setByteArray(byte[] b, int offset, int length)` Copy byte array into message by copying "length" number of elements starting at "offset".
`void`	`setByteArray(java.nio.ByteBuffer buf)` Copy buffer data into message's byte array.
`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 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 to the given argument without copying the byte array itself - only the reference is copied.
`void`	`setByteArrayOffset(int offset)` Set byte array index to region of interest.
`protected void`	`setExpandedPayload(boolean ep)` Set the "expanded-payload" bit of a message.
`protected int`	`setFieldsFromText(java.lang.String text, int flag)` This method 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.
`protected void`	`setNullGetServerResponse(boolean ngsr)` Set the "nullGetServerResponse" bit of a message.
`void`	`setReliableSend(boolean b)` Sets whether the send will be reliable (default, TCP) or will be allowed to be unreliable (UDP).
`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 intVal.
`void`	`setUserTime(java.util.Date time)` Set time.
`void`	`setUserTime(long time)` Set time.
`java.lang.String`	`toString()` This method converts the message to a printable string in XML format.
`java.lang.String`	`toString(boolean binary, boolean compact, boolean noSystemFields)` 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 being 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 from a responder? -- 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
  - nullGetServerResponse
```
public static final int nullGetServerResponse
```
    Does local server have no subscriber to send from sendAndGet? Is stored in 8rd 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
  - dateFormatter
```
protected static final transient java.text.SimpleDateFormat dateFormatter
```
    Object to format and parse date strings.
  - byteArrayCopied
```
boolean byteArrayCopied
```
    Was the byte array copied in or only a reference assigned?
  - sysMsgId
```
protected int sysMsgId
```
    Unique message intVal created by cMsg system. Used by cMsg domain server to track client's "sendAndGet" calls.
  - domain
```
protected java.lang.String domain
```
    Message exists in this domain.
  - info
```
protected int info
```
    Condensed information stored in bits. Is message a sendAndGet request? -- stored in 1st bit. Is message a response to a sendAndGet? -- stored in 2nd bit. Is the response message null instead of a message? -- stored in 3rd bit. Is the byte array data in big endian form? -- stored in 4th bit. Was it sent over the wire? -- stored in 5th bit. Does it have a compound payload? -- stored in 6th bit. Is the payload expanded? -- stored in 7th bit. Does local server have no subscriber for send of sendAndGet? -- stored in 8th bit.
    
    See Also:
    
    isGetRequest, isGetResponse, isNullGetResponse, isBigEndian, wasSent, hasPayload(), isExpandedPayload(), isNullGetServerResponse()
  - version
```
protected int version
```
    Version number of cMsg.
  - reserved
```
protected int reserved
```
    Class member reserved for future use.
  - subject
```
protected java.lang.String subject
```
    Subject of message.
  - type
```
protected java.lang.String type
```
    Type of message.
  - text
```
protected java.lang.String text
```
    Text of message.
  - userInt
```
protected int userInt
```
    Integer supplied by user.
  - userTime
```
protected long userTime
```
    Time supplied by user in milliseconds from midnight GMT, Jan 1st, 1970.
  - bytes
```
protected byte[] bytes
```
    Byte array of message.
  - offset
```
protected int offset
```
    Offset into byte array of first element.
  - length
```
protected int length
```
    Length of byte array elements to use.
  - items
```
protected transient java.util.concurrent.ConcurrentHashMap<java.lang.String,cMsgPayloadItem> items
```
    List of payload items. BUGBUG why create it here? for clone?
  - payloadText
```
protected java.lang.String payloadText
```
    String representation of the entire payload (including hidden system payload items).
  - noHistoryAdditions
```
protected transient boolean noHistoryAdditions
```
    If true, do NOT add current sender to message history in payload.
  - sender
```
protected java.lang.String sender
```
    Name of message sender (must be unique in some domains).
  - senderHost
```
protected java.lang.String senderHost
```
    Host sender is running on.
  - senderTime
```
protected long senderTime
```
    Time message was sent in milliseconds from midnight GMT, Jan 1st, 1970.
  - senderToken
```
protected int senderToken
```
    Field used by domain server in implementing "sendAndGet".
  - receiver
```
protected java.lang.String receiver
```
    Name of message receiver.
  - receiverHost
```
protected java.lang.String receiverHost
```
    Host receiver is running on.
  - receiverTime
```
protected long receiverTime
```
    Time message was received in milliseconds from midnight GMT, Jan 1st, 1970.
  - reliableSend
```
protected boolean reliableSend
```
    Should the message be sent with a reliable method (TCP) or is an unreliable method (UDP) ok?
  - context
```
protected transient cMsgMessageContextInterface context
```
    Object giving info about callback environment.
- 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 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 static void copy(cMsgMessage src,
                        cMsgMessage dst)
```
    This method turns the destination message into a complete copy of the source message. If the source msg has a byte array it is copied into the dest msg only if it was originally copied into the source msg, else only the reference is copied.
    
    Parameters:
    
    src - message to be copied
    
    dst - message to be copied to
  - 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
  - noHistoryAdditions
```
public boolean noHistoryAdditions()
```
    Does the message record sender history (assuming history length max is not exceeded)?
    
    Returns:
    
    true if message does NOT record sender history
  - 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 intVal of message. Irrelevant to the user, used only by the system.
    
    Returns:
    
    system intVal 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 intVal.
    
    Parameters:
    
    userInt - message sender's intVal.
  - 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 ad Date object.
  - setUserTime
```
public void setUserTime(long time)
```
    Set time.
    
    Parameters:
    
    time - time as long (amount of millisec since Jan 1 1970, 12am, GMT)
  - getByteArray
```
public byte[] getByteArray()
```
    Get byte array of message.
    
    Returns:
    
    byte array of message.
  - setByteArray
```
public void setByteArray(byte[] b)
```
    Copy byte array into message. Offset is set to 0. Length is set to the full length of the copied array. If the byte array is null or length = 0, then internal byte array is set to null, and both the offset and length are set to 0.
    
    Parameters:
    
    b - byte array of message.
  - setByteArray
```
public void setByteArray(byte[] b,
                         int offset,
                         int length)
                  throws cMsgException
```
    Copy byte array into message by copying "length" number of elements starting at "offset". In this message, the offset will be set to zero, and the length will be set to "length". If the byte array is null or length = 0, then internal byte array is set to null, and both the offset and length are set to 0.
    
    Parameters:
    
    b - byte array of message.
    
    offset - index into byte array to bytes to be copied.
    
    length - number of bytes to be copied.
    
    Throws:
    
    cMsgException - if length, offset, or offset+length is out of array bounds
  - setByteArray
```
public void setByteArray(java.nio.ByteBuffer buf)
                  throws cMsgException
```
    Copy buffer data into message's byte array. In this message, the offset will be set to zero, and the length will be set to buffer.remaining(). If the buffer is null or remaining bytes = 0, then internal byte array is set to null, and both the offset and length are set to 0. Position of buf is changed temporarily.
    
    Parameters:
    
    buf - ByteBuffer with data for byte array of message.
    
    Throws:
    
    cMsgException - if length, offset, or offset+length is out of array bounds
  - setByteArrayNoCopy
```
public void setByteArrayNoCopy(byte[] b)
```
    Set byte array to the given argument without copying the byte array itself - only the reference is copied. In this message the offset will be set to zero, and the length will be set to length of the array. If the byte array is null or length is 0, then internal byte array is set to null, and both the offset and length are set to 0.
    
    Parameters:
    
    b - byte array of message.
  - setByteArrayNoCopy
```
public void setByteArrayNoCopy(byte[] b,
                               int offset,
                               int length)
                        throws cMsgException
```
    Set byte array to the given argument without copying the byte array itself - only the reference is copied. In this message the offset will be set to "offset", and the length will be set to "length". If the byte array is null, or length = 0, then internal byte array is set to null, and both the offset and length are 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 region of interest. This may be smaller than the total or full length of the array.
    
    Returns:
    
    length of byte array's data of interest.
  - getByteArrayLengthFull
```
public int getByteArrayLengthFull()
```
    Get full length of the byte array or 0 if it is null.
    
    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 or full 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
  - resetByteArrayLength
```
public void resetByteArrayLength()
```
    Reset the byte array length to the full length of the array or zero if there is none.
  - getByteArrayOffset
```
public int getByteArrayOffset()
```
    Get byte array index to region 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 region 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:
    - cMsgConstants.endianBig for a big endian
    - cMsgConstants.endianLittle for a little endian
    - cMsgConstants.endianLocal for same endian as local host
    - cMsgConstants.endianNotLocal for opposite endian as local host
    - cMsgConstants.endianSwitch for opposite current endian
    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.
  - setReliableSend
```
public void setReliableSend(boolean b)
```
    Sets whether the send will be reliable (default, TCP) or will be allowed to be unreliable (UDP).
    
    Parameters:
    
    b - false if using UDP, or true if using TCP
  - getReliableSend
```
public boolean getReliableSend()
```
    Gets whether the send will be reliable (default, TCP) or will be allowed to be unreliable (UDP).
    
    Returns:
    
    value true if using TCP, else false
  - 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
  - escapeAllForXML
```
static java.lang.String escapeAllForXML(java.lang.String s)
```
    This method escapes the chars <, >, " for putting strings into XML.
    
    Parameters:
    
    s - string to be escaped
    
    Returns:
    
    escaped string
  - escapeQuotesForXML
```
static java.lang.String escapeQuotesForXML(java.lang.String s)
```
    This method escapes the " char for putting strings into XML.
    
    Parameters:
    
    s - string to be escaped
    
    Returns:
    
    escaped string
  - escapeCdataForXML
```
static java.lang.String escapeCdataForXML(java.lang.String s)
```
    This method escapes CDATA constructs which will appear inside of XML CDATA sections. It is not possible to have nested cdata sections. Actually the CDATA ending sequence, ]]> , is what cannot be containing in a surrounding CDATA section. This restriction can be cleverly circumvented by inserting "<![CDATA[]]]]><![CDATA[>" after each CDATA ending sequence. This creates independent CDATA sections which are not nested.
    This method assumes that there are no nested cdata sections in the input string. Nothing is done to the string if:
    - there is no ]]> so no escaping is necessary
    - there is no <![CDATA[ so s contains malformed XML
    - a particular <![CDATA[ has no corresponding ]]> so s contains malformed XML
    - ]]> comes before <![CDATA[ so s contains malformed XML
    Parameters:
    
    s - string to be escaped
    
    Returns:
    
    escaped string
  - 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 or a blank string if any error occurs
  - toString
```
public java.lang.String toString(boolean binary,
                                 boolean compact,
                                 boolean noSystemFields)
```
    This method converts the message to a printable string in XML format. Any binary data is encoded in the base64 format.
    
    Parameters:
    
    binary - includes binary as ASCII if true, else binary is ignored
    
    compact - if true, do not include attributes with null or default integer values
    
    noSystemFields - if true, do not include system (metadata) payload fields
    
    Returns:
    
    message as XML String object or a blank string if any error occurs
  - payloadToString
```
public java.lang.String payloadToString()
                                 throws cMsgException
```
    This method converts the message payload to a printable string in XML format. Any binary data is encoded in the base64 format. Returns null if there is no payload and an exception if the payload is not expanded.
    
    Returns:
    
    message payloadas XML String object
    
    Throws:
    
    cMsgException - if payload is not expanded
  - hexStrToLong
```
static final long hexStrToLong(java.lang.String hex,
                               boolean zeroSup)
```
    Method to convert 16 hex characters into a long value. No arguments checks are made.
    
    Parameters:
    
    hex - string to convert
    
    zeroSup - first char is "Z" for zero suppression so only convert next 15 chars
    
    Returns:
    
    long value of string
  - hexStrToInt
```
static final int hexStrToInt(java.lang.String hex,
                             boolean zeroSup)
```
    Method to convert 8 hex characters into a int value. No arguments checks are made.
    
    Parameters:
    
    hex - string to convert
    
    zeroSup - first char is "Z" for zero suppression so only convert next 7 chars
    
    Returns:
    
    int value of string
  - hexStrToShort
```
static final short hexStrToShort(java.lang.String hex,
                                 boolean zeroSup)
```
    Method to convert 4 hex characters into a short value. No arguments checks are made.
    
    Parameters:
    
    hex - string to convert
    
    zeroSup - first char is "Z" for zero suppression so only convert next 3 chars
    
    Returns:
    
    int value of string
  - isNullGetServerResponse
```
protected boolean isNullGetServerResponse()
```
    Is this message a result of the local server having no subscribers to the send part of a sendAndGet?
    
    Returns:
    
    true if message result of the local server having no subscribers to the send part of a sendAndGet, else false.
  - setNullGetServerResponse
```
protected void setNullGetServerResponse(boolean ngsr)
```
    Set the "nullGetServerResponse" bit of a message.
    
    Parameters:
    
    ngsr - boolean which is true if msg is result of the local server having no subscribers to the send part of a sendAndGet, else false.
  - 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)
  - isExpandedPayload
```
protected boolean isExpandedPayload()
```
    Does this message have a payload that consists of objects in a hashmap (ie. is "expanded")? Or does it simply have a payloadText field which has not been expanded.
    
    Returns:
    
    true if message has an expanded payload, else false.
  - setExpandedPayload
```
protected void setExpandedPayload(boolean ep)
```
    Set the "expanded-payload" bit of a message.
    
    Parameters:
    
    ep - boolean which is true if msg has an expanded payload, else false
  - expandPayload
```
protected void expandPayload()
```
    If this message is unexpanded (has a non-null payloadText field but no items in its payload hashmap), then expand the payload text into a hashmap containing all cMsgPayloadItems.
  - 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.
  - resetPayload
```
public void resetPayload()
```
    Clears the payload of all items including system 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
  - 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 being sent) of the message and stores it in the payloadText member. This string is used for sending the payload over the network.
  - createPayloadText
```
java.lang.String createPayloadText(java.util.Map<java.lang.String,cMsgPayloadItem> map)
```
    This method creates a string representation out of a given map of payload items with names as keys.
    
    Parameters:
    
    map - a map of payload items to be turned into a string representation
    
    Returns:
    
    string representation of given map of payload items
  - addHistoryToPayloadText
```
public java.lang.String addHistoryToPayloadText(java.lang.String sendersName,
                                                java.lang.String sendersHost,
                                                long sendersTime)
```
    This method creates a string representation out of the existing payload text and the given history parameters made into payload items together. Used when generating a text representation of the payload to be sent over the network containing additions for sender history of names, times, hosts.
    When a client sends the same message over and over again, we do NOT want the history to change. To ensure this, we follow a simple principle: the sender history needs to go into the sent message (ie. over the wire), but must not be added to the local one. Thus, if I send a message, its local sender history will not change.
    
    Parameters:
    
    sendersName - name to be added to history of senders
    
    sendersHost - host to be added to history of sender hosts
    
    sendersTime - time to be added to history of sender times
    
    Returns:
    
    string representation of existing payload text and the given history payload items together
  - 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 method 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. Warning, only up to 1000 chars of a binary payload are printed out.
    
    Parameters:
    
    level - level of indentation (0 = normal)

Class cMsgMessage

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

isGetRequest

isGetResponse

isNullGetResponse

isBigEndian

wasSent

hasPayload

expandedPayload

nullGetServerResponse

systemFieldsOnly

payloadFieldsOnly

allFields

dateFormatter

byteArrayCopied

sysMsgId

domain

info

version

reserved

subject

type

text

userInt

userTime

bytes

offset

length

items

payloadText

noHistoryAdditions

sender

senderHost

senderTime

senderToken

receiver

receiverHost

receiverTime

reliableSend

context

Constructor Detail

cMsgMessage

cMsgMessage

Method Detail

clone

copy

copy

response

nullResponse

makeResponse

makeNullResponse

noHistoryAdditions

getHistoryLengthMax

setHistoryLengthMax

getSysMsgId

getDomain

isGetResponse

setGetResponse

isNullGetResponse

setNullGetResponse

isGetRequest

getInfo

getVersion

getSubject

setSubject

getType

setType

getText

setText

getUserInt

setUserInt

getUserTime

setUserTime

setUserTime

getByteArray

setByteArray