org.jlab.coda.jevio

Class EvioCompactReaderV6

java.lang.Object

org.jlab.coda.jevio.EvioCompactReaderV6

All Implemented Interfaces:

IEvioCompactReader

class EvioCompactReaderV6
extends java.lang.Object
implements IEvioCompactReader

This class is used to read an evio format version 6 formatted file or buffer. It's essentially a wrapper for the hipo.Reader class so the user can have access to the EvioCompactReader methods. It is NOT thread-safe.

Author:

timmer

Field Summary

Fields inherited from interface org.jlab.coda.jevio.IEvioCompactReader

MAGIC_OFFSET, VERSION_MASK, VERSION_OFFSET

Constructor Summary

Constructors

Constructor and Description
EvioCompactReaderV6(java.nio.ByteBuffer byteBuffer) Constructor for reading a buffer.
EvioCompactReaderV6(java.nio.ByteBuffer byteBuffer, EvioNodeSource pool) Constructor for reading a buffer.

Method Summary

Modifier and Type	Method and Description
java.nio.ByteBuffer	addStructure(int eventNumber, java.nio.ByteBuffer addBuffer) This method adds an evio container (bank, segment, or tag segment) as the last structure contained in an event.
void	close() This sets the buffer position to its initial value and marks reader as closed.
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 record usually at the end of version 4 files/buffers.
java.nio.ByteBuffer	getByteBuffer() Get the byte buffer being read.
java.nio.ByteOrder	getByteOrder() Get the byte order of the file/buffer being read.
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 if there is one.
EvioNode	getEvent(int eventNumber) Get the EvioNode object associated with a particular event number.
java.nio.ByteBuffer	getEventBuffer(int eventNumber) Get an evio bank or event in ByteBuffer form.
java.nio.ByteBuffer	getEventBuffer(int eventNumber, boolean copy) Get an evio bank or event in ByteBuffer form.
int	getEventCount() This is the number of events in the file/buffer.
int	getEvioVersion() Get the evio version number of file/buffer being read.
java.nio.ByteOrder	getFileByteOrder() Get the byte order of the file being read.
IBlockHeader	getFirstBlockHeader() This returns the FIRST block (or record) header.
java.nio.MappedByteBuffer	getMappedByteBuffer() Get the memory mapped buffer corresponding to the event file.
java.lang.String	getPath() Get the path to the file which is always null cause there is no file.
EvioNode	getScannedEvent(int eventNumber) Get the EvioNode object associated with a particular event number which has been scanned so all substructures are contained in the node.allNodes list.
EvioNode	getScannedEvent(int eventNumber, EvioNodeSource nodeSource) Get the EvioNode object associated with a particular event number which has been scanned so all substructures are contained in the node.allNodes list.
java.nio.ByteBuffer	getStructureBuffer(EvioNode node) Get an evio structure (bank, seg, or tagseg) in ByteBuffer form.
java.nio.ByteBuffer	getStructureBuffer(EvioNode node, boolean copy) Get an evio structure (bank, seg, or tagseg) in ByteBuffer form.
boolean	hasDictionary() Does this evio buffer have an associated XML dictionary?
boolean	isClosed() Has close() been called (without reopening by calling setBuffer(ByteBuffer))?
boolean	isCompressed() Is the data in the file/buffer compressed?
boolean	isFile() Is this reader reading a file? Always false for this class.
java.nio.ByteBuffer	removeEvent(int eventNumber) This method removes the data of the given event from the buffer.
java.nio.ByteBuffer	removeStructure(EvioNode removeNode) This method removes the data, represented by the given node, from the buffer.
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	setBuffer(java.nio.ByteBuffer buf, EvioNodeSource pool) 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

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

Constructor Detail

EvioCompactReaderV6

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

Constructor for reading a buffer.

Parameters:

byteBuffer - the buffer that contains events.

Throws:

EvioException - if buffer arg is null, buffer too small, buffer not in the proper format, or earlier than version 6.

See Also:

EventWriter

EvioCompactReaderV6

public EvioCompactReaderV6(java.nio.ByteBuffer byteBuffer,
                           EvioNodeSource pool)
                    throws EvioException

Constructor for reading a buffer.

Parameters:

byteBuffer - the buffer that contains events.

pool - pool of EvioNode objects to use when parsing buf to avoid garbage collection.

Throws:

EvioException - if buffer arg is null, buffer too small, buffer not in the proper format, or earlier than version 6.

See Also:

EventWriter

Method Detail

isFile

public boolean isFile()

Is this reader reading a file? Always false for this class.

Specified by:

isFile in interface IEvioCompactReader

Returns:

false.

isCompressed

public boolean isCompressed()

Is the data in the file/buffer compressed?

Specified by:

isCompressed in interface IEvioCompactReader

Returns:

true if data is compressed.

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 close() method must called before calling this method.

Specified by:

setBuffer in interface IEvioCompactReader

Parameters:

buf - ByteBuffer to be read

Throws:

