ncsa.hdf.object.h5
Class H5File

java.lang.Object
  java.io.File
      ncsa.hdf.object.FileFormat
          ncsa.hdf.object.h5.H5File

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<java.io.File>

public class H5File
extends FileFormat

H5File is an implemention of the FileFormat class for HDF5 files.

The HDF5 file structure is stored in a tree that is made up of Java TreeNode objects. Each tree node represents an HDF5 object: a Group, Dataset, or Named Datatype. Starting from the root of the tree, rootNode, the tree can be traversed to find a specific object.

The following example shows how to find an object by a given path

  HObject findObject(FileFormat file, String path)
  {
      if (file == null || path == null)
          return null;

      if (!path.endsWith("/"))
          path = path+"/";

      DefaultMutableTreeNode theRoot = 
                        (DefaultMutableTreeNode)file.getRootNode();

      if (theRoot == null)
          return null;
      else if (path.equals("/"))
          return (HObject)theRoot.getUserObject();

      Enumeration local_enum = 
            ((DefaultMutableTreeNode)theRoot).breadthFirstEnumeration();
      DefaultMutableTreeNode theNode = null;
      HObject theObj = null;
      while(local_enum.hasMoreElements())
      {
          theNode = (DefaultMutableTreeNode)local_enum.nextElement();
          theObj = (HObject)theNode.getUserObject();
          String fullPath = theObj.getFullName()+"/";
          if (path.equals(fullPath))
              break;
      }

      return theObj;
  }
 

See Also:

Serialized Form

Field Summary

static long

serialVersionUID

Fields inherited from class ncsa.hdf.object.FileFormat

CREATE, fid, FILE_CREATE_DELETE, FILE_CREATE_OPEN, FILE_TYPE_HDF4, FILE_TYPE_HDF5, fullFileName, isReadOnly, READ, WRITE

Fields inherited from class java.io.File

pathSeparator, pathSeparatorChar, separator, separatorChar

Constructor Summary

H5File()
Constructs an H5File instance with an empty file name and read-only access.

H5File(java.lang.String fileName)
Constructs an H5File instance with specified file name and read/write access.

H5File(java.lang.String fileName, int access)
Constructs an H5File instance with specified file name and access.

Method Summary

void	close() Closes file associated with this H5File instance.
javax.swing.tree.TreeNode	copy(HObject srcObj, Group dstGroup, java.lang.String dstName) Copies the source object to a new destination.
static void	copyAttributes(HObject src, HObject dst) Copies the attributes of one object to another object.
static void	copyAttributes(int src_id, int dst_id) Copies the attributes of one object to another object.
Dataset	createCompoundDS(java.lang.String name, Group pgroup, long[] dims, long[] maxdims, long[] chunks, int gzip, java.lang.String[] memberNames, Datatype[] memberDatatypes, int[] memberSizes, java.lang.Object data) Creates a new compound dataset in a file with/without chunking and compression.
Datatype	createDatatype(int tclass, int tsize, int torder, int tsign) Methods related to Datatypes and HObjects in HDF5 Files.
Datatype	createDatatype(int tclass, int tsize, int torder, int tsign, java.lang.String name) Creates a named datatype in a file.
FileFormat	createFile(java.lang.String filename, int createFlag) Creates an HDF5 file with the specified name and returns a new H5File instance associated with the file.
Group	createGroup(java.lang.String name, Group pgroup) Creates a new group with specified name in exisiting group.
Dataset	createImage(java.lang.String name, Group pgroup, Datatype type, long[] dims, long[] maxdims, long[] chunks, int gzip, int ncomp, int interlace, java.lang.Object data) Creates a new image in a file.
FileFormat	createInstance(java.lang.String filename, int access) Creates an H5File instance with specified file name and access.
HObject	createLink(Group parentGroup, java.lang.String name, HObject currentObj) Creates a link to an existing object in the open file.
Dataset	createScalarDS(java.lang.String name, Group pgroup, Datatype type, long[] dims, long[] maxdims, long[] chunks, int gzip, java.lang.Object data) Creates a new dataset in a file with/without chunking/compression.
void	delete(HObject obj) Deletes an object from a file.
HObject	get(java.lang.String path) Gets the HObject with the specified path from the file.
static java.util.List	getAttribute(int objID) Returns a list of attributes for the specified object.
java.lang.String	getLibversion() Returns the version of the HDF5 library.
javax.swing.tree.TreeNode	getRootNode() Returns the root node of the open HDF5 File.
boolean	isThisType(FileFormat theFile) Checks if the specified FileFormat instance has the HDF5 format.
boolean	isThisType(java.lang.String filename) Checks if the specified file has the HDF5 format.
int	open() Opens file and returns a file identifier.
int	open(int plist) Opens a file with specific file access property list.
static void	updateReferenceDataset(H5File srcFile, H5File dstFile) Updates values of scalar dataste object references in copied file.
void	writeAttribute(HObject obj, Attribute attr, boolean attrExisted) Attaches a given attribute to an object.

