org.jlab.coda.jevio

Class CompactEventBuilder

java.lang.Object

org.jlab.coda.jevio.CompactEventBuilder

public final class CompactEventBuilder
extends java.lang.Object

This class is used for creating events and their substructures while minimizing use of Java objects. Evio format data of a single event is written directly, and sequentially, into a buffer. The buffer contains only the single event, not the full, evio file format.

The methods of this class are not synchronized so it is NOT threadsafe. This is done for speed. The buffer retrieved by getBuffer() is ready to read.

Author:

timmer (Feb 6 2014)

Constructor Summary

Constructors

Constructor and Description
CompactEventBuilder(java.nio.ByteBuffer buffer) This is the constructor to use for building a new event (just the event in a buffer, not the full evio file format) with a user-given buffer.
CompactEventBuilder(java.nio.ByteBuffer buffer, boolean generateNodes) This is the constructor to use for building a new event (just the event in a buffer, not the full evio file format) with a user-given buffer.
CompactEventBuilder(int bufferSize, java.nio.ByteOrder order) This is the constructor to use for building a new event (just the event in a buffer, not the full evio file format).
CompactEventBuilder(int bufferSize, java.nio.ByteOrder order, boolean generateNodes) This is the constructor to use for building a new event (just the event in a buffer, not the full evio file format).

Method Summary

Modifier and Type	Method and Description
void	addByteData(byte[] data) Appends byte data to the structure.
void	addCompositeData(CompositeData[] data) Appends CompositeData objects to the structure.
void	addDoubleData(double[] data) Appends double data to the structure.
void	addEvioNode(EvioNode node) Adds the evio structure represented by the EvioNode object into the buffer.
void	addFloatData(float[] data) Appends float data to the structure.
void	addIntData(int[] data) Appends int data to the structure.
void	addIntData(int[] data, int offset) Appends int data to the structure.
void	addIntData(int[] data, int offset, int len) Appends int data to the structure.
void	addLongData(long[] data) Appends long data to the structure.
void	addLongData(long[] data, int offset, int len) Appends long data to the structure.
void	addShortData(short data) Appends a short integer to the structure.
void	addShortData(short[] data) Appends short data to the structure.
void	addShortData(short[] data, int offset, int len) Appends short data to the structure.
void	addStringData(java.lang.String[] strings) Appends string array to the structure.
void	closeAll() This method finishes the event writing by setting all the proper lengths & padding and ends up at the event or top level.
boolean	closeStructure() This method ends the writing of the current evio structure and makes sure the length and padding fields are properly set.
java.nio.ByteBuffer	getBuffer() Get the buffer being written into.
int	getTotalBytes() Get the total number of bytes written into the buffer.
EvioNode	openBank(int tag, int num, DataType dataType) This method adds an evio bank to the buffer.
EvioNode	openSegment(int tag, DataType dataType) This method adds an evio segment structure to the buffer.
EvioNode	openTagSegment(int tag, DataType dataType) This method adds an evio tagsegment structure to the buffer.
void	setBuffer(java.nio.ByteBuffer buffer) Set the buffer to be written into.
void	setBuffer(java.nio.ByteBuffer buffer, boolean generateNodes) Set the buffer to be written into.
void	setTopLevelTag(short tag) In the emu software package, it's necessary to change the top level tag after the top level bank has already been created.
void	toFile(java.lang.String filename) This method writes a file in proper evio format with block header containing the single event constructed by this object.

Methods inherited from class java.lang.Object

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

Constructor Detail

CompactEventBuilder

public CompactEventBuilder(int bufferSize,
                           java.nio.ByteOrder order)
                    throws EvioException

This is the constructor to use for building a new event (just the event in a buffer, not the full evio file format). A buffer is created in this constructor.

Parameters:

bufferSize - size of byte buffer (in bytes) to create.

order - byte order of created buffer.

Throws:

EvioException - if arg is null; if bufferSize arg too small

CompactEventBuilder

public CompactEventBuilder(int bufferSize,
                           java.nio.ByteOrder order,
                           boolean generateNodes)
                    throws EvioException

This is the constructor to use for building a new event (just the event in a buffer, not the full evio file format). A buffer is created in this constructor.

Parameters:

bufferSize - size of byte buffer (in bytes) to create.

order - byte order of created buffer.

generateNodes - generate and store an EvioNode object for each evio structure created.

Throws:

EvioException - if arg is null; if bufferSize arg too small

CompactEventBuilder

public CompactEventBuilder(java.nio.ByteBuffer buffer)
                    throws EvioException

This is the constructor to use for building a new event (just the event in a buffer, not the full evio file format) with a user-given buffer.

Parameters:

buffer - the byte buffer to write into.

Throws:

EvioException - if arg is null; if buffer is too small

CompactEventBuilder

public CompactEventBuilder(java.nio.ByteBuffer buffer,
                           boolean generateNodes)
                    throws EvioException

This is the constructor to use for building a new event (just the event in a buffer, not the full evio file format) with a user-given buffer.

Parameters:

buffer - the byte buffer to write into.

generateNodes - generate and store an EvioNode object for each evio structure created.

Throws:

EvioException - if arg is null; if buffer is too small

Method Detail

setBuffer

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

Set the buffer to be written into.

Parameters:

buffer - buffer to be written into.

Throws:

EvioException - if arg is null; if buffer is too small

setBuffer

public void setBuffer(java.nio.ByteBuffer buffer,
                      boolean generateNodes)
               throws EvioException

Set the buffer to be written into.

Parameters:

buffer - buffer to be written into.

generateNodes - generate and store an EvioNode object for each evio structure created.

Throws:

EvioException - if arg is null; if buffer is too small

