hdf.object.h5

## Class H5Group

- Object
- - hdf.object.HObject
  - - hdf.object.Group
    - - hdf.object.h5.H5Group

- All Implemented Interfaces:
    MetaDataContainer, Serializable

      public class H5Group
      extends Group

  An H5Group object represents an existing HDF5 group in file.

  In HDF5, every object has at least one name. An HDF5 group is used to store a set of the names together in one place, i.e. a group. The general structure of a group is similar to that of the UNIX file system in that the group may contain references to other groups or data objects just as the UNIX directory may contain sub-directories or files.

  For more information on HDF5 Groups, HDF5 User's Guide

  Version:
    1.1 9/4/2007
  Author:
    Peter X. Cao
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected List` | `attributeList` The list of attributes of this data object.

    - ### Fields inherited from class hdf.object.Group

      `CRT_ORDER_INDEXED, CRT_ORDER_TRACKED, LINK_TYPE_EXTERNAL, LINK_TYPE_HARD, LINK_TYPE_SOFT, nMembersInFile, parent`

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

      `fileFormat, linkTargetObjName, oid, separator`

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clear()` Clears up member list and other resources in memory for the group.
    `void` | `close(long gid)` Closes access to the object.
    `static H5Group` | `create(String name, Group pgroup, long... gplist)` Creates a new group with a name in a group and with the group creation properties specified in gplist.
    `List` | `getMetadata()` Retrieves the object's metadata, such as attributes, from the file.
    `List` | `getMetadata(int... attrPropList)`
    `int` | `getNumberOfMembersInFile()` Returns the total number of members of this group in file.
    `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 info)` Deletes an existing piece of metadata from this object.
    `void` | `setName(String newName)` Sets the name of the group.
    `void` | `setPath(String newPath)` Sets the path of the object.
    `void` | `updateMetadata(Object info)` Updates an existing piece of metadata attached to this object.
    `void` | `writeMetadata(Object info)` Writes a specific piece of metadata (such as an attribute) into the file.

    - ### Methods inherited from class hdf.object.Group

      `addToMemberList, breadthFirstMemberList, depthFirstMemberList, getMember, getMemberList, getParent, isRoot, removeFromMemberList`

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

      `debug, equals, equalsOID, getFID, getFile, getFileFormat, getFullName, getLinkTargetObjName, getName, getOID, getPath, setLinkTargetObjName, toString`

    - ### Methods inherited from class Object

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

- - ### Field Detail

    - #### attributeList

          protected List attributeList

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

  - ### Constructor Detail

    - #### H5Group

          public H5Group(FileFormat theFile,
                         String name,
                         String path,
                         Group 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.

    - #### H5Group

          @Deprecated
          public H5Group(FileFormat theFile,
                                     String name,
                                     String path,
                                     Group parent,
                                     long[] oid)

      Deprecated. Not for public use in the future.
      Using `H5Group(FileFormat, String, String, Group)`
      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 Detail

    - #### hasAttribute

          public boolean hasAttribute()

      Description copied from interface: `MetaDataContainer`
      Check if the object has any attributes attached.
      Returns:
        true if it has any attributes, false otherwise.

    - #### getNumberOfMembersInFile

          public int getNumberOfMembersInFile()

      Description copied from class: `Group`
      Returns the total number of members of this group in file. Current Java applications such as HDFView cannot handle files with large numbers of objects (1,000,000 or more objects) due to JVM memory limitation. The max_members is used so that applications such as HDFView will load up to max_members number of objects. If the number of objects in file is larger than max_members, only max_members are loaded in memory.

      getNumberOfMembersInFile() returns the number of objects in this group. The number of objects in memory is obtained by getMemberList().size().

      Overrides:
        `getNumberOfMembersInFile` in class `Group`
      Returns:
        Total number of members of this group in the file.

    - #### clear

          public void clear()

      Description copied from class: `Group`
      Clears up member list and other resources in memory for the group. Since the destructor will clear memory space, the function is usually not needed.
      Overrides:
        `clear` in class `Group`

    - #### getMetadata

          public List getMetadata()
                           throws hdf.hdf5lib.exceptions.HDF5Exception

      Description copied from interface: `MetaDataContainer`
      Retrieves the object's metadata, such as attributes, from the file.

      Metadata, such as attributes, is stored in a List.

      Returns:
        the list of metadata objects.
      Throws:
        `hdf.hdf5lib.exceptions.HDF5Exception`

    - #### getMetadata

          public List getMetadata(int... attrPropList)
                           throws hdf.hdf5lib.exceptions.HDF5Exception

      Throws:
        `hdf.hdf5lib.exceptions.HDF5Exception`

    - #### writeMetadata

          public void writeMetadata(Object info)
                             throws Exception

      Description copied from interface: `MetaDataContainer`
      Writes a specific piece of metadata (such as an attribute) into the file. If an HDF(4&5) 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.
      Parameters:
        `info` - the metadata to write.
      Throws:
        `Exception` - if the metadata can not be written

    - #### removeMetadata

          public void removeMetadata(Object info)
                              throws hdf.hdf5lib.exceptions.HDF5Exception

      Description copied from interface: `MetaDataContainer`
      Deletes an existing piece of metadata from this object.
      Parameters:
        `info` - the metadata to delete.
      Throws:
        `hdf.hdf5lib.exceptions.HDF5Exception`

    - #### updateMetadata

          public void updateMetadata(Object info)
                              throws hdf.hdf5lib.exceptions.HDF5Exception

      Description copied from interface: `MetaDataContainer`
      Updates an existing piece of metadata attached to this object.
      Parameters:
        `info` - the metadata to update.
      Throws:
        `hdf.hdf5lib.exceptions.HDF5Exception`

    - #### 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 gid)

      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:
        `gid` - The object identifier.

    - #### create

          public static H5Group create(String name,
                                       Group pgroup,
                                       long... gplist)
                                throws Exception

      Creates a new group with a name in a group and with the group creation properties specified in gplist.

      The gplist contains a sequence of group creation property list identifiers, lcpl, gcpl, gapl. It allows the user to create a group with group creation properties. It will close the group creation properties specified in gplist.

      Parameters:
        `name` - The name of a new group.
        `pgroup` - The parent group object.
        `gplist` - The group creation properties, in which the order of the properties conforms the HDF5 library API, H5Gcreate(), i.e. lcpl, gcpl and gapl, where
        - lcpl : Property list for link creation
        - gcpl : Property list for group creation
        - gapl : Property list for group access
      Returns:
        The new group if successful; otherwise returns null.
      Throws:
        `Exception` - if there is a failure.
      See Also:
        `for the order of property list identifiers.`

    - #### setName

          public void setName(String newName)
                       throws Exception

      Description copied from class: `Group`
      Sets the name of the group.

      setName (String newName) changes the name of the group in memory and file.

      setName() updates the path in memory for all the objects that are under the group with the new name.

      Overrides:
        `setName` in class `Group`
      Parameters:
        `newName` - The new name of the group.
      Throws:
        `Exception` - if the name can not be set

    - #### setPath

          public void setPath(String newPath)
                       throws Exception

      Description copied from class: `HObject`
      Sets the path of the object.

      setPath() is needed to change the path for an object when the name of a group containing the object is changed by setName(). The path of the object in memory under this group should be updated to the new path to the group. Unlike setName(), setPath() does not change anything in file.

      Overrides:
        `setPath` in class `HObject`
      Parameters:
        `newPath` - The new path of the object.
      Throws:
        `Exception` - if a failure occurred

Copyright © 2018. All Rights Reserved.