Methods inherited from class ncsa.hdf.object.FileFormat

addFileExtension, addFileFormat, copy, create, createCompoundDS, getFID, getFileExtensions, getFileFormat, getFileFormatKeys, getFileFormats, getFilePath, getHObject, getHObject, getInstance, getMaxMembers, getNumberOfMembers, getStartMembers, isReadOnly, open, removeFileFormat, setMaxMembers, setStartMembers

Methods inherited from class java.io.File

canRead, canWrite, compareTo, createNewFile, createTempFile, createTempFile, delete, deleteOnExit, equals, exists, getAbsoluteFile, getAbsolutePath, getCanonicalFile, getCanonicalPath, getName, getParent, getParentFile, getPath, hashCode, isAbsolute, isDirectory, isFile, isHidden, lastModified, length, list, list, listFiles, listFiles, listFiles, listRoots, mkdir, mkdirs, renameTo, setLastModified, setReadOnly, toString, toURI, toURL

Methods inherited from class java.lang.Object

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

Field Detail

serialVersionUID

public static final long serialVersionUID

See Also:

HObject.serialVersionUID, Constant Field Values

Constructor Detail

H5File

public H5File()

Constructs an H5File instance with an empty file name and read-only access.

H5File

public H5File(java.lang.String fileName)

Constructs an H5File instance with specified file name and read/write access.

This constructor does not open the file for access, nor does it confirm that the file can be opened read/write.

Parameters:

fileName - A valid file name, with a relative or absolute path.

Throws:

java.lang.NullPointerException - If the fileName argument is null.

H5File

public H5File(java.lang.String fileName,
              int access)

Constructs an H5File instance with specified file name and access.

The access parameter values and corresponding behaviors:

• READ: Read-only access; open() will fail file doesn't exist.
• WRITE: Read/Write access; open() will fail if file doesn't exist or if file can't be opened with read/write access.
• CREATE: Read/Write access; create a new file or truncate an existing one; open() will fail if file can't be created or if file exists but can't be opened read/write.

This constructor does not open the file for access, nor does it confirm that the file can later be opened read/write or created.

The flag returned by FileFormat.isReadOnly() is set to true if the access parameter value is READ, even though the file isn't yet open.

Parameters:

fileName - A valid file name, with a relative or absolute path.

access - The file access flag, which determines behavior when file is opened. Acceptable values are READ, WRITE, and CREATE.

Throws:

java.lang.NullPointerException - If the fileName argument is null.

Method Detail

copyAttributes

public static final void copyAttributes(HObject src,
                                        HObject dst)

Copies the attributes of one object to another object.

This method copies all the attributes from one object (source object) to another (destination object). If an attribute already exists in the destination object, the attribute will not be copied. Attribute names exceeding 256 characters will be truncated in the destination object.

The object can be an H5Group, an H5Dataset, or a named H5Datatype. This method is in the H5File class because there is no H5Object class and it is specific to HDF5 objects.

The copy can fail for a number of reasons, including an invalid source or destination object, but no exceptions are thrown. The actual copy is carried out by the method: copyAttributes(int, int)

Parameters:

src - The source object.

dst - The destination object.

See Also:

copyAttributes(int, int)

copyAttributes

public static final void copyAttributes(int src_id,
                                        int dst_id)

