Description of the Java HDF5 Interface (JHI5)
Very Important Change: Version 3.0 (and above) of the JHI5 packages all HDF library
calls as "hdf.hd5flib". Note that the "ncsa" has been removed. Source code which used
earlier versions of the JHI5 should be changed to reflect this new implementation.
What it is
The Java HD5 HDF5 Interface (JHI5) is a Java package (hdf.hdf5lib) that ``wraps around'' the HDF5 library.
There are over 460 functions in the HDF5 library (version 1.8). Ninety three of the functions are not supported in JHI5. Most of the unsupported functions have C function pointers, which is not currently implemented in JHI5. For a complete list of unsupported functions, please see unsupported functions.
|Note: The JHI5 does not support HDF4 or earlier. See the JHI.|
The central part of the JHI5 is the Java class hdf.hdf5lib.H5. The H5 class calls the standard (i.e., `native' code) HDF5 library, with native methods for most of the HDF5 functions.
How to use it
The JHI5 is used by Java classes to call the HDF5 library, in order to create HDF5 files, and read and write data in existing HDF5 files. For example, the HDF5 library has the function H5Fopen to open an HDF5 file. The Java interface is the class hdf.hdf5lib.H5, which has a method:
The H5 class automatically loads the native method implementations and the HDF-5 library.
The Java HDF5 Interface (JHI5) is a Java package (hdf.hdf5lib) that ``wraps'' HDF5 library. For general information about HDF5 file format and library, please see the HDF5 Home Page. The JHI5 may be used by any Java application that needs to access HDF5 files. This product cannot be used in most network browsers because it accesses the local disk using native code.
A central part of the JHI5 is the Java class hdf.hdf5lib.H5. The H5class calls the standard (i.e., `native' code) HDF5 library, with native methods for most of the HDF5 functions. In general, there is one native method call for each function in the HDF5 API, with similar arguments. Consult the HDF5 reference manual for details of the C API. (HDF5 API Specification)
The Java HDF5 Interface consists of Java classes and dynamically linked native libraries. The Java classes declare native methods, and the library contains C functions which implement the native methods. The C functions call the standard HDF5 library, which is linked as part of the same library on most platforms. The Java HDF5 Interface also translates between Java and C arrays, and converts error codes from the HDF5 C library to Java Exceptions.
The JHI5 is not a persistent object store for Java objects. It would be possible to implement an object store with the JHI5, but the interface does not provide any special support for storing and retrieving Java objects.
2. How to use the JHI5
How it works
The JHI5 is used to call the HDF-5 library. The Java application will make essentially the same calls as a C program. The HDF-5 library is accessed through the Java class hdf.hdf5lib.H5.
For more information about JHI5 exceptions see, Exceptions.
3. What definitely works
The JHI5 Interface supports the writing and reading of multi-dimensional arrays of numbers. Any Java number type can be used (both intrinsic and object types, i.e., both float and Float), and Strings. The Java HDF5 Interface must translate data between C data types and Java data types and vice versa. For instance, when a Java program reads a two dimensional array of floating point numbers (float ), the HDF5 native library actually returns an array of bytes in C order. The Java HDF5 Interface converts this to the correct Java object(s), and returns the Java object to the calling program. Similarly, the Java program will pass an array of Java numbers, which is converted to an array of bytes in correct C order, and then passed to HDF5.
The JHI5 supports reading and writing selections, including hyperslabs, repeated blocks (strides), and point selections. These work as expected for Java arrays of any dimension and any number type. HDF5 "chunking" works as expected. Compression can be used, providing that the appropriate compression libraries are linked with the HDF5 library. (See "What may not work", below.)
The current implementation of the Java HDF5 interface provides most of the functions of the HDF5 library. However, some features of HDF5 could not be supported for Java.
The HDF5 library is very general and flexible, and the library is correspondingly complex. The Java HDF5 Interface provides the key features of the HDF5 library, but some features are only partially supported, or must be used with care.
To correctly read and write Java long or Long data, the HDF5 data type must be H5T_STD_64BE or H5T_STD_64LE, i.e., 64-bit big endian or little endian. Either may be selected, but an appropriate byte order must be specified to read the data correctly. However, in the current implementation this data cannot be read with the C type H5T_NATIVE_LONG. To read on a platform with the same byte order, the data must be read with the same H5T type. To read on a platform with a different byte order, the data must be read with the opposite byte order.
In general, 64-bit data should be used with caution, and results checked carefully to make sure that data is correct.
Compound data types
The HDF5 format and library support complex structured data types, including arrays of "compound data types", i.e., arrays of structured records. Compound data is stored as packed arrays of bytes, as C stores 'struct' data. The Java language does not use a flat memory model; data--including arrays--are stored as objects. An array of Java objects is not necessarily stored as a contiguous block of storage, and contains information besides the content of the variables. For these reasons, it is very difficult to automatically map between HDF5 compound data types and Java objects.
See "Using Compound Datatypes" for a detailed example.
|H5Epush1||Function format with list|
|H5Epush2||Function format with list|