org.jlab.coda.jevio

Class EventWriter

java.lang.Object

org.jlab.coda.jevio.EventWriter

public class EventWriter
extends java.lang.Object

An EventWriter object is used for writing events to a file or to a byte buffer. This class does NOT write versions 1-3 data, only version 4! This class is threadsafe.

Author:

heddle, timmer

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	EventWriter.IOStatus This enum denotes the status of a read.

Field Summary

Fields

Modifier and Type	Field and Description
java.lang.String	baseFileName Part of filename without run or split numbers.
int	runNumber Run number possibly used in naming split files.
int	specifierCount Number of C-style int format specifiers contained in baseFileName.

Constructor Summary

Constructors

Constructor and Description
EventWriter(java.nio.ByteBuffer buf) Create an EventWriter for writing events to a ByteBuffer.
EventWriter(java.nio.ByteBuffer buf, boolean append) Create an EventWriter for writing events to a ByteBuffer.
EventWriter(java.nio.ByteBuffer buf, int blockSizeMax, int blockCountMax, java.lang.String xmlDictionary, java.util.BitSet bitInfo) Create an EventWriter for writing events to a ByteBuffer.
EventWriter(java.nio.ByteBuffer buf, int blockSizeMax, int blockCountMax, java.lang.String xmlDictionary, java.util.BitSet bitInfo, boolean append) Create an EventWriter for writing events to a ByteBuffer.
EventWriter(java.nio.ByteBuffer buf, int blockSizeMax, int blockCountMax, java.lang.String xmlDictionary, java.util.BitSet bitInfo, int reserved1) Create an EventWriter for writing events to a ByteBuffer.
EventWriter(java.nio.ByteBuffer buf, int blockSizeMax, int blockCountMax, java.lang.String xmlDictionary, java.util.BitSet bitInfo, int reserved1, boolean append) Create an EventWriter for writing events to a ByteBuffer.
EventWriter(java.nio.ByteBuffer buf, java.lang.String xmlDictionary, boolean append) Create an EventWriter for writing events to a ByteBuffer.
EventWriter(java.io.File file) Creates an EventWriter for writing to a file in native byte order.
EventWriter(java.io.File file, boolean append) Creates an EventWriter for writing to a file in native byte order.
EventWriter(java.io.File file, int blockSizeMax, int blockCountMax, java.nio.ByteOrder byteOrder, java.lang.String xmlDictionary, java.util.BitSet bitInfo) Create an EventWriter for writing events to a file.
EventWriter(java.io.File file, int blockSizeMax, int blockCountMax, java.nio.ByteOrder byteOrder, java.lang.String xmlDictionary, java.util.BitSet bitInfo, boolean overWriteOK) Create an EventWriter for writing events to a file.
EventWriter(java.io.File file, int blockSizeMax, int blockCountMax, java.nio.ByteOrder byteOrder, java.lang.String xmlDictionary, java.util.BitSet bitInfo, boolean overWriteOK, boolean append) Create an EventWriter for writing events to a file.
EventWriter(java.io.File file, java.lang.String dictionary, boolean append) Creates an EventWriter for writing to a file in native byte order.
EventWriter(java.lang.String filename) Creates an EventWriter for writing to a file in native byte order.
EventWriter(java.lang.String filename, boolean append) Creates an EventWriter for writing to a file in native byte order.
EventWriter(java.lang.String filename, boolean append, java.nio.ByteOrder byteOrder) Creates an EventWriter for writing to a file in the specified byte order.
EventWriter(java.lang.String baseName, java.lang.String directory, java.lang.String runType, int runNumber, long split, java.nio.ByteOrder byteOrder, java.lang.String xmlDictionary) Create an EventWriter for writing events to a file.
EventWriter(java.lang.String baseName, java.lang.String directory, java.lang.String runType, int runNumber, long split, java.nio.ByteOrder byteOrder, java.lang.String xmlDictionary, boolean overWriteOK) Create an EventWriter for writing events to a file.
EventWriter(java.lang.String baseName, java.lang.String directory, java.lang.String runType, int runNumber, long split, int blockSizeMax, int blockCountMax, int bufferSize, java.nio.ByteOrder byteOrder, java.lang.String xmlDictionary, java.util.BitSet bitInfo, boolean overWriteOK, boolean append) Create an EventWriter for writing events to a file.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() This method flushes any remaining data to file and disables this object.
void	flushToFile() Flush everything in buffer to file.
int	getBlockNumber() Get the current block number.
java.nio.ByteBuffer	getBuffer() Get the buffer being written into.
java.lang.String	getCurrentFilename() Get the name of the current file being written to.
int	getEventsWritten() Get the number of events written to a file/buffer.
int	getSplitCount() Get the current split count which is the number of files created by this object.
boolean	isClosed() Has close() been called (without reopening by calling setBuffer(java.nio.ByteBuffer)) ?
void	setBuffer(java.nio.ByteBuffer buf) Set the buffer being written into (initially set in constructor).
void	setStartingBlockNumber(int startingBlockNumber) Set the number with which to start block numbers.
boolean	toFile() Is this object writing to file?
void	writeEvent(java.nio.ByteBuffer eventBuffer) Write an event (bank) to the buffer in evio version 4 format.
void	writeEvent(EvioBank bank) Write an event (bank) to a buffer containing evio version 4 format blocks.

