evio::EvioReaderV6 Class Reference

This class is used to read an evio version 6 format file or buffer. More...

#include <EvioReaderV6.h>

Public Types
enum	ReadWriteStatus {   SUCCESS = 0, END_OF_FILE, CANNOT_OPEN_FILE, EVIO_EXCEPTION,   UNKNOWN_ERROR }
	This enum denotes the status of a read/write. More...

Public Member Functions
	EvioReaderV6 (std::string const &path, bool checkRecNumSeq=false, bool synced=false)
	Constructor for reading an event file. More...
	EvioReaderV6 (std::shared_ptr< ByteBuffer > &byteBuffer, bool checkRecNumSeq=false, bool synced=false)
	Constructor for reading a buffer. More...
void	setBuffer (std::shared_ptr< ByteBuffer > &buf) override
	This method can be used to avoid creating additional EvioReader objects by reusing this one with another buffer.The method close() is called before anything else. Parameters buf ByteBuffer to be read. Exceptions underflow_error if not enough data in buffer. EvioException if buf is null; buf not in proper format; if first record/block number != 1 when checkRecNumSeq arg is true. More...
bool	isClosed () override
	Has close() been called (without reopening by calling setBuffer(std::shared_ptr<ByteBuffer> &))? Returns true if this object closed, else false . More...
bool	checkBlockNumberSequence () override
	Is this reader checking the block number sequence and throwing an exception if it's not sequential and starting with 1? Returns true if checking block number sequence, else false More...
ByteOrder &	getByteOrder () override
	Get the byte order of the file/buffer being read. Returns byte order of the file/buffer being read. More...
uint32_t	getEvioVersion () override
	Get the evio version number. Returns evio version number. More...
std::string	getPath () override
	Get the path to the file. Returns path to the file More...
std::shared_ptr< EventParser > &	getParser () override
	Get the file/buffer parser. Returns file/buffer parser. More...
void	setParser (std::shared_ptr< EventParser > &evParser) override
	Set the file/buffer parser. Parameters evParser file/buffer parser. More...
std::string	getDictionaryXML () override
	Get the XML format dictionary if there is one. Returns XML format dictionary, else null. More...
bool	hasDictionaryXML () override
	Does this evio file have an associated XML dictionary? Returns true if this evio file has an associated XML dictionary, else false More...
std::shared_ptr< EvioEvent >	getFirstEvent () override
	Get the "first" event if there is one.It's also called the Beginning-Of-Run event. This event is defined once but included in each of the related split files written out. Returns the first event is it existed, else null. More...
bool	hasFirstEvent () override
	Does this evio file have an associated first event? It's also called the Beginning-Of-Run event.This event is defined once but included in each of the related split files written out. Returns true if this evio file has an associated first event, else false More...
size_t	getNumEventsRemaining () override
	Get the number of events remaining in the file.Useful only if doing a sequential read. Returns number of events remaining in the file Exceptions EvioException if failed reading from file More...
std::shared_ptr< ByteBuffer >	getByteBuffer () override
	Get the byte buffer being read.Not useful when reading files. Returns the byte buffer being read (in certain cases). More...
size_t	fileSize () override
	Get the size of the file being read, in bytes. Returns the file size in bytes More...
std::shared_ptr< IBlockHeader >	getFirstBlockHeader () override
	This returns the FIRST block (record) header. Returns the first block (record) header. More...
std::shared_ptr< EvioEvent >	getEvent (size_t index) override
	Get the event in the file/buffer at a given index (starting at 1).As useful as this sounds, most applications will probably call parseNextEvent() or parseEvent(size_t) instead, since it combines combines getting an event with parsing it. Parameters index number of event desired, starting at 1, from beginning of file/buffer Returns the event in the file/buffer at the given index or null if none Exceptions EvioException if failed file access; if failed read due to bad file/buffer format; if index out of bounds; if object closed More...
