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

static class

EventWriter.IOStatus This enum denotes the status of a read.

Constructor Summary

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

Method Summary

void	close() If writing to a file, flush events waiting to be written, close the underlying data output stream and with it the file.
int	getBlockNumber() Get the current block number.
java.nio.ByteBuffer	getBuffer() Get the buffer being written into.
int	getEventsWritten() Get the number of events written to a file/buffer.
static void	main(java.lang.String[] args) Main program for testing.
static void	mainOrig(java.lang.String[] args) Main program for testing.
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.
void	writeEvent(EvioBank bank) Write an event (bank) to the file in evio version 4 format in blocks.

Methods inherited from class java.lang.Object

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

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 - block size too small or 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 - block size too small or 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 - block size too small or 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 - block size too small or 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 - block size too small or 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 - block size too small or 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 - block size too small or 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 - block size too small, 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.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.

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.

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

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. This was initially supplied by user in constructor. This returns null if writing to a file.

Returns:

buffer being written into; null if writing to file.

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. (Although a particular event may not yet be flushed to the file/buffer).

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 nothing if events have already been written.

Parameters:

startingBlockNumber - the number with which to start block numbers.

close

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

If writing to a file, flush events waiting to be written, close the underlying data output stream and with it the file. If writing to a buffer, flush events waiting to be written. If writing to a buffer, setBuffer(java.nio.ByteBuffer) can be called after this method to reset and reopen this object.

Throws:

java.io.IOException - if error writing to file

EvioException - if writing to buffer and not enough space

writeEvent

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

Write an event (bank) to the file in evio version 4 format in 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. A dictionary passed to the constructor will be written as the very first event and does not need to be explicitly written using this method.

Parameters:

bank - the bank to write.

Throws:

java.io.IOException - error writing to file

EvioException - if bank arg is null or not enough room in buffer

mainOrig

public static void mainOrig(java.lang.String[] args)

Main program for testing.

Parameters:

args - ignored command line arguments.

main

public static void main(java.lang.String[] args)

Main program for testing.

Parameters:

args - ignored command line arguments.