org.jlab.coda.jevio

Class EvioReaderV6

java.lang.Object

org.jlab.coda.jevio.EvioReaderV6

All Implemented Interfaces:

IEvioReader

public class EvioReaderV6
extends java.lang.Object
implements IEvioReader

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

Constructor Summary

Constructors

Constructor and Description
EvioReaderV6(java.nio.ByteBuffer byteBuffer) Constructor for reading a buffer.
EvioReaderV6(java.nio.ByteBuffer byteBuffer, boolean checkRecNumSeq) Constructor for reading a buffer.
EvioReaderV6(java.io.File file) Constructor for reading an event file.
EvioReaderV6(java.lang.String path) Constructor for reading an event file.
EvioReaderV6(java.lang.String path, boolean checkRecNumSeq) Constructor for reading an event file.

Method Summary

Modifier and Type	Method and Description
boolean	checkBlockNumberSequence() Is this reader checking the block number sequence and throwing an exception if it's not sequential and starting with 1?
void	close() This is closes the file, but for buffers it only sets the position to 0.
long	fileSize() Get the size of the file being read, in bytes.
int	getBlockCount() This is the number of records in the file/buffer including the empty record or trailer 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.
IBlockHeader	getCurrentBlockHeader() This returns the current (active) block (physical record) header.
java.lang.String	getDictionaryXML() Get the XML format dictionary if there is one.
EvioEvent	getEvent(int index) Get the event in the file/buffer at a given index (starting at 1).
byte[]	getEventArray(int eventNumber) Get an evio bank or event in byte array form.
java.nio.ByteBuffer	getEventBuffer(int eventNumber) 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.
IBlockHeader	getFirstBlockHeader() This returns the FIRST block (physical record) header.
EvioEvent	getFirstEvent() Get the "first" event if there is one.
int	getNumEventsRemaining() Get the number of events remaining in the file.
EventParser	getParser() Get the file/buffer parser.
java.lang.String	getPath() Get the path to the file.
EvioEvent	gotoEventNumber(int evNumber) Deprecated. use parseEvent(int).
boolean	hasDictionaryXML() Does this evio file have an associated XML dictionary?
boolean	hasFirstEvent() Does this evio file have an associated first event? It's also called the Beginning-Of-Run event.
boolean	isClosed() Has IEvioReader.close() been called (without reopening by calling IEvioReader.setBuffer(ByteBuffer))?
EvioEvent	nextEvent() Get the next event in the file/buffer.
void	parseEvent(EvioEvent evioEvent) This will parse an event, SAX-like.
EvioEvent	parseEvent(int index) This is a workhorse method.
EvioEvent	parseNextEvent() This is a workhorse method.
long	position() This method is not relevant in evio 6, does nothing, and returns 0.
void	rewind() This method is not relevant in evio 6 and does nothing.
void	setBuffer(java.nio.ByteBuffer buf) This method can be used to avoid creating additional EvioReader objects by reusing this one with another buffer.
void	setParser(EventParser parser) Set the file/buffer parser.
WriteStatus	toXMLFile(java.lang.String path) Rewrite the file to XML (not including dictionary and "first" event).
WriteStatus	toXMLFile(java.lang.String path, boolean hex) Rewrite the file to XML (not including dictionary and "first" event).
WriteStatus	toXMLFile(java.lang.String path, IEvioProgressListener progressListener) Rewrite the file to XML (not including dictionary and "first" event).
WriteStatus	toXMLFile(java.lang.String path, IEvioProgressListener progressListener, boolean hex) Rewrite the file to XML (not including dictionary and "first" event).

Methods inherited from class java.lang.Object

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

Constructor Detail

EvioReaderV6

public EvioReaderV6(java.lang.String path)
             throws EvioException,
                    java.io.IOException

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.

Throws:

java.io.IOException - if read failure

EvioException - if file arg is null

See Also:

EventWriter

EvioReaderV6

public EvioReaderV6(java.lang.String path,
                    boolean checkRecNumSeq)
             throws EvioException,
                    java.io.IOException

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 record number sequence and throw an exception if it is not sequential starting with 1

Throws:

java.io.IOException - if read failure

EvioException - if file arg is null; if first record number != 1 when checkRecNumSeq arg is true

See Also:

EventWriter

EvioReaderV6

public EvioReaderV6(java.io.File file)
             throws EvioException,
                    java.io.IOException

