From 85711b31d83b06c2a21d0e2d39dbdc809da932f2 Mon Sep 17 00:00:00 2001 From: Allen Byrne Date: Mon, 14 Mar 2016 12:51:41 -0500 Subject: [PATCH] [svn-r29399] HDFFV-9717: add overview section to javadocs --- MANIFEST | 1 + config/cmake/HDF518_Examples.cmake.in | 4 ++ config/cmake/UseJava.cmake | 68 +++++++++++++++++-- java/src/hdf/hdf5lib/CMakeLists.txt | 1 + java/src/hdf/overview.html | 96 +++++++++++++++++++++++++++ 5 files changed, 166 insertions(+), 4 deletions(-) create mode 100644 java/src/hdf/overview.html diff --git a/MANIFEST b/MANIFEST index 7de29fbd57..88b68c53f4 100644 --- a/MANIFEST +++ b/MANIFEST @@ -2493,6 +2493,7 @@ ./java/src/hdf/CMakeLists.txt ./java/src/hdf/hdf5lib/CMakeLists.txt +./java/src/hdf/hdf5lib/overview.html ./java/src/hdf/hdf5lib/callbacks/Callbacks.java ./java/src/hdf/hdf5lib/callbacks/H5A_iterate_cb.java diff --git a/config/cmake/HDF518_Examples.cmake.in b/config/cmake/HDF518_Examples.cmake.in index 1be5c65905..135dcfc236 100644 --- a/config/cmake/HDF518_Examples.cmake.in +++ b/config/cmake/HDF518_Examples.cmake.in @@ -37,9 +37,13 @@ if(NOT DEFINED CTEST_SOURCE_NAME) endif() if(NOT DEFINED STATIC_LIBRARIES) set(STATICLIBRARIES "YES") +else(NOT DEFINED STATIC_LIBRARIES) + set(STATICLIBRARIES "NO") endif() if(NOT DEFINED FORTRAN_LIBRARIES) set(FORTRANLIBRARIES "NO") +else(NOT DEFINED FORTRAN_LIBRARIES) + set(FORTRANLIBRARIES "YES") endif() #TAR_SOURCE - name of tarfile diff --git a/config/cmake/UseJava.cmake b/config/cmake/UseJava.cmake index d6945176ee..9b2b1e06e3 100644 --- a/config/cmake/UseJava.cmake +++ b/config/cmake/UseJava.cmake @@ -184,7 +184,7 @@ # This is used by install_jni_symlink(). # JAR_FILE The location of the jar file so that you can include # it. -# CLASS_DIR The directory where the class files can be found. For +# CLASSDIR The directory where the class files can be found. For # example to use them with javah. # # :: @@ -444,7 +444,7 @@ function(add_jar _TARGET_NAME) if (_add_jar_MANIFEST) set(_MANIFEST_OPTION m) - set(_MANIFEST_VALUE ${_add_jar_MANIFEST}) + get_filename_component (_MANIFEST_VALUE "${_add_jar_MANIFEST}" ABSOLUTE) endif () if (LIBRARY_OUTPUT_PATH) @@ -865,6 +865,7 @@ endfunction () function(create_javadoc _target) set(_javadoc_packages) set(_javadoc_files) + set(_javadoc_overview) set(_javadoc_sourcepath) set(_javadoc_classpath) set(_javadoc_installpath "${CMAKE_INSTALL_PREFIX}/share/javadoc") @@ -884,6 +885,8 @@ function(create_javadoc _target) set(_state "files") elseif (${arg} STREQUAL "SOURCEPATH") set(_state "sourcepath") + elseif (${arg} STREQUAL "OVERVIEW") + set(_state "overview") elseif (${arg} STREQUAL "CLASSPATH") set(_state "classpath") elseif (${arg} STREQUAL "INSTALLPATH") @@ -907,6 +910,8 @@ function(create_javadoc _target) set(_state "files") elseif (${arg} STREQUAL "SOURCEPATH") set(_state "sourcepath") + elseif (${arg} STREQUAL "OVERVIEW") + set(_state "overview") elseif (${arg} STREQUAL "CLASSPATH") set(_state "classpath") elseif (${arg} STREQUAL "INSTALLPATH") @@ -929,6 +934,8 @@ function(create_javadoc _target) set(_state "packages") elseif (${arg} STREQUAL "SOURCEPATH") set(_state "sourcepath") + elseif (${arg} STREQUAL "OVERVIEW") + set(_state "overview") elseif (${arg} STREQUAL "CLASSPATH") set(_state "classpath") elseif (${arg} STREQUAL "INSTALLPATH") @@ -951,6 +958,8 @@ function(create_javadoc _target) set(_state "packages") elseif (${arg} STREQUAL "FILES") set(_state "files") + elseif (${arg} STREQUAL "OVERVIEW") + set(_state "overview") elseif (${arg} STREQUAL "CLASSPATH") set(_state "classpath") elseif (${arg} STREQUAL "INSTALLPATH") @@ -975,6 +984,8 @@ function(create_javadoc _target) set(_state "files") elseif (${arg} STREQUAL "SOURCEPATH") set(_state "sourcepath") + elseif (${arg} STREQUAL "OVERVIEW") + set(_state "overview") elseif (${arg} STREQUAL "INSTALLPATH") set(_state "installpath") elseif (${arg} STREQUAL "DOCTITLE") @@ -997,6 +1008,8 @@ function(create_javadoc _target) set(_state "files") elseif (${arg} STREQUAL "SOURCEPATH") set(_state "sourcepath") + elseif (${arg} STREQUAL "OVERVIEW") + set(_state "overview") elseif (${arg} STREQUAL "DOCTITLE") set(_state "doctitle") elseif (${arg} STREQUAL "WINDOWTITLE") @@ -1017,6 +1030,8 @@ function(create_javadoc _target) set(_state "files") elseif (${arg} STREQUAL "SOURCEPATH") set(_state "sourcepath") + elseif (${arg} STREQUAL "OVERVIEW") + set(_state "overview") elseif (${arg} STREQUAL "INSTALLPATH") set(_state "installpath") elseif (${arg} STREQUAL "CLASSPATH") @@ -1039,6 +1054,8 @@ function(create_javadoc _target) set(_state "files") elseif (${arg} STREQUAL "SOURCEPATH") set(_state "sourcepath") + elseif (${arg} STREQUAL "OVERVIEW") + set(_state "overview") elseif (${arg} STREQUAL "CLASSPATH") set(_state "classpath") elseif (${arg} STREQUAL "INSTALLPATH") @@ -1061,6 +1078,8 @@ function(create_javadoc _target) set(_state "files") elseif (${arg} STREQUAL "SOURCEPATH") set(_state "sourcepath") + elseif (${arg} STREQUAL "OVERVIEW") + set(_state "overview") elseif (${arg} STREQUAL "CLASSPATH") set(_state "classpath") elseif (${arg} STREQUAL "INSTALLPATH") @@ -1085,6 +1104,8 @@ function(create_javadoc _target) set(_state "files") elseif (${arg} STREQUAL "SOURCEPATH") set(_state "sourcepath") + elseif (${arg} STREQUAL "OVERVIEW") + set(_state "overview") elseif (${arg} STREQUAL "CLASSPATH") set(_state "classpath") elseif (${arg} STREQUAL "INSTALLPATH") @@ -1109,6 +1130,8 @@ function(create_javadoc _target) set(_state "files") elseif (${arg} STREQUAL "SOURCEPATH") set(_state "sourcepath") + elseif (${arg} STREQUAL "OVERVIEW") + set(_state "overview") elseif (${arg} STREQUAL "CLASSPATH") set(_state "classpath") elseif (${arg} STREQUAL "INSTALLPATH") @@ -1126,6 +1149,30 @@ function(create_javadoc _target) else () set(_javadoc_version ${arg}) endif () + elseif (${_state} STREQUAL "overview") + if (${arg} STREQUAL "PACKAGES") + set(_state "packages") + elseif (${arg} STREQUAL "FILES") + set(_state "files") + elseif (${arg} STREQUAL "SOURCEPATH") + set(_state "sourcepath") + elseif (${arg} STREQUAL "CLASSPATH") + set(_state "classpath") + elseif (${arg} STREQUAL "INSTALLPATH") + set(_state "installpath") + elseif (${arg} STREQUAL "DOCTITLE") + set(_state "doctitle") + elseif (${arg} STREQUAL "WINDOWTITLE") + set(_state "windowtitle") + elseif (${arg} STREQUAL "AUTHOR") + set(_state "author") + elseif (${arg} STREQUAL "USE") + set(_state "use") + elseif (${arg} STREQUAL "VERSION") + set(_state "version") + else () + list(APPEND _javadoc_overview ${arg}) + endif () endif () endforeach () @@ -1145,6 +1192,19 @@ function(create_javadoc _target) set(_javadoc_options ${_javadoc_options} -sourcepath ${_sourcepath}) endif () + if (_javadoc_overview) + set(_start TRUE) + foreach(_path ${_javadoc_overview}) + if (_start) + set(_overview ${_path}) + set(_start FALSE) + else () + set(_overview ${_overview}:${_path}) + endif () + endforeach() + set(_javadoc_options ${_javadoc_options} -overview ${_overview}) + endif () + if (_javadoc_classpath) set(_start TRUE) foreach(_path ${_javadoc_classpath}) @@ -1212,7 +1272,7 @@ function (create_javah) set (_output_files) if (WIN32 AND NOT CYGWIN AND CMAKE_HOST_SYSTEM_NAME MATCHES "Windows") - set(_classpath_sep ";") + set(_classpath_sep "$") else () set(_classpath_sep ":") endif() @@ -1242,7 +1302,7 @@ function (create_javah) endif() endforeach() string (REPLACE ";" "${_classpath_sep}" _classpath "${_classpath}") - list (APPEND _javah_options -classpath ${_classpath}) + list (APPEND _javah_options -classpath "${_classpath}") endif() if (_create_javah_OUTPUT_DIR) diff --git a/java/src/hdf/hdf5lib/CMakeLists.txt b/java/src/hdf/hdf5lib/CMakeLists.txt index 56c1e59c1f..c2daff41af 100644 --- a/java/src/hdf/hdf5lib/CMakeLists.txt +++ b/java/src/hdf/hdf5lib/CMakeLists.txt @@ -114,6 +114,7 @@ set_target_properties (${HDF5_JAVA_HDF5_LIB_TARGET} PROPERTIES FOLDER libraries/ create_javadoc(hdf5_java_doc FILES ${HDF5_JAVA_HDF_HDF5_CALLBACKS_SRCS} ${HDF5_JAVA_HDF_HDF5_EXCEPTIONS_SRCS} ${HDF5_JAVA_HDF_HDF5_STRUCTS_SRCS} ${HDF5_JAVA_HDF_HDF5_SRCS} + OVERVIEW ${HDF5_JAVA_HDF5_SRC_DIR}/overview.html CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH} WINDOWTITLE "HDF5 Java" DOCTITLE "

