org.jlab.coda.jevio

Class BlockHeaderV2

java.lang.Object

org.jlab.coda.jevio.BlockHeaderV2

All Implemented Interfaces:

java.lang.Cloneable, IBlockHeader, IEvioWriter

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

This holds an 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.

 ####################################
 Evio block header, versions 1,2 & 3:
 ####################################

 MSB(31)                          LSB(0)
 <---  32 bits ------------------------>
 _______________________________________
 |            Block Length             |
 |_____________________________________|
 |            Block Number             |
 |_____________________________________|
 |          Header Length = 8          |
 |_____________________________________|
 |               Start                 |
 |_____________________________________|
 |                End                  |
 |_____________________________________|
 |              Version                |
 |_____________________________________|
 |             Reserved 1              |
 |_____________________________________|
 |            Magic Number             |
 |_____________________________________|


      Block Length  = number of ints in block (including this one).
                      This is fixed for versions 1-3, generally at 8192 (32768 bytes)
      Block Number  = id number (starting at 0)
      Header Length = number of ints in this header (always 8)
      Start         = offset to first event header in block relative to start of block
      End           = # of valid words (header + data) in block (normally = block size)
      Version       = evio format version
      Reserved 1    = reserved
      Magic #       = magic number (0xc0da0100) used to check endianness

 

Author:

heddle

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAX_BLOCK_SIZE The maximum block size in 32 bit ints in this implementation of evio.

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

MAGIC_NUMBER

Constructor Summary

Constructors

Constructor and Description
BlockHeaderV2() Null constructor initializes all fields to zero.
BlockHeaderV2(BlockHeaderV2 blkHeader) This copy constructor creates an evio version 1-3 BlockHeader from another object of this class.
BlockHeaderV2(int size, int number) Creates a BlockHeader for evio versions 1-3 format.

Method Summary

Modifier and Type	Method and Description
int	bytesRemaining(long position) Gives the bytes remaining in this block (physical record) given a buffer position.
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).
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.
java.nio.ByteOrder	getByteOrder() Get the byte order of the data being read.
int	getEnd() Get the ending position of the block (physical record.) This is the number of valid words (header + data) in the block (physical record.) This is normally the same as the block size, except for the last block (physical record) in the file. NOTE: for evio files, even if end < size (blocksize) for the last block (physical record), the data behind it will be padded with zeroes so that the file size is an integer multiple of the block size.
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 in the block (physical record) header.
int	getSize() Get the size of the block (physical record).
int	getStart() Get the starting position of the block (physical record.).
int	getVersion() Get the evio version of the block (physical record) header.
boolean	hasDictionary() Gets whether this block's first event is an evio dictionary.
boolean	isLastBlock() Is this the last block in the file or being sent over the network? This is not implemented in evio versions 1-3.
long	nextBufferStartingPosition() Determines where the start of the next block (physical record) header in some buffer is located (in bytes).
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	setByteOrder(java.nio.ByteOrder byteOrder) Sets the byte order of data being read.
void	setEnd(int end) Set the ending position of the block (physical record.) This is the number of valid words (header + data) in the block (physical record.) This is normally the same as the block size, except for the last block (physical record) in the file.
void	setHeaderLength(int headerLength) Set the block header length, in ints.
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 reserved 1.
void	setSize(int size) Set the size of the block (physical record).
void	setStart(int start) Set the starting position 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

MAX_BLOCK_SIZE

public static final int MAX_BLOCK_SIZE

The maximum block size in 32 bit ints in this implementation of evio. There is, in actuality, no limit on size; however, the versions 1-3 C library only used 8192 as the block size.

See Also:

Constant Field Values

Constructor Detail

BlockHeaderV2

public BlockHeaderV2()

Null constructor initializes all fields to zero.

BlockHeaderV2

public BlockHeaderV2(int size,
                     int number)

Creates a BlockHeader for evio versions 1-3 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 2
  
• reserved1 is initialized to 0
  
• magicNumber is initialized to MAGIC_NUMBER
  

Parameters:

size - the size of the block in ints.

