ncsa.hdf.object.h4
Class H4File

java.lang.Object
  extended byjava.io.File
      extended byncsa.hdf.object.FileFormat
          extended byncsa.hdf.object.h4.H4File
All Implemented Interfaces:
java.lang.Comparable, java.io.Serializable

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.

See Also:
Serialized Form

Field Summary
 
Fields inherited from class ncsa.hdf.object.FileFormat
CREATE, fid, FILE_TYPE_HDF4, FILE_TYPE_HDF5, FILE_TYPE_JPEG, FILE_TYPE_PNG, FILE_TYPE_TIFF, 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 pathname, int access)
          Creates an H4File with specific full file name and access flag.
 
Method Summary
 void close()
          Closes access to the file resource.
 javax.swing.tree.TreeNode copy(HObject srcObj, Group dstGroup)
          Copy an object to a group.
 FileFormat create(java.lang.String fileName)
          Creates a new HDF4 file.
 Dataset createCompoundDS(java.lang.String name, Group pgroup, long[] dims, java.lang.String[] memberNames, Datatype[] memberDatatypes, int[] memberSizes, java.lang.Object data)
          Create a new compound dataset in this file.
 Datatype createDatatype(int tclass, int tsize, int torder, int tsign)
          Create a new datatype based on this FileFormat.
 Group createGroup(java.lang.String name, Group pgroup)
          Create a new group with given group name and a parent in this file.
 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)
          Create a new image at given parent group in this file.
 Dataset createScalarDS(java.lang.String name, Group pgroup, Datatype type, long[] dims, long[] maxdims, long[] chunks, int gzip, java.lang.Object data)
          Create a new dataset in this file.
 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 getFilePath()
          Returns the full path of the file: file path + file name.
 java.lang.String getLibversion()
          Returns the version of the HDF4 library.
 javax.swing.tree.TreeNode getRootNode()
          Returns the root node of the file.
 boolean isReadOnly()
          Returns the true if the file is read-only, otherwise returns false.
 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 access to the file resource and returns the file identifier.
 FileFormat open(java.lang.String pathname, int access)
          Open a file and returns an instance of implementing class of the FileFormat.
 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, createDatatype, createLink, getFID, getFileExtensions, getFileFormat, getFileFormatKeys, getFileFormats, getHObject, getHObject, getInstance, getMaxMembers, getStartMembers, setMaxMembers, setStartMembers
 
Methods inherited from class java.io.File
canRead, canWrite, compareTo, compareTo, createNewFile, createTempFile, createTempFile, delete, deleteOnExit, equals, exists, getAbsoluteFile, getAbsolutePath, getCanonicalFile, getCanonicalPath, getName, getParent, getParentFile, getPath, hashCode, isAbsolute, isDirectory, isFile, isHidden, lastModified, length, list, list, listFiles, listFiles, listFiles, listRoots, mkdir, mkdirs, renameTo, setLastModified, setReadOnly, toString, toURI, toURL
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

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 pathname,
              int access)
Creates an H4File with specific full file name and access flag.

Parameters:
pathname - the full path of the file name.
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.

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.

open

public FileFormat open(java.lang.String pathname,
                       int access)
                throws java.lang.Exception
Description copied from class: FileFormat
Open a file and returns an instance of implementing class of the FileFormat.

Specified by:
open in class FileFormat
Parameters:
pathname - the full path name of the file.
Throws:
java.lang.Exception

open

public int open()
         throws java.lang.Exception
Description copied from class: FileFormat
Opens access to the file resource and returns the file identifier. If the file is already open, it returns the file access identifier.

Specified by:
open in class FileFormat
Returns:
the file access identifier if opening the file is succsessful; otherwise returns a negative value.
Throws:
java.lang.Exception

close

public void close()
           throws HDFException
Description copied from class: FileFormat
Closes access to the file resource.

Specified by:
close in class FileFormat
Throws:
HDFException

getRootNode

public javax.swing.tree.TreeNode getRootNode()
Description copied from class: FileFormat
Returns the root node of the file. The root node contains the hierarchy of the file. For file with hierarchical structure such HDF, the structure is stored as a tree. The root of the tree is the root the the file.

Specified by:
getRootNode in class FileFormat

getFilePath

public java.lang.String getFilePath()
Description copied from class: FileFormat
Returns the full path of the file: file path + file name.

