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