Methods inherited from class java.lang.Object

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

Field Detail

baseFileName

public java.lang.String baseFileName

Part of filename without run or split numbers.

specifierCount

public int specifierCount

Number of C-style int format specifiers contained in baseFileName.

runNumber

public int runNumber

Run number possibly used in naming split files.

Constructor Detail

EventWriter

public EventWriter(java.io.File file)
            throws EvioException

Creates an EventWriter for writing to a file in native byte order. If the file already exists, its contents will be overwritten. If it doesn't exist, it will be created.

Parameters:

file - the file object to write to.

Throws:

EvioException - file cannot be created

EventWriter

public EventWriter(java.io.File file,
           boolean append)
            throws EvioException

Creates an EventWriter for writing to a file in native byte order. If the file already exists, its contents will be overwritten unless it is being appended to. If it doesn't exist, it will be created.

Parameters:

file - the file object to write to.

append - if true and the file already exists, all events to be written will be appended to the end of the file.

Throws:

EvioException - file cannot be created

EventWriter

public EventWriter(java.io.File file,
           java.lang.String dictionary,
           boolean append)
            throws EvioException

Creates an EventWriter for writing to a file in native byte order. If the file already exists, its contents will be overwritten unless it is being appended to. If it doesn't exist, it will be created.

Parameters:

file - the file object to write to.

dictionary - dictionary in xml format or null if none.

append - if true and the file already exists, all events to be written will be appended to the end of the file.

Throws:

EvioException - file cannot be created

EventWriter

public EventWriter(java.lang.String filename)
            throws EvioException

Creates an EventWriter for writing to a file in native byte order. If the file already exists, its contents will be overwritten. If it doesn't exist, it will be created.

Parameters:

filename - name of the file to write to.

Throws:

EvioException - file cannot be created

EventWriter

public EventWriter(java.lang.String filename,
           boolean append)
            throws EvioException

Creates an EventWriter for writing to a file in native byte order. If the file already exists, its contents will be overwritten unless it is being appended to. If it doesn't exist, it will be created.

Parameters:

filename - name of the file to write to.

append - if true and the file already exists, all events to be written will be appended to the end of the file.

Throws:

EvioException - file cannot be created

EventWriter

public EventWriter(java.lang.String filename,
           boolean append,
           java.nio.ByteOrder byteOrder)
            throws EvioException

Creates an EventWriter for writing to a file in the specified byte order. If the file already exists, its contents will be overwritten unless it is being appended to. If it doesn't exist, it will be created.

Parameters:

filename - name of the file to write to.

append - if true and the file already exists, all events to be written will be appended to the end of the file.

byteOrder - the byte order in which to write the file.

Throws:

EvioException - file cannot be created

EventWriter

