public class EvioReader extends java.lang.Object implements IEvioReader
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.
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.nio.ByteBuffer byteBuffer,
boolean checkRecNumSeq,
boolean synced)
Constructor for reading a buffer with option of removing synchronization
for much greater speed.
|
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 checkRecNumSeq,
boolean sequential)
Constructor for reading an event file.
|
EvioReader(java.io.File file,
boolean checkRecNumSeq,
boolean sequential,
boolean synced)
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 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.
|
(package private) static EvioEvent |
getEvent(byte[] array,
int offset,
java.nio.ByteOrder order)
Transform an event in the form of a byte array into an EvioEvent object.
|
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)
Go to a specific event in the file.
|
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.
|
static EvioEvent |
parseEvent(byte[] array,
int offset,
java.nio.ByteOrder order)
Completely parse the given byte array into an EvioEvent.
|
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 |
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.
|
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).
|
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 checkRecNumSeq, boolean sequential) throws EvioException, java.io.IOException
file
- the file that contains events.checkRecNumSeq
- 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.io.File file, boolean checkRecNumSeq, boolean sequential, boolean synced) throws EvioException, java.io.IOException
file
- the file that contains events.checkRecNumSeq
- 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.synced
- if true, methods are synchronized for thread safety, else false.java.io.IOException
- if read failureEvioException
- if file arg is null; bad evio version #;
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
byteBuffer
- the buffer that contains events.EvioException
- if buffer arg is nullEventWriter
public EvioReader(java.nio.ByteBuffer byteBuffer, boolean checkBlkNumSeq) throws EvioException
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 1EvioException
- if buffer arg is null;
if first block number != 1 when checkBlkNumSeq arg is trueEventWriter
public EvioReader(java.nio.ByteBuffer byteBuffer, boolean checkRecNumSeq, boolean synced) throws EvioException
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 1synced
- if true, methods are synchronized for thread safety, else false.EvioException
- if buffer arg is null; bad version #;
failure to read first block headerEventWriter
public void setBuffer(java.nio.ByteBuffer buf) throws EvioException, java.io.IOException
IEvioReader.close()
is called before anything else.setBuffer
in interface IEvioReader
buf
- ByteBuffer to be readEvioException
- if buf is null;
if first block number != 1 when checkBlkNumSeq arg is truejava.io.IOException
- if read failurepublic boolean isClosed()
IEvioReader.close()
been called (without reopening by calling
IEvioReader.setBuffer(ByteBuffer)
)?isClosed
in interface IEvioReader
true
if this object closed, else false
.public boolean checkBlockNumberSequence()
checkBlockNumberSequence
in interface IEvioReader
true
if checking block number sequence, else false
public java.nio.ByteOrder getByteOrder()
getByteOrder
in interface IEvioReader
public int getEvioVersion()
getEvioVersion
in interface IEvioReader
public java.lang.String getPath()
getPath
in interface IEvioReader
public EventParser getParser()
getParser
in interface IEvioReader
public void setParser(EventParser parser)
setParser
in interface IEvioReader
parser
- file/buffer parser.public java.lang.String getDictionaryXML()
getDictionaryXML
in interface IEvioReader
public boolean hasDictionaryXML()
hasDictionaryXML
in interface IEvioReader
true
if this evio file has an associated XML dictionary,
else false
public EvioEvent getFirstEvent()
getFirstEvent
in interface IEvioReader
public boolean hasFirstEvent()
hasFirstEvent
in interface IEvioReader
true
if this evio file has an associated first event,
else false
public int getNumEventsRemaining() throws java.io.IOException, EvioException
getNumEventsRemaining
in interface IEvioReader
java.io.IOException
- if failed file accessEvioException
- if failed reading from coda v3 filepublic java.nio.ByteBuffer getByteBuffer()
getByteBuffer
in interface IEvioReader
public long fileSize()
fileSize
in interface IEvioReader
public IBlockHeader getFirstBlockHeader()
getFirstBlockHeader
in interface IEvioReader
public EvioEvent getEvent(int index) throws java.io.IOException, EvioException
IEvioReader.parseNextEvent()
or IEvioReader.parseEvent(int)
instead,
since it combines combines getting an event with parsing it.getEvent
in interface IEvioReader
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 out of bounds;
if object closedpublic EvioEvent parseEvent(int index) throws java.io.IOException, EvioException
parseEvent
in interface IEvioReader
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 out of bounds;
if object closedpublic EvioEvent nextEvent() throws java.io.IOException, EvioException
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.
nextEvent
in interface IEvioReader
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
parseNextEvent
in interface IEvioReader
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 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.
parseEvent
in interface IEvioReader
evioEvent
- the event to parse.EvioException
- if bad formatstatic EvioEvent getEvent(byte[] array, int offset, java.nio.ByteOrder order) throws EvioException
parseEvent(byte[], int, ByteOrder)
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.array
- array to parse into EvioEvent object.offset
- offset into array.order
- byte order to use.EvioException
- if null arg, too little data, length too large, or data not in evio format.public static EvioEvent parseEvent(byte[] array, int offset, java.nio.ByteOrder order) throws EvioException
array
- array to parse into EvioEvent object.offset
- offset into array.order
- byte order to use.EvioException
- if null arg, too little data, length too large, or data not in evio format.public byte[] getEventArray(int eventNumber) throws EvioException, java.io.IOException
getEventArray
in interface IEvioReader
eventNumber
- number of event of interest (starting at 1).EvioException
- if eventNumber out of bounds (starts at 1);
if the event number does not correspond to an existing event;
if object closedjava.io.IOException
- if failed file accesspublic java.nio.ByteBuffer getEventBuffer(int eventNumber) throws EvioException, java.io.IOException
getEventBuffer
in interface IEvioReader
eventNumber
- number of event of interestEvioException
- if eventNumber is out of bounds;
if the event number does not correspond to an existing event;
if object closedjava.io.IOException
- if failed file accesspublic void rewind() throws java.io.IOException, EvioException
position()
and the
close()
method, allows applications to treat files
in a normal random access manner.rewind
in interface IEvioReader
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.position
in interface IEvioReader
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.close
in interface IEvioReader
java.io.IOException
- if error accessing filepublic IBlockHeader getCurrentBlockHeader()
getCurrentBlockHeader
in interface IEvioReader
public EvioEvent gotoEventNumber(int evNumber) throws java.io.IOException, EvioException
IEvioReader.getEvent(int)
.gotoEventNumber
in interface IEvioReader
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 WriteStatus toXMLFile(java.lang.String path) throws java.io.IOException, EvioException
toXMLFile
in interface IEvioReader
path
- the path to the XML file.java.io.IOException
- if failed file accessEvioException
- if object closedpublic WriteStatus toXMLFile(java.lang.String path, boolean hex) throws java.io.IOException, EvioException
toXMLFile
in interface IEvioReader
path
- the path to the XML file.hex
- if true, ints get displayed in hexadecimaljava.io.IOException
- if failed file accessEvioException
- if object closedpublic WriteStatus toXMLFile(java.lang.String path, IEvioProgressListener progressListener) throws java.io.IOException, EvioException
toXMLFile
in interface IEvioReader
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 WriteStatus toXMLFile(java.lang.String path, IEvioProgressListener progressListener, boolean hex) throws java.io.IOException, EvioException
toXMLFile
in interface IEvioReader
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
getEventCount
in interface IEvioReader
java.io.IOException
- if failed file accessEvioException
- if read failure;
if object closedpublic int getBlockCount() throws EvioException
getBlockCount
in interface IEvioReader
EvioException
- if object closed.