NCSA

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


NCSA
The National Center for Supercomputing Applications

University of Illinois at Urbana-Champaign

hdfhelp@ncsa.uiuc.edu
Last Modified: March 15, 1998