std::shared_ptr< EvioEvent >	parseEvent (size_t index) override
	This is a workhorse method.It retrieves the desired event from the file/buffer, and then parses it SAX-like. It will drill down and uncover all structures (banks, segments, and tagsegments) and notify any interested listeners. Parameters index number of event desired, starting at 1, from beginning of file/buffer Returns the parsed event at the given index or null if none Exceptions EvioException if failed file access; if failed read due to bad file/buffer format; if index out of bounds; if object closed More...
std::shared_ptr< EvioEvent >	nextEvent () override
	Get the next event in the file/buffer.As useful as this sounds, most applications will probably call parseNextEvent() instead, since it combines getting the next event with parsing the next event.Although this method can get events in versions 4+, it now delegates that to another method. No changes were made to this method from versions 1-3 in order to read the version 4 format as it is subset of versions 1-3 with variable block length. Returns the next event in the file. On error it throws an EvioException. On end of file, it returns null. Exceptions EvioException if failed file access; if failed read due to bad buffer format; if object closed More...
std::shared_ptr< EvioEvent >	parseNextEvent () override
	This is a workhorse method.It retrieves the next event from the file/buffer, and then parses it SAX-like. It will drill down and uncover all structures (banks, segments, and tagsegments) and notify any interested listeners. Returns the event that was parsed. On error it throws an EvioException. On end of file, it returns null. Exceptions EvioException if failed file access; if read failure or bad format; if object closed More...
void	parseEvent (std::shared_ptr< EvioEvent > evioEvent) override
	This will parse an event, SAX-like.It will drill down and uncover all structures (banks, segments, and tagsegments) and notify any interested listeners.As useful as this sounds, most applications will probably call parseNextEvent() instead, since it combines combines getting the next event with parsing the next event.This method is only called by synchronized methods and therefore is not synchronized. Parameters evioEvent the event to parse. Exceptions EvioException if bad format More...
uint32_t	getEventArray (size_t evNumber, std::vector< uint8_t > &vec) override
	Get an evio bank or event in vector-of-bytes form. Parameters evNumber number of event of interest (starting at 1). vec vector to contain bank's/event's bytes. Returns number of bytes in returned event. Exceptions EvioException if failed file access; if eventNumber out of bounds (starts at 1); if the event number does not correspond to an existing event; if object closed More...
uint32_t	getEventBuffer (size_t evNumber, ByteBuffer &buf) override
	Get an evio bank or event in ByteBuffer form. Parameters evNumber number of event of interest buf buffer to contain bank's/event's bytes. Returns number of bytes in returned event. Exceptions EvioException if failed file access; if eventNumber out of bounds (starts at 1); if the event number does not correspond to an existing event; if object closed More...
void	rewind () override
	This method is not relevant in evio 6 and does nothing. More...
ssize_t	position () override
	This method is not relevant in evio 6, does nothing, and returns 0. More...
void	close () override
	This is closes the file, but for buffers it only sets the position to 0. More...
std::shared_ptr< IBlockHeader >	getCurrentBlockHeader () override
	This returns the current (active) block (physical record) header.Since most users have no interest in physical records, this method should not be used. Returns the current block header. More...
std::shared_ptr< EvioEvent >	gotoEventNumber (size_t evNumber) override
	In this version, this method is a wrapper on parseEvent(size_t). More...
size_t	getEventCount () override
	This is the number of events in the file/buffer.Any dictionary or first event are not included in the count. Returns the number of events in the file/buffer. Exceptions EvioException if read failure; if failed file access; if object closed More...
size_t	getBlockCount () override
	This is the number of blocks/records in the file/buffer including the empty block, record or trailer at the end. Exceptions EvioException if object closed. Returns the number of records in the file/buffer (estimate for version 3 files). More...

Detailed Description

This class is used to read an evio version 6 format file or buffer.

It is called by an EvioReader object. This class is mostly a wrapper to the new hipo library.

The streaming effect of parsing an event is that the parser will read the event and hand off structures, such as banks, to any IEvioListeners. For those familiar with XML, the event is processed SAX-like. It is up to the listener to decide what to do with the structures.

As an alternative to stream processing, after an event is parsed, the user can use the events treeModel for access to the structures. For those familiar with XML, the event is processed DOM-like.

Since

version 6

