org.jlab.coda.jevio

Class EvioNode

java.lang.Object

org.jlab.coda.jevio.EvioNode

All Implemented Interfaces:

java.lang.Cloneable

public class EvioNode
extends java.lang.Object
implements java.lang.Cloneable

This class is used to store relevant info about an evio container (bank, segment, or tag segment), without having to de-serialize it into many objects and arrays. It is not thread-safe and is designed for speed.

Author:

timmer Date: 11/13/12

Field Summary

Fields

Modifier and Type	Field and Description
BlockNode	blockNode Block containing this node.

Constructor Summary

Constructors

Constructor and Description
EvioNode() Constructor when fancy features not needed.
EvioNode(int pos, int place, java.nio.ByteBuffer buffer, BlockNode blockNode) Constructor which creates an EvioNode associated with an event (top level) evio container when parsing buffers for evio data.
EvioNode(int pos, int place, int recordPos, java.nio.ByteBuffer buffer) Constructor which creates an EvioNode associated with an event (top level) evio container when parsing buffers for evio data.

Method Summary

Modifier and Type	Method and Description
void	clear() Clear all data in this object.
void	clearAll() Clear everything in this object and set allNodes object to null.
void	clearIntArray() Only clear the data array.
void	clearLists() Clear childNodes.
void	clearObjects() Empty all lists and remove all other objects from this object.
java.lang.Object	clone()
static EvioNode	extractEventNode(java.nio.ByteBuffer buffer, EvioNodeSource pool, BlockNode blockNode, int position, int place) This method extracts an EvioNode object representing an evio event (top level evio bank) from a given buffer, a location in the buffer, and a few other things.
static EvioNode	extractEventNode(java.nio.ByteBuffer buffer, EvioNodeSource pool, int recPosition, int position, int place) This method extracts an EvioNode object representing an evio event (top level evio bank) from a given buffer, a location in the buffer, and a few other things.
static EvioNode	extractNode(EvioNode bankNode, int position) This method populates an EvioNode object that will represent an evio bank from that same node containing a reference to the backing buffer and given a position in that buffer.
void	getAllDescendants(java.util.List<EvioNode> descendants) Get the list of all descendant nodes that this node contains - not only the immediate children.
java.util.ArrayList<EvioNode>	getAllNodes() Get the list of all nodes that this node contains, always including itself.
java.nio.ByteBuffer	getBuffer() Get the object containing the buffer that this node is associated with.
java.nio.ByteBuffer	getByteData(boolean copy) Get the data associated with this node in ByteBuffer form.
EvioNode	getChildAt(int index) Get the child node at the given index (starts at 0).
int	getChildCount() Get the number all children that this node contains.
java.util.ArrayList<EvioNode>	getChildNodes() Get the list of all child nodes that this node contains.
int	getDataLength() Get the length of this evio structure's data only (no header words) in 32-bit words.
int	getDataPosition() Get the file/buffer byte position of this evio structure's data.
int	getDataType() Get the evio type of the data this evio structure contains.
DataType	getDataTypeObj() Get the evio type of the data this evio structure contains as an object.
int	getEventNumber() If this object represents an event (top-level, evio bank), then returns its number (place in file or buffer) starting with 1.
int[]	getIntData() Get the data associated with this node as an 32-bit integer array.
int[]	getIntData(int[] intData, int[] length) Get the data associated with this node as an 32-bit integer array.
int	getLength() Get the length of this evio structure (not including length word itself) in 32-bit words.
long[]	getLongData() Get the data associated with this node as an 64-bit integer array.
long[]	getLongData(long[] longData, int[] length) Get the data associated with this node as an 64-bit integer array.
int	getNum() Get the num of this evio structure.
int	getPad() Get the padding of this evio structure.
EvioNode	getParentNode() Get this node's parent node.
int	getPlace() Get the place of containing event in file/buffer.
int	getPosition() Get the file/buffer byte position of this evio structure.
int	getRecordPosition() Get the file/buffer byte position of the record containing this node.
short[]	getShortData() Get the data associated with this node as an 16-bit integer array.
short[]	getShortData(short[] shortData, int[] length) Get the data associated with this node as an 16-bit integer array.
java.nio.ByteBuffer	getStructureBuffer(boolean copy) Get this node's entire evio structure in ByteBuffer form.
int	getTag() Get the tag of this evio structure.
int	getTotalBytes() Get the length of this evio structure including entire header in bytes.
int	getType() Get the evio type of this evio structure, not what it contains.
DataType	getTypeObj() Get the evio type of this evio structure as an object.
boolean	isEvent() Does this object represent an event?
boolean	isObsolete() Has the data this node represents in the buffer been removed?
void	setBuffer(java.nio.ByteBuffer buf) Set the buffer.
void	setObsolete(boolean obsolete) Set whether this node and descendants are now obsolete because the data they represent in the buffer has been removed.
EvioNode	shift(int deltaPos) Shift the positions (pos, dataPos, and recordPos) of this node and its children by a fixed amount.
java.lang.String	toString() Return a String representation of this object.
void	updateLengths(int deltaLen) Update the length of this node in the buffer and all its parent nodes as well.
void	updateNum(int newNum) Update, in the buffer, the num of the bank header this object represents.
void	updateTag(int newTag) Update, in the buffer, the tag of the structure header this object represents.

