Module org.hdfgroup.object
Package hdf.object.nc2

# Class NC2File

Object
File
hdf.object.FileFormat
hdf.object.nc2.NC2File

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

public class NC2File 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, 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
  `NC2File()`
  Constructs an empty NC2File with read-only access.
  `NC2File(String fileName)`
  Creates an NC2File object of given file name with read-only access.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Closes file associated with this instance.
  `static NC2Attribute`
  `convertAttribute(HObject parent, ucar.nc2.Attribute netcdfAttr)`
  converts a ucar.nc2.Attribute into an hdf.object.nc2.NC2Attribute
  `HObject`
  `copy(HObject srcObj, Group dstGroup, String dstName)`
  Copies the source object to a new destination.
  `void`
  `copyAttributes(int srcID, int dstID)`
  Copies the attributes of one object to another object.
  `void`
  `copyAttributes(HObject src, HObject dst)`
  Copies the attributes of one object to another object.
  `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.
  `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 intelace, Object data)`
  Creates a new image in a file.
  `FileFormat`
  `createInstance(String filename, int access)`
  Creates a NC2File instance with specified file name and READ access.
  `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.
  `HObject`
  `get(String path)`
  Gets the HObject with the specified path from the file.
  `String`
  `getLibversion()`
  Returns the version of the library.
  `ucar.nc2.NetcdfFile`
  `getNetcdfFile()`
  `HObject`
  `getRootObject()`
  Returns the root object for the file associated with this instance.
  `boolean`
  `isThisType(FileFormat fileformat)`
  Checks if the given file format is a NetCDF3 file.
  `boolean`
  `isThisType(String filename)`
  Checks if the given file is a NetCDF file.
  `long`
  `open()`
  Opens file and returns a file identifier.
  `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, createCompoundDS, createFile, 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, initLibBounds, isReadOnly, open, open, removeFileFormat, renameAttribute, setIndexOrder, setIndexType, setLibBounds, setMaxMembers, setNewLibBounds, 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`

- ## Constructor Details

  - ### NC2File

    public NC2File()
    Constructs an empty NC2File with read-only access.

  - ### NC2File

    public NC2File(String fileName)
    Creates an NC2File object of given file name with read-only access.
    Parameters:
      `fileName` - A valid file name, with a relative or absolute path.

- ## Method Details

  - ### isThisType

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

  - ### isThisType

    public boolean isThisType(String filename)
    Checks if the given file is a NetCDF file.
    Specified by:
      `isThisType` in class `FileFormat`
    Parameters:
      `filename` - the file to be checked.
    Returns:
      true if the given file is a NetCDF file; otherwise returns false.
    See Also:
      - `FileFormat.isThisType(FileFormat)`

  - ### createInstance

    public FileFormat createInstance(String filename, int access) throws Exception
    Creates a NC2File instance with specified file name and READ access. Regardless of specified access, the NC2File implementation uses READ.
    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)`

  - ### 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 IOException
    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:
      `IOException`
    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()`

  - ### getNetcdfFile

    public ucar.nc2.NetcdfFile getNetcdfFile()
    Returns:
      the NetCDF file.

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

  - ### createNamedDatatype

    public Datatype createNamedDatatype(Datatype tnative, 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.createNamedDatatype(
                                     nativetype,
                                     "Native Integer");

    Overrides:
      `createNamedDatatype` in class `FileFormat`
    Parameters:
      `tnative` - the native 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); // 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 intelace, 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.
      `intelace` - 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
    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.

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

  - ### writeAttribute

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

  - ### copyAttributes

    public void copyAttributes(HObject src, HObject dst)
    Copies the attributes of one object to another object. NC3 does not support attribute copy
    Parameters:
      `src` - The source object.
      `dst` - The destination object.

  - ### copyAttributes

    public void copyAttributes(int srcID, int dstID)
    Copies the attributes of one object to another object. NC3 does not support attribute copy
    Parameters:
      `srcID` - The source identifier.
      `dstID` - The destination identifier.

  - ### convertAttribute

    public static NC2Attribute convertAttribute(HObject parent, ucar.nc2.Attribute netcdfAttr)
    converts a ucar.nc2.Attribute into an hdf.object.nc2.NC2Attribute
    Parameters:
      `parent` - the parent object.
      `netcdfAttr` - the ucar.nc2.Attribute object.
    Returns:
      the hdf.object.nc2.NC2Attribute if successful

  - ### getLibversion

    public String getLibversion()
    Returns the version of the library.
    Specified by:
      `getLibversion` in class `FileFormat`
    Returns:
      The library version.

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