Author

timmer

Date

6/16/2020

Member Enumeration Documentation

enum evio::IEvioReader::ReadWriteStatus

inherited

This enum denotes the status of a read/write.

Used internally.
SUCCESS indicates a successful read.
END_OF_FILE indicates that we cannot read because an END_OF_FILE has occurred. Technically this means that whatever we are trying to read is larger than the buffer's unread bytes.
CANNOT_OPEN_FILE indicates that we cannot write because the destination file cannot be opened.
EVIO_EXCEPTION indicates that an EvioException was thrown during a read/write, possibly due to out of range values.
UNKNOWN_ERROR indicates that an unrecoverable error has occurred.

Enumerator
SUCCESS
END_OF_FILE
CANNOT_OPEN_FILE
EVIO_EXCEPTION
UNKNOWN_ERROR

Constructor & Destructor Documentation

evio::EvioReaderV6::EvioReaderV6 ( std::string const &  path, bool  checkSeq = false, bool  synced = false  )

explicit

Constructor for reading an event file.

Parameters

path	the full path to the file that contains events.
checkSeq	if true check the record number sequence and throw an exception if it is not sequential starting with 1
synced	if true, this class's methods are mutex protected for thread safety.

See Also

EventWriter

Exceptions

IOException	if read failure
EvioException	if file arg is null; if file is too small to have valid evio format data if first record number != 1 when checkRecNumSeq arg is true

evio::EvioReaderV6::EvioReaderV6 ( std::shared_ptr< ByteBuffer > &  byteBuffer, bool  checkRecNumSeq = false, bool  synced = false  )

explicit

Constructor for reading a buffer.

Parameters

byteBuffer	the buffer that contains events.
checkRecNumSeq	if true check the record number sequence and throw an exception if it is not sequential starting with 1
synced	if true, this class's methods are mutex protected for thread safety.

See Also

EventWriter

Exceptions

EvioException

if buffer arg is null; if first record number != 1 when checkRecNumSeq arg is true; if buffer data not in evio format.

Member Function Documentation

bool evio::EvioReaderV6::checkBlockNumberSequence ( )

overridevirtual

Is this reader checking the block number sequence and throwing an exception if it's not sequential and starting with 1?

Returns

true if checking block number sequence, else false

Implements evio::IEvioReader.

void evio::EvioReaderV6::close ( )

overridevirtual

This is closes the file, but for buffers it only sets the position to 0.

Exceptions

IOException

if error accessing file

Implements evio::IEvioReader.

size_t evio::EvioReaderV6::fileSize ( )

overridevirtual

Get the size of the file being read, in bytes.

Returns

the file size in bytes

Implements evio::IEvioReader.

size_t evio::EvioReaderV6::getBlockCount ( )

overridevirtual

This is the number of blocks/records in the file/buffer including the empty block, record or trailer at the end.

Exceptions

EvioException

if object closed.

Returns

the number of records in the file/buffer (estimate for version 3 files).

Implements evio::IEvioReader.

std::shared_ptr< ByteBuffer > evio::EvioReaderV6::getByteBuffer ( )

overridevirtual

Get the byte buffer being read.Not useful when reading files.

Returns

the byte buffer being read (in certain cases).

Implements evio::IEvioReader.

ByteOrder & evio::EvioReaderV6::getByteOrder ( )

overridevirtual

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

Returns

byte order of the file/buffer being read.

Implements evio::IEvioReader.

std::shared_ptr< IBlockHeader > evio::EvioReaderV6::getCurrentBlockHeader ( )

overridevirtual

This returns the current (active) block (physical record) header.Since most users have no interest in physical records, this method should not be used.

Returns

the current block header.

Implements evio::IEvioReader.

std::string evio::EvioReaderV6::getDictionaryXML ( )

overridevirtual

Get the XML format dictionary if there is one.

Returns

XML format dictionary, else null.

Implements evio::IEvioReader.

std::shared_ptr< EvioEvent > evio::EvioReaderV6::getEvent ( size_t  index )

overridevirtual

