ncsa.hdf.object
Class FileFormat

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

public abstract class FileFormat
extends java.io.File

This FileFormat defines general I/O accessing interface to file resources, such as open/close file, and retrieve file structure.

FileFormat is a plugable component. A implementing class of FileFormat can be added to the supported file list. The current implementing classes include H5File and H4File. By default, H5File and H4File are added to the list of supported file formats.

See Also:
Serialized Form

Field Summary
static int CREATE
          Flag for creating a new file.
protected  int fid
          file identifier for the open file.
static java.lang.String FILE_TYPE_HDF4
          tag for HDF4 file.
static java.lang.String FILE_TYPE_HDF5
          tag for HDF5 file.
static java.lang.String FILE_TYPE_JPEG
          tag for JPEG image.
static java.lang.String FILE_TYPE_PNG
          tag for PNG image.
static java.lang.String FILE_TYPE_TIFF
          tag for TIFF image.
static int READ
          Flag for opening a file for read only.
static int WRITE
          Flag for opening a file for read/write.
 
Fields inherited from class java.io.File
pathSeparator, pathSeparatorChar, separator, separatorChar
 
Constructor Summary
FileFormat(java.lang.String filename)
          Construct a FileFormat with given file name
 
Method Summary
static void addFileExtension(java.lang.String extension)
           
static void addFileFormat(java.lang.String key, FileFormat fileformat)
          Add a new file format.
abstract  void close()
          Closes access to the file resource.
abstract  javax.swing.tree.TreeNode copy(HObject srcObj, Group dstGroup)
          Copy a data object to a group.
abstract  FileFormat create(java.lang.String fileName)
          Create a new instance of this 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.
abstract  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)
           
abstract  Group createGroup(java.lang.String name, Group pgroup)
          Create a new group with given group name and a parent in this file.
abstract  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.
 HObject createLink(Group parentGroup, java.lang.String name, HObject currentObj)
           
abstract  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.
abstract  void delete(HObject obj)
          Delete an object from the file.
 HObject get(java.lang.String path)
          Get an individual HObject with a given path.
 int getFID()
           
static java.lang.String getFileExtensions()
           
static FileFormat getFileFormat(java.lang.String key)
          Gets a FileFormat from the supported file list.
static java.util.Enumeration getFileFormatKeys()
          Returns a list of keys of the supported FileFormats.
static FileFormat[] getFileFormats()
          returns a list of supported file formats
abstract  java.lang.String getFilePath()
          Returns the full path of the file: file path + file name.
static HObject getHObject(java.lang.String fullPath)
          get HObject with given file name and object path in the format of filename#//path
static HObject getHObject(java.lang.String filename, java.lang.String path)
          get HObject with given file name and object path
static FileFormat getInstance(java.lang.String fileName)
          Constructs a FileFormat corresponding to the data in a file.
abstract  java.lang.String getLibversion()
          Returns the version of the HDF5 library.
protected  int getMaxMembers()
           
abstract  javax.swing.tree.TreeNode getRootNode()
          Returns the root node of the file.
protected  int getStartMembers()
           
abstract  boolean isReadOnly()
          Returns the true if the file is read-only, otherwise returns false.
abstract  boolean isThisType(FileFormat fileformat)
          Checks if a given file format is this type of file.
abstract  boolean isThisType(java.lang.String filename)
          Checks if a given file is this type of file.
abstract  int open()
          Opens access to the file resource and returns the file identifier.
abstract  FileFormat open(java.lang.String pathname, int access)
          Open a file and returns an instance of implementing class of the FileFormat.
 void setMaxMembers(int n)
          Current Java application such as HDFView cannot handle files with large number of objects such 1,000,000 objects.
 void setStartMembers(int idx)
          Current Java application such as HDFView cannot handle files with large number of objects such 1,000,000 objects.
abstract  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 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
 

Field Detail

READ

public static final int READ
Flag for opening a file for read only.

See Also:
Constant Field Values

WRITE

public static final int WRITE
Flag for opening a file for read/write.

See Also:
Constant Field Values

CREATE

public static final int CREATE
Flag for creating a new file.

See Also:
Constant Field Values

FILE_TYPE_JPEG

public static final java.lang.String FILE_TYPE_JPEG
tag for JPEG image.

See Also:
Constant Field Values

FILE_TYPE_TIFF

public static final java.lang.String FILE_TYPE_TIFF
tag for TIFF image.

See Also:
Constant Field Values

FILE_TYPE_PNG

public static final java.lang.String FILE_TYPE_PNG
tag for PNG image.

See Also:
Constant Field Values

FILE_TYPE_HDF4

public static final java.lang.String FILE_TYPE_HDF4
tag for HDF4 file.

See Also:
Constant Field Values

FILE_TYPE_HDF5

public static final java.lang.String FILE_TYPE_HDF5
tag for HDF5 file.

See Also:
Constant Field Values

fid

protected int fid
file identifier for the open file.

Constructor Detail

FileFormat

public FileFormat(java.lang.String filename)
Construct a FileFormat with given file name

Method Detail

open

public abstract int open()
                  throws java.lang.Exception
Opens access to the file resource and returns the file identifier. If the file is already open, it returns the file access identifier.

Returns:
the file access identifier if opening the file is succsessful; otherwise returns a negative value.
Throws:
java.lang.Exception

open

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

