Module org.hdfgroup.object
Package hdf.object.h4

# Class H4ScalarAttribute

Object
hdf.object.HObject
hdf.object.Dataset
hdf.object.ScalarDS
hdf.object.h4.H4ScalarAttribute

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

public class H4ScalarAttribute extends ScalarDS implements Attribute
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. For more details on attributes, read HDF5 Attributes in HDF5 User Guide The following code is an example of an attribute with 1D integer array of two elements.

     // Example of creating a new attribute
     // The name of the new attribute
     String name = "Data range";
     // Creating an unsigned 1-byte integer datatype
     Datatype type = new Datatype(Datatype.CLASS_INTEGER, // class
                                  1,                      // size in bytes
                                  Datatype.ORDER_LE,      // byte order
                                  Datatype.SIGN_NONE);    // unsigned
     // 1-D array of size two
     long[] dims = {2};
     // The value of the attribute
     int[] value = {0, 255};
     // Create a new attribute
     Attribute dataRange = new Attribute(name, type, dims);
     // Set the attribute value
     dataRange.setValue(value);
     // See FileFormat.writeAttribute() for how to attach an attribute to an object,
     @see hdf.object.FileFormat#writeAttribute(HObject, Attribute, boolean)

For an atomic datatype, the value of an H4ScalarAttribute will be a 1D array of integers, floats and strings.

Version:
  2.0 4/2/2018
Author:
  Peter X. Cao, Jordan T. Henderson