Copies the attributes of one object to another object.

This method copies all the attributes from one object (source object) to another (destination object). If an attribute already exists in the destination object, the attribute will not be copied. Attribute names exceeding 256 characters will be truncated in the destination object.

The object can be an H5Group, an H5Dataset, or a named H5Datatype. This method is in the H5File class because there is no H5Object class and it is specific to HDF5 objects.

The copy can fail for a number of reasons, including an invalid source or destination object identifier, but no exceptions are thrown.

Parameters:

src_id - The identifier of the source object.

dst_id - The identidier of the destination object.

getAttribute

public static final java.util.List getAttribute(int objID)
                                         throws HDF5Exception

Returns a list of attributes for the specified object.

This method returns a list containing the attributes associated with the identified object. If there are no associated attributes, an empty list will be returned.

Attribute names exceeding 256 characters will be truncated in the returned list.

Parameters:

objID - The identifier for the object whose attributes are to be returned.

Returns:

The list of the object's attributes.

Throws:

HDF5Exception - If an underlying HDF library routine is unable to perform a step necessary to retrieve the attributes. A variety of failures throw this exception.

updateReferenceDataset

public static final void updateReferenceDataset(H5File srcFile,
                                                H5File dstFile)
                                         throws java.lang.Exception

Updates values of scalar dataste object references in copied file.

This method has very specific functionality as documented below, and the user is advised to pay close attention when dealing with files that contain references.

When a copy is made from one HDF file to another, object references and dataset region references are copied, but the references in the destination file are not updated by the copy and are therefore invalid.

When an entire file is copied, this method updates the values of the object references and dataset region references that are in scalar datasets in the destination file so that they point to the correct object(s) in the destination file. The method does not update references that occur in objects other than scalar datasets.

In the current release, the updating of object references is not handled completely as it was not required by the projects that funded development. There is no support for updates when the copy does not include the entire file. Nor is there support for updating objects other than scalar datasets in full-file copies. This functionality will be extended as funding becomes available or, possibly, when the underlying HDF library supports the reference updates itself.

Parameters:

srcFile - The file that was copied.

dstFile - The destination file where the object references will be updated.

Throws:

java.lang.Exception - If there is a problem in the update process.

getLibversion

public java.lang.String getLibversion()

Returns the version of the HDF5 library.

Specified by:

getLibversion in class FileFormat

Returns:

The library version.

See Also:

FileFormat.getLibversion()

isThisType

public boolean isThisType(FileFormat theFile)

Checks if the specified FileFormat instance has the HDF5 format.

Specified by:

isThisType in class FileFormat

Parameters:

theFile - The FileFormat to be checked.

Returns:

True if this instance implements the specified FileFormat; otherwise returns false.

See Also:

FileFormat.isThisType(ncsa.hdf.object.FileFormat)

isThisType

public boolean isThisType(java.lang.String filename)

Checks if the specified file has the HDF5 format.

Specified by:

isThisType in class FileFormat

Parameters:

filename - The name of the file to be checked.

Returns:

True if the format of the file matches the format of this instance; otherwise returns false.

See Also:

FileFormat.isThisType(java.lang.String)

createFile

public FileFormat createFile(java.lang.String filename,
                             int createFlag)
                      throws java.lang.Exception

Creates an HDF5 file with the specified name and returns a new H5File instance associated with the file.

Overrides:

createFile in class FileFormat

Parameters:

filename - The filename; a pathname string.

createFlag - The creation flag, which determines behavior when the file already exists. Acceptable values are FILE_CREATE_DELETE and FILE_CREATE_OPEN.

Throws:

HDF5Exception - If the file cannot be created or if createFlag has unexpected value.

java.lang.NullPointerException - If the filename argument is null.

java.lang.UnsupportedOperationException - If the implementing class does not support the file creation operation.

java.lang.Exception - If the file cannot be created or if the creation flag has an unexpected value. The exceptions thrown vary depending on the implementing class.

See Also:

FileFormat.createFile(java.lang.String, int), H5File(String, int)

createInstance

public FileFormat createInstance(java.lang.String filename,
                                 int access)
                          throws java.lang.Exception

