java.io.File
ncsa.hdf.object.FileFormat
ncsa.hdf.object.nc2.NC2File
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
public class NC2File
This class provides file level APIs. File access APIs include retrieving the file hierarchy, opening and closing file, and writing file content to disk.
| 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 | |
|---|---|
NC2File()
Constructs an empty NC2File with read-only access. |
|
NC2File(java.lang.String pathname)
Constructs an NC2File object of given file name with read-only access. |
|
| Method Summary | |
|---|---|
void |
close()
Closes file associated with this instance. |
static Attribute |
convertAttribute(ucar.nc2.Attribute netcdfAttr)
converts a ucar.nc2.Attribute into an ncsa.hdf.object.Attribute |
javax.swing.tree.TreeNode |
copy(HObject srcObj,
Group dstGroup,
java.lang.String dstName)
Copies the source object to a new destination. |
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. |
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. |
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 intelace,
java.lang.Object data)
Creates a new image in a file. |
FileFormat |
createInstance(java.lang.String filename,
int access)
Creates an NC2File instance with specified file name and READ 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)
Deletes an object from a file. |
HObject |
get(java.lang.String path)
Gets the HObject with the specified path from the file. |
java.lang.String |
getLibversion()
Returns the version of the library. |
ucar.nc2.NetcdfFile |
getNetcdfFile()
|
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 a NetCDF file. |
boolean |
isThisType(java.lang.String filename)
Checks if a given file is a NetCDF file. |
int |
open()
Opens file and returns a file identifier. |
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, copy, create, createCompoundDS, createCompoundDS, createFile, 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 |
|---|
public static final long serialVersionUID
| Constructor Detail |
|---|
public NC2File()
public NC2File(java.lang.String pathname)
| Method Detail |
|---|
public boolean isThisType(FileFormat fileformat)
isThisType in class FileFormatfileformat - the fileformat to be checked.
FileFormat.isThisType(String)public boolean isThisType(java.lang.String filename)
isThisType in class FileFormatfilename - the file to be checked.
FileFormat.isThisType(FileFormat)
public FileFormat createInstance(java.lang.String filename,
int access)
throws java.lang.Exception
Regardless of specified access, the NC2File implementation uses READ.
createInstance in class FileFormatfilename - The filename; a pathname string.access - The file access flag, which determines behavior when file is
opened. Acceptable values are READ, WRITE, and
CREATE.
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.FileFormat.createInstance(java.lang.String, int)
public int open()
throws java.lang.Exception
FileFormat
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.
open in class FileFormatjava.lang.Exception - If the file cannot be opened. The exceptions thrown vary
depending on the implementing class.FileFormat.createFile(String, int),
FileFormat.createInstance(String, int),
FileFormat.getInstance(String),
FileFormat.getRootNode()
public void close()
throws java.io.IOException
FileFormatThis method closes the file associated with this FileFormat instance, as well as all objects associated with the file.
close in class FileFormatjava.io.IOExceptionFileFormat.open()public javax.swing.tree.TreeNode getRootNode()
FileFormat
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.
getRootNode in class FileFormatnull there is no
associated file or if the associated file has not yet been
opened.FileFormat.open()public ucar.nc2.NetcdfFile getNetcdfFile()
public Group createGroup(java.lang.String name,
Group pgroup)
throws java.lang.Exception
FileFormatIf the parent group is null, the new group will be created in the root group.
createGroup in class FileFormatname - The name of the new group.pgroup - The parent group, or null.
java.lang.Exception - The exceptions thrown vary depending on the implementing
class.
public Datatype createDatatype(int tclass,
int tsize,
int torder,
int tsign)
throws java.lang.Exception
FileFormatThe 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);
createDatatype in class FileFormattclass - class of datatype, e.g. Datatype.CLASS_INTEGERtsize - 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.
java.lang.Exception - The exceptions thrown vary depending on the implementing
class.
public Datatype createDatatype(int tclass,
int tsize,
int torder,
int tsign,
java.lang.String name)
throws java.lang.Exception
FileFormatThe 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");
createDatatype in class FileFormattclass - class of datatype, e.g. Datatype.CLASS_INTEGERtsize - 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".
java.lang.Exception - The exceptions thrown vary depending on the implementing
class.
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
FileFormatThe 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);
createScalarDS in class FileFormatname - 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.
java.lang.Exception - The exceptions thrown vary depending on the implementing
class.
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
FileFormatThe 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);
createImage in class FileFormatname - 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.
java.lang.Exception - The exceptions thrown vary depending on the implementing
class.
public void delete(HObject obj)
throws java.lang.Exception
FileFormat
delete in class FileFormatobj - The object to delete.
java.lang.Exception - The exceptions thrown vary depending on the implementing
class.
public javax.swing.tree.TreeNode copy(HObject srcObj,
Group dstGroup,
java.lang.String dstName)
throws java.lang.Exception
FileFormatThis 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 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 exisiting 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.
TreeNode copy1 = existingFile.copy(srcObj, dstGroup, "copy1");
TreeNode copy2 = newFile.copy(srcObj, dstGroup, "copy2");
// Close both the files.
file.close();
newFile.close();
copy in class FileFormatsrcObj - 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.
java.lang.Exception
public void copyAttributes(HObject src,
HObject dst)
public void copyAttributes(int src_id,
int dst_id)
public void writeAttribute(HObject obj,
Attribute attr,
boolean attrExisted)
throws java.lang.Exception
writeAttribute in class FileFormatobj - the object which the attribute is to be attached to.attr - the atribute to attach.attrExisted - The indicator if the given attribute exists.
java.lang.Exception - The exceptions thrown vary depending on the implementing
class.public static Attribute convertAttribute(ucar.nc2.Attribute netcdfAttr)
public java.lang.String getLibversion()
getLibversion in class FileFormat
public HObject get(java.lang.String path)
throws java.lang.Exception
FileFormatThis 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.
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}
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.
get("/go")
returns the instance for /g0 with the information necessary to access
/g0/dataset_comp, /g0/dataset_int, /g0/g00, and /g0/g01.
get in class FileFormatpath - Full path of the data object to be returned.
null.
java.lang.Exception - If there are unexpected problems in trying to retrieve the
object. The exceptions thrown vary depending on the
implementing class.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||