HDF5 Java Wrapper

" diff --git a/java/src/hdf/overview.html b/java/src/hdf/overview.html new file mode 100644 index 0000000000..39d75b7ff3 --- /dev/null +++ b/java/src/hdf/overview.html @@ -0,0 +1,96 @@ + + +

Java HDF5 Interface (JHI5)

+ +

What it is

+The Java HD5 Interface (JHI5) is a Java package +(hdf.hdf5lib) +that ``wraps around'' the HDF5 library. +

There are a large number of functions in the HDF5 +library (version 1.10). Some of the functions are not supported in JHI5. Most +of the unsupported functions have C function pointers, which is not currently +implemented in JHI5. + +

+ + + +
+
Note: The JHI5 does not support HDF4 or earlier.
+
+ +

The JHI5 may be used by any Java application that needs to access HDF5 +files. It is extremely important to emphasize that this package is not +a pure Java implementation of the HDF5 library. The JHI5 calls the +same HDF5 library that is used by C or FORTRAN programs. (Note that this +product cannot be used in most network browsers because it accesses the +local disk using native code.) +

The Java HDF5 Interface consists of Java classes and a dynamically +linked native library. The Java classes declare native methods, and the +library contains C functions which implement the native methods. The C +functions call the standard HDF5 library, which is linked as part of the +same library on most platforms. +

