org.jlab.coda.jevio
Class EvioCompactReader

java.lang.Object
  org.jlab.coda.jevio.EvioCompactReader

public class EvioCompactReader
extends java.lang.Object

This class is used to read an evio version 4 formatted file or buffer and extract specific evio containers (bank, seg, or tagseg) with actual data in them given a tag/num pair. It is theoretically thread-safe. It is designed to be fast and does NOT do a full deserialization on each event examined.

Author:

timmer

Nested Class Summary

static class

EvioCompactReader.ReadStatus This enum denotes the status of a read.

Field Summary

java.util.ArrayList<EvioNode>

eventNodes Stores info of all the (top-level) events.

Constructor Summary

EvioCompactReader(java.nio.ByteBuffer byteBuffer)
Constructor for reading a buffer.

EvioCompactReader(java.io.File file)
Constructor for reading an event file.

EvioCompactReader(java.lang.String path)
Constructor for reading an event file.

Method Summary

java.nio.ByteBuffer	addStructure(int eventNumber, java.nio.ByteBuffer addBuffer) This method adds a bank, segment, or tag segment onto the end of an event.
void	close() This only sets the position to its initial value.
long	fileSize() Get the size of the file being read, in bytes.
int	getBlockCount() This is the number of blocks in the file including the empty block usually at the end of version 4 files/buffers.
java.nio.ByteBuffer	getByteBuffer() Get the byte buffer being read directly or corresponding to the event file.
java.nio.ByteBuffer	getData(EvioNode node) Get the data associated with an evio structure in ByteBuffer form.
java.nio.ByteBuffer	getData(EvioNode node, boolean copy) Get the data associated with an evio structure in ByteBuffer form.
EvioXMLDictionary	getDictionary() Get the evio dictionary if is there is one.
java.lang.String	getDictionaryXML() Get the XML format dictionary is there is one.
EvioNode	getEvent(int eventNumber) Get the EvioNode object associated with a particular event number.
int	getEventCount() This is the number of events in the file.
int	getEvioVersion() Get the evio version number.
java.nio.MappedByteBuffer	getMappedByteBuffer() Get the memory mapped buffer corresponding to the event file.
java.lang.String	getPath() Get the path to the file.
boolean	hasDictionary() Does this evio file have an associated XML dictionary?
java.util.List<EvioNode>	searchEvent(int eventNumber, int tag, int num) This method searches the specified event in a file/buffer and returns a list of objects each of which contain information about a single evio structure which matches the given tag and num.
java.util.List<EvioNode>	searchEvent(int eventNumber, java.lang.String dictName, EvioXMLDictionary dictionary) This method searches the specified event in a file/buffer and returns a list of objects each of which contain information about a single evio structure which matches the given dictionary entry name.
void	setBuffer(java.nio.ByteBuffer buf) This method can be used to avoid creating additional EvioCompactReader objects by reusing this one with another buffer.
void	toFile(java.io.File file) Save the internal byte buffer to the given file (overwrites existing file).
void	toFile(java.lang.String fileName) Save the internal byte buffer to the given file (overwrites existing file).

Methods inherited from class java.lang.Object

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

Field Detail

eventNodes

public final java.util.ArrayList<EvioNode> eventNodes

Stores info of all the (top-level) events.

Constructor Detail

EvioCompactReader

public EvioCompactReader(java.lang.String path)
                  throws EvioException,
                         java.io.IOException

Constructor for reading an event file.

Parameters:

path - the full path to the file that contains events. For writing event files, use an EventWriter object.

Throws:

java.io.IOException - if read failure

EvioException - if file arg is null

See Also:

EventWriter

EvioCompactReader

public EvioCompactReader(java.io.File file)
                  throws EvioException,
                         java.io.IOException

Constructor for reading an event file.

Parameters:

file - the file that contains events.

Throws:

java.io.IOException - if read failure

EvioException - if file arg is null; file is too large; if first block number != 1 when checkBlkNumSeq arg is true

See Also:

EventWriter

EvioCompactReader

public EvioCompactReader(java.nio.ByteBuffer byteBuffer)
                  throws EvioException

Constructor for reading a buffer.

Parameters:

byteBuffer - the buffer that contains events.

Throws:

EvioException - if file arg is null; if first block number != 1 when checkBlkNumSeq arg is true; failure to read first block header

See Also:

EventWriter

Method Detail

setBuffer

public void setBuffer(java.nio.ByteBuffer buf)
               throws EvioException

This method can be used to avoid creating additional EvioCompactReader objects by reusing this one with another buffer. The method close() is called before anything else.

Parameters:

buf - ByteBuffer to be read

Throws:

EvioException - if first block number != 1 when checkBlkNumSeq arg is true; failure to read first block header

getEvioVersion

public int getEvioVersion()

Get the evio version number.

Returns:

evio version number.

getPath

public java.lang.String getPath()

Get the path to the file.

Returns:

path to the file

getDictionaryXML

public java.lang.String getDictionaryXML()

Get the XML format dictionary is there is one.

Returns:

XML format dictionary, else null.

getDictionary

public EvioXMLDictionary getDictionary()

Get the evio dictionary if is there is one.

Returns:

evio dictionary if exists, else null.

hasDictionary

public boolean hasDictionary()

Does this evio file have an associated XML dictionary?

Returns:

true if this evio file has an associated XML dictionary, else false

getMappedByteBuffer

