org.jlab.coda.jevio

Class Utilities

java.lang.Object

org.jlab.coda.jevio.Utilities

public final class Utilities
extends java.lang.Object

This class contains generally useful methods.

Author:

timmer Date: 6/11/13

Field Summary

Fields

Modifier and Type	Field and Description
static int[]	padValue Array to help find number of bytes to pad data.

Constructor Summary

Constructors

Constructor and Description
Utilities()

Method Summary

Modifier and Type	Method and Description
static byte[]	bankToBytes(EvioBank bank, java.nio.ByteOrder order) Method to create a byte array representing a bank.
static void	bufferToFile(java.lang.String fileName, java.nio.ByteBuffer buf, boolean overWriteOK, boolean addBlockHeader) This method takes a byte buffer and saves it to the specified file, overwriting whatever is there.
(package private) static java.lang.String	decreaseXmlIndent(java.lang.String xmlIndent) Decrease the indentation of the given XML indentation.
static int[]	generateBaseFileName(java.lang.String baseName, java.lang.String runType, java.lang.StringBuilder newNameBuilder) This method generates part of a file name given a base file name as an argument.
static java.lang.String	generateFileName(java.lang.String fileName, int specifierCount, int runNumber, long split, int splitNumber, int streamId, int streamCount) This method generates a complete file name from the previously determined baseFileName obtained from calling generateBaseFileName(String, String, StringBuilder).
(package private) static java.lang.String	generateFileNameOld(java.lang.String baseFileName, int specifierCount, int runNumber, long split, int splitNumber) This method generates a complete file name from the previously determined baseFileName obtained from calling generateBaseFileName(String, String, StringBuilder).
(package private) static java.lang.String	generateFileNameOld(java.lang.String baseFileName, int specifierCount, int runNumber, long split, int splitNumber, int streamId) This method generates a complete file name from the previously determined baseFileName obtained from calling generateBaseFileName(String, String, StringBuilder).
static DataType	getDataType(java.lang.String type) This method returns an XML element name given an evio data type.
static int	getEvioVersion(java.nio.ByteBuffer headerData) Get the evio version of the given evio header in ByteBuffer form.
static int	getEvioVersion(java.io.File file) Get the evio version of the given file.
static int	getPadding(int length) Returns number of bytes needed to pad to 4-byte boundary for the given length.
static int	getWords(int length) Returns length padded to 4-byte boundary for given length in bytes.
(package private) static java.lang.String	increaseXmlIndent(java.lang.String xmlIndent) Increase the indentation of the given XML indentation.
static EvioEvent	nodeToEvent(EvioNode node) This method takes an EvioNode object and converts it to an EvioEvent object.
static int	powerOfTwo(int x, boolean roundUp) Return the power of 2 closest to the given argument.
static void	printBuffer(java.nio.ByteBuffer buf, int position, int words, java.lang.String label) This method takes a byte buffer and prints out the desired number of words from the given position.
static void	printBytes(byte[] array, int offset, int bytes, java.lang.String label) This method takes a byte array and prints out the desired number of bytes from the given index.
static void	printBytes(java.nio.ByteBuffer buf, int position, int bytes, java.lang.String label) This method takes a byte buffer and prints out the desired number of bytes from the given position.
static void	printBytes(java.lang.String fileName, long offset, int bytes, java.lang.String label) This method takes a file and prints out the desired number of bytes from the given offset.
static void	printStackTrace() This method prints out the current stack trace.
static void	readBytes(java.lang.String fileName, java.nio.ByteBuffer buf) This method reads part of a file into a ByteBuffer.
static byte[]	stringToBank(java.lang.String text, short tag, byte num, java.nio.ByteOrder order) Method to create a byte array representing a bank with one string as data.
static java.util.List<EvioEvent>	toEvents(java.lang.String xmlString) This method takes a string representation of evio events (each starting with lt; event gt;) and converts them to a list of EvioEvent objects.
static java.util.List<EvioEvent>	toEvents(java.lang.String xmlString, int maxEvents, int skip, EvioXMLDictionary dictionary, boolean debug) This method takes a string representation of evio events (each starting with lt; event gt;) and converts them to a list of EvioEvent objects.
static java.lang.String	toXML(EvioNode node, boolean hex) This method takes an EvioNode object and converts it to a readable, XML String.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

