public class EvioReader
extends java.lang.Object
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.
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 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.
|
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.
|
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.
|
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).
|
public EvioReader(java.lang.String path) throws EvioException, java.io.IOException
path
- the full path to the file that contains events.
For writing event files, use an EventWriter
object.java.io.IOException
- if read failureEvioException
- if file arg is nullEventWriter
public EvioReader(java.lang.String path, boolean checkBlkNumSeq) throws EvioException, java.io.IOException
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 1java.io.IOException
- if read failureEvioException
- if file arg is null;
if first block number != 1 when checkBlkNumSeq arg is trueEventWriter
public EvioReader(java.io.File file) throws EvioException, java.io.IOException
file
- the file that contains events.java.io.IOException
- if read failureEvioException
- if file arg is nullEventWriter
public EvioReader(java.io.File file, boolean checkBlkNumSeq) throws EvioException, java.io.IOException
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 1java.io.IOException
- if read failureEvioException
- if file arg is null;
if first block number != 1 when checkBlkNumSeq arg is trueEventWriter
public EvioReader(java.lang.String path, boolean checkBlkNumSeq, boolean sequential) throws EvioException, java.io.IOException
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 1sequential
- 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.java.io.IOException
- if read failureEvioException
- if file arg is null;
if first block number != 1 when checkBlkNumSeq arg is trueEventWriter
public EvioReader(java.io.File file, boolean checkBlkNumSeq, boolean sequential) throws EvioException, java.io.IOException
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 1sequential
- 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.java.io.IOException
- if read failureEvioException
- 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 trueEventWriter
public EvioReader(java.nio.ByteBuffer byteBuffer) throws EvioException, java.io.IOException
byteBuffer
- the buffer that contains events.java.io.IOException
- if read failureEvioException
- if buffer arg is nullEventWriter
public EvioReader(java.nio.ByteBuffer byteBuffer, boolean checkBlkNumSeq) throws EvioException, java.io.IOException
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 1java.io.IOException
- if read failureEvioException
- if buffer arg is null;
if first block number != 1 when checkBlkNumSeq arg is trueEventWriter
public void setBuffer(java.nio.ByteBuffer buf) throws EvioException, java.io.IOException
close()
is called before anything else.buf
- ByteBuffer to be readjava.io.IOException
- if read failureEvioException
- if buf is null;
if first block number != 1 when checkBlkNumSeq arg is truepublic boolean isClosed()
close()
been called (without reopening by calling
setBuffer(java.nio.ByteBuffer)
)?true
if this object closed, else false
.public boolean checkBlockNumberSequence()
true
if checking block number sequence, else false
public java.nio.ByteOrder getByteOrder()
public int getEvioVersion()
public java.lang.String getPath()
public EventParser getParser()
public void setParser(EventParser parser)
parser
- file/buffer parser.public java.lang.String getDictionaryXML()
public boolean hasDictionaryXML()
true
if this evio file has an associated XML dictionary,
else false
public int getNumEventsRemaining() throws java.io.IOException, EvioException
java.io.IOException
- if failed file accessEvioException
- if failed reading from coda v3 filepublic java.nio.ByteBuffer getByteBuffer()
public long fileSize()
public IBlockHeader getFirstBlockHeader()
public EvioEvent getEvent(int index) throws java.io.IOException, EvioException
parseNextEvent()
or parseEvent(int)
instead,
since it combines combines getting an event with parsing it.index
- the event number in a 1,2,..N counting sense, from beginning of file/buffer.java.io.IOException
- if failed file accessEvioException
- if failed read due to bad file/buffer format;
if out of memory;
if index < 1;
if object closedpublic EvioEvent parseEvent(int index) throws java.io.IOException, EvioException
index
- number of event desired, starting at 1, from beginning of file/bufferjava.io.IOException
- if failed file accessEvioException
- if failed read due to bad file/buffer format;
if out of memory;
if index < 1;
if object closedpublic EvioEvent nextEvent() throws java.io.IOException, EvioException
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.
null
.java.io.IOException
- if failed file accessEvioException
- if failed read due to bad buffer format;
if object closedpublic EvioEvent parseNextEvent() throws java.io.IOException, EvioException
null
.java.io.IOException
- if failed file accessEvioException
- if read failure or bad format
if object closedpublic void parseEvent(EvioEvent evioEvent) throws EvioException
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.
evioEvent
- the event to parse.EvioException
- if bad formatpublic void rewind() throws java.io.IOException, EvioException
position()
and the
close()
method, allows applications to treat files
in a normal random access manner.java.io.IOException
- if failed file access or buffer/file readEvioException
- if object closedpublic long position() throws java.io.IOException, EvioException
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.java.io.IOException
- if error accessing fileEvioException
- if object closed@Deprecated public void position(long position) throws java.io.IOException, EvioException
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.
position
- the new position of the buffer.java.io.IOException
- if error accessing fileEvioException
- if object closedpublic void close() throws java.io.IOException
rewind()
and the two
position()
methods, allows applications to treat files
in a normal random access manner.java.io.IOException
- if error accessing filepublic IBlockHeader getCurrentBlockHeader()
EvioReaderTest
class.public EvioEvent gotoEventNumber(int evNumber) throws java.io.IOException, EvioException
getEvent(int)
.evNumber
- the event number in a 1..N counting sense, from the start of the file.java.io.IOException
- if failed file accessEvioException
- if object closedpublic EvioReader.WriteStatus toXMLFile(java.lang.String path) throws java.io.IOException, EvioException
path
- the path to the XML file.java.io.IOException
- if failed file accessEvioException
- if object closedpublic EvioReader.WriteStatus toXMLFile(java.lang.String path, boolean hex) throws java.io.IOException, EvioException
path
- the path to the XML file.hex
- if true, ints get displayed in hexadecimaljava.io.IOException
- if failed file accessEvioException
- if object closedpublic EvioReader.WriteStatus toXMLFile(java.lang.String path, IEvioProgressListener progressListener) throws java.io.IOException, EvioException
path
- the path to the XML file.progressListener
- and optional progress listener, can be null
.java.io.IOException
- if failed file accessEvioException
- if object closedIEvioProgressListener
public EvioReader.WriteStatus toXMLFile(java.lang.String path, IEvioProgressListener progressListener, boolean hex) throws java.io.IOException, EvioException
path
- the path to the XML file.progressListener
- and optional progress listener, can be null
.hex
- if true, ints get displayed in hexadecimaljava.io.IOException
- if failed file accessEvioException
- if object closedIEvioProgressListener
public int getEventCount() throws java.io.IOException, EvioException
java.io.IOException
- if failed file accessEvioException
- if read failure;
if object closedpublic int getBlockCount() throws EvioException
EvioException
- if object closed