ncsa.hdf.object

## Class CompoundDS

- java.lang.Object
- - ncsa.hdf.object.HObject
  - - ncsa.hdf.object.Dataset
    - - ncsa.hdf.object.CompoundDS

All Implemented Interfaces:
  java.io.Serializable, DataFormat

Direct Known Subclasses:
  H4Vdata, H5CompoundDS

    public abstract class CompoundDS
    extends Dataset

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 datatype can be nested, i.e. members of compound datatype can be some other compound datatype.

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

Since Java cannot handle C-structured compound data, data in 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 memeber 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 an 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
`protected boolean[]` `isMemberSelected` The array to store flags to indicate if a member of compound dataset is selected for read/write.
`protected java.lang.Object[]` `memberDims` The dimension sizes of each member.
`protected java.lang.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 compound.
`protected Datatype[]` `memberTypes` The datatypes of compound members.
`protected int` `numberOfMembers` The number of members of the compound dataset.
`static java.lang.String` `separator` A single character to separate the names of nested compound fields.

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

`chunkSize, compression, convertByteToString, convertedBuf, data, datatype, dimNames, dims, enumConverted, isDataLoaded, maxDims, nPoints, originalBuf, rank, selectedDims, selectedIndex, selectedStride, startDims`

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

`linkTargetObjName, oid`

### Constructor Summary

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

### Method Summary

Methods
`Dataset` `copy(Group pgroup, java.lang.String name, long[] dims, java.lang.Object data)` Deprecated. Not implemented for compound dataset.
`int` `getMemberCount()` Returns the number of members of the compound dataset.
`java.lang.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 compound.
`Datatype[]` `getMemberTypes()` Returns an array of datatype objects of compound members.
`int[]` `getMemeberDims(int i)` Returns the dimension sizes of of the i-th member.
`int` `getSelectedMemberCount()` Returns the number of selected members of the compound dataset.
`int[]` `getSelectedMemberOrders()` Returns array containing the total number of elements of the elected members of compound.
`Datatype[]` `getSelectedMemberTypes()` Returns an array of datatype objects of selected compound members.
`boolean` `isMemberSelected(int idx)` Checks if a member of compound is selected for read/write.
`void` `selectMember(int idx)` Selects the i-th member for read/write.
`void` `setMemberSelection(boolean isSelected)` Selects/deselects all members.

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

`byteToString, clear, clearData, convertFromUnsignedC, convertFromUnsignedC, convertToUnsignedC, convertToUnsignedC, getChunkSize, getCompression, getConvertByteToString, getData, getDatatype, getDimNames, getDims, getHeight, getMaxDims, getRank, getSelectedDims, getSelectedIndex, getSize, getStartDims, getStride, getWidth, init, isEnumConverted, isString, read, readBytes, setConvertByteToString, setData, setEnumConverted, stringToByte, write, write`

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

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

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

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

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

`getMetadata, hasAttribute, removeMetadata, writeMetadata`

### Field Detail

#### separator

    public static final java.lang.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 java.lang.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 compound.

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 java.lang.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 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,
              java.lang.String name,
              java.lang.String path)

Constructs a CompoundDS object with 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 informatoin into tree structure (TreeNode). It is rarely used elsewhere.

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

#### CompoundDS

    @Deprecated
    public CompoundDS(FileFormat theFile,
                         java.lang.String name,
                         java.lang.String path,
                         long[] oid)

Deprecated. Not for public use in the future.
Using `CompoundDS(FileFormat, String, String)`

### Method Detail

#### getMemberCount

    public final int getMemberCount()

Returns the number of members of the compound dataset.

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 dataset. In this case, getSelectedMemberCount() returns two.

Returns:
  the number of selected members.

#### getMemberNames

    public final java.lang.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"}.

Returns:
  the names of compound members.

#### isMemberSelected

    public final boolean isMemberSelected(int idx)

Checks if a member of compound is selected for read/write.

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.

Parameters:
  `idx` - the index of compound member.

#### setMemberSelection

    public final void setMemberSelection(boolean isSelected)

Selects/deselects all members.

Parameters:
  `isSelected` - 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 compound.

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.

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 elected members of compound.

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}

Returns:
  array containing the total number of elements of the selected members of compound.

#### getMemeberDims

    public final int[] getMemeberDims(int i)

Returns the dimension sizes of 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];
         }

getMemeberDims(2) returns an array of {2, 3}, while getMemeberDims(1) returns an array of {5}, getMemeberDims(0) returns null.

Returns:
  the dimension sizes of 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().

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.

Returns:
  an array of datatype objects of selected compound members.

#### copy

    @Deprecated
    public Dataset copy(Group pgroup,
                          java.lang.String name,
                          long[] dims,
                          java.lang.Object data)
                 throws java.lang.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:
  `java.lang.Exception`