padValue

public static int[] padValue

Array to help find number of bytes to pad data.

Constructor Detail

Utilities

public Utilities()

Method Detail

getWords

public static int getWords(int length)

Returns length padded to 4-byte boundary for given length in bytes.

Parameters:

length - length in bytes.

Returns:

length in bytes padded to 4-byte boundary.

getPadding

public static int getPadding(int length)

Returns number of bytes needed to pad to 4-byte boundary for the given length.

Parameters:

length - length in bytes.

Returns:

number of bytes needed to pad to 4-byte boundary.

getEvioVersion

public static int getEvioVersion(java.io.File file)
                          throws EvioException

Get the evio version of the given file.

Parameters:

file - file name.

Returns:

the evio version of the given file.

Throws:

EvioException - if version cannot be found.

getEvioVersion

public static int getEvioVersion(java.nio.ByteBuffer headerData)
                          throws EvioException

Get the evio version of the given evio header in ByteBuffer form. The buffer can contain any evio version and be a file, record, or block header. Side effect is that the headerData arg is set to the correct endian order.

Parameters:

headerData - ByteBuffer object with at least 8 words (32 bytes) of data.

Returns:

the evio version of the given data.

Throws:

EvioException - if version cannot be found.

generateBaseFileName

public static int[] generateBaseFileName(java.lang.String baseName,
                                         java.lang.String runType,
                                         java.lang.StringBuilder newNameBuilder)
                                  throws EvioException

This method generates part of a file name given a base file name as an argument.

The base file name may contain up to 3, C-style integer format specifiers (such as %03d, or %x). If more than 3 are found, an exception will be thrown. If no "0" precedes any integer between the "%" and the "d" or "x" of the format specifier, it will be added automatically in order to avoid spaces in the returned string. In the generateFileName(String, int, int, long, int, int, int) method, the first occurrence will be substituted with the given runNumber value. If the file is being split, the second will be substituted with the split number. If there are multiple streams, the third will be substituted with the stream id.

The base file name may contain characters of the form $(ENV_VAR) which will be substituted with the value of the associated environmental variable or a blank string if none is found.

Finally, the base file name may contain occurrences of the string "%s" which will be substituted with the value of the runType arg or nothing if the runType is null.

Parameters:

baseName - file name to start with

runType - run type/configuration name

newNameBuilder - object which contains generated base file name

Returns:

int array containing number of C-style int format specifiers found in baseName arg.

Throws:

EvioException - if baseName arg is improperly formatted; if baseName or newNameBuilder arg is null

generateFileNameOld

static java.lang.String generateFileNameOld(java.lang.String baseFileName,
                                            int specifierCount,
                                            int runNumber,
                                            long split,
                                            int splitNumber)
                                     throws java.util.IllegalFormatException

This method generates a complete file name from the previously determined baseFileName obtained from calling generateBaseFileName(String, String, StringBuilder). If evio data is to be split up into multiple files (split > 0), numbers are used to distinguish between the split files with splitNumber. If baseFileName contains C-style int format specifiers (specifierCount > 0), then the first occurrence will be substituted with the given runNumber value. If the file is being split, the second will be substituted with the splitNumber. If 2 specifiers exist and the file is not being split, no substitutions are made. If no specifier for the splitNumber exists, it is tacked onto the end of the file name.

Parameters:

baseFileName - file name to use as a basis for the generated file name

specifierCount - number of C-style int format specifiers in baseFileName arg

runNumber - CODA run number

split - number of bytes at which to split off evio file

splitNumber - number of the split file

Returns:

generated file name

Throws:

java.util.IllegalFormatException - if the baseFileName arg contains printing format specifiers which are not compatible with integers and interfere with formatting

generateFileNameOld

static java.lang.String generateFileNameOld(java.lang.String baseFileName,
                                            int specifierCount,
                                            int runNumber,
                                            long split,
                                            int splitNumber,
                                            int streamId)
                                     throws java.util.IllegalFormatException

This method generates a complete file name from the previously determined baseFileName obtained from calling generateBaseFileName(String, String, StringBuilder). If evio data is to be split up into multiple files (split > 0), numbers are used to distinguish between the split files with splitNumber. If baseFileName contains C-style int format specifiers (specifierCount > 0), then the first occurrence will be substituted with the given runNumber value. If the file is being split, the second will be substituted with the splitNumber. If 2 specifiers exist and the file is not being split, no substitutions are made. If no specifier for the splitNumber exists, it is tacked onto the end of the file name.

