<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG and Java</title>
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Java"></a>25 SWIG and Java</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Java_overview">Overview</a>
<li><a href="#Java_preliminaries">Preliminaries</a>
<ul>
<li><a href="#Java_running_swig">Running SWIG</a>
<li><a href="#Java_commandline">Additional Commandline Options</a>
<li><a href="#Java_getting_right_headers">Getting the right header files</a>
<li><a href="#Java_compiling_dynamic">Compiling a dynamic module</a>
<li><a href="#Java_using_module">Using your module</a>
<li><a href="#Java_dynamic_linking_problems">Dynamic linking problems</a>
<li><a href="#Java_compilation_problems_cpp">Compilation problems and compiling with C++</a>
<li><a href="#Java_building_windows">Building on Windows</a>
<ul>
<li><a href="#Java_visual_studio">Running SWIG from Visual Studio</a>
<li><a href="#Java_nmake">Using NMAKE</a>
</ul>
</ul>
<li><a href="#Java_basic_tour">A tour of basic C/C++ wrapping</a>
<ul>
<li><a href="#Java_module_packages_classes">Modules, packages and generated Java classes</a>
<li><a href="#Java_functions">Functions</a>
<li><a href="#Java_global_variables">Global variables</a>
<li><a href="#Java_constants">Constants</a>
<li><a href="#Java_enumerations">Enumerations</a>
<ul>
<li><a href="#Java_anonymous_enums">Anonymous enums</a>
<li><a href="#Java_typesafe_enums">Typesafe enums</a>
<li><a href="#Java_proper_enums">Proper Java enums</a>
<li><a href="#Java_typeunsafe_enums">Type unsafe enums</a>
<li><a href="#Java_simple_enums">Simple enums</a>
</ul>
<li><a href="#Java_pointers">Pointers</a>
<li><a href="#Java_structures">Structures</a>
<li><a href="#Java_classes">C++ classes</a>
<li><a href="#Java_inheritance">C++ inheritance</a>
<li><a href="#Java_pointers_refs_arrays">Pointers, references, arrays and pass by value</a>
<ul>
<li><a href="#Java_null_pointers">Null pointers</a>
</ul>
<li><a href="#Java_overloaded_functions">C++ overloaded functions</a>
<li><a href="#Java_default_arguments">C++ default arguments</a>
<li><a href="#Java_namespaces">C++ namespaces</a>
<li><a href="#Java_templates">C++ templates</a>
<li><a href="#Java_smart_pointers">C++ Smart Pointers</a>
</ul>
<li><a href="#Java_further_details">Further details on the generated Java classes</a>
<ul>
<li><a href="#Java_imclass">The intermediary JNI class</a>
<ul>
<li><a href="#Java_imclass_pragmas">The intermediary JNI class pragmas</a>
</ul>
<li><a href="#Java_module_class">The Java module class</a>
<ul>
<li><a href="#Java_module_class_pragmas">The Java module class pragmas</a>
</ul>
<li><a href="#Java_proxy_classes">Java proxy classes</a>
<ul>
<li><a href="#Java_memory_management">Memory management</a>
<li><a href="#Java_inheritance_mirroring">Inheritance</a>
<li><a href="#Java_proxy_classes_gc">Proxy classes and garbage collection</a>
<li><a href="#Java_pgcpp">The premature garbage collection prevention parameter for proxy class marshalling</a>
<li><a href="#Java_multithread_libraries">Single threaded applications and thread safety</a>
</ul>
<li><a href="#Java_type_wrapper_classes">Type wrapper classes</a>
<li><a href="#Java_enum_classes">Enum classes</a>
<ul>
<li><a href="#Java_typesafe_enums_classes">Typesafe enum classes</a>
<li><a href="#Java_proper_enums_classes">Proper Java enum classes</a>
<li><a href="#Java_typeunsafe_enums_classes">Type unsafe enum classes</a>
</ul>
</ul>
<li><a href="#Java_directors">Cross language polymorphism using directors</a>
<ul>
<li><a href="#Java_enabling_directors">Enabling directors</a>
<li><a href="#Java_directors_classes">Director classes</a>
<li><a href="#Java_directors_overhead">Overhead and code bloat</a>
<li><a href="#Java_directors_example">Simple directors example</a>
<li><a href="#Java_directors_threading">Director threading issues</a>
<li><a href="#Java_directors_performance">Director performance tuning</a>
<li><a href="#Java_exceptions_from_directors">Java exceptions from directors</a>
</ul>
<li><a href="#Java_allprotected">Accessing protected members</a>
<li><a href="#Java_common_customization">Common customization features</a>
<ul>
<li><a href="#Java_helper_functions">C/C++ helper functions</a>
<li><a href="#Java_class_extension">Class extension with %extend</a>
<li><a href="#Java_exception_handling">Exception handling with %exception and %javaexception</a>
<li><a href="#Java_method_access">Method access with %javamethodmodifiers</a>
</ul>
<li><a href="#Java_tips_techniques">Tips and techniques</a>
<ul>
<li><a href="#Java_input_output_parameters">Input and output parameters using primitive pointers and references</a>
<li><a href="#Java_simple_pointers">Simple pointers</a>
<li><a href="#Java_c_arrays">Wrapping C arrays with Java arrays</a>
<li><a href="#Java_unbounded_c_arrays">Unbounded C Arrays</a>
<li><a href="#Java_binary_char">Binary data vs Strings</a>
<li><a href="#Java_heap_allocations">Overriding new and delete to allocate from Java heap</a>
</ul>
<li><a href="#Java_typemaps">Java typemaps</a>
<ul>
<li><a href="#Java_default_primitive_type_mappings">Default primitive type mappings</a>
<li><a href="#Java_default_non_primitive_typemaps">Default typemaps for non-primitive types</a>
<li><a href="#Java_jvm64">Sixty four bit JVMs</a>
<li><a href="#Java_what_is_typemap">What is a typemap?</a>
<li><a href="#Java_typemaps_c_to_java_types">Typemaps for mapping C/C++ types to Java types</a>
<li><a href="#Java_typemap_attributes">Java typemap attributes</a>
<li><a href="#Java_special_variables">Java special variables</a>
<li><a href="#Java_typemaps_for_c_and_cpp">Typemaps for both C and C++ compilation</a>
<li><a href="#Java_code_typemaps">Java code typemaps</a>
<li><a href="#Java_directors_typemaps">Director specific typemaps</a>
</ul>
<li><a href="#Java_typemap_examples">Typemap Examples</a>
<ul>
<li><a href="#Java_simpler_enum_classes">Simpler Java enums for enums without initializers</a>
<li><a href="#Java_exception_typemap">Handling C++ exception specifications as Java exceptions</a>
<li><a href="#Java_nan_exception_typemap">NaN Exception - exception handling for a particular type</a>
<li><a href="#Java_converting_java_string_arrays">Converting Java String arrays to char ** </a>
<li><a href="#Java_expanding_java_object">Expanding a Java object to multiple arguments</a>
<li><a href="#Java_using_typemaps_return_arguments">Using typemaps to return arguments</a>
<li><a href="#Java_adding_downcasts">Adding Java downcasts to polymorphic return types</a>
<li><a href="#Java_adding_equals_method">Adding an equals method to the Java classes</a>
<li><a href="#Java_void_pointers">Void pointers and a common Java base class</a>
<li><a href="#Java_struct_pointer_pointer">Struct pointer to pointer</a>
<li><a href="#Java_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="#Java_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<li><a href="#Java_date_marshalling">Date marshalling using the javain typemap and associated attributes</a>
</ul>
<li><a href="#Java_directors_faq">Living with Java Directors</a>
<li><a href="#Java_odds_ends">Odds and ends</a>
<ul>
<li><a href="#Java_javadoc_comments">JavaDoc comments</a>
<li><a href="#Java_functional_interface">Functional interface without proxy classes</a>
<li><a href="#Java_using_own_jni_functions">Using your own JNI functions</a>
<li><a href="#Java_performance">Performance concerns and hints</a>
<li><a href="#Java_debugging">Debugging</a>
</ul>
<li><a href="#Java_examples">Java Examples</a>
</ul>
</div>
<!-- INDEX -->


<p>
This chapter describes SWIG's support of Java. 
It covers most SWIG features, but certain low-level details are covered in less depth than in earlier chapters. 
</p>


<H2><a name="Java_overview"></a>25.1 Overview</H2>


<p>
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 
want to take advantage of Java but are forced into using some native (C/C++) code.
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. 
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.
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.
If only one or two JNI functions are needed then using SWIG may be overkill.
SWIG enables a Java program to easily call into C/C++ code from Java.
Historically, SWIG was not able to generate any code to call into Java code from C++.
However, SWIG now supports full cross language polymorphism and code is generated to call up from C++ to Java when wrapping C++ virtual methods via the director feature.
</p>

<p>
Java is one of the few non-scripting language modules in SWIG.
As SWIG utilizes the type safety that the Java language offers, it takes a somewhat different approach to that used for scripting languages.
In particular runtime type checking and the runtime library are not used by Java.
This should be borne in mind when reading the rest of the SWIG documentation.
This chapter on Java is relatively self contained and will provide you with nearly everything you need for using SWIG and Java.
However, the "<a href="SWIG.html#SWIG">SWIG Basics</a>" chapter will be a useful read in conjunction with this one.
</p>

<p>
This chapter starts with a few practicalities on running SWIG and compiling the generated code.
If you are looking for the minimum amount to read, have a look at the sections up to and including the
<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.
Following this section are details of the C/C++ code and Java classes that SWIG generates.
Due to the complexities of C and C++ there are different ways in which C/C++ code could be wrapped and called from Java.
SWIG is a powerful tool and the rest of the chapter details how the default code wrapping can be tailored.
Various customisation tips and techniques using SWIG directives are covered.
The latter sections cover the advanced techniques of using typemaps for complete control of the wrapping process.
</p>

<H2><a name="Java_preliminaries"></a>25.2 Preliminaries</H2>


<p>
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.
Given the choice, you should probably use the latest version of Sun's JDK. 
The SWIG Java module is known to work using Sun's JVM on Solaris, Linux and the various flavours of Microsoft Windows including Cygwin. 
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. 
The generated code is also known to work on vxWorks using WindRiver's PJava 3.1. 
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. 
Run <tt>make -k check</tt> from the SWIG root directory after installing SWIG on Unix systems. </p>

<p>
The Java module requires your system to support shared libraries and dynamic loading. 
This is the commonly used method to load JNI code so your system will more than likely support this.</p>

<p>
Android uses Java JNI and also works with SWIG. Please read the <a href="Android.html">Android chapter</a> in conjunction with this one if you are targeting Android.
</p>

<H3><a name="Java_running_swig"></a>25.2.1 Running SWIG</H3>


<p>
Suppose that you defined a SWIG module such as the following:
</p>

<div class="code">
<pre>
/* File: example.i */
%module test
%{
#include "stuff.h"
%}
int fact(int n);
</pre>
</div>


<p>
To build a Java module, run SWIG using the <tt>-java</tt> option :</p>

<div class="code"><pre>
%swig -java example.i
</pre></div>

<p>
If building C++, add the <tt>-c++</tt> option:
</p>

<div class="code"><pre>
$ swig -c++ -java example.i
</pre></div>

<p>
This creates two different files; a C/C++ source file <tt>example_wrap.c</tt> or
<tt>example_wrap.cxx</tt> and numerous Java files.   The generated
C/C++ source file contains the JNI wrapper code that needs to be compiled and linked with the
rest of your C/C++ application. 
</p>

<p>
The name of the wrapper file is derived from the name of the input file.  For example, if the
input file is <tt>example.i</tt>, the name of the wrapper file is <tt>example_wrap.c</tt>.
To change this, you can use the <tt>-o</tt> option. 
It is also possible to change the <a href="SWIG.html#SWIG_output">output directory </a> that the Java files are generated into using <tt>-outdir</tt>.
</p>

<p>
The module name, specified with <tt>%module</tt>, determines the name of various generated classes as discussed <a href="#Java_module_packages_classes">later</a>.
Note that the module name does not define a Java package and by default, the generated Java classes do not have a Java package.
The <tt>-package</tt> option described below can specify a Java package name to use.
</p>

<p>
The following sections have further practical examples and details on how you might go about
compiling and using the generated files.
</p>

<H3><a name="Java_commandline"></a>25.2.2 Additional Commandline Options</H3>


<p>
The following table list the additional commandline options available for the Java module. They can also be seen by using: 
</p>

<div class="code"><pre>
swig -java -help 
</pre></div>

<table summary="Java specific options">
<tr>
<th>Java specific options</th>
</tr>

<tr>
<td>-nopgcpp</td>
<td>suppress the premature garbage collection prevention parameter</td>
</tr>

<tr>
<td>-noproxy</td>
<td>generate the low-level functional interface instead of proxy classes </td>
</tr>

<tr>
<td>-package &lt;name&gt;</td>
<td>set name of the Java package to &lt;name&gt;</td>
</tr>

</table>

<p>
Their use will become clearer by the time you have finished reading this section on SWIG and Java.
</p>

<H3><a name="Java_getting_right_headers"></a>25.2.3 Getting the right header files</H3>


<p>
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. 
They are usually in directories like this:</p>

<div class="code"><pre>
/usr/java/include
/usr/java/include/&lt;operating_system&gt;
</pre></div>

<p>
The exact location may vary on your machine, but the above locations are typical. </p>

<H3><a name="Java_compiling_dynamic"></a>25.2.4 Compiling a dynamic module</H3>


<p>
The JNI code exists in a dynamic module or shared library (DLL on Windows) and gets loaded by the JVM. 
Assuming you have code you need to link to in a file called <tt>example.c</tt>, in order to build a shared library file, you need to compile your module in a manner similar to the following (shown for Solaris):</p>

<div class="code"><pre>
$ swig -java example.i
$ gcc -fPIC -c example_wrap.c -I/usr/java/include -I/usr/java/include/solaris
$ gcc -fPIC -c example.c
$ ld -G example_wrap.o example.o -o libexample.so
</pre></div>

<p>
The exact commands for doing this vary from platform to platform. 
However, SWIG tries to guess the right options when it is installed.  Therefore, 
you may want to start with one of the examples in the <tt>Examples/java</tt> 
directory.   If that doesn't work, you will need to read the man-pages for
your compiler and linker to get the right set of options.  You might also
check the <a href="http://www.dabeaz.com/cgi-bin/wiki.pl">SWIG Wiki</a> for
additional information.
<a href="http://weblogs.java.net/blog/kellyohair/archive/2006/01/compilation_of.html">JNI compilation</a>
is a useful reference for compiling on different platforms.
</p>

<p>
<b>Important</b> <br>
If you are going to use optimisations turned on with gcc (for example -O2), ensure you also compile with -fno-strict-aliasing. The GCC optimisations have become 
more aggressive from gcc-4.0 onwards and will result in code that fails with strict aliasing optimisations turned on. See the <a href="#Java_typemaps_c_to_java_types">C/C++ to Java typemaps</a> section for more details.
</p>

<p>
The name of the shared library output file is important. 
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="#Java_dynamic_linking_problems">Dynamic linking problems</a> for more information). 
The name of the module is specified using the <tt>%module</tt> directive or <tt>-module</tt> command line option.</p>

<H3><a name="Java_using_module"></a>25.2.5 Using your module</H3>


<p>
To load your shared native library module in Java, simply use Java's <tt>System.loadLibrary</tt> method in a Java class:</p>

<div class="code"><pre>
// runme.java

public class runme {
  static {
    System.loadLibrary("example");
  }

  public static void main(String argv[]) {
    System.out.println(example.fact(4));
  }
}
</pre></div>

<p>
Compile all the Java files and run:
</p>

<div class="code"><pre>
$ javac *.java
$ java runme
24
$
</pre></div>

<p>
If it doesn't work have a look at the following section which discusses problems loading the shared library.
</p>

<H3><a name="Java_dynamic_linking_problems"></a>25.2.6 Dynamic linking problems</H3>


<p>
As shown in the previous section the code to load a native library (shared library) is <tt>System.loadLibrary("name")</tt>. 
This can fail with an UnsatisfiedLinkError exception and can be due to a number of reasons.
</p>

<p>
You may get an exception similar to this:
</p>

<div class="code"><pre>
$ java runme
Exception in thread "main" java.lang.UnsatisfiedLinkError: no example in java.library.path
        at java.lang.ClassLoader.loadLibrary(ClassLoader.java:1312)
        at java.lang.Runtime.loadLibrary0(Runtime.java:749)
        at java.lang.System.loadLibrary(System.java:820)
        at runme.&lt;clinit&gt;(runme.java:5)
</pre></div>

<p>
The most common cause for this is an incorrect naming of the native library for the name passed to the <tt>loadLibrary</tt> function. 
The string passed to the <tt>loadLibrary</tt> function must not include the file extension name in the string, that is <i>.dll</i> or <i>.so</i>. 
The string must be <i>name</i> and not <i>libname</i> for all platforms. 
On Windows the native library must then be called <i>name.dll</i> and on most Unix systems it must be called <i>libname.so</i>. 
</p>

<p>
Another common reason for the native library not loading is because it is not in your path. 
On Windows make sure the <i>path</i> environment variable contains the path to the native library. 
On Unix make sure that your <i>LD_LIBRARY_PATH</i> contains the path to the native library. 
Adding paths to <i>LD_LIBRARY_PATH</i> can slow down other programs on your system so you may want to consider alternative approaches.
For example you could recompile your native library with extra path information using <tt>-rpath</tt> if you're using GNU, see the GNU linker documentation (<tt>ld</tt> man page).
You could use a command such as <tt>ldconfig</tt> (Linux) or
<tt>crle</tt> (Solaris) to add additional search paths to the default
system configuration (this requires root access and you will need to read the man pages).
</p>

<p>
The native library will also not load if there are any unresolved symbols in the compiled C/C++ code. 
The following exception is indicative of this:
</p>

<div class="code"><pre>
$ java runme
Exception in thread "main" java.lang.UnsatisfiedLinkError: libexample.so: undefined
symbol: fact
        at java.lang.ClassLoader$NativeLibrary.load(Native Method)
        at java.lang.ClassLoader.loadLibrary0(ClassLoader.java, Compiled Code)
        at java.lang.ClassLoader.loadLibrary(ClassLoader.java, Compiled Code)
        at java.lang.Runtime.loadLibrary0(Runtime.java, Compiled Code)
        at java.lang.System.loadLibrary(System.java, Compiled Code)
        at runme.&lt;clinit&gt;(runme.java:5)
$
</pre></div>

<p>
This error usually indicates that you forgot to include some object files or libraries in the linking of the native library file.  
Make sure you compile both the SWIG wrapper file and the code you are wrapping into the native library file.  
If you forget to compile and link in the SWIG wrapper file into your native library file, you will get a message similar to the following:
</p>

<div class="code"><pre>
$ java runme
Exception in thread "main" java.lang.UnsatisfiedLinkError: exampleJNI.gcd(II)I
	at exampleJNI.gcd(Native Method)
	at example.gcd(example.java:12)
	at runme.main(runme.java:18)
</pre></div>

<p>
where <tt>gcd</tt> is the missing JNI function that SWIG generated into the wrapper file.
Also make sure you pass all of the required libraries to the linker.  
The <tt>java -verbose:jni</tt> commandline switch is also a great way to get more information on unresolved symbols.
One last piece of advice is to beware of the common faux pas of having more than one native library version in your path.
</p>

<p>
In summary, ensure that you are using the correct C/C++ compiler and linker combination and options for successful native library loading. 
If you are using the examples that ship with SWIG, then the Examples/Makefile must have these set up correctly for your system. 
The SWIG installation package makes a best attempt at getting these correct but does not get it right 100% of the time.
The <a href="http://www.dabeaz.com/cgi-bin/wiki.pl">SWIG Wiki</a> also has some settings for commonly used compiler and operating system combinations.
The following section also contains some C++ specific linking problems and solutions.
</p>


<H3><a name="Java_compilation_problems_cpp"></a>25.2.7 Compilation problems and compiling with C++</H3>


<p>
On most machines, shared library files should be linked using the C++
compiler.  For example:
</p>

<div class="code"><pre>
% swig -c++ -java example.i
% g++ -c -fpic example.cxx
% g++ -c -fpic example_wrap.cxx -I/usr/java/j2sdk1.4.1/include -I/usr/java/j2sdk1.4.1/include/linux
% g++ -shared example.o example_wrap.o -o libexample.so
</pre></div>

<p>
In addition to this, you may need to include additional library
files to make it work.  For example, if you are using the Sun C++ compiler on
Solaris, you often need to add an extra library <tt>-lCrun</tt> like this:
</p>

<div class="code"><pre>
% swig -c++ -java example.i
% CC -c example.cxx
% CC -c example_wrap.cxx -I/usr/java/include -I/usr/java/include/solaris
% CC -G example.o example_wrap.o -L/opt/SUNWspro/lib -o libexample.so -lCrun
</pre></div>

<p>
If you aren't entirely sure about the linking for C++, you
might look at an existing C++ program.  On many Unix machines, the
<tt>ldd</tt> command will list library dependencies.  This should give
you some clues about what you might have to include when you link your
shared library. For example:
</p>

<div class="code">
<pre>
$ ldd swig
        libstdc++-libc6.1-1.so.2 =&gt; /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000)
        libm.so.6 =&gt; /lib/libm.so.6 (0x4005b000)
        libc.so.6 =&gt; /lib/libc.so.6 (0x40077000)
        /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x40000000)
$
</pre>
</div>

<p>
Finally make sure the version of JDK header files matches the version of Java that you are running as incompatibilities could lead to compilation problems or unpredictable behaviour.
</p>


<H3><a name="Java_building_windows"></a>25.2.8 Building on Windows</H3>


<p>
Building on Windows is roughly similar to the process used with Unix.  
You will want to produce a DLL that can be loaded by the Java Virtual Machine.  
This section covers the process of using SWIG with Microsoft Visual C++ 6 although the procedure may be similar with other compilers.  
In order for everything to work, you will need to have a JDK installed on your machine in order to read the JNI header files.</p>

<H4><a name="Java_visual_studio"></a>25.2.8.1 Running SWIG from Visual Studio</H4>


<p>
If you are developing your application within Microsoft Visual studio, SWIG can be invoked as a custom build option. 
The Examples\java directory has a few <a href="Windows.html#Windows_examples">Windows Examples</a> containing Visual Studio project (.dsp) files.
The process to re-create the project files for a C project are roughly:</p>

<ul>
<li>Open up a new workspace and use the AppWizard to select a DLL project.
<li>Add both the SWIG interface file (the .i file), any supporting C files, and the name of the wrapper file that will be created by SWIG (ie. <tt>example_wrap.c</tt>).   
Don't worry if the wrapper file doesn't exist yet--Visual Studio will keep a reference to it.
<li>Select the SWIG interface file and go to the settings menu. Under settings, select the "Custom Build" option.
<li>Enter "SWIG" in the description field.
<li>Enter "<tt>swig -java -o $(ProjDir)\$(InputName)_wrap.c $(InputPath)</tt>" in the "Build command(s) field"
<li>Enter "<tt>$(ProjDir)\$(InputName)_wrap.c</tt>" in the "Output files(s) field".
<li>Next, select the settings for the entire project and go to C/C++ tab and select the Preprocessor category . Add the include directories to the JNI header files under "Additional include directories", eg "C:\jdk1.3\include,C:\jdk1.3\include\win32".
<li>Next, select the settings for the entire project and go to Link tab and select the General category. Set the name of the output file to match the name of your Java module (ie. example.dll).
<li>Next, select the example.c and example_wrap.c files and go to the C/C++ tab and select the Precompiled Headers tab in the project settings. Disabling precompiled headers for these files will overcome any precompiled header errors while building.
<li>Finally, add the java compilation as a post build rule in the Post-build step tab in project settings, eg, "c:\jdk1.3\bin\javac *.java" 
<li>Build your project.
</ul>

<p>
Note: If using C++, choose a C++ suffix for the wrapper file, for example <tt>example_wrap.cxx</tt>.
Use <tt>_wrap.cxx</tt> instead of <tt>_wrap.c</tt> in the instructions above and add -c++ when invoking swig.
</p>

<p>
Now, assuming all went well, SWIG will be automatically invoked when you build your project.  
When doing a build, any changes made to the interface file will result in SWIG being automatically invoked to produce a new version of the wrapper file.
</p>

<p>
The Java classes that SWIG output should also be compiled into .class files. 
To run the native code in the DLL (example.dll), make sure that it is in your path then run your Java program which uses it, as described in the previous section. 
If the library fails to load have a look at <a href="#Java_dynamic_linking_problems">Dynamic linking problems</a>.
</p>

<H4><a name="Java_nmake"></a>25.2.8.2 Using NMAKE</H4>


<p>
Alternatively, a Makefile for use by NMAKE can be written.   
Make sure the environment variables for MSVC++ are available and the MSVC++ tools are in your path.   
Now, just write a short Makefile like this :</p>

<div class="code"><pre>
# Makefile for using SWIG and Java for C code

SRCS          = example.c
IFILE         = example
INTERFACE     = $(IFILE).i
WRAPFILE      = $(IFILE)_wrap.c

# Location of the Visual C++ tools (32 bit assumed)

TOOLS         = c:\msdev
TARGET        = example.dll
CC            = $(TOOLS)\bin\cl.exe
LINK          = $(TOOLS)\bin\link.exe
INCLUDE32     = -I$(TOOLS)\include
MACHINE       = IX86

# C Library needed to build a DLL

DLLIBC        = msvcrt.lib oldnames.lib  

# Windows libraries that are apparently needed
WINLIB        = kernel32.lib advapi32.lib user32.lib gdi32.lib comdlg32.lib winspool.lib

# Libraries common to all DLLs
LIBS          = $(DLLIBC) $(WINLIB) 

# Linker options
LOPT      = -debug:full -debugtype:cv /NODEFAULTLIB /RELEASE /NOLOGO \
             /MACHINE:$(MACHINE) -entry:_DllMainCRTStartup@12 -dll

# C compiler flags

CFLAGS        = /Z7 /Od /c /nologo
JAVA_INCLUDE    = -ID:\jdk1.3\include -ID:\jdk1.3\include\win32

java::
	swig -java -o $(WRAPFILE) $(INTERFACE)
	$(CC) $(CFLAGS) $(JAVA_INCLUDE) $(SRCS) $(WRAPFILE)
	set LIB=$(TOOLS)\lib
	$(LINK) $(LOPT) -out:example.dll $(LIBS) example.obj example_wrap.obj
	javac *.java
</pre></div>

<p>
To build the DLL and compile the java code, run NMAKE (you may need to run <tt>vcvars32</tt> first). 
This is a pretty simplistic Makefile, but hopefully its enough to get you started.
Of course you may want to make changes for it to work for C++ by adding in the -c++ command line switch for swig and replacing .c with .cxx.
</p>


<H2><a name="Java_basic_tour"></a>25.3 A tour of basic C/C++ wrapping</H2>


<p>
By default, SWIG attempts to build a natural Java interface
to your C/C++ code.  Functions are wrapped as functions, classes are wrapped as classes, 
variables are wrapped with JavaBean type getters and setters and so forth.
This section briefly covers the essential aspects of this wrapping.
</p>

<H3><a name="Java_module_packages_classes"></a>25.3.1 Modules, packages and generated Java classes</H3>


