hdf images hdf images

Java HDF Interface (JHI)

1. What it is

The Java HDF Interface (JHI) is a Java package (ncsa.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 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 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:


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 ncsa.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_ncsa_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 'ncsa.hdf.hdflib.*', and then invoke the 'Hopen' method on the object 'HDFLibrary'. The Java program would look something like this:

import ncsa.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.


4. To Obtain

The JHI is included with the HDF-Java Products, which can be downloaded from the HDF-Java Home Page. - - Last modified: 14 October 2016