Specified by:
getFilePath in class FileFormat

isReadOnly

public boolean isReadOnly()
Description copied from class: FileFormat
Returns the true if the file is read-only, otherwise returns false.

Specified by:
isReadOnly in class FileFormat

create

public FileFormat create(java.lang.String fileName)
                  throws java.lang.Exception
Creates a new HDF4 file.

Specified by:
create in class FileFormat
Parameters:
fileName - the name of the file to create.
Throws:
java.lang.Exception

createGroup

public Group createGroup(java.lang.String name,
                         Group pgroup)
                  throws java.lang.Exception
Description copied from class: FileFormat
Create a new group with given group name and a parent in this file.

Specified by:
createGroup in class FileFormat
Parameters:
name - the name fo the new group.
pgroup - the parent group.
Throws:
java.lang.Exception

createDatatype

public Datatype createDatatype(int tclass,
                               int tsize,
                               int torder,
                               int tsign)
                        throws java.lang.Exception
Description copied from class: FileFormat
Create a new datatype based on this FileFormat.

For example, the following code creates an instance of H5Datatype.

 FileFormat file = FileFormat.getFileFormat(FileFormat.FILE_TYPE_HDF5);
 H5Datatype dtype = file.createDatatype(Datatype.CLASS_INTEGER,
     Datatype.NATIVE, Datatype.NATIVE, Datatype.NATIVE);
 

Specified by:
createDatatype in class FileFormat
Parameters:
tclass - the class of datatype, such as Integer, Float
tsize - the size of the datatype in bytes
Throws:
java.lang.Exception

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
Create a new dataset in this file. For example, to create a 2D integer dataset of size 100X50 at the root in an HDF5 file.
 String name = "2D integer";
 Group pgroup = (Group)((DefaultMutableTreeNode)getRootNode).getUserObject();
 Datatype dtype = new H5Datatype(Datatype.CLASS_INTEGER, Datatype.NATIVE,
     Datatype.NATIVE, Datatype.NATIVE);
 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 - the name of the new dataset
pgroup - the parent group where the new dataset is created.
type - the datatype of the new dataset.
dims - dimension sizes of the new dataset.
maxdims - the maximum dimension sizes of the new dataset.
chunks - the chunk sizes of the new dataset.
gzip - the compression level.
data - the data of the new dataset.
Throws:
java.lang.Exception

createCompoundDS

public Dataset createCompoundDS(java.lang.String name,
                                Group pgroup,
                                long[] dims,
                                java.lang.String[] memberNames,
                                Datatype[] memberDatatypes,
                                int[] memberSizes,
                                java.lang.Object data)
                         throws java.lang.Exception
Description copied from class: FileFormat
Create a new compound dataset in this file. For example, to create a 2D compound dataset with size of 100X50 and member x and y at the root in an HDF5 file.
 String name = "2D compound";
 Group pgroup = (Group)((DefaultMutableTreeNode)getRootNode).getUserObject();
 long[] dims = {100, 50};
 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, memberNames, memberDatatypes, memberSizes, null);
 

Overrides:
createCompoundDS in class FileFormat
Parameters:
name - the name of the new dataset
pgroup - the parent group where the new dataset is created.
dims - dimension sizes of the new dataset.
memberNames - the names of the members.
memberDatatypes - the datatypes of the members.
memberSizes - the array size of the member.
data - the data of the new dataset.
Throws:
java.lang.Exception

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
Create a new image at given parent group in this file. For example, to create a 2D image of size 100X50 at the root in an HDF5 file.
 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 = 2;
 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 - the name of the new image
pgroup - the parent group where the new image is created.
type - the datatype of the new image.
dims - dimension sizes of the new image.
maxdims - the maximum dimension sizes of the new image.
chunks - the chunk sizes of the new image.
gzip - the compression level.
ncomp - the number of components of the new image
data - the data of the new image.
Throws:
java.lang.Exception

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

copy

public javax.swing.tree.TreeNode copy(HObject srcObj,
                                      Group dstGroup)
                               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.
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 atribute to attach.
isSDglobalAttr - The indicator if the given attribute exists.
Returns:
true if successful and false otherwise.
Throws:
HDFException

getLibversion

public java.lang.String getLibversion()
Returns the version of the HDF4 library.

Specified by:
getLibversion in class FileFormat

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.

Overrides:
get in class FileFormat
Throws:
java.lang.Exception