ncsa.hdf.object
Class HObject

java.lang.Object
  ncsa.hdf.object.HObject

All Implemented Interfaces:

java.io.Serializable, DataFormat

Direct Known Subclasses:

Dataset, Datatype, Group, H5Link

public abstract class HObject
extends java.lang.Object
implements java.io.Serializable, DataFormat

The HObject class is the root class of all the HDF data objects. Every data class has HObject as a superclass. All objects (Groups and Datasets) 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 H4SclarDS 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 pathes. 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 of the (ref_id, tag_id) pair. The ref_id is the object reference count. 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 or object reference. The OID is usually obtained by H5Rcreate(). The following example shows how to retrieve an object ID from a file.

 // retrieve the object ID 
 try {
     byte[] ref_buf = H5.H5Rcreate(h5file.getFID(), this.getFullName(),
             HDF5Constants.H5R_OBJECT, -1);
     long[] oid = new long[1];
     oid[0] = HDFNativeData.byteToLong(ref_buf, 0);
 }
 catch (Exception ex) {
 }
 

Version:

1.1 9/4/2007

Author:

Peter X. Cao

See Also:

ncsa.hdf.object.DataFormat, Serialized Form

Field Summary

static java.lang.String	separator The separator of object path, i.e.
static long	serialVersionUID The serialVersionUID is a universal version identifier for a Serializable class.

Constructor Summary

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

HObject(FileFormat theFile, java.lang.String theName, java.lang.String thePath)
Constructs an instance of a data object with specific name and path.

HObject(FileFormat theFile, java.lang.String theName, java.lang.String thePath, long[] oid)
Deprecated. Not for public use in the future.
Using HObject(FileFormat, String, String)

Method Summary

abstract void	close(int id) Closes access to the object.
boolean	equalsOID(long[] theID) Checks if the OID of the object is the same as the given object identifier within the same file.
int	getFID() Returns the file identifier of of the file containing the object.
java.lang.String	getFile() Returns the name of the file that contains this data object.
FileFormat	getFileFormat() Returns the file that contains the object.
java.lang.String	getFullName() Returns the full name (group path + object name) of the object.
java.lang.String	getLinkTargetObjName() Returns the name of the target object that is linked to.
java.lang.String	getName() Returns the name of the object.
long[]	getOID() Returns a cloned copy of the object identifier.
java.lang.String	getPath() Returns the group path of the object.
abstract int	open() Opens an existing object such as dataset or group for access.
void	setLinkTargetObjName(java.lang.String targetObjName) Sets the name of the target object that is linked to.
void	setName(java.lang.String newName) Sets the name of the object.
void	setPath(java.lang.String newPath) Sets the path of the object.
java.lang.String	toString() Returns the name of the object.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ncsa.hdf.object.DataFormat

getMetadata, hasAttribute, removeMetadata, writeMetadata

Field Detail

serialVersionUID

public static final long serialVersionUID

The serialVersionUID is a universal version identifier for a Serializable class. Deserialization uses this number to ensure that a loaded class corresponds exactly to a serialized object. For details, see http://java.sun.com/j2se/1.5.0/docs/api/java/io/Serializable.html

See Also:

Constant Field Values

separator

public static final java.lang.String separator

The separator of object path, i.e. "/".

See Also:

Constant Field Values

Constructor Detail

HObject

public HObject()

Constructs an instance of a data object without name and path.

HObject

public HObject(FileFormat theFile,
               java.lang.String theName,
               java.lang.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,
                          java.lang.String theName,
                          java.lang.String thePath,
                          long[] oid)

Deprecated. Not for public use in the future.
Using HObject(FileFormat, String, String)

Method Detail

getFile

public final java.lang.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.

Specified by:

getFile in interface DataFormat

Returns:

The full path (path + name) of the file.

getName

public final java.lang.String getName()

Returns the name of the object. For example, "Raster Image #2".

Returns:

The name of the object.

getLinkTargetObjName

public final java.lang.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(java.lang.String targetObjName)

Sets the name of the target object that is linked to.

getFullName

public final java.lang.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 java.lang.String getPath()

Returns the group path of the object. For example, "/Images".

Returns:

The group path of the object.

setName

public void setName(java.lang.String newName)
             throws java.lang.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:

java.lang.Exception

setPath

public void setPath(java.lang.String newPath)
             throws java.lang.Exception

Sets the path of the object.

setPath() is needed to change the path for an object when the name of a group conatining 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:

java.lang.Exception

open

public abstract int open()

Opens an existing object such as 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(int src_id, int dst_id) and other purposes. The open() function should be used in pair with close(int) function.

Returns:

the object identifier if successful; otherwise returns a negative value.

See Also:

close(int)

close

public abstract void close(int 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 ncsa.hdf.hdf5lib.H5.H5Gclose() method and closes the group resource specified by the group id.

Parameters:

id - The object identifier.

getFID

public final int getFID()

Returns the file identifier of of the file containing the object.

Returns:

the file identifier of of the file containing the object.

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.

Returns:

true if the ID of the object equals the given OID; otherwise, returns false.

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. getIOD() clones the object OID to ensure the object OID cannot be modified outside of this class.

Returns:

the cloned copy of the object OID.

toString

public java.lang.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 "ncsa.hdf.object.h4.H4SDS".

Overrides:

toString in class java.lang.Object

Returns:

The name of the object.