java.io.File
ncsa.hdf.object.FileFormat
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
public abstract class FileFormat
FileFormat defines general interfaces for working with files whose data is organized according to a supported format.
FileFormat is a pluggable component. New implementing classes of FileFormat can be added to the list of supported file formats. Current implementing classes include H5File and H4File. By default, H5File and H4File are added to the list of supported file formats maintained by the static FileFormat instance.
FileFormat
_________________|_________________
| | |
H5File H4File Other...
A FileFormat instance may exist without being associated with a given file. A FileFormat instance may be associated with a file that is not open for access. Most typically, a FileFormat instance is used to open the associated file and perform operations such as retrieval and manipulation (if the file access is read-write) of the file structure and objects.
| Field Summary | |
|---|---|
static int |
CREATE
File access flag for creating/truncating with read-write permission. |
static int |
FILE_CREATE_DELETE
Flag for creating/truncating a file. |
static int |
FILE_CREATE_OPEN
Flag for creating/opening a file. |
static java.lang.String |
FILE_OBJ_SEP
A separator that separates file name and object name. |
static java.lang.String |
FILE_TYPE_HDF4
Key for HDF4 file format. |
static java.lang.String |
FILE_TYPE_HDF5
Key for HDF5 file format. |
static int |
READ
File access flag for read-only permission. |
static int |
WRITE
File access flag for read/write permission. |
| Fields inherited from class java.io.File |
|---|
pathSeparator, pathSeparatorChar, separator, separatorChar |
| Constructor Summary | |
|---|---|
FileFormat(java.lang.String filename)
Creates a new FileFormat instance with the given filename. |
|
| Method Summary | |
|---|---|
static void |
addFileExtension(java.lang.String extension)
Adds file extension(s) to the list of file extensions for supported file formats. |
static void |
addFileFormat(java.lang.String key,
FileFormat fileformat)
Adds a FileFormat with specified key to the list of supported formats. |
abstract void |
close()
Closes file associated with this instance. |
javax.swing.tree.TreeNode |
copy(HObject srcObj,
Group dstGroup)
Deprecated. As of 2.4, replaced by copy(HObject, Group, String)
To mimic the behavior originally provided by this method,
call the replacement method with |
abstract javax.swing.tree.TreeNode |
copy(HObject srcObj,
Group dstGroup,
java.lang.String dstName)
Copies the source object to a new destination. |
FileFormat |
create(java.lang.String fileName)
Deprecated. As of 2.4, replaced by createFile(String, int)
The replacement method has an additional parameter that
controls the behavior if the file already exists. Use
|
Dataset |
createCompoundDS(java.lang.String name,
Group pgroup,
long[] dims,
long[] maxdims,
long[] chunks,
int gzip,
java.lang.String[] memberNames,
Datatype[] memberDatatypes,
int[] memberSizes,
java.lang.Object data)
Creates a new compound dataset in a file with/without chunking and compression. |
Dataset |
createCompoundDS(java.lang.String name,
Group pgroup,
long[] dims,
java.lang.String[] memberNames,
Datatype[] memberDatatypes,
int[] memberSizes,
java.lang.Object data)
Deprecated. As of 2.4, replaced by createCompoundDS(String, Group, long[], long[], long[], int, String[], Datatype[], int[], Object)
The replacement method has additional parameters:
|
abstract Datatype |
createDatatype(int tclass,
int tsize,
int torder,
int tsign)
Creates a new datatype in memory. |
abstract 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 a file with the specified name and returns a new FileFormat implementation instance associated with the file. |
int |
createGcpl(int creationorder,
int maxcompact,
int mindense)
Creates the group creation property list identifier, gcpl. |
abstract Group |
createGroup(java.lang.String name,
Group parentGroup)
Creates a new group with specified name in existing group. |
Group |
createGroup(java.lang.String name,
Group pgroup,
int... gplist)
Creates a new group with specified name in existing group. |
abstract 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. |
abstract FileFormat |
createInstance(java.lang.String filename,
int access)
Creates a FileFormat implementation instance with specified filename and access. |
HObject |
createLink(Group parentGroup,
java.lang.String name,
HObject currentObj,
int type)
Creates a soft, hard or external link to an existing object in the open file. |
HObject |
createLink(Group linkGroup,
java.lang.String name,
java.lang.Object currentObj)
Creates a link to an existing object in the open file. |
HObject |
createLink(Group parentGroup,
java.lang.String name,
java.lang.String currentObj,
int type)
Creates a soft or external links to objects in a file that do not exist at the time the link is created. |
abstract 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. |
abstract void |
delete(HObject obj)
Deletes an object from a file. |
static HObject |
findObject(FileFormat file,
long[] oid)
Finds an object by its object ID |
static HObject |
findObject(FileFormat file,
java.lang.String path)
Finds an object by the full path of the object (path+name) |
abstract HObject |
get(java.lang.String path)
Gets the HObject with the specified path from the file. |
int |
getFID()
Returns file identifier of open file associated with this instance. |
static java.lang.String |
getFileExtensions()
Returns a list of file extensions for all supported file formats. |
static FileFormat |
getFileFormat(java.lang.String key)
Returns the FileFormat with specified key from the list of supported formats. |
static java.util.Enumeration |
getFileFormatKeys()
Returns an Enumeration of keys for all supported formats. |
static FileFormat[] |
getFileFormats()
Returns an array of supported FileFormat instances. |
java.lang.String |
getFilePath()
Returns the absolute path for the file. |
static HObject |
getHObject(java.lang.String fullPath)
Deprecated. As of 2.4, replaced by get(String)
This static method, which as been deprecated, causes two problems:
|
static HObject |
getHObject(java.lang.String filename,
java.lang.String path)
Deprecated. As of 2.4, replaced by get(String)
This static method, which as been deprecated, causes two problems:
|
static FileFormat |
getInstance(java.lang.String filename)
Creates a FileFormat instance for the specified file. |
int[] |
getLibBounds()
Gets the bounds of library versions |
abstract java.lang.String |
getLibversion()
Returns the version of the library for the implementing FileFormat class. |
int |
getMaxMembers()
Returns the maximum number of objects that can be loaded into memory. |
int |
getNumberOfMembers()
Returns the number of objects in memory. |
abstract javax.swing.tree.TreeNode |
getRootNode()
Returns the root node for the file associated with this instance. |
int |
getStartMembers()
Returns the index of the starting object to be loaded into memory. |
boolean |
isReadOnly()
Returns true if the file access is read-only. |
abstract boolean |
isThisType(FileFormat fileFormat)
Checks if the class implements the specified FileFormat. |
abstract boolean |
isThisType(java.lang.String filename)
Checks if the implementing FileFormat class matches the format of the specified file. |
abstract int |
open()
Opens file and returns a file identifier. |
int |
open(int... propList)
Opens file and returns a file identifier. |
FileFormat |
open(java.lang.String pathname,
int access)
Deprecated. As of 2.4, replaced by createInstance(String, int)
The replacement method has identical functionality and a more
descriptive name. Since open is used elsewhere to
perform a different function this method has been deprecated. |
static FileFormat |
removeFileFormat(java.lang.String key)
Removes a FileFormat from the list of supported formats. |
void |
renameAttribute(HObject obj,
java.lang.String oldAttrName,
java.lang.String newAttrName)
Renames an attribute. |
void |
setLibBounds(int low,
int high)
Sets the bounds of library versions. |
void |
setMaxMembers(int n)
Sets the maximum number of objects to be loaded into memory. |
void |
setStartMembers(int idx)
Sets the starting index of objects to be loaded into memory. |
abstract void |
writeAttribute(HObject obj,
Attribute attr,
boolean attrExisted)
Attaches a given attribute to an object. |
| 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 int READ
createInstance(String, int ),
Constant Field Valuespublic static final int WRITE
createInstance(String, int ),
Constant Field Valuespublic static final int CREATE
createInstance(String, int ),
Constant Field Valuespublic static final int FILE_CREATE_DELETE
createFile(String, int ),
Constant Field Valuespublic static final int FILE_CREATE_OPEN
createFile(String, int ),
Constant Field Valuespublic static final java.lang.String FILE_TYPE_HDF4
public static final java.lang.String FILE_TYPE_HDF5
public static final java.lang.String FILE_OBJ_SEP
getHObject(String),
Constant Field Values| Constructor Detail |
|---|
public FileFormat(java.lang.String filename)
The filename in this method call is equivalent to the pathname in the java.io.File class. The filename is converted into an abstract pathname by the File class.
Typically this constructor is not called directly, but is called by a constructor of an implementing class. Applications most frequently use the createFile(), createInstance(), or getInstance() methods to generate a FileFormat instance with an associated filename.
The file is not opened by this call. The read-only flag is set to false by this call.
filename - The filename; a pathname string.
java.lang.NullPointerException - If the filename argument is null.File.File(String),
createFile(String, int),
createInstance(String, int),
getInstance(String)| Method Detail |
|---|
public static final void addFileFormat(java.lang.String key,
FileFormat fileformat)
This method allows a new FileFormat, tagged with an identifying key, to be added dynamically to the list of supported File Formats. Using it, applications can add new File Formats at runtime.
For example, to add a new File Format with the key "xyz" that is implemented by the class xyzFile in the package companyC.files, an application would make the following calls:
Class fileClass = Class.forName( "companyC.files.xyzFile" );
FileFormat ff = (FileFormat) fileClass.newInstance();
if ( ff != null ) {
ff.addFileFormat ("xyz", ff )
}
If either key or fileformat are
null, or if key is already in use, the method
returns without updating the list of supported File Formats.
key - A string that identifies the FileFormat.fileformat - An instance of the FileFormat to be added.getFileFormat(String),
getFileFormatKeys(),
getFileFormats(),
removeFileFormat(String)public static final FileFormat getFileFormat(java.lang.String key)
This method returns a FileFormat instance, as identified by an identifying key, from the list of supported File Formats.
If the specified key is in the list of supported formats, the instance of
the associated FileFormat object is returned. If the specified key is not
in the list of supported formats, null is returned.
key - A string that identifies the FileFormat.
null
if the key is not found in the list of supported File Formats.addFileFormat(String,FileFormat),
getFileFormatKeys(),
getFileFormats(),
removeFileFormat(String)public static final java.util.Enumeration getFileFormatKeys()
This method returns an Enumeration containing the unique keys (Strings) for the all File Formats in the list of supported File Formats.
addFileFormat(String,FileFormat),
getFileFormat(String),
getFileFormats(),
removeFileFormat(String)public static final FileFormat[] getFileFormats()
This method returns an array of FileFormat instances that appear in the list of supported File Formats.
If the list of supported formats is empty, null is returned.
null if the list is empty.addFileFormat(String,FileFormat),
getFileFormat(String),
getFileFormatKeys(),
removeFileFormat(String)public static final FileFormat removeFileFormat(java.lang.String key)
This method removes a FileFormat, as identified by the specified key, from the list of supported File Formats.
If the specified key is in the list of supported formats, the instance of
the FileFormat object that is being removed from the list is returned. If
the key is not in the list of supported formats, null is
returned.
key - A string that identifies the FileFormat to be removed.
null if the key
is not found in the list of supported File Formats.addFileFormat(String,FileFormat),
getFileFormat(String),
getFileFormatKeys(),
getFileFormats()public static final void addFileExtension(java.lang.String extension)
Multiple extensions can be included in the single parameter if they are separated by commas.
The list of file extensions updated by this call is not linked with supported formats that implement FileFormat objects. The file extension list is maintained for the benefit of applications that may choose to recognize only those files with extensions that appear in the list of file extensions for supported file formats.
By default, the file extensions list includes: "hdf, h4, hdf5, h5"
extension - The file extension(s) to add.addFileFormat(String,FileFormat),
getFileExtensions()public static final java.lang.String getFileExtensions()
The extensions in the returned String are separates by commas: "hdf, h4, hdf5, h5"
It is the responsibility of the application to update the file extension
list using addFileExtension(String) when new FileFormat
implementations are added.
addFileExtension(String)
public static final FileFormat getInstance(java.lang.String filename)
throws java.lang.Exception
This method checks the list of supported file formats to find one that
matches the format of the specified file. If a match is found, the method
returns an instance of the associated FileFormat object. If no match is
found, null is returned.
For example, if "test_hdf5.h5" is an HDF5 file, FileFormat.getInstance("test_hdf5.h5") will return an instance of H5File.
The file is not opened as part of this call. Read/write file access is associated with the FileFormat instance if the matching file format supports read/write access. Some file formats only support read access.
filename - A valid file name, with a relative or absolute path.
null if no
match.
java.lang.IllegalArgumentException - If the filename argument is null or
does not specify an existing file.
java.lang.Exception - If there are problems creating the new instance.createFile(String, int),
createInstance(String, int),
getFileFormats()public abstract java.lang.String getLibversion()
The implementing FileFormat classes have freedom in how they obtain or generate the version number that is returned by this method. The H5File and H4File implementations query the underlying HDF libraries and return the reported version numbers. Other implementing classes may generate the version string directly within the called method.
public abstract boolean isThisType(FileFormat fileFormat)
The Java "instanceof" operation is unable to check if an object is an instance of a FileFormat that is loaded at runtime. This method provides the "instanceof" functionality, and works for implementing classes that are loaded at runtime.
This method lets applications that only access the abstract object layer determine the format of a given instance of the abstract class.
For example, HDFView uses the following code to determine if a file is an HDF5 file:
FileFormat h5F = FileFormat.getFileFormat(FileFormat.FILE_TYPE_HDF5); HObject hObject = viewer.getTreeView().getCurrentObject(); FileFormat thisF = hObject.getFileFormat(); boolean isH5 = h5F.isThisType(thisF);
fileFormat - The FileFormat to be checked.
isThisType(String)public abstract boolean isThisType(java.lang.String filename)
For example, if "test.h5" is an HDF5 file, the first call to isThisType()
in the code fragment shown will return false, and the second
call will return true.
FileFormat h4F = FileFormat.getFileFormat(FileFormat.FILE_TYPE_HDF4);
FileFormat h5F = FileFormat.getFileFormat(FileFormat.FILE_TYPE_HDF5);
boolean isH4 = h4F.isThisType("test.h5"); // false
boolean isH5 = h5F.isThisType("test.h5"); // true
filename - The name of the file to be checked.
isThisType(FileFormat)
public FileFormat createFile(java.lang.String filename,
int createFlag)
throws java.lang.Exception
This method creates a file whose format is the same as that of the implementing class. An instance of the FileFormat implementing class is created and associated with the file. That instance is returned by the method.
The filename in this method call is equivalent to the pathname in the java.io.File class. The filename is converted into an abstract pathname by the File class.
A flag controls the behavior if the named file already exists. The flag values and corresponding behaviors are:
If the flag is FILE_CREATE_DELETE, the method will create a new file or truncate an existing file. If the flag is FILE_CREATE_OPEN and the file does not exist, the method will create a new file.
This method does not open the file for access, nor does it confirm that the file can later be opened read/write. The file open is carried out by the open() call.
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.
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.createInstance(String, int),
getInstance(String),
open()
public abstract FileFormat createInstance(java.lang.String filename,
int access)
throws java.lang.Exception
This method creates an instance of the FileFormat implementing class and sets the filename and file access parameters.
The filename in this method call is equivalent to the pathname in the java.io.File class. The filename is converted into an abstract pathname by the File class.
The access parameter values and corresponding behaviors at file open:
Some FileFormat implementing classes may only support READ access and will use READ regardless of the value specified in the call. Refer to the implementing class documentation for details.
This method does not open the file for access, nor does it confirm that the file can later be opened read/write or created. The file open is carried out by the open() call.
Example (without exception handling):
// Request the implementing class of FileFormat: H5File
FileFormat h5file = FileFormat.getFileFormat(FileFormat.FILE_TYPE_HDF5);
// Create an instance of H5File object with read/write access
H5File test1 = (H5File) h5file.createInstance("test_hdf5.h5", FileFormat.WRITE);
// Open the file and load the file structure; file id is returned.
int fid = test1.open();
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.
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.createFile(String, int),
getInstance(String),
open()public final java.lang.String getFilePath()
For example, "/samples/hdf5_test.h5". If there is no file associated with
this FileFormat instance, null is returned.
null if there is no associated file.public final int getFID()
public final boolean isReadOnly()
This method returns true if the file access is read-only. If the file access is read-write, or if there is no file associated with the FileFormat instance, false will be returned.
Note that this method may return true even if the file is not open for access when the method is called. The file access is set by the createFile(), createInstance(), or getInstance() call, and the file is opened for access by the open() call.
createFile(String, int),
createInstance(String, int),
getInstance(String),
open()public final void setMaxMembers(int n)
Current Java applications, such as HDFView, cannot handle files with large numbers of objects due to JVM memory limitations. The maximum number limits the number of objects that will be loaded for a given FileFormat instance.
The implementing FileFormat class has freedom in how it interprets the maximum number. H5File, for example, will load the maximum number of objects for each group in the file.
n - The maximum number of objects to be loaded into memory.getMaxMembers(),
setStartMembers(int)public final int getMaxMembers()
setMaxMembers(int)public final void setStartMembers(int idx)
The implementing FileFormat class has freedom in how it indexes objects in the file.
idx - The starting index of the object to be loaded into memorygetStartMembers(),
setMaxMembers(int)public final int getStartMembers()
setStartMembers(int)public final int getNumberOfMembers()
This method returns the total number of objects loaded into memory for this FileFormat instance. The method counts the objects that are loaded, which can take some time for a large number of objects.
It is worth noting that the total number of objects in memory may be different than the total number of objects in the file.
Since implementing classes have freedom in how they interpret and use the maximum number of members value, there may be differing numbers of objects in memory in different implementation instances, even with the same "use case".
For example, say the use case is a file that contains 20,000 objects, the maximum number of members for an instance is 10,000, and the start member index is 1. There are 2 groups in the file. The root group contains 10,500 objects and the group "/g1" contains 9,500 objects.
In an implementation that limits the total number of objects loaded to the maximum number of members, this method will return 10,000.
In contrast, the H5File implementation loads up to the maximum number of members objects for each group in the file. So, with our use case 10,000 objects will be loaded in the root group and 9,500 objects will be loaded into group "/g1". This method will return the value 19,500, which exceeds the maximum number of members value.
getMaxMembers(),
setMaxMembers(int),
getStartMembers(),
setStartMembers(int)
public abstract int open()
throws java.lang.Exception
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.
java.lang.Exception - If the file cannot be opened. The exceptions thrown vary
depending on the implementing class.createFile(String, int),
createInstance(String, int),
getInstance(String),
getRootNode()
public abstract void close()
throws java.lang.Exception
This method closes the file associated with this FileFormat instance, as well as all objects associated with the file.
java.lang.Exception - If the file or associated objects cannot be closed. The
exceptions thrown vary depending on the implementing class.open()public abstract javax.swing.tree.TreeNode getRootNode()
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.
null there is no
associated file or if the associated file has not yet been
opened.open()
public abstract HObject get(java.lang.String path)
throws java.lang.Exception
This 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
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.
path - 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.
public abstract Datatype createDatatype(int tclass,
int tsize,
int torder,
int tsign,
java.lang.String name)
throws java.lang.Exception
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");
tclass - 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 abstract Datatype createDatatype(int tclass,
int tsize,
int torder,
int tsign)
throws java.lang.Exception
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);
tclass - 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 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
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);
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.
java.lang.Exception - The exceptions thrown vary depending on the implementing
class.
public Dataset createCompoundDS(java.lang.String name,
Group pgroup,
long[] dims,
long[] maxdims,
long[] chunks,
int gzip,
java.lang.String[] memberNames,
Datatype[] memberDatatypes,
int[] memberSizes,
java.lang.Object data)
throws java.lang.Exception
The following example creates a compressed 2D compound dataset with size of 100X50 in a root group. The compound dataset has two members, x and y. Member x is an interger, member y is an 1-D float array of size 10.
String name = "2D compound";
Group pgroup =
(Group)((DefaultMutableTreeNode)getRootNode).getUserObject();
long[] dims = {100, 50};
long[] chunks = {1, 50};
int gzip = 9;
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, null,
chunks, gzip, memberNames, memberDatatypes, memberSizes, null);
name - name of the new datasetpgroup - parent group where the new dataset is created.dims - dimension sizes of the new dataset.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.memberNames - names of the members.memberDatatypes - datatypes of the members.memberSizes - array sizes of the members.data - data written to the new dataset, null if no data is written to
the new dataset.
java.lang.UnsupportedOperationException - If the implementing class does not support compound datasets.
java.lang.Exception - The exceptions thrown vary depending on the implementing
class.
public abstract 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
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);
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.
java.lang.Exception - The exceptions thrown vary depending on the implementing
class.
public abstract Group createGroup(java.lang.String name,
Group parentGroup)
throws java.lang.Exception
If the parent group is null, the new group will be created in the root group.
name - The name of the new group.parentGroup - The parent group, or null.
java.lang.Exception - The exceptions thrown vary depending on the implementing
class.
public HObject createLink(Group parentGroup,
java.lang.String name,
HObject currentObj,
int type)
throws java.lang.Exception
If parentGroup is null, the new link is created in the root group.
parentGroup - The group where the link is created.name - The name of the link.currentObj - The existing object the new link will reference.type - The type of link to be created. It can be a hard link, a soft
link or an external link.
java.lang.Exception - The exceptions thrown vary depending on the implementing
class.
public HObject createLink(Group parentGroup,
java.lang.String name,
java.lang.String currentObj,
int type)
throws java.lang.Exception
parentGroup - The group where the link is created.name - The name of the link.currentObj - The name of the object the new link will reference. The object
doesn't have to exist.type - The type of link to be created.
java.lang.Exception - The exceptions thrown vary depending on the implementing
class.
public abstract javax.swing.tree.TreeNode copy(HObject srcObj,
Group dstGroup,
java.lang.String dstName)
throws java.lang.Exception
This 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();
srcObj - 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.
Exceptions - are specific to the implementing class. RUTH CONFIRM USE
SRC.copy not DEST.copy. Also what is returned on failure.
ALSO exceptions. ALSO, does it copy data or just structure?
java.lang.Exception
public abstract void delete(HObject obj)
throws java.lang.Exception
obj - The object to delete.
java.lang.Exception - The exceptions thrown vary depending on the implementing
class.
public abstract void writeAttribute(HObject obj,
Attribute attr,
boolean attrExisted)
throws java.lang.Exception
If an HDF(4&5) attribute exists in file, the method updates its value. If the attribute does not exists in file, it creates the attribute in file and attaches it to the object. It will fail to write a new attribute to the object where an attribute with the same name already exists. To update the value of an existing attribute in file, one needs to get the instance of the attribute by getMetadata(), change its values, and use writeAttribute() to write the value.
obj - The object to which the attribute is 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.
@Deprecated
public final FileFormat create(java.lang.String fileName)
throws java.lang.Exception
createFile(String, int)
The replacement method has an additional parameter that
controls the behavior if the file already exists. Use
FileFormat.FILE_CREATE_DELETE as the second
argument in the replacement method to mimic the behavior
originally provided by this method.
java.lang.Exception
@Deprecated
public final FileFormat open(java.lang.String pathname,
int access)
throws java.lang.Exception
createInstance(String, int)
The replacement method has identical functionality and a more
descriptive name. Since open is used elsewhere to
perform a different function this method has been deprecated.
java.lang.Exception
@Deprecated
public final 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
createCompoundDS(String, Group, long[], long[], long[], int, String[], Datatype[], int[], Object)
The replacement method has additional parameters:
maxdims, chunks, and gzip. To mimic
the behavior originally provided by this method, call the
replacement method with the following parameter list:
( name, pgroup, dims, null, null, -1,
memberNames, memberDatatypes, memberSizes, data );
java.lang.Exception
@Deprecated
public final javax.swing.tree.TreeNode copy(HObject srcObj,
Group dstGroup)
throws java.lang.Exception
copy(HObject, Group, String)
To mimic the behavior originally provided by this method,
call the replacement method with null as the 3rd
parameter.
java.lang.Exception
@Deprecated
public static final HObject getHObject(java.lang.String fullPath)
throws java.lang.Exception
get(String)
This static method, which as been deprecated, causes two problems:
java.lang.Exception
@Deprecated
public static final HObject getHObject(java.lang.String filename,
java.lang.String path)
throws java.lang.Exception
get(String)
This static method, which as been deprecated, causes two problems:
Dataset dset = H5File.getObject("hdf5_test.h5", "/images/iceburg");
...
// close the file through dset
dset.getFileFormat().close();
java.lang.Exception
public static final HObject findObject(FileFormat file,
long[] oid)
file - the file containing the objectoid - the oid to search for
public static final HObject findObject(FileFormat file,
java.lang.String path)
file - the file containing the objectoid - the path the full path of the object to search for
public int open(int... propList)
throws java.lang.Exception
propList - The property list is the list of parameters, like index type
and the index order. The index type can be alphabetical or
creation. The index order can be increasing order or
decreasing order.
java.lang.Exception
public Group createGroup(java.lang.String name,
Group pgroup,
int... gplist)
throws java.lang.Exception
If the parent group is null, the new group will be created in the root group.
name - The name of a new group.pgroup - The parent group object.gplist - The group creation properties, in which the order of the
properties conforms the HDF5 library API, H5Gcreate(), i.e.
lcpl, gcpl and gapl, where
java.lang.Exception
public int createGcpl(int creationorder,
int maxcompact,
int mindense)
throws java.lang.Exception
creationorder - The order in which the objects in a group should be created.
It can be Tracked or Indexed.maxcompact - The maximum number of links to store in the group in a compact
format.mindense - The minimum number of links to store in the indexed
format.Groups which are in indexed format and in which the
number of links falls below this threshold are automatically
converted to compact format.
java.lang.Exception
public HObject createLink(Group linkGroup,
java.lang.String name,
java.lang.Object currentObj)
throws java.lang.Exception
If linkGroup is null, the new link is created in the root group.
linkGroup - The group where the link is created.name - The name of the link.currentObj - The existing object the new link will reference.
java.lang.Exception - The exceptions thrown vary depending on the implementing
class.
public void renameAttribute(HObject obj,
java.lang.String oldAttrName,
java.lang.String newAttrName)
throws java.lang.Exception
obj - The object whose attribute is to be renamed.oldAttrName - The current name of the attribute.newAttrName - The new name of the attribute.
HDF5Exception
java.lang.Exception
public void setLibBounds(int low,
int high)
throws java.lang.Exception
low - The earliest version of the library.high - The latest version of the library.
HDF5Exception
java.lang.Exception
public int[] getLibBounds()
throws java.lang.Exception
HDF5Exception
java.lang.Exception
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||