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 and 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, storage_layout`

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

      `fileFormat, linkTargetObjName, oid`

  - ### Constructor Summary

    Constructors
    Constructor and 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

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and 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.
    `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, debug, equals, equalsOID, getFID, getFile, getFileFormat, getFullName, getLinkTargetObjName, getName, getOID, getPath, open, setLinkTargetObjName, setName, setPath, toString`

    - ### Methods inherited from class Object

      `clone, equals, finalize, getClass, hashCode, 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 Detail

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

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

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

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

Copyright © 2018. All Rights Reserved.