Methods inherited from class java.lang.Object

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

Field Detail

blockNode

public BlockNode blockNode

Block containing this node.

Constructor Detail

EvioNode

public EvioNode()

Constructor when fancy features not needed.

EvioNode

public EvioNode(int pos,
                int place,
                java.nio.ByteBuffer buffer,
                BlockNode blockNode)

Constructor which creates an EvioNode associated with an event (top level) evio container when parsing buffers for evio data.

Parameters:

pos - position of event in buffer (number of bytes)

place - containing event's place in buffer (starting at 0)

buffer - buffer containing this event

blockNode - block containing this event

EvioNode

public EvioNode(int pos,
                int place,
                int recordPos,
                java.nio.ByteBuffer buffer)

Constructor which creates an EvioNode associated with an event (top level) evio container when parsing buffers for evio data.

Parameters:

pos - position of event in buffer (number of bytes).

place - containing event's place in buffer (starting at 0).

recordPos - position of record containing this node.

buffer - buffer containing this event.

Method Detail

shift

public final EvioNode shift(int deltaPos)

Shift the positions (pos, dataPos, and recordPos) of this node and its children by a fixed amount. Useful, for example, when the contents of one buffer is copied into another.

Parameters:

deltaPos - number of bytes to add to existing positions.

Returns:

this object.

clone

public final java.lang.Object clone()

Overrides:

clone in class java.lang.Object

toString

public final java.lang.String toString()

Return a String representation of this object.

Overrides:

toString in class java.lang.Object

Returns:

a String representation of this object.

clearLists

public final void clearLists()

Clear childNodes. Place only this or eventNode object into the allNodes list if it exists.

clear

public final void clear()

Clear all data in this object.

clearObjects

public final void clearObjects()

Empty all lists and remove all other objects from this object.

clearAll

public final void clearAll()

Clear everything in this object and set allNodes object to null.

clearIntArray

public final void clearIntArray()

Only clear the data array.

setBuffer

public void setBuffer(java.nio.ByteBuffer buf)

Set the buffer.

Parameters:

buf - buffer associated with this object.

extractEventNode

public static final EvioNode extractEventNode(java.nio.ByteBuffer buffer,
                                              EvioNodeSource pool,
                                              BlockNode blockNode,
                                              int position,
                                              int place)
                                       throws EvioException

This method extracts an EvioNode object representing an evio event (top level evio bank) from a given buffer, a location in the buffer, and a few other things. An EvioNode object represents an evio container - either a bank, segment, or tag segment.

Parameters:

buffer - buffer to examine

pool - pool of EvioNode objects

blockNode - object holding data about block header

position - position in buffer

place - place of event in buffer (starting at 0)

Returns:

EvioNode object containing evio event information

Throws:

EvioException - if file/buffer too small

extractEventNode

public static final EvioNode extractEventNode(java.nio.ByteBuffer buffer,
                                              EvioNodeSource pool,
                                              int recPosition,
                                              int position,
                                              int place)
                                       throws EvioException

This method extracts an EvioNode object representing an evio event (top level evio bank) from a given buffer, a location in the buffer, and a few other things. An EvioNode object represents an evio container - either a bank, segment, or tag segment.

Parameters:

buffer - buffer to examine

pool - pool of EvioNode objects

recPosition - position of containing record

position - position in buffer

place - place of event in buffer (starting at 0)

Returns:

EvioNode object containing evio event information

Throws:

EvioException - if file/buffer too small

extractNode

public static final EvioNode extractNode(EvioNode bankNode,
                                         int position)
                                  throws EvioException

This method populates an EvioNode object that will represent an evio bank from that same node containing a reference to the backing buffer and given a position in that buffer.

