org.jlab.coda.cMsg
Class cMsgPayloadItem

java.lang.Object
  extended by org.jlab.coda.cMsg.cMsgPayloadItem
All Implemented Interfaces:
java.lang.Cloneable

public final class cMsgPayloadItem
extends java.lang.Object
implements java.lang.Cloneable

This class represents an item in a cMsg message's payload. The value of each item is stored in this class along with a text representation of that item. Following is the text format of various types of payload items where [nl] means newline.

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.

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]


Constructor Summary
cMsgPayloadItem(java.lang.String name, java.math.BigInteger big)
          Construct a payload item from an unsigned 64-bit integer.
cMsgPayloadItem(java.lang.String name, java.math.BigInteger[] bigs)
          Construct a payload item from an array of unsigned 64-bit integers.
cMsgPayloadItem(java.lang.String name, byte b)
          Construct a payload item from an 8-bit integer.
cMsgPayloadItem(java.lang.String name, byte[] b)
          Construct a payload item from an array of 8-bit integers.
cMsgPayloadItem(java.lang.String name, byte[] b, int end)
          Construct a payload item from a byte array containing binary data.
cMsgPayloadItem(java.lang.String name, cMsgMessage msg)
          Construct a payload item from a cMsgMessage object.
cMsgPayloadItem(java.lang.String name, cMsgMessage[] msgs)
          Construct a payload item from an array of cMsgMessage objects.
cMsgPayloadItem(java.lang.String name, double d)
          Construct a payload item from a double.
cMsgPayloadItem(java.lang.String name, double[] d)
          Construct a payload item from an array of doubles.
cMsgPayloadItem(java.lang.String name, float f)
          Construct a payload item from a float.
cMsgPayloadItem(java.lang.String name, float[] f)
          Construct a payload item from an array of floats.
cMsgPayloadItem(java.lang.String name, int i)
          Construct a payload item from a 32-bit integer.
cMsgPayloadItem(java.lang.String name, int[] i)
          Construct a payload item from an array of 32-bit integers.
cMsgPayloadItem(java.lang.String name, long l)
          Construct a payload item from a 64-bit integer.
cMsgPayloadItem(java.lang.String name, long[] l)
          Construct a payload item from an array of 64-bit integers.
cMsgPayloadItem(java.lang.String name, short s)
          Construct a payload item from a 16-bit integer.
cMsgPayloadItem(java.lang.String name, short[] s)
          Construct a payload item from an array of 16-bit integers.
cMsgPayloadItem(java.lang.String name, java.lang.String s)
          Construct a payload item from a String object.
cMsgPayloadItem(java.lang.String name, java.lang.String[] s)
          Construct a payload item from a String array.
cMsgPayloadItem(java.lang.String name, T t)
          Construct a payload item from an object implementing the Number interface.
cMsgPayloadItem(java.lang.String name, T[] t)
          Construct a payload item from an array of objects implementing the Number interface.
 
Method Summary
 java.lang.Object clone()
          Clone this object.
 cMsgPayloadItem copy()
          Creates a complete copy of this object.
 java.math.BigInteger getBigInt()
          Gets the payload item as a BigInteger object.
 java.math.BigInteger[] getBigIntArray()
          Gets the payload item as an array of BigInteger objects.
 byte[] getBinary()
          Gets the payload item as a byte array object holding binary data.
 byte getByte()
          Gets the payload item as a byte (8-bit integer).
 byte[] getByteArray()
          Gets the payload item as an array of bytes (8-bit integers).
 int getCount()
          Get the number of elements if this payload item is an array, else return one.
 double getDouble()
          Gets the payload item as a double.
 double[] getDoubleArray()
          Gets the payload item as an array of doubles.
 int getEndian()
          Get the endian value if this payload item is a byte array containing binary data.
 float getFloat()
          Gets the payload item as a float.
 float[] getFloatArray()
          Gets the payload item as an array of floats.
 int getInt()
          Gets the payload item as a int (32-bit integer).
 int[] getIntArray()
          Gets the payload item as an array of ints (32-bit integers).
 java.lang.Object getItem()
          Get the payload item itself as an object of class Object.
 long getLong()
          Gets the payload item as a long (64-bit integer).
 long[] getLongArray()
          Gets the payload item as an array of longs (64-bit integers).
 cMsgMessage getMessage()
          Gets the payload item as a cMsgMessage object.
 cMsgMessage[] getMessageArray()
          Gets the payload item as an array of cMsgMessage objects.
 java.lang.String getName()
          Get the name of this payload item.
 short getShort()
          Gets the payload item as a short (16-bit integer).
 short[] getShortArray()
          Gets the payload item as an array of shorts (16-bit integers).
 java.lang.String getString()
          Gets the payload item as a String object.
 java.lang.String[] getStringArray()
          Gets the payload item as an array of String objects.
 java.lang.String getText()
          Get the text representation of this payload item.
 int getType()
          Get the type of this payload item.
