From b823ddc52636596a886c9cc8424142b7c28a1b29 Mon Sep 17 00:00:00 2001 From: Allen Byrne <50328838+byrnHDF@users.noreply.github.com> Date: Tue, 16 Nov 2021 23:13:59 -0600 Subject: Add javadoc to packages - HDFFV-11285 (#1197) --- MANIFEST | 4 + java/src/hdf/hdf5lib/CMakeLists.txt | 22 ++- java/src/hdf/hdf5lib/H5.java | 16 +- java/src/hdf/hdf5lib/callbacks/package-info.java | 27 ++++ java/src/hdf/hdf5lib/exceptions/package-info.java | 31 ++++ java/src/hdf/hdf5lib/package-info.java | 174 ++++++++++++++++++++++ java/src/hdf/hdf5lib/structs/package-info.java | 17 +++ 7 files changed, 282 insertions(+), 9 deletions(-) create mode 100644 java/src/hdf/hdf5lib/callbacks/package-info.java create mode 100644 java/src/hdf/hdf5lib/exceptions/package-info.java create mode 100644 java/src/hdf/hdf5lib/package-info.java create mode 100644 java/src/hdf/hdf5lib/structs/package-info.java diff --git a/MANIFEST b/MANIFEST index 7bcf0c0..0030b6e 100644 --- a/MANIFEST +++ b/MANIFEST @@ -3293,6 +3293,7 @@ ./java/src/hdf/hdf5lib/callbacks/H5P_prp_set_func_cb.java ./java/src/hdf/hdf5lib/callbacks/H5P_iterate_cb.java ./java/src/hdf/hdf5lib/callbacks/H5P_iterate_t.java +./java/src/hdf/hdf5lib/callbacks/package-info.java ./java/src/hdf/hdf5lib/exceptions/HDF5AttributeException.java ./java/src/hdf/hdf5lib/exceptions/HDF5BtreeException.java @@ -3318,6 +3319,7 @@ ./java/src/hdf/hdf5lib/exceptions/HDF5ReferenceException.java ./java/src/hdf/hdf5lib/exceptions/HDF5ResourceUnavailableException.java ./java/src/hdf/hdf5lib/exceptions/HDF5SymbolTableException.java +./java/src/hdf/hdf5lib/exceptions/package-info.java ./java/src/hdf/hdf5lib/structs/H5_ih_info_t.java ./java/src/hdf/hdf5lib/structs/H5A_info_t.java @@ -3332,12 +3334,14 @@ ./java/src/hdf/hdf5lib/structs/H5O_info_t.java ./java/src/hdf/hdf5lib/structs/H5O_native_info_t.java ./java/src/hdf/hdf5lib/structs/H5O_token_t.java +./java/src/hdf/hdf5lib/structs/package-info.java ./java/src/hdf/hdf5lib/H5.java ./java/src/hdf/hdf5lib/HDF5Constants.java ./java/src/hdf/hdf5lib/HDF5GroupInfo.java ./java/src/hdf/hdf5lib/HDFArray.java ./java/src/hdf/hdf5lib/HDFNativeData.java +./java/src/hdf/hdf5lib/package-info.java ./java/examples/Makefile.am ./java/examples/CMakeLists.txt diff --git a/java/src/hdf/hdf5lib/CMakeLists.txt b/java/src/hdf/hdf5lib/CMakeLists.txt index 5651031..a26e117 100644 --- a/java/src/hdf/hdf5lib/CMakeLists.txt +++ b/java/src/hdf/hdf5lib/CMakeLists.txt @@ -40,6 +40,11 @@ set (HDF5_JAVA_HDF_HDF5_CALLBACKS_SOURCES callbacks/Callbacks.java ) +set (HDF5_JAVADOC_HDF_HDF5_CALLBACKS_SOURCES + ${HDF5_JAVA_HDF_HDF5_CALLBACKS_SOURCES} + callbacks/package-info.java +) + set (HDF5_JAVA_HDF_HDF5_EXCEPTIONS_SOURCES exceptions/HDF5Exception.java exceptions/HDF5IdException.java @@ -67,6 +72,11 @@ set (HDF5_JAVA_HDF_HDF5_EXCEPTIONS_SOURCES exceptions/HDF5SymbolTableException.java ) +set (HDF5_JAVADOC_HDF_HDF5_EXCEPTIONS_SOURCES + ${HDF5_JAVA_HDF_HDF5_EXCEPTIONS_SOURCES} + exceptions/package-info.java +) + set (HDF5_JAVA_HDF_HDF5_STRUCTS_SOURCES structs/H5_ih_info_t.java structs/H5A_info_t.java @@ -83,6 +93,11 @@ set (HDF5_JAVA_HDF_HDF5_STRUCTS_SOURCES structs/H5O_token_t.java ) +set (HDF5_JAVADOC_HDF_HDF5_STRUCTS_SOURCES + ${HDF5_JAVA_HDF_HDF5_STRUCTS_SOURCES} + structs/package-info.java +) + set (HDF5_JAVA_HDF_HDF5_SOURCES HDFArray.java HDF5Constants.java @@ -91,6 +106,11 @@ set (HDF5_JAVA_HDF_HDF5_SOURCES H5.java ) +set (HDF5_JAVADOC_HDF_HDF5_SOURCES + ${HDF5_JAVA_HDF_HDF5_SOURCES} + package-info.java +) + set (CMAKE_JNI_TARGET TRUE) file (WRITE ${PROJECT_BINARY_DIR}/Manifest.txt @@ -114,7 +134,7 @@ add_dependencies (${HDF5_JAVA_HDF5_LIB_TARGET} ${HDF5_JAVA_JNI_LIB_TARGET}) set_target_properties (${HDF5_JAVA_HDF5_LIB_TARGET} PROPERTIES FOLDER libraries/java) create_javadoc(hdf5_java_doc - FILES ${HDF5_JAVA_HDF_HDF5_CALLBACKS_SOURCES} ${HDF5_JAVA_HDF_HDF5_EXCEPTIONS_SOURCES} ${HDF5_JAVA_HDF_HDF5_STRUCTS_SOURCES} ${HDF5_JAVA_HDF_HDF5_SOURCES} + FILES ${HDF5_JAVADOC_HDF_HDF5_CALLBACKS_SOURCES} ${HDF5_JAVADOC_HDF_HDF5_EXCEPTIONS_SOURCES} ${HDF5_JAVADOC_HDF_HDF5_STRUCTS_SOURCES} ${HDF5_JAVADOC_HDF_HDF5_SOURCES} OVERVIEW ${HDF5_JAVA_HDF5_SRC_DIR}/overview.html CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH} WINDOWTITLE "HDF5 Java" diff --git a/java/src/hdf/hdf5lib/H5.java b/java/src/hdf/hdf5lib/H5.java index cfff680..3a485da 100644 --- a/java/src/hdf/hdf5lib/H5.java +++ b/java/src/hdf/hdf5lib/H5.java @@ -64,8 +64,8 @@ import hdf.hdf5lib.structs.H5O_token_t; * 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/ + * For details of the HDF5 library, see the HDF5 Documentation at: + * http://hdfgroup.org/HDF5/ *


*

* Mapping of arguments for Java @@ -162,8 +162,8 @@ import hdf.hdf5lib.structs.H5O_token_t; *

* For Java, this ``ANY'' is a problem, as the type of data must always be declared. Furthermore, multidimensional * arrays are definitely not layed 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 + * 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 @@ -187,8 +187,8 @@ import hdf.hdf5lib.structs.H5O_token_t; * 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 HDF5CDataTypes looks up the values when initiated. The values + * These values are determined at run time by the HDF-5 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: * *

@@ -204,8 +204,8 @@ import hdf.hdf5lib.structs.H5O_token_t;
  * 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 + * 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 diff --git a/java/src/hdf/hdf5lib/callbacks/package-info.java b/java/src/hdf/hdf5lib/callbacks/package-info.java new file mode 100644 index 0000000..0833162 --- /dev/null +++ b/java/src/hdf/hdf5lib/callbacks/package-info.java @@ -0,0 +1,27 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/** All callback definitions must derive from the Callbacks interface. Any + * derived interfaces must define a single public method named "callback". + * You are responsible for deregistering your callback (if necessary) + * in its {@link Object#finalize} method. If native code attempts to call + * a callback which has been GC'd, you will likely crash the VM. If + * there is no method to deregister the callback (e.g. atexit + * in the C library), you must ensure that you always keep a live reference + * to the callback object.

+ * A callback should generally never throw an exception, since it doesn't + * necessarily have an encompassing Java environment to catch it. Any + * exceptions thrown will be passed to the default callback exception + * handler. + */ +package hdf.hdf5lib.callbacks; diff --git a/java/src/hdf/hdf5lib/exceptions/package-info.java b/java/src/hdf/hdf5lib/exceptions/package-info.java new file mode 100644 index 0000000..8640ccb --- /dev/null +++ b/java/src/hdf/hdf5lib/exceptions/package-info.java @@ -0,0 +1,31 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/** + *

+ * The package exceptions contains error classes for the Java HDF5 Interface. + *

+ * There are two sub-classes of exceptions defined: + *

    + *
  1. + * HDF5LibraryException -- errors raised the HDF5 library code + *
  2. + * HDF5JavaException -- errors raised the HDF5 Java wrapper code + *
+ *

+ * The HDF5LibraryException is the base class for the classes that represent specific error conditions. + * In particular, HDF5LibraryException has a sub-class for each major + * error code returned by the HDF5 library. + * + */ +package hdf.hdf5lib.exceptions; \ No newline at end of file diff --git a/java/src/hdf/hdf5lib/package-info.java b/java/src/hdf/hdf5lib/package-info.java new file mode 100644 index 0000000..838a266 --- /dev/null +++ b/java/src/hdf/hdf5lib/package-info.java @@ -0,0 +1,174 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + + +/** + * This package is the Java interface for the HDF5 library. + *

+ * 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. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
HDF-5 C types to Java types
HDF-5Java
H5T_NATIVE_INTint, Integer
H5T_NATIVE_SHORTshort, Short
H5T_NATIVE_FLOATfloat, Float
H5T_NATIVE_DOUBLEdouble, Double
H5T_NATIVE_CHARbyte, Byte
H5T_C_S1java.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 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 layed 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[][]. + *

+ * 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 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 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 + * 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 HDF-5 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, 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. + *


+ * + * See also: http://hdfgroup.org/HDF5" + **/ +package hdf.hdf5lib; \ No newline at end of file diff --git a/java/src/hdf/hdf5lib/structs/package-info.java b/java/src/hdf/hdf5lib/structs/package-info.java new file mode 100644 index 0000000..8a9d97d --- /dev/null +++ b/java/src/hdf/hdf5lib/structs/package-info.java @@ -0,0 +1,17 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/** All structure definitions define java equivalents of the C structures needed + * by the C API calls. See the C API for information about the structures. + */ +package hdf.hdf5lib.structs; -- cgit v0.12