NCSA Java HDF5 Interface (JHI5)

JHI5 Design Notes

What it is

The Java HD5 Interface (JHI5) is a Java package ( ncsa.hdf.hdf5lib) that ``wraps around'' the NCSA HDF5 library.

Note: The JHI5 does not support HDF4 or earlier. See the JHI.

The JHI5 may be used by any Java application that needs to access HDF-5 files. It is extremely important to emphasize that this package is not a pure Java implementation of the HDF-5 library. The JHI5 calls the same HDF-5 library that is used by C or FORTRAN programs. (Note that this product cannot be used in most network browsers because it accesses the local disk using native code.)

The Java HDF-5 Interface consists of Java classes and a dynamically linked native library. The Java classes declare native methods, and the library contains C functions which implement the native methods. The C functions call the standard HDF-5 library, which is linked as part of the same library on most platforms.

The central part of the JHI5 is the Java class ncsa.hdf.hdf5lib.H5. The H5 class calls the standard (i.e., `native' code) HDF-5 library, with native methods for most of the HDF-5 functions.

How to use it

The JHI5 is used by Java classes to call the HDF-5 library, in order to create HDF-5 files, and read and write data in existing HDF-5 files.

For example, the HDF-5 library had the function H5Fopen to open an HDF-5 file. The Java interface is the class ncsa.hdf.hdf5lib.H5, which has a method:

static native int H5Fopen(String filename, int flags, int access );

The native method is implemented in C using the Java Native Method Interface (JNI). This is written something like the following:

JNIEXPORT jint
JNICALL Java_ncsa_hdf_hdf5lib_H5_H5Fopen
(
 JNIEnv *env,
 jclass class,
 jstring hdfFile,
 jint flags,
 jint access)
 {

 /* ...convert Java String to (char *) */

 /* call the HDF library */
 retVal = H5Fopen((char *)file, (unsigned)flags, (hid_t)access );

 /* ... */
}

This C function calls the HDF-5 library and returns the result appropriately.

There is one native method for each HDF entry point (several hundred in all), which are compiled with the HDF library into a dynamically loaded library (libjhdf5). Note that this library must be built for each platform.

To call the HDF `H5Fopen' function, a Java program would import the package 'ncsa.hdf.hdf5lib.*', and invoke the method on the class 'H5'. The Java program would look something like this:

import ncsa.hdf.hdf5lib.*;

{
 /* ... */

 try {
 file = H5.Hopen("myFile.hdf", flags, access );
 } catch (HDF5Exception ex) {
 //...
 }

 /* ... */
}

The H5 class automatically loads the native method implementations and the HDF-5 library.

To Obtain

The JHI5 is included with the HDF-Java Products, which can be downloaded from the following page: the hdf-java home page

- - Last modified:October 19th 2007