## com.rbnb.api
Class DataBlock

    java.lang.Object
      com.rbnb.api.DataBlock

All Implemented Interfaces:
  Serializable, Cloneable

    public final class DataBlock

extends Object

Describes and provides the data belonging to an `Rmap`.

A `DataBlock` consists of three basic parts:

1. The size of the data,
2. The description of the data, and
3. The data payload.

The size of the data in the `DataBlock` is required and consists of:

- The number of data points, and
- The size of each data point in bytes.

The description of the data (`DataReference`) is optional and consists of:

- The data primitive type (INT16, FLOAT32, etc.),
- The order of bytes for multi-byte values (MSB, LSB, UNKNOWN),
- A flag indicating the indivisibility of the data,
- The offset in bytes to the first point, and
- The stride in bytes from the start of one point to the start of the next.

The data payload is optional and consists of a `java.util.Vector` containing one or more arrays of data. The arrays can be one of two cases:

1. Arrays of primitive objects, or
2. Arrays of arrays of bytes.

A special case: a byte[0] array of data is a placeholder indicating that a data payload exists, but has been omitted.

Since:
  V2.0
See Also:
  `DataReference`, `Rmap`, Serialized Form
Author:
  Ian Brown
Version:
  2005/03/23

Field Summary
`static byte` `ORDER_LSB` Least-Significant-Byte first (big-endian, Intel) byte ordering.
`static byte` `ORDER_MSB` Most-Significant-Byte first (little-endian, Java) byte order.
`static byte` `TYPE_BOOLEAN` Boolean (8-bit, one byte) data type.
`static byte` `TYPE_BYTEARRAY` Byte array data type.
`static byte` `TYPE_FLOAT32` 32-bit (four byte) floating point data type.
`static byte` `TYPE_FLOAT64` 64-bit (eight byte) floating point data type.
`static byte` `TYPE_FROM_INPUT` Take the data type from the input data payload.
`static byte` `TYPE_INT16` 16-bit (two byte) signed integer data type.
`static byte` `TYPE_INT32` 32-bit (four byte) signed integer data type.
`static byte` `TYPE_INT64` 64-bit (eight byte) signed integer data type.
`static byte` `TYPE_INT8` 8-bit (one byte) signed integer data type.
`static byte` `TYPE_STRING` Character string data type.
`static byte` `TYPE_USER` User registration type.
`static byte` `UNKNOWN` Unknown data type or byte ordering.

Constructor Summary
`DataBlock()` Class constructor.
`DataBlock(Object dataI, int ndataI, int ptsizeI)` Class constructor to build a `DataBlock` from the basic fields.
`DataBlock(Object dataI, int ndataI, int ptsizeI, byte dtypeI, byte worderI, boolean indivflgI, int offsetI, int strideI)` Class constructor to build a `DataBlock` from the data payload and description from the input values.
`DataBlock(Object dataI, int ndataI, int ptsizeI, byte dtypeI, String mimeTypeI, byte worderI, boolean indivflgI, int offsetI, int strideI)` Class constructor to build a `DataBlock` from the data payload and description from the input values.

