org.jlab.coda.cMsg

Class cMsgPayloadItem

java.lang.Object

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.

    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]

*

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
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[] ta) Construct a payload item from an array of objects implementing the Number interface.

Method Summary

Modifier and Type	Method and Description
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,
                       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.

Type Parameters:

T - class that extends the Number interface.

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:

• cMsgConstants.payloadStr for a String
• cMsgConstants.payloadFlt for a 4 byte float
• cMsgConstants.payloadDbl for an 8 byte float
• cMsgConstants.payloadInt8 for an 8 bit int
• cMsgConstants.payloadInt16 for a 16 bit int
• cMsgConstants.payloadInt32 for a 32 bit int
• cMsgConstants.payloadInt64 for a 64 bit int
• cMsgConstants.payloadUint8 for an unsigned 8 bit int
• cMsgConstants.payloadUint16 for an unsigned 16 bit int
• cMsgConstants.payloadUint32 for an unsigned 32 bit int
• cMsgConstants.payloadUint64 for an unsigned 64 bit int
• cMsgConstants.payloadMsg for a cMsg message
• cMsgConstants.payloadBin for binary
  
• cMsgConstants.payloadStrA for a String array
• cMsgConstants.payloadFltA for a 4 byte float array
• cMsgConstants.payloadDblA for an 8 byte float array
• cMsgConstants.payloadInt8A for an 8 bit int array
• cMsgConstants.payloadInt16A for a 16 bit int array
• cMsgConstants.payloadInt32A for a 32 bit int array
• cMsgConstants.payloadInt64A for a 64 bit int array
• cMsgConstants.payloadUint8A for an unsigned 8 bit int array
• cMsgConstants.payloadUint16A for an unsigned 16 bit int array
• cMsgConstants.payloadUint32A for an unsigned 32 bit int array
• cMsgConstants.payloadUint64A for an unsigned 64 bit int array
• cMsgConstants.payloadMsgA for a cMsg message array
• cMsgConstants.payloadBinA for an array of binary items

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