Module org.hdfgroup.object
Package hdf.object

Class HObject

Object
hdf.object.HObject
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
Dataset, Datatype, Group, H5Link, H5MetaDataContainer
public abstract class HObject extends Object implements Serializable
The HObject class is the root class of all the HDF data objects. Every data class has HObject as a superclass. All objects implement the methods of this class. The following is the inherited structure of HDF Objects. 
                                 HObject
          __________________________|________________________________
          |                         |                               |
        Group                    Dataset                        Datatype
          |                _________|___________                    |
          |                |                   |                    |
          |             ScalarDS          CompoundDS                |
          |                |                   |                    |
    ---------------------Implementing classes such as-------------------------
      ____|____       _____|______        _____|_____          _____|_____
      |       |       |          |        |         |          |         |
   H5Group H4Group H5ScalarDS H4ScalarDS H5CompDS H4CompDS H5Datatype H4Datatype
All HDF4 and HDF5 data objects are inherited from HObject. At the top level of the hierarchy, both HDF4 and HDF5 have the same super-classes, such as Group and Dataset. At the bottom level of the hierarchy, HDF4 and HDF5 objects have their own implementation, such as H5Group, H5ScalarDS, H5CompoundDS, and H5Datatype. Warning: HDF4 and HDF5 may have multiple links to the same object. Data objects in this model do not deal with multiple links. Users may create duplicate copies of the same data object with different paths. Applications should check the OID of the data object to avoid duplicate copies of the same object. HDF4 objects are uniquely identified by the OID (tag_id, ref_id) pair. The ref_id is the object reference count. The tag_id is a pre-defined number to identify the type of object. For example, DFTAG_RI is for raster image, DFTAG_SD is for scientific dataset, and DFTAG_VG is for Vgroup. HDF5 objects are uniquely identified by the OID containing just the object reference. The OID is usually obtained by H5Rcreate_object(). The following example shows how to retrieve an object ID from a file: 
                // retrieve the object ID
                byte[] refBuf = null;
                try {
                    refBuf = H5.H5Rcreate_object(theFile.getFID(), this.getFullName(), HDF5Constants.H5P_DEFAULT);
                    this.oid = HDFNativeData.byteToLong(refBuf);
                    log.trace("constructor REF {} to OID {}", refBuf, this.oid);
                }
                catch (Exception ex) {
                    log.debug("constructor ID {} for {} failed H5Rcreate_object", theFile.getFID(), this.getFullName());
                }
                finally {
                    if (refBuf)
                        H5.H5Rdestroy(refBuf);
                }
