evio::EvioReader Class Reference

This is a class of interest to the user. More...

#include <EvioReader.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
	EvioReader (std::string const &path, bool checkRecNumSeq=false, bool synced=false)
	Constructor for reading an event file. More...
	EvioReader (std::shared_ptr< ByteBuffer > &bb, bool checkRecNumSeq=false, bool synced=false)
	Constructor for reading a buffer with option of removing synchronization for much greater speed. 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
	The equivalent of rewinding the file.What it actually does is set the position of the file/buffer back to where it was after calling the constructor - after the first header. Exceptions EvioException if object closed; if failed file access or buffer/file read More...
ssize_t	position () override
	This is equivalent to obtaining the current position in the file.What it actually does is return the position of the buffer. Only meaningful to evio versions 1-3 and for sequential reading. Returns the position of the buffer; -1 if not sequential read and version 4+ Exceptions EvioException if object closed; if error accessing file 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
	Go to a specific event in the file.The events are numbered 1..N. This number is transient–it is not part of the event as stored in the evio file. In versions 4 and up this is just a wrapper on getEvent(size_t). Parameters evNumber the event number in a 1..N counting sense, from the start of the file. Returns the specified event in file or null if there's an error or nothing at that event #. Exceptions EvioException if object closed; if failed file access 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...

Static Public Member Functions
static std::shared_ptr< EvioEvent >	getEvent (uint8_t *src, size_t len, ByteOrder const &order)
	Transform an event in the form of a byte array into an EvioEvent object. More...
static std::shared_ptr< EvioEvent >	parseEvent (uint8_t *src, size_t len, ByteOrder const &order)
	Completely parse the given byte array into an EvioEvent. More...

Detailed Description

This is a class of interest to the user.

It is used to read any evio version format file or buffer. Create an EvioReader object corresponding to an event file or file-formatted buffer, and from this class you can test it for consistency and, more importantly, you can call parseNextEvent or parseEvent(size_t) to get new events and to stream the embedded structures to an IEvioListener.

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' tree structure for access its nodes. For those familiar with XML, the event is processed DOM-like.

Author

heddle (original java version)

timmer

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::EvioReader::EvioReader ( std::string const &  path, bool  checkRecNumSeq = false, bool  synced = false  )

explicit

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.
checkRecNumSeq	if true check the block number sequence and throw an exception if it is not sequential starting with 1.
synced	if true, methods are synchronized for thread safety, else false.

See Also

EventWriter

Exceptions

underflow_error	if too few bytes to read file header
EvioException	if file read failure; if path is empty; bad evio version #; if first block number != 1 when checkBlkNumSeq arg is true

References evio::ByteBuffer::array(), evio::Util::findEvioVersion(), and evio::ByteBuffer::order().

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

explicit

Constructor for reading a buffer with option of removing synchronization for much greater speed.

Parameters

bb	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, methods are synchronized for thread safety, else false.

See Also

EventWriter

Exceptions

underflow_error	if too little data in bb to read.
EvioException	bad evio version #; failure to read first block header

References evio::Util::findEvioVersion().

Member Function Documentation

bool evio::EvioReader::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::EvioReader::close ( )

overridevirtual

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

Implements evio::IEvioReader.

size_t evio::EvioReader::fileSize ( )

overridevirtual

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

Returns

the file size in bytes

Implements evio::IEvioReader.

size_t evio::EvioReader::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::EvioReader::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::EvioReader::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::EvioReader::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::EvioReader::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::EvioReader::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.

Referenced by evio::EvioReaderV6::getEvent(), evio::EvioReaderV6::nextEvent(), and parseEvent().

std::shared_ptr< EvioEvent > evio::EvioReader::getEvent ( uint8_t *  src, size_t  maxLen, ByteOrder const &  order  )

static

Transform an event in the form of a byte array into an EvioEvent object.

However, only top level header is parsed. Most users will want to call parseEvent(uint8_t *, size_t, ByteOrder const &) instead since it returns a fully parsed event. Byte array must not be in file format (have record headers), but must consist of only the bytes comprising the evio event.

Parameters

src	array to parse into EvioEvent object.
maxLen	max length of valid data in src.
order	byte order to use.

Returns

an EvioEvent object parsed from the given array.

Exceptions

EvioException

if null arg, too little data, length too large, or data not in evio format.

References evio::EvioEvent::getInstance(), and evio::Util::toInt().

uint32_t evio::EvioReader::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.

uint32_t evio::EvioReader::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.

size_t evio::EvioReader::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::EvioReader::getEvioVersion ( )

overridevirtual

Get the evio version number.

Returns

evio version number.

Implements evio::IEvioReader.

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

overridevirtual

This returns the FIRST block (record) header.

Returns

the first block (record) header.

Implements evio::IEvioReader.

std::shared_ptr< EvioEvent > evio::EvioReader::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.

size_t evio::EvioReader::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::EvioReader::getParser ( )

overridevirtual

Get the file/buffer parser.

Returns

file/buffer parser.

Implements evio::IEvioReader.

std::string evio::EvioReader::getPath ( )

overridevirtual

Get the path to the file.

Returns

path to the file

Implements evio::IEvioReader.

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

overridevirtual

Go to a specific event in the file.The events are numbered 1..N. This number is transient–it is not part of the event as stored in the evio file. In versions 4 and up this is just a wrapper on getEvent(size_t).

Parameters

evNumber

the event number in a 1..N counting sense, from the start of the file.

Returns

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

Exceptions

EvioException

if object closed; if failed file access

Implements evio::IEvioReader.

bool evio::EvioReader::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::EvioReader::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::EvioReader::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::EvioReader::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.

std::shared_ptr< EvioEvent > evio::EvioReader::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.

Referenced by evio::EvioReaderV6::getFirstEvent().

void evio::EvioReader::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::EvioReader::parseEvent ( uint8_t *  src, size_t  len, ByteOrder const &  order  )

static

Completely parse the given byte array into an EvioEvent.

Byte array must not be in file format (have record headers), but must consist of only the bytes comprising the evio event.

Parameters

src	array to parse into EvioEvent object.
len	max length of valid data in src.
order	byte order to use.

Returns

the EvioEvent object parsed from the given bytes.

Exceptions

EvioException

if null arg, too little data, length too large, or data not in evio format.

References evio::EventParser::eventParse(), and getEvent().

std::shared_ptr< EvioEvent > evio::EvioReader::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.

ssize_t evio::EvioReader::position ( )

overridevirtual

This is equivalent to obtaining the current position in the file.What it actually does is return the position of the buffer. Only meaningful to evio versions 1-3 and for sequential reading.

Returns

the position of the buffer; -1 if not sequential read and version 4+

Exceptions

EvioException

if object closed; if error accessing file

Implements evio::IEvioReader.

void evio::EvioReader::rewind ( )

overridevirtual

The equivalent of rewinding the file.What it actually does is set the position of the file/buffer back to where it was after calling the constructor - after the first header.

Exceptions

EvioException

if object closed; if failed file access or buffer/file read

Implements evio::IEvioReader.

void evio::EvioReader::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::EvioReader::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:

• EvioReader.h
• EvioReader.cpp