Module org.hdfgroup.object
Package hdf.object.h5

Class H5CompoundAttr

Object
hdf.object.HObject
hdf.object.Dataset
hdf.object.CompoundDS
hdf.object.h5.H5CompoundAttr
All Implemented Interfaces:
Attribute, CompoundDataFormat, DataFormat, H5Attribute, Serializable
public class H5CompoundAttr extends CompoundDS implements H5Attribute
The H5CompoundAttr class defines an HDF5 attribute of compound datatypes. An attribute is a (name, value) pair of metadata attached to a primary data object such as a dataset, group or named datatype. Like a dataset, an attribute has a name, datatype and dataspace. A HDF5 compound datatype is similar to a struct in C or a common block in Fortran: it is a collection of one or more atomic types or small arrays of such types. Each member of a compound type has a name which is unique within that type, and a byte offset that determines the first byte (smallest byte address) of that member in a compound datum. For more information on HDF5 attributes and datatypes, read the HDF5 User's Guide. There are two basic types of compound attributes: simple compound data and nested compound data. Members of a simple compound attribute have atomic datatypes. Members of a nested compound attribute are compound or array of compound data. Since Java does not understand C structures, we cannot directly read/write compound data values as in the following C example. 
 typedef struct s1_t {
         int    a;
         float  b;
         double c;
         } s1_t;
     s1_t       s1[LENGTH];
     ...
     H5Dwrite(..., s1);
     H5Dread(..., s1);