Method Summary
`void` `addData(Object dataI, int nPtsI)` Adds more data.
`Object` `clone()` Clones this `DataBlock`.
`Object` `extractData(DataBlock dRefI)` Extracts data from this data pool for the input `DataBlock`.
`Vector` `getData()` Gets the data payload.
`byte` `getDtype()` Gets the type of data.
`boolean` `getIndivFlg()` Gets the indivisible flag.
`String` `getMIMEType()` Gets the MIME type.
`int` `getNpts()` Gets the number of points.
`int` `getOffset()` Gets the number of bytes to the first point.
`int` `getPtsize()` Gets the size of a point in bytes.
`int` `getStride()` Gets the number of bytes to the next point.
`byte` `getWorder()` Gets the order of bytes within a point.
`void` `nullify()` Nullifies this `DataBlock`.
`void` `set(Object dataI, int ndataI, int ptsizeI)` Sets the data payload and description using basic values.
`void` `set(Object dataI, int ndataI, int ptsizeI, byte dtypeI, byte worderI, boolean indivflgI, int offsetI, int strideI)` Sets the data payload and description from the input values.
`void` `set(Object dataI, int ndataI, int ptsizeI, byte dtypeI, String mimeTypeI, byte worderI, boolean indivflgI, int offsetI, int strideI)` Sets the data payload and description from the input values.
`void` `setData(Object dataI)` Sets the data payload.
`void` `setDtype(byte dtypeI)` Sets the type of data.
`void` `setIndivFlg(boolean indivflgI)` Sets the indivisible flag.
`void` `setMIMEType(String mimeTypeI)` Sets the MIME type.
`void` `setNpts(int nptsI)` Sets the number of points.
`void` `setOffset(int offsetI)` Sets the number of bytes to the first point.
`void` `setOffsetStride(int offsetI, int strideI)` Sets the offset in bytes to the start of the first point and the stride in bytes between points.
`void` `setPtsize(int ptsizeI)` Sets the size of a point in bytes.
`void` `setStride(int strideI)` Sets the number of bytes to the next point.
`void` `setWorder(byte worderI)` Sets the order of bytes within a point.
`String` `toString()` Gets a displayable string representation of this `DataBlock`.

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### UNKNOWN

    public static final byte UNKNOWN

  Unknown data type or byte ordering.

  Since:
    V2.0
  See Also:
    Constant Field Values
  Author:
    Ian Brown
  Version:
    01/23/2001

### ORDER_LSB

    public static final byte ORDER_LSB

  Least-Significant-Byte first (big-endian, Intel) byte ordering.

  Since:
    V2.0
  See Also:
    Constant Field Values
  Author:
    Ian Brown
  Version:
    01/23/2001

### ORDER_MSB

    public static final byte ORDER_MSB

  Most-Significant-Byte first (little-endian, Java) byte order.

  Since:
    V2.0
  See Also:
    Constant Field Values
  Author:
    Ian Brown
  Version:
    01/23/2001

### TYPE_FROM_INPUT

    public static final byte TYPE_FROM_INPUT

  Take the data type from the input data payload.

  The resulting data type value will be one of the other types.

  Since:
    V2.0
  See Also:
    Constant Field Values
  Author:
    Ian Brown
  Version:
    01/23/2001

### TYPE_BOOLEAN

    public static final byte TYPE_BOOLEAN

  Boolean (8-bit, one byte) data type.

  Since:
    V2.0
  See Also:
    Constant Field Values
  Author:
    Ian Brown
  Version:
    01/23/2001

### TYPE_INT8

    public static final byte TYPE_INT8

  8-bit (one byte) signed integer data type.

  Since:
    V2.0
  See Also:
    Constant Field Values
  Author:
    Ian Brown
  Version:
    01/23/2001

### TYPE_INT16

    public static final byte TYPE_INT16

  16-bit (two byte) signed integer data type.

  Since:
    V2.0
  See Also:
    Constant Field Values
  Author:
    Ian Brown
  Version:
    01/23/2001

### TYPE_INT32

    public static final byte TYPE_INT32

  32-bit (four byte) signed integer data type.

  Since:
    V2.0
  See Also:
    Constant Field Values
  Author:
    Ian Brown
  Version:
    01/23/2001

### TYPE_INT64

    public static final byte TYPE_INT64

  64-bit (eight byte) signed integer data type.

  Since:
    V2.0
  See Also:
    Constant Field Values
  Author:
    Ian Brown
  Version:
    01/23/2001

### TYPE_FLOAT32

    public static final byte TYPE_FLOAT32

  32-bit (four byte) floating point data type.

  Since:
    V2.0
  See Also:
    Constant Field Values
  Author:
    Ian Brown
  Version:
    01/23/2001