Creates an H5File instance with specified file name and access.

Specified by:

createInstance in class FileFormat

Parameters:

filename - The filename; a pathname string.

access - The file access flag, which determines behavior when file is opened. Acceptable values are READ, WRITE, and CREATE.

Throws:

java.lang.NullPointerException - If the filename argument is null.

java.lang.Exception - If the instance cannot be created or if the access flag has an unexpected value. The exceptions thrown vary depending on the implementing class.

See Also:

FileFormat.createInstance(java.lang.String, int), H5File(String, int)

open

public int open()
         throws java.lang.Exception

Opens file and returns a file identifier.

Specified by:

open in class FileFormat

Returns:

File identifier if successful; otherwise -1.

Throws:

java.lang.Exception - If the file cannot be opened. The exceptions thrown vary depending on the implementing class.

See Also:

FileFormat.open()

close

public void close()
           throws HDF5Exception

Closes file associated with this H5File instance.

Specified by:

close in class FileFormat

Throws:

HDF5Exception

See Also:

FileFormat.close()

getRootNode

public javax.swing.tree.TreeNode getRootNode()

Returns the root node of the open HDF5 File.

Specified by:

getRootNode in class FileFormat

Returns:

The root node of the file, or null there is no associated file or if the associated file has not yet been opened.

See Also:

FileFormat.getRootNode()

get

public HObject get(java.lang.String path)
            throws java.lang.Exception

Description copied from class: FileFormat

Gets the HObject with the specified path from the file.

This method returns the specified object from the file associated with this FileFormat instance.

If the specified object is a group, groups and datasets that are members of the group will be accessible via the returned HObject instance. The exact contents of the returned HObject instance depends on whether or not FileFormat.open() was called previously for this file.

• If the file was opened prior to this method call, the complete tree of objects under the group will be accessible via the returned HObject instance.
• If the file was not opened prior to this method call, only the members immediately under the group will be accessible via the returned HOBject instance.

The decision to have different behaviors was made to give users some control over the "cost" of the method. In many cases, a user wants only one level of a tree, and the performance penalty for loading the entire hierarchy of objects in a large and complex file can be significant. In the case where open() has already been called, the HObject instances have already been created in memory and can be returned quickly. If open() has not been called, this method creates the HObject instances before returning the requested HObject.

For example, say we have the following structure in our file:

        /g0                      Group
        /g0/dataset_comp         Dataset {50, 10}
        /g0/dataset_int          Dataset {50, 10}
        /g0/g00                  Group
        /g0/g00/dataset_float    Dataset {50, 10}
        /g0/g01                  Group
        /g0/g01/dataset_string   Dataset {50, 10}
 

• If open() is called before get(), the full structure of file is loaded into memory. The call get("/g0") returns the instance for /g0 with the information necessary to access /g0/dataset_comp, /g0/dataset_int, /g0/g00, /g0/g00/dataset_float, /g0/g01, and /g0/g01/dataset_string.
• If open() is not called before get(), only the objects immediately under the specified group are accessible via the returned HObject instance. In this example, the call get("/go") returns the instance for /g0 with the information necessary to access /g0/dataset_comp, /g0/dataset_int, /g0/g00, and /g0/g01.

Specified by:

get in class FileFormat

Parameters:

path - Full path of the data object to be returned.

Returns:

The object if it exists in the file; otherwise null.

Throws:

java.lang.Exception - If there are unexpected problems in trying to retrieve the object. The exceptions thrown vary depending on the implementing class.

createDatatype

public Datatype createDatatype(int tclass,
                               int tsize,
                               int torder,
                               int tsign,
                               java.lang.String name)
                        throws java.lang.Exception

Description copied from class: FileFormat

Creates a named datatype in a file.

The following code creates a named datatype in a file.

 H5File file = (H5File)h5file.createInstance("test_hdf5.h5",FileFormat.WRITE);
 H5Datatype dtype = file.createDatatype(Datatype.CLASS_INTEGER,
     4, Datatype.NATIVE, Datatype.NATIVE, "Native Integer");
 

Specified by:

createDatatype in class FileFormat

Parameters:

