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

  • 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:

    • 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