static void intToStr(java.lang.StringBuilder sb, int i)
          This method changes an int value into a string of 8 hex characters in order to represent its bit pattern.
static void longToStr(java.lang.StringBuilder sb, long l)
          This method changes a long value into a string of 16 hex characters in order to represent its bit pattern.
 void validName(java.lang.String name, boolean isSystem)
          This method checks a string to see if it is a valid payload item name.
static void zerosToIntStr(java.lang.StringBuilder sb, int zeros)
          This method changes an integer value into a string of 8 hex characters starting with "Z" in order to represent a number of zeros in our simple zero-compression scheme.
static void zerosToLongStr(java.lang.StringBuilder sb, int zeros)
          This method changes an integer value into a string of 16 hex characters starting with "Z" in order to represent a number of zeros in our simple zero-compression scheme.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       java.lang.String s)
                throws cMsgException
Construct a payload item from a String object.

Parameters:
name - name of item
s - string to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       java.lang.String[] s)
                throws cMsgException
Construct a payload item from a String array.

Parameters:
name - name of item
s - string to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       byte[] b,
                       int end)
                throws cMsgException
Construct a payload item from a byte array containing binary data.

Parameters:
name - name of item
b - byte array containing binary data to be part of the payload
end - endian value of the binary data (cMsgConstants.endianBig, cMsgConstants.endianLittle, cMsgConstants.endianLocal, or cMsgConstants.endianNotLocal)
Throws:
cMsgException - if invalid name or endian value

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       cMsgMessage msg)
                throws cMsgException
Construct a payload item from a cMsgMessage object.

Parameters:
name - name of item
msg - cMsgMessage object to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       cMsgMessage[] msgs)
                throws cMsgException
Construct a payload item from an array of cMsgMessage objects.

Parameters:
name - name of item
msgs - array of cMsgMessage objects to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       byte b)
                throws cMsgException
Construct a payload item from an 8-bit integer.

Parameters:
name - name of item
b - byte (8-bit integer) to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       short s)
                throws cMsgException
Construct a payload item from a 16-bit integer.

Parameters:
name - name of item
s - short (16-bit integer) to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       int i)
                throws cMsgException
Construct a payload item from a 32-bit integer.

Parameters:
name - name of item
i - int (32-bit integer) to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       long l)
                throws cMsgException
Construct a payload item from a 64-bit integer.

Parameters:
name - name of item
l - long (64-bit integer) to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       java.math.BigInteger big)
                throws cMsgException
Construct a payload item from an unsigned 64-bit integer.

Parameters:
name - name of item
big - BigInteger object (containing an unsigned 64-bit integer) to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       T t)
                throws cMsgException
Construct a payload item from an object implementing the Number interface. The object must be one of either Byte, Short, Integer, Long, Float, or Double.

Parameters:
name - name of item
t - Number object to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       byte[] b)
                throws cMsgException
Construct a payload item from an array of 8-bit integers.

Parameters:
name - name of item
b - byte array (array of 8-bit integers) to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       short[] s)
                throws cMsgException
Construct a payload item from an array of 16-bit integers.

Parameters:
name - name of item
s - short array (array of 16-bit integers) to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       int[] i)
                throws cMsgException
Construct a payload item from an array of 32-bit integers.

Parameters:
name - name of item
i - int array (array of 32-bit integers) to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       long[] l)
                throws cMsgException
Construct a payload item from an array of 64-bit integers.

Parameters:
name - name of item
l - long array (array of 64-bit integers) to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       java.math.BigInteger[] bigs)
                throws cMsgException
Construct a payload item from an array of unsigned 64-bit integers.

Parameters:
name - name of item
bigs - array of BigInteger objects (each containing an unsigned 64-bit integer) to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       T[] t)
                throws cMsgException
Construct a payload item from an array of objects implementing the Number interface. The objects must be one of either Byte, Short, Integer, Long, Float, or Double.

Parameters:
name - name of item
t - array of Number objects to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       float f)
                throws cMsgException
Construct a payload item from a float.

Parameters:
name - name of item
f - float to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       double d)
                throws cMsgException
Construct a payload item from a double.

Parameters:
name - name of item
d - double to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       float[] f)
                throws cMsgException
Construct a payload item from an array of floats.

Parameters:
name - name of item
f - float array to be part of the payload
Throws:
cMsgException - if invalid name

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       double[] d)
                throws cMsgException
Construct a payload item from an array of doubles.

