org.jlab.coda.jevio
Class BaseStructure

java.lang.Object
  extended by org.jlab.coda.jevio.BaseStructure
All Implemented Interfaces:
javax.swing.tree.MutableTreeNode, javax.swing.tree.TreeNode, IEvioStructure, IEvioWriter
Direct Known Subclasses:
EvioBank, EvioSegment, EvioTagSegment

public abstract class BaseStructure
extends java.lang.Object
implements IEvioStructure, javax.swing.tree.MutableTreeNode, IEvioWriter

This is the base class for all evio structures: Banks, Segments, and TagSegments. It implements MutableTreeNode because a tree representation of events is created when a new event is parsed.

Author:
heddle, timmer - add byte order tracking

Constructor Summary
BaseStructure(BaseStructureHeader header)
          Constructor using a provided header
 
Method Summary
 void appendByteData(byte[] data)
          Appends byte data to the structure.
 void appendCharData(char[] data)
          Appends char data to the structure (as ascii).
 void appendDoubleData(double[] data)
          Appends double data to the structure.
 void appendFloatData(float[] data)
          Appends float data to the structure.
 void appendIntData(int[] data)
          Appends int data to the structure.
 void appendLongData(long[] data)
          Appends long data to the structure.
 void appendShortData(short[] data)
          Appends short data to the structure.
 java.util.Enumeration<?> children()
          Get an enumeration of all the children of this structure.
 boolean getAllowsChildren()
          Checks whether children are allowed.
 byte[] getByteData()
          This is a method from the IEvioStructure Interface.
 java.nio.ByteOrder getByteOrder()
          What is the byte order of this data?
 javax.swing.tree.TreeNode getChildAt(int index)
          Obtain the child at the given index.
 int getChildCount()
          Get the count of the number of children.
 java.util.Vector<BaseStructure> getChildren()
          Get the children of this structure.
 java.lang.String getDescription()
          Get the description from the name provider (dictionary), if there is one.
 double[] getDoubleData()
          This is a method from the IEvioStructure Interface.
 float[] getFloatData()
          This is a method from the IEvioStructure Interface.
 BaseStructureHeader getHeader()
          This is a method from the IEvioStructure Interface.
 int getIndex(javax.swing.tree.TreeNode node)
          Get the index of a node.
 int[] getIntData()
          This is a method from the IEvioStructure Interface.
 long[] getLongData()
          This is a method from the IEvioStructure Interface.
 BaseStructure getParent()
          Get the parent of this structure.
 byte[] getRawBytes()
          Get the raw data of the structure.
 short[] getShortData()
          This is a method from the IEvioStructure Interface.
 java.lang.String getStringData()
          This is a method from the IEvioStructure Interface.
abstract  StructureType getStructureType()
          A convenience method use instead of "instanceof" to see what type of structure we have.
 int getTotalBytes()
          Get the length of this structure in bytes, including the header.
abstract  java.lang.String getXMLElementName()
          Get the element name for the structure for writing to XML.
 void insert(javax.swing.tree.MutableTreeNode child)
          Convenience method to add a child at the end of the child list.
 void insert(javax.swing.tree.MutableTreeNode child, int index)
          Add a child at the given index.
 boolean isContainer()
          Checks whether this structure is a container, i.e.
 boolean isLeaf()
          Checks whether this is a leaf.
 boolean isSwap()
          Is a byte swap required? Since this is java, code is big endian.
 void remove(int index)
          Removes the child at index from the receiver.
 void remove(javax.swing.tree.MutableTreeNode child)
          Removes the child.
 void removeFromParent()
          Remove this node from its parent.
 int setAllHeaderLengths()
          Compute the and set length of all header fields for this structure and all its descendants.
 void setByteOrder(java.nio.ByteOrder byteOrder)
          Set the byte order of this data.
 void setParent(javax.swing.tree.MutableTreeNode parent)
          Set the parent for this node.
 void setRawBytes(byte[] rawBytes)
          Set the data for the structure.
 void setUserObject(java.lang.Object arg0)
          This method is not relevant for this implementation.
 java.lang.String toString()
          Obtain a string representation of the structure.
