ncsa.hdf.object.h4
Class H4File

java.lang.Object
  java.io.File
      ncsa.hdf.object.FileFormat
          ncsa.hdf.object.h4.H4File

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<java.io.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

static long

serialVersionUID

Fields inherited from class ncsa.hdf.object.FileFormat

CREATE, FILE_CREATE_DELETE, FILE_CREATE_OPEN, FILE_OBJ_SEP, FILE_TYPE_HDF4, FILE_TYPE_HDF5, READ, WRITE

Fields inherited from class java.io.File

pathSeparator, pathSeparatorChar, separator, separatorChar

Constructor Summary

H4File()
Creates an H4File with read only access.

H4File(java.lang.String pathname)
Creates an H4File with read only access.

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

Method Summary

void	close() Closes file associated with this instance.
javax.swing.tree.TreeNode	copy(HObject srcObj, Group dstGroup, java.lang.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, java.lang.String name) Creates a named datatype in a file.
FileFormat	createFile(java.lang.String filename, int createFlag) Creates an HDF4 file with the specified name and returns a new H4File instance associated with the file.
Group	createGroup(java.lang.String name, Group pgroup) Creates a new group with specified name in existing group.
Dataset	createImage(java.lang.String name, Group pgroup, Datatype type, long[] dims, long[] maxdims, long[] chunks, int gzip, int ncomp, int interlace, java.lang.Object data) Creates a new image in a file.
FileFormat	createInstance(java.lang.String filename, int access) Creates an H4File instance with specified file name and access.
Dataset	createScalarDS(java.lang.String name, Group pgroup, Datatype type, long[] dims, long[] maxdims, long[] chunks, int gzip, java.lang.Object data) Creates a new dataset in a file with/without chunking/compression.
void	delete(HObject obj) Delete an object from the file.
HObject	get(java.lang.String path) Get an individual HObject with a given path.
java.lang.String	getLibversion() Returns the version of the HDF4 library.
javax.swing.tree.TreeNode	getRootNode() Returns the root node for the file associated with this instance.
boolean	isThisType(FileFormat fileformat) Checks if the given file format is an HDF4 file.
boolean	isThisType(java.lang.String filename) Checks if the given file is an HDF4 file or netCDF.
int	open() Opens file and returns a file identifier.
void	writeAttribute(HObject obj, Attribute attr, boolean isSDglobalAttr) Creates a new attribute and attached to the object if attribute does not exist.

Methods inherited from class ncsa.hdf.object.FileFormat

addFileExtension, addFileFormat, copy, create, createCompoundDS, createCompoundDS, createGcpl, createGroup, createLink, createLink, createLink, findObject, findObject, getFID, getFileExtensions, getFileFormat, getFileFormatKeys, getFileFormats, getFilePath, getHObject, getHObject, getInstance, getLibBounds, getMaxMembers, getNumberOfMembers, getStartMembers, isReadOnly, open, open, removeFileFormat, renameAttribute, setLibBounds, 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, toString, toURI, toURL

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

serialVersionUID

public static final long serialVersionUID

See Also:

Constant Field Values

Constructor Detail

H4File

public H4File()

Creates an H4File with read only access.

H4File

public H4File(java.lang.String pathname)

Creates an H4File with read only access.

H4File

public H4File(java.lang.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 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:

java.lang.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(java.lang.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(java.lang.String filename,
                             int createFlag)
                      throws java.lang.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.

Throws:

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

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

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

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

See Also:

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

createInstance

public FileFormat createInstance(java.lang.String filename,
                                 int access)
                          throws java.lang.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.

Throws:

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

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

See Also:

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

open

public int open()
         throws java.lang.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 node.

Specified by:

open in class FileFormat

Returns:

File identifier if successful; otherwise -1.

Throws:

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

See Also:

FileFormat.createFile(String, int), FileFormat.createInstance(String, int), FileFormat.getInstance(String), FileFormat.getRootNode()

close

public void close()
           throws 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:

HDFException

See Also:

FileFormat.open()

getRootNode

public javax.swing.tree.TreeNode getRootNode()

Description copied from class: FileFormat

Returns the root node for the file associated with this instance.

The root node is a Java TreeNode object (javax.swing.tree.DefaultMutableTreeNode) 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 nodes represent non-empty groups. Leaf nodes represent datasets, named datatypes, or empty groups.

Specified by:

getRootNode in class FileFormat

Returns:

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

See Also:

FileFormat.open()

createGroup

public Group createGroup(java.lang.String name,
                         Group pgroup)
                  throws java.lang.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:

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

createDatatype

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

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, Datatype.SIGN_NONE.

Returns:

The new datatype object if successful; otherwise returns null.

Throws:

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

createDatatype

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

Description copied from class: FileFormat

Creates a named datatype in a file.

The following code creates a named datatype in a file.

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

Specified by:

createDatatype in class FileFormat

Parameters:

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

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

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

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

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

Returns:

The new datatype if successful; otherwise returns null.

Throws:

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

createScalarDS

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

Description copied from class: FileFormat

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

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

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

Specified by:

createScalarDS in class FileFormat

Parameters:

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

pgroup - parent group where the new dataset is created.

type - datatype of the new dataset.

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

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

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

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

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

Returns:

The new dataset if successful; otherwise returns null

Throws:

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

createImage

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

Description copied from class: FileFormat

Creates a new image in a file.

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

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

Specified by:

createImage in class FileFormat

Parameters:

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

pgroup - parent group where the new image is created.

type - datatype of the new image.

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

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

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

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

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

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

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

Returns:

The new image object if successful; otherwise returns null

Throws:

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

delete

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

Delete an object from the file.

Specified by:

delete in class FileFormat

Parameters:

obj - the data object to delete.

Throws:

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

copy

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

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 new node containing the new object.

Throws:

java.lang.Exception

writeAttribute

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

Creates a new attribute and attached to the object if 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:

HDFException

getLibversion

public java.lang.String getLibversion()

Returns the version of the HDF4 library.

Specified by:

getLibversion in class FileFormat

Returns:

The library version.

get

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

Get an individual HObject with a given path. It deoes not load the whole file structure.

Specified by:

get in class FileFormat

Parameters:

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

Returns:

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

Throws:

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