org.jlab.coda.jevio

Class CompositeData

java.lang.Object

org.jlab.coda.jevio.CompositeData

All Implemented Interfaces:

java.lang.Cloneable

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

This is the class defining the composite data type. It is a mixture of header and raw data.

Author:

timmer

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CompositeData.Data This class is used to provide all data when constructing a CompositeData object.

Constructor Summary

Constructors

Constructor and Description
CompositeData(byte[] rawBytes, java.nio.ByteOrder byteOrder) Constructor used when reading existing data.
CompositeData(java.lang.String format, CompositeData.Data data) Constructor used for creating this object from scratch.
CompositeData(java.lang.String format, int formatTag, CompositeData.Data data, int dataTag, int dataNum) Constructor used for creating this object from scratch.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	clone() Method to clone a CompositeData object.
static java.util.List<java.lang.Integer>	compositeFormatToInt(java.lang.String fmt) This method transforms a composite, format-containing ASCII string to an int array.
static void	dataToRawBytes(java.nio.ByteBuffer rawBuf, CompositeData.Data data, java.util.List<java.lang.Integer> ifmt) This method takes a CompositeData object and a transformed format string and uses that to write data into a buffer/array in raw form.
static byte[]	generateRawBytes(CompositeData[] data) This method generates raw bytes of evio format from an array of CompositeData objects.
java.lang.Byte	getByte() This method gets the next data item as a Byte object.
java.nio.ByteOrder	getByteOrder() This method gets the raw data byte order.
java.lang.Double	getDouble() This method gets the next data item as a Double object.
java.lang.Float	getFloat() This method gets the next data item as a Float object.
java.lang.String	getFormat() This method gets the format string.
java.lang.Integer	getHollerit() This method gets the next data item (which is of Hollerit type) as an Integer object.
java.lang.Integer	getInt() This method gets the next data item as an Integer object.
java.util.List<java.lang.Object>	getItems() This method gets a list of all the data items inside the composite.
java.lang.Long	getLong() This method gets the next data item as a Long object.
java.lang.Integer	getmValue() This method gets the next m value item as an Integer object.
java.util.List<java.lang.Byte>	getmValues() This method gets a list of all the m values of the data items inside the composite.
java.lang.Integer	getnValue() This method gets the next n value item as an Integer object.
java.lang.Integer	getNValue() This method gets the next N value item as an Integer object.
java.util.List<java.lang.Short>	getnValues() This method gets a list of all the n values of the data items inside the composite.
java.util.List<java.lang.Integer>	getNValues() This method gets a list of all the N values of the data items inside the composite.
int	getPadding() Get the data padding (0, 1, 2, or 3 bytes).
byte[]	getRawBytes() This method gets the raw byte representation of this object's data.
java.lang.Short	getShort() This method gets the next data item as a Short object.
java.lang.String[]	getStrings() This method gets the next data item as a String array.
java.util.List<DataType>	getTypes() This method gets a list of all the types of the data items inside the composite.
int	index() This methods returns the index of the data item to be returned on the next call to one of the get<Type>() methods (e.g.
void	index(int index) This methods sets the index of the data item to be returned on the next call to one of the get<Type>() methods (e.g.
static CompositeData[]	parse(byte[] rawBytes, java.nio.ByteOrder byteOrder) This method parses an array of raw bytes into an array of CompositeData objects.
void	process() This method swaps EVIO composite type data, in place, to big endian (IEEE) if currently little endian (DECS).
static java.lang.String	stringsToFormat(java.lang.String[] strings) This method helps the CompositeData object creator by finding the proper format string parameter for putting this array of Strings into its data.
void	swap() This method swaps the data of this composite type between big and little endian.
static void	swapAll(byte[] src, int srcOff, byte[] dest, int destOff, int length, java.nio.ByteOrder srcOrder) This method converts (swaps) a buffer of EVIO composite type between big and little endian.
static void	swapData(byte[] src, int srcOff, byte[] dest, int destOff, int nBytes, java.util.List<java.lang.Integer> ifmt, java.nio.ByteOrder srcOrder) This method converts (swaps) an array of EVIO composite type data between IEEE (big endian) and DECS (little endian).
static void	swapData(java.nio.ByteBuffer srcBuf, java.nio.ByteBuffer destBuf, int srcPos, int destPos, int nBytes, java.util.List<java.lang.Integer> ifmt) This method converts (swaps) EVIO composite type data between Big endian and Little endian.
static void	swapData(java.nio.ByteBuffer srcBuf, java.nio.ByteBuffer destBuf, int nBytes, java.util.List<java.lang.Integer> ifmt) This method converts (swaps) EVIO composite type data between Big endian and Little endian.
java.lang.String	toString() Obtain a string representation of the composite data.
java.lang.String	toString(boolean hex) This method returns a string representation of this CompositeData object suitable for displaying in a gui.
java.lang.String	toString(java.lang.String indent) Obtain a string representation of the composite data.
java.lang.String	toXML(boolean hex) This method writes an xml string representation of this CompositeData object.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CompositeData

public CompositeData(java.lang.String format,
                     CompositeData.Data data)
              throws EvioException

Constructor used for creating this object from scratch.

Parameters:

format - format String defining data

data - data in given format

Throws:

EvioException - data or format arg = null; if improper format string

CompositeData

public CompositeData(java.lang.String format,
                     int formatTag,
                     CompositeData.Data data,
                     int dataTag,
                     int dataNum)
              throws EvioException

Constructor used for creating this object from scratch.

Parameters:

format - format String defining data

formatTag - tag used in tagsegment containing format

data - data in given format

dataTag - tag used in bank containing data

dataNum - num used in bank containing data

Throws:

EvioException - data or format arg = null; if improper format string

CompositeData

public CompositeData(byte[] rawBytes,
                     java.nio.ByteOrder byteOrder)
              throws EvioException

Constructor used when reading existing data.

Parameters:

rawBytes - raw data defining this composite type item

byteOrder - byte order of rawBytes

Throws:

EvioException - if null arg(s) or bad data format

Method Detail

parse

public static CompositeData[] parse(byte[] rawBytes,
                                    java.nio.ByteOrder byteOrder)
                             throws EvioException

This method parses an array of raw bytes into an array of CompositeData objects.

Parameters:

rawBytes - array of raw bytes to parse

byteOrder - byte order of raw bytes

Returns:

array of CompositeData objects obtained from parsing rawBytes. If none, return null.

Throws:

EvioException - if null args or bad format of raw data

generateRawBytes

public static byte[] generateRawBytes(CompositeData[] data)
                               throws EvioException

This method generates raw bytes of evio format from an array of CompositeData objects. The returned array consists of gluing together all the individual objects' rawByte arrays. All CompositeData element must be of the same byte order.

Parameters:

data - array of CompositeData object to turn into bytes

Returns:

array of raw, evio format bytes; null if arg is null or empty

Throws:

EvioException - if data takes up too much memory to store in raw byte array (JVM limit); array elements have different byte order.

clone

public java.lang.Object clone()

Method to clone a CompositeData object. Deep cloned so no connection exists between clone and object cloned.

Overrides:

clone in class java.lang.Object

Returns:

cloned CompositeData object.

stringsToFormat

public static java.lang.String stringsToFormat(java.lang.String[] strings)

This method helps the CompositeData object creator by finding the proper format string parameter for putting this array of Strings into its data. The format is in the form "Ma" where M is an actual integer. Warning, in this case, M may not be greater than 15. If you want a longer string or array of strings, use the format "Na" with a literal N. The N value can be added through CompositeData.Data.addN(int)

Parameters:

strings - array of strings to eventually put into a CompositeData object.

Returns:

string representing its format to be used in the CompositeData object's format string

getPadding

public int getPadding()

Get the data padding (0, 1, 2, or 3 bytes).

Returns:

data padding.

getFormat

public java.lang.String getFormat()

This method gets the format string.

Returns:

format string.

getByteOrder

public java.nio.ByteOrder getByteOrder()

This method gets the raw data byte order.

Returns:

raw data byte order.

getRawBytes

public byte[] getRawBytes()

This method gets the raw byte representation of this object's data.

Returns:

raw byte representation of this object's data.

getItems

public java.util.List<java.lang.Object> getItems()

This method gets a list of all the data items inside the composite.

Returns:

list of all the data items inside the composite.

getTypes

public java.util.List<DataType> getTypes()

This method gets a list of all the types of the data items inside the composite.

Returns:

list of all the types of the data items inside the composite.

getNValues

public java.util.List<java.lang.Integer> getNValues()

This method gets a list of all the N values of the data items inside the composite.

Returns:

list of all the N values of the data items inside the composite.

getnValues

public java.util.List<java.lang.Short> getnValues()

This method gets a list of all the n values of the data items inside the composite.

Returns:

list of all the n values of the data items inside the composite.

getmValues

public java.util.List<java.lang.Byte> getmValues()

This method gets a list of all the m values of the data items inside the composite.

Returns:

list of all the m values of the data items inside the composite.

index

public int index()

This methods returns the index of the data item to be returned on the next call to one of the get<Type>() methods (e.g. getInt().

Returns:

returns the index of the data item to be returned

index

public void index(int index)

This methods sets the index of the data item to be returned on the next call to one of the get<Type>() methods (e.g. getInt().

Parameters:

index - the index of the next data item to be returned

getInt

public java.lang.Integer getInt()

This method gets the next data item as an Integer object.

Returns:

Integer object, if that is the correct type of the next data item.

getNValue

public java.lang.Integer getNValue()

This method gets the next N value item as an Integer object.

Returns:

Integer object, if the correct type of the next data item is NVALUE.

getnValue

public java.lang.Integer getnValue()

This method gets the next n value item as an Integer object.

Returns:

Integer object, if the correct type of the next data item is nVALUE.

getmValue

public java.lang.Integer getmValue()

This method gets the next m value item as an Integer object.

Returns:

Integer object, if the correct type of the next data item is mVALUE.

getHollerit

public java.lang.Integer getHollerit()

This method gets the next data item (which is of Hollerit type) as an Integer object.

Returns:

Integer object, if Hollerit is the type of the next data item.

getByte

public java.lang.Byte getByte()

This method gets the next data item as a Byte object.

Returns:

Byte object, if that is the correct type of the next data item.

getShort

public java.lang.Short getShort()

This method gets the next data item as a Short object.

Returns:

Short object, if that is the correct type of the next data item.

getLong

public java.lang.Long getLong()

This method gets the next data item as a Long object.

Returns:

Long object, if that is the correct type of the next data item.

getFloat

public java.lang.Float getFloat()

This method gets the next data item as a Float object.

Returns:

Float object, if that is the correct type of the next data item.

getDouble

public java.lang.Double getDouble()

This method gets the next data item as a Double object.

Returns:

Double object, if that is the correct type of the next data item.

getStrings

public java.lang.String[] getStrings()

This method gets the next data item as a String array.

Returns:

String array, if that is the correct type of the next data item.

compositeFormatToInt

public static java.util.List<java.lang.Integer> compositeFormatToInt(java.lang.String fmt)
                                                              throws EvioException

This method transforms a composite, format-containing ASCII string to an int array. It is to be used in conjunction with swapData(ByteBuffer, ByteBuffer, int, List) to swap the endianness of composite data. It's translated from the eviofmt C function.

   format code bits <- format in ascii form
    [15:14] [13:8] [7:0]
      Nnm      #     0           #'('
        0      0     0            ')'
      Nnm      #     1           #'i'   unsigned int
      Nnm      #     2           #'F'   floating point
      Nnm      #     3           #'a'   8-bit char (C++)
      Nnm      #     4           #'S'   short
      Nnm      #     5           #'s'   unsigned short
      Nnm      #     6           #'C'   char
      Nnm      #     7           #'c'   unsigned char
      Nnm      #     8           #'D'   double (64-bit float)
      Nnm      #     9           #'L'   long long (64-bit int)
      Nnm      #    10           #'l'   unsigned long long (64-bit int)
      Nnm      #    11           #'I'   int
      Nnm      #    12           #'A'   hollerit (4-byte char with int endining)

   NOTES:
    1. The number of repeats '#' must be the number between 2 and 63, number 1 assumed by default
    2. If the number of repeats is symbol 'N' instead of the number, it will be taken from data assuming 'int32' format;
       if the number of repeats is symbol 'n' instead of the number, it will be taken from data assuming 'int16' format;
       if the number of repeats is symbol 'm' instead of the number, it will be taken from data assuming 'int8' format;
       Two bits Nnm [15:14], if not zero, requires to take the number of repeats from data in appropriate format:
            [01] means that number is integer (N),
            [10] - short (n),
            [11] - char (m)
    3. If format ends but end of data did not reach, format in last parenthesis
       will be repeated until all data processed; if there are no parenthesis
       in format, data processing will be started from the beginning of the format
       (FORTRAN agreement)
 

Parameters:

fmt - composite data format string

Returns:

List of ints resulting from transformation of "fmt" string

Throws:

EvioException - if improper format string

swap

public void swap()
          throws EvioException

This method swaps the data of this composite type between big and little endian. It swaps the entire type including the beginning tagsegment header, the following format string it contains, the data's bank header, and finally the data itself.

Throws:

EvioException - if internal error

swapAll

public static void swapAll(byte[] src,
                           int srcOff,
                           byte[] dest,
                           int destOff,
                           int length,
                           java.nio.ByteOrder srcOrder)
                    throws EvioException

This method converts (swaps) a buffer of EVIO composite type between big and little endian. It swaps the entire type including the beginning tagsegment header, the following format string it contains, the data's bank header, and finally the data itself. The src array may contain an array of composite type items and all will be swapped. If swapping in place, destOff set equal to srcOff.

Parameters:

src - source data array (of 32 bit words)

srcOff - # of bytes offset into source data array

dest - destination data array (of 32 bit words)

destOff - # of bytes offset into destination data array

length - length of data array in 32 bit words

srcOrder - the byte order of data in src

Throws:

EvioException - if offsets or length < 0; if src = null; if src or dest is too small

swapData

public static void swapData(byte[] src,
                            int srcOff,
                            byte[] dest,
                            int destOff,
                            int nBytes,
                            java.util.List<java.lang.Integer> ifmt,
                            java.nio.ByteOrder srcOrder)
                     throws EvioException

This method converts (swaps) an array of EVIO composite type data between IEEE (big endian) and DECS (little endian). This data does NOT include the composite type's beginning tagsegment and the format string it contains. It also does NOT include the data's bank header words. If swapping in place, destOff set equal to srcOff. The dest array can be null or the same as srcBuf in which case data is swapped in place.

Parameters:

src - source data array (of 32 bit words)

srcOff - offset into source data array

dest - destination data array (of 32 bit words)

destOff - offset into destination data array

nBytes - length of data to swap in bytes

ifmt - format list as produced by compositeFormatToInt(String)

srcOrder - byte order of the src data array

Throws:

EvioException - if src == null or ifmt == null; if nBytes < 8, or ifmt size < 1; srcOff or destOff negative; buffer limit/position combo too small;

swapData

public static void swapData(java.nio.ByteBuffer srcBuf,
                            java.nio.ByteBuffer destBuf,
                            int nBytes,
                            java.util.List<java.lang.Integer> ifmt)
                     throws EvioException

This method converts (swaps) EVIO composite type data between Big endian and Little endian. This data does NOT include the composite type's beginning tagsegment and the format string it contains. It also does NOT include the data's bank header words. Caller must be sure the endian value of the srcBuf is set properly before the call.

The destBuf can be null or the same as srcBuf in which case data is swapped in place and the srcBuf byte order is switched in this method.

Parameters:

srcBuf - source data buffer

destBuf - destination data buffer; if null, use srcBuf as destination

nBytes - length of data to swap in bytes

ifmt - format list as produced by compositeFormatToInt(String)

Throws:

EvioException - if ifmt null; ifmt size < 1; nBytes < 8; srcBuf is null; buffer limit/position combo too small;

swapData

public static void swapData(java.nio.ByteBuffer srcBuf,
                            java.nio.ByteBuffer destBuf,
                            int srcPos,
                            int destPos,
                            int nBytes,
                            java.util.List<java.lang.Integer> ifmt)
                     throws EvioException

This method converts (swaps) EVIO composite type data between Big endian and Little endian. This data does NOT include the composite type's beginning tagsegment and the format string it contains. It also does NOT include the data's bank header words. Caller must be sure the endian value of the srcBuf is set properly before the call.

The destBuf can be null or the same as srcBuf in which case data is swapped in place and the srcBuf byte order is switched in this method. The positions of both srcBuf and destBuf are NOT changed.

Parameters:

srcBuf - source data buffer

destBuf - destination data buffer; if null, use srcBuf as destination

srcPos - position in srcBuf to beginning swapping

destPos - position in destBuf to beginning writing swapped data

nBytes - length of data to swap in bytes (be sure to account for padding)

ifmt - format list as produced by compositeFormatToInt(String)

Throws:

EvioException - if ifmt null; ifmt size < 1; nBytes < 8; srcBuf is null; srcPos or destPos negative; buffer limit/position combo too small;

dataToRawBytes

public static void dataToRawBytes(java.nio.ByteBuffer rawBuf,
                                  CompositeData.Data data,
                                  java.util.List<java.lang.Integer> ifmt)
                           throws EvioException

This method takes a CompositeData object and a transformed format string and uses that to write data into a buffer/array in raw form.

Parameters:

rawBuf - data buffer in which to put the raw bytes

data - data to convert to raw bytes

ifmt - format list as produced by compositeFormatToInt(String)

Throws:

EvioException - if ifmt size <= 0; if srcBuf or destBuf is too small; not enough dataItems for the given format

process

public void process()

This method swaps EVIO composite type data, in place, to big endian (IEEE) if currently little endian (DECS). It also extracts and stores all the data items and their types in 2 lists.

toString

public java.lang.String toString()

Obtain a string representation of the composite data.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the composite data.

toString

public java.lang.String toString(java.lang.String indent)

Obtain a string representation of the composite data. This string has an indent inserted in front of each group of 5 items. After each group of 5, a newline is inserted. Useful for writing data in xml format.

Parameters:

indent - a string to insert in front of each group of 5 items

Returns:

a string representation of the composite data.

toXML

public java.lang.String toXML(boolean hex)

This method writes an xml string representation of this CompositeData object.

Parameters:

hex - if true then print integers in hexadecimal.

Returns:

an xml string representation of this CompositeData object.

toString

public java.lang.String toString(boolean hex)

This method returns a string representation of this CompositeData object suitable for displaying in a gui. Each data item is separated from those before and after by a line. Non-parenthesis repeats are printed together.

Parameters:

hex - if true then print integers in hexadecimal

Returns:

a string representation of this CompositeData object.