Parameters:

bankNode - EvioNode to represent a bank and containing, at least, a reference to backing buffer.

position - position in backing buffer

Returns:

EvioNode bankNode arg filled with appropriate data.

Throws:

EvioException - if file/buffer too small

isObsolete

public final boolean isObsolete()

Has the data this node represents in the buffer been removed?

Returns:

true if node no longer represents valid buffer data, else false.

setObsolete

public final void setObsolete(boolean obsolete)

Set whether this node and descendants are now obsolete because the data they represent in the buffer has been removed. Only for internal use.

Parameters:

obsolete - true if node and descendants no longer represent valid buffer data, else false.

getAllNodes

public final java.util.ArrayList<EvioNode> getAllNodes()

Get the list of all nodes that this node contains, always including itself. This is meaningful only if this node has been scanned, otherwise it contains only itself.

Returns:

list of all nodes that this node contains.

getChildNodes

public final java.util.ArrayList<EvioNode> getChildNodes()

Get the list of all child nodes that this node contains. This is meaningful only if this node has been scanned, otherwise it is null.

Returns:

list of all child nodes that this node contains; null if not scanned or no children

getAllDescendants

public final void getAllDescendants(java.util.List<EvioNode> descendants)

Get the list of all descendant nodes that this node contains - not only the immediate children. This is meaningful only if this node has been scanned, otherwise nothing is added to the given list.

Parameters:

descendants - list to be filled with EvioNodes of all descendants

getChildAt

public final EvioNode getChildAt(int index)

Get the child node at the given index (starts at 0). This is meaningful only if this node has been scanned, otherwise it is null.

Parameters:

index - index of child node

Returns:

child node at the given index; null if not scanned or no child at that index

getChildCount

public final int getChildCount()

Get the number all children that this node contains. This is meaningful only if this node has been scanned, otherwise it returns 0.

Returns:

number of children that this node contains; 0 if not scanned

getBuffer

public final java.nio.ByteBuffer getBuffer()

Get the object containing the buffer that this node is associated with.

Returns:

object containing the buffer that this node is associated with.

getLength

public final int getLength()

Get the length of this evio structure (not including length word itself) in 32-bit words.

Returns:

length of this evio structure (not including length word itself) in 32-bit words

getTotalBytes

public final int getTotalBytes()

Get the length of this evio structure including entire header in bytes.

Returns:

length of this evio structure including entire header in bytes.

getTag

public final int getTag()

Get the tag of this evio structure.

Returns:

tag of this evio structure

getNum

public final int getNum()

Get the num of this evio structure. Will be zero for tagsegments.

Returns:

num of this evio structure

getPad

public final int getPad()

Get the padding of this evio structure. Will be zero for segments and tagsegments.

Returns:

padding of this evio structure

getPosition

public final int getPosition()

Get the file/buffer byte position of this evio structure.

Returns:

file/buffer byte position of this evio structure

getType

public final int getType()

Get the evio type of this evio structure, not what it contains. Call DataType.getDataType(int) on the returned value to get the object representation.

Returns:

evio type of this evio structure, not what it contains

getTypeObj

public final DataType getTypeObj()

Get the evio type of this evio structure as an object.

Returns:

evio type of this evio structure as an object.

getDataLength

public final int getDataLength()

Get the length of this evio structure's data only (no header words) in 32-bit words.

Returns:

length of this evio structure's data only (no header words) in 32-bit words.

getDataPosition

public final int getDataPosition()

Get the file/buffer byte position of this evio structure's data.

Returns:

file/buffer byte position of this evio structure's data

getDataType

public final int getDataType()

Get the evio type of the data this evio structure contains. Call DataType.getDataType(int) on the returned value to get the object representation.

Returns:

evio type of the data this evio structure contains

getDataTypeObj

public final DataType getDataTypeObj()

Get the evio type of the data this evio structure contains as an object.

Returns:

evio type of the data this evio structure contains as an object.

getRecordPosition

public int getRecordPosition()

Get the file/buffer byte position of the record containing this node.

Returns:

file/buffer byte position of the record containing this node.

Since:

version 6.

getPlace

public final int getPlace()

Get the place of containing event in file/buffer. First event = 0, second = 1, etc. Only for internal use.

Returns:

place of containing event in file/buffer.

getParentNode

public final EvioNode getParentNode()

Get this node's parent node.

Returns:

this node's parent node or null if none.

getEventNumber

public final int getEventNumber()

