* This code is the 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://hdfgroup.org/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. * *
| HDF5 | *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 | *
* 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 @ref ERRORS. *
* 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 synchronized static native void 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. *
* Arrays *
* HDF5 needs to read and write multi-dimensional arrays of any number type (and records). The HDF5 API * describes the * layout of the source and destination, and the data for the array passed as a block of bytes, for instance, * *
* herr_t H5Dread(long fid, long filetype, long memtype, long memspace, void *data); ** *
* where ``void *'' means that the data may be any valid numeric type, and is a contiguous block of bytes that * is the * data for a multi-dimensional array. The other parameters describe the dimensions, rank, and datatype of the * array on * disk (source) and in memory (destination). *
* For Java, this ``ANY'' is a problem, as the type of data must always be declared. Furthermore, * multidimensional * arrays are definitely not laid out contiguously in memory. It would be infeasible to declare a * separate * routine for every combination of number type and dimensionality. For that reason, the * HDFArray class is used to discover the type, shape, and * size of the * data array at run time, and to convert to and from a contiguous array of bytes in synchronized static * native C order. *
* The upshot is that any Java array of numbers (either primitive or sub-classes of type Number) can be * passed as * an ``Object'', and the Java API will translate to and from the appropriate packed array of bytes needed by * the C * library. So the function above would be declared: * *
* public synchronized static native int H5Dread(long fid, long filetype, long memtype, long memspace, Object * data); ** OPEN_IDS.addElement(id); * and the parameter data can be any multi-dimensional array of numbers, such as float[][], or * int[][][], or * Double[][]. *
* HDF5 Constants *
* The HDF5 API defines a set of constants and enumerated values. Most of these values are available to Java * programs * via the class HDF5Constants. For example, the * parameters for * the h5open() call include two numeric values, HDFConstants.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 HDF5 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 HDF5 C library. To support these parameters, the Java class * HDF5CDataTypes looks up the values when initiated. * The values * can be accessed as public variables of the Java class, such as: * *
* long data_type = HDF5CDataTypes.JH5T_NATIVE_INT; ** * The Java application uses both types of constants the same way, the only difference is that the * HDF5CDataTypes 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 HDF5 library. This API is * available 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, @ref ERRORSLIB HDF5LibraryException * and @ref ERRORSJAVA HDF5JavaException. * The sub-classes of the former represent errors from the HDF5 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 HDF5 error stack, as described * in the HDF5 C API @ref H5Eprint(). This may be * used by Java * exception handlers to print out the HDF5 error stack. *