# Java HDF Interface (JHI4)

## What it is

The Java HDF Interface (JHI4) is a Java package (hdf.hdflib) that ``wraps around'' the HDF library.

There are a large number of functions in the HDF library (version 4.2). Some of the functions are not supported in JHI4.

Note: The JHI4 only supports HDF4.

The JHI4 may be used by any Java application that needs to access HDF files. It is extremely important to emphasize that this package is not a pure Java implementation of the HDF library. The JHI4 calls the same HDF 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 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 library, which is linked as part of the same library on most platforms.

The central part of the JHI4 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 HDF4functions.

### How to use it

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

For example, the HDF library has 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 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_hdf_hdflib_HDFLibrary_Hopen
    (
     JNIEnv *env,
     jclass class,
     jstring hdfFile,
     jint flags,
     jint access)
     {

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

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

     /* ... */
    }

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_java). 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 invoke the method on the class 'HDFLibrary'. The Java program would look something like this:

    import hdf.hdflib.*;

    {
     /* ... */

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

     /* ... */
    }

The HDFLibrary class automatically loads the native method implementations and the HDF library.

### To Obtain

The JHI4 is included with the HDF library.