Parameters:
pathname - the full path name of the file.
Throws:
java.lang.Exception

close

public abstract void close()
                    throws java.lang.Exception
Closes access to the file resource.

Throws:
java.lang.Exception

getRootNode

public abstract javax.swing.tree.TreeNode getRootNode()
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.


getFilePath

public abstract java.lang.String getFilePath()
Returns the full path of the file: file path + file name.


isReadOnly

public abstract boolean isReadOnly()
Returns the true if the file is read-only, otherwise returns false.


create

public abstract FileFormat create(java.lang.String fileName)
                           throws java.lang.Exception
Create a new instance of this file. A subclass must implementing this method to create a file of its type. For example,
 FileFormat file = H5File.create("test.h5");
 
creates an HDF5 file "test.h5".

Throws:
java.lang.Exception

createGroup

public abstract Group createGroup(java.lang.String name,
                                  Group pgroup)
                           throws java.lang.Exception
Create a new group with given group name and a parent in this file.

Parameters:
name - the name fo the new group.
pgroup - the parent group.
Throws:
java.lang.Exception

createScalarDS

public abstract 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
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);
 

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
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);
 

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 abstract 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
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);
 

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

createDatatype

public abstract Datatype createDatatype(int tclass,
                                        int tsize,
                                        int torder,
                                        int tsign)
                                 throws java.lang.Exception
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);
 

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
Throws:
java.lang.Exception

createLink

public HObject createLink(Group parentGroup,
                          java.lang.String name,
                          HObject currentObj)
                   throws java.lang.Exception
Throws:
java.lang.Exception

addFileFormat

public static void addFileFormat(java.lang.String key,
                                 FileFormat fileformat)
Add a new file format.

This method is provided for adding new FileFormat dynamically.

Parameters:
key - the unique ID key to identify the file format. such as "HDF5" or "HDF4"
fileformat - the name of the new file format to be added.

getFileFormat

public static FileFormat getFileFormat(java.lang.String key)
Gets a FileFormat from the supported file list.

Parameters:
key - the unique ID key to identify the file format. such as "HDF5" or "HDF4"

getFileFormatKeys

public static final java.util.Enumeration getFileFormatKeys()
Returns a list of keys of the supported FileFormats.


getLibversion

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


isThisType

public abstract boolean isThisType(java.lang.String filename)
Checks if a given file is this type of file. For example, if "test.h5" is an HDF5 file, isThisType("test.h5") returns true for H5File, and false for H4File;
 FileFormat file = FileFormat.getFileFormat(FileFormat.FILE_TYPE_HDF5);
 boolean isH5 = file.isThisType("test.h5");
 

Parameters:
filename - the file to be checked.

isThisType

public abstract boolean isThisType(FileFormat fileformat)
Checks if a given file format is this type of file.

Parameters:
fileformat - the fileformat to be checked

writeAttribute

public abstract void writeAttribute(HObject obj,
                                    Attribute attr,
                                    boolean attrExisted)
                             throws java.lang.Exception
Creates a new attribute and attached to the object if attribute does not exist. Otherwise, just update the value of the attribute.

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:
java.lang.Exception

copy

public abstract javax.swing.tree.TreeNode copy(HObject srcObj,
                                               Group dstGroup)
                                        throws java.lang.Exception
Copy a data object to a group.

Parameters:
srcObj - the object to copy.
dstGroup - the destination group.
Returns:
the new node containing the new object.
Throws:
java.lang.Exception

delete

public abstract void delete(HObject obj)
                     throws java.lang.Exception
Delete an object from the file.

Parameters:
obj - the data object to delete.
Throws:
java.lang.Exception

setMaxMembers

public void setMaxMembers(int n)
Current Java application such as HDFView cannot handle files with large number of objects such 1,000,000 objects. setMaxMembers() sets the maximum number of objects will be loaded into memory.

Parameters:
n - the maximum number of objects to load into memory

setStartMembers

public void setStartMembers(int idx)
Current Java application such as HDFView cannot handle files with large number of objects such 1,000,000 objects. setStartMember() sets the starting index of objects will be loaded into memory.


getMaxMembers

protected int getMaxMembers()

getStartMembers

protected int getStartMembers()

getFileExtensions

public static java.lang.String getFileExtensions()

getFID

public int getFID()

addFileExtension

public static void addFileExtension(java.lang.String extension)

getInstance

public static FileFormat getInstance(java.lang.String fileName)
                              throws java.lang.Exception
Constructs a FileFormat corresponding to the data in a file. fileName may be an absolute or a relative file specification. It checks the registered FileFormats and returns an instance of the matched one, or null if none is matched

Throws:
java.lang.Exception

getHObject

public static HObject getHObject(java.lang.String fullPath)
                          throws java.lang.Exception
get HObject with given file name and object path in the format of filename#//path

Parameters:
fullPath - the file name and object path in the format of filename#//path
Throws:
java.lang.Exception

getHObject

public static HObject getHObject(java.lang.String filename,
                                 java.lang.String path)
                          throws java.lang.Exception
get HObject with given file name and object path

Parameters:
filename - the name of the file to open
path - the path of the data object in the file
Throws:
java.lang.Exception

get

public HObject get(java.lang.String path)
            throws java.lang.Exception
Get an individual HObject with a given path.

Throws:
java.lang.Exception

getFileFormats

public static FileFormat[] getFileFormats()
returns a list of supported file formats