Get the event in the file/buffer at a given index (starting at 1).As useful as this sounds, most applications will probably call parseNextEvent() or parseEvent(size_t) instead, since it combines combines getting an event with parsing it.

Parameters

index

number of event desired, starting at 1, from beginning of file/buffer

Returns

the event in the file/buffer at the given index or null if none

Exceptions

EvioException

if failed file access; if failed read due to bad file/buffer format; if index out of bounds; if object closed

Implements evio::IEvioReader.

References evio::EvioReader::getEvent(), and getEventArray().

Referenced by parseEvent().

uint32_t evio::EvioReaderV6::getEventArray ( size_t  evNumber, std::vector< uint8_t > &  vec  )

overridevirtual

Get an evio bank or event in vector-of-bytes form.

Parameters

evNumber	number of event of interest (starting at 1).
vec	vector to contain bank's/event's bytes.

Returns

number of bytes in returned event.

Exceptions

EvioException

if failed file access; if eventNumber out of bounds (starts at 1); if the event number does not correspond to an existing event; if object closed

Implements evio::IEvioReader.

Referenced by getEvent().

uint32_t evio::EvioReaderV6::getEventBuffer ( size_t  evNumber, ByteBuffer &  buf  )

overridevirtual

Get an evio bank or event in ByteBuffer form.

Parameters

evNumber	number of event of interest
buf	buffer to contain bank's/event's bytes.

Returns

number of bytes in returned event.

Exceptions

EvioException

if failed file access; if eventNumber out of bounds (starts at 1); if the event number does not correspond to an existing event; if object closed

Implements evio::IEvioReader.

References evio::ByteBuffer::array(), evio::ByteBuffer::arrayOffset(), evio::ByteBuffer::clear(), and evio::ByteBuffer::expand().

size_t evio::EvioReaderV6::getEventCount ( )

overridevirtual

This is the number of events in the file/buffer.Any dictionary or first event are not included in the count.

Returns

the number of events in the file/buffer.

Exceptions

EvioException

if read failure; if failed file access; if object closed

Implements evio::IEvioReader.

uint32_t evio::EvioReaderV6::getEvioVersion ( )

overridevirtual

Get the evio version number.

Returns

evio version number.

Implements evio::IEvioReader.

std::shared_ptr< IBlockHeader > evio::EvioReaderV6::getFirstBlockHeader ( )

overridevirtual

This returns the FIRST block (record) header.

Returns

the first block (record) header.

Implements evio::IEvioReader.

std::shared_ptr< EvioEvent > evio::EvioReaderV6::getFirstEvent ( )

overridevirtual

Get the "first" event if there is one.It's also called the Beginning-Of-Run event. This event is defined once but included in each of the related split files written out.

Returns

the first event is it existed, else null.

Implements evio::IEvioReader.

References evio::EvioReader::parseEvent().

size_t evio::EvioReaderV6::getNumEventsRemaining ( )

overridevirtual

Get the number of events remaining in the file.Useful only if doing a sequential read.

Returns

number of events remaining in the file

Exceptions

EvioException

if failed reading from file

Implements evio::IEvioReader.

std::shared_ptr< EventParser > & evio::EvioReaderV6::getParser ( )

overridevirtual

Get the file/buffer parser.

Returns

file/buffer parser.

Implements evio::IEvioReader.

std::string evio::EvioReaderV6::getPath ( )

overridevirtual

Get the path to the file.

Returns

path to the file

Implements evio::IEvioReader.

std::shared_ptr< EvioEvent > evio::EvioReaderV6::gotoEventNumber ( size_t  evNumber )

overridevirtual

In this version, this method is a wrapper on parseEvent(size_t).

Deprecated:

use parseEvent(size_t).

Parameters

evNumber

the event number from the start of the file starting at 1.

Returns

the specified event in file or null if there's an error or nothing at that event #.

Exceptions

EvioException

if object closed

Implements evio::IEvioReader.

References parseEvent().

bool evio::EvioReaderV6::hasDictionaryXML ( )

overridevirtual

Does this evio file have an associated XML dictionary?

Returns

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

Implements evio::IEvioReader.