### TYPE_FLOAT64

    public static final byte TYPE_FLOAT64

  64-bit (eight byte) floating point data type.

  Since:
    V2.0
  See Also:
    Constant Field Values
  Author:
    Ian Brown
  Version:
    01/23/2001

### TYPE_STRING

    public static final byte TYPE_STRING

  Character string data type.

  Since:
    V2.0
  See Also:
    Constant Field Values
  Author:
    Ian Brown
  Version:
    01/23/2001

### TYPE_BYTEARRAY

    public static final byte TYPE_BYTEARRAY

  Byte array data type.

  Since:
    V2.1
  See Also:
    Constant Field Values
  Author:
    Ian Brown
  Version:
    02/20/2002

### TYPE_USER

    public static final byte TYPE_USER

  User registration type.

  Since:
    V2.5B4
  See Also:
    Constant Field Values
  Author:
    WHF

Constructor Detail

### DataBlock

    public DataBlock()

  Class constructor.

  Since:
    V2.0
  Author:
    Ian Brown
  Version:
    08/09/2001

### DataBlock

    public DataBlock(Object dataI,
                     int ndataI,
                     int ptsizeI)

  Class constructor to build a `DataBlock` from the basic fields.

  Parameters:
    `dataI` - the data payload.
    `ndataI` - the number of points.
    `ptsizeI` - the number of bytes in a single point.
  Throws:
    `IllegalArgumentException` - thrown if the number of points or point size is not positive or if they do not match the size of the data payload.
  Since:
    V2.0
  Author:
    Ian Brown
  Version:
    01/24/2002

### DataBlock

    public DataBlock(Object dataI,
                     int ndataI,
                     int ptsizeI,
                     byte dtypeI,
                     byte worderI,
                     boolean indivflgI,
                     int offsetI,
                     int strideI)

  Class constructor to build a `DataBlock` from the data payload and description from the input values.

  Parameters:
    `dataI` - the data payload.
    `ndataI` - the number of points.
    `ptsizeI` - the number of bytes in a single point.
    `dtypeI` - the type of data.
    `worderI` - the word order of the data.
    `indivflgI` - are points are individually accessible?
    `offsetI` - the offset in bytes to the first point.
    `strideI` - the stride in bytes to the next point.
  Throws:
    `IllegalArgumentException` - thrown if:

    - the number of points is not positive,
    - the point size is not positive,
    - the offset is not 0 or positive,
    - the stride is not 0 or positive,
    - the number of points or point size does not match the size of the data payload,
    - the offset is non-zero and the data payload is not null,
    - the stride is non-zero and not equal to the point size and the data payload is not null, or
    - the data type does not match the point size or data payload type.
  Since:
    V2.0
  See Also:
    `getData()`, `getDtype()`, `getIndivFlg()`, `getNpts()`, `getOffset()`, `getPtsize()`, `getStride()`
  Author:
    Ian Brown
  Version:
    01/24/2002

### DataBlock

    public DataBlock(Object dataI,
                     int ndataI,
                     int ptsizeI,
                     byte dtypeI,
                     String mimeTypeI,
                     byte worderI,
                     boolean indivflgI,
                     int offsetI,
                     int strideI)

  Class constructor to build a `DataBlock` from the data payload and description from the input values.

  This version handles MIME data.

  Parameters:
    `dataI` - the data payload.
    `ndataI` - the number of points.
    `ptsizeI` - the number of bytes in a single point.
    `dtypeI` - the type of data.
    `mimeTypeI` - the MIME type.
    `worderI` - the word order of the data.
    `indivflgI` - are points are individually accessible?
    `offsetI` - the offset in bytes to the first point.
    `strideI` - the stride in bytes to the next point.
  Throws:
    `IllegalArgumentException` - thrown if:

    - the number of points is not positive,
    - the offset is not 0 or positive,
    - the stride is not 0 or positive,
    - the number of points does not match the size of the data payload,
    - the offset is non-zero and the data payload is not null,
    - the stride is non-zero and not equal to the point size and the data payload is not null, or
    - the data type does not match the point size or data payload type.
  Since:
    V2.0
  See Also:
    `getData()`, `getDtype()`, `getIndivFlg()`, `getMIMEType()`, `getNpts()`, `getOffset()`, `getStride()`
  Author:
    Ian Brown
  Version:
    01/25/2002