The central part of the JHI5 is the Java class +hdf.hdf5lib.H5. +The H5 class calls the standard (i.e., `native' code) HDF5 +library, with native methods for most of the HDF5 functions. + +

+How to use it

+The JHI5 is used by Java classes to call the HDF5 library, in order to +create HDF5 files, and read and write data in existing HDF5 files. +

For example, the HDF5 library has the function H5Fopen to open +an HDF5 file. The Java interface is the class +hdf.hdf5lib.H5, +which has a method: +

static native int H5Fopen(String filename, int flags, int access );
+The native method is implemented in C using the +Java +Native Method Interface (JNI). This is written something like the following: +
JNIEXPORT jint
+JNICALL Java_hdf_hdf5lib_H5_H5Fopen
+(
+ JNIEnv *env,
+ jclass class,
+ jstring hdfFile,
+ jint flags,
+ jint access)
+ {
+
+ /* ...convert Java String to (char *) */
+
+ /* call the HDF library */
+ retVal = H5Fopen((char *)file, (unsigned)flags, (hid_t)access );
+
+ /* ... */
+}
+This C function calls the HDF5 library and returns the result appropriately. +

There is one native method for each HDF entry point (several hundred +in all), which are compiled with the HDF library into a dynamically loaded +library (libhdf5_java). Note that this library must be built for each +platform. +

To call the HDF `H5Fopen' function, a Java program would +import the package 'hdf.hdf5lib.*', and invoke the method +on the class 'H5'. The Java program would look something +like this: +

import hdf.hdf5lib.*;
+
+{
+ /* ... */
+
+ try {
+ file = H5.Hopen("myFile.hdf", flags, access );
+ } catch (HDF5Exception ex) {
+ //...
+ }
+
+ /* ... */
+}
+The H5 class automatically loads the native method implementations +and the HDF5 library. + +

+To Obtain

+The JHI5 is included with the HDF5 library. + +