org.jlab.coda.cMsg
Class cMsgPayloadItem

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

public final class cMsgPayloadItem
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

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 (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]

See Also:
Serialized Form

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)
          Construct a payload item from an array of byte arrays containing binary data.
cMsgPayloadItem(java.lang.String name, byte[][] b, int[] end)
          Construct a payload item from an array of byte arrays containing binary data.
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[] ta)
          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[][] getBinaryArray()
          Gets the payload item as an array of byte array objects 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.
 int[] getEndianArray()
          Get the array of endian values if this payload item is an array of byte arrays 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.
 
Methods inherited from class java.lang.Object
equals, 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,
                       byte[][] b,
                       int[] end)
                throws cMsgException
Construct a payload item from an array of byte arrays containing binary data.

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

cMsgPayloadItem

public cMsgPayloadItem(java.lang.String name,
                       byte[][] b)
                throws cMsgException
Construct a payload item from an array of byte arrays containing binary data. Big endian data is assumed.

Parameters:
name - name of item
b - array of byte arrays containing binary data to be part of the payload 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[] ta)
                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
ta - 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.

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

getEndianArray

public int[] getEndianArray()
Get the array of endian values if this payload item is an array of byte arrays containing binary data.

Returns:
array of endian values if this payload item is an array of byte arrays 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

getBinaryArray

public byte[][] getBinaryArray()
                        throws cMsgException
Gets the payload item as an array of byte array objects holding binary data.

Returns:
payload item as an array of byte array objects holding binary data
Throws:
cMsgException - if payload item is not of type cMsgConstants.payloadBinA

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