Method Detail

### addData

    public final void addData(Object dataI,
                              int nPtsI)

  Adds more data.

  This method adds the additional data as a new element of the data vector. There must already be data in the vector.

  Parameters:
    `dataI` - the data to add.
    `nPtsI` - the number of additional points.
  Since:
    V2.0
  Author:
    Ian Brown
  Version:
    08/09/2001

### clone

    public final Object clone()

  Clones this `DataBlock`.

  This method clones the data reference and payload.

  Returns:
    the clone.
  Since:
    V2.0
  Author:
    Ian Brown
  Version:
    02/20/2002

### extractData

    public final Object extractData(DataBlock dRefI)

  Extracts data from this data pool for the input `DataBlock`.

  This method supports extracting from byte arrays in all cases and from other primitive types so long as the extraction doesn't change the type.

  When extracting from an array of bytes or from an vector of arrays of bytes, the method creates an output byte array and fills it in using `System.arraycopy`.

  When extracting from an array of some other primitive type, the method creates an output array of that data type and fills it in using `System.arraycopy`.

  Parameters:
    `dRefI` - the `DataReference` (`DataBlock`).
  Returns:
    the extracted data.
  Throws:
    `IllegalStateException` - thrown if there is a mismatch between this data pool and the the `DataReference`.
  Since:
    V2.0
  Author:
    Ian Brown
  Version:
    08/30/2002

### getData

    public final Vector getData()

  Gets the data payload.

  The data payload is a `java.util.Vector` containing either:

  - A single array of primitives (shorts or floats, etc.), or
  - One byte array per data point.

  Returns:
    the data payload.
  Since:
    V2.0
  See Also:
    `setData(Object)`
  Author:
    Ian Brown
  Version:
    08/09/2001

### getDtype

    public final byte getDtype()

  Gets the type of data.

  Returns:
    the type of data.
  Since:
    V2.0
  See Also:
    `setDtype(byte)`
  Author:
    Ian Brown
  Version:
    08/09/2001

### getIndivFlg

    public final boolean getIndivFlg()

  Gets the indivisible flag.

  Returns:
    individual points are not accessible?
  Since:
    V2.0
  See Also:
    `setIndivFlg(boolean)`
  Author:
    Ian Brown
  Version:
    08/09/2001

### getMIMEType

    public final String getMIMEType()

  Gets the MIME type.

  Returns:
    the MIME type.
  Since:
    V2.0
  See Also:
    `setMIMEType(String)`
  Author:
    Ian Brown
  Version:
    01/24/2002

### getNpts

    public final int getNpts()

  Gets the number of points.

  Returns:
    the number of points.
  Since:
    V2.0
  See Also:
    `setNpts(int)`
  Author:
    Ian Brown
  Version:
    08/09/2001

### getOffset

    public final int getOffset()

  Gets the number of bytes to the first point.

  Returns:
    the number of bytes to the first point.
  Since:
    V2.0
  See Also:
    `setOffset(int)`, `setOffsetStride(int,int)`
  Author:
    Ian Brown
  Version:
    08/09/2001

### getPtsize

    public final int getPtsize()

  Gets the size of a point in bytes.

  Returns:
    the point size in bytes.
  Since:
    V2.0
  See Also:
    `setPtsize(int)`
  Author:
    Ian Brown
  Version:
    08/09/2001

### getStride

    public final int getStride()

  Gets the number of bytes to the next point.

  Returns:
    the number of bytes to the next point.
  Since:
    V2.0
  See Also:
    `setStride(int)`
  Author:
    Ian Brown
  Version:
    08/09/2001

