org.jlab.coda.hipo

Class RecordInputStream

java.lang.Object

org.jlab.coda.hipo.RecordInputStream

public class RecordInputStream
extends java.lang.Object

Class which reads data to create an Evio or HIPO Record. This class is NOT thread safe!

 RECORD STRUCTURE:

               Uncompressed                                      Compressed

    +----------------------------------+            +----------------------------------+
    |       General Record Header      |            |       General Record Header      |
    +----------------------------------+            +----------------------------------+

    +----------------------------------+ ---------> +----------------------------------+
    |           Index Array            |            |        Compressed Data           |
    +----------------------------------+            |             Record               |
                                                    |                                  |
    +----------------------------------+            |                                  |
    |           User Header            |            |                  ----------------|
    |           (Optional)             |            |                  |    Pad 3      |
    |                  ----------------|            +----------------------------------+
    |                  |    Pad 1      |           ^
    +----------------------------------+          /
                                                 /
    +----------------------------------+       /
    |           Data Record            |     /
    |                                  |    /
    |                  ----------------|   /
    |                  |    Pad 2      | /
    +----------------------------------+




 GENERAL RECORD HEADER STRUCTURE ( see RecordHeader.java )

    +----------------------------------+
  1 |         Record Length            | // 32bit words, inclusive
    +----------------------------------+
  2 +         Record Number            |
    +----------------------------------+
  3 +         Header Length            | // 14 (words)
    +----------------------------------+
  4 +       Event (Index) Count        |
    +----------------------------------+
  5 +      Index Array Length          | // bytes
    +-----------------------+---------+
  6 +       Bit Info        | Version  | // version (8 bits)
    +-----------------------+----------+
  7 +      User Header Length          | // bytes
    +----------------------------------+
  8 +          Magic Number            | // 0xc0da0100
    +----------------------------------+
  9 +     Uncompressed Data Length     | // bytes
    +------+---------------------------+
 10 +  CT  |  Data Length Compressed   | // CT = compression type (4 bits)
    +----------------------------------+
 11 +        General Register 1        | // UID 1st (64 bits)
    +--                              --+
 12 +                                  |
    +----------------------------------+
 13 +        General Register 2        | // UID 2nd (64 bits)
    +--                              --+
 14 +                                  |
    +----------------------------------+
 

Since:

6.0 10/13/17

Version:

6.0

Author:

gavalian

Constructor Summary

Constructors

Constructor and Description
RecordInputStream() Default, no-arg constructor.
RecordInputStream(java.nio.ByteOrder order) Constructor with arguments.

Method Summary

Modifier and Type	Method and Description
java.nio.ByteOrder	getByteOrder() Get the byte order of the internal buffers.
int	getEntries() Returns number of the events packed in the record.
java.nio.ByteBuffer	getEvent(java.nio.ByteBuffer buffer, int index) Get the event at the given index and write it into the given byte buffer.
java.nio.ByteBuffer	getEvent(java.nio.ByteBuffer buffer, int bufOffset, int index) Get the event at the given index and write it into the given byte buffer.
byte[]	getEvent(int index) Get the event at the given index and return it in an allocated array.
int	getEventLength(int index) Returns the length of the event with given index.
RecordHeader	getHeader() Get the header of this record.
java.nio.ByteBuffer	getUncompressedDataBuffer() Get the buffer with all uncompressed data in it.
byte[]	getUserHeader() Get the user header contained in this record.
java.nio.ByteBuffer	getUserHeader(java.nio.ByteBuffer buffer, int bufOffset) Get any existing user header and write it into the given byte buffer.
RecordInputStream	getUserHeaderAsRecord(java.nio.ByteBuffer buffer, int bufOffset) Get any existing user header and write it into the given byte buffer.
boolean	hasIndex() Does this record contain an event index?
boolean	hasUserHeader() Does this record contain a user header?
static void	main(java.lang.String[] args) test main program
void	readRecord(java.nio.ByteBuffer buffer, int offset) Reads a record from the buffer at the given offset.
void	readRecord(java.io.RandomAccessFile file, long position) Reads record from the file at given position.
(package private) static int	uncompressRecord(java.nio.ByteBuffer srcBuf, int srcOff, java.nio.ByteBuffer dstBuf, boolean arrayBacked, RecordHeader header) Uncompress the data of a record from the source buffer at the given offset into the destination buffer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RecordInputStream

public RecordInputStream()

Default, no-arg constructor.

RecordInputStream

public RecordInputStream(java.nio.ByteOrder order)

Constructor with arguments.

Parameters:

order - byte order of record byte arrays.

Method Detail

getHeader

public RecordHeader getHeader()

Get the header of this record.

Returns:

header of this record.

getByteOrder

public java.nio.ByteOrder getByteOrder()

Get the byte order of the internal buffers.

Returns:

byte order of the internal buffers.

getUncompressedDataBuffer

public java.nio.ByteBuffer getUncompressedDataBuffer()

Get the buffer with all uncompressed data in it. It's position and limit are set to read only event data. That means no header, index, or user-header.

Returns:

the buffer with uncompressed event data in it.

hasIndex

public boolean hasIndex()

Does this record contain an event index?

Returns:

true if record contains an event index, else false.

hasUserHeader

public boolean hasUserHeader()

Does this record contain a user header?

Returns:

true if record contains a user header, else false.

getEvent

public byte[] getEvent(int index)

Get the event at the given index and return it in an allocated array.

