Java HDF Interface (JHI)
The Java HDF Interface (JHI) is a Java package
(ncsa.hdf.hdflib)
that ``wraps'' the NCSA HDF library. The JHI may be used by any Java
application that needs to access HDF files.
This product cannot be used in most network browsers because it
accesses the local disk using native code.
What it is
A central part of the JHI is the Java class ncsa.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 FORTAN
programs.
The Java HDF 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 HDF library, which is linked as part of the same library
on most platforms.
How to use it
For example, the HDF library had the function Hopen to open an
HDF file. The Java interface is the class ncsa.hdf.hdflib.HDFLibrary,
which has a method:
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_ncsa_hdf_hdflib_HDFLibrary_Hopen
(
JNIEnv *env,
jobject obj,
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 'ncsa.hdf.hdflib.*', and create an object of type 'HDFLibrary'.
It would then invoke the 'Hopen' method. The Java program would
look something like this:
import ncsa.hdf.hdflib.*;
{
/* ... */
HDFLibrary hdf = new HDFLibrary();
/* ... */
hdf.Hopen("myFile.hdf", access);
/* ... */
}
The HDFLibrary class automatically loads the HDF library with
the native method implementations and the HDF library.
Technical notes
- Data coversion 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 and integer array. For instance, the C function
void foo( int inVar /* IN */,
int *outVar /* OUT */ )
would be rendered in Java as:
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 initial release
most HDF library errors are not detected, so exceptions will not be raised
except when opening a file. Error handling will be completed in a future
release.
Intended purpose
The Java HDF Interface is intended to be the standard interface for
access HDF 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 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.
For More Information
For more information about the Java HDF Interface, see
|