tclass - class of datatype, e.g. Datatype.CLASS_INTEGER

tsize - size of the datatype in bytes, e.g. 4 for 32-bit integer.

torder - order of the byte endianing, Datatype.ORDER_LE.

tsign - signed or unsinged of an integer, Datatype.SIGN_NONE.

name - name of the datatype to create, e.g. "Native Integer".

Returns:

The new datatype if successful; otherwise returns null.

Throws:

java.lang.Exception - The exceptions thrown vary depending on the implementing class.

createDatatype

public Datatype createDatatype(int tclass,
                               int tsize,
                               int torder,
                               int tsign)
                        throws java.lang.Exception

Methods related to Datatypes and HObjects in HDF5 Files. Strictly speaking, these methods aren't related to H5File and the actions coudl be carried out through the H5Group, H5Datatype and H5*DS classes. But, in some cases they allow a null input and expect the generated object to be of HDF5 type. So, we put them in the H5File class so that we create the proper type of HObject... H5Group for example. Here again, if there could be Implementation Class methods we'd use those. But, since we can't override class methods (they can only be shadowed in Java), these are instance methods.

Specified by:

createDatatype in class FileFormat

Parameters:

tclass - class of datatype, e.g. Datatype.CLASS_INTEGER

tsize - size of the datatype in bytes, e.g. 4 for 32-bit integer.

torder - order of the byte endian, e.g. Datatype.ORDER_LE.

tsign - signed or unsinged of an integer, Datatype.SIGN_NONE.

Returns:

The new datatype object if successful; otherwise returns null.

Throws:

java.lang.Exception - The exceptions thrown vary depending on the implementing class.

createScalarDS

public Dataset createScalarDS(java.lang.String name,
                              Group pgroup,
                              Datatype type,
                              long[] dims,
                              long[] maxdims,
                              long[] chunks,
                              int gzip,
                              java.lang.Object data)
                       throws java.lang.Exception

Description copied from class: FileFormat

Creates a new dataset in a file with/without chunking/compression.

The following example creates a 2D integer dataset of size 100X50 at the root group in an HDF5 file.

 String name = "2D integer";
 Group pgroup = 
             (Group)((DefaultMutableTreeNode)getRootNode).getUserObject();
 Datatype dtype = new H5Datatype(
                           Datatype.CLASS_INTEGER, // class
                           4,                      // size in bytes
                           Datatype.ORDER_LE,      // byte order
                           Datatype.SIGN_NONE);    // signed or unsigned
 long[] dims = {100, 50};
 long[] maxdims = dims;
 long[] chunks = null; // no chunking
 int gzip = 0; // no compression
 Object data = null; // no initial data values

 Dataset d = (H5File)file.createScalarDS(name, pgroup, dtype, dims,
                                         maxdims, chunks, gzip, data);
 

Specified by:

createScalarDS in class FileFormat

Parameters:

name - name of the new dataset, e.g. "2D integer"

pgroup - parent group where the new dataset is created.

type - datatype of the new dataset.

dims - dimension sizes of the new dataset, e.g. long[] dims = {100, 50}.

maxdims - maximum dimension sizes of the new dataset, null if maxdims is the same as dims.

chunks - chunk sizes of the new dataset, null if no chunking.

gzip - GZIP compression level (1 to 9), 0 or negative values if no compression.

data - data written to the new dataset, null if no data is written to the new dataset.

Returns:

The new dataset if successful; otherwise returns null

Throws:

java.lang.Exception - The exceptions thrown vary depending on the implementing class.

createCompoundDS

public Dataset createCompoundDS(java.lang.String name,
                                Group pgroup,
                                long[] dims,
                                long[] maxdims,
                                long[] chunks,
                                int gzip,
                                java.lang.String[] memberNames,
                                Datatype[] memberDatatypes,
                                int[] memberSizes,
                                java.lang.Object data)
                         throws java.lang.Exception

Description copied from class: FileFormat

Creates a new compound dataset in a file with/without chunking and compression.

