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

Constructor Summary

Constructors

Constructor and Description
Utilities()

Method Summary

Modifier and Type	Method and Description
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) Deprecated. This method is being replace by a newer version generateBaseFileNameNew(String, String, StringBuilder) which returns additional information.
static int[]	generateBaseFileNameNew(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.
(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 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	printBufferBytes(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 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

Constructor Detail

Utilities

public Utilities()

Method Detail

generateBaseFileName

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

Deprecated. This method is being replace by a newer version generateBaseFileNameNew(String, String, StringBuilder) which returns additional information.

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

The base file name may contain up to 2, C-style integer format specifiers (such as %03d, or %x). If more than 2 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.

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:

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

generateBaseFileNameNew

public static int[] generateBaseFileNameNew(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 2, C-style integer format specifiers (such as %03d, or %x). If more than 2 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.

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)

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

printBufferBytes

public static void printBufferBytes(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

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 corresponding to input node object.

Throws:

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

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 format string representation of input node object.

Throws:

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