abstract  void toXML(javax.xml.stream.XMLStreamWriter xmlWriter)
          This is a method that must be filled in by subclasses.
 int write(java.nio.ByteBuffer byteBuffer)
          Write myself out a byte buffer.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

BaseStructure

public BaseStructure(BaseStructureHeader header)
Constructor using a provided header

Parameters:
header - the header to use.
See Also:
BaseStructureHeader
Method Detail

getStructureType

public abstract StructureType getStructureType()
A convenience method use instead of "instanceof" to see what type of structure we have. Note: this returns the type of this structure, not the type of data (the content type) this structure holds.

Specified by:
getStructureType in interface IEvioStructure
Returns:
the StructureType of this structure.
See Also:
StructureType

toXML

public abstract void toXML(javax.xml.stream.XMLStreamWriter xmlWriter)
This is a method that must be filled in by subclasses. Write this structure out as an XML record.

Parameters:
xmlWriter - the writer used to write the events. It is tied to an open file.

getXMLElementName

public abstract java.lang.String getXMLElementName()
Get the element name for the structure for writing to XML.

Returns:
the element name for the structure for writing to XML.

getByteOrder

public java.nio.ByteOrder getByteOrder()
What is the byte order of this data?

Returns:
ByteOrder.BIG_ENDIAN or ByteOrder.LITTLE_ENDIAN

setByteOrder

public void setByteOrder(java.nio.ByteOrder byteOrder)
Set the byte order of this data.

Parameters:
byteOrder - ByteOrder.BIG_ENDIAN or ByteOrder.LITTLE_ENDIAN

isSwap

public boolean isSwap()
Is a byte swap required? Since this is java, code is big endian. If data is little endian, then a swap is required.

Returns:
true if byte swapping is required (data is little endian).

getDescription

public java.lang.String getDescription()
Get the description from the name provider (dictionary), if there is one.

Specified by:
getDescription in interface IEvioStructure
Returns:
the description from the name provider (dictionary), if there is one. If not, return NameProvider.NO_NAME_STRING.

toString

public java.lang.String toString()
Obtain a string representation of the structure.

Overrides:
toString in class java.lang.Object
Returns:
a string representation of the structure.

getHeader

public BaseStructureHeader getHeader()
This is a method from the IEvioStructure Interface. Return the header for this structure.

Specified by:
getHeader in interface IEvioStructure
Returns:
the header for this structure.

getTotalBytes

public int getTotalBytes()
Get the length of this structure in bytes, including the header.

Returns:
the length of this structure in bytes, including the header.

getRawBytes

public byte[] getRawBytes()
Get the raw data of the structure.

Returns:
the raw data of the structure.

setRawBytes

public void setRawBytes(byte[] rawBytes)
Set the data for the structure.

Parameters:
rawBytes - the structure raw data.

getIntData

public int[] getIntData()
This is a method from the IEvioStructure Interface. Gets the raw data as an integer array, if the content type as indicated by the header is appropriate. NOTE: since Java does not have unsigned primitives, both INT32 and UINT32 data types will be returned as int arrays. The application will have to deal with reinterpreting signed ints that are negative as unsigned ints.

Specified by:
getIntData in interface IEvioStructure
Returns:
the data as an int array, or null if this makes no sense for the given content type.

getLongData

public long[] getLongData()
This is a method from the IEvioStructure Interface. Gets the raw data as a long array, if the content type as indicated by the header is appropriate. NOTE: since Java does not have unsigned primitives, both LONG64 and ULONG64 data types will be returned as long arrays. The application will have to deal with reinterpreting signed longs that are negative as unsigned longs.

Specified by:
getLongData in interface IEvioStructure
Returns:
the data as an long array, or null if this makes no sense for the given content type.

getFloatData

public float[] getFloatData()
This is a method from the IEvioStructure Interface. Gets the raw data as a float array, if the content type as indicated by the header is appropriate.