public EventWriter(java.io.File file,
           int blockSizeMax,
           int blockCountMax,
           java.nio.ByteOrder byteOrder,
           java.lang.String xmlDictionary,
           java.util.BitSet bitInfo)
            throws EvioException

Create an EventWriter for writing events to a file. If the file already exists, its contents will be overwritten. If it doesn't exist, it will be created.

Parameters:

file - the file object to write to.

blockSizeMax - the max blocksize to use which must be >= MIN_BLOCK_SIZE and <= MAX_BLOCK_SIZE ints. The size of the block will not be larger than this size unless a single event itself is larger.

blockCountMax - the max number of events in a single block which must be >= MIN_BLOCK_COUNT and <= MAX_BLOCK_COUNT.

byteOrder - the byte order in which to write the file.

xmlDictionary - dictionary in xml format or null if none.

bitInfo - set of bits to include in first block header.

Throws:

EvioException - if blockSizeMax or blockCountMax exceed limits; file cannot be created

EventWriter

public EventWriter(java.io.File file,
           int blockSizeMax,
           int blockCountMax,
           java.nio.ByteOrder byteOrder,
           java.lang.String xmlDictionary,
           java.util.BitSet bitInfo,
           boolean overWriteOK)
            throws EvioException

Create an EventWriter for writing events to a file. If the file already exists, its contents will be overwritten unless the "overWriteOK" argument is false in which case an exception will be thrown. If it doesn't exist, it will be created.

Parameters:

file - the file to write to.

blockSizeMax - the max blocksize to use which must be >= MIN_BLOCK_SIZE and <= MAX_BLOCK_SIZE ints. The size of the block will not be larger than this size unless a single event itself is larger.

blockCountMax - the max number of events in a single block which must be >= MIN_BLOCK_COUNT and <= MAX_BLOCK_COUNT.

byteOrder - the byte order in which to write the file.

xmlDictionary - dictionary in xml format or null if none.

bitInfo - set of bits to include in first block header.

overWriteOK - if false and the file already exists, an exception is thrown rather than overwriting it.

Throws:

EvioException - if blockSizeMax or blockCountMax exceed limits; file exists and cannot be deleted; file exists and user requested no deletion.

EventWriter

public EventWriter(java.io.File file,
           int blockSizeMax,
           int blockCountMax,
           java.nio.ByteOrder byteOrder,
           java.lang.String xmlDictionary,
           java.util.BitSet bitInfo,
           boolean overWriteOK,
           boolean append)
            throws EvioException

Create an EventWriter for writing events to a file. If the file already exists, its contents will be overwritten unless the "overWriteOK" argument is false in which case an exception will be thrown. Unless ..., the option to append these events to an existing file is true, in which case everything is fine. If the file doesn't exist, it will be created. Byte order defaults to big endian if arg is null.

Parameters:

file - the file to write to.

blockSizeMax - the max blocksize to use which must be >= MIN_BLOCK_SIZE and <= MAX_BLOCK_SIZE ints. The size of the block will not be larger than this size unless a single event itself is larger.

blockCountMax - the max number of events in a single block which must be >= MIN_BLOCK_COUNT and <= MAX_BLOCK_COUNT.

byteOrder - the byte order in which to write the file. This is ignored if appending to existing file.

xmlDictionary - dictionary in xml format or null if none.

bitInfo - set of bits to include in first block header.

overWriteOK - if false and the file already exists, an exception is thrown rather than overwriting it.

append - if true and the file already exists, all events to be written will be appended to the end of the file.

Throws:

EvioException - if blockSizeMax or blockCountMax exceed limits; if defined dictionary while appending; if file arg is null; if file could not be opened or positioned; if file exists but user requested no over-writing or appending.

EventWriter

public EventWriter(java.lang.String baseName,
           java.lang.String directory,
           java.lang.String runType,
           int runNumber,
           long split,
           java.nio.ByteOrder byteOrder,
           java.lang.String xmlDictionary)
            throws EvioException

Create an EventWriter for writing events to a file. This constructor is useful when splitting and automatically naming the split files. If any of the generated files already exist, it will NOT be overwritten. Byte order defaults to big endian.

Parameters:

