Module org.hdfgroup.object
Package hdf.object

# Class CompoundDS

Object
hdf.object.HObject
hdf.object.Dataset
hdf.object.CompoundDS

All Implemented Interfaces:
  `CompoundDataFormat`, `DataFormat`, `MetaDataContainer`, `Serializable`

Direct Known Subclasses:
  `H4Vdata`, `H5CompoundDS`

public abstract class CompoundDS extends Dataset implements CompoundDataFormat
A CompoundDS is a dataset with compound datatype.

A compound datatype is an aggregation of one or more datatypes. Each member of a compound type has a name which is unique within that type, and a datatype of that member in a compound datum. Compound datatypes can be nested, i.e. members of a compound datatype can be some other compound datatype.

For more details on compound datatypes, see HDF5 User's Guide

Since Java cannot handle C-structured compound data, data in a compound dataset is loaded in to an Java List. Each element of the list is a data array that corresponds to a compound field. The data is read/written by compound field.

For example, if compound dataset "comp" has the following nested structure, and member datatypes

     comp --> m01 (int)
     comp --> m02 (float)
     comp --> nest1 --> m11 (char)
     comp --> nest1 --> m12 (String)
     comp --> nest1 --> nest2 --> m21 (long)
     comp --> nest1 --> nest2 --> m22 (double)

The data object is a Java list of six arrays: {int[], float[], char[], Stirng[], long[] and double[]}.

Version:
  1.1 9/4/2007
Author:
  Peter X. Cao
See Also:
  Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected boolean[]`
  `isMemberSelected`
  The array to store flags to indicate if a member of this compound dataset is selected for read/write.
  `protected Object[]`
  `memberDims`
  The dimension sizes of each member.
  `protected String[]`
  `memberNames`
  The names of members of the compound dataset.
  `protected int[]`
  `memberOrders`
  Returns array containing the total number of elements of the members of this compound dataset.
  `protected Datatype[]`
  `memberTypes`
  The datatypes of compound members.
  `protected int`
  `numberOfMembers`
  The number of members of the compound dataset.
  `static String`
  `SEPARATOR`
  A single character to separate the names of nested compound fields.

  ### Fields inherited from class hdf.object.Dataset

  `chunkSize, compression, COMPRESSION_GZIP_TXT, convertByteToString, convertedBuf, data, datatype, dimNames, dims, filters, inited, isDataLoaded, maxDims, nPoints, originalBuf, rank, selectedDims, selectedIndex, selectedStride, startDims, storage, storageLayout`

  ### Fields inherited from class hdf.object.HObject

  `fileFormat, linkTargetObjName, oid`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CompoundDS​(FileFormat theFile, String dsName, String dsPath)`
  Constructs a CompoundDS object with the given file, dataset name and path.
  `CompoundDS​(FileFormat theFile, String dsName, String dsPath, long[] oid)`
  Deprecated.
  Not for public use in the future.
  Using `CompoundDS(FileFormat, String, String)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Dataset`
  `copy​(Group pgroup, String name, long[] dims, Object data)`
  Deprecated.
  Not implemented for compound dataset.
  `int`
  `getMemberCount()`
  Returns the number of members of the compound dataset.
  `int[]`
  `getMemberDims​(int i)`
  Returns the dimension sizes of the i-th member.
  `String[]`
  `getMemberNames()`
  Returns the names of the members of the compound dataset.
  `int[]`
  `getMemberOrders()`
  Returns array containing the total number of elements of the members of the compound dataset.
  `Datatype[]`
  `getMemberTypes()`
  Returns an array of datatype objects of compound members.
  `int`
  `getSelectedMemberCount()`
  Returns the number of selected members of the compound dataset.
  `String[]`
  `getSelectedMemberNames()`
  Returns an array of the names of the selected members of the compound dataset.
  `int[]`
  `getSelectedMemberOrders()`
  Returns array containing the total number of elements of the selected members of the compound dataset.
  `Datatype[]`
  `getSelectedMemberTypes()`
  Returns an array of datatype objects of selected compound members.
  `boolean`
  `isMemberSelected​(int idx)`
  Checks if a member of the compound dataset is selected for read/write.
  `void`
  `selectMember​(int idx)`
  Selects the i-th member for read/write.
  `void`
  `setAllMemberSelection​(boolean selectAll)`
  Selects/deselects all members.

  ### Methods inherited from class hdf.object.Dataset

  `byteToString, clear, clearData, convertFromUnsignedC, convertFromUnsignedC, convertToUnsignedC, convertToUnsignedC, getChunkSize, getCompression, getConvertByteToString, getData, getDatatype, getDimNames, getDims, getFilters, getHeight, getMaxDims, getOriginalClass, getRank, getSelectedDims, getSelectedIndex, getSize, getStartDims, getStorage, getStorageLayout, getStride, getVirtualFilename, getVirtualMaps, getWidth, isInited, isString, isVirtual, readBytes, setConvertByteToString, setData, stringToByte, write`

  ### Methods inherited from class hdf.object.HObject

  `close, createFullname, debug, equals, equals, equalsOID, getFID, getFile, getFileFormat, getFullName, getLinkTargetObjName, getName, getOID, getPath, hashCode, open, setFullname, setLinkTargetObjName, setName, setPath, toString`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface hdf.object.DataFormat

  `clearData, convertFromUnsignedC, convertToUnsignedC, getCompression, getData, getDatatype, getDims, getFillValue, getHeight, getOriginalClass, getRank, getSelectedDims, getSelectedIndex, getStartDims, getStride, getWidth, init, isInited, read, setData, write, write`

  ### Methods inherited from interface hdf.object.MetaDataContainer

  `getMetadata, hasAttribute, removeMetadata, updateMetadata, writeMetadata`