Parameters:

index - index of event starting at 0. If index too large, it's set to last index. If negative, it's set to 0.

Returns:

byte array containing event.

getEventLength

public int getEventLength(int index)

Returns the length of the event with given index.

Parameters:

index - index of the event

Returns:

length of the data in bytes.

getEvent

public java.nio.ByteBuffer getEvent(java.nio.ByteBuffer buffer,
                                    int index)
                             throws HipoException

Get the event at the given index and write it into the given byte buffer. The given byte buffer has to be large enough to receive all the event's data, but the buffer.limit() is ignored and reset. If no buffer is given (arg is null), create a buffer internally and return it. Buffer's byte order is set to that of the internal buffers.

Parameters:

buffer - buffer to be filled with event starting at position = 0

index - index of event starting at 0. Negative value = 0.

Returns:

buffer or newly allocated buffer if arg is null.

Throws:

HipoException - if buffer has insufficient space to contain event (buffer.capacity() < event size).

getEvent

public java.nio.ByteBuffer getEvent(java.nio.ByteBuffer buffer,
                                    int bufOffset,
                                    int index)
                             throws HipoException

Get the event at the given index and write it into the given byte buffer. The given byte buffer has to be large enough to receive all the event's data, but the buffer.limit() is ignored and reset. If no buffer is given (arg is null), create a buffer internally and return it. Buffer's byte order is set to that of the internal buffers.

Parameters:

buffer - buffer to be filled with event.

bufOffset - offset into buffer to place event.

index - index of event starting at 0. Negative value = 0.

Returns:

buffer or newly allocated buffer if arg is null.

Throws:

HipoException - if buffer has insufficient space to contain event (buffer.capacity() - bufOffset < event size).

getUserHeader

public byte[] getUserHeader()

Get the user header contained in this record.

Returns:

the user header contained in this record, or null if none.

getUserHeader

public java.nio.ByteBuffer getUserHeader(java.nio.ByteBuffer buffer,
                                         int bufOffset)
                                  throws HipoException

Get any existing user header and write it into the given byte buffer. The given byte buffer must be large enough to contain user header. If no buffer is given (arg is null), create a buffer internally and return it. Buffer's byte order is set to that of the internal buffers. Buffer's position is set to bufOffset and limit is set to bufOffset + userHeader size.

Parameters:

buffer - buffer to be filled with user header. If null, create one and return that.

bufOffset - offset into buffer to place user header.

Returns:

buffer (or newly allocated buffer if arg is null) if header exists and successfully copied into buffer, or null if no user header exists.

Throws:

HipoException - if buffer has insufficient space to contain user header (buffer.capacity() - bufOffset < user header size). If buffer is not null and offset negative.

getUserHeaderAsRecord

public RecordInputStream getUserHeaderAsRecord(java.nio.ByteBuffer buffer,
                                               int bufOffset)
                                        throws HipoException

Get any existing user header and write it into the given byte buffer. The byte buffer must be large enough to contain it. Warning, buffer.limit() is ignored and reset. If no buffer is given (arg is null), create a buffer internally and use it. Parse the user header into the returned recordInputStream object.

Parameters:

buffer - buffer to be filled with user header

bufOffset - offset into buffer to place user header.

Returns:

record parsed from user header or null if no user header exists.

Throws:

HipoException - if non-null buffer has insufficient space to contain user header (buffer.capacity() - bufOffset < user header size). If offset negative.

readRecord

public void readRecord(java.io.RandomAccessFile file,
                       long position)
                throws HipoException

Reads record from the file at given position. Call this method or readRecord(ByteBuffer, int) before calling any other. Any compressed data is decompressed. Memory is allocated as needed. First the header is read, then the length of the record is read from header, then following bytes are read and decompressed.

Parameters:

file - opened file descriptor

position - position in the file

Throws:

HipoException - if file not in hipo format or if bad argument(s)

readRecord

public void readRecord(java.nio.ByteBuffer buffer,
                       int offset)
                throws HipoException

Reads a record from the buffer at the given offset. Call this method or readRecord(RandomAccessFile, long) before calling any other. Any compressed data is decompressed. Memory is allocated as needed.

Parameters:

buffer - buffer containing record data.

offset - offset into buffer to beginning of record data.

Throws:

HipoException - if buffer not in hipo format or if bad argument(s)

uncompressRecord

static int uncompressRecord(java.nio.ByteBuffer srcBuf,
                            int srcOff,
                            java.nio.ByteBuffer dstBuf,
                            boolean arrayBacked,
                            RecordHeader header)
                     throws HipoException

Uncompress the data of a record from the source buffer at the given offset into the destination buffer. Be aware that the position and limit of srcBuf may be changed. The limit of dstBuf may be changed. The position of dstBuf will be set to just after the user-header and just before the data.

Parameters:

srcBuf - buffer containing record data.

srcOff - offset into buffer to beginning of record data.

dstBuf - buffer into which the record is uncompressed.

arrayBacked - true if both srcBuf and dstBuf are backed by arrays.

header - RecordHeader object to be used to read the record header in srcBuf.

Returns:

the original record size in srcBuf (bytes).

Throws:

HipoException - if srcBuf/dstBuf/header is null, contains too little data, is not in proper format, or version earlier than 6.

getEntries

public int getEntries()

Returns number of the events packed in the record.

Returns:

number of the events packed in the record.

main

public static void main(java.lang.String[] args)

test main program

Parameters:

args - args.