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 from a File object corresponding to an event file, and from this class you can test the file 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. The same can be done by creating an EvioReader from a ByteBuffer. 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.

NOTE: Even though this class has a constructor that accepts an i/o mode, that is for backwards compatibility only. An EvioReader is used for reading and parsing events only. To write an event file or buffer, use an EventWriter object.

Author:

heddle, timmer

Nested Class Summary

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

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.lang.String path)
Constructor for reading an event file.

EvioReader(java.lang.String path, boolean checkBlkNumSeq)
Constructor for reading an event file.

Method Summary

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 equivalent to closing the file.
static boolean	compareEventFiles(java.io.File evFile1, java.io.File evFile2) Method used for diagnostics.
int	fileSize() Obtain the file size using the memory mapped buffer's capacity, which should be the same.
java.nio.ByteBuffer	getByteBuffer() Get the byte buffer being read directly or corresponding to the event file.
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.
java.nio.MappedByteBuffer	getMappedByteBuffer() Get the memory mapped buffer corresponding to the event file.
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?
EvioEvent	nextEvent() Get the next event in the file.
void	parseEvent(EvioEvent evioEvent) This will parse an event, SAX-like.
EvioEvent	parseEvent(int index) This is the workhorse method.
EvioEvent	parseNextEvent() This is the workhorse method.
int	position() This is equivalent to obtaining the current position in the file.
void	position(int position) This is equivalent to setting the current position in the file.
void	rewind() The equivalent of rewinding the file.
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, IEvioProgressListener progressListener) Rewrite the file to XML (not including dictionary).

Methods inherited from class java.lang.Object

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

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.

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.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 file 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 file arg is null; if first block number != 1 when checkBlkNumSeq arg is true

See Also:

EventWriter

Method Detail

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

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 EvioException

Get the number of events remaining in the file.

Returns:

number of events remaining in the file

Throws:

EvioException - if failed reading from coda v3 file

fileSize

public int fileSize()

Obtain the file size using the memory mapped buffer's capacity, which should be the same.

Returns:

the file size in bytes--actually the mapped memory size.

getMappedByteBuffer

public java.nio.MappedByteBuffer getMappedByteBuffer()

Get the memory mapped buffer corresponding to the event file.

Returns:

the memory mapped buffer corresponding to the event file.

getByteBuffer

public java.nio.ByteBuffer getByteBuffer()

Get the byte buffer being read directly or corresponding to the event file.

Returns:

the byte buffer being read directly or corresponding to the event file.

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

Parameters:

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

Returns:

the event in the file 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 < 1

parseEvent

public EvioEvent parseEvent(int index)
                     throws EvioException

This is the 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:

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

nextEvent

public EvioEvent nextEvent()
                    throws EvioException

Get the next event in the file. 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.

In evio version 4, events no longer cross block boundaries. There are only one or more complete events in each block. 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:

EvioException - if failed read due to bad buffer format

parseNextEvent

public EvioEvent parseNextEvent()
                         throws EvioException

This is the workhorse method. It retrieves the next event from the file, and then parses is 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:

EvioException - if read failure or bad format

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 .

Parameters:

evioEvent - the event to parse.

Throws:

EvioException - if bad format

rewind

public void rewind()

The equivalent of rewinding the file. What it actually does is set the position of the buffer back to 0. This method, along with the two position() and the close() method, allows applications to treat files in a normal random access manner.

position

public int position()

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.

Returns:

the position of the buffer.

position

public void position(int position)

This is equivalent to setting the current position in the file. What it actually does is set the position of the buffer. This method, along with the rewind(), position() and the close() method, allows applications to treat files in a normal random access manner.

Parameters:

position - the new position of the buffer.

close

public void close()

This is equivalent to closing the file. What it actually does is clear all data from the buffer, and sets its 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.

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

Returns:

the current block header.

gotoEventNumber

public EvioEvent gotoEventNumber(int evNumber)

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

toXMLFile

public EvioReader.WriteStatus toXMLFile(java.lang.String path)

Rewrite the file to XML (not including dictionary).

Parameters:

path - the path to the XML file.

Returns:

the status of the write.

toXMLFile

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

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.

See Also:

IEvioProgressListener

getEventCount

public int getEventCount()
                  throws 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:

EvioException - if read failure

compareEventFiles

public static boolean compareEventFiles(java.io.File evFile1,
                                        java.io.File evFile2)

Method used for diagnostics. It compares two event files. It checks the following (in order):

1. That neither file is null.
2. That both files exist.
3. That neither file is a directory.
4. That both files can be read.
5. That both files are the same size.
6. That both files contain the same number of events.
7. Finally, that they are the same in a byte-by-byte comparison.

NOTE: Two files with the same events but different physical record size will be reported as different. They will fail the same size test.

Parameters:

evFile1 - first file to be compared

evFile2 - second file to be compared

Returns:

true if the files are, byte-by-byte, identical.