Constructor for reading an event file. Sequential reading and not memory-mapped buffer.

Parameters:

file - the file that contains events.

Throws:

java.io.IOException - if read failure

EvioException - if file arg is null

See Also:

EventWriter

EvioReaderV6

public EvioReaderV6(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

See Also:

EventWriter

EvioReaderV6

public EvioReaderV6(java.nio.ByteBuffer byteBuffer,
                    boolean checkRecNumSeq)
             throws EvioException

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;

Throws:

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

See Also:

EventWriter

Method Detail

setBuffer

public void setBuffer(java.nio.ByteBuffer buf)
               throws EvioException,
                      java.io.IOException

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.

Specified by:

setBuffer in interface IEvioReader

Parameters:

buf - ByteBuffer to be read

Throws:

java.io.IOException - if read failure

EvioException - if buf is null; if first record number != 1 when checkRecNumSeq arg is true; buf not in evio format.

isClosed

public boolean isClosed()

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

Specified by:

isClosed in interface IEvioReader

Returns:

true if this object closed, else false.

checkBlockNumberSequence

public boolean checkBlockNumberSequence()

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

Specified by:

checkBlockNumberSequence in interface IEvioReader

Returns:

true if checking block number sequence, else false

getByteOrder

public java.nio.ByteOrder getByteOrder()

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

Specified by:

getByteOrder in interface IEvioReader

Returns:

byte order of the file/buffer being read.

getEvioVersion

public int getEvioVersion()

Get the evio version number.

Specified by:

getEvioVersion in interface IEvioReader

Returns:

evio version number.

getPath

public java.lang.String getPath()

Get the path to the file.

Specified by:

getPath in interface IEvioReader

Returns:

path to the file

getParser

public EventParser getParser()

Get the file/buffer parser.

Specified by:

getParser in interface IEvioReader

Returns:

file/buffer parser.

setParser

public void setParser(EventParser parser)

Set the file/buffer parser.

Specified by:

setParser in interface IEvioReader

Parameters:

parser - file/buffer parser.

getDictionaryXML

public java.lang.String getDictionaryXML()

Get the XML format dictionary if there is one.

Specified by:

getDictionaryXML in interface IEvioReader

Returns:

XML format dictionary, else null.

hasDictionaryXML

public boolean hasDictionaryXML()

Does this evio file have an associated XML dictionary?

Specified by:

hasDictionaryXML in interface IEvioReader

Returns:

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

getFirstEvent

public EvioEvent getFirstEvent()

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.

Specified by:

getFirstEvent in interface IEvioReader

Returns:

the first event if it existed, else null.

hasFirstEvent

public boolean hasFirstEvent()

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.

Specified by:

hasFirstEvent in interface IEvioReader

Returns:

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

getNumEventsRemaining

public int getNumEventsRemaining()
                          throws EvioException

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

Specified by:

getNumEventsRemaining in interface IEvioReader

Returns:

number of events remaining in the file

Throws:

EvioException - if failed reading from coda v3 file

getByteBuffer

public java.nio.ByteBuffer getByteBuffer()

Get the byte buffer being read directly or corresponding to the event file. Not a very useful method. For files, it works only for evio format versions 2,3 and returns the internal buffer containing an evio block if using sequential access (for example files > 2.1 GB). It returns the memory mapped buffer otherwise. For reading buffers it returns the buffer being read.

Specified by:

getByteBuffer in interface IEvioReader

Returns:

the byte buffer being read (in certain cases).

fileSize

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

Specified by:

fileSize in interface IEvioReader

Returns:

the file size in bytes

getFirstBlockHeader

public IBlockHeader getFirstBlockHeader()

This returns the FIRST block (physical record) header.

Specified by:

getFirstBlockHeader in interface IEvioReader

Returns:

the first block header.

getEvent

public EvioEvent getEvent(int index)
                   throws EvioException

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(int) instead, since it combines combines getting an event with parsing it.

Specified by:

getEvent in interface IEvioReader

Parameters:

index - the event number in a 1,2,..N counting sense, from beginning of file/buffer.

Returns:

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

Throws:

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

parseEvent

public EvioEvent parseEvent(int index)
                     throws EvioException

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.

Specified by:

parseEvent in interface IEvioReader

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

Throws:

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

nextEvent

public EvioEvent nextEvent()
                    throws EvioException

Get the next event in the file/buffer. As useful as this sounds, most applications will probably call IEvioReader.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.

Specified by:

nextEvent in interface IEvioReader

Returns:

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

Throws:

EvioException - if failed read due to bad buffer format; if object closed

parseNextEvent

public EvioEvent parseNextEvent()
                         throws java.io.IOException,
                                EvioException

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.

Specified by:

parseNextEvent in interface IEvioReader

Returns:

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

Throws:

java.io.IOException - if failed file access

EvioException - if read failure or bad format if object closed

parseEvent

public void parseEvent(EvioEvent evioEvent)
                throws EvioException

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

Specified by:

parseEvent in interface IEvioReader

Parameters:

evioEvent - the event to parse.

Throws:

EvioException - if bad format

getEventArray

public byte[] getEventArray(int eventNumber)
                     throws EvioException

Get an evio bank or event in byte array form.

Specified by:

getEventArray in interface IEvioReader

Parameters:

eventNumber - number of event of interest (starting at 1).

Returns:

array containing bank's/event's bytes.

Throws:

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

getEventBuffer

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

Get an evio bank or event in ByteBuffer form.

Specified by:

getEventBuffer in interface IEvioReader

Parameters:

eventNumber - number of event of interest

Returns:

buffer containing bank's/event's bytes.

Throws:

EvioException - if eventNumber is out of bounds; if the event number does not correspond to an existing event; if object closed

java.io.IOException - if failed file access

rewind

public void rewind()

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

Specified by:

rewind in interface IEvioReader

position

public long position()

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

Specified by:

position in interface IEvioReader

Returns:

the position of the buffer; -1 if version 4+

close

public void close()
           throws java.io.IOException

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

Specified by:

close in interface IEvioReader

Throws:

java.io.IOException - if error accessing file

getCurrentBlockHeader

public IBlockHeader getCurrentBlockHeader()

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

Specified by:

getCurrentBlockHeader in interface IEvioReader

Returns:

the current block header.

gotoEventNumber

@Deprecated
public EvioEvent gotoEventNumber(int evNumber)
                                      throws EvioException

Deprecated. use parseEvent(int).

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

Specified by:

gotoEventNumber in interface IEvioReader

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

Throws:

EvioException - if object closed

toXMLFile

public WriteStatus toXMLFile(java.lang.String path)
                      throws EvioException

Rewrite the file to XML (not including dictionary and "first" event).

Specified by:

toXMLFile in interface IEvioReader

Parameters:

path - the path to the XML file.

Returns:

the status of the write.

Throws:

EvioException - if object closed

toXMLFile

public WriteStatus toXMLFile(java.lang.String path,
                             boolean hex)
                      throws EvioException

Rewrite the file to XML (not including dictionary and "first" event).

Specified by:

toXMLFile in interface IEvioReader

Parameters:

path - the path to the XML file.

hex - if true, ints get displayed in hexadecimal

Returns:

the status of the write.

Throws:

EvioException - if object closed

toXMLFile

public WriteStatus toXMLFile(java.lang.String path,
                             IEvioProgressListener progressListener)
                      throws EvioException

Rewrite the file to XML (not including dictionary and "first" event).

Specified by:

toXMLFile in interface IEvioReader

Parameters:

path - the path to the XML file.

progressListener - and optional progress listener, can be null.

Returns:

the status of the write.

Throws:

EvioException - if object closed

See Also:

IEvioProgressListener

toXMLFile

public WriteStatus toXMLFile(java.lang.String path,
                             IEvioProgressListener progressListener,
                             boolean hex)
                      throws EvioException

Rewrite the file to XML (not including dictionary and "first" event).

Specified by:

toXMLFile in interface IEvioReader

Parameters:

path - the path to the XML file.

progressListener - and optional progress listener, can be null.

hex - if true, ints get displayed in hexadecimal

Returns:

the status of the write.

Throws:

EvioException - if object closed

See Also:

IEvioProgressListener

getEventCount

public int getEventCount()
                  throws EvioException

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

Specified by:

getEventCount in interface IEvioReader

Returns:

the number of events in the file/buffer.

Throws:

EvioException - if read failure; if object closed

getBlockCount

public int getBlockCount()
                  throws EvioException

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

Specified by:

getBlockCount in interface IEvioReader

Returns:

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

Throws:

EvioException - if object closed.