getBuffer

public java.nio.ByteBuffer getBuffer()

Get the buffer being written into. The buffer is ready to read.

Returns:

buffer being written into.

getTotalBytes

public int getTotalBytes()

Get the total number of bytes written into the buffer.

Returns:

total number of bytes written into the buffer.

openSegment

public EvioNode openSegment(int tag,
                            DataType dataType)
                     throws EvioException

This method adds an evio segment structure to the buffer.

Parameters:

tag - tag of segment header

dataType - type of data to be contained by this segment

Returns:

if told to generate nodes in constructor, then return the node created here; else return null

Throws:

EvioException - if containing structure does not hold segments; if no room in buffer for segment header; if too many nested evio structures; if top-level bank has not been added first.

openTagSegment

public EvioNode openTagSegment(int tag,
                               DataType dataType)
                        throws EvioException

This method adds an evio tagsegment structure to the buffer.

Parameters:

tag - tag of tagsegment header

dataType - type of data to be contained by this tagsegment

Returns:

if told to generate nodes in constructor, then return the node created here; else return null

Throws:

EvioException - if containing structure does not hold tagsegments; if no room in buffer for tagsegment header; if too many nested evio structures; if top-level bank has not been added first.

openBank

public EvioNode openBank(int tag,
                         int num,
                         DataType dataType)
                  throws EvioException

This method adds an evio bank to the buffer.

Parameters:

tag - tag of bank header

num - num of bank header

dataType - data type to be contained in this bank

Returns:

if told to generate nodes in constructor, then return the node created here; else return null

Throws:

EvioException - if containing structure does not hold banks; if no room in buffer for bank header; if too many nested evio structures;

closeStructure

public boolean closeStructure()

This method ends the writing of the current evio structure and makes sure the length and padding fields are properly set. Its parent, if any, then becomes the current structure.

Returns:

true if top structure was reached (is current), else false.

closeAll

public void closeAll()

This method finishes the event writing by setting all the proper lengths & padding and ends up at the event or top level.

setTopLevelTag

public void setTopLevelTag(short tag)

In the emu software package, it's necessary to change the top level tag after the top level bank has already been created. This method allows changing it after initially written.

Parameters:

tag - new tag value of top-level, event bank.

addEvioNode

public void addEvioNode(EvioNode node)
                 throws EvioException

Adds the evio structure represented by the EvioNode object into the buffer.

Parameters:

node - the EvioNode object representing the evio structure to data.

Throws:

EvioException - if data is null or empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

addByteData

public void addByteData(byte[] data)
                 throws EvioException

Appends byte data to the structure.

Parameters:

data - the byte data to append.

Throws:

EvioException - if data is null or empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

addIntData

public void addIntData(int[] data)
                throws EvioException

Appends int data to the structure.

Parameters:

data - the int data to append.

Throws:

EvioException - if data is null or empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

addIntData

public void addIntData(int[] data,
                       int offset)
                throws EvioException

Appends int data to the structure.

Parameters:

data - the int data to append.

offset - offset into data array or number of integers at beginning of data to skip (not to add to event).

Throws:

EvioException - if data is null or empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

addIntData

public void addIntData(int[] data,
                       int offset,
                       int len)
                throws EvioException

Appends int data to the structure.

Parameters:

data - the int data to append.

offset - offset into data array.

len - the number of ints from data to append.

Throws:

EvioException - if data is null; if count/offset negative or too large; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

addShortData

public void addShortData(short[] data)
                  throws EvioException

Appends short data to the structure.

Parameters:

data - the short data to append.

Throws:

EvioException - if data is null or empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

addShortData

public void addShortData(short[] data,
                         int offset,
                         int len)
                  throws EvioException

Appends short data to the structure.

Parameters:

data - the short data to append.

offset - offset into data array.

len - the number of shorts from data to append.

Throws:

EvioException - if data is null; if count/offset negative or too large; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

addShortData

public void addShortData(short data)
                  throws EvioException

Appends a short integer to the structure.

Parameters:

data - the short data to append.

Throws:

EvioException - if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

addLongData

public void addLongData(long[] data)
                 throws EvioException

Appends long data to the structure.

Parameters:

data - the long data to append.

Throws:

EvioException - if data is null or empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

addLongData

public void addLongData(long[] data,
                        int offset,
                        int len)
                 throws EvioException

Appends long data to the structure.

Parameters:

data - the long data to append.

offset - offset into data array.

len - the number of longs from data to append.

Throws:

EvioException - if data is null; if count/offset negative or too large; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

addFloatData

public void addFloatData(float[] data)
                  throws EvioException

Appends float data to the structure.

Parameters:

data - the float data to append.

Throws:

EvioException - if data is null or empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

addDoubleData

public void addDoubleData(double[] data)
                   throws EvioException

Appends double data to the structure.

Parameters:

data - the double data to append.

Throws:

EvioException - if data is null or empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

addStringData

public void addStringData(java.lang.String[] strings)
                   throws EvioException

Appends string array to the structure.

Parameters:

strings - the strings to append.

Throws:

EvioException - if data is null or empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

addCompositeData

public void addCompositeData(CompositeData[] data)
                      throws EvioException

Appends CompositeData objects to the structure.

Parameters:

data - the CompositeData objects to append, or set if there is no existing data.

Throws:

EvioException - if data is null or empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

toFile

public void toFile(java.lang.String filename)

This method writes a file in proper evio format with block header containing the single event constructed by this object. This is useful as a test to see if event is being properly constructed. Use this in conjunction with the event viewer in order to check that format is correct. This only works with array backed buffers.

Parameters:

filename - name of file