Values of compound data fields are stored in java.util.Vector object. We read and write compound data by fields instead of compound structure. As for the example above, the java.util.Vector object has three elements: int[LENGTH], float[LENGTH] and double[LENGTH]. Since Java understands the primitive datatypes of int, float and double, we will be able to read/write the compound data by field.
Version:
1.0 6/15/2021
Author:
Allen Byrne
See Also:

  • Field Details

    • parentObject

      protected HObject parentObject
      The HObject to which this NC2Attribute is attached, Attribute interface

  • Constructor Details

    • H5CompoundAttr

      public H5CompoundAttr(HObject parentObj, String attrName, Datatype attrType, long[] attrDims)
      Create an attribute with specified name, data type and dimension sizes.
      Parameters:
      parentObj - the HObject to which this H5CompoundAttr is attached.
      attrName - the name of the attribute.
      attrType - the datatype of the attribute.
      attrDims - the dimension sizes of the attribute, null for scalar attribute
      See Also:

    • H5CompoundAttr

      public H5CompoundAttr(HObject parentObj, String attrName, Datatype attrType, long[] attrDims, Object attrValue)
      Create an attribute with specific name and value.
      Parameters:
      parentObj - the HObject to which this H5CompoundAttr is attached.
      attrName - the name of the attribute.
      attrType - the datatype of the attribute.
      attrDims - the dimension sizes of the attribute, null for scalar attribute
      attrValue - the value of the attribute, null if no value
      See Also:

  • Method Details

    • open

      public long open()
      Description copied from class: HObject
      Opens an existing object such as a dataset or group for access. The return value is an object identifier obtained by implementing classes such as H5.H5Dopen(). This function is needed to allow other objects to be able to access the object. For instance, H5File class uses the open() function to obtain object identifier for copyAttributes(long src_id, long dst_id) and other purposes. The open() function should be used in pair with close(long) function.
      Specified by:
      open in class HObject
      Returns:
      the object identifier if successful; otherwise returns a negative value.
      See Also:

    • close

      public void close(long aid)
      Description copied from class: HObject
      Closes access to the object. Sub-classes must implement this interface because different data objects have their own ways of how the data resources are closed. For example, H5Group.close() calls the hdf.hdf5lib.H5.H5Gclose() method and closes the group resource specified by the group id.
      Specified by:
      close in class HObject
      Parameters:
      aid - The object identifier.

    • init

      public void init()
      Retrieves datatype and dataspace information from file and sets the attribute in memory. The init() is designed to support lazy operation in a attribute object. When a data object is retrieved from file, the datatype, dataspace and raw data are not loaded into memory. When it is asked to read the raw data from file, init() is first called to get the datatype and dataspace information, then load the raw data from file. init() is also used to reset the selection of a attribute (start, stride and count) to the default, which is the entire attribute for 1D or 2D datasets. In the following example, init() at step 1) retrieves datatype and dataspace information from file. getData() at step 3) reads only one data point. init() at step 4) resets the selection to the whole attribute. getData() at step 4) reads the values of whole attribute into memory. 
       dset = (Dataset) file.get(NAME_DATASET);

 // 1) get datatype and dataspace information from file
 attr.init();
 rank = attr.getAttributeRank(); // rank = 2, a 2D attribute
 count = attr.getSelectedDims();
 start = attr.getStartDims();
 dims = attr.getAttributeDims();

 // 2) select only one data point
 for (int i = 0; i < rank; i++) {
     start[0] = 0;
     count[i] = 1;
 }

 // 3) read one data point
 data = attr.getAttributeData();

 // 4) reset selection to the whole attribute
 attr.init();

 // 5) clean the memory data buffer
 attr.clearData();

 // 6) Read the whole attribute
 data = attr.getAttributeData();
      Specified by:
      init in interface DataFormat

    • getDatatype

      public Datatype getDatatype()
      Returns the datatype of the data object.
      Specified by:
      getDatatype in interface DataFormat
      Overrides:
      getDatatype in class Dataset
      Returns:
      the datatype of the data object.

    • getData

      public Object getData() throws Exception, OutOfMemoryError
      Returns the data buffer of the attribute in memory. If data is already loaded into memory, returns the data; otherwise, calls read() to read data from file into a memory buffer and returns the memory buffer. The whole attribute is read into memory. Users can also select a subset from the whole data. Subsetting is done in an implicit way. How to Select a Subset A selection is specified by three arrays: start, stride and count.
      1. start: offset of a selection
      2. stride: determines how many elements to move in each dimension
      3. count: number of elements to select in each dimension
      getStartDims(), getStride() and getSelectedDims() returns the start, stride and count arrays respectively. Applications can make a selection by changing the values of the arrays. The following example shows how to make a subset. In the example, the attribute is a 4-dimensional array of [200][100][50][10], i.e. dims[0]=200; dims[1]=100; dims[2]=50; dims[3]=10;
      We want to select every other data point in dims[1] and dims[2] 
       int rank = attribute.getRank(); // number of dimensions of the attribute
 long[] dims = attribute.getDims(); // the dimension sizes of the attribute
 long[] selected = attribute.getSelectedDims(); // the selected size of the attribute
 long[] start = attribute.getStartDims(); // the offset of the selection
 long[] stride = attribute.getStride(); // the stride of the attribute
 int[] selectedIndex = attribute.getSelectedIndex(); // the selected dimensions for display

 // select dim1 and dim2 as 2D data for display,and slice through dim0
 selectedIndex[0] = 1;
 selectedIndex[1] = 2;
 selectedIndex[2] = 0;

 // reset the selection arrays
 for (int i = 0; i < rank; i++) {
     start[i] = 0;
     selected[i] = 1;
     stride[i] = 1;
 }

 // set stride to 2 on dim1 and dim2 so that every other data point is
 // selected.
 stride[1] = 2;
 stride[2] = 2;

 // set the selection size of dim1 and dim2
 selected[1] = dims[1] / stride[1];
 selected[2] = dims[1] / stride[2];

 // when H5CompoundAttr.getData() is called, the selection above will be used since
 // the dimension arrays are passed by reference. Changes of these arrays
 // outside the attribute object directly change the values of these array
 // in the attribute object.
      For H5CompoundAttr, the memory data object is an java.util.List object. Each element of the list is a data array that corresponds to a compound field. For example, if compound attribute "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)
      getData() returns a list of six arrays: {int[], float[], char[], String[], long[] and double[]}.
      Specified by:
      getData in interface DataFormat
      Overrides:
      getData in class Dataset
      Returns:
      the memory buffer of the attribute.
      Throws:
      Exception - if object can not be read
      OutOfMemoryError - if memory is exhausted

    • readBytes

      public byte[] readBytes() throws hdf.hdf5lib.exceptions.HDF5Exception
      Description copied from class: Dataset
      Reads the raw data of the dataset from file to a byte array. readBytes() reads raw data to an array of bytes instead of array of its datatype. For example, for a one-dimension 32-bit integer dataset of size 5, readBytes() returns a byte array of size 20 instead of an int array of 5. readBytes() can be used to copy data from one dataset to another efficiently because the raw data is not converted to its native type, it saves memory space and CPU time.
      Specified by:
      readBytes in class Dataset
      Returns:
      the byte array of the raw data.
      Throws:
      hdf.hdf5lib.exceptions.HDF5Exception

    • read

      public Object read() throws Exception
      Reads the data from file. read() reads the data from file to a memory buffer and returns the memory buffer. The attribute object does not hold the memory buffer. To store the memory buffer in the attribute object, one must call getData(). By default, the whole attribute is read into memory. For CompoundAttr, the memory data object is an java.util.List object. Each element of the list is a data array that corresponds to a 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)
      getData() returns a list of six arrays: {int[], float[], char[], String[], long[] and double[]}.
      Specified by:
      read in interface DataFormat
      Returns:
      the data read from file.
      Throws:
      Exception - if object can not be read
      See Also:

    • write

      public void write(Object buf) throws Exception
      Writes the given data buffer into this attribute in a file. The data buffer is a vector that contains the data values of compound fields. The data is written into file as one data blob.
      Specified by:
      write in interface DataFormat
      Parameters:
      buf - The vector that contains the data values of compound fields.
      Throws:
      Exception - If there is an error at the HDF5 library level.

    • convertByteMember

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

    • convertFromUnsignedC

      public Object convertFromUnsignedC()
      Converts the data values of this data object to appropriate Java integers if they are unsigned integers.
      Specified by:
      convertFromUnsignedC in interface DataFormat
      Returns:
      the converted data buffer.
      See Also:

    • convertToUnsignedC

      public Object convertToUnsignedC()
      Converts Java integer data values of this data object back to unsigned C-type integer data if they are unsigned integers.
      Specified by:
      convertToUnsignedC in interface DataFormat
      Returns:
      the converted data buffer.
      See Also:

    • getParentObject

      public HObject getParentObject()
      Returns the HObject to which this Attribute is currently "attached".
      Specified by:
      getParentObject in interface Attribute
      Returns:
      the HObject to which this Attribute is currently "attached".

    • setParentObject

      public void setParentObject(HObject pObj)
      Sets the HObject to which this Attribute is "attached".
      Specified by:
      setParentObject in interface Attribute
      Parameters:
      pObj - the new HObject to which this Attribute is "attached".

    • setProperty

      public void setProperty(String key, Object value)
      set a property for the attribute.
      Specified by:
      setProperty in interface Attribute
      Parameters:
      key - the attribute Map key
      value - the attribute Map value

    • getProperty

      public Object getProperty(String key)
      get a property for a given key.
      Specified by:
      getProperty in interface Attribute
      Parameters:
      key - the attribute Map key
      Returns:
      the property

    • getPropertyKeys

      public Collection<String> getPropertyKeys()
      get all property keys.
      Specified by:
      getPropertyKeys in interface Attribute
      Returns:
      the Collection of property keys

    • getAttributeName

      public final String getAttributeName()
      Returns the name of the object. For example, "Raster Image #2".
      Specified by:
      getAttributeName in interface Attribute
      Returns:
      The name of the object.

    • getAttributeData

      public final Object getAttributeData() throws Exception, OutOfMemoryError
      Retrieves the attribute data from the file.
      Specified by:
      getAttributeData in interface Attribute
      Returns:
      the attribute data.
      Throws:
      Exception - if the data can not be retrieved
      OutOfMemoryError

    • getAttributeDatatype

      public final Datatype getAttributeDatatype()
      Returns the datatype of the attribute.
      Specified by:
      getAttributeDatatype in interface Attribute
      Returns:
      the datatype of the attribute.

    • getAttributeSpaceType

      public final int getAttributeSpaceType()
      Returns the space type for the attribute. It returns a negative number if it failed to retrieve the type information from the file.
      Specified by:
      getAttributeSpaceType in interface Attribute
      Returns:
      the space type for the attribute.

    • getAttributeRank

      public final int getAttributeRank()
      Returns the rank (number of dimensions) of the attribute. It returns a negative number if it failed to retrieve the dimension information from the file.
      Specified by:
      getAttributeRank in interface Attribute
      Returns:
      the number of dimensions of the attribute.

    • getAttributePlane

      public final int getAttributePlane()
      Returns the selected size of the rows and columns of the attribute. It returns a negative number if it failed to retrieve the size information from the file.
      Specified by:
      getAttributePlane in interface Attribute
      Returns:
      the selected size of the rows and colums of the attribute.

    • getAttributeDims

      public final long[] getAttributeDims()
      Returns the array that contains the dimension sizes of the data value of the attribute. It returns null if it failed to retrieve the dimension information from the file.
      Specified by:
      getAttributeDims in interface Attribute
      Returns:
      the dimension sizes of the attribute.

    • isAttributeScalar

      public boolean isAttributeScalar()
      Specified by:
      isAttributeScalar in interface Attribute
      Returns:
      true if the data is a single scalar point; otherwise, returns false.

    • setAttributeData

      public void setAttributeData(Object d)
      Not for public use in the future. setData() is not safe to use because it changes memory buffer of the dataset object. Dataset operations such as write/read will fail if the buffer type or size is changed.
      Specified by:
      setAttributeData in interface Attribute
      Parameters:
      d - the object data -must be an array of Objects

    • writeAttribute

      public void writeAttribute() throws Exception
      Writes the memory buffer of this dataset to file.
      Specified by:
      writeAttribute in interface Attribute
      Throws:
      Exception - if buffer can not be written

    • writeAttribute

      public void writeAttribute(Object buf) throws Exception
      Writes the given data buffer into this attribute in a file. The data buffer is a vector that contains the data values of compound fields. The data is written into file as one data blob.
      Specified by:
      writeAttribute in interface Attribute
      Parameters:
      buf - The vector that contains the data values of compound fields.
      Throws:
      Exception - If there is an error at the library level.

    • toAttributeString

      public String toAttributeString(String delimiter)
      Returns a string representation of the data value. For example, "0, 255". For a compound datatype, it will be a 1D array of strings with field members separated by the delimiter. For example, "{0, 10.5}, {255, 20.0}, {512, 30.0}" is a compound attribute of {int, float} of three data points.
      Specified by:
      toAttributeString in interface Attribute
      Parameters:
      delimiter - The delimiter used to separate individual data points. It can be a comma, semicolon, tab or space. For example, toString(",") will separate data by commas.
      Returns:
      the string representation of the data values.

    • toAttributeString

      public String toAttributeString(String delimiter, int maxItems)
      Returns a string representation of the data value. For example, "0, 255". For a compound datatype, it will be a 1D array of strings with field members separated by the delimiter. For example, "{0, 10.5}, {255, 20.0}, {512, 30.0}" is a compound attribute of {int, float} of three data points.
      Specified by:
      toAttributeString in interface Attribute
      Parameters:
      delimiter - The delimiter used to separate individual data points. It can be a comma, semicolon, tab or space. For example, toString(",") will separate data by commas.
      maxItems - The maximum number of Array values to return
      Returns:
      the string representation of the data values.

    • AttributeCommonIO

      public Object AttributeCommonIO(long attr_id, H5File.IO_TYPE ioType, Object objBuf) throws Exception
      The general read and write attribute operations for hdf5 object data.
      Specified by:
      AttributeCommonIO in interface H5Attribute
      Parameters:
      attr_id - the attribute to access
      ioType - the type of IO operation
      objBuf - the data buffer to use for write operation
      Returns:
      the attribute data
      Throws:
      Exception - if the data can not be retrieved

    • AttributeSelection

      public Object AttributeSelection() throws Exception
      Read a subset of an attribute for hdf5 object data.
      Specified by:
      AttributeSelection in interface H5Attribute
      Returns:
      the selected attribute data
      Throws:
      Exception - if the data can not be retrieved