ncsa.hdf.object.h5
Class H5File

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

public class H5File
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
H5File()
          Constructs an empty H5File with read-only access.
H5File(java.lang.String pathname)
          Constructs an H5File object of given file name with read-only access.
H5File(java.lang.String pathname, int access)
          Constructs an H5File object with given 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 a data object to a group.
 void copyAttributes(HObject src, HObject dst)
          Copy attributes of the source object to the destination object.
 void copyAttributes(int src_id, int dst_id)
          Copy attributes of the source object to the destination object.
 FileFormat create(java.lang.String fileName)
          Creates a new HDF5 file with given file name.
 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.
 Datatype createDatatype(int tclass, int tsize, int torder, int tsign, java.lang.String name)
           
 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 intelace, java.lang.Object data)
          Create a new image at given parent group in this file.
static void createImageAttributes(Dataset dataset, int interlace)
          Creates required atriubtes for HDF5 image.
 HObject createLink(Group parentGroup, java.lang.String name, HObject currentObj)
           
 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.
static java.util.List getAttribute(int objID)
          Returns a list of attriubtes for the given object location.
 java.lang.String getFilePath()
          Returns the full path of the file: file path + file name.
 java.lang.String getLibversion()
          Returns the version of the HDF5 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 HDF5 file.
 boolean isThisType(java.lang.String filename)
          Checks if a given file is an HDF5 file.
 int open()
          Opens access to the file resource and returns the file identifier.
 FileFormat open(java.lang.String pathname, int access)
          Creates an instance of an H5File with given file name and access flag.
 void reloadTree(Group g)
          reload the sub-tree structure.
static void updateReferenceDataset(H5File srcFile, H5File newFile)
          Update values of reference datasets.
 void writeAttribute(HObject obj, Attribute attr, boolean attrExisted)
          Creates a new attribute and attached to the object if attribute does not exist.
 
Methods inherited from class ncsa.hdf.object.FileFormat
addFileExtension, addFileFormat, 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

H5File

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


H5File

public H5File(java.lang.String pathname)
Constructs an H5File object of given file name with read-only access.


H5File

public H5File(java.lang.String pathname,
              int access)
Constructs an H5File object with given file name and access flag.

Parameters:
pathname - the full path name of the file.
Method Detail

isThisType

public boolean isThisType(FileFormat fileformat)
Checks if the given file format is an HDF5 file.

Specified by:
isThisType in class FileFormat
Parameters:
fileformat - the fileformat to be checked.
Returns:
true if the given file is an HDF5 file; otherwise returns false.

isThisType

public boolean isThisType(java.lang.String filename)
Checks if a given file is an HDF5 file.

Specified by:
isThisType in class FileFormat
Parameters:
filename - the file to be checked.
Returns:
true if the given file is an HDF5 file; otherwise returns false.

open

public FileFormat open(java.lang.String pathname,
                       int access)
                throws java.lang.Exception
Creates an instance of an H5File with given file name and access flag.

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 HDF5Exception
Description copied from class: FileFormat
Closes access to the file resource.

Specified by:
close in class FileFormat
Throws:
HDF5Exception

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 HDF5 file with given file name.

Specified by:
create in class FileFormat
Returns:
an instance of the new H5File.
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

createDatatype

public Datatype createDatatype(int tclass,
                               int tsize,
                               int torder,
                               int tsign,
                               java.lang.String name)
                        throws java.lang.Exception
Overrides:
createDatatype in class FileFormat
Throws:
java.lang.Exception

createLink

public HObject createLink(Group parentGroup,
                          java.lang.String name,
                          HObject currentObj)
                   throws java.lang.Exception
Overrides:
createLink in class FileFormat
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 intelace,
                           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
Description copied from class: FileFormat
Delete an object from the file.

Specified by:
delete in class FileFormat
Parameters:
obj - the data object to delete.
Throws:
java.lang.Exception

reloadTree

public void reloadTree(Group g)
reload the sub-tree structure. Sube-calsses need to replace it


copy

public javax.swing.tree.TreeNode copy(HObject srcObj,
                                      Group dstGroup)
                               throws java.lang.Exception
Description copied from class: FileFormat
Copy a data 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

copyAttributes

public void copyAttributes(HObject src,
                           HObject dst)
Copy attributes of the source object to the destination object.


copyAttributes

public void copyAttributes(int src_id,
                           int dst_id)
Copy attributes of the source object to the destination object.


updateReferenceDataset

public static void updateReferenceDataset(H5File srcFile,
                                          H5File newFile)
                                   throws java.lang.Exception
Update values of reference datasets. When a file is saved into a new file, the values of reference dataset will not make sense in the new file and must be updated based on the values of references in the new file.

Throws:
java.lang.Exception

getAttribute

public static java.util.List getAttribute(int objID)
                                   throws HDF5Exception
Returns a list of attriubtes for the given object location.

Parameters:
objID - the object identifier.
Returns:
the list of attriubtes of the object.
Throws:
HDF5Exception

writeAttribute

public void writeAttribute(HObject obj,
                           Attribute attr,
                           boolean attrExisted)
                    throws HDF5Exception
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.
attrExisted - The indicator if the given attribute exists.
Returns:
true if successful and false otherwise.
Throws:
HDF5Exception

createImageAttributes

public static void createImageAttributes(Dataset dataset,
                                         int interlace)
                                  throws java.lang.Exception
Creates required atriubtes for HDF5 image.
    The basic HDF5 image attributes include:
  1. The image identifier: name="CLASS", value="IMAGE"
  2. The type of the image: name="IMAGE_SUBCLASS", value="IMAGE_TRUECOLOR" or "IMAGE_INDEXED"
  3. The version of image: name="IMAGE_VERSION", value="1.2"
  4. The range of data value: name="IMAGE_MINMAXRANGE", value=[0, 255]
  5. The interlace mode: name="INTERLACE_MODE", value="INTERLACE_PIXEL" or "INTERLACE_PLANE"
  6. The pointer to the palette dataset: name="PALETTE", value=reference id of the palette dataset
For more information about HDF5 image attributes, please read the HDF5 Image and Palette Specification

Parameters:
dataset - the image dataset which the attributes are added to.
interlace - interlace the interlace mode of image data.
Throws:
java.lang.Exception

getLibversion

public java.lang.String getLibversion()
Returns the version of the HDF5 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