ch10.htm

JAVA Developing Professional JavaApplets

<TR VALIGN=TOP><TD WIDTH=122>ArrayOfDouble</TD><TD WIDTH=154>double body[1]
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=122>ArrayOfArray</TD><TD WIDTH=154>JHandle *(body[1])
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=122>ArrayOfObject</TD><TD WIDTH=154>HObject *(body[1])
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=122>ArrayOfString</TD><TD WIDTH=154>HString *(body[1])
</TD></TR>
</TABLE></CENTER>
<P>
<P>
In contrast to JHandle and array pointers, the Java basic types
are passed and referenced as direct C types. Table 10.4 displays
all the basic Java types and their corresponding C representation.
<BR>
<P>
<CENTER><B>Table 10.4. C representation of Java basic types in
Windows 95.</B></CENTER>
<P><CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD WIDTH=90><I>Java Type</I></TD><TD WIDTH=131><I>C Representation</I>
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=90><TT>boolean</TT>
</TD><TD WIDTH=131>long</TD></TR>
<TR VALIGN=TOP><TD WIDTH=90><TT>char</TT></TD>
<TD WIDTH=131>unicode</TD></TR>
<TR VALIGN=TOP><TD WIDTH=90><TT>short</TT></TD>
<TD WIDTH=131>short</TD></TR>
<TR VALIGN=TOP><TD WIDTH=90><TT>int</TT></TD>
<TD WIDTH=131>long</TD></TR>
<TR VALIGN=TOP><TD WIDTH=90><TT>long</TT></TD>
<TD WIDTH=131>int64_t</TD></TR>
<TR VALIGN=TOP><TD WIDTH=90><TT>float</TT></TD>
<TD WIDTH=131>float</TD></TR>
<TR VALIGN=TOP><TD WIDTH=90><TT>double</TT></TD>
<TD WIDTH=131>double</TD></TR>
</TABLE></CENTER>
<P>
<P><CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD><B>Note</B></TD></TR>
<TR VALIGN=TOP><TD>
<BLOCKQUOTE>
All the type information in this chapter is specific to Windows 95. The Java type representations may be different on another platform. It is best to run <TT>javah</TT> on the Demonstration class to verify the C representations when working on a different platform. In addition, all the macros and structures discussed can be found in the Java header files in the Java/include directory. These files are specific to a given platform and, as such, should be consulted when performing native method work.
</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<P>
Now that you understand the C side of Java data, it's time to
generate the code that interfaces Java to C.
<H3><A NAME="TheStubsCode">The Stubs Code</A></H3>
<P>
Run the following command on the Demonstration class:
<BLOCKQUOTE>
<TT>javah -stubs Demonstration</TT>
</BLOCKQUOTE>
<P>
The output will be a C file in the current directory. Listing
10.3 shows the result.
<HR>
<P>
<B>Listing 10.3. The output of </B><TT><B>javah
-stubs Demonstration</FONT></B></TT><B>.<BR>
</B>
<BLOCKQUOTE>
<TT>/* DO NOT EDIT THIS FILE - it is machine
generated */<BR>
#include &lt;StubPreamble.h&gt;<BR>
<BR>
/* Stubs for class Demonstration */<BR>
/* SYMBOL: &quot;Demonstration/method1()V&quot;, Java_Demonstration_method1_stub
*/<BR>
declspec(dllexport) stack_item *<BR>
 Java_Demonstration_method1_stub(stack_item *_P_,struct execenv
*_EE_) {<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extern
void Demonstration_method1(void *);<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(void)
Demonstration_method1(_P_[0].p);<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return
_P_;<BR>
}<BR>
/* SYMBOL: &quot;Demonstration/method2(ZBCS)I&quot;, Java_Demonstration_method2_stub
*/<BR>
declspec(dllexport) stack_item *<BR>
 Java_Demonstration_method2_stub(stack_item *_P_,struct execenv
*_EE_) {<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extern
long Demonstration_method2(void *,long,long,long,long);<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;_P_[0].i
= Demonstration_method2(_P_[0].p,((_P_[1].i)),<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;((_P_[2].i)),((_P_[3].i)),
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;((_P_[4].i)));
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return
_P_ + 1;<BR>
}<BR>
/* SYMBOL: &quot;Demonstration/method3([B[Z)[B&quot;, Java_Demonstration_method3_stub
*/<BR>
declspec(dllexport) stack_item *<BR>
 Java_Demonstration_method3_stub(stack_item *_P_,struct execenv
*_EE_) {<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extern
long Demonstration_method3(void *,void *,void *);<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;_P_[0].i
= Demonstration_method3(_P_[0].p,((_P_[1].p)),((_P_[2].p)));<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return
_P_ + 1;<BR>
}<BR>
/* SYMBOL: &quot;Demonstration/method4(IJFD)[Ljava/lang/String;&quot;,
<BR>
Java_Demonstration_method4_stub */<BR>
declspec(dllexport) stack_item *<BR>
 Java_Demonstration_method4_stub(stack_item *_P_,struct execenv
*_EE_) {<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Java8
_t2;<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Java8
_t4;<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extern
long Demonstration_method4(void *,long,int64_t,float,double);
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;_P_[0].i
= Demonstration_method4(_P_[0].p,<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;((_P_[1].i)),
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
GET_INT64(_t2, _P_+2),<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;((_P_[4].f)),
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
GET_DOUBLE(_t5, _P_+5));<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return
_P_ + 1;<BR>
}</TT>
</BLOCKQUOTE>
<HR>
<P>
This file contains the stub functions for each of the four native
methods. It is the stub's job to translate Java data structures
into a C format. Once this is done, the stub will then enter your
C function. Sometimes the stub will have to do a little extra
work to make the transition. For example, take a look at <TT>method4</TT>'s
stub. The Java stack is made up of 32-bit words. Java data types
<TT>long</TT> and <TT>double</TT>
each command 64 bits of storage. The stub code calls &quot;helper&quot;
functions to extract the data from the Java stack. The stubs will
perform all the work necessary, no matter how complex, to interface
the Java stack to C.
<P>
The other interesting feature of the stub module is the <TT>SYMBOL</TT>
comment at the top of each method. Java uses a system of method
&quot;signatures&quot; to identify functions. The signature contains
the method arguments and the return type; the symbols are explained
in Table 10.5.<BR>
<P>
<CENTER><B>Table 10.5. Method signature symbols.</B></CENTER>
<P><CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD WIDTH=167><I>Type</I></TD><TD WIDTH=149><CENTER><I>Signature Character</I></CENTER>
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=167><TT>byte</TT></TD>
<TD WIDTH=149><CENTER>B</CENTER></TD></TR>
<TR VALIGN=TOP><TD WIDTH=167><TT>char</TT></TD>
<TD WIDTH=149><CENTER>C</CENTER></TD></TR>
<TR VALIGN=TOP><TD WIDTH=167><TT>class</TT></TD>
<TD WIDTH=149><CENTER>L</CENTER></TD></TR>
<TR VALIGN=TOP><TD WIDTH=167><TT>end of class</TT>
</TD><TD WIDTH=149><CENTER>;</CENTER></TD></TR>
<TR VALIGN=TOP><TD WIDTH=167><TT>float</TT></TD>
<TD WIDTH=149><CENTER>F</CENTER></TD></TR>
<TR VALIGN=TOP><TD WIDTH=167><TT>double</TT>
</TD><TD WIDTH=149><CENTER>D</CENTER></TD></TR>
<TR VALIGN=TOP><TD WIDTH=167><TT>function</TT>
</TD><TD WIDTH=149><CENTER>(</CENTER></TD></TR>
<TR VALIGN=TOP><TD WIDTH=167><TT>end of function</TT>
</TD><TD WIDTH=149><CENTER>)</CENTER></TD></TR>
<TR VALIGN=TOP><TD WIDTH=167><TT>int</TT></TD>
<TD WIDTH=149><CENTER>I</CENTER></TD></TR>
<TR VALIGN=TOP><TD WIDTH=167><TT>long</TT></TD>
<TD WIDTH=149><CENTER>J</CENTER></TD></TR>
<TR VALIGN=TOP><TD WIDTH=167><TT>short</TT></TD>
<TD WIDTH=149><CENTER>S</CENTER></TD></TR>
<TR VALIGN=TOP><TD WIDTH=167><TT>void</TT></TD>
<TD WIDTH=149><CENTER>V</CENTER></TD></TR>
<TR VALIGN=TOP><TD WIDTH=167><TT>boolean</TT>
</TD><TD WIDTH=149><CENTER>Z</CENTER></TD></TR>
</TABLE></CENTER>
<P>
<P>
Signatures are important because they enable you to make calls
back into the Java system. If you know the class, name, and signature
of a method, then these elements can be used to invoke the Java
method from within a C library. The format of a signature is as
follows:
<BLOCKQUOTE>
<TT>&quot;package_name/class_name/method_name(args*)return_type&quot;</TT>
</BLOCKQUOTE>
<P>
Arguments can be any combination of the characters in Table 10.5.
Class name arguments are written like this:
<BLOCKQUOTE>
<TT>Lclass_name;</TT>
</BLOCKQUOTE>
<P>
The semicolon signals the end of the class name, just as the right
(closing) parenthesis signals the end of an argument list. Arrays
are followed by the array type:
<BLOCKQUOTE>
<TT>[B for an array of bytes<BR>
[Ljava/langString; for an array of objects (in this case, Strings)</TT>
</BLOCKQUOTE>
<P>
The Demonstration class is not actually going to be used; it's
merely a convenient tool to demonstrate the C features of Java's
runtime environment. Now it's time to move on to the chapter project
and some actual native method code.
<H2><A NAME="ChapterProjectADatabaseInterfaceLi"><FONT SIZE=5 COLOR=#FF0000>Chapter
Project: A Database Interface Library Using ODBC</FONT></A></H2>
<P>
The goal of this project is to be able to read from a database.
Although this project uses ODBC for its database access layer,
any embedded SQL routines could be used. The database query routine
has been separated from the Java return logic within the native
method. Any database access method could easily be substituted.
In fact, if you don't have ODBC installed, a synthetic query routine
is supplied on the CD-ROM in the file FakeDatabaseImpl.c.
<P>
The project will consist of two classes and an interface library.
A container class will be used to house the query statement and
resulting data, and a second class called Database will perform
all the native methods.
<P>
Listing 10.4 lays out the SQLStmt class. The native method library
reads and writes directly to the variables in this container class.
<HR>
<BLOCKQUOTE>
<B>Listing 10.4. The SQLStmt class.<BR>
</B>
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT>import java.io.*;<BR>
import java.lang.*;<BR>
import DBException;<BR>
<BR>
/**<BR>
 * Class to contain an SQL statement and resulting data<BR>
 */<BR>
public class SQLStmt<BR>
{<BR>
&nbsp;&nbsp;&nbsp;&nbsp;// The query string<BR>
&nbsp;&nbsp;&nbsp;&nbsp;public String sqlStmt = null;<BR>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;// The actual data from the query<BR>
&nbsp;&nbsp;&nbsp;&nbsp;private String result[][];<BR>
&nbsp;&nbsp;&nbsp;&nbsp;private int nRows, nCols;<BR>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;// True if the query is successful<BR>
&nbsp;&nbsp;&nbsp;&nbsp;private boolean query = false;<BR>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;/**<BR>
&nbsp;&nbsp;&nbsp;&nbsp; * The lone constructor, you must supply
a query<BR>
&nbsp;&nbsp;&nbsp;&nbsp; * string to use this constructor<BR>
&nbsp;&nbsp;&nbsp;&nbsp; * @param stmt contains the query to execute
<BR>
&nbsp;&nbsp;&nbsp;&nbsp; */<BR>
&nbsp;&nbsp;&nbsp;&nbsp;SQLStmt(String stmt)<BR>
&nbsp;&nbsp;&nbsp;&nbsp;{<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;sqlStmt = stmt;
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;System.out.println(&quot;Statement:
&quot; + stmt);<BR>
&nbsp;&nbsp;&nbsp;&nbsp;}<BR>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;/**<BR>
&nbsp;&nbsp;&nbsp;&nbsp; * Return the number of rows in a query
data set<BR>
&nbsp;&nbsp;&nbsp;&nbsp; * @exception DBException if no query
has been made<BR>
&nbsp;&nbsp;&nbsp;&nbsp; */<BR>
&nbsp;&nbsp;&nbsp;&nbsp;public int numRows()<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;throws DBException
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;{<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if ( !query )
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;throw
new DBException(&quot;No active query&quot;);<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return nRows;
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;}<BR>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;/**<BR>
&nbsp;&nbsp;&nbsp;&nbsp; * Return the number of cols in a query
data set<BR>
&nbsp;&nbsp;&nbsp;&nbsp; * @exception DBException if no query
has been made<BR>
&nbsp;&nbsp;&nbsp;&nbsp; */<BR>
&nbsp;&nbsp;&nbsp;&nbsp;public int numCols()<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;throws DBException
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;{<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if ( !query )
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;throw
new DBException(&quot;No active query&quot;);<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return nCols;
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;}<BR>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;/**<BR>
&nbsp;&nbsp;&nbsp;&nbsp; * Retreive the contents of a row.&nbsp;&nbsp;Each
column<BR>
&nbsp;&nbsp;&nbsp;&nbsp; * is separated from the others by a pipe
'|' character.<BR>
&nbsp;&nbsp;&nbsp;&nbsp; * @param row is the row to retreive<BR>
&nbsp;&nbsp;&nbsp;&nbsp; * @exception DBException if invalid row
<BR>
&nbsp;&nbsp;&nbsp;&nbsp; */<BR>