hdf.object.h4

## Class H4File

- Object
- - File
  - - hdf.object.FileFormat
    - - hdf.object.h4.H4File

- All Implemented Interfaces:
    Serializable, Comparable<File>

      public class H4File
      extends FileFormat

  This class provides file level APIs. File access APIs include retrieving the file hierarchy, opening and closing file, and writing file content to disk.
  Version:
    2.4 9/4/2007
  Author:
    Peter X. Cao
  See Also:
    Serialized Form

- - ### Field Summary

    - ### 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, fullFileName, isReadOnly, OPEN_NEW, READ, WRITE`

    - ### Fields inherited from class File

      `pathSeparator, pathSeparatorChar, separator, separatorChar`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `H4File()` Creates an H4File with read only access.
    `H4File(String pathname)` Creates an H4File with read only access.
    `H4File(String fileName, int access)` Creates an H4File instance with specified file name and access.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes file associated with this instance.
    `HObject` | `copy(HObject srcObj, Group dstGroup, String dstName)` Copy an object to a group.
    `Datatype` | `createDatatype(int tclass, int tsize, int torder, int tsign)` Creates a new datatype in memory.
    `Datatype` | `createDatatype(int tclass, int tsize, int torder, int tsign, Datatype tbase)` Creates a new datatype in memory.
    `Datatype` | `createDatatype(int tclass, int tsize, int torder, int tsign, Datatype tbase, String name)` Creates a named datatype in a file.
    `Datatype` | `createDatatype(int tclass, int tsize, int torder, int tsign, String name)` Creates a named datatype in a file.
    `FileFormat` | `createFile(String filename, int createFlag)` Creates an HDF4 file with the specified name and returns a new H4File instance associated with the file.
    `Group` | `createGroup(String name, Group pgroup)` Creates a new group with specified name in existing group.
    `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 H4File instance with specified file name and access.
    `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)` Delete an object from the file.
    `HObject` | `get(String path)` Get an individual HObject with a given path.
    `(package private) long` | `getGRAccessID()` Returns the GR identifier, which is returned from GRstart(fid).
    `String` | `getLibversion()` Returns the version of the HDF4 library.
    `HObject` | `getRootObject()` Returns the root object for the file associated with this instance.
    `(package private) long` | `getSDAccessID()` Returns the SDS identifier, which is returned from SDstart(fname, flag).
    `boolean` | `isThisType(FileFormat fileformat)` Checks if the given file format is an HDF4 file.
    `boolean` | `isThisType(String filename)` Checks if the given file is an HDF4 file or netCDF.
    `long` | `open()` Opens file and returns a file identifier.
    `void` | `setNewLibBounds(String lowStr, String highStr)` Sets the bounds of new library versions.
    `void` | `writeAttribute(HObject obj, Attribute attr, boolean isSDglobalAttr)` Creates a new attribute and attaches it to the object if the attribute does not exist.

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

      `addFileExtension, addFileFormat, copy, create, createCompoundDS, createCompoundDS, createGcpl, createGroup, createLink, createLink, createLink, createScalarDS, exportDataset, findObject, findObject, getFID, getFileExtensions, getFileFormat, getFileFormatKeys, getFileFormats, getFilePath, getHObject, getHObject, getIndexOrder, getIndexOrderValue, getIndexType, getIndexTypeValue, getInstance, getLibBounds, getLibBoundsDescription, getMaxMembers, getNumberOfMembers, getStartMembers, isReadOnly, open, open, removeFileFormat, renameAttribute, setIndexOrder, setIndexType, setLibBounds, setMaxMembers, setStartMembers`

    - ### Methods inherited from class 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 Object

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

- - ### Constructor Detail

    - #### H4File

          public H4File()

      Creates an H4File with read only access.

    - #### H4File

          public H4File(String pathname)

      Creates an H4File with read only access.
      Parameters:
        `pathname` - The file path string.

    - #### H4File

          public H4File(String fileName,
                        int access)

      Creates an H4File instance with specified file name and access.

      The access parameter values and corresponding behaviors:

      - READ: Read-only access; open() will fail if file doesn't exist.
      - WRITE: Read/Write access; if file doesn't exist, open() will create it; open() will fail if read/write access not allowed.
      - 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 Detail

    - #### isThisType

          public boolean isThisType(FileFormat fileformat)

      Checks if the given file format is an HDF4 file.
      Specified by:
        `isThisType` in class `FileFormat`
      Parameters:
        `fileformat` - the fileformat to be checked.
      Returns:
        true if the given file is an HDF4 file; otherwise returns false.
      See Also:
        `FileFormat.isThisType(String)`

    - #### isThisType

          public boolean isThisType(String filename)

      Checks if the given file is an HDF4 file or netCDF. HDF4 library supports netCDF version 2.3.2. It only supports SDS APIs.
      Specified by:
        `isThisType` in class `FileFormat`
      Parameters:
        `filename` - the file to be checked.
      Returns:
        true if the given file is an HDF4 file; otherwise returns false.
      See Also:
        `FileFormat.isThisType(FileFormat)`

    - #### createFile

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

      Creates an HDF4 file with the specified name and returns a new H4File 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:
        `hdf.hdflib.HDFException` - If the file cannot be created or if createFlag has unexpected value.
        `NullPointerException` - If the `filename` argument is `null`.
        `UnsupportedOperationException` - If the implementing class does not support the file creation operation.
        `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)`, `H4File(String, int)`

    - #### createInstance

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

      Creates an H4File 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:
        `NullPointerException` - If the `filename` argument is `null`.
        `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)`, `H4File(String, int)`

    - #### open

          public long open()
                    throws Exception

      Description copied from class: `FileFormat`
      Opens file and returns a file identifier.

      This method uses the `filename` and `access` parameters specified in the createFile(), createInstance(), or getInstance() call to open the file. It returns the file identifier if successful, or a negative value in case of failure.

      The method also loads the file structure and basic information (name, type) for data objects in the file into the FileFormat instance. It does not load the contents of any data object.

      The structure of the file is stored in a tree starting from the root object.

      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.createFile(String, int)`, `FileFormat.createInstance(String, int)`, `FileFormat.getInstance(String)`, `FileFormat.getRootObject()`

    - #### close

          public void close()
                     throws hdf.hdflib.HDFException

      Description copied from class: `FileFormat`
      Closes file associated with this instance.

      This method closes the file associated with this FileFormat instance, as well as all objects associated with the file.

      Specified by:
        `close` in class `FileFormat`
      Throws:
        `hdf.hdflib.HDFException`
      See Also:
        `FileFormat.open()`

    - #### getRootObject

          public HObject getRootObject()

      Description copied from class: `FileFormat`
      Returns the root object for the file associated with this instance.

      The root object is an HObject that represents the root group of a file. If the file has not yet been opened, or if there is no file associated with this instance, `null` will be returned.

      Starting from the root, applications can descend through the tree structure and navigate among the file's objects. In the tree structure, internal items represent non-empty groups. Leaf items represent datasets, named datatypes, or empty groups.

      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.open()`

    - #### createGroup

          public Group createGroup(String name,
                                   Group pgroup)
                            throws Exception

      Description copied from class: `FileFormat`
      Creates a new group with specified name in existing group.

      If the parent group is null, the new group will be created in the root 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.

    - #### createDatatype

          public Datatype createDatatype(int tclass,
                                         int tsize,
                                         int torder,
                                         int tsign)
                                  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);

      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.

    - #### createDatatype

          public Datatype createDatatype(int tclass,
                                         int tsize,
                                         int torder,
                                         int tsign,
                                         String name)
                                  throws 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, e.g. Datatype.ORDER_LE.
        `tsign` - signed or unsigned of an integer, e.g. Datatype.SIGN_NONE.
        `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,
                                         Datatype tbase,
                                         String name)
                                  throws 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,
                                       basetype,
                                       "Native Integer");

      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 endianing, 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
        `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.

    - #### 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); // 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.
        `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.

    - #### 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.

    - #### delete

          public void delete(HObject obj)
                      throws Exception

      Delete an object from the file.
      Specified by:
        `delete` in class `FileFormat`
      Parameters:
        `obj` - the data object to delete.
      Throws:
        `Exception` - if the object can not be deleted

    - #### copy

          public HObject copy(HObject srcObj,
                              Group dstGroup,
                              String dstName)
                       throws Exception

      Copy an object to a group.
      Specified by:
        `copy` in class `FileFormat`
      Parameters:
        `srcObj` - the object to copy.
        `dstGroup` - the destination group.
        `dstName` - The name of the new object. If dstName is null, the name of srcObj will be used.
      Returns:
        the destination group, if the copy was successful, or null otherwise.
      Throws:
        `Exception` - if the object can not be copied

    - #### writeAttribute

          public void writeAttribute(HObject obj,
                                     Attribute attr,
                                     boolean isSDglobalAttr)
                              throws hdf.hdflib.HDFException

      Creates a new attribute and attaches it to the object if the attribute does not exist. Otherwise, just update the value of the attribute.
      Specified by:
        `writeAttribute` in class `FileFormat`
      Parameters:
        `obj` - the object which the attribute is to be attached to.
        `attr` - the attribute to attach.
        `isSDglobalAttr` - The indicator if the given attribute exists.
      Throws:
        `hdf.hdflib.HDFException` - if the attribute can not be written

    - #### getGRAccessID

          long getGRAccessID()

      Returns the GR identifier, which is returned from GRstart(fid).
      Returns:
        the identifier.

    - #### getSDAccessID

          long getSDAccessID()

      Returns the SDS identifier, which is returned from SDstart(fname, flag).
      Returns:
        the identifier.

    - #### getLibversion

          public String getLibversion()

      Returns the version of the HDF4 library.
      Specified by:
        `getLibversion` in class `FileFormat`
      Returns:
        The library version.

    - #### get

          public HObject get(String path)
                      throws Exception

      Get an individual HObject with a given path. It does not load the whole file structure.
      Specified by:
        `get` in class `FileFormat`
      Parameters:
        `path` - the path of the object
      Returns:
        The object if it exists in the file; otherwise `null`.
      Throws:
        `Exception` - if the object cannot be found

    - #### setNewLibBounds

          public void setNewLibBounds(String lowStr,
                                      String highStr)
                               throws Exception

      Description copied from class: `FileFormat`
      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` - The exceptions thrown vary depending on the implementing class.

Copyright © 2018. All Rights Reserved.