NCSA Java HDF5 Interface (JHI5)

Download

JHI5 Design Notes


Installing NCSA Java HDF-5 Interface (JHI5)

Installation Instructions

The Java HDF-5 Interface is distributed as source code and as pre-built binaries for selected platforms.

When installed on a system, the JHI5 consists of two parts, the Java classes and the jhdf5 native library (which includes the HDF-5 library). The Java classes are the same for every platform, but the jhdf5 library must be built for each platform.

The usual installation would be something like:

<JHI5DIR>/lib/
 jhdf5.jar
 solaris/
 libjhdf5.so
for a solaris platform, installed in a directory <JHI5DIR>. Other platforms would have the same JAR file, but a different libjhdf5.a

At run time, the environment must be set to include the path to the JAR file in CLASSPATH, and the dynamically loaded library in LD_LIBRARY_PATH (on Unix) or PATH (Windows98/NT).


Building From Source

Prerequisites:

* Note: The Java HDF-5 Interface builds a dynamically loaded C library (e.g., libjhdf5.so), which is loaded by the Java Virtual Machine. This wrapper code depends on HDF-5 (libhdf5), which in turn requires GZIP (libz). On all Unix systems tested so far, the JVM cannot resolve these dependencies if the libhdf5 and libz are dynamic libraries. For this reason, it is necessary to link the libjhdf5.so with the static versions of libhdf5.a and libz.a, and then create a dynamic library, libjhdf5.so. The configure script and Makefile implement this requirement.


Building:

The Java HDF-5 Interface consists of Java classes and C code to implement native methods. The C code links to the HDF-5 library.

Unix:

For a Unix system, run the automatic configuration program:

./configure
This program requests the location of the prerequisite HDF-5 and GZIP libraries and the Java development tools, and
generates Makefiles with appropriate paths. For a platform not tested by NCSA, it may be necessary to adjust the Makefiles that are generated.

To build, type:

make
To install the Java HDF-5 Interface library and JAR file, type:
make install
Windows:

For a Windows 95/98/NT system, there will be two steps to build the JHI5.


Build the dynamic link library jhdf5.dll

The building procedure depends on what C/C++ compiler you are using. You will need two things to build the jhdf5.dll,

  1. the HDF5 library
  2. the C source files, which come with JHI5 source code. The files are located at your_jhi5_root/native.
Afer you compile the dynamic link library jhdf5.dll, move or copy it to your_jhi5_root/lib/win. your_jhi5_root/lib/win/jhdf5.dll is loaded by the HDF5 Java native functions.


Build the Java package of JHI5

A batch file to compile the JHI5 Java classes is provided at your_jhi5_root/win32_make.bat to compile and pack the JHI5.

Before you run the batch, edit win32_make.bat to set the JDK path to the location of the JDK. For example,

SET JAVAHOME=d:\java\jdk1.2.2
The JHI5 root should be set to the directory in which the JHI5 will be built.

Then execute win32_make.bat.


Checking the installation: loading the library

The JHI5 dynamically loads the Java HDF-5 library containing the native methods, and must also dynamically load the HDF-5 library. These libraries must be available to the Java runtime through the environment. For JDK1.2, the path is available in the 'java.library.path' environment variable. The exact path needed depends on the system and where the libraries are installed.

To help debug problems with these paths, the JHI5 distribution includes a test program, etc/TestHDF5Link.java. To test the JHI5 installation, build and run the TestHDF5Link program. The output will report the 'java.library.path' and whether the JHI5 and HDF-5 library are correctly loaded. If the TestHDF5Link program works, then its configuration can be used by any program that needs to use the JHI5.


Sample Files and Programs

The JHI5 distribution includes some simple HDF5 files in the directory samples and some examples programs in tutorial. The example programs are Java versions of the example programs from the HDF5 Tutorial and can also be found in the HDF5 Tutorial: The java programs illustrate how to call the Java HDF5 Interface, and should produce identical HDF5 files as the example C programs in the HDF5 Tutorial.