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

# Class H5File

Object
File
hdf.object.FileFormat
hdf.object.h5.H5File

All Implemented Interfaces:
  `Serializable`, `Comparable<File>`

public class H5File extends FileFormat
H5File is an implementation of the FileFormat class for HDF5 files. The HDF5 file structure is made up of HObjects stored in a tree-like fashion. Each tree node represents an HDF5 object: a Group, Dataset, or Named Datatype. Starting from the root of the tree, rootObject, the tree can be traversed to find a specific object. The following example shows the implementation of finding an object for a given path in FileFormat. User applications can directly call the static method FileFormat.findObject(file, objPath) to get the object.

     HObject findObject(FileFormat file, String path) {
         if (file == null || path == null)
             return null;
         if (!path.endsWith("/"))
             path = path + "/";
         HObject theRoot = file.getRootObject();
         if (theRoot == null)
             return null;
         else if (path.equals("/"))
             return theRoot;

         Iterator local_it = ((Group) theRoot)
                 .breadthFirstMemberList().iterator();
         HObject theObj = null;
         while (local_it.hasNext()) {
             theObj = local_it.next();
             String fullPath = theObj.getFullName() + "/";
             if (path.equals(fullPath) &&  theObj.getPath() != null ) {
                 break;
         }
         return theObj;
     }

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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `H5File.IO_TYPE`
  Enum to indicate the type of I/O to perform inside of the common I/O function.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `LIBVER_EARLIEST`
  The library earliest version value
  `static final int`
  `LIBVER_LATEST`
  The library latest version value
  `static final int`
  `LIBVER_V110`
  The library v1.10 version value
  `static final int`
  `LIBVER_V112`
  The library v1.12 version value
  `static final int`
  `LIBVER_V114`
  The library v1.14 version value
  `static final int`
  `LIBVER_V18`
  The library v1.8 version value
  `static final int`
  `SWMR`
  Indicate that this file is open for reading in a single-writer/multi-reader (SWMR) scenario.

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

  `CREATE, fid, FILE_CREATE_DELETE, FILE_CREATE_EARLY_LIB, FILE_CREATE_OPEN, FILE_OBJ_SEP, FILE_TYPE_HDF4, FILE_TYPE_HDF5, FILE_TYPE_NC3, fullFileName, isReadOnly, MULTIREAD, OPEN_NEW, READ, WRITE`

  ### Fields inherited from class java.io.File

  `pathSeparator, pathSeparatorChar, separator, separatorChar`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `H5File()`
  Constructs an H5File instance with an empty file name and read-only access.
  `H5File(String fileName)`
  Constructs an H5File instance with specified file name and read/write access.
  `H5File(String fileName, int access)`
  Constructs an H5File instance with specified file name and access.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Closes file associated with this H5File instance.
  `HObject`
  `copy(HObject srcObj, Group dstGroup, String dstName)`
  Copies the source object to a new destination.
  `static final void`
  `copyAttributes(long src_id, long dst_id)`
  Copies the attributes of one object to another object.
  `static final void`
  `copyAttributes(HObject src, HObject dst)`
  Copies the attributes of one object to another object.
  `Dataset`
  `createCompoundDS(String name, Group pgroup, long[] dims, long[] maxdims, long[] chunks, int gzip, String[] memberNames, Datatype[] memberDatatypes, int[] memberSizes, 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, Datatype tbase)`
  Creates a new datatype in memory.
  `FileFormat`
  `createFile(String filename, int createFlag)`
  Creates an HDF5 file with the specified name and returns a new H5File instance associated with the file.
  `long`
  `createGcpl(int creationorder, int maxcompact, int mindense)`
  Creates the group creation property list identifier, gcpl.
  `Group`
  `createGroup(String name, Group pgroup)`
  Creates a new group with specified name in existing group.
  `Group`
  `createGroup(String name, Group pgroup, long... gplist)`
  Creates a new group with specified name in existing group and with the group creation properties list, gplist.
  `Dataset`
  `createImage(String name, Group pgroup, Datatype type, long[] dims, long[] maxdims, long[] chunks, int gzip, int ncomp, int interlace, Object data)`
  Creates a new image in a file.
  `FileFormat`
  `createInstance(String filename, int access)`
  Creates an H5File instance with specified file name and access.
  `HObject`
  `createLink(Group parentGroup, String name, HObject currentObj, int lType)`
  Creates a link to an object in the open file.
  `HObject`
  `createLink(Group parentGroup, String name, Object currentObj)`
  Creates a link to an existing object in the open file.
  `HObject`
  `createLink(Group parentGroup, String name, String currentObj, int lType)`
  Creates a soft or external link to object in a file that does not exist at the time the link is created.
  `Datatype`
  `createNamedDatatype(Datatype tnative, String name)`
  Creates a named datatype in a file.
  `Dataset`
  `createScalarDS(String name, Group pgroup, Datatype type, long[] dims, long[] maxdims, long[] chunks, int gzip, Object fillValue, Object data)`
  Creates a new dataset in a file with/without chunking/compression.
  `void`
  `delete(HObject obj)`
  Deletes an object from a file.
  `void`
  `exportDataset(String file_export_name, Dataset object, int binary_order)`
  Export dataset.
  `HObject`
  `get(String path)`
  Gets the HObject with the specified path from the file.
  `static final List<Attribute>`
  `getAttribute(HObject obj)`
  Returns a list of attributes for the specified object.
  `static final List<Attribute>`
  `getAttribute(HObject obj, int idx_type, int order)`
  Returns a list of attributes for the specified object, in creation or alphabetical order.
  `int`
  `getIndexOrder()`
  `int`
  `getIndexOrder(String strorder)`
  `static int`
  `getIndexOrderValue(String strorder)`
  `int`
  `getIndexType()`
  `int`
  `getIndexType(String strtype)`
  `static int`
  `getIndexTypeValue(String strtype)`
  `int[]`
  `getLibBounds()`
  Gets the bounds of library versions.
  `String`
  `getLibBoundsDescription()`
  Gets the bounds of library versions as text.
  `String`
  `getLibversion()`
  Returns the version of the HDF5 library.
  `static String`
  `getLinkTargetName(HObject obj)`
  Retrieves the name of the target object that is being linked to.
  `HObject`
  `getRootObject()`
  Returns the root object of the open HDF5 File.
  `void`
  `initLibBounds()`
  Initialize the bounds of library versions
  `boolean`
  `isThisType(FileFormat theFile)`
  Checks if the specified FileFormat instance has the HDF5 format.
  `boolean`
  `isThisType(String filename)`
  Checks if the specified file has the HDF5 format.
  `long`
  `open()`
  Opens file and returns a file identifier.
  `long`
  `open(int... indexList)`
  Opens file and returns a file identifier.
  `long`
  `open(long plist)`
  Opens a file with specific file access property list.
  `void`
  `reloadTree(Group g)`
  reload the sub-tree structure from file.
  `void`
  `renameAttribute(HObject obj, String oldAttrName, String newAttrName)`
  Renames an attribute.
  `static void`
  `renameObject(HObject obj, String newName)`
  Rename the given object
  `static void`
  `renameObject(HObject obj, String newPath, String newName)`
  Rename the given object
  `void`
  `setIndexOrder(int indexOrder)`
  set the int value of the index order.
  `void`
  `setIndexType(int indexType)`
  set the int value of the index type.
  `void`
  `setLibBounds(String lowStr, String highStr)`
  Sets the bounds of library versions.
  `void`
  `setNewLibBounds(String lowStr, String highStr)`
  Sets the bounds of new library versions.
  `static final void`
  `updateReferenceDataset(H5File srcFile, H5File dstFile)`
  Updates values of scalar dataset object references in copied file.
  `void`
  `writeAttribute(HObject obj, Attribute attr, boolean attrExisted)`
  Attaches a given attribute to an object.

  ### Methods inherited from class hdf.object.FileFormat

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

  ### Methods inherited from class java.io.File

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

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### LIBVER_LATEST

    public static final int LIBVER_LATEST
    The library latest version value

  - ### LIBVER_EARLIEST

    public static final int LIBVER_EARLIEST
    The library earliest version value

  - ### LIBVER_V18

    public static final int LIBVER_V18
    The library v1.8 version value

  - ### LIBVER_V110

    public static final int LIBVER_V110
    The library v1.10 version value

  - ### LIBVER_V112

    public static final int LIBVER_V112
    The library v1.12 version value

  - ### LIBVER_V114

    public static final int LIBVER_V114
    The library v1.14 version value

  - ### SWMR

    public static final int SWMR
    Indicate that this file is open for reading in a single-writer/multi-reader (SWMR) scenario. Note that the process(es) opening the file for SWMR reading must also open the file with the #H5F_ACC_RDONLY flag.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### H5File

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

  - ### H5File

    public H5File(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:
      `NullPointerException` - If the `fileName` argument is `null`.

  - ### H5File

    public H5File(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.
    - SWMR: 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:
      `NullPointerException` - If the `fileName` argument is `null`.

- ## Method Details

  - ### 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(long, long)`
    Parameters:
      `src` - The source object.
      `dst` - The destination object.
    See Also:
      - `copyAttributes(long, long)`

  - ### copyAttributes

    public static final void copyAttributes(long src_id, long 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 identifier of the destination object.

  - ### getAttribute

    public static final List<Attribute> getAttribute(HObject obj) throws hdf.hdf5lib.exceptions.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:
      `obj` - The HObject whose attributes are to be returned.
    Returns:
      The list of the object's attributes.
    Throws:
      `hdf.hdf5lib.exceptions.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.
    See Also:
      - `getAttribute(HObject,int,int)`

  - ### getAttribute

    public static final List<Attribute> getAttribute(HObject obj, int idx_type, int order) throws hdf.hdf5lib.exceptions.HDF5Exception
    Returns a list of attributes for the specified object, in creation or alphabetical order. 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. The list of attributes returned can be in increasing or decreasing, creation or alphabetical order. Attribute names exceeding 256 characters will be truncated in the returned list.
    Parameters:
      `obj` - The HObject whose attributes are to be returned.
      `idx_type` - The type of index. Valid values are:
      - H5_INDEX_NAME: An alpha-numeric index by attribute name
      - H5_INDEX_CRT_ORDER: An index by creation order
      `order` - The index traversal order. Valid values are:
      - H5_ITER_INC: A top-down iteration incrementing the index position at each step.
      - H5_ITER_DEC: A bottom-up iteration decrementing the index position at each step.
    Returns:
      The list of the object's attributes.
    Throws:
      `hdf.hdf5lib.exceptions.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 Exception
    Updates values of scalar dataset 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:
      `Exception` - If there is a problem in the update process.

  - ### getLibversion

    public 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(hdf.object.FileFormat)`

  - ### isThisType

    public boolean isThisType(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(String filename, int createFlag) throws 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`.
    Returns:
      the FileFormat instance.
    Throws:
      `Exception` - If the file cannot be created or if createFlag has unexpected value.
    See Also:
      - `FileFormat.createFile(java.lang.String, int)`
      - `H5File(String, int)`

  - ### createInstance

    public FileFormat createInstance(String filename, int access) throws 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`.
    Returns:
      the FileFormat instance.
    Throws:
      `Exception` - If there is a failure.
    See Also:
      - `FileFormat.createInstance(java.lang.String, int)`
      - `H5File(String, int)`

  - ### open

    public long open() throws Exception
    Opens file and returns a file identifier.
    Specified by:
      `open` in class `FileFormat`
    Returns:
      File identifier if successful; otherwise -1.
    Throws:
      `Exception` - If the file cannot be opened. The exceptions thrown vary depending on the implementing class.
    See Also:
      - `FileFormat.open()`

  - ### open

    public long open(int... indexList) throws Exception
    Opens file and returns a file identifier.
    Overrides:
      `open` in class `FileFormat`
    Parameters:
      `indexList` - The property list is the list of parameters, like index type and the index order. The index type can be alphabetical or creation. The index order can be increasing order or decreasing order.
    Returns:
      File identifier if successful; otherwise -1.
    Throws:
      `Exception` - The exceptions thrown vary depending on the implementing class.
    See Also:
      - `FileFormat.open(int...)`

  - ### setNewLibBounds

    public void setNewLibBounds(String lowStr, String highStr) throws Exception
    Sets the bounds of new library versions.
    Overrides:
      `setNewLibBounds` in class `FileFormat`
    Parameters:
      `lowStr` - The earliest version of the library.
      `highStr` - The latest version of the library.
    Throws:
      `Exception` - If there is an error at the HDF5 library level.

  - ### setLibBounds

    public void setLibBounds(String lowStr, String highStr) throws Exception
    Sets the bounds of library versions.
    Overrides:
      `setLibBounds` in class `FileFormat`
    Parameters:
      `lowStr` - The earliest version of the library.
      `highStr` - The latest version of the library.
    Throws:
      `Exception` - If there is an error at the HDF5 library level.

  - ### getLibBounds

    public int[] getLibBounds() throws Exception
    Gets the bounds of library versions.
    Overrides:
      `getLibBounds` in class `FileFormat`
    Returns:
      libver The earliest and latest version of the library.
    Throws:
      `Exception` - If there is an error at the HDF5 library level.

  - ### initLibBounds

    public void initLibBounds() throws Exception
    Initialize the bounds of library versions
    Overrides:
      `initLibBounds` in class `FileFormat`
    Throws:
      `Exception` - The exceptions thrown vary depending on the implementing class.

  - ### getLibBoundsDescription

    public String getLibBoundsDescription()
    Gets the bounds of library versions as text.
    Overrides:
      `getLibBoundsDescription` in class `FileFormat`
    Returns:
      libversion The earliest and latest version of the library.

  - ### close

    public void close() throws hdf.hdf5lib.exceptions.HDF5Exception
    Closes file associated with this H5File instance.
    Specified by:
      `close` in class `FileFormat`
    Throws:
      `hdf.hdf5lib.exceptions.HDF5Exception` - If there is an error at the HDF5 library level.
    See Also:
      - `FileFormat.close()`

  - ### getRootObject

    public HObject getRootObject()
    Returns the root object of the open HDF5 File.
    Specified by:
      `getRootObject` in class `FileFormat`
    Returns:
      The root object of the file, or `null` if there is no associated file or if the associated file has not yet been opened.
    See Also:
      - `FileFormat.getRootObject()`

  - ### get

    public HObject get(String path) throws 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:
      `Exception` - If there are unexpected problems in trying to retrieve the object. The exceptions thrown vary depending on the implementing class.

  - ### createNamedDatatype

    public Datatype createNamedDatatype(Datatype tnative, String name) throws Exception
    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);
         Datatype dtype = file.createDatatype(
                                     Datatype.CLASS_INTEGER,
                                     4,
                                     Datatype.NATIVE,
                                     Datatype.NATIVE,
                                     basetype);
         H5Datatype h5dtype = file.createNamedDatatype(
                                     dtype,
                                     null,
                                     "Native Integer");

    Overrides:
      `createNamedDatatype` in class `FileFormat`
    Parameters:
      `tnative` - native datatype previously created
      `name` - name of the datatype to create, e.g. "Native Integer".
    Returns:
      The new datatype if successful; otherwise returns null.
    Throws:
      `Exception` - The exceptions thrown vary depending on the implementing class.

  - ### createDatatype

    public Datatype createDatatype(int tclass, int tsize, int torder, int tsign) throws Exception
    Methods related to Datatypes and HObjects in HDF5 Files. Strictly speaking, these methods aren't related to H5File and the actions could 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 unsigned of an integer, e.g. Datatype.SIGN_NONE.
    Returns:
      The new datatype object if successful; otherwise returns null.
    Throws:
      `Exception` - The exceptions thrown vary depending on the implementing class.

  - ### createDatatype

    public Datatype createDatatype(int tclass, int tsize, int torder, int tsign, Datatype tbase) throws Exception
    Description copied from class: `FileFormat`
    Creates a new datatype in memory. The following code creates an instance of H5Datatype in memory.

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

    Overrides:
      `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 unsigned of an integer, e.g. Datatype.SIGN_NONE.
      `tbase` - the base datatype of the new datatype
    Returns:
      The new datatype object if successful; otherwise returns null.
    Throws:
      `Exception` - The exceptions thrown vary depending on the implementing class.

  - ### createScalarDS

    public Dataset createScalarDS(String name, Group pgroup, Datatype type, long[] dims, long[] maxdims, long[] chunks, int gzip, Object fillValue, Object data) throws 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) getRootObject();
         Datatype dtype = new H5Datatype(Datatype.CLASS_INTEGER, // class
                 4, // size in bytes
                 Datatype.ORDER_LE, // byte order
                 Datatype.SIGN_NONE); // 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.
      `fillValue` - default value.
      `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:
      `Exception` - The exceptions thrown vary depending on the implementing class.

  - ### createCompoundDS

    public Dataset createCompoundDS(String name, Group pgroup, long[] dims, long[] maxdims, long[] chunks, int gzip, String[] memberNames, Datatype[] memberDatatypes, int[] memberSizes, Object data) throws 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) getRootObject();
         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:
      `Exception` - The exceptions thrown vary depending on the implementing class.

  - ### createImage

    public Dataset createImage(String name, Group pgroup, Datatype type, long[] dims, long[] maxdims, long[] chunks, int gzip, int ncomp, int interlace, Object data) throws 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) getRootObject();
         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:
      `Exception` - The exceptions thrown vary depending on the implementing class.

  - ### createGroup

    public Group createGroup(String name, Group pgroup) throws Exception
    Creates a new group with specified name in existing 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:
      `Exception` - The exceptions thrown vary depending on the implementing class.
    See Also:
      - `FileFormat.createGroup(java.lang.String, hdf.object.Group)`

  - ### createGroup

    public Group createGroup(String name, Group pgroup, long... gplist) throws Exception
    Creates a new group with specified name in existing group and with the group creation properties list, gplist.
    Overrides:
      `createGroup` in class `FileFormat`
    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` - The exceptions thrown vary depending on the implementing class.
    See Also:
      - `H5Group.create(java.lang.String, hdf.object.Group, long...)`

  - ### createGcpl

    public long createGcpl(int creationorder, int maxcompact, int mindense) throws Exception
    Creates the group creation property list identifier, gcpl. This identifier is used when creating Groups.
    Overrides:
      `createGcpl` in class `FileFormat`
    Parameters:
      `creationorder` - The order in which the objects in a group should be created. It can be Tracked or Indexed.
      `maxcompact` - The maximum number of links to store in the group in a compact format.
      `mindense` - The minimum number of links to store in the indexed format.Groups which are in indexed format and in which the number of links falls below this threshold are automatically converted to compact format.
    Returns:
      The gcpl identifier.
    Throws:
      `Exception` - The exceptions thrown vary depending on the implementing class.
    See Also:
      - `FileFormat.createGcpl(int, int, int)`

  - ### createLink

    public HObject createLink(Group parentGroup, String name, Object currentObj) throws 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.
    Overrides:
      `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:
      `Exception` - The exceptions thrown vary depending on the implementing class.

  - ### createLink

    public HObject createLink(Group parentGroup, String name, HObject currentObj, int lType) throws Exception
    Creates a link to an object in the open file. If parentGroup is null, the new link is created in the root group.
    Overrides:
      `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.
      `lType` - The type of link to be created. It can be a hard link, a soft link or an external link.
    Returns:
      The object pointed to by the new link if successful; otherwise returns null.
    Throws:
      `Exception` - The exceptions thrown vary depending on the implementing class.

  - ### createLink

    public HObject createLink(Group parentGroup, String name, String currentObj, int lType) throws Exception
    Creates a soft or external link to object in a file that does not exist at the time the link is created.
    Overrides:
      `createLink` in class `FileFormat`
    Parameters:
      `parentGroup` - The group where the link is created.
      `name` - The name of the link.
      `currentObj` - The name of the object the new link will reference. The object doesn't have to exist.
      `lType` - The type of link to be created.
    Returns:
      The H5Link object pointed to by the new link if successful; otherwise returns null.
    Throws:
      `Exception` - The exceptions thrown vary depending on the implementing class.

  - ### reloadTree

    public void reloadTree(Group g)
    reload the sub-tree structure from file. reloadTree(Group g) is useful when the structure of the group in file is changed while the group structure in memory is not changed.
    Parameters:
      `g` - the group where the structure is to be reloaded in memory

  - ### copy

    public HObject copy(HObject srcObj, Group dstGroup, String dstName) throws 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 file 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 existing 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.
         HObject copy1 = existingFile.copy(srcObj, dstGroup, "copy1");
         HObject 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 new object, or null if the copy fails.
    Throws:
      `Exception` - are specific to the implementing class.

  - ### delete

    public void delete(HObject obj) throws 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:
      `Exception` - The exceptions thrown vary depending on the implementing class.

  - ### writeAttribute

    public void writeAttribute(HObject obj, Attribute attr, boolean attrExisted) throws hdf.hdf5lib.exceptions.HDF5Exception
    Description copied from class: `FileFormat`
    Attaches a given attribute to an object. If an HDF(4&5) attribute exists in file, the method updates its value. If the attribute does not exist in file, it creates the attribute in 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 file, one needs to get the instance of the attribute by getMetadata(), change its values, and use writeAttribute() to write the value.
    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:
      `hdf.hdf5lib.exceptions.HDF5Exception`

  - ### open

    public long open(long plist) throws Exception
    Opens a file with specific file access property list. This function does the same as "long 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
         long plist = H5.H5Pcreate(HDF5Constants.H5P_FILE_ACCESS);
         H5.H5Pset_fclose_degree(plist, HDF5Constants.H5F_CLOSE_STRONG);
         long fid = open(plist);

    Parameters:
      `plist` - a file access property list identifier.
    Returns:
      the file identifier if successful; otherwise returns negative value.
    Throws:
      `Exception` - If there is a failure.

  - ### getLinkTargetName

    public static String getLinkTargetName(HObject obj) throws Exception
    Retrieves the name of the target object that is being linked to.
    Parameters:
      `obj` - The current link object.
    Returns:
      The name of the target object.
    Throws:
      `Exception` - If there is an error at the HDF5 library level.

  - ### exportDataset

    public void exportDataset(String file_export_name, Dataset object, int binary_order) throws Exception
    Export dataset.
    Overrides:
      `exportDataset` in class `FileFormat`
    Parameters:
      `file_export_name` - The file name to export data into.
      `object` - The id of the HDF5 dataset.
      `binary_order` - The data byte order
    Throws:
      `Exception` - If there is a failure.

  - ### renameAttribute

    public void renameAttribute(HObject obj, String oldAttrName, String newAttrName) throws Exception
    Renames an attribute.
    Overrides:
      `renameAttribute` in class `FileFormat`
    Parameters:
      `obj` - The object whose attribute is to be renamed.
      `oldAttrName` - The current name of the attribute.
      `newAttrName` - The new name of the attribute.
    Throws:
      `Exception` - If there is an error at the HDF5 library level.

  - ### renameObject

    public static void renameObject(HObject obj, String newName) throws Exception
    Rename the given object
    Parameters:
      `obj` - the object to be renamed.
      `newName` - the new name of the object.
    Throws:
      `Exception` - If there is a failure.

  - ### renameObject

    public static void renameObject(HObject obj, String newPath, String newName) throws Exception
    Rename the given object
    Parameters:
      `obj` - the object to be renamed.
      `newPath` - the new path of the object.
      `newName` - the new name of the object.
    Throws:
      `Exception` - If there is a failure.

  - ### getIndexTypeValue

    public static int getIndexTypeValue(String strtype)
    Parameters:
      `strtype` - The name of the index type.
    Returns:
      the int value of the index type value.

  - ### getIndexOrderValue

    public static int getIndexOrderValue(String strorder)
    Parameters:
      `strorder` - The name of the index order.
    Returns:
      the int value of the index order.

  - ### getIndexType

    public int getIndexType(String strtype)
    Overrides:
      `getIndexType` in class `FileFormat`
    Parameters:
      `strtype` - The name of the index type.
    Returns:
      the int value of the index type.

  - ### getIndexType

    public int getIndexType()
    Returns:
      the current value of the index type.

  - ### setIndexType

    public void setIndexType(int indexType)
    Description copied from class: `FileFormat`
    set the int value of the index type.
    Overrides:
      `setIndexType` in class `FileFormat`
    Parameters:
      `indexType` - The value of the index type.

  - ### getIndexOrder

    public int getIndexOrder(String strorder)
    Overrides:
      `getIndexOrder` in class `FileFormat`
    Parameters:
      `strorder` - The name of the index order.
    Returns:
      the int value of the index order.

  - ### getIndexOrder

    public int getIndexOrder()
    Returns:
      the current value of the index order.

  - ### setIndexOrder

    public void setIndexOrder(int indexOrder)
    Description copied from class: `FileFormat`
    set the int value of the index order.
    Overrides:
      `setIndexOrder` in class `FileFormat`
    Parameters:
      `indexOrder` - The index order.