BlockHeaderV4

java.lang.Object
- org.jlab.coda.jevio.BlockHeaderV4

All Implemented Interfaces:: java.lang.Cloneable, IBlockHeader, IEvioWriter

public class BlockHeaderV4
extends java.lang.Object
implements java.lang.Cloneable, IEvioWriter, IBlockHeader

This holds a evio block header, also known as a physical record header. Unfortunately, in versions 1, 2 & 3, evio files impose an anachronistic block structure. The complication that arises is that logical records (events) will sometimes cross physical record boundaries. This block structure is changed in version 4 so that blocks only contain integral numbers of events. The information stored in this block header has also changed.

 ################################
 Evio block header, version 4:
 ################################

 MSB(31)                          LSB(0)
 <---  32 bits ------------------------>
 _______________________________________
 |            Block Length             |
 |_____________________________________|
 |            Block Number             |
 |_____________________________________|
 |          Header Length = 8          |
 |_____________________________________|
 |             Event Count             |
 |_____________________________________|
 |             reserved 1              |
 |_____________________________________|
 |          Bit info & Version         |
 |_____________________________________|
 |             reserved 2              |
 |_____________________________________|
 |             Magic Int               |
 |_____________________________________|


      Block Length       = number of ints in block (including this one).
      Block Number       = id number (starting at 1)
      Header Length      = number of ints in this header (8)
      Event Count        = number of events in this block (always an integral #).
                           NOTE: this value should not be used to parse the following
                           events since the first block may have a dictionary whose
                           presence is not included in this count.
      Reserved 1         = If bits 2-5 in bit info are RocRaw (1), then (in the first block)
                           this contains the CODA id of the source
      Bit info & Version = Lowest 8 bits are the version number (4).
                           Upper 24 bits contain bit info.
                           If a dictionary is included as the first event, bit #9 is set (=1)
                           If a last block, bit #10 is set (=1)
      Magic Int          = magic number (0xc0da0100) used to check endianness



 Bit info has the following bits defined:
   Bit  9     = true if dictionary is included (relevant for first block only)

   Bit  10    = true if this block is the last block in file or network transmission

   Bits 11-14 = type of events following (ROC Raw = 0, Physics = 1, PartialPhysics = 2,
                DisentangledPhysics = 3, User = 4, Control = 5, Prestart = 6, Go = 7,
                Pause = 8, End = 9, Other = 15).

                This is useful ONLY for the CODA online use of evio.
                That's because only a single CODA event type is placed into
                a single ET buffer. That ET buffer then is parsed by an EvioReader or
                EvioCompactReader object. Thus all events will be of a single CODA type.

Author:: heddle, timmer

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`EV_BLOCKNUM` Position of word for block number, starting at 0.
`static int`	`EV_BLOCKSIZE` Position of word for size of block in 32-bit words.
`static int`	`EV_COUNT` Position of word for number of events in block.
`static int`	`EV_DICTIONARY_MASK` Dictionary presence is 9th bit in version/info word
`static int`	`EV_HEADERSIZE` Position of word for size of header in 32-bit words (=8).
`static int`	`EV_LASTBLOCK_MASK` "Last block" is 10th bit in version/info word
`static int`	`EV_MAGIC` Position of word for magic number for endianness tracking.
`static int`	`EV_RESERVED1` Position of word for reserved.
`static int`	`EV_RESERVED2` Position of word for reserved.
`static int`	`EV_VERSION` Position of word for version of file format.
`static int`	`HEADER_SIZE` The minimum & expected block header size in 32 bit ints.

Fields inherited from interface org.jlab.coda.jevio.IBlockHeader
MAGIC_NUMBER

Constructor Summary

Constructors
Constructor and Description
`BlockHeaderV4()` Null constructor initializes all fields to zero.
`BlockHeaderV4(BlockHeaderV4 blkHeader)` This copy constructor creates an evio version 4 BlockHeader from another object of this class.
`BlockHeaderV4(int size, int number)` Creates a BlockHeader for evio version 4 format.

Method Summary

Methods
Modifier and Type	Method and Description
`static boolean`	`bitInfoHasDictionary(int word)` Parses the argument into the bit info fields and looks to see if the the "has dictionary" bit is set.
`int`	`bytesRemaining(long position)` Gives the bytes remaining in this block (physical record) given a buffer position.
`static int`	`clearLastBlockBit(int i)` Clear the last-block bit in the given arg to indicate it is NOT the last block.
`java.lang.Object`	`clone()`
`long`	`firstEventStartingPosition()` Determines where the start of the first event (logical record) in this block (physical record) is located (in bytes).
`static int`	`generateSixthWord(java.util.BitSet set)` Calculates the sixth word of this header which has the version number (4) in the lowest 8 bits and the set in the upper 24 bits.
`static int`	`generateSixthWord(java.util.BitSet bSet, boolean hasDictionary, boolean isEnd)` Calculates the sixth word of this header which has the version number (4) in the lowest 8 bits and the set in the upper 24 bits.
`static int`	`generateSixthWord(java.util.BitSet bSet, int version, boolean hasDictionary, boolean isEnd, int eventType)` Calculates the sixth word of this header which has the version number (4) in the lowest 8 bits and the set in the upper 24 bits.
`static int`	`generateSixthWord(int version, boolean hasDictionary, boolean isEnd, int eventType)` Calculates the sixth word of this header which has the version number in the lowest 8 bits.
`java.util.BitSet`	`getBitInfo()` Gets a copy of all stored bit information.
`boolean`	`getBitInfo(int bitIndex)` Gets the value of a particular bit in the bitInfo field.
`long`	`getBufferEndingPosition()` Get the position in the buffer (in bytes) of this block's last data word.
`long`	`getBufferStartingPosition()` Get the starting position in the buffer (in bytes) from which this header was read--if that happened. This is not part of the block header proper.
`int`	`getEventCount()` Get the number of events completely contained in the block.
`int`	`getEventType()` Get the value of bits 2-5.
`int`	`getHeaderLength()` Get the block header length, in ints.
`int`	`getMagicNumber()` Get the magic number the block (physical record) header which should be 0xc0da0100.
`int`	`getNumber()` Get the block number for this block (physical record).
`int`	`getReserved1()` Get the first reserved word.
`int`	`getReserved2()` Get the second reserved word.
`int`	`getSixthWord()` Calculates the sixth word of this header which has the version number in the lowest 8 bits and the bit info in the highest 24 bits.
`int`	`getSize()` Get the size of the block (physical record).
`int`	`getVersion()` Get the evio version of the block (physical record) header.
`boolean`	`hasDictionary()` Is this block's first event is an evio dictionary?
`static boolean`	`hasDictionary(int i)` Does this integer indicate that there is an evio dictionary (assuming it's the header's sixth word)?
`boolean`	`isLastBlock()` Is this the last block in the file or being sent over the network?
`static boolean`	`isLastBlock(int i)` Does this integer indicate that this is the last block (assuming it's the header's sixth word)?
`long`	`nextBufferStartingPosition()` Determines where the start of the next block (physical record) header in some buffer is located (in bytes).
`void`	`parseToBitInfo(int word)` Parses the argument into the bit info fields.
`void`	`setBit(int bitIndex, boolean value)` Sets a particular bit in the bitInfo field.
`void`	`setBufferStartingPosition(long bufferStartingPosition)` Set the starting position in the buffer (in bytes) from which this header was read--if that happened. This is not part of the block header proper.
`void`	`setEventCount(int count)` Set the number of events completely contained in the block.
`static void`	`setEventType(java.util.BitSet bSet, int type)` Sets the right bits in bit set (2-5 when starting at 0) to hold 4 bits of the given type value.
`void`	`setHeaderLength(int headerLength)` Set the block header length, in ints.
`static int`	`setLastBlockBit(int i)` Set the bit in the given arg which indicates this is the last block.
`void`	`setMagicNumber(int magicNumber)` Sets the value of magicNumber.
`void`	`setNumber(int number)` Set the block number for this block (physical record).
`void`	`setReserved1(int reserved1)` Sets the value of first reserved word.
`void`	`setReserved2(int reserved2)` Sets the value of second reserved word.
`void`	`setSize(int size)` Set the size of the block (physical record).
`void`	`setVersion(int version)` Sets the evio version.
`java.lang.String`	`toString()` Obtain a string representation of the block (physical record) header.
`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

- Field Detail
  - HEADER_SIZE
```
public static final int HEADER_SIZE
```
    The minimum & expected block header size in 32 bit ints.
    
    See Also:
    Constant Field Values
  - EV_DICTIONARY_MASK
```
public static final int EV_DICTIONARY_MASK
```
    Dictionary presence is 9th bit in version/info word
    
    See Also:
    Constant Field Values
  - EV_LASTBLOCK_MASK
```
public static final int EV_LASTBLOCK_MASK
```
    "Last block" is 10th bit in version/info word
    
    See Also:
    Constant Field Values
  - EV_BLOCKSIZE
```
public static final int EV_BLOCKSIZE
```
    Position of word for size of block in 32-bit words.
    
    See Also:
    Constant Field Values
  - EV_BLOCKNUM
```
public static final int EV_BLOCKNUM
```
    Position of word for block number, starting at 0.
    
    See Also:
    Constant Field Values
  - EV_HEADERSIZE
```
public static final int EV_HEADERSIZE
```
    Position of word for size of header in 32-bit words (=8).
    
    See Also:
    Constant Field Values
  - EV_COUNT
```
public static final int EV_COUNT
```
    Position of word for number of events in block.
    
    See Also:
    Constant Field Values
  - EV_RESERVED1
```
public static final int EV_RESERVED1
```
    Position of word for reserved.
    
    See Also:
    Constant Field Values
  - EV_VERSION
```
public static final int EV_VERSION
```
    Position of word for version of file format.
    
    See Also:
    Constant Field Values
  - EV_RESERVED2
```
public static final int EV_RESERVED2
```
    Position of word for reserved.
    
    See Also:
    Constant Field Values
  - EV_MAGIC
```
public static final int EV_MAGIC
```
    Position of word for magic number for endianness tracking.
    
    See Also:
    Constant Field Values
- Constructor Detail
  - BlockHeaderV4
```
public BlockHeaderV4()
```
    Null constructor initializes all fields to zero.
  - BlockHeaderV4
```
public BlockHeaderV4(int size,
             int number)
```
    Creates a BlockHeader for evio version 4 format. Only the block size and block number are provided. The other six words, which can be modified by setters, are initialized to these values:
    - headerLength is initialized to 8
    - start is initialized to 8
    - end is initialized to size
    - version is initialized to 4
    - bitInfo is initialized to all bits off
    - magicNumber is initialized to MAGIC_NUMBER
    Parameters:
    size - the size of the block in ints.
    number - the block number--usually sequential.
  - BlockHeaderV4
```
public BlockHeaderV4(BlockHeaderV4 blkHeader)
```
    This copy constructor creates an evio version 4 BlockHeader from another object of this class.
    
    Parameters:
    blkHeader - block header object to copy
- Method Detail
  - getSize
```
public int getSize()
```
    Get the size of the block (physical record).
    
    Specified by:
    
    getSize in interface IBlockHeader
    
    Returns:
    the size of the block (physical record) in ints.
  - clone
```
public java.lang.Object clone()
```
    Overrides:
    
    clone in class java.lang.Object
  - setSize
```
public void setSize(int size)
             throws EvioException
```
    Set the size of the block (physical record). Some trivial checking is done.
    
    Parameters:
    size - the new value for the size, in ints.
    
    Throws:
    
    EvioException
  - getEventCount
```
public int getEventCount()
```
    Get the number of events completely contained in the block. NOTE: There are no partial events, only complete events stored in one block.
    
    Returns:
    the number of events in the block.
  - setEventCount
```
public void setEventCount(int count)
                   throws EvioException
```
    Set the number of events completely contained in the block. NOTE: There are no partial events, only complete events stored in one block.
    
    Parameters:
    count - the new number of events in the block.
    
    Throws:
    
    EvioException
  - getNumber
```
public int getNumber()
```
    Get the block number for this block (physical record). In a file, this is usually sequential.
    
    Specified by:
    
    getNumber in interface IBlockHeader
    
    Returns:
    the block number for this block (physical record).
  - setNumber
```
public void setNumber(int number)
```
    Set the block number for this block (physical record). In a file, this is usually sequential. This is not checked.
    
    Parameters:
    number - the number of the block (physical record).
  - getHeaderLength
```
public int getHeaderLength()
```
    Get the block header length, in ints. This should be 8.
    
    Specified by:
    
    getHeaderLength in interface IBlockHeader
    
    Returns:
    the block header length. This should be 8.
  - setHeaderLength
```
public void setHeaderLength(int headerLength)
```
    Set the block header length, in ints. Although technically speaking this value is variable, it should be 8. param headerLength the new block header length. This should be 8.
  - getVersion
```
public int getVersion()
```
    Get the evio version of the block (physical record) header.
    
    Specified by:
    
    getVersion in interface IBlockHeader
    
    Returns:
    the evio version of the block (physical record) header.
  - setVersion
```
public void setVersion(int version)
```
    Sets the evio version. Should be 4 but no check is performed here, see EvioReader.nextBlockHeader().
    
    Parameters:
    version - the evio version of evio.
  - hasDictionary
```
public static boolean hasDictionary(int i)
```
    Does this integer indicate that there is an evio dictionary (assuming it's the header's sixth word)?
    
    Returns:
    true if this int's indicates an evio dictionary, else false
  - hasDictionary
```
public boolean hasDictionary()
```
    Is this block's first event is an evio dictionary?
    
    Specified by:
    
    hasDictionary in interface IBlockHeader
    
    Returns:
    true if this block's first event is an evio dictionary, else false
  - isLastBlock
```
public boolean isLastBlock()
```
    Is this the last block in the file or being sent over the network?
    
    Specified by:
    
    isLastBlock in interface IBlockHeader
    
    Returns:
    true if this is the last block in the file or being sent over the network, else false
  - isLastBlock
```
public static boolean isLastBlock(int i)
```
    Does this integer indicate that this is the last block (assuming it's the header's sixth word)?
    
    Returns:
    true if this int's indicates the last block, else false
  - setLastBlockBit
```
public static int setLastBlockBit(int i)
```
    Set the bit in the given arg which indicates this is the last block.
    
    Parameters:
    i - integer in which to set the last-block bit
    
    Returns:
    arg with last-block bit set
  - clearLastBlockBit
```
public static int clearLastBlockBit(int i)
```
    Clear the last-block bit in the given arg to indicate it is NOT the last block.
    
    Parameters:
    i - integer in which to clear the last-block bit
    
    Returns:
    arg with last-block bit cleared
  - getEventType
```
public int getEventType()
```
    Get the value of bits 2-5. It represents the type of event being sent.
    
    Returns:
    bits 2-5 as an integer, representing event type.
  - getBitInfo
```
public java.util.BitSet getBitInfo()
```
    Gets a copy of all stored bit information.
    
    Returns:
    copy of BitSet containing all stored bit information.
  - getBitInfo
```
public boolean getBitInfo(int bitIndex)
```
    Gets the value of a particular bit in the bitInfo field.
    
    Parameters:
    bitIndex - index of bit to get
    
    Returns:
    BitSet containing all stored bit information.
  - setBit
```
public void setBit(int bitIndex,
          boolean value)
```
    Sets a particular bit in the bitInfo field.
    
    Parameters:
    bitIndex - index of bit to change
    value - value to set bit to
  - setEventType
```
public static void setEventType(java.util.BitSet bSet,
                int type)
```
    Sets the right bits in bit set (2-5 when starting at 0) to hold 4 bits of the given type value. Useful when generating a bitset for use with EventWriter constructor.
    
    Parameters:
    bSet - Bitset containing all bits to be set
    type - event type as int
  - getSixthWord
```
public int getSixthWord()
```
    Calculates the sixth word of this header which has the version number in the lowest 8 bits and the bit info in the highest 24 bits.
    
    Returns:
    sixth word of this header.
  - generateSixthWord
```
public static int generateSixthWord(java.util.BitSet set)
```
    Calculates the sixth word of this header which has the version number (4) in the lowest 8 bits and the set in the upper 24 bits.
    
    Parameters:
    set - Bitset containing all bits to be set
    
    Returns:
    generated sixth word of this header.
  - generateSixthWord
```
public static int generateSixthWord(java.util.BitSet bSet,
                    boolean hasDictionary,
                    boolean isEnd)
```
    Calculates the sixth word of this header which has the version number (4) in the lowest 8 bits and the set in the upper 24 bits. The arg isDictionary is set in the 9th bit and isEnd is set in the 10th bit.
    
    Parameters:
    bSet - Bitset containing all bits to be set
    hasDictionary - does this block include an evio xml dictionary as the first event?
    isEnd - is this the last block of a file or a buffer?
    
    Returns:
    generated sixth word of this header.
  - generateSixthWord
```
public static int generateSixthWord(int version,
                    boolean hasDictionary,
                    boolean isEnd,
                    int eventType)
```
    Calculates the sixth word of this header which has the version number in the lowest 8 bits. The arg hasDictionary is set in the 9th bit and isEnd is set in the 10th bit. Four bits of an int (event type) are set in bits 10-13.
    
    Parameters:
    version - evio version number
    hasDictionary - does this block include an evio xml dictionary as the first event?
    isEnd - is this the last block of a file or a buffer?
    eventType - 4 bit type of events header is containing
    
    Returns:
    generated sixth word of this header.
  - generateSixthWord
```
public static int generateSixthWord(java.util.BitSet bSet,
                    int version,
                    boolean hasDictionary,
                    boolean isEnd,
                    int eventType)
```
    Calculates the sixth word of this header which has the version number (4) in the lowest 8 bits and the set in the upper 24 bits. The arg isDictionary is set in the 9th bit and isEnd is set in the 10th bit. Four bits of an int (event type) are set in bits 10-13.
    
    Parameters:
    bSet - Bitset containing all bits to be set
    version - evio version number
    hasDictionary - does this block include an evio xml dictionary as the first event?
    isEnd - is this the last block of a file or a buffer?
    eventType - 4 bit type of events header is containing
    
    Returns:
    generated sixth word of this header.
  - parseToBitInfo
```
public void parseToBitInfo(int word)
                    throws EvioException
```
    Parses the argument into the bit info fields. This ignores the version in the lowest 8 bits.
    
    Parameters:
    word - integer to parse into bit info fields
    
    Throws:
    
    EvioException
  - bitInfoHasDictionary
```
public static boolean bitInfoHasDictionary(int word)
```
    Parses the argument into the bit info fields and looks to see if the the "has dictionary" bit is set.
    
    Parameters:
    word - integer to parse into bit info fields
    
    Returns:
    true if word's "has dictionary" bit is set
  - getReserved1
```
public int getReserved1()
```
    Get the first reserved word.
    
    Returns:
    the first reserved word.
  - setReserved1
```
public void setReserved1(int reserved1)
```
    Sets the value of first reserved word.
    
    Parameters:
    reserved1 - the value for first reserved word.
  - getReserved2
```
public int getReserved2()
```
    Get the second reserved word.
    
    Returns:
    the second reserved word.
  - setReserved2
```
public void setReserved2(int reserved2)
```
    Sets the value of second reserved word.
    
    Parameters:
    reserved2 - the value for second reserved word.
  - getMagicNumber
```
public int getMagicNumber()
```
    Get the magic number the block (physical record) header which should be 0xc0da0100.
    
    Specified by:
    
    getMagicNumber in interface IBlockHeader
    
    Returns:
    the magic number in the block (physical record).
  - setMagicNumber
```
public void setMagicNumber(int magicNumber)
                    throws EvioException
```
    Sets the value of magicNumber. This should match the constant MAGIC_NUMBER. If it doesn't, some obvious possibilities:
    1) The evio data (perhaps from a file) is screwed up.
    2) The reading algorithm is screwed up.
    3) The endianess is not being handled properly.
    
    Parameters:
    magicNumber - the new value for magic number.
    
    Throws:
    
    EvioException
  - toString
```
public java.lang.String toString()
```
    Obtain a string representation of the block (physical record) header.
    
    Specified by:
    
    toString in interface IBlockHeader
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    a string representation of the block (physical record) header.
  - getBufferEndingPosition
```
public long getBufferEndingPosition()
```
    Get the position in the buffer (in bytes) of this block's last data word.
    
    Specified by:
    
    getBufferEndingPosition in interface IBlockHeader
    
    Returns:
    the position in the buffer (in bytes) of this block's last data word.
  - getBufferStartingPosition
```
public long getBufferStartingPosition()
```
    Get the starting position in the buffer (in bytes) from which this header was read--if that happened.
    This is not part of the block header proper. It is a position in a memory buffer of the start of the block (physical record). It is kept for convenience. It is up to the reader to set it.
    
    Specified by:
    
    getBufferStartingPosition in interface IBlockHeader
    
    Returns:
    the starting position in the buffer (in bytes) from which this header was read--if that happened.
  - setBufferStartingPosition
```
public void setBufferStartingPosition(long bufferStartingPosition)
```
    Set the starting position in the buffer (in bytes) from which this header was read--if that happened.
    This is not part of the block header proper. It is a position in a memory buffer of the start of the block (physical record). It is kept for convenience. It is up to the reader to set it.
    
    Specified by:
    
    setBufferStartingPosition in interface IBlockHeader
    
    Parameters:
    bufferStartingPosition - the starting position in the buffer from which this header was read--if that happened.
  - nextBufferStartingPosition
```
public long nextBufferStartingPosition()
```
    Determines where the start of the next block (physical record) header in some buffer is located (in bytes). This assumes the start position has been maintained by the object performing the buffer read.
    
    Specified by:
    
    nextBufferStartingPosition in interface IBlockHeader
    
    Returns:
    the start of the next block (physical record) header in some buffer is located (in bytes).
  - firstEventStartingPosition
```
public long firstEventStartingPosition()
```
    Determines where the start of the first event (logical record) in this block (physical record) is located (in bytes). This assumes the start position has been maintained by the object performing the buffer read.
    
    Specified by:
    
    firstEventStartingPosition in interface IBlockHeader
    
    Returns:
    where the start of the first event (logical record) in this block (physical record) is located (in bytes). Returns 0 if start is 0, signaling that this entire physical record is part of a logical record that spans at least three physical records.
  - bytesRemaining
```
public int bytesRemaining(long position)
                   throws EvioException
```
    Gives the bytes remaining in this block (physical record) given a buffer position. The position is an absolute position in a byte buffer. This assumes that the absolute position in bufferStartingPosition is being maintained properly by the reader. No block is longer than 2.1GB - 31 bits of length. This is for practical reasons - so a block can be read into a single byte array.
    
    Specified by:
    
    bytesRemaining in interface IBlockHeader
    
    Parameters:
    position - the absolute current position is a byte buffer.
    
    Returns:
    the number of bytes remaining in this block (physical record.)
    
    Throws:
    
    EvioException
  - write
```
public int write(java.nio.ByteBuffer byteBuffer)
```
    Write myself out a byte buffer. This write is relative--i.e., it uses the current position of the buffer.
    
    Specified by:
    
    write in interface IBlockHeader
    
    Specified by:
    
    write in interface IEvioWriter
    
    Parameters:
    byteBuffer - the byteBuffer to write to.
    
    Returns:
    the number of bytes written, which for a BlockHeader is 32.

Class BlockHeaderV4

Field Summary

Fields inherited from interface org.jlab.coda.jevio.IBlockHeader

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

HEADER_SIZE

EV_DICTIONARY_MASK

EV_LASTBLOCK_MASK

EV_BLOCKSIZE

EV_BLOCKNUM

EV_HEADERSIZE

EV_COUNT

EV_RESERVED1

EV_VERSION

EV_RESERVED2

EV_MAGIC

Constructor Detail

BlockHeaderV4

BlockHeaderV4

BlockHeaderV4

Method Detail

getSize

clone

setSize

getEventCount

setEventCount

getNumber

setNumber

getHeaderLength

setHeaderLength

getVersion

setVersion

hasDictionary

hasDictionary

isLastBlock

isLastBlock

setLastBlockBit

clearLastBlockBit

getEventType

getBitInfo

getBitInfo

setBit

setEventType

getSixthWord

generateSixthWord

generateSixthWord

generateSixthWord

generateSixthWord

parseToBitInfo

bitInfoHasDictionary

getReserved1

setReserved1

getReserved2

setReserved2

getMagicNumber

setMagicNumber

toString

getBufferEndingPosition

getBufferStartingPosition

setBufferStartingPosition

nextBufferStartingPosition

firstEventStartingPosition

bytesRemaining

write