The following example creates a compressed 2D compound dataset with size of 100X50 in a root group. The compound dataset has two members, x and y. Member x is an interger, member y is an 1-D float array of size 10.

 String name = "2D compound";
 Group pgroup = 
           (Group)((DefaultMutableTreeNode)getRootNode).getUserObject();
 long[] dims = {100, 50};
 long[] chunks = {1, 50};
 int gzip = 9;
 String[] memberNames = {"x", "y"};
 
 Datatype[] memberDatatypes = {
     new H5Datatype(Datatype.CLASS_INTEGER, Datatype.NATIVE, 
                    Datatype.NATIVE, Datatype.NATIVE)
     new H5Datatype(Datatype.CLASS_FLOAT, Datatype.NATIVE, 
                    Datatype.NATIVE, Datatype.NATIVE));
     
 int[] memberSizes = {1, 10};
 Object data = null; // no initial data values

 Dataset d = (H5File)file.createCompoundDS(name, pgroup, dims, null, 
           chunks, gzip, memberNames, memberDatatypes, memberSizes, null);
 

Overrides:

createCompoundDS in class FileFormat

Parameters:

name - name of the new dataset

pgroup - parent group where the new dataset is created.

dims - dimension sizes of the new dataset.

maxdims - maximum dimension sizes of the new dataset, null if maxdims is the same as dims.

chunks - chunk sizes of the new dataset, null if no chunking.

gzip - GZIP compression level (1 to 9), 0 or negative values if no compression.

memberNames - names of the members.

memberDatatypes - datatypes of the members.

memberSizes - array sizes of the members.

data - data written to the new dataset, null if no data is written to the new dataset.

Returns:

new dataset object if successful; otherwise returns null

Throws:

java.lang.UnsupportedOperationException - If the implementing class does not support compound datasets.

java.lang.Exception - The exceptions thrown vary depending on the implementing class.

createImage

public Dataset createImage(java.lang.String name,
                           Group pgroup,
                           Datatype type,
                           long[] dims,
                           long[] maxdims,
                           long[] chunks,
                           int gzip,
                           int ncomp,
                           int interlace,
                           java.lang.Object data)
                    throws java.lang.Exception

Description copied from class: FileFormat

Creates a new image in a file.

The following example creates a 2D image of size 100X50 in a root group.

 String name = "2D image";
 Group pgroup = 
          (Group)((DefaultMutableTreeNode)getRootNode).getUserObject();
 Datatype dtype = new H5Datatype(Datatype.CLASS_INTEGER, 1, 
          Datatype.NATIVE, Datatype.SIGN_NONE);
 long[] dims = {100, 50};
 long[] maxdims = dims;
 long[] chunks = null; // no chunking
 int gzip = 0; // no compression
 int ncomp = 3; // RGB true color image
 int interlace = ScalarDS.INTERLACE_PIXEL;
 Object data = null; // no initial data values

 Dataset d = (H5File)file.createScalarDS(name, pgroup, dtype, dims,
     maxdims, chunks, gzip, ncomp, interlace, data);
 

Specified by:

createImage in class FileFormat

Parameters:

name - name of the new image, "2D image".

pgroup - parent group where the new image is created.

type - datatype of the new image.

dims - dimension sizes of the new dataset, e.g. long[] dims = {100, 50}.

maxdims - maximum dimension sizes of the new dataset, null if maxdims is the same as dims.

chunks - chunk sizes of the new dataset, null if no chunking.

gzip - GZIP compression level (1 to 9), 0 or negative values if no compression.

ncomp - number of components of the new image, e.g. int ncomp = 3; // RGB true color image.

interlace - interlace mode of the image. Valid values are ScalarDS.INTERLACE_PIXEL, ScalarDS.INTERLACE_PLANEL and ScalarDS.INTERLACE_LINE.

data - data value of the image, null if no data.

Returns:

The new image object if successful; otherwise returns null

Throws:

java.lang.Exception - The exceptions thrown vary depending on the implementing class.

createGroup

public Group createGroup(java.lang.String name,
                         Group pgroup)
                  throws java.lang.Exception

Creates a new group with specified name in exisiting group.

Specified by:

createGroup in class FileFormat

Parameters:

name - The name of the new group.

pgroup - The parent group, or null.

Returns:

The new group if successful; otherwise returns null.

Throws:

