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 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 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:
staticnative 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:
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:
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]'.
Exceptions. The JHI declares all the methods of HDF to throw Java
exceptions of type `HDFLibraryException'. Errors returned by the
native HDF library will be detected and the appropriate Exception raised,
just as from regular Java methods. There is no need for the Java program
to analyze HDF library error codes or return values. However, in this release
many HDF library errors are not detected as exceptions, so exceptions will
not be raised except when opening a file. Error handling will be completed
in a future release.
4. To Obtain
The JHI is included with the HDF-Java Products, which can be downloaded
from the HDF-Java Home Page.