Module org.hdfgroup.object
Package hdf.object

# Interface DataFormat

All Known Subinterfaces:
  `CompoundDataFormat`

All Known Implementing Classes:
  `CompoundDS`, `Dataset`, `FitsAttribute`, `FitsDataset`, `H4CompoundAttribute`, `H4GRImage`, `H4ScalarAttribute`, `H4SDS`, `H4Vdata`, `H5CompoundAttr`, `H5CompoundDS`, `H5ScalarAttr`, `H5ScalarDS`, `NC2Attribute`, `NC2Dataset`, `ScalarDS`

public interface DataFormat
An interface that provides general I/O operations for object data. For example, reading data content from the file into memory or writing data content from memory into the file.

Version:
  1.0 4/2/2018
Author:
  Jordan T. Henderson
See Also:
  - `HObject`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clearData()`
  Clears the current data buffer in memory and forces the next read() to load the data from file.
  `Object`
  `convertFromUnsignedC()`
  Converts the data values of this data object to appropriate Java integers if they are unsigned integers.
  `Object`
  `convertToUnsignedC()`
  Converts Java integer data values of this data object back to unsigned C-type integer data if they are unsigned integers.
  `String`
  `getCompression()`
  Returns the string representation of compression information.
  `Object`
  `getData()`
  Retrieves the object's data from the file.
  `Datatype`
  `getDatatype()`
  Returns the datatype of the data object.
  `long`
  `getDepth()`
  Returns the dimension size of the frame axis.
  `long[]`
  `getDims()`
  Returns the array that contains the dimension sizes of the data value of the data object.
  `Object`
  `getFillValue()`
  Returns the fill values for the data object.
  `long`
  `getHeight()`
  Returns the dimension size of the vertical axis.
  `Class`
  `getOriginalClass()`
  Get runtime Class of the original data buffer if converted.
  `int`
  `getRank()`
  Returns the rank (number of dimensions) of the data object.
  `long[]`
  `getSelectedDims()`
  Returns the dimension sizes of the selected subset.
  `int[]`
  `getSelectedIndex()`
  Returns the indices of display order.
  `int`
  `getSpaceType()`
  Returns the space type for the data object.
  `long[]`
  `getStartDims()`
  Returns the starting position of a selected subset.
  `long[]`
  `getStride()`
  Returns the selectedStride of the selected dataset.
  `long`
  `getWidth()`
  Returns the dimension size of the horizontal axis.
  `void`
  `init()`
  Set the initial state of all the variables
  `boolean`
  `isInited()`
  The status of initialization for this object
  `Object`
  `read()`
  Reads the data from file.
  `Object`
  `refreshData()`
  Refreshes the current object in the file.
  `void`
  `setData(Object data)`
  `void`
  `write()`
  Writes the current memory buffer to the object in the file.
  `void`
  `write(Object buf)`
  Writes a memory buffer to the object in the file.

- ## Method Details

  - ### isInited

    boolean isInited()
    The status of initialization for this object
    Returns:
      true if the data has been initialized

  - ### init

    void init()
    Set the initial state of all the variables

  - ### getData

    Object getData() throws Exception, OutOfMemoryError
    Retrieves the object's data from the file.
    Returns:
      the object's data.
    Throws:
      `Exception` - if the data can not be retrieved
      `OutOfMemoryError`

  - ### setData

    void setData(Object data)
    Parameters:
      `data` - the data to write.

  - ### clearData

    void clearData()
    Clears the current data buffer in memory and forces the next read() to load the data from file. The function read() loads data from file into memory only if the data is not read. If data is already in memory, read() just returns the memory buffer. Sometimes we want to force read() to re-read data from file. For example, when the selection is changed, we need to re-read the data.
    See Also:
      - `getData()`
      - `read()`

  - ### refreshData

    Object refreshData()
    Refreshes the current object in the file. The function read() loads data from file into memory only if the data is not read. If data is already in memory, read() just returns the memory buffer. Sometimes we want to force a clear and read to re-read the object from the file. For example, when the dimensions has changed, we need to refresh the object and data.
    Returns:
      the updated data
    See Also:
      - `getData()`
      - `read()`

  - ### read

    Object read() throws Exception, OutOfMemoryError
    Reads the data from file. read() reads the data from file to a memory buffer and returns the memory buffer. The dataset object does not hold the memory buffer. To store the memory buffer in the dataset object, one must call getData(). By default, the whole dataset is read into memory. Users can also select a subset to read. Subsetting is done in an implicit way.
    Returns:
      the data read from file.
    Throws:
      `Exception` - if object can not be read
      `OutOfMemoryError` - if memory is exhausted
    See Also:
      - `getData()`

  - ### write

    void write(Object buf) throws Exception
    Writes a memory buffer to the object in the file.
    Parameters:
      `buf` - the data to write
    Throws:
      `Exception` - if data can not be written

  - ### write

    void write() throws Exception
    Writes the current memory buffer to the object in the file.
    Throws:
      `Exception` - if data can not be written

  - ### convertFromUnsignedC

    Object convertFromUnsignedC()
    Converts the data values of this data object to appropriate Java integers if they are unsigned integers.
    Returns:
      the converted data buffer.
    See Also:
      - `Dataset.convertToUnsignedC(Object)`
      - `Dataset.convertFromUnsignedC(Object, Object)`

  - ### convertToUnsignedC

    Object convertToUnsignedC()
    Converts Java integer data values of this data object back to unsigned C-type integer data if they are unsigned integers.
    Returns:
      the converted data buffer.
    See Also:
      - `Dataset.convertToUnsignedC(Object)`
      - `Dataset.convertToUnsignedC(Object, Object)`

  - ### getFillValue

    Object getFillValue()
    Returns the fill values for the data object.
    Returns:
      the fill values for the data object.

  - ### getDatatype

    Datatype getDatatype()
    Returns the datatype of the data object.
    Returns:
      the datatype of the data object.

  - ### getSpaceType

    int getSpaceType()
    Returns the space type for the data object. It returns a negative number if it failed to retrieve the type information from the file.
    Returns:
      the space type for the data object.

  - ### getRank

    int getRank()
    Returns the rank (number of dimensions) of the data object. It returns a negative number if it failed to retrieve the dimension information from the file.
    Returns:
      the number of dimensions of the data object.

  - ### getDims

    long[] getDims()
    Returns the array that contains the dimension sizes of the data value of the data object. It returns null if it failed to retrieve the dimension information from the file.
    Returns:
      the dimension sizes of the data object.

  - ### getSelectedDims

    long[] getSelectedDims()
    Returns the dimension sizes of the selected subset. The SelectedDims is the number of data points of the selected subset. Applications can use this array to change the size of selected subset. The selected size must be less than or equal to the current dimension size. Combined with the starting position, selected sizes and stride, the subset of a rectangle selection is fully defined. For example, if a 4 X 5 dataset is as follows:

             0,  1,  2,  3,  4
            10, 11, 12, 13, 14
            20, 21, 22, 23, 24
            30, 31, 32, 33, 34
         long[] dims = {4, 5};
         long[] startDims = {1, 2};
         long[] selectedDims = {3, 3};
         long[] selectedStride = {1, 1};
         then the following subset is selected by the startDims and selectedDims
             12, 13, 14
             22, 23, 24
             32, 33, 34

    Returns:
      the dimension sizes of the selected subset.

  - ### getStartDims

    long[] getStartDims()
    Returns the starting position of a selected subset. Applications can use this array to change the starting position of a selection. Combined with the selected dimensions, selected sizes and stride, the subset of a rectangle selection is fully defined. For example, if a 4 X 5 dataset is as follows:

             0,  1,  2,  3,  4
            10, 11, 12, 13, 14
            20, 21, 22, 23, 24
            30, 31, 32, 33, 34
         long[] dims = {4, 5};
         long[] startDims = {1, 2};
         long[] selectedDims = {3, 3};
         long[] selectedStride = {1, 1};
         then the following subset is selected by the startDims and selectedDims
             12, 13, 14
             22, 23, 24
             32, 33, 34

    Returns:
      the starting position of a selected subset.

  - ### getStride

    long[] getStride()
    Returns the selectedStride of the selected dataset. Applications can use this array to change how many elements to move in each dimension. Combined with the starting position and selected sizes, the subset of a rectangle selection is defined. For example, if a 4 X 5 dataset is as follows:

             0,  1,  2,  3,  4
            10, 11, 12, 13, 14
            20, 21, 22, 23, 24
            30, 31, 32, 33, 34
         long[] dims = {4, 5};
         long[] startDims = {0, 0};
         long[] selectedDims = {2, 2};
         long[] selectedStride = {2, 3};
         then the following subset is selected by the startDims and selectedDims
             0,   3
             20, 23

    Returns:
      the selectedStride of the selected dataset.

  - ### getSelectedIndex

    int[] getSelectedIndex()
    Returns the indices of display order. selectedIndex[] is provided for two purposes:
    1. selectedIndex[] is used to indicate the order of dimensions for display. selectedIndex[0] is for the row, selectedIndex[1] is for the column and selectedIndex[2] for the depth. For example, for a four dimension dataset, if selectedIndex[] = {1, 2, 3}, then dim[1] is selected as row index, dim[2] is selected as column index and dim[3] is selected as depth index.
    2. selectedIndex[] is also used to select dimensions for display for datasets with three or more dimensions. We assume that applications such as HDFView can only display data values up to three dimensions (2D spreadsheet/image with a third dimension which the 2D spreadsheet/image is selected from). For datasets with more than three dimensions, we need selectedIndex[] to tell applications which three dimensions are chosen for display.
       For example, for a four dimension dataset, if selectedIndex[] = {1, 2, 3}, then dim[1] is selected as row index, dim[2] is selected as column index and dim[3] is selected as depth index. dim[0] is not selected. Its location is fixed at 0 by default.
    Returns:
      the array of the indices of display order.

  - ### getHeight

    long getHeight()
    Returns the dimension size of the vertical axis. This function is used by GUI applications such as HDFView. GUI applications display a dataset in a 2D table or 2D image. The display order is specified by the index array of selectedIndex as follow:
    selectedIndex[0] -- height
      The vertical axis
    selectedIndex[1] -- width
      The horizontal axis
    selectedIndex[2] -- depth
      The depth axis is used for 3 or more dimensional datasets.
    Applications can use getSelectedIndex() to access and change the display order. For example, in a 2D dataset of 200x50 (dim0=200, dim1=50), the following code will set the height=200 and width=50.

         int[] selectedIndex = dataset.getSelectedIndex();
         selectedIndex[0] = 0;
         selectedIndex[1] = 1;

    Returns:
      the size of dimension of the vertical axis.
    See Also:
      - `getSelectedIndex()`
      - `getWidth()`

  - ### getWidth

    long getWidth()
    Returns the dimension size of the horizontal axis. This function is used by GUI applications such as HDFView. GUI applications display a dataset in 2D Table or 2D Image. The display order is specified by the index array of selectedIndex as follow:
    selectedIndex[0] -- height
      The vertical axis
    selectedIndex[1] -- width
      The horizontal axis
    selectedIndex[2] -- depth
      The depth axis, which is used for 3 or more dimension datasets.
    Applications can use getSelectedIndex() to access and change the display order. For example, in a 2D dataset of 200x50 (dim0=200, dim1=50), the following code will set the height=200 and width=100.

         int[] selectedIndex = dataset.getSelectedIndex();
         selectedIndex[0] = 0;
         selectedIndex[1] = 1;

    Returns:
      the size of dimension of the horizontal axis.
    See Also:
      - `getSelectedIndex()`
      - `getHeight()`

  - ### getDepth

    long getDepth()
    Returns the dimension size of the frame axis. This function is used by GUI applications such as HDFView. GUI applications display a dataset in 2D Table or 2D Image. The display order is specified by the index array of selectedIndex as follow:
    selectedIndex[0] -- height
      The vertical axis
    selectedIndex[1] -- width
      The horizontal axis
    selectedIndex[2] -- depth
      The depth axis, which is used for 3 or more dimension datasets.
    Applications can use getSelectedIndex() to access and change the display order. For example, in a 2D dataset of 200x50 (dim0=200, dim1=50), the following code will set the height=200 and width=100.

         int[] selectedIndex = dataset.getSelectedIndex();
         selectedIndex[0] = 0;
         selectedIndex[1] = 1;

    Returns:
      the size of dimension of the frame axis.
    See Also:
      - `getSelectedIndex()`
      - `getHeight()`

  - ### getCompression

    String getCompression()
    Returns the string representation of compression information. For example, "SZIP: Pixels per block = 8: H5Z_FILTER_CONFIG_DECODE_ENABLED".
    Returns:
      the string representation of compression information.

  - ### getOriginalClass

    Class getOriginalClass()
    Get runtime Class of the original data buffer if converted.
    Returns:
      the Class of the original data buffer