If multiple streams of data, each writing a file, end up with the same file name, they can be differentiated by a stream id number. If the id is not 0, the string, ".strm" is appended to the very end of the file followed by the id number (e.g. filename.strm1). This is done after the run and split numbers have been inserted into the file name.

Parameters:

baseFileName - file name to use as a basis for the generated file name

specifierCount - number of C-style int format specifiers in baseFileName arg

runNumber - CODA run number

split - number of bytes at which to split off evio file

splitNumber - number of the split file

streamId - number of the stream id

Returns:

generated file name

Throws:

java.util.IllegalFormatException - if the baseFileName arg contains printing format specifiers which are not compatible with integers and interfere with formatting

generateFileName

public static java.lang.String generateFileName(java.lang.String fileName,
                                                int specifierCount,
                                                int runNumber,
                                                long split,
                                                int splitNumber,
                                                int streamId,
                                                int streamCount)
                                         throws java.util.IllegalFormatException

This method generates a complete file name from the previously determined baseFileName obtained from calling generateBaseFileName(String, String, StringBuilder). If evio data is to be split up into multiple files (split > 0), numbers are used to distinguish between the split files with splitNumber. If baseFileName contains C-style int format specifiers (specifierCount > 0), then the first occurrence will be substituted with the given runNumber value. If the file is being split, the second will be substituted with the splitNumber. If there are multiple streams, the third will be substituted with the stream id.

If no specifier for the splitNumber exists, it is tacked onto the end of the file name. If no specifier for the stream id exists, it is tacked onto the end of the file name, after the splitNumber. No run numbers are ever tacked on without a specifier.

For splitting: if there is only 1 stream, no stream ids are used and any third specifier is removed. For non-splitting: if there is only 1 stream, no stream ids are used and any second and third specifiers are removed. For multiple streams, the second specifier is removed and the 3rd substituted with the stream id. For all cases: if there are more than 3 specifiers, NO SUBSTITUTIONS ARE DONE. This is because an error would be thrown in the String.format() method.

Parameters:

fileName - file name to use as a basis for the generated file name

specifierCount - number of C-style int format specifiers in baseFileName arg

runNumber - CODA run number

split - number of bytes at which to split off evio file

splitNumber - number of the split file

streamId - number of the stream id

streamCount - total number of streams

Returns:

generated file name

Throws:

java.util.IllegalFormatException - if the baseFileName arg contains printing format specifiers which are not compatible with integers and interfere with formatting

bufferToFile

public static void bufferToFile(java.lang.String fileName,
                                java.nio.ByteBuffer buf,
                                boolean overWriteOK,
                                boolean addBlockHeader)
                         throws java.io.IOException,
                                EvioException

This method takes a byte buffer and saves it to the specified file, overwriting whatever is there.

Parameters:

fileName - name of file to write

buf - buffer to write to file

overWriteOK - if true, OK to overwrite previously existing file

addBlockHeader - if true, add evio block header for proper evio file format

Throws:

java.io.IOException - if trouble writing to file

EvioException - if file exists but overwriting is not permitted; if null arg(s)

printStackTrace

public static void printStackTrace()

This method prints out the current stack trace.

printBuffer

public static void printBuffer(java.nio.ByteBuffer buf,
                               int position,
                               int words,
                               java.lang.String label)

This method takes a byte buffer and prints out the desired number of words from the given position. Will not print out the extra 1, 2, or 3 bytes left at the end of the buffer.

Parameters:

buf - buffer to print out

position - position of data (bytes) in buffer to start printing

words - number of 32 bit words to print in hex

label - a label to print as header

printBytes

public static void printBytes(java.nio.ByteBuffer buf,
                              int position,
                              int bytes,
                              java.lang.String label)

This method takes a byte buffer and prints out the desired number of bytes from the given position. Prints all bytes.

Parameters:

buf - buffer to print out

position - position of data (bytes) in buffer to start printing

bytes - number of bytes to print in hex

label - a label to print as header

printBytes

public static void printBytes(byte[] array,
                              int offset,
                              int bytes,
                              java.lang.String label)

This method takes a byte array and prints out the desired number of bytes from the given index. Prints all bytes.