baseName - base file name used to generate complete file name (may not be null)

directory - directory in which file is to be placed

runType - name of run type configuration to be used in naming files

runNumber - number of the CODA run, used in naming files

split - if < 1, do not split file, write to only one file of unlimited size. Else this is max size in bytes to make a file before closing it and starting writing another.

byteOrder - the byte order in which to write the file. Defaults to big endian if null.

xmlDictionary - dictionary in xml format or null if none.

Throws:

EvioException - if baseName arg is null; if file could not be opened, positioned, or written to; if file exists.

EventWriter

public EventWriter(java.lang.String baseName,
           java.lang.String directory,
           java.lang.String runType,
           int runNumber,
           long split,
           java.nio.ByteOrder byteOrder,
           java.lang.String xmlDictionary,
           boolean overWriteOK)
            throws EvioException

Create an EventWriter for writing events to a file. This constructor is useful when splitting and automatically naming the split files. Byte order defaults to big endian.

Parameters:

baseName - base file name used to generate complete file name (may not be null)

directory - directory in which file is to be placed

runType - name of run type configuration to be used in naming files

runNumber - number of the CODA run, used in naming files

split - if < 1, do not split file, write to only one file of unlimited size. Else this is max size in bytes to make a file before closing it and starting writing another.

byteOrder - the byte order in which to write the file. Defaults to big endian if null.

xmlDictionary - dictionary in xml format or null if none.

overWriteOK - if false and the file already exists, an exception is thrown rather than overwriting it.

Throws:

EvioException - if baseName arg is null; if file could not be opened, positioned, or written to; if file exists.

EventWriter

public EventWriter(java.lang.String baseName,
           java.lang.String directory,
           java.lang.String runType,
           int runNumber,
           long split,
           int blockSizeMax,
           int blockCountMax,
           int bufferSize,
           java.nio.ByteOrder byteOrder,
           java.lang.String xmlDictionary,
           java.util.BitSet bitInfo,
           boolean overWriteOK,
           boolean append)
            throws EvioException

Create an EventWriter for writing events to a file. If the file already exists, its contents will be overwritten unless the "overWriteOK" argument is false in which case an exception will be thrown. Unless ..., the option to append these events to an existing file is true, in which case everything is fine. If the file doesn't exist, it will be created. Byte order defaults to big endian if arg is null. File can be split while writing.

Parameters:

baseName - base file name used to generate complete file name (may not be null)

directory - directory in which file is to be placed

runType - name of run type configuration to be used in naming files

runNumber - number of the CODA run, used in naming files

split - if < 1, do not split file, write to only one file of unlimited size. Else this is max size in bytes to make a file before closing it and starting writing another.

blockSizeMax - the max blocksize to use which must be >= MIN_BLOCK_SIZE and <= MAX_BLOCK_SIZE ints. The size of the block will not be larger than this size unless a single event itself is larger.

blockCountMax - the max number of events in a single block which must be >= MIN_BLOCK_COUNT and <= MAX_BLOCK_COUNT.

bufferSize - number of bytes to make the internal buffer which will be storing events before writing them to a file. Must be at least 4*blockSizeMax + 32. If not, it is set to that.

byteOrder - the byte order in which to write the file. This is ignored if appending to existing file.

xmlDictionary - dictionary in xml format or null if none.

bitInfo - set of bits to include in first block header.

overWriteOK - if false and the file already exists, an exception is thrown rather than overwriting it.

append - if true and the file already exists, all events to be written will be appended to the end of the file.

Throws:

EvioException - if blockSizeMax or blockCountMax exceed limits; if defined dictionary while appending; if splitting file while appending; if file name arg is null; if file could not be opened, positioned, or written to; if file exists but user requested no over-writing or appending.

EventWriter

public EventWriter(java.nio.ByteBuffer buf)
            throws EvioException

Create an EventWriter for writing events to a ByteBuffer. Uses the default number and size of blocks in buffer. Will overwrite any existing data in buffer!

Parameters:

buf - the buffer to write to.

Throws:

EvioException - if buf arg is null

EventWriter