### getWorder

    public final byte getWorder()

  Gets the order of bytes within a point.

  Returns:
    the word order.
  Since:
    V2.0
  See Also:
    `setWorder(byte)`
  Author:
    Ian Brown
  Version:
    08/09/2001

### nullify

    public final void nullify()

  Nullifies this `DataBlock`.

  This method ensures that all pointers in this `DataBlock` are cleared, reducing the effort needed by the garbage collector to clean it up.

  Since:
    V2.2
  Author:
    Ian Brown
  Version:
    07/30/2003

### set

    public final void set(Object dataI,
                          int ndataI,
                          int ptsizeI)

  Sets the data payload and description using basic values.

  The extended `DataReference` values are defaulted as follows:

  - `dtype` is set to `DataBlock.UNKNOWN`,
  - `worder` is set to `DataBlock.UNKNOWN`,
  - `indivflg` is set to false,
  - `offset` is set to 0, and
  - `stride` is set to `ptsizeI`.

  Parameters:
    `dataI` - the data payload.
    `ndataI` - the number of points.
    `ptsizeI` - the number of bytes in a single point.
  Throws:
    `IllegalArgumentException` - thrown if the number of points or point size are not positive or if they do not match the size of the data payload.
  Since:
    V2.0
  See Also:
    `getData()`, `getNpts()`, `getPtsize()`
  Author:
    Ian Brown
  Version:
    08/09/2001

### set

    public final void set(Object dataI,
                          int ndataI,
                          int ptsizeI,
                          byte dtypeI,
                          byte worderI,
                          boolean indivflgI,
                          int offsetI,
                          int strideI)

  Sets the data payload and description from the input values.

  Parameters:
    `dataI` - the data payload.
    `ndataI` - the number of points.
    `ptsizeI` - the number of bytes in a single point.
    `dtypeI` - the type of data.
    `worderI` - the word order of the data.
    `indivflgI` - are points are individually accessible?
    `offsetI` - the offset in bytes to the first point.
    `strideI` - the stride in bytes to the next point.
  Throws:
    `IllegalArgumentException` - thrown if:

    - the number of points is not positive,
    - the point size is not positive,
    - the offset is not 0 or positive,
    - the stride is not 0 or positive,
    - the number of points or point size does not match the size of the data payload,
    - the offset is non-zero and the data payload is not null,
    - the stride is non-zero and not equal to the point size and the data payload is not null,
    - the data type does not match the point size or data payload type.
  Since:
    V2.0
  See Also:
    `getData()`, `getDtype()`, `getIndivFlg()`, `getNpts()`, `getOffset()`, `getPtsize()`, `getStride()`
  Author:
    Ian Brown
  Version:
    01/25/2002

### set

    public final void set(Object dataI,
                          int ndataI,
                          int ptsizeI,
                          byte dtypeI,
                          String mimeTypeI,
                          byte worderI,
                          boolean indivflgI,
                          int offsetI,
                          int strideI)

  Sets the data payload and description from the input values.

  Parameters:
    `dataI` - the data payload.
    `ndataI` - the number of points.
    `ptsizeI` - the number of bytes in a single point.
    `dtypeI` - the type of data.
    `mimeTypeI` - the MIME type.
    `worderI` - the word order of the data.
    `indivflgI` - are points are individually accessible?
    `offsetI` - the offset in bytes to the first point.
    `strideI` - the stride in bytes to the next point.
  Throws:
    `IllegalArgumentException` - thrown if:

    - the number of points is not positive,
    - the point size is not positive,
    - the offset is not 0 or positive,
    - the stride is not 0 or positive,
    - the number of points or point size does not match the size of the data payload,
    - the offset is non-zero and the data payload is not null,
    - the stride is non-zero and not equal to the point size and the data payload is not null,
    - the data type does not match the point size or data payload type.
  Since:
    V2.0
  See Also:
    `getData()`, `getDtype()`, `getIndivFlg()`, `getNpts()`, `getOffset()`, `getPtsize()`, `getStride()`
  Author:
    Ian Brown
  Version:
    02/20/2002