EvioException - if arg is null, buffer too small, not in the proper format, or earlier than version 6

setBuffer

public void setBuffer(java.nio.ByteBuffer buf,
                      EvioNodeSource pool)
               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. The pool is not reset in this method. Caller may do that prior to calling method.

Specified by:

setBuffer in interface IEvioCompactReader

Parameters:

buf - ByteBuffer to be read.

pool - pool of EvioNode objects to use when parsing buf to avoid garbage collection.

Throws:

EvioException - if arg is null; if failure to read first block header

isClosed

public boolean isClosed()

Has close() been called (without reopening by calling setBuffer(ByteBuffer))?

Specified by:

isClosed in interface IEvioCompactReader

Returns:

true if this object closed, else false.

getByteOrder

public java.nio.ByteOrder getByteOrder()

Get the byte order of the file/buffer being read.

Specified by:

getByteOrder in interface IEvioCompactReader

Returns:

byte order of the file/buffer being read.

getEvioVersion

public int getEvioVersion()

Get the evio version number of file/buffer being read.

Specified by:

getEvioVersion in interface IEvioCompactReader

Returns:

evio version number of file/buffer being read.

getPath

public java.lang.String getPath()

Get the path to the file which is always null cause there is no file.

Specified by:

getPath in interface IEvioCompactReader

Returns:

null

getFileByteOrder

public java.nio.ByteOrder getFileByteOrder()

Get the byte order of the file being read. Since we're not reading a file, always return null.

Specified by:

getFileByteOrder in interface IEvioCompactReader

Returns:

null.

getDictionaryXML

public java.lang.String getDictionaryXML()

Get the XML format dictionary if there is one.

Specified by:

getDictionaryXML in interface IEvioCompactReader

Returns:

XML format dictionary if existing, else null.

getDictionary

public EvioXMLDictionary getDictionary()
                                throws EvioException

Get the evio dictionary if is there is one.

Specified by:

getDictionary in interface IEvioCompactReader

Returns:

evio dictionary if exists, else null.

Throws:

EvioException - if object closed and dictionary still unread

hasDictionary

public boolean hasDictionary()

Does this evio buffer have an associated XML dictionary?

Specified by:

hasDictionary in interface IEvioCompactReader

Returns:

true if this buffer has an associated XML dictionary, else false

getByteBuffer

public java.nio.ByteBuffer getByteBuffer()

Get the byte buffer being read.

Specified by:

getByteBuffer in interface IEvioCompactReader

Returns:

byte buffer being read.

getMappedByteBuffer

public java.nio.MappedByteBuffer getMappedByteBuffer()

Get the memory mapped buffer corresponding to the event file. Since we're not reading a file, always return null.

Specified by:

getMappedByteBuffer in interface IEvioCompactReader

Returns:

null.

fileSize

public long fileSize()

Get the size of the file being read, in bytes. Since we're not reading a file, always return 0.

Specified by:

fileSize in interface IEvioCompactReader

Returns:

0.

getEvent

public EvioNode getEvent(int eventNumber)

Get the EvioNode object associated with a particular event number.

Specified by:

getEvent in interface IEvioCompactReader

Parameters:

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

Returns:

EvioNode object associated with a particular event number, or null if eventNumber is out of bounds, reading a file or data is compressed.

getScannedEvent

public EvioNode getScannedEvent(int eventNumber)

Get the EvioNode object associated with a particular event number which has been scanned so all substructures are contained in the node.allNodes list.

Specified by:

getScannedEvent in interface IEvioCompactReader

Parameters:

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

Returns:

EvioNode object associated with a particular event number, or null if eventNumber is out of bounds, reading a file or data is compressed.

getScannedEvent

public EvioNode getScannedEvent(int eventNumber,
                                EvioNodeSource nodeSource)

Get the EvioNode object associated with a particular event number which has been scanned so all substructures are contained in the node.allNodes list.

Specified by:

getScannedEvent in interface IEvioCompactReader

Parameters:

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

nodeSource - source of EvioNode objects to use while parsing evio data.

Returns:

EvioNode object associated with a particular event number, or null if eventNumber is out of bounds, reading a file or data is compressed.

getFirstBlockHeader

public IBlockHeader getFirstBlockHeader()

This returns the FIRST block (or record) header. (Not the file header of evio version 6+ files).

Specified by:

getFirstBlockHeader in interface IEvioCompactReader

Returns:

the first block header.

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.

Specified by:

searchEvent in interface IEvioCompactReader

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); if object closed

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.

Specified by:

searchEvent in interface IEvioCompactReader

Parameters:

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

dictName - name of dictionary entry to search for

dictionary - dictionary to use; if null, use dictionary with file/buffer

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; if object closed

removeEvent

public java.nio.ByteBuffer removeEvent(int eventNumber)
                                throws EvioException

This method removes the data of the given event from the buffer. It also marks any existing EvioNodes representing the event and its descendants as obsolete. They must not be used anymore.

Specified by:

removeEvent in interface IEvioCompactReader

Parameters:

