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

# Class H5MetaDataContainer

Object
hdf.object.HObject
hdf.object.h5.H5MetaDataContainer

All Implemented Interfaces:
  `MetaDataContainer`, `Serializable`

public class H5MetaDataContainer extends HObject implements MetaDataContainer
An class that provides general I/O operations for object metadata attached to an object. For example, reading metadata content from the file into memory or writing metadata content from memory into the file.

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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected List`
  `attributeList`
  The list of attributes of this data object.
  `protected HObject`
  `parentObject`
  The HObject to which this MetaDataContainer is attached

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

  `fileFormat, linkTargetObjName, oid, SEPARATOR`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `H5MetaDataContainer(FileFormat theFile, String name, String path, HObject parent)`
  Constructs an HDF5 group with specific name, path, and parent.
  `H5MetaDataContainer(FileFormat theFile, String name, String path, HObject parent, long[] oid)`
  Deprecated.
  Not for public use in the future.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clear()`
  Removes all of the elements from metadata list.
  `void`
  `close(long tid)`
  Closes access to the object.
  `List`
  `getAttributeList()`
  Retrieves the object's attributeList.
  `List`
  `getMetadata()`
  Retrieves the object's metadata, such as attributes, from the file.
  `List`
  `getMetadata(int... attrPropList)`
  Retrieves the object's metadata, such as attributes, from the file.
  `int`
  `getObjectAttributeSize()`
  Retrieves the object's number of attributes.
  `boolean`
  `hasAttribute()`
  Check if the object has any attributes attached.
  `long`
  `open()`
  Opens an existing object such as a dataset or group for access.
  `void`
  `removeMetadata(Object metadata)`
  Deletes an existing piece of metadata from this object.
  `void`
  `setObjectAttributeSize(int objectAttributes)`
  Updates the object's number of attributes.
  `void`
  `updateMetadata(Object metadata)`
  Updates an existing piece of metadata attached to this object.
  `void`
  `writeMetadata(Object metadata)`
  Writes a specific piece of metadata (such as an attribute) into the file.

  ### 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 MetaDataContainer is attached

  - ### attributeList

    protected List attributeList
    The list of attributes of this data object. Members of the list are instance of Attribute.

- ## Constructor Details

  - ### H5MetaDataContainer

    public H5MetaDataContainer(FileFormat theFile, String name, String path, HObject parent)
    Constructs an HDF5 group with specific name, path, and parent.
    Parameters:
      `theFile` - the file which containing the group.
      `name` - the name of this group, e.g. "grp01".
      `path` - the full path of this group, e.g. "/groups/".
      `parent` - the parent of this group.

  - ### H5MetaDataContainer

    @Deprecated public H5MetaDataContainer(FileFormat theFile, String name, String path, HObject parent, long[] oid)
    Deprecated.
    Not for public use in the future.
    Parameters:
      `theFile` - the file which containing the group.
      `name` - the name of this group, e.g. "grp01".
      `path` - the full path of this group, e.g. "/groups/".
      `parent` - the parent of this group.
      `oid` - the oid of this group.

- ## Method Details

  - ### clear

    public void clear()
    Removes all of the elements from metadata list. The list should be empty after this call returns.
    Specified by:
      `clear` in interface `MetaDataContainer`

  - ### getAttributeList

    public List getAttributeList()
    Retrieves the object's attributeList.
    Returns:
      the list.

  - ### getObjectAttributeSize

    public int getObjectAttributeSize()
    Retrieves the object's number of attributes.
    Returns:
      the list size.

  - ### setObjectAttributeSize

    public void setObjectAttributeSize(int objectAttributes)
    Updates the object's number of attributes.
    Parameters:
      `objectAttributes` - the number of attributes for an object.

  - ### getMetadata

    public List getMetadata() throws Exception
    Retrieves the object's metadata, such as attributes, from the file. Metadata, such as attributes, is stored in a List.
    Specified by:
      `getMetadata` in interface `MetaDataContainer`
    Returns:
      the list of metadata objects.
    Throws:
      `Exception` - if the metadata can not be retrieved

  - ### getMetadata

    public List getMetadata(int... attrPropList) throws Exception
    Retrieves the object's metadata, such as attributes, from the file. Metadata, such as attributes, is stored in a List.
    Parameters:
      `attrPropList` - the list of properties to get
    Returns:
      the list of metadata objects.
    Throws:
      `Exception` - if the metadata can not be retrieved

  - ### writeMetadata

    public void writeMetadata(Object metadata) throws Exception
    Writes a specific piece of metadata (such as an attribute) into the file. If an HDF5 attribute exists in the file, this method updates its value. If the attribute does not exist in the file, it creates the attribute in the file and attaches it to the object. It will fail to write a new attribute to the object where an attribute with the same name already exists. To update the value of an existing attribute in the file, one needs to get the instance of the attribute by getMetadata(), change its values, then use writeMetadata() to write the value.
    Specified by:
      `writeMetadata` in interface `MetaDataContainer`
    Parameters:
      `metadata` - the metadata to write.
    Throws:
      `Exception` - if the metadata can not be written

  - ### removeMetadata

    public void removeMetadata(Object metadata) throws Exception
    Deletes an existing piece of metadata from this object.
    Specified by:
      `removeMetadata` in interface `MetaDataContainer`
    Parameters:
      `metadata` - the metadata to delete.
    Throws:
      `Exception` - if the metadata can not be removed

  - ### updateMetadata

    public void updateMetadata(Object metadata) throws Exception
    Updates an existing piece of metadata attached to this object.
    Specified by:
      `updateMetadata` in interface `MetaDataContainer`
    Parameters:
      `metadata` - the metadata to update.
    Throws:
      `Exception` - if the metadata can not be updated

  - ### hasAttribute

    public boolean hasAttribute()
    Check if the object has any attributes attached.
    Specified by:
      `hasAttribute` in interface `MetaDataContainer`
    Returns:
      true if it has any attributes, false otherwise.

  - ### 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 tid)
    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:
      `tid` - The object identifier.