Module org.hdfgroup.object
Package hdf.object

# Class CompoundDS

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

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

Direct Known Subclasses:
  `H4CompoundAttribute`, `H4Vdata`, `H5CompoundAttr`, `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 Datatypes in HDF5 User 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 List<String>`
  `flatNameList`
  A list of names of all fields including nested fields.
  `protected List<Datatype>`
  `flatTypeList`
  A list of datatypes of all fields including nested fields.
  `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 final 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, isImage, isNULL, isScalar, isText, maxDims, nPoints, originalBuf, rank, selectedDims, selectedIndex, selectedStride, space_type, startDims, storage, storageLayout`

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

  `fileFormat, linkTargetObjName, oid`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CompoundDS(FileFormat theFile, String theName, String thePath)`
  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
  `protected Object`
  `convertByteMember(Datatype dtype, byte[] byteData)`
  Routine to convert datatypes that are read in as byte arrays to regular types.
  `protected Object`
  `convertCompoundByteMembers(Datatype dtype, byte[] data)`
  Given an array of bytes representing a compound Datatype, converts each of its members into Objects and returns the results.
  `Dataset`
  `copy(Group pgroup, String name, long[] dims, Object data)`
  Deprecated.
  Not implemented for compound dataset.
  `Object`
  `getFillValue()`
  Returns the fill values for the data object.
  `final int`
  `getMemberCount()`
  Returns the number of members of the compound dataset.
  `final int[]`
  `getMemberDims(int i)`
  Returns the dimension sizes of the i-th member.
  `final String[]`
  `getMemberNames()`
  Returns the names of the members of the compound dataset.
  `final int[]`
  `getMemberOrders()`
  Returns array containing the total number of elements of the members of the compound dataset.
  `final Datatype[]`
  `getMemberTypes()`
  Returns an array of datatype objects of compound members.
  `final int`
  `getSelectedMemberCount()`
  Returns the number of selected members of the compound dataset.
  `final String[]`
  `getSelectedMemberNames()`
  Returns an array of the names of the selected members of the compound dataset.
  `final int[]`
  `getSelectedMemberOrders()`
  Returns array containing the total number of elements of the selected members of the compound dataset.
  `final Datatype[]`
  `getSelectedMemberTypes()`
  Returns an array of datatype objects of selected compound members.
  `final boolean`
  `isMemberSelected(int idx)`
  Checks if a member of the compound dataset is selected for read/write.
  `protected void`
  `resetSelection()`
  Resets selection of dataspace
  `final void`
  `selectMember(int idx)`
  Selects the i-th member for read/write.
  `final 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, getDepth, getDimNames, getDims, getFilters, getHeight, getMaxDims, getOriginalClass, getRank, getSelectedDims, getSelectedIndex, getSize, getSpaceType, getStartDims, getStorage, getStorageLayout, getStride, getVirtualFilename, getVirtualMaps, getWidth, isInited, isNULL, isScalar, isString, isVirtual, readBytes, refreshData, setConvertByteToString, setData, stringToByte, toString, toString, toString, 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, getDepth, getDims, getHeight, getOriginalClass, getRank, getSelectedDims, getSelectedIndex, getSpaceType, getStartDims, getStride, getWidth, init, isInited, read, refreshData, setData, write, write`

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

  - ### flatNameList

    protected List<String> flatNameList
    A list of names of all fields including nested fields. The nested names are separated by CompoundDS.SEPARATOR. For example, if compound dataset "A" has the following nested structure,

         A --> m01
         A --> m02
         A --> nest1 --> m11
         A --> nest1 --> m12
         A --> nest1 --> nest2 --> m21
         A --> nest1 --> nest2 --> m22
         i.e.
         A = { m01, m02, nest1{m11, m12, nest2{ m21, m22}}}

    The flatNameList of compound dataset "A" will be {m01, m02, nest1[m11, nest1[m12, nest1[nest2[m21, nest1[nest2[m22}

  - ### flatTypeList

    protected List<Datatype> flatTypeList
    A list of datatypes of all fields including nested fields.

- ## Constructor Details

  - ### CompoundDS

    public CompoundDS(FileFormat theFile, String theName, String thePath)
    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 CompoundDS(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 data object.
      `theName` - the name of the data object, e.g. "dset".
      `thePath` - the full path of the data object, e.g. "/arrays/".

  - ### 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 data object.
      `dsName` - the name of the data object, e.g. "dset".
      `dsPath` - the full path of the data object, e.g. "/arrays/".
      `oid` - the oid of the data object.

- ## Method Details

  - ### resetSelection

    protected void resetSelection()
    Resets selection of dataspace
    Overrides:
      `resetSelection` in class `Dataset`

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

  - ### getFillValue

    public Object getFillValue()
    Returns the fill values for the data object.
    Specified by:
      `getFillValue` in interface `DataFormat`
    Returns:
      the fill values for the data object.

  - ### 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

  - ### convertByteMember

    protected Object convertByteMember(Datatype dtype, byte[] byteData)
    Routine to convert datatypes that are read in as byte arrays to regular types.
    Parameters:
      `dtype` - the datatype to convert to
      `byteData` - the bytes to convert
    Returns:
      the converted object

  - ### convertCompoundByteMembers

    protected Object convertCompoundByteMembers(Datatype dtype, byte[] data)
    Given an array of bytes representing a compound Datatype, converts each of its members into Objects and returns the results.
    Parameters:
      `dtype` - The compound datatype to convert
      `data` - The byte array representing the data of the compound Datatype
    Returns:
      The converted types of the bytes