public java.nio.MappedByteBuffer getMappedByteBuffer()

Get the memory mapped buffer corresponding to the event file.

Returns:

the memory mapped buffer corresponding to the event file.

getByteBuffer

public java.nio.ByteBuffer getByteBuffer()

Get the byte buffer being read directly or corresponding to the event file.

Returns:

the byte buffer being read directly or corresponding to the event file.

fileSize

public long fileSize()

Get the size of the file being read, in bytes. For small files, obtain the file size using the memory mapped buffer's capacity.

Returns:

the file size in bytes

getEvent

public EvioNode getEvent(int eventNumber)

Get the EvioNode object associated with a particular event number.

Parameters:

eventNumber - number of event (place in file/buffer) starting at 1.

Returns:

EvioNode object associated with a particular event number, or null if there is none.

searchEvent

public java.util.List<EvioNode> searchEvent(int eventNumber,
                                            int tag,
                                            int num)
                                     throws EvioException

This method searches the specified event in a file/buffer and returns a list of objects each of which contain information about a single evio structure which matches the given tag and num.

Parameters:

eventNumber - place of event in buffer (starting with 1)

tag - tag to match

num - num to match

Returns:

list of EvioNode objects corresponding to matching evio structures (empty if none found)

Throws:

EvioException - if bad arg value(s)

searchEvent

public java.util.List<EvioNode> searchEvent(int eventNumber,
                                            java.lang.String dictName,
                                            EvioXMLDictionary dictionary)
                                     throws EvioException

This method searches the specified event in a file/buffer and returns a list of objects each of which contain information about a single evio structure which matches the given dictionary entry name.

Parameters:

eventNumber - place of event in buffer (starting with 1)

dictName - name of dictionary entry to search for

Returns:

list of EvioNode objects corresponding to matching evio structures (empty if none found)

Throws:

EvioException - if dictName is null; if dictName is an invalid dictionary entry; if dictionary is null and none provided in file/buffer being read

addStructure

public java.nio.ByteBuffer addStructure(int eventNumber,
                                        java.nio.ByteBuffer addBuffer)
                                 throws EvioException

This method adds a bank, segment, or tag segment onto the end of an event. It is the responsibility of the caller to make sure that the buffer argument contains valid evio data (only data representing the bank or structure to be added - not in file format with bank header and the like) which is compatible with the type of data structure stored in the given event. To produce such an evio data use BaseStructure.write(java.nio.ByteBuffer), BaseStructure.write(java.nio.ByteBuffer) or BaseStructure.write(java.nio.ByteBuffer) depending on whether a bank, seg, or tagseg is being added.

A note about files here. If the constructor of this reader read in data from a file, it will now switch to using a new, internal buffer which is returned by this method or can be retrieved by calling getByteBuffer(). It will not expand the file originally used. A new file can be created by calling either the toFile(String) or toFile(java.io.File) methods.

The given buffer argument must be ready to read with its position and limit defining the limits of the data to copy. This method is synchronized due to the bulk, relative puts.

Parameters:

eventNumber - number of event to which addBuffer is to be added

addBuffer - buffer containing evio data to add (not evio file format, i.e. no bank headers)

Returns:

a new ByteBuffer object which is created and filled with all the data including what was just added.

Throws:

EvioException - if trying to add to a file; if eventNumber < 1; if addBuffer is null; if addBuffer arg is empty or has non-evio format; if added data is not the proper length (i.e. multiple of 4 bytes); if the event number does not correspond to an existing event; if there is an internal programming error;

getData

public java.nio.ByteBuffer getData(EvioNode node)

Get the data associated with an evio structure in ByteBuffer form. The returned buffer is a view into this reader's buffer (no copy done). Changes in one will affect the other.

Parameters:

node - evio structure whose data is to be retrieved

Returns:

ByteBuffer object containing data. Position and limit are set for reading.

getData

public java.nio.ByteBuffer getData(EvioNode node,
                                   boolean copy)

Get the data associated with an evio structure in ByteBuffer form. Depending on the copy argument, the returned buffer will either be a copy of or a view into the data of this reader's buffer.

This method is synchronized due to the bulk, relative gets & puts.

Parameters:

node - evio structure whose data is to be retrieved

copy - if true, then return a copy as opposed to a view into this reader object's buffer.

Returns:

ByteBuffer object containing data. Position and limit are set for reading.

close

public void close()

This only sets the position to its initial value.

getEventCount

public int getEventCount()

This is the number of events in the file. Any dictionary event is not included in the count. In versions 3 and earlier, it is not computed unless asked for, and if asked for it is computed and cached.

Returns:

the number of events in the file.

getBlockCount

public int getBlockCount()

This is the number of blocks in the file including the empty block usually at the end of version 4 files/buffers. For version 3 files, a block size read from the first block is used to calculate the result. It is not computed unless in random access mode or is asked for, and if asked for it is computed and cached.

Returns:

the number of blocks in the file (estimate for version 3 files)

toFile

public void toFile(java.lang.String fileName)
            throws EvioException,
                   java.io.IOException

Save the internal byte buffer to the given file (overwrites existing file).

Parameters:

fileName -

Throws:

java.io.IOException

EvioException - if fileName arg is null

toFile

public void toFile(java.io.File file)
            throws EvioException,
                   java.io.IOException

Save the internal byte buffer to the given file (overwrites existing file).

Parameters:

file -

Throws:

EvioException - if file arg is null

java.io.IOException