Parameters:
name - name of item
d - double array to be part of the payload
Throws:
cMsgException - if invalid name
Method Detail

clone

public java.lang.Object clone()
Clone this object.

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

copy

public cMsgPayloadItem copy()
Creates a complete copy of this object.

Returns:
copy of this object.

validName

public void validName(java.lang.String name,
                      boolean isSystem)
               throws cMsgException
This method checks a string to see if it is a valid payload item name. It returns false if it is not, or true if it is. A check is made to see if it contains any character from a list of excluded characters. All names starting with "cmsg", independent of case, are reserved for use by the cMsg system itself. Names may not be longer than CMSG_PAYLOAD_NAME_LEN_MAX characters.

Parameters:
name - string to check
isSystem - if true, allows names starting with "cmsg", else not
Throws:
cMsgException - if string is null, contains illegal characters, starts with "cmsg" if not isSystem, or is too long

zerosToIntStr

public static final void zerosToIntStr(java.lang.StringBuilder sb,
                                       int zeros)
This method changes an integer value into a string of 8 hex characters starting with "Z" in order to represent a number of zeros in our simple zero-compression scheme. This only makes sense for positive integers.

Parameters:
sb - StringBuilder object into which the characters are written
zeros - the number of zeros to be encoded/compressed

zerosToLongStr

public static final void zerosToLongStr(java.lang.StringBuilder sb,
                                        int zeros)
This method changes an integer value into a string of 16 hex characters starting with "Z" in order to represent a number of zeros in our simple zero-compression scheme. This only makes sense for positive integers.

Parameters:
sb - StringBuilder object into which the characters are written
zeros - the number of zeros to be encoded/compressed

longToStr

public static final void longToStr(java.lang.StringBuilder sb,
                                   long l)
This method changes a long value into a string of 16 hex characters in order to represent its bit pattern.

Parameters:
sb - StringBuilder object into which the characters are written
l - the number to transform

intToStr

public static final void intToStr(java.lang.StringBuilder sb,
                                  int i)
This method changes an int value into a string of 8 hex characters in order to represent its bit pattern.

Parameters:
sb - StringBuilder object into which the characters are written
i - the number to transform

getName

public java.lang.String getName()
Get the name of this payload item.

Returns:
name of this payload item

getItem

public java.lang.Object getItem()
Get the payload item itself as an object of class Object.

Returns:
payload item as an object of class Object

getType

public int getType()
Get the type of this payload item. The type has one of the following values:

Returns:
type of this payload item

getText

public java.lang.String getText()
Get the text representation of this payload item.

Returns:
text representation of this payload item

getCount

public int getCount()
Get the number of elements if this payload item is an array, else return one.

Returns:
number of elements if this payload item is an array, else one

getEndian

public int getEndian()
Get the endian value if this payload item is a byte array containing binary data.

Returns:
endian value if this payload item is a byte array containing binary data, else meaningless

getString

public java.lang.String getString()
                           throws cMsgException
Gets the payload item as a String object.

Returns:
payload item as a String object
Throws:
cMsgException - if payload item is not of type cMsgConstants.payloadStr

getStringArray

public java.lang.String[] getStringArray()
                                  throws cMsgException
Gets the payload item as an array of String objects.

Returns:
payload item as an array of String objects
Throws:
cMsgException - if payload item is not of type cMsgConstants.payloadStrA

getBinary

public byte[] getBinary()
                 throws cMsgException
Gets the payload item as a byte array object holding binary data.

Returns:
payload item as a byte array object holding binary data
Throws:
cMsgException - if payload item is not of type cMsgConstants.payloadBin

getMessage

public cMsgMessage getMessage()
                       throws cMsgException
Gets the payload item as a cMsgMessage object.

Returns:
payload item as a cMsgMessage object
Throws:
cMsgException - if payload item is not of type cMsgConstants.payloadMsg

getMessageArray

public cMsgMessage[] getMessageArray()
                              throws cMsgException
Gets the payload item as an array of cMsgMessage objects.

Returns:
payload item as an array of cMsgMessage objects
Throws:
cMsgException - if payload item is not of type cMsgConstants.payloadMsgA

getByte

public byte getByte()
             throws cMsgException
Gets the payload item as a byte (8-bit integer). This method will also return all other integer types as a byte if the payload item's value is in the valid range of a byte.

Returns:
payload item as a byte (8-bit integer)
Throws:
cMsgException - if payload item is not of an integer type, or if its value is out-of-range for a byte

getShort

public short getShort()
               throws cMsgException
Gets the payload item as a short (16-bit integer). This method will also return all other integer types as a short if the payload item's value is in the valid range of a short.