eventNumber - number of event to remove from buffer

Returns:

new ByteBuffer created and updated to reflect the event removal, or null if reading a file or data is compressed.

Throws:

EvioException - if eventNumber < 1; if event number does not correspond to existing event; if object closed; if node was not found in any event; if internal programming error

removeStructure

public java.nio.ByteBuffer removeStructure(EvioNode removeNode)
                                    throws EvioException

This method removes the data, represented by the given node, from the buffer. It also marks all nodes taken from that buffer as obsolete. They must not be used anymore.

Specified by:

removeStructure in interface IEvioCompactReader

Parameters:

removeNode - evio structure to remove from buffer

Returns:

ByteBuffer updated to reflect the node removal

Throws:

EvioException - if object closed; if node was not found in any event; if internal programming error; if buffer has compressed data.

addStructure

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

This method adds an evio container (bank, segment, or tag segment) as the last structure contained in an event. It is the responsibility of the caller to make sure that the buffer argument contains valid evio data (only data representing the structure to be added - not in file format with record header and the like) which is compatible with the type of data stored in the given event.

To produce such evio data use BaseStructure.write(ByteBuffer), BaseStructure.write(ByteBuffer) or BaseStructure.write(ByteBuffer) depending on whether a bank, seg, or tagseg is being added.

The given buffer argument must be ready to read with its position and limit defining the limits of the data to copy.

Specified by:

addStructure in interface IEvioCompactReader

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 record headers)

Returns:

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

Throws:

EvioException - if eventNumber < 1; if addBuffer is null; if addBuffer arg is empty or has non-evio format; if addBuffer is opposite endian to current event buffer; 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; if object closed

getData

public java.nio.ByteBuffer getData(EvioNode node)
                            throws EvioException

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.

Specified by:

getData in interface IEvioCompactReader

Parameters:

node - evio structure whose data is to be retrieved

Returns:

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

Throws:

EvioException - if object closed or node arg is null.

getData

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

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.

Specified by:

getData in interface IEvioCompactReader

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.

Throws:

EvioException - if object closed or node arg is null.

getEventBuffer

public java.nio.ByteBuffer getEventBuffer(int eventNumber)
                                   throws EvioException

Get an evio bank or event in ByteBuffer form. The returned buffer is a view into the data of this reader's buffer.

Specified by:

getEventBuffer in interface IEvioCompactReader

Parameters:

eventNumber - number of event of interest

Returns:

ByteBuffer object containing bank's/event's bytes. Position and limit are set for reading.

Throws:

EvioException - if eventNumber < 1; if the event number does not correspond to an existing event; if object closed

getEventBuffer

public java.nio.ByteBuffer getEventBuffer(int eventNumber,
                                          boolean copy)
                                   throws EvioException

Get an evio bank or event 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.

Specified by:

getEventBuffer in interface IEvioCompactReader

Parameters:

eventNumber - number of event of interest

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

Returns:

ByteBuffer object containing bank's/event's bytes. Position and limit are set for reading.

Throws:

EvioException - if eventNumber < 1; if the event number does not correspond to an existing event; if object closed

getStructureBuffer

public java.nio.ByteBuffer getStructureBuffer(EvioNode node)
                                       throws EvioException

Get an evio structure (bank, seg, or tagseg) in ByteBuffer form. The returned buffer is a view into the data of this reader's buffer.

Specified by:

getStructureBuffer in interface IEvioCompactReader

Parameters:

node - node object representing evio structure of interest

Returns:

ByteBuffer object containing bank's/event's bytes. Position and limit are set for reading.

Throws:

EvioException - if node is null; if object closed

getStructureBuffer

public java.nio.ByteBuffer getStructureBuffer(EvioNode node,
                                              boolean copy)
                                       throws EvioException

Get an evio structure (bank, seg, or tagseg) 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.

Specified by:

getStructureBuffer in interface IEvioCompactReader

Parameters:

node - node object representing evio structure of interest

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

Returns:

ByteBuffer object containing structure's bytes. Position and limit are set for reading.

Throws:

EvioException - if node is null; if object closed

close

public void close()

This sets the buffer position to its initial value and marks reader as closed.

Specified by:

close in interface IEvioCompactReader

getEventCount

public int getEventCount()

This is the number of events in the file/buffer. 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.

Specified by:

getEventCount in interface IEvioCompactReader

Returns:

the number of events in the file.

getBlockCount

public int getBlockCount()

This is the number of blocks in the file including the empty record usually at the end of version 4 files/buffers. For version 3 files, a record size read from the first record 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.

Specified by:

getBlockCount in interface IEvioCompactReader

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

Specified by:

toFile in interface IEvioCompactReader

Parameters:

fileName - name of file to write

Throws:

java.io.IOException - if error writing to file

EvioException - if fileName arg is null; if object closed

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

Specified by:

toFile in interface IEvioCompactReader

Parameters:

file - object of file to write

Throws:

EvioException - if file arg is null; if object closed

java.io.IOException - if error writing to file