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.