IEvioCompactReader

All Known Implementing Classes:

EvioCompactReader
```
public interface IEvioCompactReader
```
This is an interface for a compact reader of evio format files and buffers. The word "compact" refers to using the EvioNode class as a compact or lightweight means to refer to an evio event or structure in a buffer. Compact readers do not use EvioEvent, EvioBank, EvioSegment or EvioTagSegment classes which require a full parsing of each event and the creation of a large number of objects.

Since:

11/1/17.

Author:

timmer

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`MAGIC_OFFSET` Offset to get magic number from start of file for every evio version.
`static int`	`VERSION_MASK` Mask to get version number from 6th int in block for every evio version.
`static int`	`VERSION_OFFSET` Offset to get version number from start of file for every evio version.

Method Summary

All Methods Instance Methods Abstract Methods
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 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/buffer including the empty block at the end.
`java.nio.ByteBuffer`	`getByteBuffer()` Get the byte buffer being read directly or corresponding to the event file.
`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 is 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.
`java.nio.ByteOrder`	`getFileByteOrder()` When reading a file, this method's return value is the byte order of the evio data in the file.
`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.
`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 file 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?
`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).

- Field Detail
  - MAGIC_OFFSET
```
static final int MAGIC_OFFSET
```
    Offset to get magic number from start of file for every evio version.
    
    See Also:
    
    Constant Field Values
  - VERSION_OFFSET
```
static final int VERSION_OFFSET
```
    Offset to get version number from start of file for every evio version.
    
    See Also:
    
    Constant Field Values
  - VERSION_MASK
```
static final int VERSION_MASK
```
    Mask to get version number from 6th int in block for every evio version.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - isFile
```
boolean isFile()
```
    Is this reader reading a file?
    
    Returns:
    
    true if reading file, false if reading buffer
  - isCompressed
```
boolean isCompressed()
```
    Is the data in the file/buffer compressed?
    
    Returns:
    
    true if data is compressed.
  - setBuffer
```
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() should be called before calling this.
    
    Parameters:
    
    buf - ByteBuffer to be read
    
    Throws:
    
    EvioException - if arg is null; if failure to read first block header; buf not in evio format.
  - setBuffer
```
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 given buffer may NOT have compressed data or an exception will be thrown. The method close() is called before anything else. The pool is not reset in this method. Caller may do that prior to calling method.
    
    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; buf not in evio format.
  - isClosed
```
boolean isClosed()
```
    Has close() been called (without reopening by calling setBuffer(ByteBuffer))?
    
    Returns:
    
    true if this object closed, else false.
  - getByteOrder
```
java.nio.ByteOrder getByteOrder()
```
    Get the byte order of the file/buffer being read.
    
    Returns:
    
    byte order of the file/buffer being read.
  - getEvioVersion
```
int getEvioVersion()
```
    Get the evio version number.
    
    Returns:
    
    evio version number.
  - getPath
```
java.lang.String getPath()
```
    Get the path to the file.
    
    Returns:
    
    path to the file
  - getFileByteOrder
```
java.nio.ByteOrder getFileByteOrder()
```
    When reading a file, this method's return value is the byte order of the evio data in the file.
    
    Returns:
    
    byte order of the evio data in the file.
  - getDictionaryXML
```
java.lang.String getDictionaryXML()
                           throws EvioException
```
    Get the XML format dictionary is there is one.
    
    Returns:
    
    XML format dictionary, else null.
    
    Throws:
    
    EvioException - if object closed and dictionary still unread
  - getDictionary
```
EvioXMLDictionary getDictionary()
                         throws EvioException
```
    Get the evio dictionary if is there is one.
    
    Returns:
    
    evio dictionary if exists, else null.
    
    Throws:
    
    EvioException - if object closed and dictionary still unread
  - hasDictionary
```
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
```
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
```
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
```
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
```
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.
  - getScannedEvent
```
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.
    
    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.
  - getScannedEvent
```
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.
    
    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 there is none.
  - getFirstBlockHeader
```
IBlockHeader getFirstBlockHeader()
```
    This returns the FIRST block (or record) header. (Not the file header of evio version 6+ files).
    
    Returns:
    
    the first block header.
  - searchEvent
```
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); if object closed
  - searchEvent
```
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
    
    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
```
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.
    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 change the file originally used. A new file can be created by calling either the toFile(String) or toFile(java.io.File) methods.
    
    Parameters:
    
    eventNumber - number of event to remove from buffer
    
    Returns:
    
    new ByteBuffer created and updated to reflect the event removal
    
    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
```
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.
    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 change the file originally used. A new file can be created by calling either the toFile(String) or toFile(java.io.File) methods.
    
    Parameters:
    
    removeNode - evio structure to remove from buffer
    
    Returns:
    
    new ByteBuffer (perhaps created) and updated to reflect the node removal
    
    Throws:
    
    EvioException - if object closed; if node was not found in any event; if internal programming error
  - addStructure
```
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 block 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.
    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 block 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
```
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 or node arg is null.
  - getData
```
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
  - getEventBuffer
```
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.
    
    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
```
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.
    
    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
```
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.
    
    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
```
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.
    
    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
```
void close()
```
    This sets the position to its initial value and marks reader as closed.
  - getEventCount
```
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.
    
    Returns:
    
    the number of events in the file/buffer.
  - getBlockCount
```
int getBlockCount()
```
    This is the number of blocks in the file/buffer including the empty block at the end.
    
    Returns:
    
    the number of blocks in the file/buffer (estimate for version 3 files)
  - toFile
```
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 - name of file to write
    
    Throws:
    
    java.io.IOException - if error writing to file
    
    EvioException - if fileName arg is null; if object closed
  - toFile
```
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 - object of file to write
    
    Throws:
    
    EvioException - if file arg is null; if object closed
    
    java.io.IOException - if error writing to file

Interface IEvioCompactReader

Field Summary

Method Summary

Field Detail

MAGIC_OFFSET

VERSION_OFFSET

VERSION_MASK

Method Detail

isFile

isCompressed

setBuffer

setBuffer

isClosed

getByteOrder

getEvioVersion

getPath

getFileByteOrder

getDictionaryXML

getDictionary

hasDictionary

getMappedByteBuffer

getByteBuffer

fileSize

getEvent

getScannedEvent

getScannedEvent

getFirstBlockHeader

searchEvent

searchEvent

removeEvent

removeStructure

addStructure

getData

getData

getEventBuffer

getEventBuffer

getStructureBuffer

getStructureBuffer

close

getEventCount

getBlockCount

toFile

toFile