### setData

    public final void setData(Object dataI)

  Sets the data payload.

  Parameters:
    `dataI` - the data payload.
  Since:
    V2.0
  See Also:
    `getData()`
  Author:
    Ian Brown
  Version:
    05/02/2003

### setDtype

    public final void setDtype(byte dtypeI)

  Sets the type of data.

  Parameters:
    `dtypeI` - the type of data.
  Throws:
    `IllegalArgumentException` - thrown if the data type doesn't match the point size or the type of the data payload.
  Since:
    V2.0
  See Also:
    `getDtype()`
  Author:
    Ian Brown
  Version:
    08/09/2001

### setIndivFlg

    public final void setIndivFlg(boolean indivflgI)

  Sets the indivisible flag.

  Parameters:
    `indivflgI` - individual points are not accessible?
  Since:
    V2.0
  See Also:
    `getIndivFlg()`
  Author:
    Ian Brown
  Version:
    08/09/2001

### setMIMEType

    public final void setMIMEType(String mimeTypeI)

  Sets the MIME type.

  Parameters:
    `mimeTypeI` - the MIME type.
  Since:
    V2.0
  See Also:
    `getMIMEType()`
  Author:
    Ian Brown
  Version:
    01/25/2002

### setNpts

    public final void setNpts(int nptsI)

  Sets the number of points.

  Parameters:
    `nptsI` - the number of points.
  Since:
    V2.0
  See Also:
    `getNpts()`
  Author:
    Ian Brown
  Version:
    05/31/2001

### setOffset

    public final void setOffset(int offsetI)

  Sets the number of bytes to the first point.

  Parameters:
    `offsetI` - the number of bytes to the first point.
  Throws:
    `IllegalArgumentException` - thrown if the offset is negative or if there is a data payload.
  Since:
    V2.0
  See Also:
    `getOffset()`, `setOffsetStride(int,int)`
  Author:
    Ian Brown
  Version:
    08/09/2001

### setOffsetStride

    public final void setOffsetStride(int offsetI,
                                      int strideI)

  Sets the offset in bytes to the start of the first point and the stride in bytes between points.

  Parameters:
    `offsetI` - The number of bytes to the first point.
    `strideI` - The number of bytes between points.
  Throws:
    `IllegalArgumentException` - thrown if the offset is negative, the stride is nnegative, or if there is a data payload.
  Since:
    V2.0
  See Also:
    `getOffset()`, `getStride()`, `setOffset(int)`, `setStride(int)`
  Author:
    Ian Brown
  Version:
    08/09/2001

### setPtsize

    public final void setPtsize(int ptsizeI)

  Sets the size of a point in bytes.

  Parameters:
    `ptsizeI` - the point size in bytes.
  Since:
    V2.0
  See Also:
    `getPtsize()`
  Author:
    Ian Brown
  Version:
    05/31/2001

### setStride

    public final void setStride(int strideI)

  Sets the number of bytes to the next point.

  Parameters:
    `strideI` - the number of bytes to the next point.
  Throws:
    `IllegalArgumentException` - thrown if the stride is negative or if there is a data payload and the stride is non-zero and not equal to the point size.
  Since:
    V2.0
  See Also:
    `getStride()`, `setOffsetStride(int,int)`
  Author:
    Ian Brown
  Version:
    08/09/2001

### setWorder

    public final void setWorder(byte worderI)

  Sets the order of bytes within a point.

  Parameters:
    `worderI` - the word order.
  Throws:
    `IllegalArgumentException` - thrown if the word order is not a legal value.
  Since:
    V2.0
  See Also:
    `getWorder()`
  Author:
    Ian Brown
  Version:
    08/09/2001

### toString

    public final String toString()

  Gets a displayable string representation of this `DataBlock`.

  Overrides:
    `toString` in class `Object`
  Returns:
    the string representation.
  Since:
    V2.0
  Author:
    Ian Brown
  Version:
    11/26/2002