If this object represents an event (top-level, evio bank), then returns its number (place in file or buffer) starting with 1. If not, return -1.

Returns:

event number if representing an event, else -1

isEvent

public final boolean isEvent()

Does this object represent an event?

Returns:

true if this object represents an event, else false

updateLengths

public final void updateLengths(int deltaLen)

Update the length of this node in the buffer and all its parent nodes as well. For internal use only.

Parameters:

deltaLen - change in length (words). Negative value reduces lengths.

updateTag

public final void updateTag(int newTag)

Update, in the buffer, the tag of the structure header this object represents. Sometimes it's necessary to go back and change the tag of an evio structure that's already been written. This will do that.

Parameters:

newTag - new tag value

updateNum

public final void updateNum(int newNum)

Update, in the buffer, the num of the bank header this object represents. Sometimes it's necessary to go back and change the num of an evio structure that's already been written. This will do that .

Parameters:

newNum - new num value

getByteData

public final java.nio.ByteBuffer getByteData(boolean copy)

Get the data associated with this node in ByteBuffer form. Depending on the copy argument, the returned buffer will either be a copy of or a view into this node's buffer. Position and limit are set for reading.

This method is not synchronized.

Parameters:

copy - if true, then return a copy as opposed to a view into this node's buffer.

Returns:

ByteBuffer containing data. Position and limit are set for reading.

getIntData

public final int[] getIntData()

Get the data associated with this node as an 32-bit integer array. Store it for future 2nd gets (like in event builder). If data is of a type less than 32 bits, the last int will be junk. Call this to avoid calling getByteData(boolean) and converting it to an int array which involves creating additional objects and calling additional methods. This method is not synchronized.

Returns:

integer array containing data.

getIntData

public final int[] getIntData(int[] intData,
                              int[] length)

Get the data associated with this node as an 32-bit integer array. Place data in the given array. Only allocate memory if array is too small. If data is of a type less than 32 bits, the last int will be junk. Call this to avoid calling getByteData(boolean) and converting it to an int array which involves creating additional objects and calling additional methods. This method is not synchronized. This method is only used in Evio.java in emu package.

Parameters:

intData - integer array in which to store data.

length - set first element to contain number of valid array elements of the returned array.

Returns:

integer array containing data, or null if length array arg is null or 0 length.

getLongData

public final long[] getLongData()

Get the data associated with this node as an 64-bit integer array. If data is of a type less than 64 bits, the last long will be junk. Make sure we don't try to read beyond the end. Call this to avoid calling getByteData(boolean) and converting it to a long array which involves creating additional objects and calling additional methods. This method is not synchronized.

Returns:

long array containing data.

getLongData

public final long[] getLongData(long[] longData,
                                int[] length)

Get the data associated with this node as an 64-bit integer array. Place data in the given array. Only allocate memory if array is too small. If data is of a type less than 64 bits, the last element may be junk. Call this to avoid calling getByteData(boolean) and converting it to an long array which involves creating additional objects and calling additional methods. This method is not synchronized.

Parameters:

longData - long array in which to store data.

length - set first element to contain number of valid array elements of the returned array.

Returns:

long array containing data, or null if length array arg is null or 0 length.

getShortData

public final short[] getShortData()

Get the data associated with this node as an 16-bit integer array. If data is of a type less than 16 bits, the last int will be junk. Call this to avoid calling getByteData(boolean) and converting it to a short array which involves creating additional objects and calling additional methods. This method is not synchronized.

Returns:

short array containing data.

getShortData

public final short[] getShortData(short[] shortData,
                                  int[] length)

Get the data associated with this node as an 16-bit integer array. Place data in the given array. Only allocate memory if array is too small. If data is of a type less than 16 bits, the last element may be junk. Call this to avoid calling getByteData(boolean) and converting it to an short array which involves creating additional objects and calling additional methods. This method is not synchronized.

Parameters:

shortData - short array in which to store data.

length - set first element to contain number of valid array elements of the returned array.

Returns:

short array containing data, or null if length array arg is null or 0 length.

getStructureBuffer

public final java.nio.ByteBuffer getStructureBuffer(boolean copy)

Get this node's entire evio structure in ByteBuffer form. Depending on the copy argument, the returned buffer will either be a copy of or a view into the data of this node's buffer. Position and limit are set for reading.

This method is not synchronized.

Parameters:

copy - if true, then return a copy as opposed to a view into this node's buffer.

Returns:

ByteBuffer object containing evio structure's bytes. Position and limit are set for reading.