Specified by:
getFloatData in interface IEvioStructure
Returns:
the data as an double array, or null if this makes no sense for the given contents type.

getDoubleData

public double[] getDoubleData()
This is a method from the IEvioStructure Interface. Gets the raw data as a double array, if the content type as indicated by the header is appropriate.

Specified by:
getDoubleData in interface IEvioStructure
Returns:
the data as an double array, or null if this makes no sense for the given content type.

getShortData

public short[] getShortData()
This is a method from the IEvioStructure Interface. Gets the raw data as a double array, if the contents type as indicated by the header is appropriate. NOTE: since Java does not have unsigned primitives, both SHORT16 and USHORT16 data types will be returned as short arrays. The application will have to deal with reinterpreting signed shorts that are negative as unsigned longs.

Specified by:
getShortData in interface IEvioStructure
Returns:
the data as an short array, or null if this makes no sense for the given contents type.

getByteData

public byte[] getByteData()
This is a method from the IEvioStructure Interface. Gets the raw data as an byte array, if the contents type as indicated by the header is appropriate. NOTE: since Java does not have unsigned primitives, CHARSTAR8, CHAR8 and UCHAR8 data types will be returned as byte arrays. The application will have to deal with reinterpreting bytes as characters, if necessary.

Specified by:
getByteData in interface IEvioStructure
Returns:
the data as an byte array, or null if this makes no sense for the given contents type.

getStringData

public java.lang.String getStringData()
This is a method from the IEvioStructure Interface. Gets the raw data (ascii) as a String, if the contents type as indicated by the header is appropriate. NOTE: ending non-printing ascii chars (value < 32) are not included in the string (since they are most likely there for padding). For any other behavior, the user should retrieve the data as a byte array and manipulate it in the exact manner desired.

Specified by:
getStringData in interface IEvioStructure
Returns:
the data as a String if DataType is CHARSTAR8, or null if this makes no sense for the given type.

getParent

public BaseStructure getParent()
Get the parent of this structure. The outer event bank is the only structure with a null parent (the only orphan). All other structures have non-null parent giving the container in which they were embedded. Part of the MutableTreeNode interface.

Specified by:
getParent in interface javax.swing.tree.TreeNode
Returns:
the parent of this structure.

children

public java.util.Enumeration<?> children()
Get an enumeration of all the children of this structure. If none, it returns a constant, empty Enumeration. Part of the MutableTreeNode interface.

Specified by:
children in interface javax.swing.tree.TreeNode

insert

public void insert(javax.swing.tree.MutableTreeNode child,
                   int index)
Add a child at the given index.

Specified by:
insert in interface javax.swing.tree.MutableTreeNode
Parameters:
child - the child to add.
index - the target index. Part of the MutableTreeNode interface.

insert

public void insert(javax.swing.tree.MutableTreeNode child)
Convenience method to add a child at the end of the child list. In this application where are not concerned with the ordering of the children.

Parameters:
child - the child to add. It will be added to the end of child list.

remove

public void remove(int index)
Removes the child at index from the receiver. Part of the MutableTreeNode interface.

Specified by:
remove in interface javax.swing.tree.MutableTreeNode
Parameters:
index - the target index for removal.

remove

public void remove(javax.swing.tree.MutableTreeNode child)
Removes the child. Part of the MutableTreeNode interface.

Specified by:
remove in interface javax.swing.tree.MutableTreeNode
Parameters:
child - the child node being removed.

removeFromParent

public void removeFromParent()
Remove this node from its parent. Part of the MutableTreeNode interface.

Specified by:
removeFromParent in interface javax.swing.tree.MutableTreeNode

setParent

public void setParent(javax.swing.tree.MutableTreeNode parent)
Set the parent for this node. Part of the MutableTreeNode interface.

Specified by:
setParent in interface javax.swing.tree.MutableTreeNode

setUserObject

public void setUserObject(java.lang.Object arg0)
This method is not relevant for this implementation. An empty implementation is provided to satisfy the interface. Part of the MutableTreeNode interface.

Specified by:
setUserObject in interface javax.swing.tree.MutableTreeNode