<p>
The SWIG <tt>%module</tt> directive specifies the name of the Java
module. When you specify `<tt>%module example</tt>', the <i>module name</i>
determines the name of some of the generated files in the module.
The generated code consists of a <i>module class</i> file <tt>example.java</tt>, an
<i>intermediary JNI class</i> file, <tt>exampleJNI.java</tt> as well as numerous other Java <i>proxy class</i> files.
Each proxy class is named after the structs, unions and classes you are wrapping.
You may also get a <i>constants interface</i> file if you are wrapping any unnamed enumerations or constants, for example <tt>exampleConstants.java</tt>.
When choosing a module name, make sure you don't use the same name as one of the generated
proxy class files nor a Java keyword. Sometimes a C/C++ type cannot be wrapped by a proxy class, for 
example a pointer to a primitive type. In these situations a <i>type wrapper class</i> is generated.
Wrapping an enum generates an <i>enum class</i>, either a proper Java enum or a Java class that simulates the enums pattern.
Details of all these generated classes will unfold as you read this section.
</p>

<p>
The JNI (C/C++) code is generated into a file which also contains the module name, for example <tt>example_wrap.cxx</tt>
or <tt>example_wrap.c</tt>. These C or C++ files complete the contents of the module.
</p>

<p>
The generated Java classes can be placed into a Java package by using the <tt>-package</tt> commandline option.
This is often combined with the <tt>-outdir</tt> to specify a package directory for generating the Java files.
</p>

<div class="code"><pre>
swig -java -package com.bloggs.swig -outdir com/bloggs/swig example.i
</pre></div>

<p>
SWIG won't create the directory, so make sure it exists beforehand.
</p>

<H3><a name="Java_functions"></a>25.3.2 Functions</H3>


<p>
There is no such thing as a global Java function so global C functions are wrapped as static methods in 
the module class. For example,
</p>

<div class="code"><pre>
%module example
int fact(int n);

</pre></div>

<p>
creates a static function that works exactly like you think it might:</p>

<div class="code"><pre>
public class example {
  public static int fact(int n) {
    // makes call using JNI to the C function
  }
}
</pre></div>


<p>
The Java class <tt>example</tt> is the <i>module class</i>. The function can be used as follows from Java:</p>

<div class="code"><pre>
System.out.println(example.fact(4));
</pre></div>


<H3><a name="Java_global_variables"></a>25.3.3 Global variables</H3>


<p>
C/C++ global variables are fully supported by SWIG.  
Java does not allow the overriding of the dot operator so all variables are accessed through getters and setters. 
Again because there is no such thing as a
Java global variable, access to C/C++ global variables is done through static getter and setter functions in the module class.
</p>

<div class="code"><pre>
// SWIG interface file with global variables
%module example
...
%inline %{
extern int My_variable;
extern double density;
%}
...
</pre></div>

<p>
Now in Java :</p>

<div class="code"><pre>
// Print out value of a C global variable
System.out.println("My_variable = " + example.getMy_variable());
// Set the value of a C global variable
example.setDensity(0.8442);
</pre></div>

<p>
The value returned by the getter will always be up to date even if the value is changed in C. 
Note that the getters and setters produced follow the JavaBean property design pattern. 
That is the first letter of the variable name is capitalized and preceded with set or get.
If you have the misfortune of wrapping two variables that differ only in the capitalization of their first letters,
use %rename to change one of the variable names. For example:
</p>

<div class="code"><pre>
%rename Clash RenamedClash;
float Clash;
int clash;
</pre></div>

<p>
If a variable is declared as <tt>const</tt>, it is wrapped as a read-only variable.  
That is only a getter is produced.
</p>

<p>
To make ordinary variables read-only, you can use the <tt>%immutable</tt> directive. For example:
</p>

<div class="code">
<pre>
%{
extern char *path;
%}
%immutable;
extern char *path;
%mutable;
</pre>
</div>

<p>
The <tt>%immutable</tt> directive stays in effect until it is explicitly disabled or cleared using
<tt>%mutable</tt>.
See the <a href="SWIG.html#SWIG_readonly_variables">Creating read-only variables</a> section for further details.
</p>

<p>
If you just want to make a specific variable immutable, supply a declaration name.  For example:
</p>

<div class="code">
<pre>
%{
extern char *path;
%}
%immutable path;
...
extern char *path;      // Read-only (due to %immutable)
</pre>
</div>


<H3><a name="Java_constants"></a>25.3.4 Constants</H3>


<p>
C/C++ constants are wrapped as Java static final variables.
To create a constant, use <tt>#define</tt> or the
<tt>%constant</tt> directive.  For example:
</p>

<div class="code">
<pre>
#define PI 3.14159
#define VERSION "1.0"
%constant int FOO = 42;
%constant const char *path = "/usr/local";
</pre>
</div>

<p>
By default the generated static final variables are initialized by making a JNI call to get their value.
The constants are generated into the constants interface and look like this:
</p>

<div class="code"><pre>
public interface exampleConstants {
  public final static double PI = exampleJNI.PI_get();
  public final static String VERSION = exampleJNI.VERSION_get();
  public final static int FOO = exampleJNI.FOO_get();
  public final static String path = exampleJNI.path_get();
}
</pre></div>

<p>
Note that SWIG has inferred the C type and used an appropriate Java type that will fit the range of all possible values for the C type.
By default SWIG generates <b>runtime constants</b>. They are not <b>compiler constants</b> that can, for example, be used 
in a switch statement. This can be changed by using the <tt>%javaconst(flag)</tt> directive. It works like all
the other <a href="Customization.html#Customization_features">%feature directives</a>. The default is <tt>%javaconst(0)</tt>. 
It is possible to initialize all wrapped constants from pure Java code by placing a <tt>%javaconst(1)</tt> <b>before</b> SWIG parses the constants.
Putting it at the top of your interface file would ensure this.
Here is an example:
</p>

<div class="code"><pre>
%javaconst(1);
%javaconst(0) BIG;
%javaconst(0) LARGE;

#define EXPRESSION (0x100+5)
#define BIG 1000LL
#define LARGE 2000ULL
</pre></div>

<p>
generates:
</p>

<div class="code"><pre>
public interface exampleConstants {
  public final static int EXPRESSION = (0x100+5);
  public final static long BIG = exampleJNI.BIG_get();
  public final static java.math.BigInteger LARGE = exampleJNI.LARGE_get();
}
</pre></div>

<p>
Note that SWIG has inferred the C <tt>long long</tt> type from <tt>BIG</tt> and used an appropriate Java type (<tt>long</tt>) as
a Java <tt>long</tt> is the smallest sized Java type that will take all possible values for a C <tt>long long</tt>.
Similarly for <tt>LARGE</tt>.
</p>

<p>
Be careful using the <tt>%javaconst(1)</tt> directive as not all C code will compile as Java code. For example neither the 
<tt>1000LL</tt> value for <tt>BIG</tt> nor <tt>2000ULL</tt> for <tt>LARGE</tt> above would generate valid Java code. 
The example demonstrates how you can target particular constants (<tt>BIG</tt> and <tt>LARGE</tt>) with <tt>%javaconst</tt>.
SWIG doesn't use <tt>%javaconst(1)</tt> as the default as it tries to generate code that will always compile.
However, using a <tt>%javaconst(1)</tt> at the top of your interface file is strongly recommended as the preferred compile time constants
will be generated and most C constants will compile as Java code and in any case the odd constant that doesn't can be fixed using <tt>%javaconst(0)</tt>.
</p>

<p>
There is an alternative directive which can be used for these rare constant values that won't compile as Java code.
This is the <tt>%javaconstvalue(value)</tt> directive, where <tt>value</tt> is a Java code replacement for the C constant and can be either a string or a number.
This is useful if you do not want to use either the parsed C value nor a JNI call,
such as when the C parsed value will not compile as Java code and a compile time constant is required.
The same example demonstrates this:
</p>

<div class="code"><pre>
%javaconst(1);
%javaconstvalue("new java.math.BigInteger(\"2000\")") LARGE;
%javaconstvalue(1000) BIG;

#define EXPRESSION (0x100+5)
#define BIG 1000LL
#define LARGE 2000ULL
</pre></div>

<p>
Note the string quotes for <tt>"2000"</tt> are escaped. The following is then generated:
</p>

<div class="code"><pre>
public interface exampleConstants {
  public final static int EXPRESSION = (0x100+5);
  public final static long BIG = 1000;
  public final static java.math.BigInteger LARGE = new java.math.BigInteger("2000");
}
</pre></div>

<p>
Note:  declarations declared as <tt>const</tt> are wrapped as read-only variables and
will be accessed using a getter as described in the previous section.  They
are not wrapped as constants.
The exception to this rule are static const integral values defined within a class/struct, where they are wrapped as constants, eg:.
</p>

<div class="code"><pre>
struct Maths {
  static const int FIVE = 5;
};
</pre></div>


<p>
<b>Compatibility Note:</b> In SWIG-1.3.19 and earlier releases, the constants were generated into the module class and the constants interface didn't exist.
Backwards compatibility is maintained as the module class implements the constants interface (even though some consider this type of interface implementation to be bad practice):
</p>

<div class="code"><pre>
public class example implements exampleConstants {
}
</pre></div>

<p>
You thus have the choice of accessing these constants from either the module class or the constants interface, for example,
<tt>example.EXPRESSION</tt> or <tt>exampleConstants.EXPRESSION</tt>.
Or if you decide this practice isn't so bad and your own class implements <tt>exampleConstants</tt>, you can of course just use <tt>EXPRESSION</tt>.
</p>


<H3><a name="Java_enumerations"></a>25.3.5 Enumerations</H3>


<p>
SWIG handles both named and unnamed (anonymous) enumerations.
There is a choice of approaches to wrapping named C/C++ enums.
This is due to historical reasons as SWIG's initial support for enums was limited and Java did not originally have support for enums.
Each approach has advantages and disadvantages and it is important for the user to decide which is the most appropriate solution.
There are four approaches of which the first is the default approach based on the so called Java typesafe enum pattern.
The second generates proper Java enums.
The final two approaches use simple integers for each enum item.
Before looking at the various approaches for wrapping named C/C++ enums, anonymous enums are considered.
</p>

<H4><a name="Java_anonymous_enums"></a>25.3.5.1 Anonymous enums</H4>


<p>
There is no name for anonymous enums and so they are handled like constants. For example:
</p>

<div class="code">
<pre>
enum { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
</pre>
</div>

<p>
is wrapped into the constants interface, in a similar manner as constants (see previous section):
</p>

<div class="code"><pre>
public interface exampleConstants {
  public final static int ALE = exampleJNI.ALE_get();
  public final static int LAGER = exampleJNI.LAGER_get();
  public final static int STOUT = exampleJNI.STOUT_get();
  public final static int PILSNER = exampleJNI.PILSNER_get();
  public final static int PILZ = exampleJNI.PILZ_get();
}
</pre></div>

<p>
The <tt>%javaconst(flag)</tt> and <tt>%javaconstvalue(value)</tt> directive introduced in the previous section on constants can also be used with enums.
As is the case for constants, the default is <tt>%javaconst(0)</tt> as not all C values will compile as Java code.
However, it is strongly recommended to add in a <tt>%javaconst(1)</tt> directive at the top of your 
interface file as it is only on very rare occasions that this will produce code that won't compile under Java.
Using <tt>%javaconst(1)</tt> will ensure compile time constants are generated, thereby allowing the enum values to be used in Java switch statements. 
Example usage:
</p>

<div class="code">
<pre>
%javaconst(1);
%javaconst(0) PILSNER;
enum { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
</pre>
</div>

<p>
generates:
</p>

<div class="code"><pre>
public interface exampleConstants {
  public final static int ALE = 0;
  public final static int LAGER = 10;
  public final static int STOUT = LAGER + 1;
  public final static int PILSNER = exampleJNI.PILSNER_get();
  public final static int PILZ = PILSNER;
}
</pre></div>

<p>
As in the case of constants, you can access them through either the module class or the constants interface, for example, <tt>example.ALE</tt> or <tt>exampleConstants.ALE</tt>.
</p>


<H4><a name="Java_typesafe_enums"></a>25.3.5.2 Typesafe enums</H4>


<p>
This is the default approach to wrapping named enums.
The typesafe enum pattern is a relatively well known construct to work around the lack of enums in versions of Java prior to JDK 1.5.
It basically defines a class for the enumeration and permits a limited number of final static instances of the class.
Each instance equates to an enum item within the enumeration.
The implementation is in the "enumtypesafe.swg" file.
Let's look at an example:
</p>

<div class="code">
<pre>
%include "enumtypesafe.swg" // optional as typesafe enums are the default
enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
</pre>
</div>

<p>will generate:</p>

<div class="code">
<pre>
public final class Beverage {
  public final static Beverage ALE = new Beverage("ALE");
  public final static Beverage LAGER = new Beverage("LAGER", exampleJNI.LAGER_get());
  public final static Beverage STOUT = new Beverage("STOUT");
  public final static Beverage PILSNER = new Beverage("PILSNER");
  public final static Beverage PILZ = new Beverage("PILZ", exampleJNI.PILZ_get());
  [... additional support methods omitted for brevity ...]
}
</pre>
</div>

<p>
See <a href="#Java_typesafe_enums_classes">Typesafe enum classes</a> to see the omitted support methods.
Note that the enum item with an initializer (LAGER) is initialized with the enum value obtained via a JNI call.
However, as with anonymous enums and constants, use of the <tt>%javaconst</tt> directive is strongly recommended to change this behaviour:
</p>

<div class="code">
<pre>
%include "enumtypesafe.swg" // optional as typesafe enums are the default
%javaconst(1);
enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
</pre>
</div>

<p>
will generate:
</p>

<div class="code">
<pre>
public final class Beverage {
  public final static Beverage ALE = new Beverage("ALE");
  public final static Beverage LAGER = new Beverage("LAGER", 10);
  public final static Beverage STOUT = new Beverage("STOUT");
  public final static Beverage PILSNER = new Beverage("PILSNER");
  public final static Beverage PILZ = new Beverage("PILZ", PILSNER);
  [... additional support methods omitted for brevity ...]
}
</pre>
</div>

<p>
The generated code is easier to read and more efficient as a true constant is used instead of a JNI call.
As is the case for constants, the default is <tt>%javaconst(0)</tt> as not all C values will compile as Java code.
However, it is recommended to add in a <tt>%javaconst(1)</tt> directive at the top of your 
interface file as it is only on very rare occasions that this will produce code that won't compile under Java.
The <tt>%javaconstvalue(value)</tt> directive can also be used for typesafe enums.
Note that global enums are generated into a Java class within whatever package you are using.
C++ enums defined within a C++ class are generated into a static final inner Java class within the Java proxy class.
</p>

<p>
Typesafe enums have their advantages over using plain integers in that they can be used in a typesafe manner.
However, there are limitations. For example, they cannot be used in switch statements and serialization is an issue.
Please look at the following references for further information: 

         http://java.sun.com/developer/Books/shiftintojava/page1.html#replaceenums
<a href="http://java.sun.com/developer/Books/shiftintojava/page1.html#replaceenums">Replace Enums with Classes</a> in <i>Effective Java Programming</i> on the Sun website,
<a href="http://www.javaworld.com/javaworld/jw-07-1997/jw-07-enumerated.html">Create enumerated constants in Java</a> JavaWorld article,
<a href="http://www.javaworld.com/javaworld/javatips/jw-javatip133.html">Java Tip 133: More on typesafe enums</a> and
<a href="http://www.javaworld.com/javaworld/javatips/jw-javatip122.html">Java Tip 122: Beware of Java typesafe enumerations</a> JavaWorld tips.
</p>

<p>
Note that the syntax required for using typesafe enums is the same as that for proper Java enums.
This is useful during the period that a project has to support legacy versions of Java.
When upgrading to JDK 1.5 or later, proper Java enums could be used instead, without users having to change their code.
The following section details proper Java enum generation.
</p>

<H4><a name="Java_proper_enums"></a>25.3.5.3 Proper Java enums</H4>


<p>
Proper Java enums were only introduced in JDK 1.5 so this approach is only compatible with more recent versions of Java.
Java enums have been designed to overcome all the limitations of both typesafe and type unsafe enums
and should be the choice solution, provided older versions of Java do not have to be supported.
In this approach, each named C/C++ enum is wrapped by a Java enum.
Java enums, by default, do not support enums with initializers.
Java enums are in many respects similar to Java classes in that they can be customised with additional methods.
SWIG takes advantage of this feature to facilitate wrapping C/C++ enums that have initializers.
In order to wrap all possible C/C++ enums using proper Java enums, the "enums.swg" file must be used.
Let's take a look at an example.
</p>

<div class="code">
<pre>
%include "enums.swg"
%javaconst(1);
enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
</pre>
</div>

<p>
will generate:
</p>

<div class="code">
<pre>
public enum Beverage {
  ALE,
  LAGER(10),
  STOUT,
  PILSNER,
  PILZ(PILSNER);
  [... additional support methods omitted for brevity ...]
}
</pre>
</div>

<p>
See <a href="#Java_proper_enums_classes">Proper Java enum classes</a> to see the omitted support methods.
The generated Java enum has numerous additional methods to support enums with initializers, such as <tt>LAGER</tt> above.
Note that as with the typesafe enum pattern, enum items with initializers are by default initialized with the enum value obtained via a JNI call.
However, this is not the case above as we have used the recommended <tt>%javaconst(1)</tt> to avoid the JNI call.
The <tt>%javaconstvalue(value)</tt> directive covered in the <a href="#Java_constants">Constants</a> section can also be used for proper Java enums.
</p>

<p>
The additional support methods need not be generated if none of the enum items have initializers and this is covered later in the 
<a href="#Java_simpler_enum_classes">Simpler Java enums for enums without initializers</a> section.
</p>

<H4><a name="Java_typeunsafe_enums"></a>25.3.5.4 Type unsafe enums</H4>


<p>
In this approach each enum item in a named enumeration is wrapped as a static final integer in a class named after the C/C++ enum name.
This is a commonly used pattern in Java to simulate C/C++ enums, but it is not typesafe.
However, the main advantage over the typesafe enum pattern is enum items can be used in switch statements.
In order to use this approach, the "enumtypeunsafe.swg" file must be used.
Let's take a look at an example.
</p>

<div class="code">
<pre>
%include "enumtypeunsafe.swg"
%javaconst(1);
enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
</pre>
</div>

<p>
will generate:
</p>

<div class="code">
<pre>
public final class Beverage {
  public final static int ALE = 0;
  public final static int LAGER = 10;
  public final static int STOUT = LAGER + 1;
  public final static int PILSNER = STOUT + 1;
  public final static int PILZ = PILSNER;
}
</pre>
</div>

<p>
As is the case previously, the default is <tt>%javaconst(0)</tt> as not all C/C++ values will compile as Java code.
However, again it is recommended to add in a <tt>%javaconst(1)</tt> directive.
and the <tt>%javaconstvalue(value)</tt> directive covered in the <a href="#Java_constants">Constants</a> section can also be used for type unsafe enums.
Note that global enums are generated into a Java class within whatever package you are using.
C++ enums defined within a C++ class are generated into a static final inner Java class within the Java proxy class.
</p>

<p>
Note that unlike typesafe enums, this approach requires users to mostly use different syntax compared with proper Java enums.
Thus the upgrade path to proper enums provided in JDK 1.5 is more painful.
</p>

<H4><a name="Java_simple_enums"></a>25.3.5.5 Simple enums</H4>


<p>
This approach is similar to the type unsafe approach.
Each enum item is also wrapped as a static final integer.
However, these integers are not generated into a class named after the C/C++ enum.
Instead, global enums are generated into the constants interface.
Also, enums defined in a C++ class have their enum items generated directly into the Java proxy class rather than an inner class within the Java proxy class.
In fact, this approach is effectively wrapping the enums as if they were anonymous enums and the resulting code is as per <a href="#Java_anonymous_enums">anonymous enums</a>.
The implementation is in the "enumsimple.swg" file.
</p>

<p>
<b>Compatibility Note:</b>
SWIG-1.3.21 and earlier versions wrapped all enums using this approach.
The type unsafe approach is preferable to this one and this simple approach is only included for backwards compatibility with these earlier versions of SWIG.
</p>

<H3><a name="Java_pointers"></a>25.3.6 Pointers</H3>


<p>
C/C++ pointers are fully supported by SWIG.  Furthermore, SWIG has no problem working with
incomplete type information.  Here is a rather simple interface:
</p>

<div class="code">
<pre>
%module example

FILE *fopen(const char *filename, const char *mode);
int fputs(const char *, FILE *);
int fclose(FILE *);
</pre>
</div>

<p>
When wrapped, you will be able to use the functions in a natural way from Java. For example:
</p>

<div class="code">
<pre>
SWIGTYPE_p_FILE f = example.fopen("junk","w");
example.fputs("Hello World\n", f);
example.fclose(f);
</pre>
</div>

<p>
C pointers in the Java module are stored in a Java <tt>long</tt> and cross the JNI boundary held within this 64 bit number.
Many other SWIG language modules use an encoding of the pointer in a string. 
These scripting languages use the SWIG runtime type checker for dynamic type checking as they do not support static type checking by a compiler.
In order to implement static type checking of pointers within Java, they are wrapped by a simple Java class. 
In the example above the <tt>FILE *</tt> pointer is wrapped with a <i>type wrapper class </i> 
called <tt>SWIGTYPE_p_FILE</tt>.
</p>

<p>
Once obtained, a type wrapper object can be freely passed around to different C functions that
expect to receive an object of that type.  The only thing you can't do is 
dereference the pointer from Java. Of course, that isn't much of a concern in this example.
</p>

<p>
As much as you might be inclined to modify a pointer value directly
from Java, don't.  The value is not necessarily the
same as the logical memory address of the underlying object.  The value will
vary depending on the native byte-ordering of the platform (i.e.,
big-endian vs. little-endian).  
Most JVMs are 32 bit applications so any JNI code must also be compiled as 32 bit. 
The net result is pointers in JNI code are also 32 bits and 
are stored in the high order 4 bytes on big-endian machines and in the low order 4 bytes on little-endian machines. 
By design it is also not possible to manually cast
a pointer to a new type by using Java casts as it is particularly dangerous especially when
casting C++ objects.  If you need to cast a pointer or
change its value, consider writing some helper functions instead.  For
example:
</p>

<div class="code">
<pre>
%inline %{
/* C-style cast */
Bar *FooToBar(Foo *f) {
   return (Bar *) f;
}

/* C++-style cast */
Foo *BarToFoo(Bar *b) {
   return dynamic_cast&lt;Foo*&gt;(b);
}

Foo *IncrFoo(Foo *f, int i) {
    return f+i;
}
%}
</pre>
</div>

<p>
Also, if working with C++, you should always try
to use the new C++ style casts.  For example, in the above code, the
C-style cast may return a bogus result whereas as the C++-style cast will return
a NULL pointer if the conversion can't be performed.
</p>

<H3><a name="Java_structures"></a>25.3.7 Structures</H3>


<p>
If you wrap a C structure, it is wrapped by a Java class with getters and setters for access to the
member variables. For example,
</p>

<div class="code"><pre>
struct Vector {
	double x,y,z;
};

</pre></div>

<p>
is used as follows:
</p>

<div class="code"><pre>
Vector v = new Vector();
v.setX(3.5);
v.setY(7.2);
double x = v.getX();
double y = v.getY();
</pre></div>

<p>
The variable setters and getters are also based on the JavaBean design pattern already covered under the Global variables section.
Similar access is provided for unions and the public data members of C++ classes.</p>

<p>
This object is actually an instance of a Java class that has been wrapped around a pointer to the C structure.  
This instance doesn't actually do anything--it just serves as a proxy.
The pointer to the C object is held in the Java proxy class in much the same way as pointers are held by type wrapper classes.
Further details about Java proxy classes are covered a little later.
</p>

<p>
<tt>const</tt> members of a structure are read-only. Data members
can also be forced to be read-only using the <tt>%immutable</tt> directive. For example:
</p>

<div class="code">
<pre>
struct Foo {
   ...
   %immutable;
   int x;        /* Read-only members */
   char *name;
   %mutable;
   ...
};
</pre>
</div>

<p>
When <tt>char *</tt> members of a structure are wrapped, the contents are assumed to be
dynamically allocated using <tt>malloc</tt> or <tt>new</tt> (depending on whether or not
SWIG is run with the -c++ option).   When the structure member is set, the old contents will be 
released and a new value created.   If this is not the behavior you want, you will have to use
a typemap (described later).
</p>

<p>
If a structure contains arrays, access to those arrays is managed through pointers.  For
example, consider this:
</p>

<div class="code">
<pre>
struct Bar {
    int  x[16];
};
</pre>
</div>

<p>
If accessed in Java, you will see behavior like this:
</p>

<div class="code">
<pre>
Bar b = new Bar();
SWIGTYPE_p_int x = b.getX();
</pre>
</div>

<p>
This pointer can be passed around to functions that expect to receive
an <tt>int *</tt> (just like C).   You can also set the value of an array member using
another pointer.  For example:
</p>

<div class="code">
<pre>
Bar b = new Bar();
SWIGTYPE_p_int x = b.getX();
Bar c = new Bar();
c.setX(x);                    // Copy contents of b.x to c.x
</pre>
</div>

<p>
For array assignment (setters not getters), SWIG copies the entire contents of the array starting with the data pointed
to by <tt>b.x</tt>.   In this example, 16 integers would be copied.  Like C, SWIG makes
no assumptions about bounds checking---if you pass a bad pointer, you may get a segmentation
fault or access violation.
The default wrapping makes it hard to set or get just one element of the array and so array access from Java is somewhat limited.
This can be changed easily though by using the approach outlined later in the <a href="#Java_c_arrays">Wrapping C arrays with Java arrays</a> and
<a href="#Java_unbounded_c_arrays">Unbounded C Arrays</a> sections.
</p>

<p>
When a member of a structure is itself a structure, it is handled as a
pointer.  For example, suppose you have two structures like this:
</p>

<div class="code">
<pre>
struct Foo {
   int a;
};

struct Bar {
   Foo f;
};
</pre>
</div>

<p>
Now, suppose that you access the <tt>f</tt> member of <tt>Bar</tt> like this:
</p>

<div class="code">
<pre>
Bar b = new Bar();
Foo x = b.getF();
</pre>
</div>

<p>
In this case, <tt>x</tt> is a pointer that points to the <tt>Foo</tt> that is inside <tt>b</tt>.
This is the same value as generated by this C code:
</p>

<div class="code">
<pre>
Bar b;
Foo *x = &amp;b-&gt;f;       /* Points inside b */
</pre>
</div>

<p>
Because the pointer points inside the structure, you can modify the contents and 
everything works just like you would expect. For example:
</p>

<div class="code">
<pre>
Bar b = new Bar();
b.getF().setA(3);   // Modify b.f.a
Foo x = b.getF();                   
x.setA(3);          // Modify x.a - this is the same as b.f.a
</pre>
</div>


<H3><a name="Java_classes"></a>25.3.8 C++ classes</H3>


<p>
C++ classes are wrapped by Java classes as well. For example, if you have this class,
</p>

<div class="code"><pre>
class List {
public:
  List();
  ~List();
  int  search(char *item);
  void insert(char *item);
  void remove(char *item);
  char *get(int n);
  int  length;
};
</pre></div>

<p>
you can use it in Java like this:
</p>

<div class="code"><pre>
List l = new List();
l.insert("Ale");
l.insert("Stout");
l.insert("Lager");
String item = l.get(2);
int length = l.getLength();
</pre></div>

<p>
Class data members are accessed in the same manner as C structures.  
</p>

<p>
Static class members are unsurprisingly wrapped as static members of the Java class:
</p>

<div class="code">
<pre>
class Spam {
public:
   static void foo();
   static int bar;
};
</pre>
</div>

<p>
The static members work like any other Java static member:
</p>

<div class="code">
<pre>
Spam.foo();
int bar = Spam.getBar();
</pre>
</div>


<H3><a name="Java_inheritance"></a>25.3.9 C++ inheritance</H3>


<p>
SWIG is fully aware of issues related to C++ inheritance.  Therefore, if you have
classes like this
</p>

<div class="code">
<pre>
class Foo {
...
};

class Bar : public Foo {
...
};
</pre>
</div>

<p>
those classes are wrapped into a hierarchy of Java classes that reflect the same inheritance
structure:
</p>

<div class="code">
<pre>
Bar b = new Bar();
Class c = b.getClass();
System.out.println(c.getSuperclass().getName());
</pre>
</div>

<p>
will of course display:
</p>

<div class="code"><pre>
Foo
</pre></div>


<p>
Furthermore, if you have functions like this
</p>

<div class="code">
<pre>
void spam(Foo *f);
</pre>
</div>

<p>
then the Java function <tt>spam()</tt> accepts instances of <tt>Foo</tt> or instances of any other proxy classes derived from <tt>Foo</tt>.
</p>

<p>
Note that Java does not support multiple inheritance so any multiple inheritance in the C++ code is not going to work. 
A warning is given when multiple inheritance is detected and only the first base class is used. 
</p>

<H3><a name="Java_pointers_refs_arrays"></a>25.3.10 Pointers, references, arrays and pass by value</H3>


<p>
In C++, there are many different ways a function might receive
and manipulate objects.  For example:
</p>

<div class="code">
<pre>
void spam1(Foo *x);      // Pass by pointer
void spam2(Foo &amp;x);      // Pass by reference
void spam3(Foo x);       // Pass by value
void spam4(Foo x[]);     // Array of objects
</pre>
</div>

<p>
In Java, there is no detailed distinction like this--specifically,
there are only instances of classes.  There are no pointers nor references.
Because of this, SWIG unifies all of these types
together in the wrapper code.  For instance, if you actually had the
above functions, it is perfectly legal to do this from Java:
</p>

<div class="code">
<pre>
Foo f = new Foo();  // Create a Foo
example.spam1(f);   // Ok. Pointer
example.spam2(f);   // Ok. Reference
example.spam3(f);   // Ok. Value.
example.spam4(f);   // Ok. Array (1 element)
</pre>
</div>

<p>
Similar behavior occurs for return values.  For example, if you had
functions like this,
</p>

<div class="code">
<pre>
Foo *spam5();
Foo &amp;spam6();
Foo  spam7();
</pre>
</div>

<p>
then all three functions will return a pointer to some <tt>Foo</tt> object.
Since the third function (spam7) returns a value, newly allocated memory is used 
to hold the result and a pointer is returned (Java will release this memory 
when the returned object's finalizer is run by the garbage collector).
</p>

<H4><a name="Java_null_pointers"></a>25.3.10.1 Null pointers</H4>


<p>
Working with null pointers is easy. 
A Java <tt>null</tt> can be used whenever a method expects a proxy class or typewrapper class.
However, it is not possible to pass null to C/C++ functions that take parameters by value or by reference. 
If you try you will get a NullPointerException.
</p>

<div class="code">
<pre>
example.spam1(null);   // Pointer - ok
example.spam2(null);   // Reference - NullPointerException
example.spam3(null);   // Value - NullPointerException
example.spam4(null);   // Array - ok
</pre>
</div>

<p>
For <tt>spam1</tt> and <tt>spam4</tt> above the Java <tt>null</tt> gets translated into a NULL pointer for passing to the C/C++ function. 
The converse also occurs, that is, NULL pointers are translated into <tt>null</tt> Java objects when returned from a C/C++ function.
</p>

<H3><a name="Java_overloaded_functions"></a>25.3.11 C++ overloaded functions</H3>


<p>
C++ overloaded functions, methods, and constructors are mostly supported by SWIG.  For example,
if you have two functions like this:
</p>

<div class="code">
<pre>
%module example

void foo(int);
void foo(char *c);
</pre>
</div>

<p>
You can use them in Java in a straightforward manner:
</p>

<div class="code">
<pre>
example.foo(3);           // foo(int)
example.foo("Hello");     // foo(char *c)
</pre>
</div>

<p>
Similarly, if you have a class like this,
</p>

<div class="code">
<pre>
class Foo {
public:
    Foo();
    Foo(const Foo &amp;);
    ...
};
</pre>
</div>

<p>
you can write Java code like this:
</p>

<div class="code">
<pre>
Foo f = new Foo();        // Create a Foo
Foo g = new Foo(f);       // Copy f
</pre>
</div>

<p>
Overloading support is not quite as flexible as in C++. Sometimes there are methods that SWIG
cannot disambiguate as there can be more than one C++ type mapping onto a single Java type. For example:
</p>

<div class="code">
<pre>
void spam(int);
void spam(unsigned short);
</pre>
</div>

<p>
Here both int and unsigned short map onto a Java int. 
Here is another example:
</p>

<div class="code">
<pre>
void foo(Bar *b);
void foo(Bar &amp;b);
</pre>
</div>

<p>
If declarations such as these appear, you will get a warning message like this:
</p>

<div class="code">
<pre>
example.i:12: Warning 515: Overloaded method spam(unsigned short) ignored.
Method spam(int) at example.i:11 used.
</pre>
</div>

<p>
To fix this, you either need to either <a href="SWIG.html#SWIG_rename_ignore">rename or ignore</a> one of the methods.  For example:
</p>

<div class="code">
<pre>
%rename(spam_ushort) spam(unsigned short);
...
void spam(int);    
void spam(unsigned short);   // Now renamed to spam_ushort
</pre>
</div>

<p>
or
</p>

<div class="code">
<pre>
%ignore spam(unsigned short);
...
void spam(int);    
void spam(unsigned short);   // Ignored
</pre>
</div>

<H3><a name="Java_default_arguments"></a>25.3.12 C++ default arguments</H3>


<p>
Any function with a default argument is wrapped by generating an additional function for each argument that is defaulted.
For example, if we have the following C++:
</p>

<div class="code">
<pre>
%module example

void defaults(double d=10.0, int i=0);
</pre>
</div>

<p>
The following methods are generated in the Java module class:
</p>

<div class="code">
<pre>
public class example {
  public static void defaults(double d, int i) { ... }
  public static void defaults(double d) { ... }
  public static void defaults() { ... }
}
</pre>
</div>

<p>
It is as if SWIG had parsed three separate overloaded methods.
The same approach is taken for static methods, constructors and member methods.
</p>

<p>
<b>Compatibility note:</b> Versions of SWIG prior to SWIG-1.3.23 wrapped these with a
single wrapper method and so the default values could not be taken advantage of from Java.
Further details on default arguments and how to restore this approach are given in the more general 
<a href="SWIGPlus.html#SWIGPlus_default_args">Default arguments</a> section.
</p>


<H3><a name="Java_namespaces"></a>25.3.13 C++ namespaces</H3>


<p>
SWIG is aware of named C++ namespaces and they can be mapped to Java packages, however, 
the default wrapping flattens the namespaces, effectively ignoring them.
So by default, the namespace names do not appear in
the module nor do namespaces result in a module that is broken up into
submodules or packages.  For example, if you have a file like this,
</p>

<div class="code">
<pre>
%module example

namespace foo {
   int fact(int n);
   struct Vector {
       double x,y,z;
   };
};
</pre>
</div>

<p>
it works in Java as follows:
</p>

<div class="code">
<pre>
int f = example.fact(3);
Vector v = new Vector();
v.setX(3.4);
double y = v.getY();
</pre>
</div>

<p>
If your program has more than one namespace, name conflicts (if any) can be resolved using <tt>%rename</tt>
For example:
</p>

<div class="code">
<pre>
%rename(Bar_spam) Bar::spam;

namespace Foo {
    int spam();
}

namespace Bar {
    int spam();
}
</pre>
</div>

<p>
If you have more than one namespace and you want to keep their
symbols separate, consider wrapping them as separate SWIG modules.
Each SWIG module can be placed into a separate package.
</p>

<p>
The default behaviour described above can be improved via the <a href="SWIGPlus.html#SWIGPlus_nspace">nspace feature</a>.
Note that it only works for classes, structs, unions and enums declared within a named C++ namespace.
When the nspace feature is used, the C++ namespaces are converted into Java packages of the same name.
Proxy classes are thus declared within a package and this proxy makes numerous calls to the JNI intermediary class which is declared in the unnamed package by default.
As Java does not support types declared in a named package accessing types declared in an unnamed package, the <tt>-package</tt> commandline option described earlier generally should be used to provide a parent package.
So if SWIG is run using the <tt>-package com.myco</tt> option, a wrapped class, <tt>MyWorld::Material::Color</tt>, can then be accessed as <tt>com.myco.MyWorld.Material.Color</tt>.
If you don't specify a package, you will get the following warning:
</p>

<div class="shell">
<pre>
example.i:16: Warning 826: The nspace feature is used on 'MyWorld::Material::Color' without -package. The generated code 
may not compile as Java does not support types declared in a named package accessing types declared in an unnamed package.
</pre>
</div>

<p>
If it is undesirable to have a single top level package, the nspace feature may be used without the <tt>-package</tt> commandline option
(and the resulting warning ignored) if all of the types exposed using SWIG are placed in a package using the nspace feature and the
'jniclasspackage' pragma is used to specify a package for the JNI intermediary class.
</p>

<p>
If the resulting use of the nspace feature and hence packages results in a proxy class in one package deriving or using a proxy class from another package,
you will need to open up the visibility for the pointer constructor and <tt>getCPtr</tt> method from the default 'protected' to 'public' with the <tt>SWIG_JAVABODY_PROXY</tt> macro. See <a href="#Java_code_typemaps">Java code typemaps</a>.
</p>

<H3><a name="Java_templates"></a>25.3.14 C++ templates</H3>


<p>
C++ templates don't present a huge problem for SWIG.  However, in order
to create wrappers, you have to tell SWIG to create wrappers for a particular
template instantiation.  To do this, you use the <tt>%template</tt> directive.
For example:
</p>

<div class="code">
<pre>
%module example
%{
#include &lt;utility&gt;
%}

template&lt;class T1, class T2&gt;
struct pair {
   typedef T1 first_type;
   typedef T2 second_type;
   T1 first;
   T2 second;
   pair();
   pair(const T1&amp;, const T2&amp;);
  ~pair();
};

%template(pairii) pair&lt;int,int&gt;;
</pre>
</div>

<p>
In Java:
</p>

<div class="code">
<pre>
pairii p = new pairii(3,4);
int first = p.getFirst();
int second = p.getSecond();
</pre>
</div>

<p>
Obviously, there is more to template wrapping than shown in this example.
More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter.   
</p>

<H3><a name="Java_smart_pointers"></a>25.3.15 C++ Smart Pointers</H3>


<p>
In certain C++ programs, it is common to use classes that have been wrapped by
so-called "smart pointers."   Generally, this involves the use of a template class
that implements <tt>operator-&gt;()</tt> like this:
</p>

<div class="code">
<pre>
template&lt;class T&gt; class SmartPtr {
   ...
   T *operator-&gt;();
   ...
}
</pre>
</div>

<p>
Then, if you have a class like this,
</p>

<div class="code">
<pre>
class Foo {
public:
     int x;
     int bar();
};
</pre>
</div>

<p>
A smart pointer would be used in C++ as follows:
</p>

<div class="code">
<pre>
SmartPtr&lt;Foo&gt; p = CreateFoo();   // Created somehow (not shown)
...
p-&gt;x = 3;                        // Foo::x
int y = p-&gt;bar();                // Foo::bar
</pre>
</div>

<p>
To wrap this in Java, simply tell SWIG about the <tt>SmartPtr</tt> class and the low-level
<tt>Foo</tt> object.  Make sure you instantiate <tt>SmartPtr</tt> using <tt>%template</tt> if necessary.
For example:
</p>

<div class="code">
<pre>
%module example
...
%template(SmartPtrFoo) SmartPtr&lt;Foo&gt;;
...
</pre>
</div>

<p>
Now, in Java, everything should just "work":
</p>

<div class="code">
<pre>
SmartPtrFoo p = example.CreateFoo(); // Create a smart-pointer somehow
p.setX(3);                           // Foo::x
int y = p.bar();                     // Foo::bar
</pre>
</div>

<p>
If you ever need to access the underlying pointer returned by <tt>operator-&gt;()</tt> itself,
simply use the <tt>__deref__()</tt> method.  For example:
</p>

<div class="code">
<pre>
Foo f = p.__deref__();               // Returns underlying Foo *
</pre>
</div>

<H2><a name="Java_further_details"></a>25.4 Further details on the generated Java classes</H2>


<p>
In the previous section, a high-level view of Java wrapping was
presented.  A key component of this wrapping is that structures and
classes are wrapped by Java proxy classes and type wrapper classes are used
in situations where no proxies are generated.  This provides a very
natural, type safe Java interface to the C/C++ code and fits in with the Java programming paradigm.
However, a number of low-level details were omitted.  This section provides a brief overview
of how the proxy classes work and then covers the type wrapper classes.
Finally enum classes are covered.
First, the crucial intermediary JNI class is considered.
</p>

<H3><a name="Java_imclass"></a>25.4.1 The intermediary JNI class</H3>


<p>
In the <a href="SWIG.html#SWIG">"SWIG basics"</a> and <a href="SWIGPlus.html#SWIGPlus">"SWIG and C++"</a> chapters,
details of low-level structure and class wrapping are described.  To summarize those chapters, if you
have a global function and class like this
</p>

<div class="code">
<pre>
class Foo {
public:
     int x;
     int spam(int num, Foo* foo);
};
void egg(Foo* chips);
</pre>
</div>

<p>
then SWIG transforms the class into a set of low-level procedural wrappers.
These procedural wrappers essentially perform the equivalent of this C++ code:
</p>

<div class="code">
<pre>
Foo *new_Foo() {
    return new Foo();
}
void delete_Foo(Foo *f) {
    delete f;
}
int Foo_x_get(Foo *f) {
    return f-&gt;x;
}
void Foo_x_set(Foo *f, int value) {
    f-&gt;x = value;
}
int Foo_spam(Foo *f, int num, Foo* foo) {
    return f-&gt;spam(num, foo);
}
</pre>
</div>

<p>
These procedural function names don't actually exist, but their functionality appears inside the generated
JNI functions. The JNI functions have to follow a particular naming convention so the function names are actually:
</p>

<div class="code">
<pre>
SWIGEXPORT jlong JNICALL Java_exampleJNI_new_1Foo(JNIEnv *jenv, jclass jcls);
SWIGEXPORT void JNICALL Java_exampleJNI_delete_1Foo(JNIEnv *jenv, jclass jcls,
                                                    jlong jarg1);
SWIGEXPORT void JNICALL Java_exampleJNI_Foo_1x_1set(JNIEnv *jenv, jclass jcls,
                                                    jlong jarg1, jobject jarg1_, jint jarg2);
SWIGEXPORT jint JNICALL Java_exampleJNI_Foo_1x_1get(JNIEnv *jenv, jclass jcls,
                                                    jlong jarg1, jobject jarg1_);
SWIGEXPORT jint JNICALL Java_exampleJNI_Foo_1spam(JNIEnv *jenv, jclass jcls,
                                                  jlong jarg1, jobject jarg1_, jint jarg2,
                                                  jlong jarg3, jobject jarg3_);
SWIGEXPORT void JNICALL Java_exampleJNI_egg(JNIEnv *jenv, jclass jcls,
                                            jlong jarg1, jobject jarg1_);
</pre>
</div>

<p>
For every JNI C function there has to be a static native Java function. These appear in the intermediary JNI class:
</p>

<div class="code">
<pre>
class exampleJNI {
  public final static native long new_Foo();
  public final static native void delete_Foo(long jarg1);
  public final static native void Foo_x_set(long jarg1, Foo jarg1_, int jarg2);
  public final static native int Foo_x_get(long jarg1, Foo jarg1_);
  public final static native int Foo_spam(long jarg1, Foo jarg1_, int jarg2,
                                          long jarg3, Foo jarg3_);
  public final static native void egg(long jarg1, Foo jarg1_);
}
</pre>
</div>

<p>
This class contains the complete Java - C/C++ interface so all function calls go via this class. 
As this class acts as a go-between for all JNI calls to C/C++ code from the Java <a href="#Java_proxy_classes">proxy classes</a>, <a href="#Java_type_wrapper_classes">type wrapper classes</a> and <a href="#Java_module_class">module class</a>, it is known as the intermediary JNI class.
</p>

<p>
You may notice that SWIG uses a Java long wherever a pointer or class object needs to be marshalled across the Java-C/C++ boundary.
This approach leads to minimal JNI code which makes for better performance as JNI code involves a lot of string manipulation.
SWIG favours generating Java code over JNI code as Java code is compiled into byte code and avoids the costly string operations needed in JNI code.
This approach has a downside though as the proxy class might get collected before the native method has completed.
You might notice above that there is an additional parameters with a underscore postfix, eg <tt>jarg1_</tt>.
These are added in order to prevent <a href="#Java_pgcpp">premature garbage collection when marshalling proxy classes</a>.
</p>

<p>
The functions in the intermediary JNI class cannot be accessed outside of its package. Access to them is gained through the module class for globals otherwise the appropriate proxy class.
</p>

<a name="Java_module_directive"></a>
<p>
The name of the intermediary JNI class can be changed from its default, that is, the module name with JNI appended after it. 
The module directive attribute <tt>jniclassname</tt> is used to achieve this:
</p>

<div class="code">
<pre>
%module (jniclassname="name") modulename
</pre>
</div>

<p>
If <tt>name</tt> is the same as <tt>modulename</tt> then the module class name gets changed
from <tt>modulename</tt> to <tt>modulenameModule</tt>.
</p>

<H4><a name="Java_imclass_pragmas"></a>25.4.1.1 The intermediary JNI class pragmas</H4>


<p>
The intermediary JNI class can be tailored through the use of pragmas, but is not commonly done. The pragmas for this class are:
</p>

<table BORDER summary="Intermediary JNI class pragmas">
<tr VALIGN=TOP>
<td><b>Pragma</b></td>
<td><b>Description</b></td>
</tr>

<tr>
    <td>jniclassbase            </td> <td>Base class for the intermediary JNI class</td>
</tr>
<tr>
    <td>jniclasspackage         </td> <td>Package in which to place the intermediary JNI class</td>
</tr>
<tr>
    <td>jniclassclassmodifiers  </td> <td>Class modifiers and class type for the intermediary JNI class</td>
</tr>
<tr>
    <td>jniclasscode            </td> <td>Java code is copied verbatim into the intermediary JNI class</td>
</tr>
<tr>
    <td>jniclassimports         </td> <td>Java code, usually one or more import statements, placed before the intermediary JNI class definition</td>
</tr>
<tr>
    <td>jniclassinterfaces      </td> <td>Comma separated interface classes for the intermediary JNI class</td>
</tr>
</table>

<p>
The pragma code appears in the generated intermediary JNI class where you would expect:
</p>

<div class="code">
<pre>
[ jniclassimports pragma ]
[ jniclassclassmodifiers pragma ] jniclassname extends [ jniclassbase pragma ]
                                          implements [ jniclassinterfaces pragma ] {
[ jniclasscode pragma ]
... SWIG generated native methods ...
}
</pre>
</div>

<p>
The <tt>jniclasscode</tt> pragma is quite useful for adding in a static block for loading the shared library / dynamic link library and demonstrates how pragmas work:
</p>

<div class="code">
<pre>
%pragma(java) jniclasscode=%{
  static {
    try {
        System.loadLibrary("example");
    } catch (UnsatisfiedLinkError e) {
      System.err.println("Native code library failed to load. \n" + e);
      System.exit(1);
    }
  }
%}
</pre>
</div>

<p>
Pragmas will take either <tt>""</tt> or <tt>%{ %}</tt> as delimiters. 
For example, let's change the intermediary JNI class access to just the default package-private access. 
</p>

<div class="code">
<pre>
%pragma(java) jniclassclassmodifiers="class"
</pre>
</div>

<p>
All the methods in the intermediary JNI class will then not be callable outside of the package as the method modifiers have been changed from public access to default access. This is useful if you want to prevent users calling these low level functions.
</p>

<H3><a name="Java_module_class"></a>25.4.2 The Java module class</H3>


<p>
All global functions and variable getters/setters appear in the module class. For our example, there is just one function:
</p>

<div class="code">
<pre>
public class example {
  public static void egg(Foo chips) {
    exampleJNI.egg(Foo.getCPtr(chips), chips);
  }
}
</pre>
</div>

<p>
The module class is necessary as there is no such thing as a global in Java so all the C globals are put into this class. They are generated as static functions and so must be accessed as such by using the module name in the static function call:
</p>

<div class="code">
<pre>
example.egg(new Foo());
</pre>
</div>

<p>
The primary reason for having the module class wrapping the calls in the intermediary JNI class is to implement static type checking. In this case only a <tt>Foo</tt> can be passed to the <tt>egg</tt> function, whereas any <tt>long</tt> can be passed to the <tt>egg</tt> function in the intermediary JNI class.
</p>

<H4><a name="Java_module_class_pragmas"></a>25.4.2.1 The Java module class pragmas</H4>


<p>
The module class can be tailored through the use of pragmas, in the same manner as the intermediary JNI class. The pragmas are similarly named and are used in the same way. The complete list follows:
</p>

<table BORDER summary="Java module class pragmas">
<tr VALIGN=TOP>
<td><b>Pragma</b></td>
<td><b>Description</b></td>
</tr>
<tr>
    <td>modulebase            </td> <td>Base class for the module class</td>
</tr>
<tr>
    <td>moduleclassmodifiers  </td> <td>Class modifiers and class type for the module class</td>
</tr>
<tr>
    <td>modulecode            </td> <td>Java code is copied verbatim into the module class</td>
</tr>
<tr>
    <td>moduleimports         </td> <td>Java code, usually one or more import statements, placed before the module class definition</td>
</tr>
<tr>
    <td>moduleinterfaces      </td> <td>Comma separated interface classes for the module class</td>
</tr>

</table>


<p>
The pragma code appears in the generated module class like this:
</p>

<div class="code">
<pre>
[ moduleimports pragma ]
[ modulemodifiers pragma ] modulename extends [ modulebase pragma ]
                                      implements [ moduleinterfaces pragma ] {
[ modulecode pragma ]
... SWIG generated wrapper functions ...
}
</pre>
</div>

<p>
See <a href="#Java_imclass_pragmas">The intermediary JNI class pragmas</a> section for further details on using pragmas.
</p>


<H3><a name="Java_proxy_classes"></a>25.4.3 Java proxy classes</H3>


<p>
A Java proxy class is generated for each structure, union or C++ class that is wrapped.
Proxy classes have also been called <a href="http://java.sun.com/docs/books/jni/html/stubs.html">peer classes</a>.
The default proxy class for our previous example looks like this:
</p>

<div class="code">
<pre>
public class Foo {
  private transient long swigCPtr;
  protected transient boolean swigCMemOwn;

  protected Foo(long cPtr, boolean cMemoryOwn) {
    swigCMemOwn = cMemoryOwn;
    swigCPtr = cPtr;
  }

  protected static long getCPtr(Foo obj) {
    return (obj == null) ? 0 : obj.swigCPtr;
  }

  protected void finalize() {
    delete();
  }

  public synchronized void delete() {
    if(swigCPtr != 0 &amp;&amp; swigCMemOwn) {
      swigCMemOwn = false;
      exampleJNI.delete_Foo(swigCPtr);
    }
    swigCPtr = 0;
  }

  public void setX(int value) {
    exampleJNI.Foo_x_set(swigCPtr, this, value);
  }

  public int getX() {
    return exampleJNI.Foo_x_get(swigCPtr, this);
  }

  public int spam(int num, Foo foo) {
    return exampleJNI.Foo_spam(swigCPtr, this, num, Foo.getCPtr(foo), foo);
  }

  public Foo() {
    this(exampleJNI.new_Foo(), true);
  }

}
</pre>
</div>


<p>
This class merely holds a pointer to the underlying C++ object (<tt>swigCPtr</tt>).
It also contains all the methods in the C++ class it is proxying plus getters and setters for public
member variables. These functions call the native methods in the intermediary JNI class. 
The advantage of having this extra layer is the type safety that the proxy class functions offer. 
It adds static type checking which leads to fewer surprises at runtime. 
For example, you can see that if you attempt to use the <tt>spam()</tt>
function it will only compile when the parameters passed are an <tt>int</tt> and a <tt>Foo</tt>. 
From a user's point of view, it makes the class work as if it were a Java class:
</p>

<div class="code">
<pre>
Foo f = new Foo();
f.setX(3);
int y = f.spam(5, new Foo());
</pre>
</div>

<H4><a name="Java_memory_management"></a>25.4.3.1 Memory management</H4>


<p>
Each proxy class has an ownership flag <tt>swigCMemOwn</tt>.   The value of this
flag determines who is responsible for deleting the underlying C++ object.   If set to <tt>true</tt>,
the proxy class's finalizer will destroy the C++ object when the proxy class is 
garbage collected.   If set to false, then the destruction of the proxy class has no effect on the C++ object.
</p>

<p>
When an object is created by a constructor or returned by value, Java automatically takes
ownership of the result. 
On the other hand, when pointers or references are returned to Java, there is often no way to know where
they came from.  Therefore, the ownership is set to false.  For example:
</p>


<div class="code">
<pre>
class Foo {
public:
    Foo();
    Foo bar1();
    Foo &amp;bar2();
    Foo *bar2();
};
</pre>
</div>

<p>
In Java:
</p>

<div class="code">
<pre>
Foo f = new Foo();   //  f.swigCMemOwn = true
Foo f1 = f.bar1();   // f1.swigCMemOwn = true
Foo f2 = f.bar2();   // f2.swigCMemOwn = false
Foo f3 = f.bar3();   // f3.swigCMemOwn = false
</pre>
</div>

<p>
This behavior for pointers and references is especially important for classes that act as containers.  
For example, if a method returns a pointer to an object
that is contained inside another object, you definitely don't want
Java to assume ownership and destroy it!
</p>

<p>
For the most part, memory management issues remain hidden.  However,
there are situations where you might have to manually
change the ownership of an object.  For instance, consider code like this:
</p>

<div class="code">
<pre>
class Obj {};
class Node {
   Obj *value;
public:
   void set_value(Obj *v) { value = v; }
};
</pre>
</div>

<p>
Now, consider the following Java code:
</p>

<div class="code">
<pre>
Node n = new Node();    // Create a node
{
  Obj o = new Obj();    // Create an object
  n.set_value(o);       // Set value
}                       // o goes out of scope
</pre>
</div>

<p>
In this case, the Node <tt>n</tt> is holding a reference to
<tt>o</tt> internally.  However, SWIG has no way to know that this
has occurred.  The Java proxy class still thinks that it has ownership of 
<tt>o</tt>.  As <tt>o</tt> has gone out of scope, it could be garbage collected in which case the C++ destructor
will be invoked and <tt>n</tt> will then be holding a stale-pointer to <tt>o</tt>.  If
you're lucky, you will only get a segmentation fault.
</p>

<p>
To work around this, the ownership flag of <tt>o</tt> needs changing to <tt>false</tt>. 
The ownership flag is a private member variable of the proxy class so this is not possible without some customization of the proxy class. 
This can be achieved by using a typemap to customise the proxy class with pure Java code as detailed later in the section on 
<a href="#Java_typemaps">Java typemaps</a>.
</p>

<p>
Sometimes a function will create memory and return a pointer to a newly allocated object. 
SWIG has no way of knowing this so by default the proxy class does not manage the returned object.
However, you can tell the proxy class to manage the memory if you specify the <tt>%newobject</tt> directive. Consider:
</p>

<div class="code">
<pre>
class Obj {...};
class Factory {
public:
    static Obj *createObj() { return new Obj(); }
};
</pre>
</div>

<p>
If we call the factory function, then we have to manually delete the memory:
</p>

<div class="code">
<pre>
Obj obj = Factory.createObj();   // obj.swigCMemOwn = false
...
obj.delete();
</pre>
</div>

<p>
Now add in the %newobject directive:
</p>

<div class="code">
<pre>
%newobject Factory::createObj();

class Obj {...};
class Factory {
public:
    static Obj *createObj() { return new Obj(); }
};
</pre>
</div>

<p>
A call to <tt>delete()</tt> is no longer necessary as the garbage collector will make the C++ destructor call because <tt>swigCMemOwn</tt> is now true.
</p>

<div class="code">
<pre>
Obj obj = Factory.createObj();   // obj.swigCMemOwn = true;
...
</pre>
</div>

<p>
Some memory management issues are quite tricky to fix and may only be noticeable after using for a long time.
One such issue is premature garbage collection of an object created from Java and resultant usage from C++ code.
The section on typemap examples cover two such scenarios, 
<a href="#Java_memory_management_objects">Memory management for objects passed to the C++ layer</a>
and 
<a href="#Java_memory_management_member_variables">Memory management when returning references to member variables</a>
</p>


<H4><a name="Java_inheritance_mirroring"></a>25.4.3.2 Inheritance</H4>


<p>
Java proxy classes will mirror C++ inheritance chains. For example, given the base class <tt>Base</tt> and its derived class <tt>Derived</tt>:
</p>

<div class="code"><pre>
class Base {
public:
  virtual double foo();
};

class Derived : public Base {
public:
  virtual double foo();
};
</pre></div>

<p>
The base class is generated much like any other proxy class seen so far:
</p>

<div class="code"><pre>
public class Base {
  private transient long swigCPtr;
  protected transient boolean swigCMemOwn;

  protected Base(long cPtr, boolean cMemoryOwn) {
    swigCMemOwn = cMemoryOwn;
    swigCPtr = cPtr;
  }

  protected static long getCPtr(Base obj) {
    return (obj == null) ? 0 : obj.swigCPtr;
  }

  protected void finalize() {
    delete();
  }

  public synchronized void delete() {
    if(swigCPtr != 0 &amp;&amp; swigCMemOwn) {
      swigCMemOwn = false;
      exampleJNI.delete_Base(swigCPtr);
    }
    swigCPtr = 0;
  }

  public double foo() {
    return exampleJNI.Base_foo(swigCPtr, this);
  }

  public Base() {
    this(exampleJNI.new_Base(), true);
  }

}
</pre></div>

<p>
The <tt>Derived</tt> class extends <tt>Base</tt> mirroring the C++ class inheritance hierarchy. 
</p>

<div class="code"><pre>
public class Derived extends Base {
  private transient long swigCPtr;

  protected Derived(long cPtr, boolean cMemoryOwn) {
    super(exampleJNI.SWIGDerivedUpcast(cPtr), cMemoryOwn);
    swigCPtr = cPtr;
  }

  protected static long getCPtr(Derived obj) {
    return (obj == null) ? 0 : obj.swigCPtr;
  }

  protected void finalize() {
    delete();
  }

  public synchronized void delete() {
    if(swigCPtr != 0 &amp;&amp; swigCMemOwn) {
      swigCMemOwn = false;
      exampleJNI.delete_Derived(swigCPtr);
    }
    swigCPtr = 0;
    super.delete();
  }

  public double foo() {
    return exampleJNI.Derived_foo(swigCPtr, this);
  }

  public Derived() {
    this(exampleJNI.new_Derived(), true);
  }

}
</pre></div>

<p>
Note the memory ownership is controlled by the base class. 
However each class in the inheritance hierarchy has its own pointer value which is obtained during construction. 
The <tt>SWIGDerivedUpcast()</tt> call converts the pointer from a <tt>Derived *</tt> to a <tt>Base *</tt>.
This is a necessity as C++ compilers are free to implement pointers in the inheritance hierarchy with different values. 
</p>

<p>
It is of course possible to extend <tt>Base</tt> using your own Java classes. 
If <tt>Derived</tt> is provided by the C++ code, you could for example add in a pure Java class <tt>Extended</tt> derived from <tt>Base</tt>. 
There is a caveat and that is any C++ code will not know about your pure Java class <tt>Extended</tt> so this type of derivation is restricted.
However, true cross language polymorphism can be achieved using the <a href="#Java_directors">directors</a> feature.
</p>


<H4><a name="Java_proxy_classes_gc"></a>25.4.3.3 Proxy classes and garbage collection</H4>


<p>
By default each proxy class has a <tt>delete()</tt> and a <tt>finalize()</tt> method. 
The <tt>finalize()</tt> method calls <tt>delete()</tt> which frees any malloc'd memory for wrapped C structs or calls the C++ class destructors. 
The idea is for <tt>delete()</tt> to be called when you have finished with the C/C++ object. 
Ideally you need not call <tt>delete()</tt>, but rather leave it to the garbage collector to call it from the finalizer. 
When a program exits, the garbage collector does not guarantee to call all finalizers. 
An insight into the reasoning behind this can be obtained from <a href="http://www.hpl.hp.com/techreports/2002/HPL-2002-335.html">Hans Boehm's Destructors, Finalizers, and Synchronization</a> paper.
Depending on what the finalizers do and which operating system you use, this may or may not be a problem. 
</p>

<p>
If the <tt>delete()</tt> call into JNI code is just for memory handling, there is not a problem when run on most operating systems, for example Windows and Unix. 
Say your JNI code creates memory on the heap which your finalizers should clean up, the finalizers may or may not be called before the program exits. 
In Windows and Unix all memory that a process uses is returned to the system on exit, so this isn't a problem. 
This is not the case in some operating systems like vxWorks. 
If however, your finalizer calls into JNI code invoking the C++ destructor which in turn releases a TCP/IP socket for example, there is no guarantee that it will be released. 
Note that with long running programs the garbage collector will eventually run, thereby calling any unreferenced object's finalizers.
</p>

<p>
Some not so ideal solutions are:
</p>

<ol>
<li><p>
Call the <tt>System.runFinalizersOnExit(true)</tt> or <tt>Runtime.getRuntime().runFinalizersOnExit(true)</tt> to ensure the finalizers are called before the program exits. The catch is that this is a deprecated function call as the documentation says: </p>
<div class="code"><i>
This method is inherently unsafe. It may result in finalizers being called on live objects while other threads are concurrently manipulating those objects, resulting in erratic behavior or deadlock.
</i></div> 
<p>In many cases you will be lucky and find that it works, but it is not to be advocated. 
Have a look at <a href="http://www.oracle.com/technetwork/java/index.html">Java web site</a> and search for <tt>runFinalizersOnExit</tt>.
</p></li>

<li><p>
From jdk1.3 onwards a new function, <tt>addShutdownHook()</tt>, was introduced which is guaranteed to be called when your program exits. 
You can encourage the garbage collector to call the finalizers, for example, add this static block to the class that has the <tt>main()</tt> function: </p>
<div class="code"><pre>
  static {
    Runtime.getRuntime().addShutdownHook( 
      new Thread() {
        public void run() { System.gc(); System.runFinalization(); }
      }
    );
  }
</pre></div>
<p>Although this usually works, the documentation doesn't guarantee that <tt>runFinalization()</tt> will actually call the finalizers. 
As the shutdown hook is guaranteed you could also make a JNI call to clean up any resources that are being tracked by the C/C++ code.</p>
</li>

<li>
<p>Call the <tt>delete()</tt> function manually which will immediately invoke the C++ destructor. 
As a suggestion it may be a good idea to set the object to null so that should the object be inadvertently used again a Java null pointer exception is thrown, the alternative would crash the JVM by using a null C pointer. 
For example given a SWIG generated class A:</p>
<div class="code"><pre>
A myA = new A();
// use myA ...
myA.delete();
// any use of myA here would crash the JVM 
myA=null;
// any use of myA here would cause a Java null pointer exception to be thrown
</pre></div>

<p>
The SWIG generated code ensures that the memory is not deleted twice, in the event the finalizers get called in addition to the manual <tt>delete()</tt> call.
</p>
</li>

<li>
<p>
Write your own object manager in Java. 
You could derive all SWIG classes from a single base class which could track which objects have had their finalizers run, then call the rest of them on program termination.
The section on <a href="#Java_typemaps">Java typemaps</a> details how to specify a pure Java base class.
</p>
</li>
</ol>

<p>
See the <a href="http://www.devx.com/Java/Article/30192">How to Handle Java Finalization's Memory-Retention Issues</a> article for alternative approaches to managing memory by avoiding finalizers altogether.
</p>

<H4><a name="Java_pgcpp"></a>25.4.3.4 The premature garbage collection prevention parameter for proxy class marshalling</H4>


<p>
As covered earlier, the C/C++ struct/class pointer is stored in the proxy class as a Java long and when needed is passed
into the native method where it is cast into the appropriate type.
This approach provides very fast marshalling but could be susceptible to premature garbage collection.
Consider the following C++ code:
</p>

<div class="code"><pre>
class Wibble {
};
void wobble(Wibble &amp;w);
</pre></div>

<p>
The module class contains the Java wrapper for the global <tt>wobble</tt> method:
</p>

<div class="code"><pre>
public class example {
  ...
  public static void wobble(Wibble w) {
    exampleJNI.wobble(Wibble.getCPtr(w), w);
  }
}
</pre></div>

<p>
where <tt>example</tt> is the name of the module. 
All native methods go through the intermediary class which has the native method declared as such:
</p>

<div class="code"><pre>
public class exampleJNI {
  ...
  public final static native void wobble(long jarg1, Wibble jarg1_);
}
</pre></div>

<p>
The second parameter, <tt>jarg1_</tt>, is the premature garbage collection prevention parameter and is added to the native method parameter list whenever a C/C++ struct or class is marshalled as a Java long.
In order to understand why, consider the alternative where the intermediary class method is declared without the additional parameter:
</p>

<div class="code"><pre>
public class exampleJNI {
  ...
  public final static native void wobble(long jarg1);
}
</pre></div>

<p>
and the following simple call to <tt>wobble</tt>:
</p>

<div class="code"><pre>
{
  Wibble w = new Wibble();
  example.wobble(w);
}
</pre></div>

<p>
The hotspot compiler effectively sees something like:
</p>

<div class="code"><pre>
{
  Wibble w = new Wibble();
  long w_ptr = Wibble.getCPtr(w);
  // w is no longer reachable
  exampleJNI.wobble(w_ptr);
}
</pre></div>

<p>
The <tt>Wibble</tt> object is no longer reachable after the point shown as in this bit of code, the <tt>Wibble</tt> object is not referenced again after this point.
This means that it is a candidate for garbage collection.
Should <tt>wobble</tt> be a long running method, it is quite likely that the finalizer for the <tt>Wibble</tt> instance will be called.
This in turn will call its underlying C++ destructor which 
is obviously disastrous while the method <tt>wobble</tt> is running using this object.
Even if <tt>wobble</tt> is not a long running method, it is possible for the <tt>Wibble</tt> instance to be finalized.
By passing the <tt>Wibble</tt> instance into the native method, it will not be finalized as the JVM guarantees not to
finalize any objects until the native method returns.
Effectively, the code then becomes
</p>

<div class="code"><pre>
{
  Wibble w = new Wibble();
  long w_ptr = Wibble.getCPtr(w);
  exampleJNI.wobble(w_ptr, w);
  // w is no longer reachable
}
</pre></div>

<p>
and therefore there is no possibility of premature garbage collection. In practice, this premature garbage collection was only ever observed in Sun's server JVM from jdk-1.3 onwards and in Sun's client JVM from jdk-1.6 onwards.
</p>

<p>
The premature garbage collection prevention parameter for proxy classes is generated by default whenever proxy classes are passed by value, reference or with a pointer.
The implementation for this extra parameter generation requires the "jtype" typemap to contain <tt>long</tt> and the "jstype" typemap to contain the name of a proxy class.
</p>

<p>
The additional parameter does impose a slight performance overhead and the parameter generation can be suppressed globally with the <tt>-nopgcpp</tt> commandline option.
More selective suppression is possible with the 'nopgcpp' attribute in the "jtype" <a href="#Java_typemaps">Java typemap</a>.
The attribute is a flag and so should be set to "1" to enable the suppression, or it can be omitted or set to "0" to disable.
For example:
</p>

<div class="code"><pre>
%typemap(jtype, nopgcpp="1") Wibble &amp; "long"
</pre></div>

<p>
<b>Compatibility note:</b> The generation of this additional parameter did not occur in versions prior to SWIG-1.3.30.
</p>

<H4><a name="Java_multithread_libraries"></a>25.4.3.5 Single threaded applications and thread safety</H4>


<p>
Single threaded Java applications using JNI need to consider thread safety.
The same applies for the C# module where the .NET wrappers use PInvoke.
Consider the C++ class:
</p>

<div class="code"><pre>
class Test {
  string str;
public:
  Test() : str("initial") {}
};
</pre></div>

<p>
and the Java proxy class generated by SWIG:
</p>

<div class="code"><pre>
public class Test {
  private transient long swigCPtr;
  protected transient boolean swigCMemOwn;

  protected Test(long cPtr, boolean cMemoryOwn) {
    swigCMemOwn = cMemoryOwn;
    swigCPtr = cPtr;
  }

  protected static long getCPtr(Test obj) {
    return (obj == null) ? 0 : obj.swigCPtr;
  }

  protected void finalize() {
    delete();
  }

  // Call C++ destructor
  public synchronized void delete() {
    if(swigCPtr != 0 &amp;&amp; swigCMemOwn) {
      swigCMemOwn = false;
      exampleJNI.delete_Test(swigCPtr);
    }
    swigCPtr = 0;
  }

  // Call C++ constructor
  public Test() {
    this(exampleJNI.new_Test(), true);
  }

}
</pre></div>


<p>
It has two methods that call JNI methods, namely, <tt>exampleJNI.new_Test()</tt> for the C++ constructor and <tt>exampleJNI.delete_Test()</tt> for the C++ destructor. 
If the garbage collector collects an instance of this class, ie <tt>delete()</tt> is not explicitly called, then the C++ destructor will be run in a different thread to the main thread. 
This is because when an object is marked for garbage collection, any objects with finalizers are added to a finalization queue 
and the objects in the finalization queue have their <tt>finalize()</tt> methods run in a separate finalization thread. 
Therefore, if the C memory allocator is not thread safe, then the heap will get corrupted sooner or later, when a concurrent C++ delete and new are executed. 
It is thus essential, even in single threaded usage, to link to the C multi-thread runtime libraries,
for example, use the /MD option for Visual C++ on Windows.
Alternatively, lock all access to C++ functions that have heap allocation/deallocation. 
</p>

<p>
Note that some of the STL in Visual C++ 6 is not thread safe, so although code might be linked to the multithread runtime libraries, undefined behaviour might still occur in a single threaded Java program.
Similarly some older versions of Sun Studio have bugs in the multi-threaded implementation of the std::string class and so will lead to undefined behaviour in these supposedly single threaded Java applications.
</p>

<p>
The following innocuous Java usage of Test is an example that will crash very quickly on a multiprocessor machine if the JNI compiled code is linked against the single thread C runtime libraries.
</p>
 
<div class="code"><pre>
for (int i=0; i&lt;100000; i++) {
  System.out.println("Iteration " + i);
  for (int k=0; k&lt;10; k++) {
    Test test = new Test();
  }
  System.gc();
}
</pre></div>
 

<H3><a name="Java_type_wrapper_classes"></a>25.4.4 Type wrapper classes</H3>


<p>
The generated type wrapper class, for say an <tt>int *</tt>, looks like this:
</p>

<div class="code"><pre>
public class SWIGTYPE_p_int {
  private transient long swigCPtr;

  protected SWIGTYPE_p_int(long cPtr, boolean bFutureUse) {
    swigCPtr = cPtr;
  }

  protected SWIGTYPE_p_int() {
    swigCPtr = 0;
  }

  protected static long getCPtr(SWIGTYPE_p_int obj) {
    return obj.swigCPtr;
  }
}
</pre></div>

<p>
The methods do not have public access, so by default it is impossible to do anything with objects of this class other than 
pass them around. The methods in the class are part of the inner workings of SWIG. 
If you need to mess around with pointers you will have to use some typemaps specific to the Java module to achieve this.
The section on <a href="#Java_typemaps">Java typemaps</a> details how to modify the generated code.
</p>

<p>
Note that if you use a pointer or reference to a proxy class in a function then no type wrapper class is generated because the proxy class can be used
as the function parameter. If however,  you need anything more complicated like a pointer to a pointer to a proxy class then a typewrapper class
is generated for your use. 
</p>

<p>
Note that SWIG generates a type wrapper class and not a proxy class when it has not parsed the definition of a type that gets used. 
For example, say SWIG has not parsed the definition of <tt>class Snazzy</tt> because it is in a header file that you may have forgotten to use the <tt>%include</tt> directive on.
Should SWIG parse <tt>Snazzy *</tt> being used in a function parameter, it will then generates a type wrapper class around a <tt>Snazzy</tt> pointer.
Also recall from earlier that SWIG will use a pointer when a class is passed by value or by reference:
</p>

<div class="code">
<pre>
void spam(Snazzy *x, Snazzy &amp;y, Snazzy z);
</pre>
</div>

<p>
Should SWIG not know anything about <tt>Snazzy</tt> then a <tt>SWIGTYPE_p_Snazzy</tt> must be used for all 3 parameters in the <tt>spam</tt> function.
The Java function generated is:
</p>

<div class="code">
<pre>
public static void spam(SWIGTYPE_p_Snazzy x, SWIGTYPE_p_Snazzy y, SWIGTYPE_p_Snazzy z) {
 ...
}
</pre>
</div>

<p>
Note that typedefs are tracked by SWIG and the typedef name is used to construct the type wrapper class name. For example, consider the case where <tt>Snazzy</tt> is a typedef to an <tt>int</tt> which SWIG does parse:
</p>


<div class="code">
<pre>
typedef int Snazzy;
void spam(Snazzy *x, Snazzy &amp;y, Snazzy z);
</pre>
</div>

<p>
Because the typedefs have been tracked the Java function generated is:
</p>

<div class="code">
<pre>
public static void spam(SWIGTYPE_p_int x, SWIGTYPE_p_int y, int z) { ... }
</pre>
</div>


<H3><a name="Java_enum_classes"></a>25.4.5 Enum classes</H3>


<p>
SWIG can generate three types of enum classes.
The <a href="#Java_enumerations">Enumerations</a> section discussed these but omitted all the details.
The following sub-sections detail the various types of enum classes that can be generated.
</p>

<H4><a name="Java_typesafe_enums_classes"></a>25.4.5.1 Typesafe enum classes</H4>


<p>
The following example demonstrates the typesafe enum classes which SWIG generates:
</p>

<div class="code">
<pre>
%include "enumtypesafe.swg"
%javaconst(1);
enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
</pre>
</div>

<p>
The following is the code that SWIG generates:
</p>

<div class="code">
<pre>
public final class Beverage {
  public final static Beverage ALE = new Beverage("ALE");
  public final static Beverage LAGER = new Beverage("LAGER", 10);
  public final static Beverage STOUT = new Beverage("STOUT");
  public final static Beverage PILSNER = new Beverage("PILSNER");
  public final static Beverage PILZ = new Beverage("PILZ", PILSNER);

  public final int swigValue() {
    return swigValue;
  }

  public String toString() {
    return swigName;
  }

  public static Beverage swigToEnum(int swigValue) {
    if (swigValue &lt; swigValues.length &amp;&amp; swigValue &gt;= 0 &amp;&amp;
        swigValues[swigValue].swigValue == swigValue)
      return swigValues[swigValue];
    for (int i = 0; i &lt; swigValues.length; i++)
      if (swigValues[i].swigValue == swigValue)
        return swigValues[i];
    throw new IllegalArgumentException("No enum " + Beverage.class + " with value " +
                                                                         swigValue);
  }

  private Beverage(String swigName) {
    this.swigName = swigName;
    this.swigValue = swigNext++;
  }

  private Beverage(String swigName, int swigValue) {
    this.swigName = swigName;
    this.swigValue = swigValue;
    swigNext = swigValue+1;
  }

  private Beverage(String swigName, Beverage swigEnum) {
    this.swigName = swigName;
    this.swigValue = swigEnum.swigValue;
    swigNext = this.swigValue+1;
  }

  private static Beverage[] swigValues = { ALE, LAGER, STOUT, PILSNER, PILZ };
  private static int swigNext = 0;
  private final int swigValue;
  private final String swigName;
}
</pre>
</div>

<p>
As can be seen, there are a fair number of support methods for the typesafe enum pattern.
The typesafe enum pattern involves creating a fixed number of static instances of the enum class.
The constructors are private to enforce this.
Three constructors are available - two for C/C++ enums with an initializer and one for those without an initializer.
Note that the two enums with initializers, <tt>LAGER</tt> and <tt>PILZ</tt>, each call one the two different initializer constructors.
In order to use one of these typesafe enums, the <tt>swigToEnum</tt> static method must be called to return a reference to one of the static instances.
The JNI layer returns the enum value from the C/C++ world as an integer and this method is used to find the appropriate Java enum static instance.
The <tt>swigValue</tt> method is used for marshalling in the other direction.
The <tt>toString</tt> method is overridden so that the enum name is available.
</p>

<H4><a name="Java_proper_enums_classes"></a>25.4.5.2 Proper Java enum classes</H4>


<p>
The following example demonstrates the Java enums approach:
</p>

<div class="code">
<pre>
%include "enums.swg"
%javaconst(1);
enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
</pre>
</div>

<p>
SWIG will generate the following Java enum:
</p>

<div class="code">
<pre>
public enum Beverage {
  ALE,
  LAGER(10),
  STOUT,
  PILSNER,
  PILZ(PILSNER);

  public final int swigValue() {
    return swigValue;
  }

  public static Beverage swigToEnum(int swigValue) {
    Beverage[] swigValues = Beverage.class.getEnumConstants();
    if (swigValue &lt; swigValues.length &amp;&amp; swigValue &gt;= 0 &amp;&amp;
        swigValues[swigValue].swigValue == swigValue)
      return swigValues[swigValue];
    for (Beverage swigEnum : swigValues)
      if (swigEnum.swigValue == swigValue)
        return swigEnum;
    throw new IllegalArgumentException("No enum " + Beverage.class +
                                       " with value " + swigValue);
  }

  private Beverage() {
    this.swigValue = SwigNext.next++;
  }

  private Beverage(int swigValue) {
    this.swigValue = swigValue;
    SwigNext.next = swigValue+1;
  }

  private Beverage(Beverage swigEnum) {
    this.swigValue = swigEnum.swigValue;
    SwigNext.next = this.swigValue+1;
  }

  private final int swigValue;

  private static class SwigNext {
    private static int next = 0;
  }
}
</pre>
</div>

<p>
The enum items appear first.
Like the typesafe enum pattern, the constructors are private.
The constructors are required to handle C/C++ enums with initializers.
The <tt>next</tt> variable is in the <tt>SwigNext</tt> inner class rather than in the enum class as static primitive variables cannot be modified from within enum constructors.
Marshalling between Java enums and the C/C++ enum integer value is handled via the <tt>swigToEnum</tt> and <tt>swigValue</tt> methods.
All the constructors and methods in the Java enum are required just to handle C/C++ enums with initializers.
These needn't be generated if the enum being wrapped does not have any initializers and the 
<a href="#Java_simpler_enum_classes">Simpler Java enums for enums without initializers</a> section describes how typemaps can be used to achieve this.
</p>

<H4><a name="Java_typeunsafe_enums_classes"></a>25.4.5.3 Type unsafe enum classes</H4>


<p>
The following example demonstrates type unsafe enums:
</p>

<div class="code">
<pre>
%include "enumtypeunsafe.swg"
%javaconst(1);
enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
</pre>
</div>

<p>
SWIG will generate the following simple class:
</p>

<div class="code">
<pre>
public final class Beverage {
  public final static int ALE = 0;
  public final static int LAGER = 10;
  public final static int STOUT = LAGER + 1;
  public final static int PILSNER = STOUT + 1;
  public final static int PILZ = PILSNER;
}
</pre>
</div>

<H2><a name="Java_directors"></a>25.5 Cross language polymorphism using directors</H2>


<p>
Proxy classes provide a natural, object-oriented way to wrap C++ classes.
as described earlier, each proxy instance has an associated C++ instance, and method calls from Java to the proxy are passed to the C++ instance transparently via C wrapper functions.
</p>

<p>
This arrangement is asymmetric in the sense that no corresponding mechanism exists to pass method calls down the inheritance chain from C++ to Java. 
In particular, if a C++ class has been extended in Java (by deriving from the proxy class), these classes will not be visible from C++ code. 
Virtual method calls from C++ are thus not able to access the lowest implementation in the inheritance chain.
</p>

<p>
SWIG can address this problem and make the relationship between C++ classes and proxy classes more symmetric. 
To achieve this goal, new classes called directors are introduced at the bottom of the C++ inheritance chain. 
The job of the directors is to route method calls correctly, either to C++ implementations higher in the inheritance chain or to Java implementations lower in the inheritance chain. 
The upshot is that C++ classes can be extended in Java and from C++ these extensions look exactly like native C++ classes. 
Neither C++ code nor Java code needs to know where a particular method is implemented: the combination of proxy classes, director classes, and C wrapper functions transparently takes care of all the cross-language method routing.
</p>

<H3><a name="Java_enabling_directors"></a>25.5.1 Enabling directors</H3>


<p>
The director feature is disabled by default.
To use directors you must make two changes to the interface file.
First, add the "directors" option to the %module directive, like this:
</p>

<div class="code">
<pre>
%module(directors="1") modulename
</pre>
</div>

<p>
Without this option no director code will be generated.
Second, you must use the %feature("director") directive to tell SWIG which classes and methods should get directors.
The %feature directive can be applied globally, to specific classes, and to specific methods, like this:
</p>

<div class="code">
<pre>
// generate directors for all classes that have virtual methods
%feature("director");         

// generate directors for all virtual methods in class Foo
%feature("director") Foo;      
</pre>
</div>

<p>
You can use the %feature("nodirector") directive to turn off directors for specific classes or methods.
So for example,
</p>

<div class="code">
<pre>
%feature("director") Foo;
%feature("nodirector") Foo::bar;
</pre>
</div>

<p>
will generate directors for all virtual methods of class Foo except bar().  
</p>

<p>
Directors can also be generated implicitly through inheritance. 
In the following, class Bar will get a director class that handles the methods one() and two() (but not three()):
</p>

<div class="code">
<pre>
%feature("director") Foo;
class Foo {
public:
    virtual void one();
    virtual void two();
};

class Bar: public Foo {
public:
    virtual void three();
};
</pre>
</div>

<H3><a name="Java_directors_classes"></a>25.5.2 Director classes</H3>


<p>
For each class that has directors enabled, SWIG generates a new class that derives from both the class in question and a special <tt>Swig::Director</tt> class. 
These new classes, referred to as director classes, can be loosely thought of as the C++ equivalent of the Java proxy classes.
The director classes store a pointer to their underlying Java proxy classes.
</p>

<p>
For simplicity let's ignore the <tt>Swig::Director</tt> class and refer to the original C++ class as the director's base class.
By default, a director class extends all virtual methods in the inheritance chain of its base class (see the preceding section for how to modify this behavior).
Thus all virtual method calls, whether they originate in C++ or in Java via proxy classes, eventually end up in at the implementation in the director class.
The job of the director methods is to route these method calls to the appropriate place in the inheritance chain.
By "appropriate place" we mean the method that would have been called if the C++ base class and its Java derived classes were seamlessly integrated.
That seamless integration is exactly what the director classes provide, transparently skipping over all the messy JNI glue code that binds the two languages together.
</p>

<p>
In reality, the "appropriate place" is one of only two possibilities: C++ or Java.
Once this decision is made, the rest is fairly easy.
If the correct implementation is in C++, then the lowest implementation of the method in the C++ inheritance chain is called explicitly.
If the correct implementation is in Java, the Java API is used to call the method of the underlying Java object 
(after which the usual virtual method resolution in Java automatically finds the right implementation).
</p>


<H3><a name="Java_directors_overhead"></a>25.5.3 Overhead and code bloat</H3>


<p>
Enabling directors for a class will generate a new director method for every virtual method in the class' inheritance chain.
This alone can generate a lot of code bloat for large hierarchies.
Method arguments that require complex conversions to and from Java types can result in large director methods.
For this reason it is recommended that directors are selectively enabled only for specific classes that are likely to be extended in Java and used in C++.
</p>

<p>
Although directors make it natural to mix native C++ objects with Java objects (as director objects),
one should be aware of the obvious fact that method calls to Java objects from C++ will be much slower than calls to C++ objects.
Additionally, compared to classes that do not use directors, the call routing in the director methods adds a small overhead.
This situation can be optimized by selectively enabling director methods (using the %feature directive) for only those methods that are likely to be extended in Java.
</p>


<H3><a name="Java_directors_example"></a>25.5.4 Simple directors example</H3>


<p>
Consider the following SWIG interface file:
</p>

<div class="code">
<pre>
%module(directors="1") example;

%feature("director") DirectorBase;

class DirectorBase {
public:
  virtual ~DirectorBase() {}
  virtual void upcall_method() {}
};

void callup(DirectorBase *director) {
  director-&gt;upcall_method();
}
</pre>
</div>

<p>
The following <code>DirectorDerived</code> Java class is derived from the Java proxy class <code>DirectorBase</code> and overrides <code>upcall_method()</code>.
When C++ code invokes <code>upcall_method()</code>, the SWIG-generated C++ code redirects the call via JNI to the Java <code>DirectorDerived</code> subclass.
Naturally, the SWIG generated C++ code and the generated Java intermediary class marshal and convert arguments between C++ and Java when needed.
</p>

<div class="code">
<pre>
public class DirectorDerived extends DirectorBase {
  public DirectorDerived() {
  }

  public void upcall_method() {
    System.out.println("DirectorDerived::upcall_method() invoked.");
  }
}
</pre>
</div>

<p>
Running the following Java code
</p>

<div class="code">
<pre>
DirectorDerived director = new DirectorDerived();
example.callup(director);
</pre>
</div>

<p>
will result in the following being output:
</p>

<div class="code">
<pre>
DirectorDerived::upcall_method() invoked.
</pre>
</div>

<H3><a name="Java_directors_threading"></a>25.5.5 Director threading issues</H3>


<p>
Depending on your operating system and version of Java and how you are using threads, you might find the JVM hangs on exit.
There are a couple of solutions to try out. The preferred solution requires jdk-1.4 and later and uses <tt>AttachCurrentThreadAsDaemon</tt> instead of <tt>AttachCurrentThread</tt> whenever a call into the JVM is required. This can be enabled by defining the SWIG_JAVA_ATTACH_CURRENT_THREAD_AS_DAEMON macro when compiling the C++ wrapper code. For older JVMs define SWIG_JAVA_NO_DETACH_CURRENT_THREAD instead, to avoid the <tt>DetachCurrentThread</tt> call but this will result in a memory leak instead. For further details inspect the source code in the java/director.swg library file.
</p>

<p>
Macros can be defined on the commandline when compiling your C++ code, or alternatively added to the C++ wrapper file as shown below:
</p>

<div class="code">
<pre>
%insert("runtime") %{
#define SWIG_JAVA_NO_DETACH_CURRENT_THREAD
%}
</pre>
</div>

<H3><a name="Java_directors_performance"></a>25.5.6 Director performance tuning</H3>


<p>
When a new instance of a director (or subclass) is created in Java, the C++ side of the director performs a runtime check per director method to determine if that particular method is overridden in Java or if it should invoke the C++ base implementation directly.  Although this makes initialization slightly more expensive, it is generally a good overall tradeoff.
</p>

<p>
However, if all director methods are expected to usually be overridden by Java subclasses, then initialization can be made faster by avoiding these checks via the <tt>assumeoverride</tt> attribute.  For example:
</p>

<div class="code">
<pre>
%feature("director", assumeoverride=1) Foo;
</pre>
</div>

<p>
The disadvantage is that invocation of director methods from C++ when Java doesn't actually override the method will require an additional call up into Java and back to C++.  As such, this option is only useful when overrides are extremely common and instantiation is frequent enough that its performance is critical.
</p>

<H3><a name="Java_exceptions_from_directors"></a>25.5.7 Java exceptions from directors</H3>


<p>
With directors routing method calls to Java, and proxies routing them
to C++, the handling of exceptions is an important concern.
The default behavior from SWIG 3.0
onwards is to convert the thrown Java exception into a SWIG defined
<code>DirectorException</code> C++ exception.
SWIG 2.0 and earlier versions didn't provide any mechanism to handle the Java director method exceptions in C++.
</p>

<p>
Converting Java exceptions into C++ exceptions can be done in two different ways using
the <code>director:except</code> <a href="Customization.html#Customization_features">feature</a>.
In the simplest approach, a code block is attached to each director method to
handle the mapping of Java exceptions into C++ exceptions.
</p>

<div class="code">
<pre>
%feature("director:except") MyClass::method(int x) {
  jthrowable $error = jenv-&gt;ExceptionOccurred();
  if ($error) {
    jenv-&gt;ExceptionClear();
    if (Swig::ExceptionMatches(jenv, $error, "java/lang/IndexOutOfBoundsException"))
      throw std::out_of_range(Swig::JavaExceptionMessage(jenv, $error).message());
    if (Swig::ExceptionMatches(jenv, $error, "$packagepath/MyJavaException"))
      throw MyCppException(Swig::JavaExceptionMessage(jenv, $error).message());
    throw std::runtime_error("Unexpected exception thrown in MyClass::method");
  }
}

class MyClass {
  /** Throws either a std::out_of_range or MyCppException on error */
  void method(int x);
}
</pre>
</div>

<p>
This approach allows a flexible mapping of Java exceptions thrown by director methods into
C++ exceptions expected by a C++ caller.  There
need not be any C++ <em>exception specifications</em> on the C++ method. The
utility function <code>Swig::ExceptionMatches</code>
and class <code>Swig::JavaExceptionMessage</code> are provided to simplify
writing code for wrappers that use the <code>director:except</code> feature. The
function <code>Swig::ExceptionMatches</code> matches the type of the
<code>jthrowable</code> thrown against a <b>fully qualified</b> JNI style class
name, such as <code>"java/lang/IOError"</code>.  If the throwable class is the same
type, or derives from the given type, <code>Swig::ExceptionMatches</code> will return true.  Care must be taken to
provide the correct fully qualified name, since for wrapped exceptions the
generated proxy class will have additional package qualification, depending on
the '-package' argument and use of the <a href="#Java_namespaces">nspace
  feature</a>.  The special variable <code>$error</code> is expanded by SWIG into a unique variable name and
should be used for the 
assignment of the exception that occurred.  The special variable <code>$packagepath</code> is
replaced by the outer package provided for SWIG generation by the -package
option.  The utility class <code>Swig::JavaExceptionMessage</code> is a holder
providing access to the message from the thrown Java exception.
The <code>message()</code> method returns the exception message as a <code>const char *</code>,
which is only valid during the lifetime of the holder.  Any code using this message
needs to copy it, for example into a std::string or a newly constructed C++ exception.
</p>

<p>
Using the above approach to
write handlers for a large number of methods will require 
repetitive duplication of the <code>director:except</code> feature code.
To mitigate this, an alternative approach is provided via typemaps in a
fashion analagous to
the <a href="Typemaps.html#throws_typemap">"throws" typemap.</a>  The
"throws" typemap provides an approach to automatically map all the C++
exceptions listed in a method's defined exceptions (either from
a C++ <em>exception specification</em> or a <code>%catches</code>
feature) into Java exceptions.
The "directorthrows" typemap provides the inverse mapping and should contain
code to convert a suitably matching Java exception into a C++ exception.
The example below converts a Java <code>java.lang.IndexOutOfBoundsException</code> exception
to the typemap's type, that is <code>std::out_of_range</code>:

<div class="code">
<pre>
%typemap(directorthrows) std::out_of_range %{
  if (Swig::ExceptionMatches(jenv, $error, "java/lang/IndexOutOfBoundsException")) {
    throw std::out_of_range(Swig::JavaExceptionMessage(jenv, $error).message());
  }
%}
</pre>
</div>

<p>
The "directorthrows" typemap is then used in conjunction with the
<code>director:except</code> feature if the <code>$directorthrowshandlers</code> special variable
is used in the feature code. Consider the following, which also happens to be the default:
</p>

<div class="code">
<pre>
%feature("director:except") %{
   jthrowable $error = jenv-&gt;ExceptionOccurred();
   if ($error) {
     jenv-&gt;ExceptionClear();
     $directorthrowshandlers
     throw Swig::DirectorException(jenv, $error);
   }
%}
</pre>
</div>

<p>The code generated using the <code>director:except</code> feature
replaces the <code>$directorthrowshandlers</code> special variable with the code in
the "directorthrows" typemaps, for each and every exception defined for the method. 
The possible exceptions can be defined either with a C++ exception
specification or <code>%catches</code> as described for the
<a href="Typemaps.html#throws_typemap">"throws" typemap</a>.
</p>

<p>
Consider the following director method:
</p>

<div class="code">
<pre>
  ...
  virtual void doSomething(int index) throw (std::out_of_range);
  ...
</pre>
</div>

<p>
When combined with the default <code>director:except</code> feature and the "directorthrows" typemap above,
the resulting code generated in the director method after calling up to Java will be:
</p>

<div class="code">
<pre>
jthrowable swigerror = jenv-&gt;ExceptionOccurred();
if (swigerror) {
  jenv-&gt;ExceptionClear();
  if (Swig::ExceptionMatches(jenv, swigerror, "java/lang/IndexOutOfBoundsException")) {
    throw std::out_of_range(Swig::JavaExceptionMessage(jenv, swigerror).message());
  }
  
  throw Swig::DirectorException(jenv, swigerror);
}
</pre>
</div>

<p><em>
Note: Beware of using exception specifications as the SWIG director methods
will be generated with the same exception specifications and if the
director method throws an exception that is not specified it is likely
to terminate your program. See the C++ standard for more details.
Using the %catches feature instead to define the handled exceptions does not suffer
this potential fate.
</em></p>

<p>Because the default code generation maps any unhandled Java exceptions to
<code>Swig::DirectorException</code>, any director methods that have exception
specifications may cause program termination.  To simply ignore
unexpected exceptions, the default handling can be changed with:
</p>

<div class="code">
<pre>
%feature("director:except") %{
   jthrowable $error = jenv-&gt;ExceptionOccurred();
   if ($error) {
     jenv-&gt;ExceptionClear();
     $directorthrowshandlers
     return $null; // exception is ignored
   }
%}
</pre>
</div>

<p>Alternatively an exception compatible with the existing director
method exception specifications can be thrown. Assuming that all
methods allow std::runtime_error to be thrown,
the <code>return&nbsp;$null;</code> could be changed to:
</p>

<div class="code">
<pre>
   throw std::runtime_error(Swig::JavaExceptionMessage(jenv, $error).message());
</pre>
</div>

<p>In more complex situations, a separate <code>director:except</code> feature
may need to be attached to specific methods.
</p>

<p>Below is a complete example demonstrating the use
of the "directorthrows" typemaps.  In this example, a
generic "directorthrows" typemap is appropriate for all three exceptions - all
take single string constructors.  If the exceptions had different constructors,
it would be neccessary to have separate typemaps for each exception type.


<!-- All the DEFINE_ and DECLARE_EXCEPTIONS CAN BE OMITTED to make
  this more succinct.  They are included to make this a complete
  example interface that could be generated and built.  -->
<div class="code">
<pre>
%module(directors="1") example

%{
  #include &lt;string&gt;
  #include &lt;stdexcept&gt;
%}

// Define exceptions in header section using std::runtime_error
%define DEFINE_EXCEPTION(NAME)
%{
  namespace MyNS {
    struct NAME : public std::runtime_error { NAME(const std::string &amp;what) : runtime_error(what) {} };
  }
%}
%enddef

// Expose C++ exceptions as Java Exceptions by changing the Java base class and providing a getMessage()
%define DECLARE_EXCEPTION(NAME)
%typemap(javabase) MyNS::NAME "java.lang.Exception";
%rename(getMessage) MyNS::NAME::what;
namespace MyNS {
  struct NAME {
    NAME(const std::string&amp; what);
    const char * what();
  };
}
%enddef

DEFINE_EXCEPTION(ExceptionA)
DEFINE_EXCEPTION(ExceptionB)
DEFINE_EXCEPTION(Unexpected)

// Mark three methods to map director thrown exceptions.
%feature("director:except") MyClass::meth1(int);
%feature("director:except") MyClass::meth2;
%feature("director:except") meth3;

%typemap(directorthrows) MyNS::ExceptionA, MyNS::ExceptionB, MyNS::Unexpected %{
  if (Swig::ExceptionMatches(jenv, $error, "$packagepath/$javaclassname"))
    throw $1_type(Swig::JavaExceptionMessage(jenv, $error).message());
%}

DECLARE_EXCEPTION(ExceptionA)
DECLARE_EXCEPTION(ExceptionB)
DECLARE_EXCEPTION(Unexpected)

%catches(MyNS::ExceptionA, MyNS::ExceptionB, MyNS::Unexpected) MyClass::meth2();

%inline {
  class MyClass {
  public:
    virtual void meth1(int x) throw(MyNS::ExceptionA, MyNS::ExceptionB) = 0;
    virtual void meth2() = 0;   /* throws MyNS::ExceptionA, MyNS::ExceptionB, MyNS::Unexpected */
    virtual void meth3(float x) throw(MyNS::Unexpected) = 0;
    virtual ~MyClass() {}
  };
}
</pre>
</div>

<p>
In this case the three different "directorthrows" typemaps will be used
to generate the three different exception handlers for
<code>meth1</code>, <code>meth2</code> and <code>meth3</code>.  The generated
handlers will have "if" blocks for each exception type specified, in
the exception specification or <code>%catches</code> feature. 
</p>

<p>Note that the "directorthrows" typemaps are important
only if it is important for the the exceptions passed through the C++
layer to be mapped to distinct C++ exceptions.  If director methods
are being called by C++ code that is itself wrapped in a
SWIG generated Java wrapper and access is always through this wrapper,
the default <code>Swig::DirectorException</code> class provides enough information
to reconstruct the original exception.  In this case removing the
<code>$directorthrowshandlers</code> special variable from the
default <code>director:except</code> feature and simply always
throwing a <code>Swig::DirectorException</code> will achieve the desired result.
Along with this a generic exception feature is added to convert any
caught <code>Swig::DirectorException</code>s back into the underlying
Java exceptions via the <code>Swig::DirectorException::raiseJavaException</code> method,
as demonstrated with <code>%javaexception</code> below:
</p>

<div class="code">
<pre>
%javaexception("Exception") MyClass::myMethod %{
  try {
    $action
  } catch (Swig::DirectorException &amp;e) {
    // raise/throw the Java exception that originally caused the DirectorException
    e.raiseJavaException(jenv);
    return $null;
  }
%}
</pre>
</div>

<p>
See the <a href="#Java_exception_handling">Exception handling with %exception and %javaexception</a>
section for more on converting C++ exceptions to Java exceptions.
</p>

<H2><a name="Java_allprotected"></a>25.6 Accessing protected members</H2>


<p>
When using directors, the protected virtual methods are also wrapped. 
These methods are wrapped with a protected Java proxy method, so the only way that Java code can access these is from within a Java class derived from the director class.
</p>

<p>
Members which are protected and non-virtual can also be accessed when using the 'allprotected' mode.
The allprotected mode requires directors and is turned on by setting the <tt>allprotected</tt> option in addition to the <tt>directors</tt> option in the %module directive, like this:
</p>

<div class="code">
<pre>
%module(directors="1", allprotected="1") modulename
</pre>
</div>

<p>
Protected member variables and methods (both static and non-static) will then be wrapped with protected access in the Java proxy class.
</p>

<p>
<b>Note:</b> Neither the directors option nor the allprotected mode support types defined with protected scope.
This includes any enums or typedefs declared in the protected section of the C++ class.
</p>

<p>
The following simple example is a class with numerous protected members, including the constructor and destructor:
</p>

<div class="code">
<pre>
%module(directors="1", allprotected="1") example

%feature("director") ProtectedBase;

// Ignore use of unsupported types (those defined in the protected section)
%ignore ProtectedBase::typedefs;

%inline %{

class ProtectedBase {
protected:
  ProtectedBase() {}
  virtual ~ProtectedBase() {}
  virtual void virtualMethod() const {}
  void nonStaticMethod(double d) const {}
  static void staticMethod(int i) {}
  int instanceMemberVariable;
  static int staticMemberVariable;

  // unsupported: types defined with protected access and the methods/variables which use them
  typedef int IntegerType;
  IntegerType typedefs(IntegerType it) { return it; }
};
int ProtectedBase::staticMemberVariable = 10;

%}

</pre>
</div>

<p>
Note that the <tt>IntegerType</tt> has protected scope and the members which use this type must be ignored as they cannot be wrapped.
</p>

<p>
The proxy methods are protected, so the only way the protected members can be accessed is within a class that derives from the director class, such as the following:
</p>

<div class="code">
<pre>
class MyProtectedBase extends ProtectedBase
{
  public MyProtectedBase() {
  }

  public void accessProtected() {
    virtualMethod();
    nonStaticMethod(1.2);
    staticMethod(99);

    setInstanceMemberVariable(5);
    int i = getInstanceMemberVariable();

    setStaticMemberVariable(10);
    i = getStaticMemberVariable();
  }
}
</pre>
</div>


<H2><a name="Java_common_customization"></a>25.7 Common customization features</H2>


<p>
An earlier section presented the absolute basics of C/C++ wrapping. If you do nothing
but feed SWIG a header file, you will get an interface that mimics the behavior
described.  However, sometimes this isn't enough to produce a nice module.  Certain
types of functionality might be missing or the interface to certain functions might
be awkward.  This section describes some common SWIG features that are used
to improve the interface to existing C/C++ code.
</p>

<H3><a name="Java_helper_functions"></a>25.7.1 C/C++ helper functions</H3>


<p>
Sometimes when you create a module, it is missing certain bits of functionality. For
example, if you had a function like this
</p>

<div class="code">
<pre>
typedef struct Image {...};
void set_transform(Image *im, double m[4][4]);
</pre>
</div>

<p>
it would be accessible from Java, but there may be no easy way to call it.
The problem here is that a type wrapper class is generated for the two dimensional array parameter so
there is no easy way to construct and manipulate a suitable
<tt>double [4][4]</tt> value.   To fix this, you can write some extra C helper
functions.  Just use the <tt>%inline</tt> directive. For example:
</p>

<div class="code">
<pre>
%inline %{
/* Note: double[4][4] is equivalent to a pointer to an array double (*)[4] */
double (*new_mat44())[4] {
   return (double (*)[4]) malloc(16*sizeof(double));
}
void free_mat44(double (*x)[4]) {
   free(x);
}
void mat44_set(double x[4][4], int i, int j, double v) {
   x[i][j] = v;
}
double mat44_get(double x[4][4], int i, int j) {
   return x[i][j];
}
%}
</pre>
</div>

<p>
From Java, you could then write code like this:
</p>

<div class="code">
<pre>
Image im = new Image();
SWIGTYPE_p_a_4__double a = example.new_mat44();
example.mat44_set(a,0,0,1.0);
example.mat44_set(a,1,1,1.0);
example.mat44_set(a,2,2,1.0);
...
example.set_transform(im,a);
example.free_mat44(a);
</pre>
</div>

<p>
Admittedly, this is not the most elegant looking approach.  However, it works and it wasn't too
hard to implement.  It is possible to improve on this using Java code, typemaps, and other
customization features as covered in later sections, but sometimes helper functions are a quick and easy solution to difficult cases.  
</p>

<H3><a name="Java_class_extension"></a>25.7.2 Class extension with %extend</H3>


<p>
One of the more interesting features of SWIG is that it can extend
structures and classes with new methods or constructors.
Here is a simple example:
</p>

<div class="code">
<pre>
%module example
%{
#include "someheader.h"
%}

struct Vector {
   double x,y,z;
};

%extend Vector {
   char *toString() {
       static char tmp[1024];
       sprintf(tmp,"Vector(%g,%g,%g)", $self-&gt;x,$self-&gt;y,$self-&gt;z);
       return tmp;
   }
   Vector(double x, double y, double z) {
       Vector *v = (Vector *) malloc(sizeof(Vector));
       v-&gt;x = x;
       v-&gt;y = y;
       v-&gt;z = z;
       return v;
   }
};
</pre>
</div>

<p>
Now, in Java
</p>

<div class="code">
<pre>
Vector v = new Vector(2,3,4);
System.out.println(v);
</pre>
</div>

<p>
will display
</p>

<div class="code">
<pre>
Vector(2,3,4)
</pre>
</div>

<p>
<tt>%extend</tt> works with both C and C++ code.  It does not modify the underlying object
in any way---the extensions only show up in the Java interface.
</p>

<H3><a name="Java_exception_handling"></a>25.7.3 Exception handling with %exception and %javaexception</H3>


<p>
If a C or C++ function throws an error, you may want to convert that error into a Java
exception. To do this, you can use the <tt>%exception</tt> directive.  The <tt>%exception</tt> directive
simply lets you rewrite part of the generated wrapper code to include an error check.
It is detailed in full in the <a href="Customization.html#Customization_exception">Exception handling with %exception</a> section.
</p>

<p>
In C, a function often indicates an error by returning a status code (a negative number
or a NULL pointer perhaps).  Here is a simple example of how you might handle that:
</p>

<div class="code">
<pre>
%exception malloc {
  $action
  if (!result) {
    jclass clazz = (*jenv)-&gt;FindClass(jenv, "java/lang/OutOfMemoryError");
    (*jenv)-&gt;ThrowNew(jenv, clazz, "Not enough memory");
    return $null;
  }
}
void *malloc(size_t nbytes);
</pre>
</div>

<p>
In Java,
</p>

<div class="code">
<pre>
SWIGTYPE_p_void a = example.malloc(2000000000);
</pre>
</div>

<p>
will produce a familiar looking Java exception:
</p>

<div class="code">
<pre>
Exception in thread "main" java.lang.OutOfMemoryError: Not enough memory
        at exampleJNI.malloc(Native Method)
        at example.malloc(example.java:16)
        at runme.main(runme.java:112)
</pre>
</div>

<p>
If a library provides some kind of general error handling framework, you can also use
that.  For example:
</p>

<div class="code">
<pre>
%exception malloc {
  $action
  if (err_occurred()) {
    jclass clazz = (*jenv)-&gt;FindClass(jenv, "java/lang/OutOfMemoryError");
    (*jenv)-&gt;ThrowNew(jenv, clazz, "Not enough memory");
    return $null;
  }
}
void *malloc(size_t nbytes);
</pre>
</div>

<p>
If no declaration name is given to <tt>%exception</tt>, it is applied to all wrapper functions.
The <tt>$action</tt> is a SWIG special variable and is replaced by the C/C++ function call being wrapped.
The <tt>return $null;</tt> handles all native method return types, namely those that have a void return and those that do not.
This is useful for typemaps that will be used in native method returning all return types. 
See the section on
<a href="#Java_special_variables">Java special variables</a> for further explanation.
</p>

<p>
C++ exceptions are also easy to handle.  
We can catch the C++ exception and rethrow it as a Java exception like this:</p>

<div class="code">
<pre>
%exception getitem {
  try {
     $action
  } catch (std::out_of_range &amp;e) {
    jclass clazz = jenv-&gt;FindClass("java/lang/Exception");
    jenv-&gt;ThrowNew(clazz, "Range error");
    return $null;
   }
}

class FooClass {
public:
     FooClass *getitem(int index);      // Might throw std::out_of_range exception
     ...
};
</pre>
</div>

<p>
In the example above, <tt>java.lang.Exception</tt> is a checked exception class and so ought to be declared in the throws clause of <tt>getitem</tt>.
Classes can be specified for adding to the throws clause using <tt>%javaexception(classes)</tt> instead of <tt>%exception</tt>,
where <tt>classes</tt> is a string containing one or more comma separated Java classes.
The <tt>%clearjavaexception</tt> feature is the equivalent to <tt>%clearexception</tt> and clears previously declared exception handlers. 
The <tt>%nojavaexception</tt> feature is the equivalent to <tt>%noexception</tt> and disables the exception handler.
See <a href="Customization.html#Customization_clearing_features">Clearing features</a> for the difference on disabling and clearing features.
</p>

<div class="code">
<pre>
%javaexception("java.lang.Exception") getitem {
  try {
     $action
  } catch (std::out_of_range &amp;e) {
    jclass clazz = jenv-&gt;FindClass("java/lang/Exception");
    jenv-&gt;ThrowNew(clazz, "Range error");
    return $null;
   }
}

class FooClass {
public:
     FooClass *getitem(int index);      // Might throw std::out_of_range exception
     ...
};
</pre>
</div>

<p>
The generated proxy method now generates a throws clause containing <tt>java.lang.Exception</tt>:
</p>

<div class="code">
<pre>
public class FooClass {
  ...
  public FooClass getitem(int index) throws java.lang.Exception { ... }
  ...
}
</pre>
</div>


<p>
The examples above first use the C JNI calling syntax then the C++ JNI calling syntax. The C++ calling syntax will not compile as C and also vice versa.
It is however possible to write JNI calls which will compile under both C and C++ and is covered in the <a href="#Java_typemaps_for_c_and_cpp">Typemaps for both C and C++ compilation</a> section. 
</p>

<p>
The language-independent <tt>exception.i</tt> library file can also be used
to raise exceptions.  See the <a href="Library.html#Library">SWIG Library</a> chapter.
The typemap example <a href="#Java_exception_typemap">Handling C++ exception specifications as Java exceptions</a> provides further exception handling capabilities.
</p>

<H3><a name="Java_method_access"></a>25.7.4 Method access with %javamethodmodifiers</H3>


<p>
A Java feature called <tt>%javamethodmodifiers</tt> can be used to change the method modifiers from the default <tt>public</tt>. It applies to both module class methods and proxy class methods. For example:
</p>

<div class="code">
<pre>
%javamethodmodifiers protect_me() "protected";
void protect_me();
</pre>
</div>

<p>
Will produce the method in the module class with protected access.
</p>

<div class="code">
<pre>
protected static void protect_me() {
  exampleJNI.protect_me();
}
</pre>
</div>

<H2><a name="Java_tips_techniques"></a>25.8 Tips and techniques</H2>


<p>
Although SWIG is largely automatic, there are certain types of wrapping problems that
require additional user input.    Examples include dealing with output parameters,
strings and arrays.   This chapter discusses the common techniques for
solving these problems.
</p>

<H3><a name="Java_input_output_parameters"></a>25.8.1 Input and output parameters using primitive pointers and references</H3>


<p>
A common problem in some C programs is handling parameters passed as simple pointers or references.  For
example:
</p>

<div class="code">
<pre>
void add(int x, int y, int *result) {
   *result = x + y;
}
</pre>
</div>

<p>
or perhaps
</p>

<div class="code">
<pre>
int sub(int *x, int *y) {
   return *x-*y;
}
</pre>
</div>

<p>
The <tt>typemaps.i</tt> library file will help in these situations.  For example:
</p>

<div class="code">
<pre>
%module example
%include "typemaps.i"

void add(int, int, int *OUTPUT);
int  sub(int *INPUT, int *INPUT);
</pre>
</div>

<p>
In Java, this allows you to pass simple values.  For example:
</p>

<div class="code">
<pre>
int result = example.sub(7,4);
System.out.println("7 - 4 = " + result);
int[] sum = {0};
example.add(3,4,sum);
System.out.println("3 + 4 = " + sum[0]);
</pre>
</div>

<p>
Which will display:
</p>

<div class="code"> <pre>
7 - 4 = 3
3 + 4 = 7
</pre></div>

<p>
Notice how the <tt>INPUT</tt> parameters allow integer values to be passed instead of pointers
and how the <tt>OUTPUT</tt> parameter will return the result in the first element of the integer array.
</p>

<p>
If you don't want to use the names <tt>INPUT</tt> or <tt>OUTPUT</tt>, use the <tt>%apply</tt>
directive.  For example:
</p>

<div class="code">
<pre>
%module example
%include "typemaps.i"

%apply int *OUTPUT { int *result };
%apply int *INPUT  { int *x, int *y};

void add(int x, int y, int *result);
int  sub(int *x, int *y);
</pre>
</div>

<p>
If a function mutates one of its parameters like this,
</p>

<div class="code">
<pre>
void negate(int *x) {
   *x = -(*x);
}
</pre>
</div>

<p>
you can use <tt>INOUT</tt> like this:
</p>

<div class="code">
<pre>
%include "typemaps.i"
...
void negate(int *INOUT);
</pre>
</div>

<p>
In Java, the input parameter is the first element in a 1 element array and is replaced by the output of the function. For example:
</p>

<div class="code">
<pre>
int[] neg = {3};
example.negate(neg);
System.out.println("Negative of 3 = " + neg[0]);
</pre>
</div>

<p>
And no prizes for guessing the output:
</p>

<div class="code"><pre>
Negative of 3 = -3
</pre></div>

<p>
These typemaps can also be applied to C++ references. 
The above examples would work the same if they had been defined using references instead of pointers.
For example, the Java code to use the <tt>negate</tt> function would be the same if it were defined either as it is above: 
</p>

<div class="code">
<pre>
void negate(int *INOUT);
</pre>
</div>

<p>
or using a reference:
</p>

<div class="code">
<pre>
void negate(int &amp;INOUT);
</pre>
</div>

<p>
Note: Since most Java primitive types are immutable and are passed by value, it is not possible to
perform in-place modification of a type passed as a parameter.
</p>

<p>
Be aware that the primary purpose of the <tt>typemaps.i</tt> file is to support primitive datatypes.
Writing a function like this
</p>

<div class="code">
<pre>
void foo(Bar *OUTPUT);
</pre>
</div>

<p>
will not have the intended effect since <tt>typemaps.i</tt> does not define an OUTPUT rule for <tt>Bar</tt>.
</p>

<H3><a name="Java_simple_pointers"></a>25.8.2 Simple pointers</H3>


<p>
If you must work with simple pointers such as <tt>int *</tt> or <tt>double *</tt> another approach to using 
<tt>typemaps.i</tt> is to use the <tt>cpointer.i</tt> pointer library file.    For example:
</p>

<div class="code">
<pre>
%module example
%include "cpointer.i"

%inline %{
extern void add(int x, int y, int *result);
%}

%pointer_functions(int, intp);
</pre>
</div>

<p>
The <tt>%pointer_functions(type,name)</tt> macro generates five helper functions that can be used to create,
destroy, copy, assign, and dereference a pointer.  In this case, the functions are as follows:
</p>

<div class="code">
<pre>
int  *new_intp();
int  *copy_intp(int *x);
void  delete_intp(int *x);
void  intp_assign(int *x, int value);
int   intp_value(int *x);
</pre>
</div>

<p>
In Java, you would use the functions like this:
</p>

<div class="code">
<pre>
SWIGTYPE_p_int intPtr = example.new_intp();
example.add(3,4,intPtr);
int result = example.intp_value(intPtr);
System.out.println("3 + 4 = " + result);
</pre>
</div>

<p>
If you replace <tt>%pointer_functions(int,intp)</tt> by <tt>%pointer_class(int,intp)</tt>, the interface is more class-like.
</p>

<div class="code">
<pre>
intp intPtr = new intp();
example.add(3,4,intPtr.cast());
int result = intPtr.value();
System.out.println("3 + 4 = " + result);
</pre>
</div>

<p>
See the <a href="Library.html#Library">SWIG Library</a> chapter for further details.
</p>

<H3><a name="Java_c_arrays"></a>25.8.3 Wrapping C arrays with Java arrays</H3>


<p>
SWIG can wrap arrays in a more natural Java manner than the default by using the <tt>arrays_java.i</tt> library file. 
Let's consider an example:
</p>

<div class="code">
<pre>
%include "arrays_java.i";
int array[4];
void populate(int x[]) {
    int i;
    for (i=0; i&lt;4; i++)
        x[i] = 100 + i;
}
</pre>
</div>

<p>
These one dimensional arrays can then be used as if they were Java arrays:
</p>

<div class="code">
<pre>
int[] array = new int[4];
example.populate(array);

System.out.print("array: ");
for (int i=0; i&lt;array.length; i++)
    System.out.print(array[i] + " ");

example.setArray(array);

int[] global_array = example.getArray();

System.out.print("\nglobal_array: ");
for (int i=0; i&lt;array.length; i++)
    System.out.print(global_array[i] + " ");
</pre>
</div>

<p>
Java arrays are always passed by reference, so any changes a function makes to the array will be seen by the calling function. 
Here is the output after running this code:
</p>

<div class="code">
<pre>
array: 100 101 102 103
global_array: 100 101 102 103
</pre>
</div>

<p>
Note that for assigning array variables the length of the C variable is used, so it is possible to use a Java array that is bigger than the C code will cope with.
Only the number of elements in the C array will be used.
However, if the Java array is not large enough then you are likely to get a segmentation fault or access violation, just like you would in C.
When arrays are used in functions like <tt>populate</tt>, the size of the C array passed to the function is determined by the size of the Java array.
</p>

<p>
Please be aware that the typemaps in this library are not efficient as all the elements are copied from the Java array to a C array whenever the array is passed to and from JNI code.
There is an alternative approach using the SWIG array library and this is covered in the next section.
</p>

<H3><a name="Java_unbounded_c_arrays"></a>25.8.4 Unbounded C Arrays</H3>


<p>
Sometimes a C function expects an array to be passed as a pointer.  For example,
</p>

<div class="code">
<pre>
int sumitems(int *first, int nitems) {
    int i, sum = 0;
    for (i = 0; i &lt; nitems; i++) {
        sum += first[i];
    }
    return sum;
}
</pre>
</div>

<p>
One of the ways to wrap this is to apply the Java array typemaps that come in the <tt>arrays_java.i</tt> library file:
</p>

<div class="code">
<pre>
%include "arrays_java.i"
%apply int[] {int *};
</pre>
</div>

<p>
The <tt>ANY</tt> size will ensure the typemap is applied to arrays of all sizes.
You could narrow the typemap matching rules by specifying a particular array size.
Now you can use a pure Java array and pass it to the C code:
</p>

<div class="code">
<pre>
int[] array = new int[10000000];          // Array of 10-million integers
for (int i=0; i&lt;array.length; i++) {      // Set some values
  array[i] = i;
}
int sum = example.sumitems(array,10000);
System.out.println("Sum = " + sum);
</pre>
</div>

<p>
and the sum would be displayed:
</p>

<div class="code">
<pre>
Sum = 49995000
</pre>
</div>

<p>
This approach is probably the most natural way to use arrays.
However, it suffers from performance problems when using large arrays as a lot of copying
of the elements occurs in transferring the array from the Java world to the C++ world.
An alternative approach to using Java arrays for C arrays is to use an alternative SWIG library file <tt>carrays.i</tt>.
This approach can be more efficient for large arrays as the array is accessed one element at a time.
For example:
</p>

<div class="code">
<pre>
%include "carrays.i"
%array_functions(int, intArray);
</pre>
</div>

<p>
The <tt>%array_functions(type,name)</tt> macro generates four helper functions that can be used to create and
destroy arrays and operate on elements.  In this case, the functions are as follows:
</p>

<div class="code">
<pre>
int *new_intArray(int nelements);
void delete_intArray(int *x);
int intArray_getitem(int *x, int index);
void intArray_setitem(int *x, int index, int value);
</pre>
</div>

<p>
In Java, you would use the functions like this:
</p>

<div class="code">
<pre>
SWIGTYPE_p_int array = example.new_intArray(10000000);  // Array of 10-million integers
for (int i=0; i&lt;10000; i++) {                           // Set some values
    example.intArray_setitem(array,i,i);
}
int sum = example.sumitems(array,10000);
System.out.println("Sum = " + sum);
</pre>
</div>

<p>
If you replace <tt>%array_functions(int,intp)</tt> by <tt>%array_class(int,intp)</tt>, the interface is more class-like
and a couple more helper functions are available for casting between the array and the type wrapper class.
</p>

<div class="code">
<pre>
%include "carrays.i"
%array_class(int, intArray);
</pre>
</div>

<p>
The <tt>%array_class(type, name)</tt> macro creates wrappers for an unbounded array object that
can be passed around as a simple pointer like <tt>int *</tt> or <tt>double *</tt>.
For instance, you will be able to do this in Java:
</p>

<div class="code">
<pre>
intArray array = new intArray(10000000);  // Array of 10-million integers
for (int i=0; i&lt;10000; i++) {             // Set some values
    array.setitem(i,i);
}
int sum = example.sumitems(array.cast(),10000);
System.out.println("Sum = " + sum);
</pre>
</div>

<p>
The array "object" created by <tt>%array_class()</tt> does not
encapsulate pointers inside a special array object.  In fact, there is
no bounds checking or safety of any kind (just like in C).  Because of
this, the arrays created by this library are extremely low-level
indeed.  You can't iterate over them nor can you even query their
length.  In fact, any valid memory address can be accessed if you want
(negative indices, indices beyond the end of the array, etc.).
Needless to say, this approach is not going to suit all applications.
On the other hand, this low-level approach is extremely efficient and
well suited for applications in which you need to create buffers,
package binary data, etc.
</p>

<H3><a name="Java_binary_char"></a>25.8.5 Binary data vs Strings</H3>


<p>
By default SWIG handles <tt>char *</tt> as a string but there is a handy multi-argument typemap available as mentioned in <a href="Library.html#Library_nn10">Passing binary data</a>.
The following simple example demonstrates using a byte array instead of passing the default string type and length to the wrapped function.
</p>


<div class="code">
<pre>
%apply (char *STRING, size_t LENGTH) { (const char data[], size_t len) }
%inline %{
void binaryChar1(const char data[], size_t len) {
  printf("len: %d data: ", len);
  for (size_t i=0; i&lt;len; ++i)
    printf("%x ", data[i]);
  printf("\n");
}
%}
</pre>
</div>

<p>
Calling from Java requires just the byte array to be passed in as the multi-argument typemap being applied reduces the number of arguments in the target language to one, from the original two:
</p>

<div class="code">
<pre>
byte[] data = "hi\0jk".getBytes();
example.binaryChar1(data);     
</pre>
</div>

<p>
resulting in the output
</p>

<div class="code"><pre>
$ java runme
len: 5 data: 68 69 0 6a 6b
</pre></div>


<H3><a name="Java_heap_allocations"></a>25.8.6 Overriding new and delete to allocate from Java heap</H3>


<p>
Unlike some languages supported by SWIG, Java has a true garbage collection
subsystem.  Other languages will free SWIG wrapped objects when their reference
count reaches zero.  Java only schedules these objects for finalization, which
may not occur for some time.  Because SWIG objects are allocated on the C
heap, Java users may find the JVM memory use 
quickly exceeds the assigned limits, as memory fills with unfinalized proxy
objects.  Forcing garbage collection is clearly an undesirable solution.
</p>

<p>
An elegant fix for C++ users is to override new and delete using the following
code (here shown included in a SWIG interface file)
</p>

<div class="code">
<pre>
/* File: java_heap.i */
%module test
%{
#include &lt;stdexcept&gt;
#include "jni.h"

/**
 *  A stash area embedded in each allocation to hold java handles
 */
struct Jalloc {
  jbyteArray jba;
  jobject ref;
};

static JavaVM *cached_jvm = 0;

JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *jvm, void *reserved) {
  cached_jvm = jvm;
  return JNI_VERSION_1_2;
}

static JNIEnv * JNU_GetEnv() {
  JNIEnv *env;
  jint rc = cached_jvm-&gt;GetEnv((void **)&amp;env, JNI_VERSION_1_2);
  if (rc == JNI_EDETACHED)
    throw std::runtime_error("current thread not attached");
  if (rc == JNI_EVERSION)
    throw std::runtime_error("jni version not supported");
  return env;
}

void * operator new(size_t t) {
  if (cached_jvm != 0) {
    JNIEnv *env = JNU_GetEnv();
    jbyteArray jba = env-&gt;NewByteArray((int) t + sizeof(Jalloc));
    if (env-&gt;ExceptionOccurred())
      throw bad_alloc();
    void *jbuffer = static_cast&lt;void *&gt;(env-&gt;GetByteArrayElements(jba, 0));
    if (env-&gt;ExceptionOccurred())
      throw bad_alloc();
    Jalloc *pJalloc = static_cast&lt;Jalloc *&gt;(jbuffer);
    pJalloc-&gt;jba = jba;
    /* Assign a global reference so byte array will persist until delete'ed */
    pJalloc-&gt;ref = env-&gt;NewGlobalRef(jba);
    if (env-&gt;ExceptionOccurred())
      throw bad_alloc();
    return static_cast&lt;void *&gt;(static_cast&lt;char *&gt;(jbuffer) + sizeof(Jalloc));
  }
  else { /* JNI_OnLoad not called, use malloc and mark as special */
    Jalloc *pJalloc = static_cast&lt;Jalloc *&gt;(malloc((int) t + sizeof(Jalloc)));
    if (!pJalloc)
      throw bad_alloc();
    pJalloc-&gt;ref = 0;
    return static_cast&lt;void *&gt;(
        static_cast&lt;char *&gt;(static_cast&lt;void *&gt;(pJalloc)) + sizeof(Jalloc));
  }
}

void operator delete(void *v) {
  if (v != 0) {
    void *buffer = static_cast&lt;void *&gt;( static_cast&lt;char *&gt;(v) - sizeof(Jalloc));
    Jalloc *pJalloc = static_cast&lt;Jalloc *&gt;(buffer);
    if (pJalloc-&gt;ref) {
      JNIEnv *env = JNU_GetEnv();
      env-&gt;DeleteGlobalRef(pJalloc-&gt;ref);
      env-&gt;ReleaseByteArrayElements(pJalloc-&gt;jba, static_cast&lt;jbyte *&gt;(buffer), 0);
    }
    else {
      free(buffer);
    }
  }
}
%}
...
</pre>
</div>

<p>
This code caches the Java environment during initialization,
and when new is called, a Java ByteArray is allocated to provide the
SWIG objects with space in the Java heap.  This has the combined
effect of re-asserting the Java virtual machine's limit on memory allocation,
and puts additional pressure on the garbage collection system to run more
frequently.
This code is made slightly more complicated because allowances must be made
if new is called before the JNI_OnLoad is executed.  This can happen during
static class initialization, for example.  
</p>

<p>
Unfortunately, because most Java implementations call malloc and free, this
solution will not work for C wrapped structures.  However, you are free to
make functions that allocate and free memory from the Java heap using this
model and use these functions in place of malloc and free in your own
code.
</p>

<H2><a name="Java_typemaps"></a>25.9 Java typemaps</H2>


<p>
This section describes how you can modify SWIG's default wrapping behavior
for various C/C++ datatypes using the <tt>%typemap</tt> directive.   
You are advised to be familiar with the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter.
While not absolutely essential knowledge, this section assumes some familiarity with the Java Native Interface (JNI). 
JNI documentation can be consulted either online at <a href="http://java.sun.com">Sun's Java web site</a> or from a good JNI book. 
The following two books are recommended:</p>

<ul>
<li> Title: 'Essential JNI: Java Native Interface.' Author: Rob Gordon. Publisher: Prentice Hall. ISBN: 0-13-679895-0.  </li>
<li> Title: 'The Java Native Interface: Programmer's Guide and Specification.' Author: Sheng Liang. Publisher: Addison-Wesley. ISBN: 0-201-32577-2.  Also available <a href="http://java.sun.com/docs/books/jni">online</a> at the Sun Developer Network.</li>
</ul>

<p>
Before proceeding, it should be stressed that typemaps are not a required 
part of using SWIG---the default wrapping behavior is enough in most cases.
Typemaps are only used if you want to change some aspect of the generated code.

<H3><a name="Java_default_primitive_type_mappings"></a>25.9.1 Default primitive type mappings</H3>


<p>
The following table lists the default type mapping from Java to C/C++.</p>

<table BORDER summary="Default primitive type mappings">
<tr>
<td><b>C/C++ type</b></td>
<td><b>Java type</b></td>
<td><b>JNI type</b></td>
</tr>

<tr>
<td>bool<br> const bool &amp; </td>
<td>boolean</td>
<td>jboolean</td>
</tr>

<tr>
<td>char<br>const char &amp;</td>
<td>char</td>
<td>jchar</td>
</tr>

<tr>
<td>signed char<br>const signed char &amp;</td>
<td>byte</td>
<td>jbyte</td>
</tr>

<tr>
<td>unsigned char<br>const unsigned char &amp;</td>
<td>short</td>
<td>jshort</td>
</tr>

<tr>
<td>short<br>const short &amp;</td>
<td>short</td>
<td>jshort</td>
</tr>

<tr>
<td>unsigned short<br> const unsigned short &amp;</td>
<td>int</td>
<td>jint</td>
</tr>

<tr>
<td>int<br> const int &amp;</td>
<td>int</td>
<td>jint</td>
</tr>

<tr>
<td>unsigned int<br> const unsigned int &amp;</td>
<td>long</td>
<td>jlong</td>
</tr>

<tr>
<td>long<br>const long &amp;</td>
<td>int</td>
<td>jint</td>
</tr>

<tr>
<td>unsigned long<br>const unsigned long &amp;</td>
<td>long</td>
<td>jlong</td>
</tr>

<tr>
<td>long long<br> const long long &amp;</td>
<td>long</td>
<td>jlong</td>
</tr>

<tr>
<td>unsigned long long<br>const unsigned long long &amp;</td>
<td>java.math.BigInteger</td>
<td>jobject</td>
</tr>

<tr>
<td>float<br>const float &amp;</td>
<td>float</td>
<td>jfloat</td>
</tr>

<tr>
<td>double<br> const double &amp;</td>
<td>double</td>
<td>jdouble</td>
</tr>

<tr>
<td>char *<br>char []</td>
<td>String</td>
<td>jstring</td>
</tr>

</table>

<p>
Note that SWIG wraps the C <tt>char</tt> type as a character. Pointers and arrays of this type are wrapped as strings. 
The <tt>signed char</tt> type can be used if you want to treat <tt>char</tt> as a signed number rather than a character.
Also note that all const references to primitive types are treated as if they are passed by value.
</p>

<p>
Given the following C function:
</p>

<div class="code"> <pre>
void func(unsigned short a, char *b, const long &amp;c, unsigned long long d);
</pre> </div>

<p>
The module class method would be:
</p>

<div class="code"> <pre>
public static void func(int a, String b, int c, java.math.BigInteger d) {...}
</pre> </div>

<p>
The intermediary JNI class would use the same types:
</p>

<div class="code"> <pre>
public final static native void func(int jarg1, String jarg2, int jarg3,
                                     java.math.BigInteger jarg4);
</pre> </div>

<p>
and the JNI function would look like this:
</p>

<div class="code"> <pre>
SWIGEXPORT void JNICALL Java_exampleJNI_func(JNIEnv *jenv, jclass jcls,
                jint jarg1, jstring jarg2, jint jarg3, jobject jarg4) {...}
</pre> </div>

<p>
The mappings for C <tt>int</tt> and C <tt>long</tt> are appropriate for 32 bit applications which are used in the 32 bit JVMs. 
There is no perfect mapping between Java and C as Java doesn't support all the unsigned C data types. 
However, the mappings allow the full range of values for each C type from Java. 
</p>


<H3><a name="Java_default_non_primitive_typemaps"></a>25.9.2 Default typemaps for non-primitive types</H3>


<p>
The previous section covered the primitive type mappings.
Non-primitive types such as classes and structs are mapped using pointers on the C/C++ side and storing the pointer into a Java <tt>long</tt> variable which is held by
the proxy class or type wrapper class. This applies whether the type is marshalled as a pointer, by reference or by value.
It also applies for any unknown/incomplete types which use type wrapper classes.
</p>

<p>
So in summary, the C/C++ pointer to non-primitive types is cast into the 64 bit Java <tt>long</tt> type and therefore the JNI type is a <tt>jlong</tt>.
The Java type is either the proxy class or type wrapper class.
</p>

<H3><a name="Java_jvm64"></a>25.9.3 Sixty four bit JVMs</H3>


<p>
If you are using a 64 bit JVM you may have to override the C long, but probably not C int default mappings. 
Mappings will be system dependent, for example long will need remapping on Unix LP64 systems (long, pointer 64 bits, int 32 bits), but not on 
Microsoft 64 bit Windows which will be using a P64 IL32 (pointer 64 bits and int, long 32 bits) model. 
This may be automated in a future version of SWIG. 
Note that the Java write once run anywhere philosophy holds true for all pure Java code when moving to a 64 bit JVM. 
Unfortunately it won't of course hold true for JNI code.
</p>


<H3><a name="Java_what_is_typemap"></a>25.9.4 What is a typemap?</H3>


<p>
A typemap is nothing more than a code generation rule that is attached to 
a specific C datatype.   For example, to convert integers from Java to C,
you might define a typemap like this:
</p>

<div class="code"><pre>
%module example

%typemap(in) int {
  $1 = $input;
  printf("Received an integer : %d\n",  $1);
}
%inline %{
extern int fact(int nonnegative);
%}
</pre></div>

<p>
Typemaps are always associated with some specific aspect of code generation.
In this case, the "in" method refers to the conversion of input arguments
to C/C++.  The datatype <tt>int</tt> is the datatype to which the typemap
will be applied.  The supplied C code is used to convert values.  In this
code a number of special variables prefaced by a <tt>$</tt> are used.  The
<tt>$1</tt> variable is a placeholder for a local variable of type <tt>int</tt>.
The <tt>$input</tt> variable contains the Java data, the JNI <tt>jint</tt> in this case.
</p>

<p>
When this example is compiled into a Java module, it can be used as follows:
</p>

<div class="code"><pre>
System.out.println(example.fact(6));
</pre></div>

<p>
and the output will be:
</p>

<div class="code"><pre>
Received an integer : 6
720
</pre></div>

<p>
In this example, the typemap is applied to all occurrences of the <tt>int</tt> datatype.
You can refine this by supplying an optional parameter name.  For example:
</p>

<div class="code"><pre>
%module example

%typemap(in) int nonnegative {
  $1 = $input;
  printf("Received an integer : %d\n",  $1);
}

%inline %{
extern int fact(int nonnegative);
%}
</pre></div>

<p>
In this case, the typemap code is only attached to arguments that exactly match <tt>int nonnegative</tt>.
</p>

<p>
The application of a typemap to specific datatypes and argument names involves
more than simple text-matching--typemaps are fully integrated into the
SWIG C++ type-system.   When you define a typemap for <tt>int</tt>, that typemap
applies to <tt>int</tt> and qualified variations such as <tt>const int</tt>.  In addition,
the typemap system follows <tt>typedef</tt> declarations.  For example:
</p>

<div class="code">
<pre>
%typemap(in) int nonnegative {
  $1 = $input;
  printf("Received an integer : %d\n",  $1);
}
%inline %{
typedef int Integer;
extern int fact(Integer nonnegative);    // Above typemap is applied
%}
</pre>
</div>

<p>
However, the matching of <tt>typedef</tt> only occurs in one direction.  If you
defined a typemap for <tt>Integer</tt>, it is not applied to arguments of
type <tt>int</tt>.
</p>

<p>
Typemaps can also be defined for groups of consecutive arguments.  For example:
</p>

<div class="code">
<pre>
%typemap(in) (char *str, int len) {
...
};

int count(char c, char *str, int len);
</pre>
</div>

<p>
When a multi-argument typemap is defined, the arguments are always handled as a single
Java parameter.  This allows the function to be used like this (notice how the length
parameter is omitted):
</p>

<div class="code">
<pre>
int c = example.count('e',"Hello World");
</pre>
</div>

<H3><a name="Java_typemaps_c_to_java_types"></a>25.9.5 Typemaps for mapping C/C++ types to Java types</H3>


<p>
The typemaps available to the Java module include the common typemaps listed in the main typemaps section. 
There are a number of additional typemaps which are necessary for using SWIG with Java.
The most important of these implement the mapping of C/C++ types to Java types:
</p>

<br>&nbsp;
<table BORDER summary="Typemap mappings for C/C++ types to Java types">
<tr>
<td><b>Typemap</b></td>

<td><b>Description</b></td>
</tr>

<tr>
<td>jni</td>
<td>JNI C types. These provide the default mapping of types from C/C++ to JNI for use in the JNI (C/C++) code.</td>
</tr>

<tr>
<td>jtype</td>
<td>Java intermediary types. These provide the default mapping of types from C/C++ to Java for use in the native functions in the intermediary JNI class. The type must be the equivalent Java type for the JNI C type specified in the "jni" typemap.</td>
</tr>

<tr>
<td>jstype</td>
<td>Java types. These provide the default mapping of types from C/C++ to Java for use in the Java module class, proxy classes and type wrapper classes.</td>
</tr>

<tr>
<td>javain</td>
<td>Conversion from jstype to jtype. 
    These are Java code typemaps which transform the type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap)
    to the type used in the Java intermediary JNI class (as specified in the "jtype" typemap).
    In other words the typemap provides the conversion to the native method call parameter types.</td>
</tr>

<tr>
<td>javaout</td>
<td>Conversion from jtype to jstype.
    These are Java code typemaps which transform the type used in the Java intermediary JNI class (as specified in the "jtype" typemap) to 
    the Java type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap).
    In other words the typemap provides the conversion from the native method call return type. </td>
</tr>

<tr>
<td>javadirectorin</td>
<td>Conversion from jtype to jstype for director methods.
    These are Java code typemaps which transform the type used in the Java intermediary JNI class (as specified in the "jtype" typemap) to 
    the Java type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap).
    This typemap provides the conversion for the parameters in the director methods when calling up from C++ to Java.
    See <a href="#Java_directors_typemaps">Director typemaps</a>.  </td>
</tr>

<tr>
<td>javadirectorout</td>
<td>Conversion from jstype to jtype for director methods.
    These are Java code typemaps which transform the type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap)
    to the type used in the Java intermediary JNI class (as specified in the "jtype" typemap).
    This typemap provides the conversion for the return type in the director methods when returning from the C++ to Java upcall.
    See <a href="#Java_directors_typemaps">Director typemaps</a>.  </td>
</tr>

<tr>
<td>directorin</td>
<td>Conversion from C++ type to jni type for director methods.
  These are C++ typemaps which convert the parameters used in the C++ director method to the appropriate JNI intermediary type.
  The conversion is done in JNI code prior to calling the Java function from the JNI code.
  See <a href="#Java_directors_typemaps">Director typemaps</a>. </td>
</tr>

<tr>
<td>directorout</td>
<td>Conversion from jni type to C++ type for director methods.
  These are C++ typemaps which convert the JNI return type used in the C++ director method to the appropriate C++ return type.
  The conversion is done in JNI code after calling the Java function from the JNI code.
  See <a href="#Java_directors_typemaps">Director typemaps</a>. </td>
</tr>

</table>

<p>
If you are writing your own typemaps to handle a particular type, you will normally have to write a collection of them. 
The default typemaps are in "<tt>java.swg</tt>" and so might be a good place for finding typemaps to base any new ones on.
</p>

<p>
The "jni", "jtype" and "jstype" typemaps are usually defined together to handle the Java to C/C++ type mapping.
An "in" typemap should be accompanied by a "javain" typemap and likewise an "out" typemap by a "javaout" typemap.
If an "in" typemap is written, a "freearg" and "argout" typemap may also need to be written
as some types have a default "freearg" and/or "argout" typemap which may need overriding. 
The "freearg" typemap sometimes releases memory allocated by the "in" typemap. 
The "argout" typemap sometimes sets values in function parameters which are passed by reference in Java. 
</p>

<p>
Note that the "in" typemap marshals the JNI type held in the "jni" typemap to the real C/C++ type and for the opposite direction,
the "out" typemap marshals the real C/C++ type to the JNI type held in the "jni" typemap.
For <a href="#Java_default_non_primitive_typemaps">non-primitive types</a> 
the "in" and "out" typemaps are responsible for casting between the C/C++ pointer and the 64 bit <tt>jlong</tt> type.
There is no portable way to cast a pointer into a 64 bit integer type and the approach taken by SWIG is mostly portable, but breaks C/C++ aliasing rules.
In summary, these rules state that a pointer to any type must never be dereferenced by a pointer to any other incompatible type.
The following code snippet might aid in understand aliasing rules better:
</p>

<div class="code"><pre>
    short a;
    short* pa = 0;
    int i = 0x1234;

    a = (short)i;    /* okay */
    a = *(short*)&amp;i; /* breaks aliasing rules */
</pre></div>

<p>
An email posting, <a href="http://mail-index.netbsd.org/tech-kern/2003/08/11/0001.html">Aliasing, pointer casts and gcc 3.3</a> elaborates further on the subject.
In SWIG, the "in" and "out" typemaps for pointers are typically
</p>

<div class="code"><pre>
    %typemap(in) struct Foo * %{
      $1 = *(struct Foo **)&amp;$input; /* cast jlong into C ptr */
    %}
    %typemap(out) struct Bar * %{
      *(struct Bar **)&amp;$result = $1; /* cast C ptr into jlong */
    %} 
    struct Bar {...};
    struct Foo {...};
    struct Bar * FooBar(struct Foo *f);
</pre></div>

<p>
resulting in the following code which breaks the aliasing rules:
</p>

<div class="code"><pre>
SWIGEXPORT jlong JNICALL Java_exampleJNI_FooBar(JNIEnv *jenv, jclass jcls,
                                                jlong jarg1, jobject jarg1_) {
  jlong jresult = 0 ;
  struct Foo *arg1 = (struct Foo *) 0 ;
  struct Bar *result = 0 ;
  
  (void)jenv;
  (void)jcls;
  (void)jarg1_;
  arg1 = *(struct Foo **)&amp;jarg1; 
  result = (struct Bar *)FooBar(arg1);
  *(struct Bar **)&amp;jresult = result; 
  return jresult;
}
</pre></div>

<p>
If you are using gcc as your C compiler, you might get a "dereferencing type-punned pointer will break strict-aliasing rules" warning about this.
Please see <a href="#Java_compiling_dynamic">Compiling a dynamic module</a> to avoid runtime problems with these strict aliasing rules.
</p>

<p>
The default code generated by SWIG for the Java module comes from the typemaps in the "<tt>java.swg</tt>" library file which implements the 
<a href="#Java_default_primitive_type_mappings">Default primitive type mappings</a> and 
<a href="#Java_default_non_primitive_typemaps">Default typemaps for non-primitive types</a> covered earlier.
There are other type mapping typemaps in the Java library. 
These are listed below:
</p>

<br>&nbsp;
<table BORDER summary="Java library typemap mappings">
<tr VALIGN=TOP>
<td><b>C Type</b></td>
<td><b>Typemap</b></td>
<td><b>File</b></td>
<td><b>Kind</b></td>
<td><b>Java Type</b></td>
<td><b>Function</b></td>
</tr>

<tr>
<td>primitive pointers and references</td>
<td>INPUT</td>
<td>typemaps.i</td>
<td>input</td>
<td>Java basic types</td>
<td>Allows values to be used for C functions taking pointers for data input.

<tr>
<td>primitive pointers and references</td>
<td>OUTPUT</td>
<td>typemaps.i</td>
<td>output</td>
<td>Java basic type arrays</td>
<td>Allows values held within an array to be used for C functions taking pointers for data output.

<tr>
<td>primitive pointers and references</td>
<td>INOUT</td>
<td>typemaps.i</td>
<td>input<br>output</td>
<td>Java basic type arrays</td>
<td>Allows values held within an array to be used for C functions taking pointers for data input and output.

<tr>
<td>string <br>wstring</td>
<td>[unnamed]</td>
<td>std_string.i</td>
<td>input<br> output</td>
<td>String</td>
<td>Use for std::string mapping to Java String.</td>
</tr>

<tr>
<td>arrays of primitive types</td>
<td>[unnamed]</td>
<td>arrays_java.i</td>
<td>input<br> output</td>
<td>arrays of primitive Java types</td>
<td>Use for mapping C arrays to Java arrays.</td>
</tr>

<tr>
<td>arrays of classes/structs/unions</td>
<td>JAVA_ARRAYSOFCLASSES macro</td>
<td>arrays_java.i</td>
<td>input<br> output</td>
<td>arrays of proxy classes</td>
<td>Use for mapping C arrays to Java arrays.</td>
</tr>

<tr>
<td>arrays of enums</td>
<td>ARRAYSOFENUMS</td>
<td>arrays_java.i</td>
<td>input<br> output</td>
<td>int[]</td>
<td>Use for mapping C arrays to Java arrays (typeunsafe and simple enum wrapping approaches only).</td>
</tr>

<tr VALIGN=TOP>
<td>char *</td>
<td>BYTE</td>
<td>various.i</td>
<td>input</td>
<td>byte[]</td>

<td VALIGN=TOP>Java byte array is converted to char array</td>
</tr>

<tr>
<td>char **</td>
<td>STRING_ARRAY</td>
<td>various.i</td>
<td>input<br> output</td>
<td>String[]</td>
<td>Use for mapping NULL terminated arrays of C strings to Java String arrays</td>
</tr>

<tr>
<td>unsigned char *</td>
<td>NIOBUFFER</td>
<td>various.i</td>
<td>input<br> output</td>
<td>java.nio.Buffer</td>
<td>Use for mapping directly allocated buffers to c/c++. useful with directors and long lived memory objects</td>
</tr>

</table>

<H3><a name="Java_typemap_attributes"></a>25.9.6 Java typemap attributes</H3>


<p>
There are a few additional typemap attributes that the Java module supports.
</p>

<p>
The first of these is the 'throws' attribute.
The throws attribute is optional and specified after the typemap name and contains one or more comma separated classes for adding to the throws clause for any methods that use that typemap.
It is analogous to the <a href="#Java_exception_handling">%javaexception</a> feature's throws attribute.
</p>

<div class="code">
<pre>
%typemap(typemapname, throws="ExceptionClass1, ExceptionClass2") type { ... }
</pre>
</div>

<p>
The attribute is necessary for supporting Java checked exceptions and can be added to just about any typemap.
The list of typemaps include all the C/C++ (JNI) typemaps in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter and the
Java specific typemaps listed in <a href="#Java_typemaps_c_to_java_types">the previous section</a>, barring
the "jni", "jtype" and "jstype" typemaps as they could never contain code to throw an exception.
</p>

<p>
The throws clause is generated for the proxy method as well as the JNI method in the JNI intermediary class.
If a method uses more than one typemap and each of those typemaps have classes specified in the throws clause,
the union of the exception classes is added to the throws clause ensuring there are no duplicate classes.
See the <a href="#Java_nan_exception_typemap">NaN exception example</a> for further usage.
</p>

<p>
The "jtype" typemap has the optional 'nopgcpp' attribute which can be used to suppress the generation of the <a href="#Java_pgcpp">premature garbage collection prevention parameter</a>.
</p>

<p>
The "javain" typemap has the optional 'pre', 'post' and 'pgcppname' attributes. These are used for generating code before and after the JNI call in the proxy class or module class. The 'pre' attribute contains code that is generated before the JNI call and the 'post' attribute contains code generated after the JNI call. The 'pgcppname' attribute is used to change the <a href="#Java_pgcpp">premature garbage collection prevention parameter</a> name passed to the JNI function. This is sometimes needed when the 'pre' typemap creates a temporary variable which is then passed to the JNI function.
</p>

<p>
<a name="Java_constructor_helper_function"></a>
Note that when the 'pre' or 'post' attributes are specified and the associated type is used in a constructor, a constructor helper function is generated. This is necessary as the Java proxy constructor wrapper makes a call to a support constructor using a <i>this</i> call. In Java the <i>this</i> call must be the first statement in the constructor body. The constructor body thus calls the helper function and the helper function instead makes the JNI call, ensuring the 'pre' code is called before the JNI call is made. There is a <a href="#Java_date_marshalling">Date marshalling</a> example showing 'pre', 'post' and 'pgcppname' attributes in action.
</p>

<H3><a name="Java_special_variables"></a>25.9.7 Java special variables</H3>


<p>
The standard SWIG special variables are available for use within typemaps as described in the <a href="Typemaps.html#Typemaps">Typemaps documentation</a>, for example <tt>$1</tt>, <tt>$input</tt>,<tt>$result</tt> etc.
</p>

<p>
The Java module uses a few additional special variables:
</p>

<p>
<b><tt>$javaclassname</tt></b><br>
This special variable works like the other <a href="Typemaps.html#Typemaps_special_variables">special variables</a>
and <tt>$javaclassname</tt> is similar to <tt>$1_type</tt>. It expands to the class name for use in Java given a pointer. 
SWIG wraps unions, structs and classes using pointers and in this case it expands to the Java proxy class name.
For example, <tt>$javaclassname</tt> is replaced by the proxy classname <tt>Foo</tt> when wrapping a <tt>Foo *</tt> and 
<tt>$&amp;javaclassname</tt> expands to the proxy classname when wrapping the C/C++ type <tt>Foo</tt> and <tt>$*javaclassname</tt>
expands to the proxy classname when wrapping <tt>Foo *&amp;</tt>.
If the type does not have an associated proxy class, it expands to the type wrapper class name, for example,
<tt>SWIGTYPE_p_unsigned_short</tt> is generated when wrapping <tt>unsigned short *</tt>.
</p>

<p>
<b><tt>$javaclazzname</tt></b><br>
This special variable works like <tt>$javaclassname</tt>, but expands the fully qualified C++ class into the package name,
if used by the <a href="SWIGPlus.html#SWIGPlus_nspace">nspace feature</a>, and the proxy class name, mangled for use as a function name. 
For example, <tt>Namespace1::Namespace2::Klass</tt> is expanded into <tt>Namespace1_Namespace2_Klass_</tt>.
This special variable is usually used for making calls to a function in the intermediary JNI class, as they are mangled with this prefix.
</p>

<p>
<b><tt>$null</tt></b><br>
Used in input typemaps to return early from JNI functions that have either void or a non-void return type. Example:
</p>

<div class="code"><pre>
%typemap(check) int * %{ 
  if (error) {
    SWIG_JavaThrowException(jenv, SWIG_JavaIndexOutOfBoundsException, "Array element error");
    return $null;
  }
%}
</pre></div>

<p>
If the typemap gets put into a function with void as return, $null will expand to nothing:
</p>

<div class="code"><pre>
SWIGEXPORT void JNICALL Java_jnifn(...) {
    if (error) {
      SWIG_JavaThrowException(jenv, SWIG_JavaIndexOutOfBoundsException, "Array element error");
      return ;
    }
  ...
}
</pre></div>

<p>
otherwise $null expands to <i>NULL</i>
</p>

<div class="code"><pre>
SWIGEXPORT jobject JNICALL Java_jnifn(...) {
    if (error) {
      SWIG_JavaThrowException(jenv, SWIG_JavaIndexOutOfBoundsException, "Array element error");
      return NULL;
    }
  ...
}
</pre></div>

<p>
<b><tt>$javainput, $jnicall and $owner</tt></b><br>
The $javainput special variable is used in "javain" typemaps and $jnicall and $owner are used in "javaout" typemaps.
$jnicall is analogous to $action in %exception. It is replaced by the call to the native method in the intermediary JNI class.
$owner is replaced by either <tt>true</tt> if %newobject has been used, otherwise <tt>false</tt>.
$javainput is analogous to the $input special variable. It is replaced by the parameter name.
</p>

<p>
Here is an example:
</p>

<div class="code"><pre>
%typemap(javain) Class "Class.getCPtr($javainput)"
%typemap(javain) unsigned short "$javainput"
%typemap(javaout) Class * {
    return new Class($jnicall, $owner);
  }

%inline %{
    class Class {...};
    Class * bar(Class cls, unsigned short ush) { return new Class(); };
%}
</pre></div>

<p>
The generated proxy code is then:
</p>

<div class="code"><pre>
public static Class bar(Class cls, int ush) {
  return new Class(exampleJNI.bar(Class.getCPtr(cls), cls, ush), false);
}
</pre></div>

<p>
Here $javainput has been replaced by <tt>cls</tt> and <tt>ush</tt>. $jnicall has been replaced by 
the native method call, <tt>exampleJNI.bar(...)</tt> and $owner has been replaced by <tt>false</tt>.
If %newobject is used by adding the following at the beginning of our example:
</p>

<div class="code"><pre>
%newobject bar(Class cls, unsigned short ush);
</pre></div>

<p>
The generated code constructs the return type using <tt>true</tt> indicating the proxy class <tt>Class</tt> is responsible for destroying the C++ memory allocated for it in <tt>bar</tt>:
</p>

<div class="code"><pre>
public static Class bar(Class cls, int ush) {
  return new Class(exampleJNI.bar(Class.getCPtr(cls), cls, ush), true);
}
</pre></div>

<p>
<b><tt>$static</tt></b><br>
This special variable expands to either <i>static</i> or nothing depending on whether the class is an inner Java class or not.
It is used in the "javaclassmodifiers" typemap so that global classes can be wrapped as Java proxy classes and nested C++ classes/enums
can be wrapped with the Java equivalent, that is, static inner proxy classes.
</p>

<p>
<b><tt>$error, $jniinput, $javacall and $packagepath</tt></b><br>
These special variables are used in the directors typemaps. See <a href="#Java_directors_typemaps">Director specific typemaps</a> for details.
</p>

<p>
<b><tt>$module</tt></b><br>
This special variable expands to the module name, as specified by <tt>%module</tt> or the <tt>-module</tt> commandline option.
</p>

<p>
<b><tt>$imclassname</tt></b><br>
This special variable expands to the intermediary class name. Usually this is the same as '$moduleJNI',
unless the jniclassname attribute is specified in the <a href="Java.html#Java_module_directive">%module directive</a>.
</p>

<H3><a name="Java_typemaps_for_c_and_cpp"></a>25.9.8 Typemaps for both C and C++ compilation</H3>


<p>
JNI calls must be written differently depending on whether the code is being compiled as C or C++. 
For example C compilation requires the pointer to a function pointer struct member syntax like
</p>

<div class="code"><pre>
const jclass clazz = (*jenv)-&gt;FindClass(jenv, "java/lang/String");
</pre></div>

<p>
whereas C++ code compilation of the same function call is a member function call using a class pointer like
</p>

<div class="code"><pre>
const jclass clazz = jenv-&gt;FindClass("java/lang/String");
</pre></div>

<p>
To enable typemaps to be used for either C or C++ compilation, a set of JCALLx macros have been defined in Lib/java/javahead.swg, 
where x is the number of arguments in the C++ version of the JNI call. 
The above JNI calls would be written in a typemap like this
</p>

<div class="code"><pre>
const jclass clazz = JCALL1(FindClass, jenv, "java/lang/String");
</pre></div>

<p>
Note that the SWIG preprocessor expands these into the appropriate C or C++ JNI calling convention. 
The C calling convention is emitted by default and the C++ calling convention is emitted when using the -c++ SWIG commandline option. 
If you do not intend your code to be targeting both C and C++ then your typemaps can use the appropriate JNI calling convention and need not use the JCALLx macros.
</p>


<H3><a name="Java_code_typemaps"></a>25.9.9 Java code typemaps</H3>


<p>
Most of SWIG's typemaps are used for the generation of C/C++ code. 
The typemaps in this section are used solely for the generation of Java code. 
Elements of proxy classes and type wrapper classes come from the following typemaps (the defaults).
</p>

<p><tt>%typemap(javabase)</tt></p>
<div class="indent">
base (extends) for Java class: empty default
<br>
Note that this typemap accepts a <tt>replace</tt> attribute as an optional flag. When set to "1", it will replace/override any C++ base classes
that might have been parsed. If this flag is not specified and there are C++ base classes, then a multiple inheritance warning
is issued and the code in the typemap is ignored.
The typemap also accepts a <tt>notderived</tt> attribute as an optional flag. When set to "1", it will not apply to classes that
are derived from a C++ base. 
When used with the SWIGTYPE type, it is useful for giving a common base for all proxy classes, that is, providing a base class that sits in between all proxy classes and the Java base class <tt>Object</tt> for example: <tt>%typemap(javabase, notderived="1") SWIGTYPE "CommonBase"</tt>.
</div>

<p><tt>%typemap(javabody)</tt></p>
<div class="indent">
  the essential support body for proxy classes (proxy base classes only), typewrapper classes and enum classes.
  Default contains extra constructors, memory ownership control member variables (<tt>swigCMemOwn</tt>, <tt>swigCPtr</tt>), the <tt>getCPtr</tt> method etc.
</div>

<p><tt>%typemap(javabody_derived)</tt></p>
<div class="indent">
  the essential support body for proxy classes (derived classes only).
  Same as "javabody" typemap, but only used for proxy derived classes.
</div>

<p><tt>%typemap(javaclassmodifiers)</tt></p>
<div class="indent">
class modifiers for the Java class: default is "public class"
</div>

<p><tt>%typemap(javacode)</tt></p>
<div class="indent">
Java code is copied verbatim to the Java class: empty default
</div>

<p><tt>%typemap(javadestruct, methodname="delete", methodmodifiers="public synchronized")</tt> <br></p>
<div class="indent">
destructor wrapper - the <tt>delete()</tt> method (proxy classes only),
used for all proxy classes except those which have a base class
: default calls C++ destructor (or frees C memory) and resets <tt>swigCPtr</tt> and <tt>swigCMemOwn</tt> flags
<br>
<br>
Note that the <tt>delete()</tt> method name is configurable and is specified by the <tt>methodname</tt> attribute.
The method modifiers are also configurable via the <tt>methodmodifiers</tt> attribute.
</div>

<p><tt>%typemap(javadestruct_derived, methodname="delete", methodmodifiers="public synchronized")</tt></p>
<div class="indent">
destructor wrapper - the <tt>delete()</tt> method (proxy classes only),
same as "javadestruct" but only used for derived proxy classes
: default calls C++ destructor (or frees C memory) and resets <tt>swigCPtr</tt> and <tt>swigCMemOwn</tt> flags
<br>
<br>
Note that the <tt>delete()</tt> method name is configurable and is specified by the <tt>methodname</tt> attribute.
The method modifiers are also configurable via the <tt>methodmodifiers</tt> attribute.
</div>

<p><tt>%typemap(javaimports)</tt></p>
<div class="indent">
import statements for Java class: empty default
</div>

<p><tt>%typemap(javainterfaces)</tt></p>
<div class="indent">
interfaces (implements) for Java class: empty default
</div>

<p><tt>%typemap(javafinalize)</tt></p>
<div class="indent">
the <tt>finalize()</tt> method (proxy classes only): default calls the <tt>delete()</tt> method

<p>
Note that the default javafinalize typemap must contain the full implementation of the finalize method.
Any customization to this typemap must still declare a java finalize method with the correct signature.
Note also that the name of the generated "delete" method may be affected by <tt>javadestruct</tt> and <tt>javadestruct_derived</tt> typemaps.
Below shows an example modifying the finalizer, assuming the <tt>delete</tt> method has been renamed to <tt>swig_delete</tt>.
</p>

<div class="code"><pre>
%typemap(javafinalize) SWIGTYPE %{
   protected void finalize() {
     swig_delete();  // renamed to prevent conflict with existing delete method
   }
]%
</pre></div>

</div>

<p>
<b>Compatibility Note:</b> In SWIG-1.3.21 and earlier releases, typemaps called "javagetcptr" and "javaptrconstructormodifiers" were available.
These are deprecated and the "javabody" typemap can be used instead.
</p>

<p>
In summary the contents of the typemaps make up a proxy class like this:
</p>

<div class="code">
<pre>
[ javaimports typemap ]
[ javaclassmodifiers typemap ] javaclassname extends [ javabase typemap ]
                                             implements [ javainterfaces typemap ] {
[ javabody or javabody_derived typemap ]
[ javafinalize typemap ]
public synchronized void <i>delete</i>() [ javadestruct OR javadestruct_derived typemap ]
[ javacode typemap ]
... proxy functions ...
}
</pre>
</div>

<p>
Note the <tt><i>delete</i>()</tt> methodname and method modifiers are configurable, see "javadestruct" and "javadestruct_derived" typemaps above.
</p>

<p>
The type wrapper class is similar in construction:
</p>

<div class="code">
<pre>
[ javaimports typemap ]
[ javaclassmodifiers typemap ] javaclassname extends [ javabase typemap ]
                                             implements [ javainterfaces typemap ] {
[ javabody typemap ]
[ javacode typemap ]
}
</pre>
</div>

<p>The enum class is also similar in construction:</p>
<div class="code">
<pre>
[ javaimports typemap ]
[ javaclassmodifiers typemap ] javaclassname extends [ javabase typemap ]
                                             implements [ javainterfaces typemap ] {
... Enum values ...
[ javabody typemap ]
[ javacode typemap ]
}
</pre>
</div>

<p>
The "javaimports" typemap is ignored if the enum class is wrapped by an inner Java class, that is when wrapping an enum declared within a C++ class.
</p>

<p>
The defaults can be overridden to tailor these classes.
Here is an example which will change the <tt>getCPtr</tt> method and constructor from the default public access to protected access. 
If the classes in one package are not using the classes in another package, then these methods need not be public and removing access to these low level implementation details, is a good thing.
If you are invoking SWIG more than once and generating the wrapped classes into different packages in each invocation, then you cannot do this as you will then have different packages.
</p>

<div class="code">
<pre>
%typemap(javabody) SWIGTYPE %{
  private transient long swigCPtr;
  protected transient boolean swigCMemOwn;

  protected $javaclassname(long cPtr, boolean cMemoryOwn) {
    swigCMemOwn = cMemoryOwn;
    swigCPtr = cPtr;
  }

  protected static long getCPtr($javaclassname obj) {
    return (obj == null) ? 0 : obj.swigCPtr;
  }
%}
</pre>
</div>

<p>
The typemap code is the same that is in "<tt>java.swg</tt>", barring the last two method modifiers.
Note that <tt>SWIGTYPE</tt> will target all proxy classes, but not the type wrapper classes.
Also the above typemap is only used for proxy classes that are potential base classes.
To target proxy classes that are derived from a wrapped class as well, the "javabody_derived" typemap should also be overridden.
</p>

<p>
For the typemap to be used in all type wrapper classes, all the different types that type wrapper classes could be used for should be targeted:
</p>

<div class="code">
<pre>
%typemap(javabody) SWIGTYPE *, SWIGTYPE &amp;, SWIGTYPE [], SWIGTYPE (CLASS::*) %{
  private transient long swigCPtr;

  protected $javaclassname(long cPtr, boolean bFutureUse) {
    swigCPtr = cPtr;
  }

  protected $javaclassname() {
    swigCPtr = 0;
  }

  protected static long getCPtr($javaclassname obj) {
    return (obj == null) ? 0 : obj.swigCPtr;
  }
%}
</pre>
</div>

<p>
Again this is the same that is in "<tt>java.swg</tt>", barring the method modifier for <tt>getCPtr</tt>.
</p>

<p>
When using <a href="Modules.html">multiple modules</a> or the <a href="#Java_namespaces">nspace feature</a> it is common to invoke SWIG with a different <tt>-package</tt>
command line option for each module.
However, by default the generated code may not compile if 
generated classes in one package use generated classes in another package.
The visibility of the
<tt>getCPtr()</tt> and pointer constructor generated from the <tt>javabody</tt> typemaps needs changing.
The default visibility is <tt>protected</tt> but it needs to be <tt>public</tt> for access from a different package.
Just changing 'protected' to 'public' in the typemap achieves this.
Two macros are available in <tt>java.swg</tt> to make this easier and using them is the preferred approach
over simply copying the typemaps and modifying as this is forward compatible with any changes in
the <tt>javabody</tt> typemap in future versions of SWIG.
The macros are for the proxy and typewrapper classes and can respectively be used to
to make the method and constructor public:
</p>

<div class="code">
<pre>
  SWIG_JAVABODY_PROXY(public, public, SWIGTYPE)
  SWIG_JAVABODY_TYPEWRAPPER(public, public, public, SWIGTYPE)
</pre>
</div>

<H3><a name="Java_directors_typemaps"></a>25.9.10 Director specific typemaps</H3>


<p>
The Java directors feature requires the "javadirectorin", "javadirectorout", "directorin" and the "directorout" typemaps in order to work properly.
The "javapackage" typemap is an optional typemap used to identify the Java package path for individual SWIG generated proxy classes used in director methods.
</p>

<p><tt>%typemap(directorin)</tt></p>
<div class="indent">

<p>
The "directorin" typemap is used for converting arguments in the C++ director class to the appropriate JNI type before the upcall to Java.
This typemap also specifies the JNI field descriptor for the type in the "descriptor" attribute.
For example, integers are converted as follows:
</p>

<div class="code">
<pre>
%typemap(directorin,descriptor="I") int "$input = (jint) $1;"
</pre>
</div>

<p>
<code>$input</code> is the SWIG name of the JNI temporary variable passed to Java in the upcall.
The <code>descriptor="I"</code> will put an <code>I</code> into the JNI field descriptor that identifies the Java method that will be called from C++.
For more about JNI field descriptors and their importance, refer to the <a href="#Java_typemaps">JNI documentation mentioned earlier</a>.
A typemap for C character strings is:
</p>

<div class="code">
<pre>
%typemap(directorin,descriptor="Ljava/lang/String;") char *
  %{ $input = jenv-&gt;NewStringUTF($1); %}
</pre>
</div>


<p>
User-defined types have the default "descriptor" attribute "<code>L$packagepath/$javaclassname;</code>" where <code>$packagepath</code> 
is the package name passed from the SWIG command line and <code>$javaclassname</code> is the Java proxy class' name.
If the <tt>-package</tt> commandline option is not used to specify the package, then '$packagepath/' will be removed from the resulting output JNI field descriptor.
<b>Do not forget the terminating ';' for JNI field descriptors starting with 'L'.</b>
If the ';' is left out, Java will generate a "method not found" runtime error.
Note that the <code>$packagepath</code> substitution always uses the path separator '/' when expanded.
The <code>$javaclassname</code> expansion can be confusing as it is normally expanded using the '.' separator.
However, <code>$javaclassname</code> is expanded using the path separator '/' in typemap's "descriptor" attribute
as well as in the "directorthrows" typemap.
</p>
</div>


<p><tt>%typemap(directorout)</tt></p>
<div class="indent">

<p>
The "directorout" typemap is used for converting the JNI return type in the C++ director class to the appropriate C++ type after the upcall to Java.
For example, integers are converted as follows:
</p>

<div class="code">
<pre>
%typemap(directorout) int %{ $result = (int)$input; %}
</pre>
</div>

<p>
<code>$input</code> is the SWIG name of the JNI temporary variable returned from Java after the upcall.
<code>$result</code> is the resulting output.
A typemap for C character strings is:
</p>

<div class="code">
<pre>
%typemap(directorout) char * {
  $1 = 0;
  if ($input) {
    $result = (char *)jenv-&gt;GetStringUTFChars($input, 0);
    if (!$1) return $null;
  }
}
</pre>
</div>

</div>


<p><tt>%typemap(javadirectorin)</tt></p>
<div class="indent">

<p>
Conversion from jtype to jstype for director methods.
These are Java code typemaps which transform the type used in the Java intermediary JNI class (as specified in the "jtype" typemap) to 
the Java type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap).
This typemap provides the conversion for the parameters in the director methods when calling up from C++ to Java.
</p>

<p>
For primitive types, this typemap is usually specified as:
</p>

<div class="code">
<pre>
%typemap(javadirectorin) int "$jniinput"
</pre>
</div>

<p>
The <code>$jniinput</code> special variable is analogous to <code>$javainput</code> special variable.
It is replaced by the input parameter name.
</p>

</div>


<p><tt>%typemap(javadirectorout)</tt></p>
<div class="indent">

<p>
Conversion from jstype to jtype for director methods.
These are Java code typemaps which transform the type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap)
to the type used in the Java intermediary JNI class (as specified in the "jtype" typemap).
This typemap provides the conversion for the return type in the director methods when returning from the C++ to Java upcall.
</p>

<p>
For primitive types, this typemap is usually specified as:
</p>

<div class="code">
<pre>
%typemap(javadirectorout) int "$javacall"
</pre>
</div>

<p>
The <code>$javacall</code> special variable is analogous to the <code>$jnicall</code> special variable.
It is replaced by the call to the target Java method.
The target method is the method in the Java proxy class which overrides the virtual C++ method in the C++ base class.
</p>

</div>

<p><tt>%typemap(directorthrows)</tt></p>
<div class="indent">

<p>
Conversion of Java exceptions to C++ exceptions in director method's exception handling.
This typemap is expected to test the <tt>$error</tt> special variable for a matching Java exception
and if successful convert and throw it into a C++ exception given by the typemap's type.
The <code>$error</code> special variable is of type <code>jthrowable</code> and is
substituted with a unique variable name in the generated code.
</p>

<p>
The example below converts a Java <code>java.lang.IndexOutOfBoundsException</code> exception
to the typemap's type, that is <code>std::out_of_range</code>:
</p>

<div class="code">
<pre>
%typemap(directorthrows) std::out_of_range %{
  if (Swig::ExceptionMatches(jenv, $error, "java/lang/IndexOutOfBoundsException")) {
    throw std::out_of_range(Swig::JavaExceptionMessage(jenv, $error).message());
  }
%}
</pre>
</div>

<p>
The utility function <code>Swig::ExceptionMatches</code>
and class <code>Swig::JavaExceptionMessage</code> are helpers available when using directors and are described
in the <a href="#Java_exceptions_from_directors">Java Exceptions from Directors</a> section.
</p>

</div>

<p><tt>%typemap(javapackage)</tt></p>
<div class="indent">


<p>
The "javapackage" typemap is optional; it serves to identify a class's Java package.
This typemap should be used in conjunction with classes that are defined outside of the current SWIG interface file.
The typemap is only used if the type is used in a director method, that is, in a virtual method in a director class.
For example:
</p>

<div class="code">
<pre>
// class Foo is handled in a different interface file:
%import "Foo.i"

%feature("director") Example;

%inline {
  class Bar { };

  class Example {
  public:
    virtual ~Example();
    virtual void ping(Foo *arg1, Bar *arg2);
  };
}
</pre>
</div>

<p>
Assume that the Foo class is part of the Java package <i>com.wombat.foo</i> but the above interface file is part of the Java package <i>com.wombat.example</i>.
Without the "javapackage" typemap, SWIG will assume that the Foo class belongs to <i>com.wombat.example</i> class.
The corrected interface file looks like:
</p>

<div class="code">
<pre>
// class Foo is handled in a different interface file:
%import "Foo.i"
%typemap("javapackage") Foo, Foo *, Foo &amp; "com.wombat.foo";
%feature("director") Example;

%inline {
  class Bar { };

  class Example {
  public:
    virtual ~Example();
    virtual void ping(Foo *arg1, Bar *arg2);
  };
}
</pre>
</div>

<p>
SWIG looks up the package based on the <b>actual</b> type (plain Foo, Foo pointer and Foo reference), so it is important to associate all three types with the desired package.
Practically speaking, you should create a separate SWIG interface file, which is %import-ed into each SWIG interface file, when you have multiple Java packages.
Note the helper macros below, <code>OTHER_PACKAGE_SPEC</code> and <code>ANOTHER_PACKAGE_SPEC</code>, which reduce the amount of extra typing.
"<code>TYPE...</code>" is useful when passing templated types to the macro, since multiargument template types appear to the SWIG preprocessor as multiple macro arguments.
</p>

<div class="code">
<pre>
%typemap("javapackage") SWIGTYPE, SWIGTYPE *, SWIGTYPE &amp;
                                            "package.for.most.classes";

%define OTHER_PACKAGE_SPEC(TYPE...)
%typemap("javapackage") TYPE, TYPE *, TYPE &amp; "package.for.other.classes";
%enddef

%define ANOTHER_PACKAGE_SPEC(TYPE...)
%typemap("javapackage") TYPE, TYPE *, TYPE &amp; "package.for.another.set";
%enddef

OTHER_PACKAGE_SPEC(Package_2_class_one)
ANOTHER_PACKAGE_SPEC(Package_3_class_two)
/* etc */
</pre>
</div>

<p>
The basic strategy here is to provide a default package typemap for the majority of the classes, only providing "javapackage" typemaps for the exceptions.
</p>

</div>

<H2><a name="Java_typemap_examples"></a>25.10 Typemap Examples</H2>


<p>
This section includes a few examples of typemaps.  For more examples, you
might look at the files "<tt>java.swg</tt>" and "<tt>typemaps.i</tt>" in
the SWIG library.
</p>


<H3><a name="Java_simpler_enum_classes"></a>25.10.1 Simpler Java enums for enums without initializers</H3>


<p>
The default <a href="#Java_proper_enums_classes">Proper Java enums</a> approach to wrapping enums is somewhat verbose.
This is to handle all possible C/C++ enums, in particular enums with initializers.
The generated code can be simplified if the enum being wrapped does not have any initializers.
</p>

<p>
The following shows how to remove the support methods that are generated by default and instead use the methods in the Java
enum base class <tt>java.lang.Enum</tt> and <tt>java.lang.Class</tt> for marshalling enums between C/C++ and Java.
The type used for the typemaps below is <tt>enum SWIGTYPE</tt> which is the default type used for all enums.
The "enums.swg" file should be examined in order to see the original overridden versions of the typemaps.
</p>

<div class="code">
<pre>
%include "enums.swg"

%typemap(javain) enum SWIGTYPE "$javainput.ordinal()"
%typemap(javaout) enum SWIGTYPE {
    return $javaclassname.class.getEnumConstants()[$jnicall];
  }
%typemap(javabody) enum SWIGTYPE ""

%inline %{
  enum HairType { blonde, ginger, brunette };
  void setHair(HairType h);
  HairType getHair();
%}
</pre>
</div>

<p>
SWIG will generate the following Java enum, which is somewhat simpler than the default:
</p>

<div class="code">
<pre>
public enum HairType {
  blonde,
  ginger,
  brunette;
}
</pre>
</div>

<p>
and the two Java proxy methods will be:
</p>

<div class="code">
<pre>
public static void setHair(HairType h) {
  exampleJNI.setHair(h.ordinal());
}

public static HairType getHair() {
  return HairType.class.getEnumConstants()[exampleJNI.getHair()];
}
</pre>
</div>

<p>
For marshalling Java enums to C/C++ enums, the <tt>ordinal</tt> method is used to convert the
Java enum into an integer value for passing to the JNI layer, see the "javain" typemap.
For marshalling C/C++ enums to Java enums, the C/C++ enum value is cast to an integer in the C/C++ typemaps (not shown).
This integer value is then used to index into the array of enum constants that the Java language provides.
See the <tt>getEnumConstants</tt> method in the "javaout" typemap.
</p>

<p>
These typemaps can often be used as the default for wrapping enums as in many cases there won't be any enum initializers.
In fact a good strategy is to always use these typemaps and to specifically handle enums with initializers using %apply.
This would be done by using the original versions of these typemaps in "enums.swg" under another typemap name for applying using %apply.
</p>


<H3><a name="Java_exception_typemap"></a>25.10.2 Handling C++ exception specifications as Java exceptions</H3>


<p>
This example demonstrates various ways in which C++ exceptions can be tailored and converted into Java exceptions.
Let's consider a simple file class <tt>SimpleFile</tt> and an exception class <tt>FileException</tt> which it may throw on error:
</p>

<div class="code">
<pre>
%include "std_string.i" // for std::string typemaps
#include &lt;string&gt;

class FileException {
  std::string message;
public:
  FileException(const std::string&amp; msg) : message(msg) {}
  std::string what() {
    return message;
  }
};

class SimpleFile {
  std::string filename;
public:
  SimpleFile(const std::string&amp; filename) : filename(filename) {}
  void open() throw(FileException) {
  ...
  }
};
</pre>
</div>

<p>
As the <tt>open</tt> method has a C++ exception specification, SWIG will parse this and know that the method can throw an exception.
The <a href="Typemaps.html#throws_typemap">"throws" typemap</a> is then used when SWIG encounters an exception specification.
The default generic "throws" typemap looks like this:
</p>

<div class="code">
<pre>
%typemap(throws) SWIGTYPE, SWIGTYPE &amp;, SWIGTYPE *, SWIGTYPE [ANY] %{
  SWIG_JavaThrowException(jenv, SWIG_JavaRuntimeException,
                          "C++ $1_type exception thrown");
  return $null;
%}
</pre>
</div>

<p>
Basically SWIG will generate a C++ try catch block and the body of the "throws" typemap constitutes the catch block.
The above typemap calls a SWIG supplied method which throws a <tt>java.lang.RuntimeException</tt>.
This exception class is a runtime exception and therefore not a checked exception.
If, however, we wanted to throw a checked exception, say <tt>java.io.IOException</tt>, then we could use the following typemap:
</p>

<div class="code">
<pre>
%typemap(throws, throws="java.io.IOException") FileException {
  jclass excep = jenv-&gt;FindClass("java/io/IOException");
  if (excep)
    jenv-&gt;ThrowNew(excep, $1.what().c_str());
  return $null;
}
</pre>
</div>

<p>
Note that this typemap uses the 'throws' <a href="#Java_typemap_attributes">typemap attribute</a> to ensure a throws clause is generated.
The generated proxy method then specifies the checked exception by containing <tt>java.io.IOException</tt> in the throws clause:
</p>

<div class="code">
<pre>
public class SimpleFile {
  ...
  public void open() throws java.io.IOException { ... }
}
</pre>
</div>

<p>
Lastly, if you don't want to map your C++ exception into one of the standard Java exceptions, the C++ class can be wrapped and turned into a custom Java exception class.
If we go back to our example, the first thing we must do is get SWIG to wrap <tt>FileException</tt> and ensure that it derives from <tt>java.lang.Exception</tt>.
Additionally, we might want to override the <tt>java.lang.Exception.getMessage()</tt> method.
The typemaps to use then are as follows:
</p>

<div class="code">
<pre>
%typemap(javabase) FileException "java.lang.Exception";
%typemap(javacode) FileException %{
  public String getMessage() {
    return what();
  }
%}
</pre>
</div>

<p>
This generates:
</p>

<div class="code">
<pre>
public class FileException extends java.lang.Exception {
  ...
  public String getMessage() {
    return what();
  }

  public FileException(String msg) { ... }

  public String what() {
    return exampleJNI.FileException_what(swigCPtr, this);
  }
}
</pre>
</div>

<p>
We could alternatively have used <tt>%rename</tt> to rename <tt>what()</tt> into <tt>getMessage()</tt>.
</p>


<H3><a name="Java_nan_exception_typemap"></a>25.10.3 NaN Exception - exception handling for a particular type</H3>


<p>
A Java exception can be thrown from any Java or JNI code.
Therefore, as most typemaps contain either Java or JNI code, just about any typemap could throw an exception.
The following example demonstrates exception handling on a type by type basis by checking for 'Not a number' (NaN) whenever a parameter of type <tt>float</tt> is wrapped.
</p>

<p>
Consider the following C++ code:
</p>

<div class="code">
<pre>
bool calculate(float first, float second);
</pre>
</div>

<p>
To validate every <tt>float</tt> being passed to C++, we could precede the code being wrapped by the following typemap which throws a runtime exception whenever the <tt>float</tt> is 'Not a Number':
</p>

<div class="code">
<pre>
%module example
%typemap(javain) float "$module.CheckForNaN($javainput)"
%pragma(java) modulecode=%{
  /** Simply returns the input value unless it is not a number,
      whereupon an exception is thrown. */
  static protected float CheckForNaN(float num) {
    if (Float.isNaN(num))
      throw new RuntimeException("Not a number");
    return num;
  }
%}
</pre>
</div>

<p>
Note that the <tt>CheckForNaN</tt> support method has been added to the module class using the <tt>modulecode</tt> pragma.
The following shows the generated code of interest:
</p>

<div class="code">
<pre>
public class example {
  ...

  /** Simply returns the input value unless it is not a number,
      whereupon an exception is thrown. */
  static protected float CheckForNaN(float num) {
    if (Float.isNaN(num))
      throw new RuntimeException("Not a number");
    return num;
  }

  public static boolean calculate(float first, float second) {
    return exampleJNI.calculate(example.CheckForNaN(first), example.CheckForNaN(second));
  }
}
</pre>
</div>

<p>
Note that the "javain" typemap is used for every occurrence of a <tt>float</tt> being used as an input.
Of course, we could have targeted the typemap at a particular parameter by using <tt>float first</tt>, say, instead of just <tt>float</tt>.
</p>

<p>
The exception checking could alternatively have been placed into the 'pre' attribute that the "javain" typemap supports.
The "javain" typemap above could be replaced with the following:
</p>

<div class="code">
<pre>
%typemap(javain, pre="    $module.CheckForNaN($javainput);") float "$javainput"
</pre>
</div>

<p>
which would modify the <tt>calculate</tt> function to instead be generated as:
</p>

<div class="code">
<pre>
public class example {
  ...
  public static boolean calculate(float first, float second) {
    example.CheckForNaN(first);
    example.CheckForNaN(second);
    {
      return exampleJNI.calculate(first, second);
    }
  }
}
</pre>
</div>

<p>
See the <a href="#Java_date_marshalling">Date marshalling example</a> for an example using further "javain" typemap attributes.
</p>

<p>
If we decide that what we actually want is a checked exception instead of a runtime exception, we can change this easily enough.
The proxy method that uses <tt>float</tt> as an input, must then add the exception class to the throws clause.
SWIG can handle this as it supports the 'throws' <a href="#Java_typemap_attributes">typemap attribute</a> for specifying classes for the throws clause.
Thus we can modify the pragma and the typemap for the throws clause:
</p>

<div class="code">
<pre>
%typemap(javain, throws="java.lang.Exception") float "$module.CheckForNaN($javainput)"
%pragma(java) modulecode=%{
  /** Simply returns the input value unless it is not a number,
      whereupon an exception is thrown. */
  static protected float CheckForNaN(float num) throws java.lang.Exception {
    if (Float.isNaN(num))
      throw new RuntimeException("Not a number");
    return num;
  }
%}
</pre>
</div>

<p>
The <tt>calculate</tt> method now has a throws clause and even though the typemap is used twice for both <tt>float first</tt> and <tt>float second</tt>,
the throws clause contains a single instance of <tt>java.lang.Exception</tt>:
</p>

<div class="code">
<pre>
public class example {
  ...

  /** Simply returns the input value unless it is not a number,
      whereupon an exception is thrown. */
  static protected float CheckForNaN(float num) throws java.lang.Exception {
    if (Float.isNaN(num))
      throw new RuntimeException("Not a number");
    return num;
  }

  public static boolean calculate(float first, float second) throws java.lang.Exception {
    return exampleJNI.calculate(example.CheckForNaN(first), example.CheckForNaN(second));
  }
}
</pre>
</div>

<p>
If we were a martyr to the JNI cause, we could replace the succinct code within the "javain" typemap with a few pages of JNI code.
If we had, we would have put it in the "in" typemap which, like all JNI and Java typemaps, also supports the 'throws' attribute.
</p>

<H3><a name="Java_converting_java_string_arrays"></a>25.10.4 Converting Java String arrays to char ** </H3>


<p>
A common problem in many C programs is the processing of command line arguments, which are usually passed in an array of NULL terminated strings.   
The following SWIG interface file allows a Java String array to be used as a <tt>char **</tt> object.
</p>

<div class="code"><pre>
%module example

/* This tells SWIG to treat char ** as a special case when used as a parameter
   in a function call */
%typemap(in) char ** (jint size) {
    int i = 0;
    size = (*jenv)-&gt;GetArrayLength(jenv, $input);
    $1 = (char **) malloc((size+1)*sizeof(char *));
    /* make a copy of each string */
    for (i = 0; i&lt;size; i++) {
        jstring j_string = (jstring)(*jenv)-&gt;GetObjectArrayElement(jenv, $input, i);
        const char * c_string = (*jenv)-&gt;GetStringUTFChars(jenv, j_string, 0);
        $1[i] = malloc((strlen(c_string)+1)*sizeof(char));
        strcpy($1[i], c_string);
        (*jenv)-&gt;ReleaseStringUTFChars(jenv, j_string, c_string);
        (*jenv)-&gt;DeleteLocalRef(jenv, j_string);
    }
    $1[i] = 0;
}

/* This cleans up the memory we malloc'd before the function call */
%typemap(freearg) char ** {
    int i;
    for (i=0; i&lt;size$argnum-1; i++)
      free($1[i]);
    free($1);
}

/* This allows a C function to return a char ** as a Java String array */
%typemap(out) char ** {
    int i;
    int len=0;
    jstring temp_string;
    const jclass clazz = (*jenv)-&gt;FindClass(jenv, "java/lang/String");

    while ($1[len]) len++;    
    jresult = (*jenv)-&gt;NewObjectArray(jenv, len, clazz, NULL);
    /* exception checking omitted */

    for (i=0; i&lt;len; i++) {
      temp_string = (*jenv)-&gt;NewStringUTF(jenv, *result++);
      (*jenv)-&gt;SetObjectArrayElement(jenv, jresult, i, temp_string);
      (*jenv)-&gt;DeleteLocalRef(jenv, temp_string);
    }
}

/* These 3 typemaps tell SWIG what JNI and Java types to use */
%typemap(jni) char ** "jobjectArray"
%typemap(jtype) char ** "String[]"
%typemap(jstype) char ** "String[]"

/* These 2 typemaps handle the conversion of the jtype to jstype typemap type
   and vice versa */
%typemap(javain) char ** "$javainput"
%typemap(javaout) char ** {
    return $jnicall;
  }

/* Now a few test functions */
%inline %{

int print_args(char **argv) {
    int i = 0;
    while (argv[i]) {
         printf("argv[%d] = %s\n", i, argv[i]);
         i++;
    }
    return i;
}

char **get_args() {
  static char *values[] = { "Dave", "Mike", "Susan", "John", "Michelle", 0};
  return &amp;values[0];
}

%}
</pre></div>

<p>
Note that the 'C' JNI calling convention is used. 
Checking for any thrown exceptions after JNI function calls has been omitted. 
When this module is compiled, our wrapped C functions can be used by the following Java program:
</p>

<div class="code"><pre>
// File runme.java

public class runme {

  static {
    try {
      System.loadLibrary("example");
    } catch (UnsatisfiedLinkError e) {
      System.err.println("Native code library failed to load. " + e);
      System.exit(1);
    }
  }

  public static void main(String argv[]) {
    String animals[] = {"Cat","Dog","Cow","Goat"};
    example.print_args(animals);
    String args[] = example.get_args();
    for (int i=0; i&lt;args.length; i++)
        System.out.println(i + ":" + args[i]);
  }
}
</pre></div>

<p>
When compiled and run we get:
</p>

<div class="code"><pre>
$ java runme
argv[0] = Cat
argv[1] = Dog
argv[2] = Cow
argv[3] = Goat
0:Dave
1:Mike
2:Susan
3:John
4:Michelle
</pre></div>

<p>
In the example, a few different typemaps are used.  The "in" typemap is
used to receive an input argument and convert it to a C array.  Since dynamic
memory allocation is used to allocate memory for the array, the
"freearg" typemap is used to later release this memory after the execution of
the C function. The "out" typemap is used for function return values.
Lastly the "jni", "jtype" and "jstype" typemaps are also required to specify
what Java types to use.
</p>

<H3><a name="Java_expanding_java_object"></a>25.10.5 Expanding a Java object to multiple arguments</H3>


<p>
Suppose that you had a collection of C functions with arguments
such as the following:
</p>

<div class="code">
<pre>
int foo(int argc, char **argv);
</pre>
</div>

<p>
In the previous example, a typemap was written to pass a Java String array as the <tt>char **argv</tt>.  This
allows the function to be used from Java as follows:
</p>

<div class="code">
<pre>
example.foo(4, new String[]{"red", "green", "blue", "white"});
</pre>
</div>

<p>
Although this works, it's a little awkward to specify the argument count.  To fix this, a multi-argument
typemap can be defined.  This is not very difficult--you only have to make slight modifications to the
previous example's typemaps:
</p>

<div class="code">
<pre>
%typemap(in) (int argc, char **argv) {
    int i = 0;
    $1 = (*jenv)-&gt;GetArrayLength(jenv, $input);
    $2 = (char **) malloc(($1+1)*sizeof(char *));
    /* make a copy of each string */
    for (i = 0; i&lt;$1; i++) {
        jstring j_string = (jstring)(*jenv)-&gt;GetObjectArrayElement(jenv, $input, i);
        const char * c_string = (*jenv)-&gt;GetStringUTFChars(jenv, j_string, 0);
        $2[i] = malloc((strlen(c_string)+1)*sizeof(char));
        strcpy($2[i], c_string);
        (*jenv)-&gt;ReleaseStringUTFChars(jenv, j_string, c_string);
        (*jenv)-&gt;DeleteLocalRef(jenv, j_string);
    }
    $2[i] = 0;
}

%typemap(freearg) (int argc, char **argv) {
    int i;
    for (i=0; i&lt;$1-1; i++)
      free($2[i]);
    free($2);
}

%typemap(jni) (int argc, char **argv) "jobjectArray"
%typemap(jtype) (int argc, char **argv) "String[]"
%typemap(jstype) (int argc, char **argv) "String[]"

%typemap(javain) (int argc, char **argv) "$javainput"
</pre>
</div>

<p>
When writing a multiple-argument typemap, each of the types is referenced by a variable such 
as <tt>$1</tt> or <tt>$2</tt>.   The typemap code simply fills in the appropriate values from
the supplied Java parameter.
</p>

<p>
With the above typemap in place, you will find it no longer necessary
to supply the argument count.  This is automatically set by the typemap code.  For example:
</p>

<div class="code">
<pre>
example.foo(new String[]{"red", "green", "blue", "white"});
</pre>
</div>


<H3><a name="Java_using_typemaps_return_arguments"></a>25.10.6 Using typemaps to return arguments</H3>


<p>
A common problem in some C programs is that values may be returned in function parameters rather than in the return value of a function. 
The <tt>typemaps.i</tt> file defines INPUT, OUTPUT and INOUT typemaps which can be used to solve some instances of this problem. 
This library file uses an array as a means of moving data to and from Java when wrapping a C function that takes non const pointers or non const references as parameters.
</p>
 
<p>
Now we are going to outline an alternative approach to using arrays for C pointers. 
The INOUT typemap uses a <tt>double[]</tt> array for receiving and returning the <tt>double*</tt> parameters. 
In this approach we are able to use a Java class <tt>myDouble</tt> instead of <tt>double[]</tt> arrays where the C pointer <tt>double*</tt> is required.
</p>

<p>
Here is our example function:
</p>

<div class="code"><pre>
/* Returns a status value and two values in out1 and out2 */
int spam(double a, double b, double *out1, double *out2);
</pre></div>

<p>
If we define a structure <tt>MyDouble</tt> containing a <tt>double</tt> member variable and use some typemaps we can solve this problem. For example we could put the following through SWIG:
</p>

<div class="code"><pre>
%module example

/* Define a new structure to use instead of double * */
%inline %{
typedef struct {
    double value;
} MyDouble;
%}


%{
/* Returns a status value and two values in out1 and out2 */
int spam(double a, double b, double *out1, double *out2) {
  int status = 1;
  *out1 = a*10.0;
  *out2 = b*100.0;
  return status;
}
%}

/* 
This typemap will make any double * function parameters with name <tt>OUTVALUE</tt> take an
argument of MyDouble instead of double *. This will 
allow the calling function to read the double * value after returning from the function.
*/
%typemap(in) double *OUTVALUE {
    jclass clazz = jenv-&gt;FindClass("MyDouble");
    jfieldID fid = jenv-&gt;GetFieldID(clazz, "swigCPtr", "J");
    jlong cPtr = jenv-&gt;GetLongField($input, fid);
    MyDouble *pMyDouble = NULL;
    *(MyDouble **)&amp;pMyDouble = *(MyDouble **)&amp;cPtr;
    $1 = &amp;pMyDouble-&gt;value;
}

%typemap(jtype) double *OUTVALUE "MyDouble"
%typemap(jstype) double *OUTVALUE "MyDouble"
%typemap(jni) double *OUTVALUE "jobject"

%typemap(javain) double *OUTVALUE "$javainput"

/* Now we apply the typemap to the named variables */
%apply double *OUTVALUE { double *out1, double *out2 };
int spam(double a, double b, double *out1, double *out2);
</pre></div>

<p>
Note that the C++ JNI calling convention has been used this time and so must be compiled as C++ and the -c++ commandline must be passed to SWIG. 
JNI error checking has been omitted for clarity.
</p>

<p>
What the typemaps do are make the named <tt>double*</tt> function parameters use our new <tt>MyDouble</tt> wrapper structure. 
The "in" typemap takes this structure, gets the C++ pointer to it, takes the <tt>double value</tt> member variable and passes it to the C++ <tt>spam</tt> function. 
In Java, when the function returns, we use the SWIG created <tt>getValue()</tt> function to get the output value. 
The following Java program demonstrates this:
</p>

<div class="code"><pre>
// File: runme.java

public class runme {

  static {
    try {
      System.loadLibrary("example");
    } catch (UnsatisfiedLinkError e) {
      System.err.println("Native code library failed to load. " + e);
      System.exit(1);
    }
  }

  public static void main(String argv[]) {
    MyDouble out1 = new MyDouble();
    MyDouble out2 = new MyDouble();
    int ret = example.spam(1.2, 3.4, out1, out2);
    System.out.println(ret + "  " + out1.getValue() + "  " + out2.getValue());
  }
}
</pre></div>

<p>
When compiled and run we get:
</p>

<div class="code"><pre>
$ java runme
1 12.0  340.0
</pre></div>

<H3><a name="Java_adding_downcasts"></a>25.10.7 Adding Java downcasts to polymorphic return types</H3>


<p>
SWIG support for polymorphism works in that the appropriate virtual function is called. However, the default generated code does not allow for downcasting. 
Let's examine this with the following code:
</p>

<div class="code"><pre>
%include "std_string.i"

#include &lt;iostream&gt;
using namespace std;
class Vehicle {
public:
    virtual void start() = 0;
...
};

class Ambulance : public Vehicle {
    string vol;
public:
    Ambulance(string volume) : vol(volume) {}
    virtual void start() {
        cout &lt;&lt; "Ambulance started" &lt;&lt; endl;
    }
    void sound_siren() {
        cout &lt;&lt; vol &lt;&lt; " siren sounded!" &lt;&lt; endl;
    }
...
};

Vehicle *vehicle_factory() {
    return new Ambulance("Very loud");
}
</pre></div>

<p>
If we execute the following Java code:
</p>

<div class="code"><pre>
Vehicle vehicle = example.vehicle_factory();
vehicle.start();

Ambulance ambulance = (Ambulance)vehicle;
ambulance.sound_siren();
</pre></div>

<p>
We get:
</p>

<div class="code"><pre>
Ambulance started
java.lang.ClassCastException
        at runme.main(runme.java:16)
</pre></div>

<p>
Even though we know from examination of the C++ code that <tt>vehicle_factory</tt> returns an object of type <tt>Ambulance</tt>, 
we are not able to use this knowledge to perform the downcast in Java.
This occurs because the runtime type information is not completely passed from C++ to Java when returning the type from <tt>vehicle_factory()</tt>.
Usually this is not a problem as virtual functions do work by default, such as in the case of <tt>start()</tt>. 
There are a few solutions to getting downcasts to work.
</p>

<p>
The first is not to use a Java cast but a call to C++ to make the cast. Add this to your code:
</p>

<div class="code"><pre>
%exception Ambulance::dynamic_cast(Vehicle *vehicle) {
    $action
    if (!result) {
        jclass excep = jenv-&gt;FindClass("java/lang/ClassCastException");
        if (excep) {
            jenv-&gt;ThrowNew(excep, "dynamic_cast exception");
        }
    }
}
%extend Ambulance {
    static Ambulance *dynamic_cast(Vehicle *vehicle) {
        return dynamic_cast&lt;Ambulance *&gt;(vehicle);
    }
};
</pre></div>

<p>
It would then be used from Java like this
</p>

<div class="code"><pre>
Ambulance ambulance = Ambulance.dynamic_cast(vehicle);
ambulance.sound_siren();
</pre></div>

<p>
Should <tt>vehicle</tt> not be of type <tt>ambulance</tt> then a Java <tt>ClassCastException</tt> is thrown.
The next solution is a purer solution in that Java downcasts can be performed on the types.
Add the following before the definition of <tt>vehicle_factory</tt>:
</p>

<div class="code"><pre>
%typemap(out) Vehicle * {
    Ambulance *downcast = dynamic_cast&lt;Ambulance *&gt;($1);
    *(Ambulance **)&amp;$result = downcast;
}

%typemap(javaout) Vehicle * {
    return new Ambulance($jnicall, $owner);
  }
</pre></div>

<p>
Here we are using our knowledge that <tt>vehicle_factory</tt> always returns type <tt>Ambulance</tt> so that the Java proxy is created as a type <tt>Ambulance</tt>.
If <tt>vehicle_factory</tt> can manufacture any type of <tt>Vehicle</tt> and we want to be able to downcast using Java casts for any of these types, then a different approach is needed.
Consider expanding our example with a new Vehicle type and a more flexible factory function:
</p>

<div class="code"><pre>
class FireEngine : public Vehicle {
public:
    FireEngine() {}
    virtual void start() {
        cout &lt;&lt; "FireEngine started" &lt;&lt; endl;
    }
    void roll_out_hose() {
        cout &lt;&lt; "Hose rolled out" &lt;&lt; endl;
    }
 ...
};
Vehicle *vehicle_factory(int vehicle_number) {
    if (vehicle_number == 0)
        return new Ambulance("Very loud");
    else
        return new FireEngine();
}
</pre></div>

<p>
To be able to downcast with this sort of Java code:
</p>

<div class="code"><pre>
FireEngine fireengine = (FireEngine)example.vehicle_factory(1);
fireengine.roll_out_hose();
Ambulance ambulance = (Ambulance)example.vehicle_factory(0);
ambulance.sound_siren();
</pre></div>

<p>
the following typemaps targeted at the <tt>vehicle_factory</tt> function will achieve this. 
Note that in this case, the Java class is constructed using JNI code rather than passing a pointer across the JNI boundary in a Java long for construction in Java code.
</p>

<div class="code"><pre>
%typemap(jni) Vehicle *vehicle_factory "jobject"
%typemap(jtype) Vehicle *vehicle_factory "Vehicle"
%typemap(jstype) Vehicle *vehicle_factory "Vehicle"
%typemap(javaout) Vehicle *vehicle_factory {
    return $jnicall;
  }

%typemap(out) Vehicle *vehicle_factory {
    Ambulance *ambulance = dynamic_cast&lt;Ambulance *&gt;($1);
    FireEngine *fireengine = dynamic_cast&lt;FireEngine *&gt;($1);
    if (ambulance) {
        // call the Ambulance(long cPtr, boolean cMemoryOwn) constructor
        jclass clazz = jenv-&gt;FindClass("Ambulance");
        if (clazz) {
            jmethodID mid = jenv-&gt;GetMethodID(clazz, "&lt;init&gt;", "(JZ)V");
            if (mid) {
                jlong cptr = 0;
                *(Ambulance **)&amp;cptr = ambulance; 
                $result = jenv-&gt;NewObject(clazz, mid, cptr, false);
            }
        }
    } else if (fireengine) {
        // call the FireEngine(long cPtr, boolean cMemoryOwn) constructor
        jclass clazz = jenv-&gt;FindClass("FireEngine");
        if (clazz) {
            jmethodID mid = jenv-&gt;GetMethodID(clazz, "&lt;init&gt;", "(JZ)V");
            if (mid) {
                jlong cptr = 0;
                *(FireEngine **)&amp;cptr = fireengine; 
                $result = jenv-&gt;NewObject(clazz, mid, cptr, false);
            }
        }
    }
    else {
        cout &lt;&lt; "Unexpected type " &lt;&lt; endl;
    }

    if (!$result)
        cout &lt;&lt; "Failed to create new java object" &lt;&lt; endl;
}
</pre></div>

<p>
Better error handling would need to be added into this code. 
There are other solutions to this problem, but this last example demonstrates some more involved JNI code.
SWIG usually generates code which constructs the proxy classes using Java code as it is easier to handle error conditions and is faster. 
Note that the JNI code above uses a number of string lookups to call a constructor, whereas this would not occur using byte compiled Java code.
</p>

<H3><a name="Java_adding_equals_method"></a>25.10.8 Adding an equals method to the Java classes</H3>


<p>
When a pointer is returned from a JNI function, it is wrapped using a new Java proxy class or type wrapper class. 
Even when the pointers are the same, it will not be possible to know that the two Java classes containing those pointers are actually the same object.
It is common in Java to use the <tt>equals()</tt> method to check whether two objects are equivalent.
The <tt>equals()</tt> method is usually accompanied by a <tt>hashCode()</tt> method in order to fulfill
the requirement that the hash code is equal for equal objects.
Pure Java code methods like these can be easily added:
</p>

<div class="code">
<pre>
%typemap(javacode) SWIGTYPE %{
  public boolean equals(Object obj) {
    boolean equal = false;
    if (obj instanceof $javaclassname)
      equal = ((($javaclassname)obj).swigCPtr == this.swigCPtr);
    return equal;
  }
  public int hashCode() {
     return (int)getPointer();
  }
%}

class Foo { };
Foo* returnFoo(Foo *foo) { return foo; }
</pre>
</div>

<p>
The following would display <tt>false</tt> without the <tt>javacode</tt> typemap above. With the typemap defining the <tt>equals</tt> method the result is <tt>true</tt>.
</p>

<div class="code">
<pre>
Foo foo1 = new Foo();
Foo foo2 = example.returnFoo(foo1);
System.out.println("foo1? " + foo1.equals(foo2));
</pre>
</div>


<H3><a name="Java_void_pointers"></a>25.10.9 Void pointers and a common Java base class</H3>


<p>
One might wonder why the common code that SWIG emits for the proxy and type wrapper classes is not pushed into a base class. 
The reason is that although <tt>swigCPtr</tt> could be put into a common base class for all classes 
wrapping C structures, it would not work for C++ classes involved in an inheritance chain.
Each class derived from a base needs a separate <tt>swigCPtr</tt> because C++ compilers sometimes use a different pointer value when casting a derived class to a base.
Additionally as Java only supports single inheritance, it would not be possible to derive wrapped classes from your own pure Java classes if the base class has been 'used up' by SWIG.
However, you may want to move some of the common code into a base class. 
Here is an example which uses a common base class for all proxy classes and type wrapper classes:
</p>

<div class="code">
<pre>
%typemap(javabase) SWIGTYPE, SWIGTYPE *, SWIGTYPE &amp;, SWIGTYPE [], 
                                                         SWIGTYPE (CLASS::*) "SWIG"

%typemap(javacode) SWIGTYPE, SWIGTYPE *, SWIGTYPE &amp;, SWIGTYPE [], 
                                                         SWIGTYPE (CLASS::*) %{
  protected long getPointer() {
    return swigCPtr;
  }
%}
</pre>
</div>

<p>
Define new base class called SWIG:
</p>

<div class="code">
<pre>
public abstract class SWIG {
  protected abstract long getPointer();

  public boolean equals(Object obj) {
    boolean equal = false;
    if (obj instanceof SWIG)
      equal = (((SWIG)obj).getPointer() == this.getPointer());
    return equal;
  }
  
  SWIGTYPE_p_void getVoidPointer() {
    return new SWIGTYPE_p_void(getPointer(), false);
  }
}
</pre>
</div>

<p>
This example contains some useful functionality which you may want in your code. 
</p>

<ul>
    <li> It has an <tt>equals()</tt> method. Unlike the previous example, the method code isn't replicated in all classes.
    <li> It also has a function which effectively implements a cast from the type of the proxy/type wrapper class to a void pointer. This is necessary for passing a proxy class or a type wrapper class to a function that takes a void pointer.
</ul>

<H3><a name="Java_struct_pointer_pointer"></a>25.10.10 Struct pointer to pointer</H3>


<p>
Pointers to pointers are often used as output parameters in C factory type functions.
These are a bit more tricky to handle.
Consider the following situation where a <tt>Butler</tt> can be hired and fired:
</p>

<div class="code">
<pre>
typedef struct {
  int hoursAvailable;
  char *greeting;
} Butler;

// Note: HireButler will allocate the memory 
// The caller must free the memory by calling FireButler()!!
extern int HireButler(Butler **ppButler);
extern void FireButler(Butler *pButler);
</pre>
</div>

<p>
C code implementation:
</p>

<div class="code">
<pre>
int HireButler(Butler **ppButler) {
  Butler *pButler = (Butler *)malloc(sizeof(Butler));
  pButler-&gt;hoursAvailable = 24;
  pButler-&gt;greeting = (char *)malloc(32);
  strcpy(pButler-&gt;greeting, "At your service Sir");
  *ppButler = pButler;
  return 1;
}
void FireButler(Butler *pButler) {
  free(pButler-&gt;greeting);
  free(pButler);
}
</pre>
</div>

<p>
Let's take two approaches to wrapping this code.
The first is to provide a functional interface, much like the original C interface.
The following Java code shows how we intend the code to be used:
</p>

<div class="code">
<pre>
    Butler jeeves = new Butler();
    example.HireButler(jeeves);
    System.out.println("Greeting:     " + jeeves.getGreeting());
    System.out.println("Availability: " + jeeves.getHoursAvailable() + " hours per day");
    example.FireButler(jeeves);
</pre>
</div>

<p>
Resulting in the following output when run:
</p>

<div class="shell">
<pre>
Greeting:     At your service Sir
Availability: 24 hours per day
</pre>
</div>

<p>
Note the usage is very much like it would be used if we were writing C code, that is, explicit memory management is needed.
No C memory is allocated in the construction of the <tt>Butler</tt> proxy class and 
the proxy class will not destroy the underlying C memory when it is collected.
A number of typemaps and features are needed to implement this approach. 
The following interface file code should be placed before SWIG parses the above C code.
</p>

<div class="code">
<pre>
%module example

// Do not generate the default proxy constructor or destructor
%nodefaultctor Butler;
%nodefaultdtor Butler;

// Add in pure Java code proxy constructor
%typemap(javacode) Butler %{
  /** This constructor creates the proxy which initially does not create nor own any C memory */
  public Butler() {
    this(0, false);
  }
%}

// Type typemaps for marshalling Butler **
%typemap(jni) Butler ** "jobject"
%typemap(jtype) Butler ** "Butler"
%typemap(jstype) Butler ** "Butler"

// Typemaps for Butler ** as a parameter output type
%typemap(in) Butler ** (Butler *ppButler = 0) %{
  $1 = &amp;ppButler;
%}
%typemap(argout) Butler ** {
  // Give Java proxy the C pointer (of newly created object)
  jclass clazz = (*jenv)-&gt;FindClass(jenv, "Butler");
  jfieldID fid = (*jenv)-&gt;GetFieldID(jenv, clazz, "swigCPtr", "J");
  jlong cPtr = 0;
  *(Butler **)&amp;cPtr = *$1;
  (*jenv)-&gt;SetLongField(jenv, $input, fid, cPtr);
}
%typemap(javain) Butler ** "$javainput"
</pre>
</div>

<p>
Note that the JNI code sets the proxy's <tt>swigCPtr</tt> member variable to point to the newly created object.
The <tt>swigCMemOwn</tt> remains unchanged (at false), so that the proxy does not own the memory.
</p>

<p>
Note: The old %nodefault directive disabled the default constructor
and destructor at the same time. This is unsafe in most of the cases,
and you can use the explicit %nodefaultctor and %nodefaultdtor
directives to achieve the same result if needed.
</p>

<p>
The second approach offers a more object oriented interface to the Java user.
We do this by making the Java proxy class's
constructor call the <tt>HireButler()</tt> method to create the underlying C object.
Additionally we get the proxy to take ownership of the memory so that the
finalizer will call the <tt>FireButler()</tt> function.
The proxy class will thus take ownership of the memory and clean it up when no longer needed.
We will also prevent the user from being able to explicitly call the <tt>HireButler()</tt> and <tt>FireButler()</tt> functions.
Usage from Java will simply be:
</p>

<div class="code">
<pre>
Butler jeeves = new Butler();
System.out.println("Greeting:     " + jeeves.getGreeting());
System.out.println("Availability: " + jeeves.getHoursAvailable() + " hours per day");
</pre>
</div>

<p>
Note that the Butler class is used just like any other Java class and no extra coding by the user needs to be written to 
clear up the underlying C memory as the finalizer will be called by the garbage collector which in turn will call the <tt>FireButler()</tt> function.
To implement this, we use the above interface file code but remove the <tt>javacode</tt> typemap and add the following:
</p>

<div class="code">
<pre>
// Don't expose the memory allocation/de-allocation functions
%ignore FireButler(Butler *pButler);
%ignore HireButler(Butler **ppButler);

// Add in a custom proxy constructor and destructor
%extend Butler {
  Butler() {
    Butler *pButler = 0;
    HireButler(&amp;pButler);
    return pButler;
  }
  ~Butler() {
     FireButler($self);
   }
}
</pre>
</div>

<p>
Note that the code in <tt>%extend</tt> is using a C++ type constructor and destructor, yet the generated code will still compile as C code,
see <a href="SWIG.html#SWIG_adding_member_functions">Adding member functions to C structures</a>.
The C functional interface has been completely morphed into an object-oriented interface and
the Butler class would behave much like any pure Java class and feel more natural to Java users.
</p>

<H3><a name="Java_memory_management_member_variables"></a>25.10.11 Memory management when returning references to member variables</H3>


<p>
This example shows how to prevent premature garbage collection of objects when the underlying C++ class returns a pointer or reference to a member variable.
</p>

<p>
Consider the following C++ code:
</p>

<div class="code">
<pre>
struct Wheel {
  int size;
  Wheel(int sz) : size(sz) {}
};

class Bike {
  Wheel wheel;
public:
  Bike(int val) : wheel(val) {}
  Wheel&amp; getWheel() { return wheel; }
};
</pre>
</div>

<p>
and the following usage from Java after running the code through SWIG:
</p>


<div class="code">
<pre>
    Wheel wheel = new Bike(10).getWheel();
    System.out.println("wheel size: " + wheel.getSize());
    // Simulate a garbage collection
    System.gc();
    System.runFinalization();
    System.out.println("wheel size: " + wheel.getSize());
</pre>
</div>

<p>
Don't be surprised that if the resulting output gives strange results such as...
</p>

<div class="shell">
<pre>
wheel size: 10
wheel size: 135019664
</pre>
</div>

<p>
What has happened here is the garbage collector has collected the <tt>Bike</tt> instance as it doesn't think it is needed any more.
The proxy instance, <tt>wheel</tt>, contains a reference to memory that was deleted when the <tt>Bike</tt> instance was collected.
In order to prevent the garbage collector from collecting the <tt>Bike</tt> instance a reference to the <tt>Bike</tt> must
be added to the <tt>wheel</tt> instance. You can do this by adding the reference when the <tt>getWheel()</tt> method
is called using the following typemaps.
</p>


<div class="code">
<pre>
%typemap(javacode) Wheel %{
  // Ensure that the GC doesn't collect any Bike instance set from Java
  private Bike bikeReference;
  protected void addReference(Bike bike) {
    bikeReference = bike;
  }
%}

// Add a Java reference to prevent premature garbage collection and resulting use
// of dangling C++ pointer. Intended for methods that return pointers or
// references to a member variable.
%typemap(javaout) Wheel&amp; getWheel {
    long cPtr = $jnicall;
    $javaclassname ret = null;
    if (cPtr != 0) {
      ret = new $javaclassname(cPtr, $owner);
      ret.addReference(this);
    }
    return ret;
  }
</pre>
</div>

<p>
The code in the first typemap gets added to the <tt>Wheel</tt> proxy class.
The code in the second typemap constitutes the bulk of the code in the generated <tt>getWheel()</tt> function:
</p>

<div class="code">
<pre>
public class Wheel {
  ...
  // Ensure that the GC doesn't collect any bike set from Java 
  private Bike bikeReference;
  protected void addReference(Bike bike) {
    bikeReference = bike;
  }
}

public class Bike {
  ...
  public Wheel getWheel() {
    long cPtr = exampleJNI.Bike_getWheel(swigCPtr, this);
    Wheel ret = null;
    if (cPtr != 0) {
      ret = new Wheel(cPtr, false);
      ret.addReference(this);
    }
    return ret;
  }
}
</pre>
</div>

<p>
Note the <tt>addReference</tt> call.
</p>

<H3><a name="Java_memory_management_objects"></a>25.10.12 Memory management for objects passed to the C++ layer</H3>


<p>
Managing memory can be tricky when using C++ and Java proxy classes.
The previous example shows one such case and this example looks at memory management for a class passed to a C++ method which expects the object to remain in scope
after the function has returned. Consider the following two C++ classes:
</p>

<div class="code">
<pre>
struct Element {
  int value;
  Element(int val) : value(val) {}
};
class Container {
  Element* element;
public:
  Container() : element(0) {}
  void setElement(Element* e) { element = e; }
  Element* getElement() { return element; }
};
</pre>
</div>

<p>
and usage from C++
</p>

<div class="code">
<pre>
    Container container;
    Element element(20);
    container.setElement(&amp;element);
    cout &lt;&lt; "element.value: " &lt;&lt; container.getElement()-&gt;value &lt;&lt; endl;
</pre>
</div>

<p>
and more or less equivalent usage from Java
</p>

<div class="code">
<pre>
    Container container = new Container();
    container.setElement(new Element(20));
    System.out.println("element value: " + container.getElement().getValue());
</pre>
</div>

<p>
The C++ code will always print out 20, but the value printed out may not be this in the Java equivalent code.
In order to understand why, consider a garbage collection occuring...
</p>

<div class="code">
<pre>
    Container container = new Container();
    container.setElement(new Element(20));
    // Simulate a garbage collection
    System.gc();
    System.runFinalization();
    System.out.println("element value: " + container.getElement().getValue());
</pre>
</div>

<p>
The temporary element created with <tt>new Element(20)</tt> could get garbage collected
which ultimately means the <tt>container</tt> variable is holding a dangling pointer, thereby printing out any old random value instead of the expected value of 20.
One solution is to add in the appropriate references in the Java layer...
</p>

<div class="code">
<pre>
public class Container {

  ...

  // Ensure that the GC doesn't collect any Element set from Java
  // as the underlying C++ class stores a shallow copy
  private Element elementReference;
  private long getCPtrAndAddReference(Element element) {
    elementReference = element;
    return Element.getCPtr(element);
  }

  public void setElement(Element e) {
    exampleJNI.Container_setElement(swigCPtr, this, getCPtrAndAddReference(e), e);
  }
}
</pre>
</div>

<p>
The following typemaps will generate the desired code.
The 'javain' typemap matches the input parameter type for the <tt>setElement</tt> method.
The 'javacode' typemap simply adds in the specified code into the Java proxy class.
</p>

<div class="code">
<pre>
%typemap(javain) Element *e "getCPtrAndAddReference($javainput)"

%typemap(javacode) Container %{
  // Ensure that the GC doesn't collect any element set from Java
  // as the underlying C++ class stores a shallow copy
  private Element elementReference;
  private long getCPtrAndAddReference(Element element) {
    elementReference = element;
    return Element.getCPtr(element);
  }
%}
</pre>
</div>


<H3><a name="Java_date_marshalling"></a>25.10.13 Date marshalling using the javain typemap and associated attributes</H3>


<p>
The <a href="#Java_nan_exception_typemap">NaN Exception example</a> is a simple example of the "javain" typemap and its 'pre' attribute.
This example demonstrates how a C++ date class, say <tt>CDate</tt>, can be mapped onto the standard Java date class,
<tt>java.util.GregorianCalendar</tt> by using the 'pre', 'post' and 'pgcppname' attributes of the "javain" typemap.
The idea is that the <tt>GregorianCalendar</tt> is used wherever the C++ API uses a <tt>CDate</tt>.
Let's assume the code being wrapped is as follows:
</p>

<div class="code">
<pre>
class CDate {
public:
  CDate(int year, int month, int day);
  int getYear();
  int getMonth();
  int getDay();
  ...
};
struct Action {
  static int doSomething(const CDate &amp;dateIn, CDate &amp;dateOut);
  Action(const CDate &amp;date, CDate &amp;dateOut);
};
</pre>
</div>

<p>
Note that <tt>dateIn</tt> is const and therefore read only and <tt>dateOut</tt> is a non-const output type.
</p>

<p>
First let's look at the code that is generated by default, where the Java proxy class <tt>CDate</tt> is used in the proxy interface:
</p>

<div class="code">
<pre>
public class Action {
  ...
  public static int doSomething(CDate dateIn, CDate dateOut) {
    return exampleJNI.Action_doSomething(CDate.getCPtr(dateIn), dateIn, 
                                         CDate.getCPtr(dateOut), dateOut);
  }

  public Action(CDate date, CDate dateOut) {
    this(exampleJNI.new_Action(CDate.getCPtr(date), date, 
                               CDate.getCPtr(dateOut), dateOut), true);
  }
}
</pre>
</div>

<p>
The <tt>CDate &amp;</tt> and <tt>const CDate &amp;</tt> Java code is generated from the following two default typemaps:
</p>

<div class="code">
<pre>
%typemap(jstype) SWIGTYPE &amp; "$javaclassname"
%typemap(javain) SWIGTYPE &amp; "$javaclassname.getCPtr($javainput)"
</pre>
</div>

<p>
where '$javaclassname' is translated into the proxy class name, <tt>CDate</tt> and '$javainput' is translated into the name of the parameter, eg <tt>dateIn</tt>.
From Java, the intention is then to call into a modifed API with something like:
</p>

<div class="code">
<pre>
java.util.GregorianCalendar calendarIn = 
    new java.util.GregorianCalendar(2011, java.util.Calendar.APRIL, 13, 0, 0, 0);
java.util.GregorianCalendar calendarOut = new java.util.GregorianCalendar();

// Note in calls below, calendarIn remains unchanged and calendarOut 
// is set to a new value by the C++ call
Action.doSomething(calendarIn, calendarOut);
Action action = new Action(calendarIn, calendarOut);
</pre>
</div>

<p>
To achieve this mapping, we need to alter the default code generation slightly so that at the Java layer, 
a <tt>GregorianCalendar</tt> is converted into a <tt>CDate</tt>. 
The JNI intermediary layer will still take a pointer to the underlying <tt>CDate</tt> class.
The typemaps to achieve this are shown below.
</p>

<div class="code">
<pre>
%typemap(jstype) const CDate&amp; "java.util.GregorianCalendar"
%typemap(javain, 
         pre="    CDate temp$javainput = new CDate($javainput.get(java.util.Calendar.YEAR), "
             "$javainput.get(java.util.Calendar.MONTH), $javainput.get(java.util.Calendar.DATE));", 
         pgcppname="temp$javainput") const CDate &amp;
         "$javaclassname.getCPtr(temp$javainput)"

%typemap(jstype) CDate&amp; "java.util.Calendar"
%typemap(javain, 
         pre="    CDate temp$javainput = new CDate($javainput.get(java.util.Calendar.YEAR), "
             "$javainput.get(java.util.Calendar.MONTH), $javainput.get(java.util.Calendar.DATE));", 
         post="      $javainput.set(temp$javainput.getYear(), temp$javainput.getMonth(), "
              "temp$javainput.getDay(), 0, 0, 0);", 
         pgcppname="temp$javainput") CDate &amp;
         "$javaclassname.getCPtr(temp$javainput)"
</pre>
</div>

<p>
The resulting generated proxy code in the <tt>Action</tt> class follows:
 </p>

<div class="code">
<pre>
public class Action {
  ...
  public static int doSomething(java.util.GregorianCalendar dateIn, 
                                java.util.Calendar dateOut) {
    CDate tempdateIn = new CDate(dateIn.get(java.util.Calendar.YEAR), 
                                 dateIn.get(java.util.Calendar.MONTH), 
                                 dateIn.get(java.util.Calendar.DATE));
    CDate tempdateOut = new CDate(dateOut.get(java.util.Calendar.YEAR), 
                                  dateOut.get(java.util.Calendar.MONTH), 
                                  dateOut.get(java.util.Calendar.DATE));
    try {
      return exampleJNI.Action_doSomething(CDate.getCPtr(tempdateIn), tempdateIn, 
                                           CDate.getCPtr(tempdateOut), tempdateOut);
    } finally {
      dateOut.set(tempdateOut.getYear(), tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
    }
  }

  static private long SwigConstructAction(java.util.GregorianCalendar date, 
                                          java.util.Calendar dateOut) {
    CDate tempdate = new CDate(date.get(java.util.Calendar.YEAR), 
                               date.get(java.util.Calendar.MONTH), 
                               date.get(java.util.Calendar.DATE));
    CDate tempdateOut = new CDate(dateOut.get(java.util.Calendar.YEAR), 
                                  dateOut.get(java.util.Calendar.MONTH), 
                                  dateOut.get(java.util.Calendar.DATE));
    try {
      return exampleJNI.new_Action(CDate.getCPtr(tempdate), tempdate, 
                                   CDate.getCPtr(tempdateOut), tempdateOut);
    } finally {
      dateOut.set(tempdateOut.getYear(), tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
    }
  }

  public Action(java.util.GregorianCalendar date, java.util.Calendar dateOut) {
    this(Action.SwigConstructAction(date, dateOut), true);
  }
}
</pre>
</div>

<p>
A few things to note:
</p>
<ul>
  <li> The "javatype" typemap has changed the parameter type to <tt>java.util.GregorianCalendar</tt> or <tt>java.util.Calendar</tt> instead of the default generated <tt>CDate</tt> proxy.
  <li> The code in the 'pre' attribute appears before the JNI call (<tt>exampleJNI.new_Action</tt> / <tt>exampleJNI.Action_doSomething</tt>).
  <li> The code in the 'post' attribute appears after the JNI call.
  <li> A try .. finally block is generated with the JNI call in the try block and 'post' code in the finally block.
  The alternative of just using a temporary variable for the return value from the JNI call and the 'post' code being generated before the
  return statement is not possible given that the JNI call is in one line and comes from the "javaout" typemap.
  <li> The temporary variables in the "javain" typemaps are called <tt>temp$javain</tt>, where "$javain" is replaced with the parameter name.
  "$javain" is used to mangle the variable name so that more than one <tt>CDate &amp;</tt> type can be used as a parameter in a method, otherwise two or 
  more local variables with the same name would be generated.
  <li> The use of the "javain" typemap causes a constructor helper function (<tt>SwigConstructAction</tt>) to be generated.
  This allows Java code to be called before the JNI call and is required as the Java compiler won't compile code inserted before the 'this' call.
  <li> The 'pgcppname' attribute is used to modify the object being passed as the <a href="#Java_pgcpp">premature garbage collection prevention parameter</a> (the 2nd and 4th parameters in the JNI calls).
</ul>


<H2><a name="Java_directors_faq"></a>25.11 Living with Java Directors</H2>


<p>
  This section is intended to address frequently asked questions and frequently encountered problems when using Java directors.
</p>

<ol>
  <li><i>When my program starts up, it complains that </i>method_foo<i> cannot
  be found in a Java method called </i>swig_module_init<i>. How do I fix
  this?</i>

  <p>
  Open up the C++ wrapper source code file and look for <code>"method_foo"</code> (include the double quotes, they are important!)
  Look at the JNI field descriptor and make sure that each class that occurs in the descriptor has the correct package name in front of it.
  If the package name is incorrect, put a "javapackage" typemap in your SWIG interface file.
  </p>
  </li>

  <li><i>I'm compiling my code and I'm using templates. I provided a
  javapackage typemap, but SWIG doesn't generate the right JNI field
  descriptor.</i>
  <p>
  Use the template's renamed name as the argument to the "javapackage" typemap:
  </p>
<div class="code">
<pre>
%typemap(javapackage)  std::vector&lt;int&gt;  "your.package.here"
%template(VectorOfInt) std::vector&lt;int&gt;;
</pre>
</div>
  </li>

  <li><p><i>When I pass class pointers or references through a C++ upcall and I
  try to type cast them, Java complains with a ClassCastException. What am I
  doing wrong?</i></p>
  <p>
  Normally, a non-director generated Java proxy class creates temporary Java objects as follows:
  </p>
<div class="code">
<pre>
public static void MyClass_method_upcall(MyClass self, long jarg1)
{
  Foo darg1 = new Foo(jarg1, false);

  self.method_upcall(darg1);
}
</pre>
</div>
  <p>Unfortunately, this loses the Java type information that is part of the underlying Foo director proxy class's Java object pointer causing the type cast to fail.
  The SWIG Java module's director code attempts to correct the problem, <b>but only for director-enabled classes</b>, since the director class retains a global reference to its Java object.
  Thus, for director-enabled classes <b>and only for director-enabled classes</b>, the generated proxy Java code looks something like:
  </p>

<div class="code">
<pre>
public static void MyClass_method_upcall(MyClass self, long jarg1,
                                         Foo jarg1_object)
{
  Foo darg1 = (jarg1_object != null ? jarg1_object : new Foo(jarg1, false));

  self.method_upcall(darg1);
}
</pre>
</div>

  <p>
  When you import a SWIG interface file containing class definitions, the classes you want to be director-enabled must be have the <code>feature("director")</code> enabled for type symmetry to work.
  This applies even when the class being wrapped isn't a director-enabled class but takes parameters that are director-enabled classes.
  </p>

  <p>
  The current "type symmetry" design will work for simple C++ inheritance, but will most likely fail for anything more complicated such as tree or diamond C++ inheritance hierarchies.
  Those who are interested in challenging problems are more than welcome to hack the <code>Java::Java_director_declaration</code> method in <code>Source/Modules/java.cxx</code>.
  </p>
  <p>
  If all else fails, you can use the downcastXXXXX() method to attempt to recover the director class's Java object pointer.
  For the Java Foo proxy class, the Foo director class's java object pointer can be accessed through the javaObjectFoo() method.
  The generated method's signature is:
  </p>

<div class="code">
<pre>
  public static Foo javaObjectFoo(Foo obj);
</pre>
</div>

<p>
  From your code, this method is invoked as follows:
</p>

<div class="code">
<pre>
public class MyClassDerived {
  public void method_upcall(Foo foo_object)
  {
    FooDerived    derived = (foo_object != null ?
                 (FooDerived) Foo.downcastFoo(foo_object) : null);
    /* rest of your code here */
  }
}
</pre>
</div>

<p>
  An good approach for managing downcasting is placing a static method in each derived class that performs the downcast from the superclass, e.g.,
</p>

<div class="code">
<pre>
public class FooDerived extends Foo {
  /* ... */
  public static FooDerived downcastFooDerived(Foo foo_object)
  {
    try {
     return (foo_object != null ? (FooDerived) Foo.downcastFoo(foo_object);
    }

    catch (ClassCastException exc) {
      // Wasn't a FooDerived object, some other subclass of Foo
      return null;
    }
  }
}
</pre>
</div>

<p>
  Then change the code in MyClassDerived as follows:
</p>

<div class="code">
<pre>
public class MyClassDerived extends MyClass {
  /* ... */
  public void method_upcall(Foo foo_object)
  {
    FooDerived    derived = FooDerived.downcastFooDerived(foo_object);
    /* rest of your code here */
  }
}
</pre>
</div>
  </li>

  <li><p><i>Why isn't the proxy class declared abstract? Why aren't the director
  upcall methods in the proxy class declared abstract?</i></p>

  <p>
  Declaring the proxy class and its methods abstract would break the JNI argument marshalling and SWIG's downcall functionality (going from Java to C++.)
  Create an abstract Java subclass that inherits from the director-enabled class instead.
  Using the previous Foo class example:
  </p>

<div class="code">
<pre>
public abstract class UserVisibleFoo extends Foo {
  /** Make sure user overrides this method, it's where the upcall
   * happens.
   */
  public abstract void method_upcall(Foo foo_object);

  /// Downcast from Foo to UserVisibleFoo
  public static UserVisibleFoo downcastUserVisibleFoo(Foo foo_object)
  {
    try {
     return (foo_object != null ? (FooDerived) Foo.downcastFoo(foo_object) : null);
    }

    catch (ClassCastException exc) {
      // Wasn't a FooDerived object, some other subclass of Foo
      return null;
    }
  }
}
</pre>
</div>
  <p>This doesn't prevent the user from creating subclasses derived from Foo, however, UserVisibleFoo provides the safety net that reminds the user to override the <code>method_upcall()</code> method.</p>
  </li>
</ol>

<H2><a name="Java_odds_ends"></a>25.12 Odds and ends</H2>


<H3><a name="Java_javadoc_comments"></a>25.12.1 JavaDoc comments</H3>


<p>
The SWIG documentation system is currently deprecated. 
When it is resurrected JavaDoc comments will be fully supported. 
If you can't wait for the full documentation system a couple of workarounds are available. 
The <tt>%javamethodmodifiers</tt> feature can be used for adding proxy class method comments and module class method comments. 
The "javaimports" typemap can be hijacked for adding in proxy class JavaDoc comments. 
The <tt>jniclassimports</tt> or <tt>jniclassclassmodifiers</tt> pragmas can also be used for adding intermediary JNI class comments and likewise the <tt>moduleimports</tt> or <tt>moduleclassmodifiers</tt> pragmas for the module class. 
Here is an example adding in a proxy class and method comment:
</p>

<div class="code">
<pre>
%javamethodmodifiers Barmy::lose_marbles() "
  /**
    * Calling this method will make you mad.
    * Use with &lt;b&gt;utmost&lt;/b&gt; caution. 
    */
  public";

%typemap(javaimports) Barmy "
/** The crazy class. Use as a last resort. */"

class Barmy {
public:
  void lose_marbles() {}
};
</pre>
</div>

<p>
Note the "public" added at the end of the <tt>%javamethodmodifiers</tt> as this is the default for this feature. 
The generated proxy class with JavaDoc comments is then as follows:
</p>

<div class="code">
<pre>
/** The crazy class. Use as a last resort. */
public class Barmy {
...
  /**
    * Calling this method will make you mad.
    * Use with &lt;b&gt;utmost&lt;/b&gt; caution. 
    */
  public void lose_marbles() {
    ...
  }
...
}
</pre>
</div>


<H3><a name="Java_functional_interface"></a>25.12.2 Functional interface without proxy classes</H3>


<p>
It is possible to run SWIG in a mode that does not produce proxy classes by using the -noproxy commandline option.
The interface is rather primitive when wrapping structures or classes and is accessed through function calls to the module class.
All the functions in the module class are wrapped by functions with identical names as those in the intermediary JNI class.
</p>

<p>
Consider the example we looked at when examining proxy classes:
</p>

<div class="code">
<pre>
class Foo {
public:
     int x;
     int spam(int num, Foo* foo);
};
</pre>
</div>

<p>
When using <tt>-noproxy</tt>, type wrapper classes are generated instead of proxy classes.
Access to all the functions and variables is through a C like set of functions where the first parameter passed is the pointer to the class, that is an instance of a type wrapper class.
Here is what the module class looks like:
</p>

<div class="code">
<pre>
public class example {
  public static void Foo_x_get(SWIGTYPE_p_Foo self, int x) {...}
  public static int Foo_x_get(SWIGTYPE_p_Foo self) {...}
  public static int Foo_spam(SWIGTYPE_p_Foo self, int num, SWIGTYPE_p_Foo foo) {...}
  public static SWIGTYPE_p_Foo new_Foo() {...}
  public static void delete_Foo(SWIGTYPE_p_Foo self) {...}
}
</pre>
</div>

<p>
This approach is not nearly as natural as using proxy classes as the functions need to be used like this:
</p>

<div class="code">
<pre>
SWIGTYPE_p_Foo foo = example.new_Foo();
example.Foo_x_set(foo, 10);
int var = example.Foo_x_get(foo);
example.Foo_spam(foo, 20, foo);
example.delete_Foo(foo);
</pre>
</div>

<p>
Unlike proxy classes, there is no attempt at tracking memory.
All destructors have to be called manually for example the <tt>delete_Foo(foo)</tt> call above.
</p>


<H3><a name="Java_using_own_jni_functions"></a>25.12.3 Using your own JNI functions</H3>


<p>
You may have some hand written JNI functions that you want to use in addition to the SWIG generated JNI functions.
Adding these to your SWIG generated package is possible using the <tt>%native</tt> directive.
If you don't want SWIG to wrap your JNI function then of course you can simply use the <tt>%ignore</tt> directive.
However, if you want SWIG to generate just the Java code for a JNI function then use the <tt>%native</tt> directive.
The C types for the parameters and return type must be specified in place of the JNI types and the function name must be the native method name.
For example:
</p>

<div class="code"><pre>
%native (HandRolled) void HandRolled(int, char *);
%{
JNIEXPORT void JNICALL Java_packageName_moduleName_HandRolled(JNIEnv *, jclass,
                                                              jlong, jstring);
%}
</pre></div>

<p>
No C JNI function will be generated and the <tt>Java_packageName_moduleName_HandRolled</tt> function will be accessible using the SWIG generated Java native method call in the intermediary JNI class which will look like this:
</p>

<div class="code"><pre>
  public final static native void HandRolled(int jarg1, String jarg2);
</pre></div>

<p>
and as usual this function is wrapped by another which for a global C function would appear in the module class:
</p>

<div class="code"><pre>
  public static void HandRolled(int arg0, String arg1) {
    exampleJNI.HandRolled(arg0, arg1);
  }
</pre></div>

<p>
The <tt>packageName</tt> and <tt>moduleName</tt> must of course be correct else you will get linker errors when the JVM dynamically loads the JNI function.
You may have to add in some "jtype", "jstype", "javain" and "javaout" typemaps when wrapping some JNI types.
Here the default typemaps work for <tt>int</tt> and <tt>char *</tt>.
</p>

<p>
In summary the <tt>%native</tt> directive is telling SWIG to generate the Java code to access the JNI C code, but not the JNI C function itself.
This directive is only really useful if you want to mix your own hand crafted JNI code and the SWIG generated code into one Java class or package.
</p>


<H3><a name="Java_performance"></a>25.12.4 Performance concerns and hints</H3>


<p>
If you're directly manipulating huge arrays of complex objects from Java, performance may suffer greatly when using the array functions in <tt>arrays_java.i</tt>.
Try and minimise the expensive JNI calls to C/C++ functions, perhaps by using temporary Java variables instead of accessing the information directly from the C/C++ object.
</p>

<p>
Java classes without any finalizers generally speed up code execution as there is less for the garbage collector to do. Finalizer generation can be stopped by using an empty <tt>javafinalize</tt> typemap: 
</p>

<div class="code"><pre>
%typemap(javafinalize) SWIGTYPE ""
</pre></div>

<p>
However, you will have to be careful about memory management and make sure that you code in a call to the <tt>delete()</tt> member function. 
This method normally calls the C++ destructor or <tt>free()</tt> for C code.
</p>

<H3><a name="Java_debugging"></a>25.12.5 Debugging</H3>


<p>
The generated code can be debugged using both a Java debugger and a C++ debugger using the usual debugging techniques.
Breakpoints can be set in either Java or C++ code and so both can be debugged simultaneously.
Most debuggers do not understand both Java and C++, with one noteable exception of Sun Studio, 
where it is possible to step from Java code into a JNI method within one environment.
</p>

<p>
Alternatively, debugging can involve placing debug printout statements in the JNI layer using the <tt>%exception</tt> directive.
See the <a href="Customization.html#Customization_exception_special_variables">special variables for %exception</a> section.
Many of the default typemaps can also be overridden and modified for adding in extra logging/debug display information.
</p>

<p>
The <tt>-Xcheck:jni</tt> and <tt>-Xcheck:nabounds</tt> Java executable options are useful for debugging to make sure the JNI code is behaving.
The -verbose:jni and -verbose:gc are also useful options for monitoring code behaviour.
</p>


<H2><a name="Java_examples"></a>25.13 Java Examples</H2>


<p>
The directory Examples/java has a number of further examples. 
Take a look at these if you want to see some of the techniques described in action.
The Examples/index.html file in the parent directory contains the SWIG Examples Documentation and is a useful starting point. 
If your SWIG installation went well Unix users should be able to type <tt>make</tt> in each example directory, then <tt>java main</tt> to see them running.
For the benefit of Windows users, there are also Visual C++ project files in a couple of the <a href="Windows.html#Windows_examples">Windows Examples</a>.
There are also many regression tests in the Examples/test-suite directory.
Many of these have runtime tests in the java subdirectory.
</p>

</body>
</html>