projects / OpenSPARC-T2-SAM / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 architecture model.
[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / swig / Java.html
CommitLineData
920dae64
AT		 1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3<head>
4<title>SWIG and Java</title>
5<link rel="stylesheet" type="text/css" href="style.css">
6</head>
7<body bgcolor="#FFFFFF">
8<H1><a name="Java"></a>19 SWIG and Java</H1>
9<!-- INDEX -->
10<div class="sectiontoc">
11<ul>
12<li><a href="#java_overview">Overview</a>
13<li><a href="#java_preliminaries">Preliminaries</a>
14<ul>
15<li><a href="#running_swig">Running SWIG</a>
16<li><a href="#java_commandline">Additional Commandline Options</a>
17<li><a href="#getting_right_headers">Getting the right header files</a>
18<li><a href="#compiling_dynamic">Compiling a dynamic module</a>
19<li><a href="#using_module">Using your module</a>
20<li><a href="#dynamic_linking_problems">Dynamic linking problems</a>
21<li><a href="#compilation_problems_cpp">Compilation problems and compiling with C++</a>
22<li><a href="#building_windows">Building on Windows</a>
23<ul>
24<li><a href="#visual_studio">Running SWIG from Visual Studio</a>
25<li><a href="#nmake">Using NMAKE</a>
26</ul>
27</ul>
28<li><a href="#java_basic_tour">A tour of basic C/C++ wrapping</a>
29<ul>
30<li><a href="#module_packages_classes">Modules, packages and generated Java classes</a>
31<li><a href="#functions">Functions</a>
32<li><a href="#global_variables">Global variables</a>
33<li><a href="#constants">Constants</a>
34<li><a href="#enumerations">Enumerations</a>
35<ul>
36<li><a href="#anonymous_enums">Anonymous enums</a>
37<li><a href="#typesafe_enums">Typesafe enums</a>
38<li><a href="#proper_enums">Proper Java enums</a>
39<li><a href="#typeunsafe_enums">Type unsafe enums</a>
40<li><a href="#simple_enums">Simple enums</a>
41</ul>
42<li><a href="#pointers">Pointers</a>
43<li><a href="#structures">Structures</a>
44<li><a href="#classes">C++ classes</a>
45<li><a href="#inheritance">C++ inheritance</a>
46<li><a href="#pointers_refs_arrays">Pointers, references, arrays and pass by value</a>
47<ul>
48<li><a href="#null_pointers">Null pointers</a>
49</ul>
50<li><a href="#overloaded_functions">C++ overloaded functions</a>
51<li><a href="#java_default_arguments">C++ default arguments</a>
52<li><a href="#namespaces">C++ namespaces</a>
53<li><a href="#templates">C++ templates</a>
54<li><a href="#smart_pointers">C++ Smart Pointers</a>
55</ul>
56<li><a href="#further_details">Further details on the generated Java classes</a>
57<ul>
58<li><a href="#imclass">The intermediary JNI class</a>
59<ul>
60<li><a href="#imclass_pragmas">The intermediary JNI class pragmas</a>
61</ul>
62<li><a href="#java_module_class">The Java module class</a>
63<ul>
64<li><a href="#module_class_pragmas">The Java module class pragmas</a>
65</ul>
66<li><a href="#java_proxy_classes">Java proxy classes</a>
67<ul>
68<li><a href="#memory_management">Memory management</a>
69<li><a href="#inheritance_mirroring">Inheritance</a>
70<li><a href="#proxy_classes_gc">Proxy classes and garbage collection</a>
71</ul>
72<li><a href="#type_wrapper_classes">Type wrapper classes</a>
73<li><a href="#enum_classes">Enum classes</a>
74<ul>
75<li><a href="#typesafe_enums_classes">Typesafe enum classes</a>
76<li><a href="#proper_enums_classes">Proper Java enum classes</a>
77<li><a href="#typeunsafe_enums_classes">Type unsafe enum classes</a>
78</ul>
79</ul>
80<li><a href="#java_directors">Cross language polymorphism using directors (experimental)</a>
81<ul>
82<li><a href="#java_enabling_directors">Enabling directors</a>
83<li><a href="#java_directors_classes">Director classes</a>
84<li><a href="#java_directors_overhead">Overhead and code bloat</a>
85<li><a href="#java_directors_example">Simple directors example</a>
86</ul>
87<li><a href="#common_customization">Common customization features</a>
88<ul>
89<li><a href="#helper_functions">C/C++ helper functions</a>
90<li><a href="#class_extension">Class extension with %extend</a>
91<li><a href="#exception_handling">Exception handling with %exception and %javaexception</a>
92<li><a href="#method_access">Method access with %javamethodmodifiers</a>
93</ul>
94<li><a href="#tips_techniques">Tips and techniques</a>
95<ul>
96<li><a href="#input_output_parameters">Input and output parameters using primitive pointers and references</a>
97<li><a href="#simple_pointers">Simple pointers</a>
98<li><a href="#c_arrays">Wrapping C arrays with Java arrays</a>
99<li><a href="#unbounded_c_arrays">Unbounded C Arrays</a>
100</ul>
101<li><a href="#java_typemaps">Java typemaps</a>
102<ul>
103<li><a href="#default_primitive_type_mappings">Default primitive type mappings</a>
104<li><a href="#jvm64">Sixty four bit JVMs</a>
105<li><a href="#what_is_typemap">What is a typemap?</a>
106<li><a href="#typemaps_c_to_java_types">Typemaps for mapping C/C++ types to Java types</a>
107<li><a href="#typemap_attributes">Java typemap attributes</a>
108<li><a href="#special_variables">Java special variables</a>
109<li><a href="#typemaps_for_c_and_c++">Typemaps for both C and C++ compilation</a>
110<li><a href="#java_code_typemaps">Java code typemaps</a>
111<li><a href="#java_directors_typemaps">Director specific typemaps</a>
112</ul>
113<li><a href="#typemap_examples">Typemap Examples</a>
114<ul>
115<li><a href="#simpler_enum_classes">Simpler Java enums for enums without initializers</a>
116<li><a href="#exception_typemap">Handling C++ exception specifications as Java exceptions</a>
117<li><a href="#nan_exception_typemap">NaN Exception - exception handling for a particular type</a>
118<li><a href="#converting_java_string_arrays">Converting Java String arrays to char ** </a>
119<li><a href="#expanding_java_object">Expanding a Java object to multiple arguments</a>
120<li><a href="#using_typemaps_return_arguments">Using typemaps to return arguments</a>
121<li><a href="#adding_downcasts">Adding Java downcasts to polymorphic return types</a>
122<li><a href="#adding_equals_method">Adding an equals method to the Java classes</a>
123<li><a href="#void_pointers">Void pointers and a common Java base class</a>
124<li><a href="#struct_pointer_pointer">Struct pointer to pointer</a>
125</ul>
126<li><a href="#java_directors_faq">Living with Java Directors</a>
127<li><a href="#odds_ends">Odds and ends</a>
128<ul>
129<li><a href="#javadoc_comments">JavaDoc comments</a>
130<li><a href="#functional_interface">Functional interface without proxy classes</a>
131<li><a href="#using_own_jni_functions">Using your own JNI functions</a>
132<li><a href="#performance">Performance concerns and hints</a>
133</ul>
134<li><a href="#java_examples">Examples</a>
135</ul>
136</div>
137<!-- INDEX -->
138
139
140
141<p>
142This chapter describes SWIG's support of Java.
143It covers most SWIG features, but certain low-level details are covered in less depth than in earlier chapters.
144</p>
145
146
147<H2><a name="java_overview"></a>19.1 Overview</H2>
148
149
150<p>
151The 100% Pure Java effort is a commendable concept, however in the real world programmers often either need to re-use their existing code or in some situations
152want to take advantage of Java but are forced into using some native (C/C++) code.
153The Java extension to SWIG makes it very easy to plumb in existing C/C++ code for access from Java, as SWIG writes the Java Native Interface (JNI) code for you.
154It is different to using the 'javah' tool as SWIG will wrap existing C/C++ code, whereas javah takes 'native' Java function declarations and creates C/C++ function prototypes.
155SWIG wraps C/C++ code using Java proxy classes and is very useful if you want to have access to large amounts of C/C++ code from Java.
156If only one or two JNI functions are needed then using SWIG may be overkill.
157SWIG enables a Java program to easily call into C/C++ code from Java.
158Historically, SWIG was not able to generate any code to call into Java code from C++.
159However, SWIG now supports full cross language polymorphism and code is generated to call up from C++ to Java when wrapping C++ virtual methods.
160</p>
161
162<p>
163Java is one of the few non-scripting language modules in SWIG.
164As SWIG utilizes the type safety that the Java language offers, it takes a somewhat different approach to that used for scripting languages.
165In particular runtime type checking and the runtime library are not used by Java.
166This should be borne in mind when reading the rest of the SWIG documentation.
167This chapter on Java is relatively self contained and will provide you with nearly everything you need for using SWIG and Java.
168However, the "<a href="SWIG.html#SWIG">SWIG Basics</a>" chapter will be a useful read in conjunction with this one.
169</p>
170
171<p>
172This chapter starts with a few practicalities on running SWIG and compiling the generated code.
173If you are looking for the minimum amount to read, have a look at the sections up to and including the
174<a href="#java_basic_tour">tour of basic C/C++ wrapping</a> section which explains how to call the various C/C++ code constructs from Java.
175Following this section are details of the C/C++ code and Java classes that SWIG generates.
176Due to the complexities of C and C++ there are different ways in which C/C++ code could be wrapped and called from Java.
177SWIG is a powerful tool and the rest of the chapter details how the default code wrapping can be tailored.
178Various customisation tips and techniques using SWIG directives are covered.
179The latter sections cover the advanced techniques of using typemaps for complete control of the wrapping process.
180</p>
181
182<H2><a name="java_preliminaries"></a>19.2 Preliminaries</H2>
183
184
185<p>
186SWIG 1.1 works with JDKs from JDK 1.1 to JDK1.4 (Java 2 SDK1.4) and should also work with any later versions.
187Given the choice, you should probably use the latest version of Sun's JDK.
188The SWIG Java module is known to work using Sun's JVM on Solaris, Linux and the various flavours of Microsoft Windows including Cygwin.
189The Kaffe JVM is known to give a few problems and at the time of writing was not a fully fledged JVM with full JNI support.
190The generated code is also known to work on vxWorks using WindRiver's PJava 3.1.
191The best way to determine whether your combination of operating system and JDK will work is to test the examples and test-suite that comes with SWIG.
192Run <tt>make -k check</tt> from the SWIG root directory after installing SWIG on Unix systems. </p>
193
194<p>
195The Java module requires your system to support shared libraries and dynamic loading.
196This is the commonly used method to load JNI code so your system will more than likely support this.</p>
197
198<H3><a name="running_swig"></a>19.2.1 Running SWIG</H3>
199
200
201<p>
202Suppose that you defined a SWIG module such as the following:
203</p>
204
205<div class="code">
206<pre>
207%module example
208%{
209#include "header.h"
210%}
211int fact(int n);
212</pre>
213</div>
214
215
216<p>
217To build a Java module, run SWIG using the <tt>-java</tt> option :</p>
218
219<div class="code"><pre>
220%swig -java example.i
221</pre></div>
222
223<p>
224If building C++, add the <tt>-c++</tt> option:
225</p>
226
227<div class="code"><pre>
228$ swig -c++ -java example.i
229</pre></div>
230
231<p>
232This creates two different files; a C/C++ source file <tt>example_wrap.c</tt> or
233<tt>example_wrap.cxx</tt> and numerous Java files. The generated
234C/C++ source file contains the JNI wrapper code that needs to be compiled and linked with the
235rest of your C/C++ application.
236</p>
237
238<p>
239The name of the wrapper file is derived from the name of the input file. For example, if the
240input file is <tt>example.i</tt>, the name of the wrapper file is <tt>example_wrap.c</tt>.
241To change this, you can use the <tt>-o</tt> option.
242It is also possible to change the <a href="SWIG.html#output">output directory </a> that the Java files are generated into using <tt>-outdir</tt>.
243</p>
244
245<H3><a name="java_commandline"></a>19.2.2 Additional Commandline Options</H3>
246
247
248<p>
249The following table list the additional commandline options available for the Java module. They can also be seen by using:
250</p>
251
252<div class="code"><pre>
253swig -java -help
254</pre></div>
255
256<table summary="Java specific options">
257<tr>
258<th>Java specific options</th>
259</tr>
260
261<tr>
262<td>-package &lt;name&gt;</td>
263<td>set name of the Java package to &lt;name&gt;</td>
264</tr>
265
266<tr>
267<td>-noproxy</td>
268<td>generate the low-level functional interface instead of proxy classes </td>
269</tr>
270
271</table>
272
273<p>
274Their use will become clearer by the time you have finished reading this section on SWIG and Java.
275</p>
276
277<H3><a name="getting_right_headers"></a>19.2.3 Getting the right header files</H3>
278
279
280<p>
281In order to compile the C/C++ wrappers, the compiler needs the <tt>jni.h</tt> and <tt>jni_md.h</tt> header files which are part of the JDK.
282They are usually in directories like this:</p>
283
284<div class="code"><pre>
285/usr/java/include
286/usr/java/include/&lt;operating_system&gt;
287</pre></div>
288
289<p>
290The exact location may vary on your machine, but the above locations are typical. </p>
291
292<H3><a name="compiling_dynamic"></a>19.2.4 Compiling a dynamic module</H3>
293
294
295<p>
296The JNI code exists in a dynamic module or shared library (DLL on Windows) and gets loaded by the JVM.
297To build a shared library file, you need to compile your module in a manner similar to the following (shown for Solaris):</p>
298
299<div class="code"><pre>
300$ swig -java example.i
301$ gcc -c example_wrap.c -I/usr/java/include -I/usr/java/include/solaris
302$ ld -G example_wrap.o -o libexample.so
303</pre></div>
304
305<p>
306The exact commands for doing this vary from platform to platform.
307However, SWIG tries to guess the right options when it is installed. Therefore,
308you may want to start with one of the examples in the <tt>Examples/java</tt>
309directory. If that doesn't work, you will need to read the man-pages for
310your compiler and linker to get the right set of options. You might also
311check the <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl">SWIG Wiki</a> for
312additional information.
313</p>
314
315<p>
316The name of the shared library output file is important.
317If the name of your SWIG module is "<tt>example</tt>", the name of the corresponding shared library file should be "<tt>libexample.so</tt>" (or equivalent depending on your machine, see <a href="#dynamic_linking_problems">Dynamic linking problems</a> for more information).
318The name of the module is specified using the <tt>%module</tt> directive or<tt> -module</tt> command line option.</p>
319
320<H3><a name="using_module"></a>19.2.5 Using your module</H3>
321
322
323<p>
324To load your shared native library module in Java, simply use Java's <tt>System.loadLibrary</tt> method in a Java class:</p>
325
326<div class="code"><pre>
327// main.java
328
329public class main {
330 static {
331