Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

JHI5 Design Notes

Important Changes

Description of the Java HDF5 Interface (JHI5)

Very Important Change: Version 3.0 (and above) of the JHI5 packages all HDF library

calls as "hdf.hd5flib". Note that the "ncsa" has been removed. Source code which used

earlier versions of the JHI5 should be changed to reflect this new implementation.

What it is

The Java HD5 HDF5 Interface (JHI5) is a Java package (hdf.hdf5lib) that ``wraps around'' the HDF5 library.

There are over 460 functions in the HDF5 library (version 1.8). Ninety three of the functions are not supported in JHI5. Most of the unsupported functions have C function pointers, which is not currently implemented in JHI5. For a complete list of unsupported functions, please see  unsupported functions.

Note: The JHI5 does not support HDF4 or earlier.  See the JHI.


The central part of the JHI5 is the Java class hdf.hdf5lib.H5. The H5 class calls the standard (i.e., `native' code) HDF5 library, with native methods for most of the HDF5 functions.

How to use it

The JHI5 is used by Java classes to call the HDF5 library, in order to create HDF5 files, and read and write data in existing HDF5 files. For example, the HDF5 library has the function H5Fopen to open an HDF5 file. The Java interface is the class hdf.hdf5lib.H5, which has a method:


The H5 class automatically loads the native method implementations and the HDF-5 library.

JHI5 Design Notes

1. Overview

The Java HDF5 Interface (JHI5) is a Java package (hdf.hdf5lib) that ``wraps'' HDF5 library. For general information about HDF5 file format and library, please see the HDF5 Home Page. The JHI5 may be used by any Java application that needs to access HDF5 files. This product cannot be used in most network browsers because it accesses the local disk using native code.


A central part of the JHI5 is the Java class hdf.hdf5lib.H5. The H5class calls the standard (i.e., `native' code) HDF5 library, with native methods for most of the HDF5 functions. In general, there is one native method call for each function in the HDF5 API, with similar arguments. Consult the HDF5 reference manual for details of the C API. (HDF5 API Specification)

The Java HDF5 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 HDF5 library, which is linked as part of the same library on most platforms. The Java HDF5 Interface also translates between Java and C arrays, and converts error codes from the HDF5 C library to Java Exceptions.


The JHI5 is not a persistent object store for Java objects. It would be possible to implement an object store with the JHI5, but the interface does not provide any special support for storing and retrieving Java objects.

2. How to use the JHI5

How it works

The JHI5 is used to call the HDF-5 library. The Java application will make essentially the same calls as a C program. The HDF-5 library is accessed through the Java class hdf.hdf5lib.H5.


For more information about JHI5 exceptions see, Exceptions.

3. What definitely works

The JHI5 Interface supports the writing and reading of multi-dimensional arrays of numbers. Any Java number type can be used (both intrinsic and object types, i.e., both float and Float), and Strings. The Java HDF5 Interface must translate data between C data types and Java data types and vice versa. For instance, when a Java program reads a two dimensional array of floating point numbers (float [][]), the HDF5 native library actually returns an array of bytes in C order. The Java HDF5 Interface converts this to the correct Java object(s), and returns the Java object to the calling program. Similarly, the Java program will pass an array of Java numbers, which is converted to an array of bytes in correct C order, and then passed to HDF5.


The JHI5 supports reading and writing selections, including hyperslabs, repeated blocks (strides), and point selections. These work as expected for Java arrays of any dimension and any number type. HDF5 "chunking" works as expected. Compression can be used, providing that the appropriate compression libraries are linked with the HDF5 library. (See "What may not work", below.)

4. What does not work

The current implementation of the Java HDF5 interface provides most of the functions of the HDF5 library. However, some features of HDF5 could not be supported for Java.


  1. H5Pset_vlen_mem_manager
  2. H5Pget_vlen_mem_manager


5. Warnings: What May or May Not Work

The HDF5 library is very general and flexible, and the library is correspondingly complex. The Java HDF5 Interface provides the key features of the HDF5 library, but some features are only partially supported, or must be used with care.


To correctly read and write Java long or Long data, the HDF5 data type must be H5T_STD_64BE or H5T_STD_64LE, i.e., 64-bit big endian or little endian. Either may be selected, but an appropriate byte order must be specified to read the data correctly. However, in the current implementation this data cannot be read with the C type H5T_NATIVE_LONG. To read on a platform with the same byte order, the data must be read with the same H5T type. To read on a platform with a different byte order, the data must be read with the opposite byte order.
In general, 64-bit data should be used with caution, and results checked carefully to make sure that data is correct.

Compound data types

The HDF5 format and library support complex structured data types, including arrays of "compound data types", i.e., arrays of structured records. Compound data is stored as packed arrays of bytes, as C stores 'struct' data. The Java language does not use a flat memory model; data--including arrays--are stored as objects. An array of Java objects is not necessarily stored as a contiguous block of storage, and contains information besides the content of the variables. For these reasons, it is very difficult to automatically map between HDF5 compound data types and Java objects.


See "Using Compound Datatypes" for a detailed example.

Unsupported Functions

H5DdebugLow priority
H5DgatherFunction pointer
H5DscatterFunction pointer
H5Eget_auto1Function pointer
H5Eget_auto2Function pointer
H5Epush1Function format with list
H5Epush2Function format with list
H5Eset_auto1Function pointer
H5Eset_auto2Function pointer
H5FDallocFunction pointer
H5FDcloseFunction pointer
H5FDcmpFunction pointer
H5FDflushFunction pointer
H5FDfreeFunction pointer
H5FDget_eoaFunction pointer
H5FDget_eofFunction pointer
H5FDget_vfd_handleFunction pointer
H5FDqueryFunction pointer
H5FDreadFunction pointer
H5FDregisterFunction pointer
H5FDset_eoaFunction pointer
H5FDtruncateFunction pointer
H5FDunregisterFunction pointer
H5FDwriteFunction pointer
H5Fget_file_imageFunction pointer
H5Fget_mdc_configFunction pointer
H5Fget_vfd_handleFunction pointer
H5Fset_mdc_configFunction pointer
H5GiterateFunction pointer
H5IregisterFunction pointer
H5Iregister_typeFunction pointer
H5Iobject_verifyFunction pointer
H5Iremove_verifyFunction pointer
H5IsearchFunction pointer
H5Lcreate_udFunction pointer
H5LregisterFunction pointer
H5Lunpack_elink_valFunction pointer
H5Pcreate_classFunction pointer
H5Pget_elink_cbFunction pointer
H5Pget_multi_typeLow priority
H5Pget_type_conv_cbFunction pointer
H5Pget_vlen_mem_managerFunction pointer
H5Pinsert1Function pointer
H5Pinsert2Function pointer
H5PiterateFunction pointer
H5Pregister1Function pointer
H5Pregister2Function pointer
H5Pset_driverFunction pointer
H5Pset_dxpl_mpio_chunk_optFunction pointer
H5Pset_dxpl_mpio_chunk_opt_numFunction pointer
H5Pset_dxpl_mpio_chunk_opt_ratioFunction pointer
H5Pset_dxpl_mpio_collective_optFunction pointer
H5Pset_elink_cbFunction pointer
H5Pset_filter_callbackFunction pointer
H5Pset_multi_typeLow priority
H5Pset_type_conv_cbFunction pointer
H5Pset_vlen_mem_managerFunction pointer
H5TfindFunction pointer
H5TregisterFunction pointer
H5TunregisterFunction pointer
H5ZregisterFunction pointer