ch.systemsx.cisd.hdf5.hdf5lib
Date: 2011-08-28

### Introduction

This package is the low-level Java interface for the CISD HDF5 library. It is derived from the the low-level Java interface of the HDF Group's HDF-Java library.

It should be considered an internal interface and is likely to change in future versions.

This code is called by Java programs to access the entry points of the HDF5 library. Each routine wraps a single HDF5 entry point, generally with the arguments and return codes analogous to the C interface.

For details of the HDF5 library, see the HDF5 Documentation at: http://hdf.ncsa.uiuc.edu/HDF5/

Mapping of arguments for Java

In general, arguments to the HDF Java API are straightforward translations from the 'C' API described in the HDF Reference Manual.

HDF-5 C types to Java types
HDF-5 | Java
H5T_NATIVE_INT | int, Integer
H5T_NATIVE_SHORT | short, Short
H5T_NATIVE_FLOAT | float, Float
H5T_NATIVE_DOUBLE | double, Double
H5T_NATIVE_CHAR | byte, Byte
H5T_C_S1 | java.lang.String
void * (i.e., pointer to `Any') | Special -- see HDFArray

General Rules for Passing Arguments and Results

In general, arguments passed IN to Java are the analogous basic types, as above. The exception is for arrays, which are discussed below.

The return value of Java methods is also the analogous type, as above. A major exception to that rule is that all HDF functions that return SUCCEED/FAIL are declared boolean in the Java version, rather than int as in the C. Functions that return a value or else FAIL are declared the equivalent to the C function. However, in most cases the Java method will raise an exception instead of returning an error code. See Errors and Exceptions below.

Java does not support pass by reference of arguments, so arguments that are returned through OUT parameters must be wrapped in an object or array. The Java API for HDF consistently wraps arguments in arrays.

For instance, a function that returns two integers is declared:

           h_err_t HDF5dummy( int *a1, int *a2)

For the Java interface, this would be declared:

     public static native int HDF5dummy(int args[]);

where a1 is args[0] and a2 is args[1], and would be invoked:

     H5.HDF5dummy(a);

All the routines where this convention is used will have specific documentation of the details, given below.

HDF-5 Constants

The HDF-5 API defines a set of constants and enumerated values. Most of these values are available to Java programs via the class `HDF55Constants`. For example, the parameters for the h5open() call include two numeric values, `HDF5Constants.H5F_ACC_RDWR` and `HDF5Constants.H5P_DEFAULT`. As would be expected, these numbers correspond to the C constants `H5F_ACC_RDWR` and `H5P_DEFAULT`.

The HDF-5 API defines a set of values that describe number types and sizes, such as "H5T_NATIVE_INT" and "hsize_t". These values are determined at run time by the HDF-5 C library. To support these parameters, the Java class `HDF55Constants` looks up the values when initiated. The values can be accessed as public variables of the Java class, such as:

     int data_type = HDF55Constants.JH5T_NATIVE_INT;

The Java application uses both types of constants the same way, the only difference is that the `HDF55Constants` may have different values on different platforms.

Error handling and Exceptions

The HDF5 error API (H5E) manages the behavior of the error stack in the HDF-5 library. This API is omitted from the JHI5. Errors are converted into Java exceptions. This is totally different from the C interface, but is very natural for Java programming.

The exceptions of the JHI5 are organized as sub-classes of the class `HDF5Exception`. There are two subclasses of `HDF5Exception`, `HDF5LibraryException` and `HDF5JavaException`. The sub-classes of the former represent errors from the HDF-5 C library, while sub-classes of the latter represent errors in the JHI5 wrapper and support code.

The super-class `HDF5LibraryException` implements the method '`printStackTrace()`', which prints out the HDF-5 error stack, as described in the HDF-5 C API H5Eprint(). This may be used by Java exception handlers to print out the HDF-5 error stack.