JHI5 Design Notes

Important Changes

Description of the Java HDF5 Interface (JHI5)

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.

...

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.

Anchor
designnotes designnotes

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.

...

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.

Anchor
unsupported unsupported

Unsupported Functions