org.jlab.coda.jevio
Class BlockHeader

java.lang.Object
  extended by org.jlab.coda.jevio.BlockHeader
All Implemented Interfaces:
IEvioWriter

public class BlockHeader
extends java.lang.Object
implements IEvioWriter

This holds a evio block header, also known as a physical record header. Unfortunately, in version 2, 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 3 so that blockd only contain integral numbers of events.

Author:
heddle

Field Summary
static int MAGIC_NUMBER
          The magic number, should be the value of magicNumber.
static int MAX_BLOCK_SIZE
          The maximum block size in 32 bit ints in this (version 2) implementation of evio.
 
Constructor Summary
BlockHeader()
          Null constructor initializes all fields to zero.
BlockHeader(int size, int number)
          Creates a BlockHeader for evio version 2 format.
BlockHeader(int size, int number, int version)
          Creates a BlockHeader.
 
Method Summary
 int bytesRemaining(int position)
          Gives the bytes remaining in this block (physical record) given a buffer position.
 int firstEventStartingPosition()
          Determines where the start of the first event (logical record) in this block (physical record) is located (in bytes).
 int 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 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 getEventCount()
          Get the number of events completely contained in the block.
 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.
 int nextBufferStartingPosition()
          Determines where the start of the next block (physical record) header in some buffer is located (in bytes).
 void setBufferStartingPosition(int 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 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 setEventCount(int count)
          Set the number of events completely contained in the block.
 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 (version 2) implementation of evio. There is, in actuality, no limit on size; however, the version 2 C library only used 8192 as the block size. In version 3 and up there is no limit.

See Also:
Constant Field Values

MAGIC_NUMBER

public static final int MAGIC_NUMBER
The magic number, should be the value of magicNumber.

See Also:
Constant Field Values
Constructor Detail

BlockHeader

public BlockHeader()
Null constructor initializes all fields to zero.


BlockHeader

public BlockHeader(int size,
                   int number)
Creates a BlockHeader for evio version 2 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.

BlockHeader

public BlockHeader(int size,
                   int number,
                   int version)
Creates a BlockHeader. Only the (block) size, (block) number, and version are provided. Only version numbers 2 or 3 are allowed. The other five words, which can be modified by setters, are initialized to these values:
  • headerLength is initialized to 8
  • start is initialized to 8 (ver2) or 0 (ver3)
  • end is initialized to size
  • 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.
version - the version number -- 2 or 3.
Method Detail

getSize

public int getSize()
Get the size of the block (physical record).

Returns:
the size of the block (physical record) in ints.

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. In evio version 3, the reserved1 element in the block header is used to store the number of events 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. In evio version 3, the reserved1 element in the block header is used to store the number of events in the block. Some trivial checking is done. 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

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

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

getNumber

public int getNumber()
Get the block number for this block (physical record). In a file, this is usually sequential.

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.

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. param 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.

Returns:
the evio version of the block (physical record) header.

setVersion

public void setVersion(int version)
Sets the evio version. Should be 1 (old) 2 (used in CODA version 2) or 3 (used in CODA version 3), but no check is performed.

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 version 2 only. In evio version 3 and later, reserved1 is used to store the number of events in the block (physical record) header.

Returns:
the first reserved word in the block (physical record). Used in evio version 2 only.

setReserved1

public void setReserved1(int reserved1)
Sets the value of reserved 1. This is not checked and should not be used in evio version 3 or later.

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".

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.

Overrides:
toString in class java.lang.Object
Returns:
a string representation of the block (physical record) header.

getBufferStartingPosition

public int 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.

Returns:
the starting position in the buffer (in bytes) from which this header was read--if that happened.

setBufferStartingPosition

public void setBufferStartingPosition(int 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.

Parameters:
bufferStartingPosition - the starting position in the buffer from which this header was read--if that happened.

nextBufferStartingPosition

public int 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.

Returns:
the start of the next block (physical record) header in some buffer is located (in bytes).

firstEventStartingPosition

public int 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.

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(int 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.

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 IEvioWriter
Parameters:
byteBuffer - the byteBuffer to write to.
Returns:
the number of bytes written, which for a BlockHeader is 32.