org.jlab.coda.jevio

Class CompositeData

java.lang.Object

org.jlab.coda.jevio.CompositeData

public final class CompositeData
extends java.lang.Object

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, int formatTag, CompositeData.Data data, int dataTag, int dataNum) Constructor used for creating this object from scratch.

Method Summary

Methods

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 list of data objects 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.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	getNValue() This method gets the next N value item as an Integer object.
java.util.List<java.lang.Integer>	getNValues() This method gets a list of all the n values of the data items inside the composite.
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.
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 & 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 IEEE (big endian) and DECS (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 IEEE (big endian) and DECS (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 ../../../.. gui.
java.lang.String	toString(java.lang.String indent) Obtain a string representation of the composite data.
void	toXML(javax.xml.stream.XMLStreamWriter xmlWriter, BaseStructure bs, boolean hex) This method writes an xml string representation of this CompositeData object into the xmlWriter given.

Methods inherited from class java.lang.Object

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

Constructor Detail

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

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.

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)

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.

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

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.

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.

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 [7:4] [3:0] # 0 #'(' 0 15 #'(' same as above, but have to take # from the data (32-bit) 0 0 ')' # 1 #'i' unsigned int # 2 #'F' floating point # 3 #'a' 8-bit ASCII char (C++) # 4 #'S' short # 5 #'s' unsigned short # 6 #'C' char # 7 #'c' unsigned char # 8 #'D' double (64-bit float) # 9 #'L' long long (64-bit int) # 10 #'l' unsigned long long (64-bit int) # 11 #'I' int # 12 #'A' hollerit (4-byte char with int ending) NOTES: 1. 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 beginnig of the format (FORTRAN agreement) 2. The number of repeats '#' must be a number between 2 and 15; if the number of repeats is symbol 'N' instead of the number, it will be taken from data assuming 'int' format

Parameters:

fmt - composite data format string

Returns:

List of ints resulting from transformation of "fmt" string

Throws:

EvioException - if improper format string

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 & 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.

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 = dest and offsets are not the same; 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.

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 or ifmt size <= 0; if src = dest and offsets are not the same; if src or dest is 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 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. Caller must be sure the endian value of the srcBuf is set properly before the call.

MAKE SURE destBuf IS SET TO THE OPPOSITE ENDIANNESS AS srcBuf OR NO SWAPPING WILL TAKE PLACE! This can be done by calling ByteBuffer.order(java.nio.ByteOrder).

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 or nBytes <= 0; srcBuf or destBuf is 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 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. Caller must be sure the endian value of the srcBuf is set properly before the call.

MAKE SURE destBuf IS SET TO THE OPPOSITE ENDIANNESS AS srcBuf OR NO SWAPPING WILL TAKE PLACE! This can be done by calling ByteBuffer.order(java.nio.ByteOrder).

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

ifmt - format list as produced by compositeFormatToInt(String)

Throws:

EvioException - if ifmt null; ifmt size or nBytes <= 0; srcBuf or destBuf is too small; if bad values for srcPos or destPos;

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 list of data objects 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 void toXML(javax.xml.stream.XMLStreamWriter xmlWriter,
         BaseStructure bs,
         boolean hex)
           throws javax.xml.stream.XMLStreamException

This method writes an xml string representation of this CompositeData object into the xmlWriter given.

Parameters:

xmlWriter - the writer used to write the events to XML. It is tied to an open file.

bs - evio container object that called this method. Allows us to use some convenient methods.

hex - if true then print integers in hexadecimal

Throws:

javax.xml.stream.XMLStreamException

toString

public java.lang.String toString(boolean hex)

This method returns a string representation of this CompositeData object suitable for displaying in ../../../.. 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