See Also:
  - `Datatype`
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected HObject`
  `parentObject`
  The HObject to which this NC2Attribute is attached, Attribute interface

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

  `fillValue, imageDataRange, interlace, INTERLACE_LINE, INTERLACE_PIXEL, INTERLACE_PLANE, isDefaultImageOrder, isFillValueConverted, isImageDisplay, isTrueColor, palette, unsignedConverted`

  ### 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, SEPARATOR`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `H4ScalarAttribute(HObject parentObj, String attrName, Datatype attrType, long[] attrDims)`
  Create an attribute with specified name, data type and dimension sizes.
  `H4ScalarAttribute(HObject parentObj, String attrName, Datatype attrType, long[] attrDims, Object attrValue)`
  Create an attribute with specific name and value.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close(long aid)`
  Closes access to the object.
  `Dataset`
  `copy(Group pgroup, String dstName, long[] dims, Object buff)`
  Creates a new dataset and writes the data buffer to the new dataset.
  `final Object`
  `getAttributeData()`
  Retrieves the attribute data from the file.
  `final Datatype`
  `getAttributeDatatype()`
  Returns the datatype of the attribute.
  `final long[]`
  `getAttributeDims()`
  Returns the array that contains the dimension sizes of the data value of the attribute.
  `final String`
  `getAttributeName()`
  Returns the name of the object.
  `final int`
  `getAttributePlane()`
  Returns the selected size of the rows and columns of the attribute.
  `final int`
  `getAttributeRank()`
  Returns the rank (number of dimensions) of the attribute.
  `final int`
  `getAttributeSpaceType()`
  Returns the space type for the attribute.
  `HObject`
  `getParentObject()`
  Returns the HObject to which this Attribute is currently "attached".
  `Object`
  `getProperty(String key)`
  get a property for a given key.
  `Collection<String>`
  `getPropertyKeys()`
  get all property keys.
  `void`
  `init()`
  Set the initial state of all the variables
  `boolean`
  `isAttributeNULL()`
  `boolean`
  `isAttributeScalar()`
  `long`
  `open()`
  Opens an existing object such as a dataset or group for access.
  `Object`
  `read()`
  Reads the data from file.
  `byte[]`
  `readBytes()`
  Reads the raw data of the dataset from file to a byte array.
  `void`
  `setAttributeData(Object d)`
  Not for public use in the future.
  `void`
  `setParentObject(HObject pObj)`
  Sets the HObject to which this Attribute is "attached".
  `void`
  `setProperty(String key, Object value)`
  set a property for the attribute.
  `String`
  `toAttributeString(String delimiter)`
  Returns a string representation of the data value.
  `String`
  `toAttributeString(String delimiter, int maxItems)`
  Returns a string representation of the data value.
  `void`
  `write(Object buf)`
  Writes a memory buffer to the object in the file.
  `void`
  `writeAttribute()`
  Writes the memory buffer of this dataset to file.
  `void`
  `writeAttribute(Object buf)`
  Writes the given data buffer into this attribute in a file.

  ### Methods inherited from class hdf.object.ScalarDS

  `addFilteredImageValue, clearData, convertFromUnsignedC, convertToUnsignedC, getFillValue, getFilteredImageValues, getImageDataRange, getInterlace, getNumberOfPalettes, getPalette, getPaletteName, isDefaultImageOrder, isImage, isImageDisplay, isTrueColor, readPalette, setImageDataRange, setIsImage, setIsImageDisplay, setPalette`

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

  `byteToString, clear, 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, refreshData, resetSelection, setConvertByteToString, setData, stringToByte, toString, toString, toString, write`

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

  `createFullname, debug, equals, equals, equalsOID, getFID, getFile, getFileFormat, getFullName, getLinkTargetObjName, getName, getOID, getPath, hashCode, setFullname, setLinkTargetObjName, setName, setPath, toString`

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

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

- ## Field Details

  - ### parentObject

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

- ## Constructor Details

  - ### H4ScalarAttribute

    public H4ScalarAttribute(HObject parentObj, String attrName, Datatype attrType, long[] attrDims)
    Create an attribute with specified name, data type and dimension sizes. For scalar attribute, the dimension size can be either an array of size one or null, and the rank can be either 1 or zero. Attribute is a general class and is independent of file format, e.g., the implementation of attribute applies to both HDF4 and HDF5. The following example creates a string attribute with the name "CLASS" and value "IMAGE".

         long[] attrDims = { 1 };
         String attrName = "CLASS";
         String[] classValue = { "IMAGE" };
         Datatype attrType = null;
         try {
             attrType = new H4Datatype(Datatype.CLASS_STRING, classValue[0].length() + 1, Datatype.NATIVE, Datatype.NATIVE);
         }
         catch (Exception ex) {}
         Attribute attr = new Attribute(attrName, attrType, attrDims);
         attr.setValue(classValue);

    Parameters:
      `parentObj` - the HObject to which this Attribute 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:
      - `Datatype`

  - ### H4ScalarAttribute

    public H4ScalarAttribute(HObject parentObj, String attrName, Datatype attrType, long[] attrDims, Object attrValue)
    Create an attribute with specific name and value. For scalar attribute, the dimension size can be either an array of size one or null, and the rank can be either 1 or zero. Attribute is a general class and is independent of file format, e.g., the implementation of attribute applies to both HDF4 and HDF5. The following example creates a string attribute with the name "CLASS" and value "IMAGE".

         long[] attrDims = { 1 };
         String attrName = "CLASS";
         String[] classValue = { "IMAGE" };
         Datatype attrType = null;
         try {
             attrType = new H4Datatype(Datatype.CLASS_STRING, classValue[0].length() + 1, Datatype.NATIVE, Datatype.NATIVE);
         }
         catch (Exception ex) {}
         Attribute attr = new Attribute(attrName, attrType, attrDims, classValue);

    Parameters:
      `parentObj` - the HObject to which this Attribute 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:
      - `Datatype`

- ## 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:
      - `HObject.close(long)`

  - ### 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()
    Description copied from interface: `DataFormat`
    Set the initial state of all the variables
    Specified by:
      `init` in interface `DataFormat`

  - ### read

    public Object read() throws Exception, OutOfMemoryError
    Reads the data from file. read() reads the data from file to a memory buffer and returns the memory buffer. The dataset object does not hold the memory buffer. To store the memory buffer in the dataset object, one must call getData(). By default, the whole dataset is read into memory. Users can also select a subset to read. Subsetting is done in an implicit way.
    Specified by:
      `read` in interface `DataFormat`
    Returns:
      the data read from file.
    Throws:
      `Exception` - if object can not be read
      `OutOfMemoryError` - if memory is exhausted
    See Also:
      - `Dataset.getData()`

  - ### write

    public void write(Object buf) throws Exception
    Writes a memory buffer to the object in the file.
    Specified by:
      `write` in interface `DataFormat`
    Parameters:
      `buf` - The buffer that contains the data values.
    Throws:
      `Exception` - if data can not be written

  - ### copy

    public Dataset copy(Group pgroup, String dstName, long[] dims, Object buff) throws Exception
    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.
      `dstName` - the name of the new dataset.
      `dims` - the dimension sizes of the the new dataset.
      `buff` - the data values of the subset to be copied.
    Returns:
      the new dataset.
    Throws:
      `Exception` - if dataset can not be copied

  - ### readBytes

    public byte[] readBytes() throws Exception
    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:
      `Exception` - if data can not be read

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

  - ### isAttributeNULL

    public boolean isAttributeNULL()
    Specified by:
      `isAttributeNULL` in interface `Attribute`
    Returns:
      true if the dataspace is a NULL; otherwise, returns false.

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