java.lang.Exception - The exceptions thrown vary depending on the implementing class.

See Also:

FileFormat.createGroup(java.lang.String, ncsa.hdf.object.Group)

createLink

public HObject createLink(Group parentGroup,
                          java.lang.String name,
                          HObject currentObj)
                   throws java.lang.Exception

Description copied from class: FileFormat

Creates a link to an existing object in the open file.

If linkGroup is null, the new link is created in the root group.

Specified by:

createLink in class FileFormat

Parameters:

parentGroup - The group where the link is created.

name - The name of the link.

currentObj - The existing object the new link will reference.

Returns:

The object pointed to by the new link if successful; otherwise returns null.

Throws:

java.lang.Exception - The exceptions thrown vary depending on the implementing class.

copy

public javax.swing.tree.TreeNode copy(HObject srcObj,
                                      Group dstGroup,
                                      java.lang.String dstName)
                               throws java.lang.Exception

Description copied from class: FileFormat

Copies the source object to a new destination.

This method copies the source object to a destination group, and assigns the specified name to the new object.

The copy may take place within a single or across files. If the source object and destination group are in different files, the files must have the same file format (both HDF5 for example).

The source object can be a group, a dataset, or a named datatype. This method copies the object along with all of its attributes and other properties. If the source object is a group, this method also copies all objects and sub-groups below the group.

The following example shows how to use the copy method to create two copies of an existing HDF5 file structure in a new HDF5 file. One copy will be under /copy1 and the other under /copy2 in the new file.

 // Open the exisiting file with the source object.
 H5File existingFile = new H5File( "existingFile.h5", FileFormat.READ );
 existingFile.open();

 // Our source object will be the root group. 
 HObject srcObj = existingFile.get("/");

 // Create a new file.
 H5File newFile = new H5File( "newFile.h5", FileFormat.CREATE );
 newFile.open();

 // Both copies in the new file will have the root group as their
 // destination group.
 Group dstGroup = (Group)newFile.get( "/" );

 // First copy goes to "/copy1" and second goes to "/copy2".
 // Notice that we can use either H5File instance to perform the copy.
 TreeNode copy1 = existingFile.copy( srcObj, dstGroup, "copy1" );
 TreeNode copy2 = newFile.copy( srcObj, dstGroup, "copy2" );

 // Close both the files.
 file.close();
 newFile.close();
 

Specified by:

copy in class FileFormat

Parameters:

srcObj - The object to copy.

dstGroup - The destination group for the new object.

dstName - The name of the new object. If dstName is null, the name of srcObj will be used.

Returns:

The tree node that contains the new object, or null if the copy fails.

Throws:

java.lang.Exception

delete

public void delete(HObject obj)
            throws java.lang.Exception

Description copied from class: FileFormat

Deletes an object from a file.

Specified by:

delete in class FileFormat

Parameters:

obj - The object to delete.

Throws:

java.lang.Exception - The exceptions thrown vary depending on the implementing class.

writeAttribute

public void writeAttribute(HObject obj,
                           Attribute attr,
                           boolean attrExisted)
                    throws HDF5Exception

Description copied from class: FileFormat

Attaches a given attribute to an object.

If the attribute does not exists, creates an attibute in file, and attches it the object. If the attribute already exists in the object, just update the value of the attribute attached to the object.

Specified by:

writeAttribute in class FileFormat

Parameters:

obj - The object to which the attribute is attached to.

attr - The atribute to attach.

attrExisted - The indicator if the given attribute exists.

Throws:

HDF5Exception

open

public int open(int plist)
         throws java.lang.Exception

Opens a file with specific file access property list.

This function does the same as "int open()" except the you can also pass an HDF5 file access property to file open. For example,

  //All open objects remaining in the file are closed then file is closed
  int plist = H5.H5Pcreate (HDF5Constants.H5P_FILE_ACCESS);
  H5.H5Pset_fclose_degree ( plist, HDF5Constants.H5F_CLOSE_STRONG);
  int fid = open(plist);
  

Parameters:

plist - a file access property list identifier.

Returns:

the file identifier if successful; otherwise returns negative value.

Throws:

java.lang.Exception