Returns:
payload item as a short (16-bit integer)
Throws:
cMsgException - if payload item is not of an integer type, or if its value is out-of-range for a short

getInt

public int getInt()
           throws cMsgException
Gets the payload item as a int (32-bit integer). This method will also return all other integer types as a int if the payload item's value is in the valid range of a int.

Returns:
payload item as a int (32-bit integer)
Throws:
cMsgException - if payload item is not of an integer type, or if its value is out-of-range for a int

getLong

public long getLong()
             throws cMsgException
Gets the payload item as a long (64-bit integer). This method will also return all other integer types as a long if the payload item's value is in the valid range of a long.

Returns:
payload item as a long (64-bit integer)
Throws:
cMsgException - if payload item is not of an integer type, or if its value is out-of-range for a long

getBigInt

public java.math.BigInteger getBigInt()
                               throws cMsgException
Gets the payload item as a BigInteger object. This method is designed to work with 64-bit, unsigned integer types, but also works with all integer types.

Returns:
payload item as a BigInteger object
Throws:
cMsgException - if payload item is not of an integer type

getByteArray

public byte[] getByteArray()
                    throws cMsgException
Gets the payload item as an array of bytes (8-bit integers). This method will also return all other integer array types as a byte array if the payload item's array values are in the valid range of a byte. Note that it is somewhat inefficient to convert large arrays from one integer type to another and have the bounds of each conversion checked.

Returns:
payload item as an array of bytes (8-bit integers)
Throws:
cMsgException - if payload item is not of an integer array type, or if its array values are out-of-range for a byte

getShortArray

public short[] getShortArray()
                      throws cMsgException
Gets the payload item as an array of shorts (16-bit integers). This method will also return all other integer array types as a short array if the payload item's array values are in the valid range of a short. Note that it is somewhat inefficient to convert large arrays from one integer type to another and have the bounds of each conversion checked.

Returns:
payload item as an array of shorts (16-bit integers)
Throws:
cMsgException - if payload item is not of an integer array type, or if its array values are out-of-range for a short

getIntArray

public int[] getIntArray()
                  throws cMsgException
Gets the payload item as an array of ints (32-bit integers). This method will also return all other integer array types as a int array if the payload item's array values are in the valid range of a int. Note that it is somewhat inefficient to convert large arrays from one integer type to another and have the bounds of each conversion checked.

Returns:
payload item as an array of ints (32-bit integers)
Throws:
cMsgException - if payload item is not of an integer array type, or if its array values are out-of-range for a int

getLongArray

public long[] getLongArray()
                    throws cMsgException
Gets the payload item as an array of longs (64-bit integers). This method will also return all other integer array types as a long array if the payload item's array values are in the valid range of a long. Note that it is somewhat inefficient to convert large arrays from one integer type to another and have the bounds of each conversion checked.

Returns:
payload item as an array of longs (64-bit integers)
Throws:
cMsgException - if payload item is not of an integer array type, or if its array values are out-of-range for a long

getBigIntArray

public java.math.BigInteger[] getBigIntArray()
                                      throws cMsgException
Gets the payload item as an array of BigInteger objects. This method is designed to work with 64-bit, unsigned integer types, but also works with all integer types. Note that it is inefficient to convert arrays from primitive integer types to BigInteger objects.

Returns:
payload item as an array of BigInteger objects
Throws:
cMsgException - if payload item is not of an integer array type

getFloat

public float getFloat()
               throws cMsgException
Gets the payload item as a float. This method will also return a double as a float if the payload item's value is in the valid range of a float.

Returns:
payload item as a float
Throws:
cMsgException - if payload item is not of type cMsgConstants.payloadFlt, or it's not of type cMsgConstants.payloadDbl and its value is out-of-range for a float

getDouble

public double getDouble()
                 throws cMsgException
Gets the payload item as a double. This method will also return a float as a double.

Returns:
payload item as a float
Throws:
cMsgException - if payload item is not of type cMsgConstants.payloadFlt or cMsgConstants.payloadDbl

getFloatArray

public float[] getFloatArray()
                      throws cMsgException
Gets the payload item as an array of floats. This method will also return an array of doubles as an array of floats if the payload item's values are in the valid range of a float.

Returns:
payload item as a float array
Throws:
cMsgException - if payload item is not of type cMsgConstants.payloadFltA, or it's not of type cMsgConstants.payloadDblA and its values are out-of-range for a float

getDoubleArray

public double[] getDoubleArray()
                        throws cMsgException
Gets the payload item as an array of doubles. This method will also return an array of floats as an array of doubles.

Returns:
payload item as a double array
Throws:
cMsgException - if payload item is not of type cMsgConstants.payloadFltA or cMsgConstants.payloadDblA