- ## Field Details

  - ### SEPARATOR

    public static final String SEPARATOR
    A single character to separate the names of nested compound fields. An extended ASCII character, 0x95, is used to avoid common characters in compound names.
    See Also:
      Constant Field Values

  - ### numberOfMembers

    protected int numberOfMembers
    The number of members of the compound dataset.

  - ### memberNames

    protected String[] memberNames
    The names of members of the compound dataset.

  - ### memberOrders

    protected int[] memberOrders
    Returns array containing the total number of elements of the members of this compound dataset.

    For example, a compound dataset COMP has members of A, B and C as

             COMP {
                 int A;
                 float B[5];
                 double C[2][3];
             }

    memberOrders is an integer array of {1, 5, 6} to indicate that member A has one element, member B has 5 elements, and member C has 6 elements.

  - ### memberDims

    protected transient Object[] memberDims
    The dimension sizes of each member.

    The i-th element of the Object[] is an integer array (int[]) that contains the dimension sizes of the i-th member.

  - ### memberTypes

    protected Datatype[] memberTypes
    The datatypes of compound members.

  - ### isMemberSelected

    protected boolean[] isMemberSelected
    The array to store flags to indicate if a member of this compound dataset is selected for read/write.

    If a member is selected, the read/write will perform on the member. Applications such as HDFView will only display the selected members of the compound dataset.

         For example, if a compound dataset has four members
             String[] memberNames = {"X", "Y", "Z", "TIME"};
         and
             boolean[] isMemberSelected = {true, false, false, true};
         members "X" and "TIME" are selected for read and write.

- ## Constructor Details

  - ### CompoundDS

    public CompoundDS​(FileFormat theFile, String dsName, String dsPath)
    Constructs a CompoundDS object with the given file, dataset name and path.

    The dataset object represents an existing dataset in the file. For example, new H5CompoundDS(file, "dset1", "/g0/") constructs a dataset object that corresponds to the dataset, "dset1", at group "/g0/".

    This object is usually constructed at FileFormat.open(), which loads the file structure and object information into memory. It is rarely used elsewhere.

    Parameters:
      `theFile` - the file that contains the dataset.
      `dsName` - the name of the CompoundDS, e.g. "compDS".
      `dsPath` - the full path of the CompoundDS, e.g. "/g1".

  - ### CompoundDS

    @Deprecated public CompoundDS​(FileFormat theFile, String dsName, String dsPath, long[] oid)
    Deprecated.
    Not for public use in the future.
    Using `CompoundDS(FileFormat, String, String)`
    Parameters:
      `theFile` - the file that contains the dataset.
      `dsName` - the name of the CompoundDS, e.g. "compDS".
      `dsPath` - the full path of the CompoundDS, e.g. "/g1".
      `oid` - the oid of the CompoundDS.