number - the block number--usually sequential.

BlockHeaderV2

public BlockHeaderV2(BlockHeaderV2 blkHeader)

This copy constructor creates an evio version 1-3 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

hasDictionary

public boolean hasDictionary()

Gets whether this block's first event is an evio dictionary. This is not implemented in evio versions 1-3. Just return false.

Specified by:

hasDictionary in interface IBlockHeader

Returns:

always returns false for evio versions 1-3

isLastBlock

public boolean isLastBlock()

Is this the last block in the file or being sent over the network? This is not implemented in evio versions 1-3. Just return false.

Specified by:

isLastBlock in interface IBlockHeader

Returns:

always returns false for evio versions 1-3

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 - if size < 8 or > MAX_BLOCK_SIZE

getStart

public int getStart()

Get the starting position of the block (physical record.). This is the offset (in ints, relative to start of block) to the start of the first event (logical record) that begins in this block. For the first event it will just be = 8, the size of the block header. For subsequent blocks it will generally not be 8. Note that a an event that spans three blocks (physical records) will have start = 0. NOTE: a logical record (event) that spans three blocks (physical records) will have start = 0.

Returns:

the starting position of the block (physical record.)

setStart

public void setStart(int start)
              throws EvioException

Set the starting position of the block (physical record.). This is the offset (in ints, relative to start of block) to the start of the first event (logical record) that begins in this block. For the first event it will just be = 8, the size of the block header. For subsequent blocks it will generally not be 8. Some trivial checking is done. Note that an event that spans three blocks (physical records) will have start = 0. NOTE: a logical record (event) that spans three blocks (physical records) will have start = 0.

Parameters:

start - the new value for the start.

Throws:

EvioException - if start < 8 or > MAX_BLOCK_SIZE

getEnd

public int getEnd()

Get the ending position of the block (physical record.) This is the number of valid words (header + data) in the block (physical record.) This is normally the same as the block size, except for the last block (physical record) in the file.
NOTE: for evio files, even if end < size (blocksize) for the last block (physical record), the data behind it will be padded with zeroes so that the file size is an integer multiple of the block size.

Returns:

the ending position of the block (physical record.)

setEnd

public void setEnd(int end)
            throws EvioException

Set the ending position of the block (physical record.) This is the number of valid words (header + data) in the block (physical record.) This is normally the same as the block size, except for the last block (physical record) in the file. Some trivial checking is done.
NOTE: for evio files, even if end < size (blocksize) for the last block (physical record), the data behind it will be padded with zeroes so that the file size is an integer multiple of the block size.

Parameters:

end - the new value for the end.

Throws:

EvioException - if start < 8 or > MAX_BLOCK_SIZE

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)
                     throws EvioException

Set the block header length, in ints. This should be 8. However, since this is usually read as part of reading the physical record header, it is a good check to have a setter rather than just fix its value at 8.

Parameters:

headerLength - the new block header length. This should be 8.

Throws:

EvioException - if headerLength is not 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 1, 2 or 3 but no check is performed here.

Parameters:

version - the evio version of evio.

getReserved1

public int getReserved1()

Get the first reserved word in the block (physical record) header. Used in evio versions 1-3 only.

Returns:

the first reserved word in the block (physical record). Used in evio versions 1-3 only.

setReserved1

public void setReserved1(int reserved1)

Sets the value of reserved 1.

Parameters:

reserved1 - the value for reserved1.

getMagicNumber

public int getMagicNumber()

Get the magic number the block (physical record) header which should be 0xc0da0100. Formerly this location in the header was called "reserved2".

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 - if magic number not the correct value.

getByteOrder

public java.nio.ByteOrder getByteOrder()

Get the byte order of the data being read.

Specified by:

getByteOrder in interface IBlockHeader

Returns:

the byte order of the data being read.

setByteOrder

public void setByteOrder(java.nio.ByteOrder byteOrder)

Sets the byte order of data being read.

Parameters:

byteOrder - the new value for data's byte order.

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 - if position < buffer starting position or > buffer end position

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.