public EventWriter(java.nio.ByteBuffer buf,
           boolean append)
            throws EvioException

Create an EventWriter for writing events to a ByteBuffer. Uses the default number and size of blocks in buffer.

Parameters:

buf - the buffer to write to.

append - if true, all events to be written will be appended to the end of the buffer.

Throws:

EvioException - if buf arg is null

EventWriter

public EventWriter(java.nio.ByteBuffer buf,
           java.lang.String xmlDictionary,
           boolean append)
            throws EvioException

Create an EventWriter for writing events to a ByteBuffer. Uses the default number and size of blocks in buffer.

Parameters:

buf - the buffer to write to.

xmlDictionary - dictionary in xml format or null if none.

append - if true, all events to be written will be appended to the end of the buffer.

Throws:

EvioException - if buf arg is null

EventWriter

public EventWriter(java.nio.ByteBuffer buf,
           int blockSizeMax,
           int blockCountMax,
           java.lang.String xmlDictionary,
           java.util.BitSet bitInfo)
            throws EvioException

Create an EventWriter for writing events to a ByteBuffer. Will overwrite any existing data in buffer!

Parameters:

buf - the buffer to write to.

blockSizeMax - the max blocksize to use which must be >= MIN_BLOCK_SIZE and <= MAX_BLOCK_SIZE ints. The size of the block will not be larger than this size unless a single event itself is larger.

blockCountMax - the max number of events in a single block which must be >= MIN_BLOCK_COUNT and <= MAX_BLOCK_COUNT.

xmlDictionary - dictionary in xml format or null if none.

bitInfo - set of bits to include in first block header.

Throws:

EvioException - if blockSizeMax or blockCountMax exceed limits; if buf arg is null

EventWriter

public EventWriter(java.nio.ByteBuffer buf,
           int blockSizeMax,
           int blockCountMax,
           java.lang.String xmlDictionary,
           java.util.BitSet bitInfo,
           boolean append)
            throws EvioException

Create an EventWriter for writing events to a ByteBuffer.

Parameters:

buf - the buffer to write to.

blockSizeMax - the max blocksize to use which must be >= MIN_BLOCK_SIZE and <= MAX_BLOCK_SIZE ints. The size of the block will not be larger than this size unless a single event itself is larger.

blockCountMax - the max number of events in a single block which must be >= MIN_BLOCK_COUNT and <= MAX_BLOCK_COUNT.

xmlDictionary - dictionary in xml format or null if none.

bitInfo - set of bits to include in first block header.

append - if true, all events to be written will be appended to the end of the buffer.

Throws:

EvioException - if blockSizeMax or blockCountMax exceed limits; if buf arg is null; if defined dictionary while appending;

EventWriter

public EventWriter(java.nio.ByteBuffer buf,
           int blockSizeMax,
           int blockCountMax,
           java.lang.String xmlDictionary,
           java.util.BitSet bitInfo,
           int reserved1)
            throws EvioException

Create an EventWriter for writing events to a ByteBuffer. Will overwrite any existing data in buffer!

Parameters:

buf - the buffer to write to.

blockSizeMax - the max blocksize to use which must be >= MIN_BLOCK_SIZE and <= MAX_BLOCK_SIZE ints. The size of the block will not be larger than this size unless a single event itself is larger.

blockCountMax - the max number of events in a single block which must be >= MIN_BLOCK_COUNT and <= MAX_BLOCK_COUNT.

xmlDictionary - dictionary in xml format or null if none.

bitInfo - set of bits to include in first block header.

reserved1 - set the value of the first "reserved" int in first block header. NOTE: only CODA (i.e. EMU) software should use this.

Throws:

EvioException - if blockSizeMax or blockCountMax exceed limits; if buf arg is null

EventWriter

public EventWriter(java.nio.ByteBuffer buf,
           int blockSizeMax,
           int blockCountMax,
           java.lang.String xmlDictionary,
           java.util.BitSet bitInfo,
           int reserved1,
           boolean append)
            throws EvioException

Create an EventWriter for writing events to a ByteBuffer.

Parameters:

buf - the buffer to write to.

