org.jlab.coda.jevio

Class EvioCompactStructureHandler

java.lang.Object

org.jlab.coda.jevio.EvioCompactStructureHandler

public class EvioCompactStructureHandler
extends java.lang.Object

This class is used to read the bytes of just an evio structure (NOT a full evio version 4 formatted file or buffer). It is also capable of adding another structure to or removing it from that structure. The EvioCompactReader class is similar but reads files and buffers in the complete evio version 4 format. It is theoretically thread-safe. It is designed to be fast and does NOT do a deserialization on the buffer examined.

Author:

timmer

Constructor Summary

Constructors

Constructor and Description
EvioCompactStructureHandler(java.nio.ByteBuffer byteBuffer, DataType type) Constructor for reading a buffer that contains 1 structure only (no block headers).
EvioCompactStructureHandler(EvioNode node) Constructor for reading an EvioNode object.

Method Summary

Modifier and Type	Method and Description
java.nio.ByteBuffer	addStructure(java.nio.ByteBuffer addBuffer) This method adds a bank, segment, or tagsegment onto the end of a structure which contains banks, segments, or tagsegments respectively.
void	close() This only sets the position to its initial value.
java.nio.ByteBuffer	getByteBuffer() Get the byte buffer being read.
java.util.List<EvioNode>	getChildNodes() This method returns an unmodifiable list of all evio structures in buffer as EvioNode objects.
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.
java.util.List<EvioNode>	getNodes() This method returns an unmodifiable list of all evio structures in buffer as EvioNode objects.
EvioNode	getScannedStructure() 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	getStructure() Get the EvioNode object associated with the structure.
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	isClosed() Has close() been called (without reopening by calling setBuffer(java.nio.ByteBuffer, DataType))?
java.nio.ByteBuffer	removeStructure(EvioNode removeNode) This method removes the data, represented by the given node, from the buffer.
java.util.List<EvioNode>	searchStructure(int tag, int num) This method searches the event 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>	searchStructure(java.lang.String dictName, EvioXMLDictionary dictionary) This method searches the event 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, DataType type) This method can be used to avoid creating additional EvioCompactEventReader objects by reusing this one with another buffer.

Methods inherited from class java.lang.Object

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

Constructor Detail

EvioCompactStructureHandler

public EvioCompactStructureHandler(EvioNode node)
                            throws EvioException

Constructor for reading an EvioNode object. The data represented by the given EvioNode object will be copied to a new buffer (obtainable by calling getByteBuffer()) and the node and all of its descendants will switch to that new buffer.

Parameters:

node - the node to be analyzed.

Throws:

EvioException - if node arg is null

EvioCompactStructureHandler

public EvioCompactStructureHandler(java.nio.ByteBuffer byteBuffer,
                                   DataType type)
                            throws EvioException

Constructor for reading a buffer that contains 1 structure only (no block headers). The data in the given ByteBuffer object will be copied to a new buffer (obtainable by calling getByteBuffer()).

Parameters:

byteBuffer - the buffer to be read that contains 1 structure only (no block headers).

type - the type of outermost structure contained in buffer, may be DataType.BANK, DataType.SEGMENT, DataType.TAGSEGMENT or equivalent.

Throws:

EvioException - if byteBuffer arg is null; if type arg is null or is not an evio structure; if byteBuffer not in proper format;

Method Detail

setBuffer

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

This method can be used to avoid creating additional EvioCompactEventReader objects by reusing this one with another buffer.

Parameters:

buf - the buffer to be read that contains 1 structure only (no block headers).

type - the type of outermost structure contained in buffer, may be DataType.BANK, DataType.SEGMENT, DataType.TAGSEGMENT or equivalent.

Throws:

EvioException - if buf arg is null; if type arg is null or is not an evio structure; if buf not in proper format;

isClosed

public boolean isClosed()

Has close() been called (without reopening by calling setBuffer(java.nio.ByteBuffer, DataType))?

Returns:

true if this object closed, else false.

getByteBuffer

public java.nio.ByteBuffer getByteBuffer()

Get the byte buffer being read.

Returns:

the byte buffer being read.

getStructure

public EvioNode getStructure()

Get the EvioNode object associated with the structure.

Returns:

EvioNode object associated with the structure.

getScannedStructure

public EvioNode getScannedStructure()

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

Returns:

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

searchStructure

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

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

Parameters:

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

searchStructure

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

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

Parameters:

dictName - name of dictionary entry to search for

dictionary - dictionary to use

Returns:

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

Throws:

EvioException - if either dictName or dictionary arg is null; if dictName is an invalid dictionary entry; if object closed

addStructure

public java.nio.ByteBuffer addStructure(java.nio.ByteBuffer addBuffer)
                                 throws EvioException

This method adds a bank, segment, or tagsegment onto the end of a structure which contains banks, segments, or tagsegments respectively. 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 parent structure. This means it is not possible to add to structures which contain only a primitive data type.

To produce properly formatted 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.

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:

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 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 there is an internal programming error; if object closed

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 the node and its descendants as obsolete. They must not be used anymore.

Parameters:

removeNode - evio structure to remove from buffer

Returns:

backing buffer updated to reflect the node removal

Throws:

EvioException - if object closed; if node was not found in any event; if internal programming error

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.

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

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.

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.

Throws:

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

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

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;

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.

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

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

getNodes

public java.util.List<EvioNode> getNodes()
                                  throws EvioException

This method returns an unmodifiable list of all evio structures in buffer as EvioNode objects.

Returns:

unmodifiable list of all evio structures in buffer as EvioNode objects.

Throws:

EvioException - if object closed

getChildNodes

public java.util.List<EvioNode> getChildNodes()
                                       throws EvioException

This method returns an unmodifiable list of all evio structures in buffer as EvioNode objects.

Returns:

unmodifiable list of all evio structures in buffer as EvioNode objects.

Throws:

EvioException - if object closed

close

public void close()

This only sets the position to its initial value.