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
(package private) java.util.ArrayList<EvioNode>	allNodes List of all nodes in the event including the top-level object ordered according to placement in buffer.
BlockNode	blockNode Block containing this node.
(package private) java.nio.ByteBuffer	buffer ByteBuffer that this node is associated with.
(package private) java.util.ArrayList<EvioNode>	childNodes List of child nodes ordered according to placement in buffer.
(package private) int[]	data Store data in int array form if calculated.
(package private) int	dataLen Length of node's data in 32-bit words.
(package private) int	dataPos Position of node's data in buffer in bytes.
(package private) int	dataType Type of data stored in node.
(package private) EvioNode	eventNode Node of event containing this node.
(package private) boolean	isEvent Does this node represent an event (top-level bank)?
(package private) int	len Header's length value (32-bit words).
(package private) int	num Header's num value.
(package private) boolean	obsolete If the data this node represents is removed from the buffer, then this object is obsolete.
(package private) int	pad Header's padding value.
(package private) EvioNode	parentNode Node containing this node.
(package private) int	place Place of containing event in file/buffer.
(package private) int	poolId If in pool, the pool's id.
(package private) int	pos Position of header in buffer in bytes.
(package private) int	recordPos Position of the record in buffer containing this node in bytes
(package private) boolean	scanned If top-level event node, was I scanned and all my banks already placed into a list?
(package private) int	tag Header's tag value.
(package private) int	type This node's (evio container's) type.

Constructor Summary

Constructors

Constructor and Description
EvioNode() Constructor when fancy features not needed.
EvioNode(EvioNode firstNode) Constructor used when swapping data.
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.
EvioNode(int tag, int num, int pos, int dataPos, DataType type, DataType dataType, java.nio.ByteBuffer buffer) Constructor which creates an EvioNode in the CompactEventBuilder.

Method Summary

Modifier and Type	Method and Description
(package private) void	addChild(EvioNode node) Add a child node to the end of the child list and to the list of all nodes contained in event.
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.
(package private) BlockNode	getBlockNode() Get the object representing the block header.
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?
(package private) void	removeChild(EvioNode node) Remove a node from this child list and, along with its descendants, from the list of all nodes contained in event.
(package private) static void	scanStructure(EvioNode node) This method recursively stores, in the given list, all the information about an evio structure's children found in the given ByteBuffer object.
(package private) static void	scanStructure(EvioNode node, EvioNodeSource nodeSource) This method recursively stores, in the given list, all the information about an evio structure's children found in the given ByteBuffer object.
void	setBuffer(java.nio.ByteBuffer buf) Set the buffer.
(package private) void	setData(int position, int place, java.nio.ByteBuffer buffer, BlockNode blockNode) Once this node is cleared, it may be reused and then re-initialized with this method.
(package private) void	setData(int position, int place, int recordPos, java.nio.ByteBuffer buffer) Once this node is cleared, it may be reused and then re-initialized with this method.
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, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

len

int len

Header's length value (32-bit words).

tag

int tag

Header's tag value.

num

int num

Header's num value.

pad

int pad

Header's padding value.

pos

int pos

Position of header in buffer in bytes.

type

int type

This node's (evio container's) type. Must be bank, segment, or tag segment.

dataLen

int dataLen

Length of node's data in 32-bit words.

dataPos

int dataPos

Position of node's data in buffer in bytes.

dataType

int dataType

Type of data stored in node.

recordPos

int recordPos

Position of the record in buffer containing this node in bytes

Since:

version 6.

data

int[] data

Store data in int array form if calculated.

isEvent

boolean isEvent

Does this node represent an event (top-level bank)?

obsolete

boolean obsolete

If the data this node represents is removed from the buffer, then this object is obsolete.

blockNode

public BlockNode blockNode

Block containing this node.

buffer

java.nio.ByteBuffer buffer

ByteBuffer that this node is associated with.

childNodes

java.util.ArrayList<EvioNode> childNodes

List of child nodes ordered according to placement in buffer.

place

int place

Place of containing event in file/buffer. First event = 0, second = 1, etc. Useful for converting node to EvioEvent object (de-serializing).

scanned

boolean scanned

If top-level event node, was I scanned and all my banks already placed into a list?

allNodes

java.util.ArrayList<EvioNode> allNodes

List of all nodes in the event including the top-level object ordered according to placement in buffer. Only created at the top-level (with constructor). All lower-level nodes are created with clone() so all nodes have a reference to the top-level allNodes object.

eventNode

EvioNode eventNode

Node of event containing this node. Is null if this is an event node.

parentNode

EvioNode parentNode

Node containing this node. Is null if this is an event node.

poolId

int poolId

If in pool, the pool's id.

Constructor Detail

EvioNode

public EvioNode()

Constructor when fancy features not needed.

EvioNode

EvioNode(EvioNode firstNode)

Constructor used when swapping data.

Parameters:

firstNode - node of event containing this node or null if this is an event node.

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.

EvioNode

EvioNode(int tag,
         int num,
         int pos,
         int dataPos,
         DataType type,
         DataType dataType,
         java.nio.ByteBuffer buffer)

Constructor which creates an EvioNode in the CompactEventBuilder.

Parameters:

tag - the tag for the event (or bank) header.

num - the num for the event (or bank) header.

pos - position of event in buffer (bytes).

dataPos - position of event's data in buffer (bytes.)

type - the type of this evio structure.

dataType - the data type contained in this evio event.

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.

setData

void setData(int position,
             int place,
             java.nio.ByteBuffer buffer,
             BlockNode blockNode)

Once this node is cleared, it may be reused and then re-initialized with this method.

Parameters:

position - position in buffer

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

buffer - buffer to examine

blockNode - object holding data about header of block containing event

setData

void setData(int position,
             int place,
             int recordPos,
             java.nio.ByteBuffer buffer)

Once this node is cleared, it may be reused and then re-initialized with this method.

Parameters:

position - position in buffer

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

recordPos - place of event in containing record (bytes)

buffer - buffer to examine

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

scanStructure

static final void scanStructure(EvioNode node)

This method recursively stores, in the given list, all the information about an evio structure's children found in the given ByteBuffer object. It uses absolute gets so buffer's position does not change.

Parameters:

node - node being scanned

scanStructure

static final void scanStructure(EvioNode node,
                                EvioNodeSource nodeSource)

This method recursively stores, in the given list, all the information about an evio structure's children found in the given ByteBuffer object. It uses absolute gets so buffer's position does not change.

Parameters:

node - node being scanned

nodeSource - source of EvioNode objects to use while parsing evio data.

addChild

final void addChild(EvioNode node)

Add a child node to the end of the child list and to the list of all nodes contained in event. This is called internally in sequence so every node ends up in the right place in allNodes. When the user adds a structure by calling EvioCompactReader.addStructure(int, ByteBuffer), the structure or node gets added at the very end - as the last child of the event.

Parameters:

node - child node to add to the end of the child list.

removeChild

final void removeChild(EvioNode node)

Remove a node from this child list and, along with its descendants, from the list of all nodes contained in event. If not a child, do nothing.

Parameters:

node - node to remove from child and allNodes lists.

getBlockNode

final BlockNode getBlockNode()

Get the object representing the block header.

Returns:

object representing the block header.

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.