blockSizeMax - the max blocksize to use which must be >= MIN_BLOCK_SIZE and <= MAX_BLOCK_SIZE ints. The size of the block will not be larger than this size unless a single event itself is larger.

blockCountMax - the max number of events in a single block which must be >= MIN_BLOCK_COUNT and <= MAX_BLOCK_COUNT.

xmlDictionary - dictionary in xml format or null if none.

bitInfo - set of bits to include in first block header.

reserved1 - set the value of the first "reserved" int in first block header. NOTE: only CODA (i.e. EMU) software should use this.

append - if true, all events to be written will be appended to the end of the buffer.

Throws:

EvioException - if blockSizeMax or blockCountMax exceed limits; if buf arg is null; if defined dictionary while appending;

Method Detail

setBuffer

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

Set the buffer being written into (initially set in constructor). This method allows the user to avoid having to create a new EventWriter each time a bank needs to be written to a different buffer. This does nothing if writing to a file.

Do not use this method unless you know what you are doing.

Parameters:

buf - the buffer to write to.

Throws:

EvioException - if this object was not closed prior to resetting the buffer, or buffer arg is null.

getBuffer

public java.nio.ByteBuffer getBuffer()

Get the buffer being written into. If writing to a buffer, this was initially supplied by user in constructor. If writing to a file, this is the internal buffer.

Returns:

buffer being written into.

toFile

public boolean toFile()

Is this object writing to file?

Returns:

true if writing to file, else false.

isClosed

public boolean isClosed()

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

Returns:

true if this object closed, else false.

getCurrentFilename

public java.lang.String getCurrentFilename()

Get the name of the current file being written to. Returns null if no file.

Returns:

the name of the current file being written to.

getSplitCount

public int getSplitCount()

Get the current split count which is the number of files created by this object. Warning, this value may be changing.

Returns:

the current split count which is the number of files created by this object.

getBlockNumber

public int getBlockNumber()

Get the current block number. Warning, this value may be changing.

Returns:

the current block number.

getEventsWritten

public int getEventsWritten()

Get the number of events written to a file/buffer. Remember that a particular event may not yet be flushed to the file/buffer. If the file being written to is split, the returned value refers to all split files taken together.

Returns:

number of events written to a file/buffer.

setStartingBlockNumber

public void setStartingBlockNumber(int startingBlockNumber)

Set the number with which to start block numbers. This method does nothing if events have already been written.

Parameters:

startingBlockNumber - the number with which to start block numbers.

close

public void close()

This method flushes any remaining data to file and disables this object.

writeEvent

public void writeEvent(java.nio.ByteBuffer eventBuffer)
                throws EvioException,
                       java.io.IOException

Write an event (bank) to the buffer in evio version 4 format. The given event buffer must contain only the event's data (event header and event data) and must not be in complete evio format. If the internal buffer is full, it will be flushed to the file if writing to a file. Otherwise an exception will be thrown.

Parameters:

eventBuffer - the event (bank) to write in buffer form

Throws:

java.io.IOException - if error writing file

EvioException - if event is opposite byte order of internal buffer; if close() already called; if bad eventBuffer format; if file could not be opened for writing; if file exists but user requested no over-writing; if no room when writing to user-given buffer;

writeEvent

public void writeEvent(EvioBank bank)
                throws EvioException,
                       java.io.IOException

Write an event (bank) to a buffer containing evio version 4 format blocks. Each block has an integral number of events. There are limits to the number of events in each block and the total size of each block. If writing to a file, each full buffer is written - one at a time - and may contain multiple blocks. Dictionary is never written with this method.

Parameters:

bank - the bank to write.

Throws:

java.io.IOException - if error writing file

EvioException - if close() already called; if file could not be opened for writing; if file exists but user requested no over-writing; if no room when writing to user-given buffer;

flushToFile

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

Flush everything in buffer to file. Does nothing if object already closed.

Generally speaking, this method should NOT be used except internally in this package.

Throws:

EvioException - if this object already closed; if file could not be opened for writing; if file exists but user requested no over-writing;

java.io.IOException - if error writing file