diff options
Diffstat (limited to 'java/src/hdf/hdf5lib/package-info.java')
| -rw-r--r-- | java/src/hdf/hdf5lib/package-info.java | 114 |
1 files changed, 56 insertions, 58 deletions
diff --git a/java/src/hdf/hdf5lib/package-info.java b/java/src/hdf/hdf5lib/package-info.java index c04b862..7ae4df9 100644 --- a/java/src/hdf/hdf5lib/package-info.java +++ b/java/src/hdf/hdf5lib/package-info.java @@ -12,10 +12,11 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /** + @page HDF5LIB_UG HDF5 Java Package * This package is the Java interface for the HDF5 library. * <p> - * This code is the called by Java programs to access the entry points of the HDF5 library. Each routine wraps - a single + * 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. * <p> * For details of the HDF5 library, see the HDF5 Documentation at: @@ -25,14 +26,13 @@ * <b>Mapping of arguments for Java</b> * * <p> - * In general, arguments to the HDF Java API are straightforward translations from the 'C' API described in - the HDF - * Reference Manual. + * In general, arguments to the HDF Java API are straightforward translations from the 'C' API described + * in the HDF Reference Manual. * * <table border=1> - * <caption><b>HDF-5 C types to Java types</b> </caption> + * <caption><b>HDF5 C types to Java types</b> </caption> * <tr> - * <td><b>HDF-5</b></td> + * <td><b>HDF5</b></td> * <td><b>Java</b></td> * </tr> * <tr> @@ -60,28 +60,27 @@ * <td>java.lang.String</td> * </tr> * <tr> - * <td>void * <BR> + * <td>void * <br /> * (i.e., pointer to `Any')</td> * <td>Special -- see HDFArray</td> * </tr> * </table> * <b>General Rules for Passing Arguments and Results</b> * <p> - * In general, arguments passed <b>IN</b> to Java are the analogous basic types, as above. The exception is - for arrays, - * which are discussed below. + * In general, arguments passed <b>IN</b> to Java are the analogous basic types, as above. The exception + * is for arrays, which are discussed below. * <p> * The <i>return value</i> of Java methods is also the analogous type, as above. A major exception to that - rule is that + * rule is that * all HDF functions that return SUCCEED/FAIL are declared <i>boolean</i> in the Java version, rather than - <i>int</i> as + * <i>int</i> as * in the C. Functions that return a value or else FAIL are declared the equivalent to the C function. - However, in most + * However, in most * cases the Java method will raise an exception instead of returning an error code. - * See <a href="#ERRORS">Errors and Exceptions</a> below. + * @see @ref ERRORS. * <p> * Java does not support pass by reference of arguments, so arguments that are returned through <b>OUT</b> - parameters + * parameters * must be wrapped in an object or array. The Java API for HDF consistently wraps arguments in arrays. * <p> * For instance, a function that returns two integers is declared: @@ -104,12 +103,12 @@ * * <p> * All the routines where this convention is used will have specific documentation of the details, given - below. + * below. * <p> * <b>Arrays</b> * <p> * HDF5 needs to read and write multi-dimensional arrays of any number type (and records). The HDF5 API - describes the + * describes the * layout of the source and destination, and the data for the array passed as a block of bytes, for instance, * * <pre> @@ -118,52 +117,52 @@ * * <p> * where ``void *'' means that the data may be any valid numeric type, and is a contiguous block of bytes that - is the + * is the * data for a multi-dimensional array. The other parameters describe the dimensions, rank, and datatype of the - array on + * array on * disk (source) and in memory (destination). * <p> * For Java, this ``ANY'' is a problem, as the type of data must always be declared. Furthermore, - multidimensional + * multidimensional * arrays are definitely <i>not</i> laid out contiguously in memory. It would be infeasible to declare a - separate + * separate * routine for every combination of number type and dimensionality. For that reason, the - * <a href="./hdf.hdf5lib.HDFArray.html"><b>HDFArray</b></a> class is used to discover the type, shape, and - size of the + * <a href="./HDFArray.html"><b>HDFArray</b></a> 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. + * native C order. * <p> * The upshot is that any Java array of numbers (either primitive or sub-classes of type <b>Number</b>) can be - passed as + * passed as * an ``Object'', and the Java API will translate to and from the appropriate packed array of bytes needed by - the C + * the C * library. So the function above would be declared: * * <pre> * public synchronized static native int H5Dread(long fid, long filetype, long memtype, long memspace, Object - data); + * data); * </pre> * OPEN_IDS.addElement(id); * and the parameter <i>data</i> can be any multi-dimensional array of numbers, such as float[][], or - int[][][], or + * int[][][], or * Double[][]. * <p> - * <b>HDF-5 Constants</b> + * <b>HDF5 Constants</b> * <p> - * The HDF-5 API defines a set of constants and enumerated values. Most of these values are available to Java - programs - * via the class <a href="./hdf.hdf5lib.HDF5Constants.html"> <b>HDF5Constants</b></a>. For example, the - parameters for + * The HDF5 API defines a set of constants and enumerated values. Most of these values are available to Java + * programs + * via the class <a href="./HDF5Constants.html"> <b>HDF5Constants</b></a>. For example, the + * parameters for * the h5open() call include two numeric values, <b><i>HDFConstants.H5F_ACC_RDWR</i></b> and * <b><i>HDF5Constants.H5P_DEFAULT</i></b>. As would be expected, these numbers correspond to the C constants * <b><i>H5F_ACC_RDWR</i></b> and <b><i>H5P_DEFAULT</i></b>. * <p> - * 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 - * <a href="./hdf.hdf5lib.HDF5CDataTypes.html"> <b>HDF5CDataTypes</b></a> looks up the values when initiated. - The values + * 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 + * <a href="./HDF5CDataTypes.html"> <b>HDF5CDataTypes</b></a> looks up the values when initiated. + * The values * can be accessed as public variables of the Java class, such as: * * <pre> @@ -175,31 +174,30 @@ * <p> * <b>Error handling and Exceptions</b> * <p> - * The HDF5 error API (H5E) manages the behavior of the error stack in the HDF-5 library. This API is - available from the + * 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 + * very natural * for Java programming. * <p> * The exceptions of the JHI5 are organized as sub-classes of the class - * <a href="./hdf.hdf5lib.exceptions.HDF5Exception.html"> <b>HDF5Exception</b></a>. There are two subclasses - of - * <b>HDF5Exception</b>, <a href="./hdf.hdf5lib.exceptions.HDF5LibraryException.html"> - <b>HDF5LibraryException</b></a> - * and <a href="./hdf.hdf5lib.exceptions.HDF5JavaException.html"> <b>HDF5JavaException</b></a>. 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. - * <p> - * The super-class <b><i>HDF5LibraryException</i></b> implements the method '<b><i>printStackTrace()</i></b>', - which - * prints out the HDF-5 error stack, as described in the HDF-5 C API <i><b>H5Eprint()</b>.</i> This may be - used by Java - * exception handlers to print out the HDF-5 error stack. + * <a href="./HDF5Exception.html"> <b>HDF5Exception</b></a>. There are two subclasses + * of + * <b>HDF5Exception</b>, @ref ERRORSLIB <b>HDF5LibraryException</b> + * and @ref ERRORSJAVA <b>HDF5JavaException</b>. + * 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. + * <p> + * The super-class <b><i>HDF5LibraryException</i></b> implements the method + * '<b><i>printStackTrace()</i></b>', which prints out the HDF5 error stack, as described + * in the HDF5 C API <i><b>@ref H5Eprint()</b>.</i> This may be + * used by Java + * exception handlers to print out the HDF5 error stack. * <hr> * - * <b>See also: <a href="http://hdfgroup.org/HDF5/"> http://hdfgroup.org/HDF5"</a></b> + * @ref HDF5LIB + * + * <b>@see: <a href="http://hdfgroup.org/HDF5/"> HDF5"</a></b> * */ package hdf.hdf5lib; |