- ## Method Details

  - ### getMemberCount

    public final int getMemberCount()
    Returns the number of members of the compound dataset.
    Specified by:
      `getMemberCount` in interface `CompoundDataFormat`
    Returns:
      the number of members of the compound dataset.

  - ### getSelectedMemberCount

    public final int getSelectedMemberCount()
    Returns the number of selected members of the compound dataset. Selected members are the compound fields which are selected for read/write.

    For example, in a compound datatype of {int A, float B, char[] C}, users can choose to retrieve only {A, C} from the dataset. In this case, getSelectedMemberCount() returns two.

    Specified by:
      `getSelectedMemberCount` in interface `CompoundDataFormat`
    Returns:
      the number of selected members.

  - ### getMemberNames

    public final String[] getMemberNames()
    Returns the names of the members of the compound dataset. The names of compound members are stored in an array of Strings.

    For example, for a compound datatype of {int A, float B, char[] C} getMemberNames() returns ["A", "B", "C"}.

    Specified by:
      `getMemberNames` in interface `CompoundDataFormat`
    Returns:
      the names of compound members.

  - ### getSelectedMemberNames

    public final String[] getSelectedMemberNames()
    Returns an array of the names of the selected members of the compound dataset.
    Specified by:
      `getSelectedMemberNames` in interface `CompoundDataFormat`
    Returns:
      an array of the names of the selected members of the compound dataset.

  - ### isMemberSelected

    public final boolean isMemberSelected​(int idx)
    Checks if a member of the compound dataset is selected for read/write.
    Specified by:
      `isMemberSelected` in interface `CompoundDataFormat`
    Parameters:
      `idx` - the index of compound member.
    Returns:
      true if the i-th memeber is selected; otherwise returns false.

  - ### selectMember

    public final void selectMember​(int idx)
    Selects the i-th member for read/write.
    Specified by:
      `selectMember` in interface `CompoundDataFormat`
    Parameters:
      `idx` - the index of compound member.

  - ### setAllMemberSelection

    public final void setAllMemberSelection​(boolean selectAll)
    Selects/deselects all members.
    Specified by:
      `setAllMemberSelection` in interface `CompoundDataFormat`
    Parameters:
      `selectAll` - The indicator to select or deselect all members. If true, all members are selected for read/write. If false, no member is selected for read/write.

  - ### getMemberOrders

    public final int[] getMemberOrders()
    Returns array containing the total number of elements of the members of the compound dataset.

    For example, a compound dataset COMP has members of A, B and C as

             COMP {
                 int A;
                 float B[5];
                 double C[2][3];
             }

    getMemberOrders() will return an integer array of {1, 5, 6} to indicate that member A has one element, member B has 5 elements, and member C has 6 elements.
    Specified by:
      `getMemberOrders` in interface `CompoundDataFormat`
    Returns:
      the array containing the total number of elements of the members of compound.

  - ### getSelectedMemberOrders

    public final int[] getSelectedMemberOrders()
    Returns array containing the total number of elements of the selected members of the compound dataset.

    For example, a compound dataset COMP has members of A, B and C as

             COMP {
                 int A;
                 float B[5];
                 double C[2][3];
             }

    If A and B are selected, getSelectedMemberOrders() returns an array of {1, 5}
    Specified by:
      `getSelectedMemberOrders` in interface `CompoundDataFormat`
    Returns:
      array containing the total number of elements of the selected members of compound.

  - ### getMemberDims

    public final int[] getMemberDims​(int i)
    Returns the dimension sizes of the i-th member.

    For example, a compound dataset COMP has members of A, B and C as

             COMP {
                 int A;
                 float B[5];
                 double C[2][3];
             }

    getMemberDims(2) returns an array of {2, 3}, while getMemberDims(1) returns an array of {5}, and getMemberDims(0) returns null.
    Specified by:
      `getMemberDims` in interface `CompoundDataFormat`
    Parameters:
      `i` - the i-th member
    Returns:
      the dimension sizes of the i-th member, null if the compound member is not an array.

  - ### getMemberTypes

    public final Datatype[] getMemberTypes()
    Returns an array of datatype objects of compound members.

    Each member of a compound dataset has its own datatype. The datatype of a member can be atomic or other compound datatype (nested compound). Sub-classes set up the datatype objects at init().

    Specified by:
      `getMemberTypes` in interface `CompoundDataFormat`
    Returns:
      the array of datatype objects of the compound members.

  - ### getSelectedMemberTypes

    public final Datatype[] getSelectedMemberTypes()
    Returns an array of datatype objects of selected compound members.
    Specified by:
      `getSelectedMemberTypes` in interface `CompoundDataFormat`
    Returns:
      an array of datatype objects of selected compound members.

  - ### copy

    @Deprecated public Dataset copy​(Group pgroup, String name, long[] dims, Object data) throws Exception
    Deprecated.
    Not implemented for compound dataset.
    Description copied from class: `Dataset`
    Creates a new dataset and writes the data buffer to the new dataset.

    This function allows applications to create a new dataset for a given data buffer. For example, users can select a specific interesting part from a large image and create a new image with the selection.

    The new dataset retains the datatype and dataset creation properties of this dataset.

    Specified by:
      `copy` in class `Dataset`
    Parameters:
      `pgroup` - the group which the dataset is copied to.
      `name` - the name of the new dataset.
      `dims` - the dimension sizes of the the new dataset.
      `data` - the data values of the subset to be copied.
    Returns:
      the new dataset.
    Throws:
      `Exception` - if dataset can not be copied