mirror/hdf5
2
0
Fork 0
mirror of https://github.com/HDFGroup/hdf5.git synced 2024-11-21 01:04:10 +08:00
Code Issues Packages Projects Releases Wiki Activity

[svn-r29399] HDFFV-9717: add overview section to javadocs

Browse Source
This commit is contained in:
Allen Byrne 2016-03-14 12:51:41 -05:00
parent 8f874a5010
commit 85711b31d8
5 changed files with 166 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
MANIFEST
View File

@ -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

4
config/cmake/HDF518_Examples.cmake.in
View File

@ -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

68
config/cmake/UseJava.cmake
View File

@ -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 "$<SEMICOLON>")
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)

1
java/src/hdf/hdf5lib/CMakeLists.txt
View File

@ -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 "<h1>HDF5 Java Wrapper</h1>"

96
java/src/hdf/overview.html Normal file
View File

@ -0,0 +1,96 @@
<body>
<h1>Java HDF5 Interface (JHI5)</h1>
<h2><u>What it is</u></h2>
The <b>Java HD5 Interface (JHI5)</b> is a Java package
(<a href="../../hdf-java-html/javadocs/hdf/hdf5lib/package-summary.html">hdf.hdf5lib</a>)
that ``wraps around'' the HDF5 library.
<p />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.
<center><table BORDER=1 COLS=1 WIDTH="71%" BGCOLOR="#dbeaf5" >
<tr>
<td>
<center>Note: The JHI5 does not support HDF4 or earlier.</center>
</td>
</tr>
</table></center>
<p>The JHI5 may be used by any Java application that needs to access HDF5
files. It is extremely important to emphasize that <i>this package is not
a pure Java implementation of the HDF5 library.</i> 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.)
<p>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.
<p>The central part of the JHI5 is the Java class <i>
<a href="../../hdf-java-html/javadocs/hdf/hdf5lib/H5.html">hdf.hdf5lib.H5</a></i>.
The <i>H5 </i>class calls the standard (<i>i.e.</i>, `native' code) HDF5
library, with native methods for most of the HDF5 functions.
<h3>
<u>How to use it</u></h3>
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.
<p>For example, the HDF5 library has the function <b>H5Fopen</b> to open
an HDF5 file. The Java interface is the class <i>
<a href="../../hdf-java-html/javadocs/hdf/hdf5lib/H5.html">hdf.hdf5lib.H5</a></i>,
which has a method:
<pre><b>static native int H5Fopen(String filename, int flags, int access );</b></pre>
The native method is implemented in C using the
<a href="http://java.sun.com/javase/6/docs/technotes/guides/jni/index.html">Java
Native Method Interface </a>(JNI). This is written something like the following:
<pre><b>JNIEXPORT jint
JNICALL Java_hdf_hdf5lib_H5_H5Fopen
(
&nbsp;JNIEnv *env,
&nbsp;jclass class,
&nbsp;jstring hdfFile,
&nbsp;jint flags,
&nbsp;jint access)
&nbsp;{
&nbsp;/* ...convert Java String to (char *) */
&nbsp;/* call the HDF library */
&nbsp;retVal = H5Fopen((char *)file, (unsigned)flags, (hid_t)access );
&nbsp;/* ... */
}</b></pre>
This C function calls the HDF5 library and returns the result appropriately.
<p>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 (<i>libhdf5_java</i>). Note that this library must be built for each
platform.
<p>To call the HDF `<b><i>H5Fopen</i></b>' function, a Java program would
import the package '<i><b>hdf.hdf5lib.*</b>'</i>, and invoke the method
on the class '<b><i>H5</i></b>'. The Java program would look something
like this:
<pre><b>import hdf.hdf5lib.*;
{
&nbsp;/* ... */
&nbsp;try {
&nbsp;file = H5.Hopen("myFile.hdf", flags, access );
&nbsp;} catch (HDF5Exception ex) {
&nbsp;//...
&nbsp;}
&nbsp;/* ... */
}</b></pre>
The <i><b>H5</b> </i>class automatically loads the native method implementations
and the HDF5 library.
<h3>
<a NAME="DOWNLOAD"></a>To Obtain</h3>
The JHI5 is included with the <a href="http://www.hdfgroup.org/HDF5/index.html">HDF5</a> library.
</body>