Version:
2.0 4/2/2018
Author:
Peter X. Cao, Jordan T. Henderson
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final FileFormat
    fileFormat
    The file which contains the object
    protected String
    linkTargetObjName
    The name of the Target Object that is being linked to.
    protected long[]
    oid
    Array of long integer storing unique identifier for the object.
    static final String
    SEPARATOR
    The separator of object path, i.e.

  • Constructor Summary

    Constructors
    Constructor
    Description
    HObject()
    Constructs an instance of a data object without name and path.
    HObject(FileFormat theFile, String theName, String thePath)
    Constructs an instance of a data object with specific name and path.
    HObject(FileFormat theFile, String theName, String thePath, long[] oid)
    Deprecated.

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract void
    close(long id)
    Closes access to the object.
    String
    createFullname(String thePath, String theName)
    Creates the full name of the object.
    protected final void
    debug(Object msg)
    Print out debug information
    boolean
    equals(HObject obj)
    Returns whether this HObject is equal to the specified HObject by comparing their OIDs.
    boolean
    equals(Object obj)
     
    final boolean
    equalsOID(long[] theID)
    Checks if the OID of the object is the same as the given object identifier within the same file.
    final long
    getFID()
    Returns the file identifier of of the file containing the object.
    final String
    getFile()
    Returns the name of the file that contains this data object.
    final FileFormat
    getFileFormat()
    Returns the file that contains the object.
    final String
    getFullName()
    Returns the full name (group path + object name) of the object.
    final String
    getLinkTargetObjName()
    Returns the name of the target object that is linked to.
    final String
    getName()
    Returns the name of the object.
    final long[]
    getOID()
    Returns a cloned copy of the object identifier.
    final String
    getPath()
    Returns the group path of the object.
    int
    hashCode()
     
    abstract long
    open()
    Opens an existing object such as a dataset or group for access.
    void
    setFullname(String thePath, String theName)
    Sets the full name of the object.
    final void
    setLinkTargetObjName(String targetObjName)
    Sets the name of the target object that is linked to.
    void
    setName(String newName)
    Sets the name of the object.
    void
    setPath(String newPath)
    Sets the path of the object.
    String
    toString()
    Returns the name of the object.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • SEPARATOR

      public static final String SEPARATOR
      The separator of object path, i.e. "/".
      See Also:

    • fileFormat

      protected final FileFormat fileFormat
      The file which contains the object

    • oid

      protected long[] oid
      Array of long integer storing unique identifier for the object. HDF4 objects are uniquely identified by a (tag_id, ref_id) pair. i.e. oid[0] = tag, oid[1] = ref_id.
      HDF5 objects are uniquely identified by a reference. i.e. oid[0...7] = H5R_ref_t.

    • linkTargetObjName

      protected String linkTargetObjName
      The name of the Target Object that is being linked to.

  • Constructor Details

    • HObject

      public HObject()
      Constructs an instance of a data object without name and path.

    • HObject

      public HObject(FileFormat theFile, String theName, String thePath)
      Constructs an instance of a data object with specific name and path. For example, in H5ScalarDS(h5file, "dset", "/arrays"), "dset" is the name of the dataset, "/arrays" is the group path of the dataset.
      Parameters:
      theFile - the file that contains the data object.
      theName - the name of the data object, e.g. "dset".
      thePath - the group path of the data object, e.g. "/arrays".

    • HObject

      @Deprecated public HObject(FileFormat theFile, String theName, String thePath, long[] oid)
      Deprecated.
      Constructs an instance of a data object with specific name and path. For example, in H5ScalarDS(h5file, "dset", "/arrays"), "dset" is the name of the dataset, "/arrays" is the group path of the dataset.
      Parameters:
      theFile - the file that contains the data object.
      theName - the name of the data object, e.g. "dset".
      thePath - the group path of the data object, e.g. "/arrays".
      oid - the ids of the data object.

  • Method Details

    • debug

      protected final void debug(Object msg)
      Print out debug information
      Parameters:
      msg - the debug message to print

    • getFile

      public final String getFile()
      Returns the name of the file that contains this data object. The file name is necessary because the file of this data object is uniquely identified when multiple files are opened by an application at the same time.
      Returns:
      The full path (path + name) of the file.

    • getName

      public final String getName()
      Returns the name of the object. For example, "Raster Image #2".
      Returns:
      The name of the object.

    • getLinkTargetObjName

      public final String getLinkTargetObjName()
      Returns the name of the target object that is linked to.
      Returns:
      The name of the object that is linked to.

    • setLinkTargetObjName

      public final void setLinkTargetObjName(String targetObjName)
      Sets the name of the target object that is linked to.
      Parameters:
      targetObjName - The new name of the object.

    • getFullName

      public final String getFullName()
      Returns the full name (group path + object name) of the object. For example, "/Images/Raster Image #2"
      Returns:
      The full name (group path + object name) of the object.

    • getPath

      public final String getPath()
      Returns the group path of the object. For example, "/Images".
      Returns:
      The group path of the object.

    • setName

      public void setName(String newName) throws Exception
      Sets the name of the object. setName (String newName) changes the name of the object in the file.
      Parameters:
      newName - The new name of the object.
      Throws:
      Exception - if name is root or contains separator

    • setPath

      public void setPath(String newPath) throws Exception
      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.
      Parameters:
      newPath - The new path of the object.
      Throws:
      Exception - if a failure occurred

    • setFullname

      public void setFullname(String thePath, String theName) throws Exception
      Sets the full name of the object.
      Parameters:
      thePath - The path of the object.
      theName - The name of the object.
      Throws:
      Exception - if a failure occurred

    • createFullname

      public String createFullname(String thePath, String theName)
      Creates the full name of the object.
      Parameters:
      thePath - The path of the object.
      theName - The name of the object.
      Returns:
      the full name of the object.

    • open

      public abstract long open()
      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.
      Returns:
      the object identifier if successful; otherwise returns a negative value.
      See Also:

    • close

      public abstract void close(long id)
      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.
      Parameters:
      id - The object identifier.

    • getFID

      public final long getFID()
      Returns the file identifier of of the file containing the object.
      Returns:
      the file identifier of of the file containing the object.

    • getFileFormat

      public final FileFormat getFileFormat()
      Returns the file that contains the object.
      Returns:
      The file that contains the object.

    • getOID

      public final long[] getOID()
      Returns a cloned copy of the object identifier. The object OID cannot be modified once it is created. getOID() clones the object OID to ensure the object OID cannot be modified outside of this class.
      Returns:
      the cloned copy of the object OID.

    • equalsOID

      public final boolean equalsOID(long[] theID)
      Checks if the OID of the object is the same as the given object identifier within the same file. HDF4 and HDF5 data objects are identified by their unique OIDs. A data object in a file may have multiple logical names , which are represented in a graph structure as separate objects. The HObject.equalsOID(long[] theID) can be used to check if two data objects with different names are pointed to the same object within the same file.
      Parameters:
      theID - The list object identifiers.
      Returns:
      true if the ID of the object equals the given OID; otherwise, returns false.

    • toString

      public String toString()
      Returns the name of the object. This method overwrites the toString() method in the Java Object class (the root class of all Java objects) so that it returns the name of the HObject instead of the name of the class. For example, toString() returns "Raster Image #2" instead of "hdf.object.h4.H4SDS".
      Overrides:
      toString in class Object
      Returns:
      The name of the object.

    • equals

      public boolean equals(HObject obj)
      Returns whether this HObject is equal to the specified HObject by comparing their OIDs.
      Parameters:
      obj - The object
      Returns:
      true if the object is equal by OID

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object