Please see The HDF Group's new Support Portal for the latest information.
1. What it is
The Java HDF Interface (JHI) is a Java package (hdf.hdflib) that ``wraps'' the HDF-4 library*. The JHI may be used by any Java application that needs to access HDF-4 files. This product cannot be used in most network browsers because it accesses the local disk using native code.| Note: The JHI does not support HDF-5. See the JHI5. |
A central part of the JHI is the Java class hdf.hdflib.HDFLibrary. The HDFLibrary class calls the standard (i.e., `native' code) HDF library, with native methods for most of the HDF functions.
It is extremely important to emphasize that this package is not a pure Java implementation of the HDF library. The JHI calls the same HDF library that is used by C or FORTRAN programs.
The Java HDF Interface consists of Java classes and dynamically linked native libraries. The Java classes declare static native methods, and the library contains C functions which implement the native methods. The C functions call the standard HDF library, which is linked as part of the same library on most platforms.
Intended purpose
The Java HDF Interface is intended to be the standard interface for accessing HDF-4 files from Java programs. The JHI is a foundation upon which application classes can be built. All classes that use this interface package should interoperate easily on any platform that has HDF-4 installed.It is unlikely that Java programs will want to directly call the HDF library. More likely, data will be represented by Java classes that meet the needs of the application. These classes can implement methods to store and retrieve data from HDF files using the Java HDF library.
Important Changes
| Very Important Change: Version 3.0 (and above) of the JHI packages
all HDF library
calls as "hdf.hdflib", note that the "ncsa" has been removed. Source code which used earlier versions of the JHI should be changed to reflect this new implementation. |
Other changes include:
- Support for Macintosh and PC path names, e.g., in Hopen().
- A separate distribution of the JHI. This contains everything from the full source distribution, omitting all the packages not used by the JHI.
- The HDFArray class was extended to support more types of Java arrays, including arrays of any sub-class of Number (Integer, Float, etc.) and arrays of String.
2. How to use it
For example, the HDF library had the function Hopen to open an HDF file. The Java interface is the class hdf.hdflib.HDFLibrary, which has a method:static native int Hopen(String filename, 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_hdf_hdflib_HDFLibrary_Hopen
(JNIEnv *env, jclass class, jstring hdfFile, jint access)
{
/* ... */
/* call the HDF library */
retVal = Hopen((char *)file, access, 0);
/* ... */
}
This C function calls the HDF 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 (libhdf). Note that this library must be built for each platform.
To call the HDF `Hopen' function, a Java program would import the package 'hdf.hdflib.*', and then invoke the 'Hopen' method on the object 'HDFLibrary'. The Java program would look something like this:
import hdf.hdflib.*;
{
/* ... */
HDFLibrary.Hopen("myFile.hdf", access);
/* ... */
}
The HDFLibrary class automatically loads the HDF-4 library with
the native method implementations and the HDF-4 library.3. Technical notes
The following is a list of a few important technical notes of the JHI. For more details, please read JHI Design Notes.
| Very Important Change: Please note that Version 2.6 (and above)
of the JHI
declares all HDF library calls as "static native" methods, and loads the library with a 'static' constructor. Source code which used earlier versions of the JHI should be changed to reflect this new, more efficient implementation. |
- Data conversion and copying. The Java HDF Interface must translate data between C data types and Java data types. For instance, when a Java program reads a two dimensional array of floating point numbers (float [][]), the HDF native library actually returns an array of bytes. The Java HDF Interface converts this to the correct Java object, and returns that to the calling program. This process uses the Java Core Reflection package to discover the type of the array, and then calls native code routines to convert the bytes from native (C) order to the correct Java object(s). This data conversion is platform specific and clearly adds overhead to the program.
- The JHI Interface to HDF. The Java HDF interface follows the HDF C interface as closely as possible. However, Java does not support pass-by-reference parameters, so all parameters that must be returned to the caller require special treatment for Java. In general, such parameters are passed as elements of an array. For example, to return an integer parameter, the Java native method would be declared to use an integer array. For instance, the C function
void foo( int inVar /* IN */, int *outVar /* OUT */ )would be rendered in Java as:
static public native void foo( int inVar, int []outVar )where the value of 'outVar' would be returned as 'outVar[0]'.