Commit | Line | Data |
---|---|---|
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> | |
142 | This chapter describes SWIG's support of Java. | |
143 | It 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> | |
151 | The 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 | |
152 | want to take advantage of Java but are forced into using some native (C/C++) code. | |
153 | The 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. | |
154 | It 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. | |
155 | SWIG 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. | |
156 | If only one or two JNI functions are needed then using SWIG may be overkill. | |
157 | SWIG enables a Java program to easily call into C/C++ code from Java. | |
158 | Historically, SWIG was not able to generate any code to call into Java code from C++. | |
159 | However, 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> | |
163 | Java is one of the few non-scripting language modules in SWIG. | |
164 | As SWIG utilizes the type safety that the Java language offers, it takes a somewhat different approach to that used for scripting languages. | |
165 | In particular runtime type checking and the runtime library are not used by Java. | |
166 | This should be borne in mind when reading the rest of the SWIG documentation. | |
167 | This chapter on Java is relatively self contained and will provide you with nearly everything you need for using SWIG and Java. | |
168 | However, 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> | |
172 | This chapter starts with a few practicalities on running SWIG and compiling the generated code. | |
173 | If 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. | |
175 | Following this section are details of the C/C++ code and Java classes that SWIG generates. | |
176 | Due to the complexities of C and C++ there are different ways in which C/C++ code could be wrapped and called from Java. | |
177 | SWIG is a powerful tool and the rest of the chapter details how the default code wrapping can be tailored. | |
178 | Various customisation tips and techniques using SWIG directives are covered. | |
179 | The 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> | |
186 | SWIG 1.1 works with JDKs from JDK 1.1 to JDK1.4 (Java 2 SDK1.4) and should also work with any later versions. | |
187 | Given the choice, you should probably use the latest version of Sun's JDK. | |
188 | The SWIG Java module is known to work using Sun's JVM on Solaris, Linux and the various flavours of Microsoft Windows including Cygwin. | |
189 | The 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. | |
190 | The generated code is also known to work on vxWorks using WindRiver's PJava 3.1. | |
191 | The 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. | |
192 | Run <tt>make -k check</tt> from the SWIG root directory after installing SWIG on Unix systems. </p> | |
193 | ||
194 | <p> | |
195 | The Java module requires your system to support shared libraries and dynamic loading. | |
196 | This 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> | |
202 | Suppose 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 | %} | |
211 | int fact(int n); | |
212 | </pre> | |
213 | </div> | |
214 | ||
215 | ||
216 | <p> | |
217 | To 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> | |
224 | If 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> | |
232 | This 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 | |
234 | C/C++ source file contains the JNI wrapper code that needs to be compiled and linked with the | |
235 | rest of your C/C++ application. | |
236 | </p> | |
237 | ||
238 | <p> | |
239 | The name of the wrapper file is derived from the name of the input file. For example, if the | |
240 | input file is <tt>example.i</tt>, the name of the wrapper file is <tt>example_wrap.c</tt>. | |
241 | To change this, you can use the <tt>-o</tt> option. | |
242 | It 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> | |
249 | The 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> | |
253 | swig -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 <name></td> | |
263 | <td>set name of the Java package to <name></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> | |
274 | Their 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> | |
281 | In 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. | |
282 | They are usually in directories like this:</p> | |
283 | ||
284 | <div class="code"><pre> | |
285 | /usr/java/include | |
286 | /usr/java/include/<operating_system> | |
287 | </pre></div> | |
288 | ||
289 | <p> | |
290 | The 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> | |
296 | The JNI code exists in a dynamic module or shared library (DLL on Windows) and gets loaded by the JVM. | |
297 | To 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> | |
306 | The exact commands for doing this vary from platform to platform. | |
307 | However, SWIG tries to guess the right options when it is installed. Therefore, | |
308 | you may want to start with one of the examples in the <tt>Examples/java</tt> | |
309 | directory. If that doesn't work, you will need to read the man-pages for | |
310 | your compiler and linker to get the right set of options. You might also | |
311 | check the <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl">SWIG Wiki</a> for | |
312 | additional information. | |
313 | </p> | |
314 | ||
315 | <p> | |
316 | The name of the shared library output file is important. | |
317 | If 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). | |
318 | The 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> | |
324 | To 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 | ||
329 | public class main { | |
330 | static { | |
331 |