Parameters:

array - byte array to print out

offset - offset into array to start printing

bytes - number of bytes to print in hex

label - a label to print as header

printBytes

public static void printBytes(java.lang.String fileName,
                              long offset,
                              int bytes,
                              java.lang.String label)

This method takes a file and prints out the desired number of bytes from the given offset.

Parameters:

fileName - file to print out

offset - offset into file to start printing

bytes - number of bytes to print in hex

label - a label to print as header

readBytes

public static void readBytes(java.lang.String fileName,
                             java.nio.ByteBuffer buf)
                      throws EvioException

This method reads part of a file into a ByteBuffer. The buffer's position will be at the end of the data that is read. The caller will have to flip the buffer to read it.

Parameters:

fileName - file to read from.

buf - buffer to write into.

Throws:

EvioException - if file not found, is a directory, or could not be read; if bad file name or unable to do I/O.

stringToBank

public static byte[] stringToBank(java.lang.String text,
                                  short tag,
                                  byte num,
                                  java.nio.ByteOrder order)

Method to create a byte array representing a bank with one string as data. Not the most efficient implementation.

Parameters:

text - string to use as data.

tag - bank's tag.

num - bank's num.

order - byte order of returned bank. If null use big endian.

Returns:

byte array containing evio bank with string data. Null if text is null.

bankToBytes

public static byte[] bankToBytes(EvioBank bank,
                                 java.nio.ByteOrder order)

Method to create a byte array representing a bank.

Parameters:

bank - bank to encode.

order - byte order of returned bank. If null use big endian.

Returns:

byte array containing evio bank as byte array. Null if bank is null.

nodeToEvent

public static EvioEvent nodeToEvent(EvioNode node)
                             throws EvioException

This method takes an EvioNode object and converts it to an EvioEvent object.

Parameters:

node - EvioNode object to EvioEvent

Returns:

EvioEvent object created from EvioNode arg.

Throws:

EvioException - if node is not a bank or cannot parse node's buffer

powerOfTwo

public static int powerOfTwo(int x,
                             boolean roundUp)

Return the power of 2 closest to the given argument.

Parameters:

x - value to get the power of 2 closest to.

roundUp - if true, round up, else down

Returns:

-1 if x is negative or the closest power of 2 to value

toEvents

public static java.util.List<EvioEvent> toEvents(java.lang.String xmlString)
                                          throws EvioException

This method takes a string representation of evio events (each starting with lt; event gt;) and converts them to a list of EvioEvent objects.

Parameters:

xmlString - xml format string to parse

Returns:

list of EvioEvent objects constructed from arg

Throws:

EvioException - if xml is not in proper format

toEvents

public static java.util.List<EvioEvent> toEvents(java.lang.String xmlString,
                                                 int maxEvents,
                                                 int skip,
                                                 EvioXMLDictionary dictionary,
                                                 boolean debug)
                                          throws EvioException

This method takes a string representation of evio events (each starting with lt; event gt;) and converts them to a list of EvioEvent objects.

Parameters:

xmlString - xml format string to parse

maxEvents - max number of events to return

skip - number of events to initially skip over

dictionary - dictionary object

debug - true for debug output

Returns:

list of EvioEvent objects constructed from arg

Throws:

EvioException - if xml is not in proper format

getDataType

public static DataType getDataType(java.lang.String type)

This method returns an XML element name given an evio data type.

Parameters:

type - evio data type

Returns:

XML element name used in evio event xml output

increaseXmlIndent

static java.lang.String increaseXmlIndent(java.lang.String xmlIndent)

Increase the indentation of the given XML indentation.

Parameters:

xmlIndent - String of spaces to increase.

Returns:

increased indentation String

decreaseXmlIndent

static java.lang.String decreaseXmlIndent(java.lang.String xmlIndent)

Decrease the indentation of the given XML indentation.

Parameters:

xmlIndent - String of spaces to increase.

Returns:

Decreased indentation String

toXML

public static java.lang.String toXML(EvioNode node,
                                     boolean hex)
                              throws EvioException

This method takes an EvioNode object and converts it to a readable, XML String.

Parameters:

node - EvioNode object to print out

hex - if true, ints get displayed in hexadecimal

Returns:

XML string.

Throws:

EvioException - if node is not a bank or cannot parse node's buffer