org.jlab.coda.jevio

Class EvioReader

java.lang.Object

org.jlab.coda.jevio.EvioReader

public class EvioReader
extends java.lang.Object

This is a class of interest to the user. It is used to read an evio version 4 or earlier 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(int) to get new events and to stream the embedded structures to an IEvioListener.

A word to the wise, constructors for reading a file in random access mode (by setting "sequential" arg to false), will memory map the file. This is not a good idea if the file is not on a local disk. Due to java restrictions, files over 2.1GB will require multiple memory maps.

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.

Author:

heddle, timmer

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	EvioReader.ReadStatus This enum denotes the status of a read.
static class	EvioReader.WriteStatus This enum denotes the status of a write. SUCCESS indicates a successful write.

Constructor Summary

Constructors

Constructor and Description
EvioReader(java.nio.ByteBuffer byteBuffer) Constructor for reading a buffer.
EvioReader(java.nio.ByteBuffer byteBuffer, boolean checkBlkNumSeq) Constructor for reading a buffer.
EvioReader(java.io.File file) Constructor for reading an event file.
EvioReader(java.io.File file, boolean checkBlkNumSeq) Constructor for reading an event file.
EvioReader(java.io.File file, boolean checkBlkNumSeq, boolean sequential) Constructor for reading an event file.
EvioReader(java.lang.String path) Constructor for reading an event file.
EvioReader(java.lang.String path, boolean checkBlkNumSeq) Constructor for reading an event file.
EvioReader(java.lang.String path, boolean checkBlkNumSeq, boolean sequential) 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 is 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 blocks in the file including the empty block usually at the end of version 4 files/buffers.
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 is there is one.
EvioEvent	getEvent(int index) Get the event in the file/buffer at a given index (starting at 1).
int	getEventCount() This is the number of events in the file.
int	getEvioVersion() Get the evio version number.
IBlockHeader	getFirstBlockHeader() This returns the FIRST block (physical record) header.
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) Go to a specific event in the file.
boolean	hasDictionaryXML() Does this evio file have an associated XML dictionary?
boolean	isClosed() Has close() been called (without reopening by calling setBuffer(java.nio.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.
protected void	parseFirstHeader(java.nio.ByteBuffer headerBuf) Reads 8 words of the first block (physical record) header in order to determine the evio version # and endianness of the file or buffer in question.
EvioEvent	parseNextEvent() This is a workhorse method.
long	position() This is equivalent to obtaining the current position in the file.
void	position(long position) Deprecated.
protected EvioReader.ReadStatus	processNextBlock() Reads the block (physical record) header.
void	rewind() The equivalent of rewinding the file.
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.
EvioReader.WriteStatus	toXMLFile(java.lang.String path) Rewrite the file to XML (not including dictionary).
EvioReader.WriteStatus	toXMLFile(java.lang.String path, boolean hex) Rewrite the file to XML (not including dictionary).
EvioReader.WriteStatus	toXMLFile(java.lang.String path, IEvioProgressListener progressListener) Rewrite the file to XML (not including dictionary).
EvioReader.WriteStatus	toXMLFile(java.lang.String path, IEvioProgressListener progressListener, boolean hex) Rewrite the file to XML (not including dictionary).

Methods inherited from class java.lang.Object

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

Constructor Detail

EvioReader

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

EvioReader

public EvioReader(java.lang.String path,
                  boolean checkBlkNumSeq)
           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.

checkBlkNumSeq - if true check the block 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 block number != 1 when checkBlkNumSeq arg is true

See Also:

EventWriter

EvioReader

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

EvioReader

public EvioReader(java.io.File file,
                  boolean checkBlkNumSeq)
           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.

checkBlkNumSeq - if true check the block 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 block number != 1 when checkBlkNumSeq arg is true

See Also:

EventWriter

EvioReader

public EvioReader(java.lang.String path,
                  boolean checkBlkNumSeq,
                  boolean sequential)
           throws EvioException,
                  java.io.IOException

Constructor for reading an event file. Do not set sequential to false for remote files.

Parameters:

path - the full path to the file that contains events. For writing event files, use an EventWriter object.

checkBlkNumSeq - if true check the block number sequence and throw an exception if it is not sequential starting with 1

sequential - if true read the file sequentially, else use memory mapped buffers. If file > 2.1 GB, reads are always sequential for the older evio format.

Throws:

java.io.IOException - if read failure

EvioException - if file arg is null; if first block number != 1 when checkBlkNumSeq arg is true

See Also:

EventWriter

EvioReader

public EvioReader(java.io.File file,
                  boolean checkBlkNumSeq,
                  boolean sequential)
           throws EvioException,
                  java.io.IOException

Constructor for reading an event file. Do not set sequential to false for remote files.

Parameters:

file - the file that contains events.

checkBlkNumSeq - if true check the block number sequence and throw an exception if it is not sequential starting with 1

sequential - if true read the file sequentially, else use memory mapped buffers. If file > 2.1 GB, reads are always sequential for the older evio format.

Throws:

java.io.IOException - if read failure

EvioException - if file arg is null; if file is too small to have valid evio format data if first block number != 1 when checkBlkNumSeq arg is true

See Also:

EventWriter

EvioReader

public EvioReader(java.nio.ByteBuffer byteBuffer)
           throws EvioException,
                  java.io.IOException

Constructor for reading a buffer.

Parameters:

byteBuffer - the buffer that contains events.

Throws:

java.io.IOException - if read failure

EvioException - if buffer arg is null

See Also:

EventWriter

EvioReader

public EvioReader(java.nio.ByteBuffer byteBuffer,
                  boolean checkBlkNumSeq)
           throws EvioException,
                  java.io.IOException

Constructor for reading a buffer.

Parameters:

byteBuffer - the buffer that contains events.

checkBlkNumSeq - if true check the block number sequence and throw an exception if it is not sequential starting with 1

Throws:

java.io.IOException - if read failure

EvioException - if buffer arg is null; if first block number != 1 when checkBlkNumSeq arg is true

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.

Parameters:

buf - ByteBuffer to be read

Throws:

java.io.IOException - if read failure

EvioException - if buf is null; if first block number != 1 when checkBlkNumSeq arg is true

isClosed

public boolean isClosed()

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

Returns:

true if this object closed, else false.

checkBlockNumberSequence

public boolean checkBlockNumberSequence()

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

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.

Returns:

byte order of the file/buffer being read.

getEvioVersion

public int getEvioVersion()

Get the evio version number.

Returns:

evio version number.

getPath

public java.lang.String getPath()

Get the path to the file.

Returns:

path to the file

getParser

public EventParser getParser()

Get the file/buffer parser.

Returns:

file/buffer parser.

setParser

public void setParser(EventParser parser)

Set the file/buffer parser.

Parameters:

parser - file/buffer parser.

getDictionaryXML

public java.lang.String getDictionaryXML()

Get the XML format dictionary is there is one.

Returns:

XML format dictionary, else null.

hasDictionaryXML

public boolean hasDictionaryXML()

Does this evio file have an associated XML dictionary?

Returns:

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

getNumEventsRemaining

public int getNumEventsRemaining()
                          throws java.io.IOException,
                                 EvioException

Get the number of events remaining in the file.

Returns:

number of events remaining in the file

Throws:

java.io.IOException - if failed file access

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.

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.

Returns:

the file size in bytes

getFirstBlockHeader

public IBlockHeader getFirstBlockHeader()

This returns the FIRST block (physical record) header.

Returns:

the first block header.

parseFirstHeader

protected void parseFirstHeader(java.nio.ByteBuffer headerBuf)
                         throws EvioException

Reads 8 words of the first block (physical record) header in order to determine the evio version # and endianness of the file or buffer in question. These things do not need to be examined in subsequent block headers. Called only by synchronized methods or constructors.

Parameters:

headerBuf - buffer to parse.

Throws:

EvioException - if buffer too small, contains invalid data, or bad block # sequence

processNextBlock

protected EvioReader.ReadStatus processNextBlock()
                                          throws java.io.IOException

Reads the block (physical record) header. Assumes mapped buffer or file is positioned at start of the next block header. If a sequential file: version 4, Read the entire next block into internal buffer. version 1-3, If unused data still exists in internal buffer, don't read anymore in right now as there is at least 1 block there (integral # of blocks read in). If no data in internal buffer read DEFAULT_READ_BYTES or the rest of the file, whichever is smaller, into the internal buffer. By the time this is called, the version # and byte order have already been determined. Not necessary to do that for each block header that's read. Called from synchronized method.

A Bank header is 8, 32-bit ints. The first int is the size of the block in ints (not counting the length itself, i.e., the number of ints to follow). Most users should have no need for this method, since most applications do not care about the block (physical record) header.

Returns:

status of read attempt

Throws:

java.io.IOException - if file access problems, evio format problems

getEvent

public EvioEvent getEvent(int index)
                   throws java.io.IOException,
                          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.

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:

java.io.IOException - if failed file access

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

parseEvent

public EvioEvent parseEvent(int index)
                     throws java.io.IOException,
                            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.

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:

java.io.IOException - if failed file access

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

nextEvent

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

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.

Throws:

java.io.IOException - if failed file access

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.

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

Throws:

EvioException - if bad format

rewind

public void rewind()
            throws java.io.IOException,
                   EvioException

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. This method, along with the two position() and the close() method, allows applications to treat files in a normal random access manner.

Throws:

java.io.IOException - if failed file access or buffer/file read

EvioException - if object closed

position

public long position()
              throws java.io.IOException,
                     EvioException

This is equivalent to obtaining the current position in the file. What it actually does is return the position of the buffer. This method, along with the rewind(), position(int) and the close() method, allows applications to treat files in a normal random access manner. Only meaningful to evio versions 1-3 and for sequential reading.

Returns:

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

Throws:

java.io.IOException - if error accessing file

EvioException - if object closed

position

@Deprecated
public void position(long position)
                          throws java.io.IOException,
                                 EvioException

Deprecated.

This method sets the current position in the file or buffer. This method, along with the rewind(), position() and the close() method, allows applications to treat files in a normal random access manner. Only meaningful to evio versions 1-3 and for sequential reading.

HOWEVER, using this method is not necessary for random access of events and is no longer recommended because it interferes with the sequential reading of events. Therefore it is now deprecated.

Parameters:

position - the new position of the buffer.

Throws:

java.io.IOException - if error accessing file

EvioException - if object closed

close

public void close()
           throws java.io.IOException

This is closes the file, but for buffers it only sets the position to 0. This method, along with the rewind() and the two position() methods, allows applications to treat files in a normal random access manner.

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. Mostly it is used by the test programs in the EvioReaderTest class.

Returns:

the current block header.

gotoEventNumber

public EvioEvent gotoEventNumber(int evNumber)
                          throws java.io.IOException,
                                 EvioException

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(int).

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

Throws:

java.io.IOException - if failed file access

EvioException - if object closed

toXMLFile

public EvioReader.WriteStatus toXMLFile(java.lang.String path)
                                 throws java.io.IOException,
                                        EvioException

Rewrite the file to XML (not including dictionary).

Parameters:

path - the path to the XML file.

Returns:

the status of the write.

Throws:

java.io.IOException - if failed file access

EvioException - if object closed

toXMLFile

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

Rewrite the file to XML (not including dictionary).

Parameters:

path - the path to the XML file.

hex - if true, ints get displayed in hexadecimal

Returns:

the status of the write.

Throws:

java.io.IOException - if failed file access

EvioException - if object closed

toXMLFile

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

Rewrite the file to XML (not including dictionary).

Parameters:

path - the path to the XML file.

progressListener - and optional progress listener, can be null.

Returns:

the status of the write.

Throws:

java.io.IOException - if failed file access

EvioException - if object closed

See Also:

IEvioProgressListener

toXMLFile

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

Rewrite the file to XML (not including dictionary).

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:

java.io.IOException - if failed file access

EvioException - if object closed

See Also:

IEvioProgressListener

getEventCount

public int getEventCount()
                  throws java.io.IOException,
                         EvioException

This is the number of events in the file. 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.

Throws:

java.io.IOException - if failed file access

EvioException - if read failure; if object closed

getBlockCount

public int getBlockCount()
                  throws EvioException

This is the number of blocks in the file including the empty block usually at the end of version 4 files/buffers. For version 3 files, a block size read from the first block is used to calculate the result. It is not computed unless in random access mode or is asked for, and if asked for it is computed and cached.

Returns:

the number of blocks in the file (estimate for version 3 files)

Throws:

EvioException - if object closed