bool evio::EvioReaderV6::hasFirstEvent ( )

overridevirtual

Does this evio file have an associated first event? It's also called the Beginning-Of-Run event.This event is defined once but included in each of the related split files written out.

Returns

true if this evio file has an associated first event, else false

Implements evio::IEvioReader.

bool evio::EvioReaderV6::isClosed ( )

overridevirtual

Has close() been called (without reopening by calling setBuffer(std::shared_ptr<ByteBuffer> &))?

Returns

true 

if this object closed, else

false 

.

Implements evio::IEvioReader.

std::shared_ptr< EvioEvent > evio::EvioReaderV6::nextEvent ( )

overridevirtual

Get the next event in the file/buffer.As useful as this sounds, most applications will probably call parseNextEvent() instead, since it combines getting the next event with parsing the next event.Although this method can get events in versions 4+, it now delegates that to another method. No changes were made to this method from versions 1-3 in order to read the version 4 format as it is subset of versions 1-3 with variable block length.

Returns

the next event in the file. On error it throws an EvioException. On end of file, it returns null.

Exceptions

EvioException

if failed file access; if failed read due to bad buffer format; if object closed

Implements evio::IEvioReader.

References evio::EvioReader::getEvent().

Referenced by parseNextEvent().

std::shared_ptr< EvioEvent > evio::EvioReaderV6::parseEvent ( size_t  index )

overridevirtual

This is a workhorse method.It retrieves the desired event from the file/buffer, and then parses it SAX-like. It will drill down and uncover all structures (banks, segments, and tagsegments) and notify any interested listeners.

Parameters

index

number of event desired, starting at 1, from beginning of file/buffer

Returns

the parsed event at the given index or null if none

Exceptions

EvioException

if failed file access; if failed read due to bad file/buffer format; if index out of bounds; if object closed

Implements evio::IEvioReader.

References getEvent().

Referenced by gotoEventNumber(), and parseNextEvent().

void evio::EvioReaderV6::parseEvent ( std::shared_ptr< EvioEvent >  evioEvent )

overridevirtual

This will parse an event, SAX-like.It will drill down and uncover all structures (banks, segments, and tagsegments) and notify any interested listeners.As useful as this sounds, most applications will probably call parseNextEvent() instead, since it combines combines getting the next event with parsing the next event.This method is only called by synchronized methods and therefore is not synchronized.

Parameters

evioEvent

the event to parse.

Exceptions

EvioException

if bad format

Implements evio::IEvioReader.

std::shared_ptr< EvioEvent > evio::EvioReaderV6::parseNextEvent ( )

overridevirtual

This is a workhorse method.It retrieves the next event from the file/buffer, and then parses it SAX-like. It will drill down and uncover all structures (banks, segments, and tagsegments) and notify any interested listeners.

Returns

the event that was parsed. On error it throws an EvioException. On end of file, it returns null.

Exceptions

EvioException

if failed file access; if read failure or bad format; if object closed

Implements evio::IEvioReader.

References nextEvent(), and parseEvent().

ssize_t evio::EvioReaderV6::position ( )

overridevirtual

This method is not relevant in evio 6, does nothing, and returns 0.

Returns

0

Implements evio::IEvioReader.

void evio::EvioReaderV6::rewind ( )

overridevirtual

This method is not relevant in evio 6 and does nothing.

Implements evio::IEvioReader.

void evio::EvioReaderV6::setBuffer ( std::shared_ptr< ByteBuffer > &  buf )

overridevirtual

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

Parameters

buf	ByteBuffer to be read.

Exceptions

underflow_error	if not enough data in buffer.
EvioException	if buf is null; buf not in proper format; if first record/block number != 1 when checkRecNumSeq arg is true.

Implements evio::IEvioReader.

void evio::EvioReaderV6::setParser ( std::shared_ptr< EventParser > &  evParser )

overridevirtual

Set the file/buffer parser.

Parameters

evParser

file/buffer parser.

Implements evio::IEvioReader.

---

The documentation for this class was generated from the following files:

• EvioReaderV6.h
• EvioReaderV6.cpp