getAllowsChildren

public boolean getAllowsChildren()
Checks whether children are allowed. Structures of structures can have children. Structures of primitive data can not. Thus is is entirely determined by the content type. Part of the MutableTreeNode interface.

Specified by:
getAllowsChildren in interface javax.swing.tree.TreeNode
Returns:
true if this node does not hold primitive data, i.e., if it is a structure of structures (a container).

getChildAt

public javax.swing.tree.TreeNode getChildAt(int index)
Obtain the child at the given index. Part of the MutableTreeNode interface.

Specified by:
getChildAt in interface javax.swing.tree.TreeNode
Parameters:
index - the target index.
Returns:
the child at the given index.

getChildCount

public int getChildCount()
Get the count of the number of children. Part of the MutableTreeNode interface.

Specified by:
getChildCount in interface javax.swing.tree.TreeNode
Returns:
the number of children.

getIndex

public int getIndex(javax.swing.tree.TreeNode node)
Get the index of a node. Part of the MutableTreeNode interface.

Specified by:
getIndex in interface javax.swing.tree.TreeNode
Returns:
the index of the target node.

isLeaf

public boolean isLeaf()
Checks whether this is a leaf. Leaves are structures with no children. All structures that contain primitive data are leaf structures. Part of the MutableTreeNode interface.
Note: this means that an empty container, say a Bank of Segments that have no segments, is a leaf.

Specified by:
isLeaf in interface javax.swing.tree.TreeNode
Returns:
true if this is a structure with a primitive data type, i.e., it is not a container structure that contains other structures.

isContainer

public boolean isContainer()
Checks whether this structure is a container, i.e. a structure of structures.

Returns:
true if this structure is a container. This is the same check as getAllowsChildren().

getChildren

public java.util.Vector<BaseStructure> getChildren()
Get the children of this structure.

Returns:
the children of this structure.

setAllHeaderLengths

public int setAllHeaderLengths()
Compute the and set length of all header fields for this structure and all its descendants. For writing events, this will be crucial for setting the values in the headers.

Returns:
the length that would go in the header field (for a leaf).

write

public int write(java.nio.ByteBuffer byteBuffer)
Write myself out a byte buffer.

Specified by:
write in interface IEvioWriter
Parameters:
byteBuffer - the byteBuffer to write to.
Returns:
the number of bytes written.

appendIntData

public void appendIntData(int[] data)
                   throws EvioException
Appends int data to the structure. If the structure has no data, then this is the same as setting the data.

Parameters:
data - the int data to append, or set if there is no existing data.
Throws:
EvioException

appendShortData

public void appendShortData(short[] data)
                     throws EvioException
Appends short data to the structure. If the structure has no data, then this is the same as setting the data.

Parameters:
data - the short data to append, or set if there is no existing data.
Throws:
EvioException

appendLongData

public void appendLongData(long[] data)
                    throws EvioException
Appends long data to the structure. If the structure has no data, then this is the same as setting the data.

Parameters:
data - the long data to append, or set if there is no existing data.
Throws:
EvioException

appendByteData

public void appendByteData(byte[] data)
                    throws EvioException
Appends byte data to the structure. If the structure has no data, then this is the same as setting the data.

Parameters:
data - the byte data to append, or set if there is no existing data.
Throws:
EvioException

appendFloatData

public void appendFloatData(float[] data)
                     throws EvioException
Appends float data to the structure. If the structure has no data, then this is the same as setting the data.

Parameters:
data - the float data to append, or set if there is no existing data.
Throws:
EvioException

appendCharData

public void appendCharData(char[] data)
                    throws EvioException
Appends char data to the structure (as ascii). If the structure has no data, then this is the same as setting the data.

Parameters:
data - the char data to append (as ascii), or set if there is no existing data.
Throws:
EvioException

appendDoubleData

public void appendDoubleData(double[] data)
                      throws EvioException
Appends double data to the structure. If the structure has no data, then this is the same as setting the data.

Parameters:
data - the double data to append, or set if there is no existing data.
Throws:
EvioException