Debian Codegraph @

java/src/hdf/overview.html

raw
1 <body>
2
3 <h1>Java HDF Interface (JHI4)</h1>
4
5 <h2><u>What it is</u></h2>
6 The <b>Java HDF Interface (JHI4)</b> is a Java package
7 (<a href="./hdf/hdflib/package-summary.html">hdf.hdflib</a>)
8 that ``wraps around'' the HDF library.
9 <p>There are a large number of functions in the HDF
10 library (version 4.2). Some of the functions are not supported in JHI4.</p>
11
12 <table style="width:71%;text-align:center;background-color:#dbeaf5" border="1">
13 <caption>Java HDF Interface (JHI4)</caption>
14 <tr>
15 <td style="text-align:center;">
16 Note: The JHI4 only supports HDF4.
17 </td>
18 </tr>
19 </table>
20
21 <p>The JHI4 may be used by any Java application that needs to access HDF
22 files. It is extremely important to emphasize that <i>this package is not
23 a pure Java implementation of the HDF library.</i> The JHI4 calls the
24 same HDF library that is used by C or FORTRAN programs. (Note that this
25 product cannot be used in most network browsers because it accesses the
26 local disk using native code.)
27 <p>The Java HDF Interface consists of Java classes and a dynamically
28 linked native library. The Java classes declare native methods, and the
29 library contains C functions which implement the native methods. The C
30 functions call the standard HDF library, which is linked as part of the
31 same library on most platforms.
32 <p>The central part of the JHI4 is the Java class <i>
33 <a href="./hdf/hdflib/HDFLibrary.html">hdf.hdflib.HDFLibrary</a></i>.
34 The <i>HDFLibrary</i> class calls the standard (<i>i.e.</i>, `native' code) HDF
35 library, with native methods for most of the HDF4functions.
36
37 <h3>
38 <u>How to use it</u></h3>
39 The JHI4 is used by Java classes to call the HDF library, in order to
40 create HDF files, and read and write data in existing HDF files.
41 <p>For example, the HDF library has the function <b>Hopen</b> to open
42 an HDF file. The Java interface is the class <i>
43 <a href="./hdf/hdflib/HDFLibrary.html">hdf.hdflib.HDFLibrary</a></i>,
44 which has a method:
45 <pre><b>static native int Hopen(String filename, int flags, int access );</b></pre>
46 The native method is implemented in C using the
47 <a href="https://docs.oracle.com/en/java/javase/18/docs/specs/jni/index.html">Java
48 Native Method Interface </a>(JNI). This is written something like the following:
49 <pre><b>JNIEXPORT jint
50 JNICALL Java_hdf_hdflib_HDFLibrary_Hopen
51 (
52 &nbsp;JNIEnv *env,
53 &nbsp;jclass class,
54 &nbsp;jstring hdfFile,
55 &nbsp;jint flags,
56 &nbsp;jint access)
57 &nbsp;{
58
59 &nbsp;/* ...convert Java String to (char *) */
60
61 &nbsp;/* call the HDF library */
62 &nbsp;retVal = Hopen((char *)file, (unsigned)flags, (hid_t)access );
63
64 &nbsp;/* ... */
65 }</b></pre>
66 This C function calls the HDF library and returns the result appropriately.
67 <p>There is one native method for each HDF entry point (several hundred
68 in all), which are compiled with the HDF library into a dynamically loaded
69 library (<i>libhdf_java</i>). Note that this library must be built for each
70 platform.
71 <p>To call the HDF `<b><i>Hopen</i></b>' function, a Java program would
72 import the package '<i><b>hdf.hdflib.*</b>'</i>, and invoke the method
73 on the class '<b><i>HDFLibrary</i></b>'. The Java program would look something
74 like this:
75 <pre><b>import hdf.hdflib.*;
76
77 {
78 &nbsp;/* ... */
79
80 &nbsp;try {
81 &nbsp;file = HDFLibrary.Hopen("myFile.hdf", flags, access );
82 &nbsp;} catch (HDFException ex) {
83 &nbsp;//...
84 &nbsp;}
85
86 &nbsp;/* ... */
87 }</b></pre>
88 The <i><b>HDFLibrary</b> </i>class automatically loads the native method implementations
89 and the HDF library.
90
91 <h3>To Obtain</h3>
92 The JHI4 is included with the <a href="https://support.hdfgroup.org/downloads/index.html">HDF</a> library.
93
94 </body>