# 15 SWIG and Java

- Overview
- Preliminaries
  - Running SWIG
  - Additional Commandline Options
  - Getting the right header files
  - Compiling a dynamic module
  - Using your module
  - Dynamic linking problems
  - Compilation problems and compiling with C++
  - Building on Windows
    - Running SWIG from Visual Studio
    - Using NMAKE
- A tour of basic C/C++ wrapping
  - Modules, packages and generated Java classes
  - Functions
  - Global variables
  - Constants
  - Enumerations
  - Pointers
  - Structures
  - C++ classes
  - C++ inheritance
  - Pointers, references, arrays and pass by value
    - Null pointers
  - C++ overloaded functions
  - C++ namespaces
  - C++ templates
  - C++ Smart Pointers
- Further details on the generated Java classes
  - The intermediary JNI class
    - The intermediary JNI class pragmas
  - The Java module class
    - The Java module class pragmas
  - Java proxy classes
    - Memory management
    - Inheritance
    - Proxy classes and garbage collection
  - Type wrapper classes
- Common customization features
  - C/C++ helper functions
  - Class extension with %extend
  - Exception handling with %exception
  - Method access with %javamethodmodifiers
- Tips and techniques
  - Input and output parameters using primitive pointers and references
  - Simple pointers
  - Wrapping C arrays with Java arrays
  - Unbounded C Arrays
- Java typemaps
  - Default primitive type mappings
  - Sixty four bit JVMs
  - What is a typemap?
  - Typemaps for mapping C/C++ types to Java types
  - Java special variables
  - Typemaps for both C and C++ compilation
  - Java code typemaps
- Typemap Examples
  - Converting Java String arrays to char **
  - Expanding a Java object to multiple arguments
  - Using typemaps to return arguments
  - Adding Java downcasts to polymorphic return types
  - Adding an equals method to the Java classes
  - Void pointers and a common Java base class
- Java class polymorphism (aka "directors" and "upcalls")
  - What are directors?
  - Director-specific typemaps
    - %typemap(directorin)
    - %typemap(javadirectorin)
    - %typemap(javadirectorout)
    - %typemap(javapackage)
  - Director method recursion
  - Living with Java Directors
- Odds and ends
  - JavaDoc comments
  - Functional interface without proxy classes
  - Using your own JNI functions
  - Performance concerns and hints
- Examples

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.

## 15.1 Overview

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. An important point to note is that SWIG enables a Java program to easily call into C/C++ code and not visa-versa. If you primarily want calls from C/C++ into Java then currently SWIG isn't particularly useful as the appropriate JNI code will have to be written by hand.

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 "SWIG Basics" chapter will be a useful read in conjunction with this one.

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 tour of basic C/C++ wrapping 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.

## 15.2 Preliminaries

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 `make -k check` from the SWIG root directory after installing SWIG on Unix systems.

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.

### 15.2.1 Running SWIG

Suppose that you defined a SWIG module such as the following:

>     %module example
>     %{
>     #include "header.h"
>     %}
>     int fact(int n);

To build a Java module, run SWIG using the `-java` option :

>     %swig -java example.i

If building C++, add the `-c++` option:

>     $ swig -c++ -java example.i

This creates two different files; a C/C++ source file `example_wrap.c` or `example_wrap.cxx` 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.

The name of the wrapper file is derived from the name of the input file. For example, if the input file is `example.i`, the name of the wrapper file is `example_wrap.c`. To change this, you can use the `-o` option. It is also possible to change the output directory that the Java files are generated into using `-outdir`.

### 15.2.2 Additional Commandline Options

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

>     swig -java -help

Java specific options
-package <name> | set name of the Java package to <name>
-noproxy | generate the low-level functional interface instead of proxy classes

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

### 15.2.3 Getting the right header files

In order to compile the C/C++ wrappers, the compiler needs the `jni.h` and `jni_md.h` header files which are part of the JDK. They are usually in directories like this:

>     /usr/java/include
>     /usr/java/include/<operating_system>

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

### 15.2.4 Compiling a dynamic module

The JNI code exists in a dynamic module or shared library (DLL on Windows) and gets loaded by the JVM. To build a shared library file, you need to compile your module in a manner similar to the following (shown for Solaris):

>     $ swig -java example.i
>     $ gcc -c example_wrap.c  -I/usr/java/include -I/usr/java/include/solaris
>     $ ld -G example_wrap.o  -o libexample.so

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 `Examples/java` 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 SWIG Wiki for additional information.

The name of the shared library output file is important. If the name of your SWIG module is "`example`", the name of the corresponding shared library file should be "`libexample.so`" (or equivalent depending on your machine, see Dynamic linking problems for more information). The name of the module is specified using the `%module` directive or`-module` command line option.

### 15.2.5 Using your module

To load your shared native library module in Java, simply use Java's `System.loadLibrary` method in a Java class:

>     // main.java

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

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

Compile all the Java files and run:

>     $ javac *.java
>     $ java main
>     24
>     $

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

### 15.2.6 Dynamic linking problems

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

You may get an exception similar to this:

>     $ java main
>     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 main.(main.java:5)

The most common cause for this is an incorrect naming of the native library for the name passed to the `loadLibrary` function. The string passed to the `loadLibrary` function must not include the file extension name in the string, that is .dll or .so. The string must be name and not libname for all platforms. On Windows the native library must then be called name.dll and on most Unix systems it must be called libname.so. If you are debugging using `java -debug`, then the native library must be called name_g.dll on Windows and libname_g.so on Unix.

Another common reason for the native library not loading is because it is not in your path. On Windows make sure the path environment variable contains the path to the native library. On Unix make sure that your LD_LIBRARY_PATH contains the path to the native library. Adding paths to LD_LIBRARY_PATH 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 `-rpath` if you're using GNU, see the GNU linker documentation (`ld` man page). You could use a command such as `ldconfig` (Linux) or `crle` (Solaris) to add additional search paths to the default system configuration (this requires root access and you will need to read the man pages).

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:

>     $ java main
>     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 main.(main.java:5)
>     $

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. Also make sure you pass all of the required libraries to the linker. The `java -verbose:jni` 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.

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 SWIG Wiki also has some settings for commonly used compiler and operating system combinations. The following section also contains some C++ specific linking problems and solutions.

### 15.2.7 Compilation problems and compiling with C++

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

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

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 `-lCrun` like this:

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

If you aren't entirely sure about the linking for C++, you might look at an existing C++ program. On many Unix machines, the `ldd` 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:

>     $ ldd swig
>             libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000)
>             libm.so.6 => /lib/libm.so.6 (0x4005b000)
>             libc.so.6 => /lib/libc.so.6 (0x40077000)
>             /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
>     $

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.

### 15.2.8 Building on Windows

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.

#### 15.2.8.1 Running SWIG from Visual Studio

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 Windows Examples containing Visual Studio project (.dsp) files. The process to re-create the project files for a C project are roughly:

- Open up a new workspace and use the AppWizard to select a DLL project.
- 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. `example_wrap.c`). Don't worry if the wrapper file doesn't exist yet--Visual Studio will keep a reference to it.
- Select the SWIG interface file and go to the settings menu. Under settings, select the "Custom Build" option.
- Enter "SWIG" in the description field.
- Enter "`swig -java -o $(ProjDir)\$(InputName)_wrap.c $(InputPath)`" in the "Build command(s) field"
- Enter "`$(ProjDir)\$(InputName)_wrap.c`" in the "Output files(s) field".
- 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".
- 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).
- 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.
- 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"
- Build your project.

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

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. 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 Dynamic linking problems.

#### 15.2.8.2 Using NMAKE

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 :

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

To build the DLL and compile the java code, run NMAKE (you may need to run `vcvars32` 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.

## 15.3 A tour of basic C/C++ wrapping

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.

### 15.3.1 Modules, packages and generated Java classes

The SWIG `%module` directive specifies the name of the Java module. When you specify ``%module example`', the module name determines the name of some of the generated files in the module. The generated code consists of a module class file `example.java`, an intermediary JNI class file, `exampleJNI.java` as well as numerous other Java proxy class files. Each proxy class is named after the structs, unions and classes you are wrapping. You may also get a constants interface file if you are wrapping any enumerations or constants, for example `exampleConstants.java`. 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 type wrapper class is generated. Details of all these generated classes will unfold as you read this section.

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

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

>     swig -java -package com.bloggs.swig -outdir com/bloggs/swig example.i

SWIG won't create the directory, so make sure it exists beforehand.

### 15.3.2 Functions

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,

>     %module example
>     int fact(int n);

creates a static function that works exactly like you think it might:

>     public class example {
>       public static int fact(int n) {
>         // makes call using JNI to the C function
>       }
>     }

The Java class `example` is the module class. The function can be used as follows from Java:

>     System.out.println(example.fact(4));

### 15.3.3 Global variables

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.

>     // SWIG interface file with global variables
>     %module example
>     ...
>     extern int My_variable;
>     extern double density;
>     ...

Now in Java :

>     // 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);

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:

>     %rename Clash RenamedClash;
>     float Clash;
>     int clash;

If a variable is declared as `const`, it is wrapped as a read-only variable. That is only a getter is produced.

To make ordinary variables read-only, you can use the `%immutable` directive. For example:

>     %immutable;
>     extern char *path;
>     %mutable;

The `%immutable` directive stays in effect until it is explicitly disabled using `%mutable`.

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

>     %immutable path;
>     ...
>     extern char *path;      // Read-only (due to %immutable)

### 15.3.4 Constants

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

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

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

>     public interface exampleConstants {
>       // enums and constants
>       public final static double PI = exampleJNI.get_PI();
>       public final static String VERSION = exampleJNI.get_VERSION();
>       public final static int FOO = exampleJNI.get_FOO();
>       public final static String path = exampleJNI.get_path();
>     }

These are runtime constants. They are not compiler constants that can, for example, be used in a switch statement. This can be changed by using the `%javaconst(flag)` directive. It works like all the other %feature directives. The default is `%javaconst(0)`. It is possible to initialize all wrapped constants from pure Java code by placing a `%javaconst(1)` before SWIG parses the constants. Putting it at the top of your interface file would ensure this. Here is an example:

>     %javaconst(1);
>     %javaconst(0) BIG;
>     #define BIG 1000LL
>     #define EXPRESSION (0x100+5)

generates:

>     public interface exampleConstants {
>       // enums and constants
>       public final static long BIG = exampleJNI.get_BIG();
>       public final static int EXPRESSION = (0x100+5);
>     }

Be careful using the `%javaconst(1)` directive as not all C code will compile as Java code. For example the `1000LL` value for the `BIG` constant above would not generate valid Java code. The example demonstrates how you can target particular constants (`BIG`) with `%javaconst`.

Note: declarations declared as `const` 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.

Compatibility Note: 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):

>     public class example implements exampleConstants {
>     }

You thus have the choice of accessing these constants from either the module class or the constants interface, for example, `example.EXPRESSION` or `exampleConstants.EXPRESSION`.

### 15.3.5 Enumerations

Enumerations are wrapped as final static integers in Java and are also initialised using a JNI call. For example:

>     enum Beverage { ALE, LAGER=10, STOUT, PILSNER };

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

>     public interface exampleConstants {
>       // enums and constants
>       public final static int ALE = exampleJNI.get_ALE();
>       public final static int LAGER = exampleJNI.get_LAGER();
>       public final static int STOUT = exampleJNI.get_STOUT();
>       public final static int PILSNER = exampleJNI.get_PILSNER();
>     }

The `%javaconst(flag)` directive introduced in the previous section on constants can also be used with enums, thereby also allowing enum values to be used in Java switch statements. As is the case for constants, the default is `%javaconst(0)` as not all C values will compile as Java code. However, it is recommended to add in a `%javaconst(1)` 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. Example usage:

>     %javaconst(1);
>     %javaconst(0) PILSNER;
>     enum Beverage { ALE, LAGER=10, STOUT, PILSNER };

generates:

>     public interface exampleConstants {
>       // enums and constants
>       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.get_PILSNER();
>     }

As in the case of constants, you can access them through either the module class or the constants interface, for example, `example.ALE` or `exampleConstants.ALE`.

For enums, make sure that the definition of the enumeration actually appears in a header file or in the wrapper file somehow---if you just have an enum in a SWIG interface without also telling the C compiler about it, the wrapper code won't compile.

### 15.3.6 Pointers

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

>     %module example

>     FILE *fopen(const char *filename, const char *mode);
>     int fputs(const char *, FILE *);
>     int fclose(FILE *);

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

>     SWIGTYPE_p_FILE f = example.fopen("junk","w");
>     example.fputs("Hello World\n", f);
>     example.fclose(f);

C pointers in the Java module are stored in a Java `long` 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 `FILE *` pointer is wrapped with a type wrapper class called `SWIGTYPE_p_FILE`.

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.

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:

>     %inline %{
>     /* C-style cast */
>     Bar *FooToBar(Foo *f) {
>        return (Bar *) f;
>     }

>     /* C++-style cast */
>     Foo *BarToFoo(Bar *b) {
>        return dynamic_cast<Foo*>(b);
>     }

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

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.

### 15.3.7 Structures

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,

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

is used as follows:

>     Vector v = new Vector();
>     v.setX(3.5);
>     v.setY(7.2);
>     double x = v.getX();
>     double y = v.getY();

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.

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.

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

>     struct Foo {
>        ...
>        %immutable;
>        int x;        /* Read-only members */
>        char *name;
>        %mutable;
>        ...
>     };

When `char *` members of a structure are wrapped, the contents are assumed to be dynamically allocated using `malloc` or `new` (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).

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

>     struct Bar {
>         int  x[16];
>     };

If accessed in Java, you will see behavior like this:

>     Bar b = new Bar();
>     SWIGTYPE_p_int x = b.getX();

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

>     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

For array assignment (setters not getters), SWIG copies the entire contents of the array starting with the data pointed to by `b.x`. 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. Array access can be changed from this default to use Java arrays and this is covered later.

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:

>     struct Foo {
>        int a;
>     };

>     struct Bar {
>        Foo f;
>     };

Now, suppose that you access the `f` member of `Bar` like this:

>     Bar b = new Bar();
>     Foo x = b.getF();

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

>     Bar b;
>     Foo *x = &b->f;       /* Points inside b */

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

>     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

### 15.3.8 C++ classes

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

>     class List {
>     public:
>       List();
>       ~List();
>       int  search(char *item);
>       void insert(char *item);
>       void remove(char *item);
>       char *get(int n);
>       int  length;
>     };

you can use it in Java like this:

>     List l = new List();
>     l.insert("Ale");
>     l.insert("Stout");
>     l.insert("Lager");
>     String item = l.get(2);
>     int length = l.getLength();

Class data members are accessed in the same manner as C structures.

Static class members are unsurprisingly wrapped as static members of the Java class:

>     class Spam {
>     public:
>        static void foo();
>        static int bar;
>     };

The static members work like any other Java static member:

>     Spam.foo();
>     int bar = Spam.getBar();

### 15.3.9 C++ inheritance

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

>     class Foo {
>     ...
>     };

>     class Bar : public Foo {
>     ...
>     };

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

>     Bar b = new Bar();
>     Class c = b.getClass();
>     System.out.println(c.getSuperclass().getName());

will of course display:

>     Foo

Furthermore, if you have functions like this

>     void spam(Foo *f);

then the Java function `spam()` accepts instances of `Foo` or instances of any other proxy classes derived from `Foo`.

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.

### 15.3.10 Pointers, references, arrays and pass by value

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

>     void spam1(Foo *x);      // Pass by pointer
>     void spam2(Foo &x);      // Pass by reference
>     void spam3(Foo x);       // Pass by value
>     void spam4(Foo x[]);     // Array of objects

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:

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

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

>     Foo *spam5();
>     Foo &spam6();
>     Foo  spam7();

then all three functions will return a pointer to some `Foo` 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).

#### 15.3.10.1 Null pointers

Working with null pointers is easy. A Java `null` 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.

>     example.spam1(null);   // Pointer - ok
>     example.spam2(null);   // Reference - NullPointerException
>     example.spam3(null);   // Value - NullPointerException
>     example.spam4(null);   // Array - ok

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

### 15.3.11 C++ overloaded functions

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

>     void foo(int);
>     void foo(char *c);

You can use them in Java in a straightforward manner:

>     foo(3);           // foo(int)
>     foo("Hello");     // foo(char *c)

Similarly, if you have a class like this,

>     class Foo {
>     public:
>         Foo();
>         Foo(const Foo &);
>         ...
>     };

you can write Java code like this:

>     Foo f = new Foo();        // Create a Foo
>     Foo g = new Foo(f);       // Copy f

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

>     void spam(int);
>     void spam(unsigned short);

Here both int and unsigned short map onto a Java int. Here is another example:

>     void foo(Bar *b);
>     void foo(Bar &b);

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

>     example.i:12: Warning(509): Overloaded spam(unsigned short) is shadowed by spam(int) at example.i:11.

The generated Java code will not compile either. To fix this, you either need to ignore or rename one of the methods. For example:

>     %rename(spam_short) spam(short);
>     ...
>     void spam(int);
>     void spam(short);   // Accessed as spam_short

or

>     %ignore spam(short);
>     ...
>     void spam(int);
>     void spam(short);   // Ignored

### 15.3.12 C++ namespaces

SWIG is aware of C++ namespaces, but 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,

>     %module example

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

it works in Java as follows:

>     int f = example.fact(3);
>     Vector v = new Vector();
>     v.setX(3.4);
>     double y = v.getY();

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

>     %rename(Bar_spam) Bar::spam;

>     namespace Foo {
>         int spam();
>     }

>     namespace Bar {
>         int spam();
>     }

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

### 15.3.13 C++ templates

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 `%template` directive. For example:

>     %module example
>     %{
>     #include "pair.h"
>     %}

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

>     %template(pairii) pair<int,int>;

In Java:

>     pairii p = new pairii(3,4);
>     int first = p.getFirst();
>     int second = p.getSecond();

Obviously, there is more to template wrapping than shown in this example. More details can be found in the SWIG and C++ chapter.

### 15.3.14 C++ Smart Pointers

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 `operator->()` like this:

>     template<class T> class SmartPtr {
>        ...
>        T *operator->();
>        ...
>     }

Then, if you have a class like this,

>     class Foo {
>     public:
>          int x;
>          int bar();
>     };

A smart pointer would be used in C++ as follows:

>     SmartPtr<Foo> p = CreateFoo();   // Created somehow (not shown)
>     ...
>     p->x = 3;                        // Foo::x
>     int y = p->bar();                // Foo::bar

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

>     %module example
>     ...
>     %template(SmartPtrFoo) SmartPtr<Foo>;
>     ...

Now, in Java, everything should just "work":

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

If you ever need to access the underlying pointer returned by `operator->()` itself, simply use the `__deref__()` method. For example:

>     Foo f = p.__deref__();               // Returns underlying Foo *

## 15.4 Further details on the generated Java classes

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 programing 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. First, the crucial intermediary JNI class is considered.

### 15.4.1 The intermediary JNI class

In the "SWIG basics" and "SWIG and C++" 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

>     class Foo {
>     public:
>          int x;
>          int spam(int num, Foo* foo);
>     };
>     void egg(Foo* chips);

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

>     Foo *new_Foo() {
>         return new Foo();
>     }
>     void delete_Foo(Foo *f) {
>         delete f;
>     }
>     int Foo_x_get(Foo *f) {
>         return f->x;
>     }
>     void Foo_x_set(Foo *f, int value) {
>         f->x = value;
>     }
>     int Foo_spam(Foo *f, int num, Foo* foo) {
>         return f->spam(num, foo);
>     }

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:

>     JNIEXPORT jlong JNICALL Java_exampleJNI_new_1Foo(JNIEnv *jenv, jclass jcls);
>     JNIEXPORT void JNICALL Java_exampleJNI_delete_1Foo(JNIEnv *jenv, jclass jcls, jlong jarg1);
>     JNIEXPORT void JNICALL Java_exampleJNI_set_1Foo_1x(JNIEnv *jenv, jclass jcls, jlong jarg1, jint jarg2);
>     JNIEXPORT jint JNICALL Java_exampleJNI_get_1Foo_1x(JNIEnv *jenv, jclass jcls, jlong jarg1);
>     JNIEXPORT jint JNICALL Java_exampleJNI_Foo_1spam(JNIEnv *jenv, jclass jcls, jlong jarg1, jint jarg2, jlong jarg3);
>     JNIEXPORT void JNICALL Java_exampleJNI_egg(JNIEnv *jenv, jclass jcls, jlong jarg1);

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

>     class exampleJNI {
>       public final static native long new_Foo();
>       public final static native void delete_Foo(long jarg1);
>       public final static native void set_Foo_x(long jarg1, int jarg2);
>       public final static native int get_Foo_x(long jarg1);
>       public final static native int Foo_spam(long jarg1, int jarg2, long jarg3);
>       public final static native void egg(long jarg1);
>     }

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 proxy classes, type wrapper classes and module class, it is known as the intermediary JNI class.

You may notice that SWIG uses a Java long wherever a pointer or class object needs traversing 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 uses Java code wherever possible as it is compiled into byte code which requires fewer string operations.

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.

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 `jniclassname` is used to achieve this:

>     %module (jniclassname="name") modulename

If `name` is the same as `modulename` then the module class name gets changed from `modulename` to `modulenameModule`.

#### 15.4.1.1 The intermediary JNI class pragmas

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

Pragma | Description
jniclassbase | Base class for the intermediary JNI class
jniclassclassmodifiers | Class modifiers for the intermediary JNI class
jniclasscode | Java code is copied verbatim into the intermediary JNI class
jniclassimports | Java code, usually one or more import statements, placed before the intermediary JNI class definition
jniclassinterfaces | Comma separated interface classes for the intermediary JNI class

The pragma code appears in the generated intermediary JNI class where you would expect:

>     [ jniclassimports pragma ]
>     [ jniclassmodifiers pragma ] class jniclassname extends [ jniclassbase pragma ] implements [ jniclassinterfaces pragma ] {
>     [ jniclasscode pragma ]
>     ... SWIG generated native methods ...
>     }

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

>     %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);
>         }
>       }
>     %}

Pragmas will take either `""` or `%{ %}` as delimeters. For example, let's change the intermediary JNI class access attribute to public.

>     %pragma(java) jniclassclassmodifiers="public"

All the methods in the intermediary JNI class will then be callable outside of the package as the method modifiers are public by default.

### 15.4.2 The Java module class

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

>     public class example {
>       public static void egg(Foo chips) {
>         exampleJNI.egg(Foo.getCPtr(chips));
>       }
>     }

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:

>     example.egg(new Foo());

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 `Foo` can be passed to the `egg` function, whereas any `long` can be passed to the `egg` function in the intermediary JNI class.

#### 15.4.2.1 The Java module class pragmas

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:

Pragma | Description
modulebase | Base class for the module class
moduleclassmodifiers | Class modifiers for the module class
modulecode | Java code is copied verbatim into the module class
moduleimports | Java code, usually one or more import statements, placed before the module class definition
moduleinterfaces | Comma separated interface classes for the module class

The pragma code appears in the generated module class like this:

>     [ moduleimports pragma ]
>     [ modulemodifiers pragma ] class modulename extends [ modulebase pragma ] implements [ moduleinterfaces pragma ] {
>     [ modulecode pragma ]
>     ... SWIG generated wrapper functions ...
>     }

See The intermediary JNI class pragmas section for further details on using pragmas.

### 15.4.3 Java proxy classes

A Java proxy class is generated for each structure, union or C++ class that is wrapped. The default proxy class for our previous example looks like this:

>     public class Foo {
>       private long swigCPtr;
>       protected boolean swigCMemOwn;

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

>       protected void finalize() {
>         delete();
>       }

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

>       protected static long getCPtr(Foo obj) {
>         return obj.swigCPtr;
>       }

>       public void setX(int x) {
>         exampleJNI.set_Foo_x(swigCPtr, x);
>       }

>       public int getX() {
>         return exampleJNI.get_Foo_x(swigCPtr);
>       }

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

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

This class merely holds a pointer to the underlying C++ object (`swigCPtr`). 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 `spam()` function it will only compile when the parameters passed are an `int` and a `Foo`. From a user's point of view, it makes the class work as if it were a Java class:

>     Foo f = new Foo();
>     f.setX(3);
>     int y = f.spam(5, new Foo());

#### 15.4.3.1 Memory management

Each proxy class has an ownership flag `swigCMemOwn`. The value of this flag determines who is responsible for deleting the underlying C++ object. If set to `true`, 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.

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:

>     class Foo {
>     public:
>         Foo();
>         Foo bar1();
>         Foo &bar2();
>         Foo *bar2();
>     };

In Java:

>     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

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!

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:

>     class Obj {};
>     class Node {
>        Obj *value;
>     public:
>        void set_value(Obj *v) { value = v; }
>     };

Now, consider the following Java code:

>     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

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

To work around this, the ownership flag of `o` needs changing to `false`. 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 is achieved using a typemap to add pure Java code to the proxy class and is detailed later in the section on typemaps.

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 `%newobject` directive. Consider:

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

If we call the factory function, then we have to manually delete the memory:

>     Obj obj = Factory.createObj();   // obj.swigCMemOwn = false
>     ...
>     obj.delete();

Now add in the %newobject directive:

>     %newobject Factory::createObj();

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

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

>     Obj obj = Factory.createObj();   // obj.swigCMemOwn = true;
>     ...

#### 15.4.3.2 Inheritance

Java proxy classes will mirror C++ inheritance chains. For example, given the base class `Base` and its derived class Derived:

>     class Base {
>     public:
>       virtual double foo();
>     };

>     class Derived : public Base {
>     public:
>       virtual double foo();
>     };

The base class is generated much like any other proxy class seen so far:

>     public class Base {
>       private long swigCPtr;
>       protected boolean swigCMemOwn;

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

>       protected void finalize() {
>         delete();
>       }

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

>       protected static long getCPtr(Base obj) {
>         return obj.swigCPtr;
>       }

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

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

The `Derived` class extends `Base` mirroring the C++ class inheritance hierarchy.

>     public class Derived extends Base {
>       private long swigCPtr;

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

>       protected void finalize() {
>         delete();
>       }

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

>       protected static long getCPtr(Derived obj) {
>         return obj.swigCPtr;
>       }

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

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

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 `SWIGDerivedToBase()` call converts the pointer from a `Derived *` to a `Base *` as C++ compilers are free to implement pointers in the inheritance hierarchy with different values.

It is of course possible to extend `Base` using your own Java classes. If `Derived` is provided by the C++ code, you could for example add in a pure Java class `Extended` derived from `Base`. There is a caveat and that is any C++ code will not know about your pure Java class `Extended` so this type of derivation is restricted.

#### 15.4.3.3 Proxy classes and garbage collection

By default each proxy class has a `delete()` and a `finalize()` method. The `finalize()` method calls `delete()` which frees any malloc'd memory for wrapped C structs or calls the C++ class destructors. The idea is for `delete()` to be called when you have finished with the C/C++ object. Ideally you need not call `delete()`, but rather leave it to the garbage collector to call it from the finalizer. The unfortunate thing is that Sun, in their wisdom, do not guarantee that the finalizers will be called. When a program exits, the garbage collector does not always call the finalizers. Depending on what the finalizers do and which operating system you use, this may or may not be a problem.

If the `delete()` 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.

Some not so ideal solutions are:

1. Call the `System.runFinalizersOnExit(true)` or `Runtime.getRuntime().runFinalizersOnExit(true)` to ensure the finalizers are called before the program exits. The catch is that this is a deprecated function call as the documenation says:

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

   In many cases you will be lucky and find that it works, but it is not to be advocated. Have a look at Sun's Java web site and search for `runFinalizersOnExit`.

2. From jdk1.3 onwards a new function, `addShutdownHook()`, 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 `main()` function:

   >       static {
   >         Runtime.getRuntime().addShutdownHook(
   >           new Thread() {
   >             public void run() { System.gc(); System.runFinalization(); }
   >           }
   >         );
   >       }

   Although this usually works, the documentation doesn't guarantee that `runFinalization()` will actually call the finalizers. As the 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.

3. Call the `delete()` 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 inadvertantly 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:

   >     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

   The SWIG generated code ensures that the memory is not deleted twice, in the event the finalizers get called in addition to the manual `delete()` call.

4. 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 Java typemaps details how to specify a pure Java base class.

### 15.4.4 Type wrapper classes

The generated type wrapper class, for say an `int *`, looks like this:

>     public class SWIGTYPE_p_int {
>       private 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;
>       }
>     }

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 Java typemaps details how to modify the generated code.

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.

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 `class Snazzy` because it is in a header file that you may have forgotten to use the `%include` directive on. Should SWIG parse `Snazzy *` being used in a function parameter, it will then generates a type wrapper class around a `Snazzy` pointer. Also recall from earlier that SWIG will use a pointer when a class is passed by value or by reference:

>     void spam(Snazzy *x, Snazzy &y, Snazzy z);

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

>     public static void spam(SWIGTYPE_p_Snazzy x, SWIGTYPE_p_Snazzy y, SWIGTYPE_p_Snazzy z) { ... }

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 `Snazzy` is a typedef to an `int` which SWIG does parse:

>     typedef int Snazzy;
>     void spam(Snazzy *x, Snazzy &y, Snazzy z);

Because the typedefs have been tracked the Java function generated is:

>     public static void spam(SWIGTYPE_p_int x, SWIGTYPE_p_int y, int z) { ... }

## 15.5 Common customization features

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.

### 15.5.1 C/C++ helper functions

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

>     typedef struct Image {...};
>     void set_transform(Image *im, double m[4][4]);

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 `double [4][4]` value. To fix this, you can write some extra C helper functions. Just use the `%inline` directive. For example:

>     %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];
>     }
>     %}

From Java, you could then write code like this:

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

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.

### 15.5.2 Class extension with %extend

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:

>     %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->x,self->y,self->z);
>            return tmp;
>        }
>        Vector(double x, double y, double z) {
>            Vector *v = (Vector *) malloc(sizeof(Vector));
>            v->x = x;
>            v->y = y;
>            v->z = z;
>            return v;
>        }
>     };

Now, in Java

>     Vector v = new Vector(2,3,4);
>     System.out.println(v);

will display

>     Vector(2,3,4)

`%extend` 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.

### 15.5.3 Exception handling with %exception

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 `%exception` directive. The `%exception` directive simply lets you rewrite part of the generated wrapper code to include an error check.

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:

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

In Java,

>     SWIGTYPE_p_void a = example.malloc(2000000000);

will produce a familiar looking Java exception:

>     Exception in thread "main" java.lang.OutOfMemoryError: Not enough memory
>             at exampleJNI.malloc(Native Method)
>             at example.malloc(example.java:16)
>             at main.main(main.java:112)

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

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

No declaration name is given to `%exception`, it is applied to all wrapper functions. The `$action` is a SWIG special variable and is replaced by the C/C++ function call being wrapped. The `return $null;` 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 Java special variables for further explanation.

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

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

>     class Base {
>     public:
>          Foo *getitem(int index);      // Exception handler added
>          ...
>     };

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 visa versa. It is however possible to write JNI calls which will compile under both C and C++ and is covered in the Typemaps for both C and C++ compilation section.

The language-independent `exception.i` library file can also be used to raise exceptions. See the SWIG Library chapter.

### 15.5.4 Method access with %javamethodmodifiers

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

>     %javamethodmodifiers protect_me() "protected";
>     void protect_me();

Will produce the method in the module class with protected access.

>     protected static void protect_me() {
>       exampleJNI.protect_me();
>     }

## 15.6 Tips and techniques

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.

### 15.6.1 Input and output parameters using primitive pointers and references

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

>     void add(int x, int y, int *result) {
>        *result = x + y;
>     }

or perhaps

>     int sub(int *x, int *y) {
>        return *x-*y;
>     }

The `typemaps.i` library file will help in these situations. For example:

>     %module example
>     %include "typemaps.i"

>     void add(int, int, int *OUTPUT);
>     int  sub(int *INPUT, int *INPUT);

In Java, this allows you to pass simple values. For example:

>     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]);

Which will display:

>     7 - 4 = 3
>     3 + 4 = 7

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

If you don't want to use the names `INPUT` or `OUTPUT`, use the `%apply` directive. For example:

>     %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);

If a function mutates one of its parameters like this,

>     void negate(int *x) {
>        *x = -(*x);
>     }

you can use `INOUT` like this:

>     %include "typemaps.i"
>     ...
>     void negate(int *INOUT);

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:

>     int[] neg = {3};
>     example.negate(neg);
>     System.out.println("Negative of 3 = " + neg[0]);

And no prizes for guessing the output:

>     Negative of 3 = -3

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 `negate` function would be the same if it were defined either as it is above:

>     void negate(int *INOUT);

or using a reference:

>     void negate(int &INOUT);

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.

Be aware that the primary purpose of the `typemaps.i` file is to support primitive datatypes. Writing a function like this

>     void foo(Bar *OUTPUT);

will not have the intended effect since `typemaps.i` does not define an OUTPUT rule for `Bar`.

### 15.6.2 Simple pointers

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

>     %module example
>     %include "cpointer.i"

>     extern void add(int x, int y, int *result);
>     %pointer_functions(int, intp);

The `%pointer_functions(type,name)` 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:

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

In Java, you would use the functions like this:

>     SWIGTYPE_p_int intPtr = example.new_intp();
>     example.add(3,4,intPtr);
>     int result = example.intp_value(intPtr);
>     System.out.println("3 + 4 = " + result);

If you replace `%pointer_functions(int,intp)` by `%pointer_class(int,intp)`, the interface is more class-like.

>     intp intPtr = new intp();
>     example.add(3,4,intPtr.cast());
>     int result = intPtr.value();
>     System.out.println("3 + 4 = " + result);

See the SWIG Library chapter for further details.

### 15.6.3 Wrapping C arrays with Java arrays

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

>     %include "arrays_java.i";
>     int array[4];
>     void populate(int x[]) {
>         int i;
>         for (i=0; i<4; i++)
>             x[i] = 100 + i;
>     }

These one dimensional arrays can then be used as if they were Java arrays:

>     int[] array = new int[4];
>     example.populate(array);

>     System.out.print("array: ");
>     for (int i=0; i<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<array.length; i++)
>         System.out.print(global_array[i] + " ");

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:

>     array: 100 101 102 103
>     global_array: 100 101 102 103

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 `populate`, the size of the C array passed to the function is determined by the size of the Java array.

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.

### 15.6.4 Unbounded C Arrays

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

>     int sumitems(int *first, int nitems) {
>         int i, sum = 0;
>         for (i = 0; i < nitems; i++) {
>             sum += first[i];
>         }
>         return sum;
>     }

One of the ways to wrap this is to apply the Java array typemaps that come in the `arrays_java.i` library file:

>     %include "arrays_java.i"
>     %apply int[ANY] {int *};

The `ANY` 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:

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

and the sum would be displayed:

>     Sum = 49995000

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 `carrays.i`. This approach can be more efficient for large arrays as the array is accessed one element at a time. For example:

>     %include "carrays.i"
>     %array_functions(int, intArray);

The `%array_functions(type,name)` 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:

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

In Java, you would use the functions like this:

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

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

>     %include "carrays.i"
>     %array_class(int, intArray);

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

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

The array "object" created by `%array_class()` 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.

## 15.7 Java typemaps

This section describes how you can modify SWIG's default wrapping behavior for various C/C++ datatypes using the `%typemap` directive. You are advised to be familiar with the the material in the "Typemaps" 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 Sun's Java web site or from a good JNI book. The following two books are recommended:

- Title: 'Essential JNI: Java Native Interface.' Author: Rob Gordon. Publisher: Prentice Hall. ISBN: 0-13-679895-0.
- Title: 'The Java Native Interface: Programmer's Guide and Specification.' Author: Sheng Liang. Publisher: Addison-Wesley. ISBN: 0-201-32577-2.

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.

### 15.7.1 Default primitive type mappings

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

C/C++ type | Java type | JNI type
bool const bool & | boolean | jboolean
char const char & | char | jchar
signed char const signed char & | byte | jbyte
unsigned char const unsigned char & | short | jshort
short const short & | short | jshort
unsigned short const unsigned short & | int | jint
int const int & | int | jint
unsigned int const unsigned int & | long | jlong
long const long & | int | jint
unsigned long const unsigned long & | long | jlong
long long const long long & | long | jlong
unsigned long long const unsigned long long & | java.math.BigInteger | jobject
float const float & | float | jfloat
double const double & | double | jdouble
char * char [] | String | jstring

Note that SWIG wraps the C `char` type as a character. Pointers and arrays of this type are wrapped as strings. The `signed char` type can be used if you want to treat `char` 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.

Given the following C function:

>     void func(unsigned short a, char *b, const long &c, unsigned long long d);

The module class method would be:

>     public static void func(int a, String b, int c, java.math.BigInteger d) {...}

The intermediary JNI class would use the same types:

>     public final static native void func(int jarg1, String jarg2, int jarg3, java.math.BigInteger jarg4);

and the JNI function would look like this:

>     JNIEXPORT void JNICALL Java_exampleJNI_func(JNIEnv *jenv, jclass jcls, jint jarg1, jstring jarg2, jint jarg3, jobject jarg4) {...}

The mappings for C `int` and C `long` 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.

### 15.7.2 Sixty four bit JVMs

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.

### 15.7.3 What is a typemap?

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:

>     %module example

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

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 `int` 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 `$` are used. The `$1` variable is a placeholder for a local variable of type `int`. The `$input` variable contains the Java data, the JNI `jint` in this case.

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

>     System.out.println(example.fact(6));

and the output will be:

>     Received an integer : 6
>     720

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

>     %module example

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

>     extern int fact(int nonnegative);

In this case, the typemap code is only attached to arguments that exactly match `int nonnegative`.

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 `int`, that typemap applies to `int` and qualified variations such as `const int`. In addition, the typemap system follows `typedef` declarations. For example:

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

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

Typemaps can also be defined for groups of consecutive arguments. For example:

>     %typemap(in) (char *str, int len) {
>     ...
>     };

>     int count(char c, char *str, int len);

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

>     int c = example.count('e',"Hello World");

### 15.7.4 Typemaps for mapping C/C++ types to Java types

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:

Typemap | Description
jni | JNI C types. These provide the default mapping of types from C/C++ to JNI for use in the JNI (C/C++) code.
jtype | 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.
jstype | 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.
javain | 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.
javaout | 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.

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 `java.swg` and so might be a good place for finding typemaps to base any new ones on.

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.

The default code generated by SWIG for the Java module comes from the typemaps in the `java.swg` library file which implements the Default primitive type mappings covered earlier. There are other type mapping typemaps in the Java library. These are listed below:

C Type | Typemap | File | Kind | Java Type | Function
primitive pointers and references | INPUT | typemaps.i | input | Java basic types | Allows values to be used for C functions taking pointers for data input.
primitive pointers and references | OUTPUT | typemaps.i | output | Java basic type arrays | Allows values held within an array to be used for C functions taking pointers for data output.
primitive pointers and references | INOUT | typemaps.i | input output | Java basic type arrays | Allows values held within an array to be used for C functions taking pointers for data input and output.
string wstring | [unnamed] | std_string.i | input output | String | Use for std::string mapping to Java String.
arrays of primitive types | [unnamed] | arrays_java.i | input output | arrays of primitive Java types | Use for mapping C arrays to Java arrays.
arrays of classes/structs/unions | JAVA_ARRAYSOFCLASSES macro | arrays_java.i | input output | arrays of proxy classes | Use for mapping C arrays to Java arrays.
arrays of enums | ARRAYSOFENUMS | arrays_java.i | input output | int[] | Use for mapping C arrays to Java arrays.
char * | BYTE | various.i | input | byte[] | Java byte array is converted to char array
char ** | STRING_IN | various.i | input | String[] | \0 terminated array of \0 terminated strings
char ** | STRING_OUT | various.i | output | String[] | &char * the argument is the address of a \0 terminated string
char ** | STRING_RET | various.i | return | String[] | \0 terminated array of \0 terminated strings the array is not free'd.

### 15.7.5 Java special variables

The standard SWIG special variables are available for use within typemaps as described in the Typemaps documentation, for example `$1`, `$input`,`$result` etc.

The Java module uses a few additional special variables:

`$javaclassname`
`$javaclassname` is similar to `$1_type`. It expands to the class name for use in Java. When wrapping a union, struct or class, it expands to the Java proxy class name. Otherwise it expands to the type wrapper class name. For example, `$javaclassname` is replaced by `Foo` when the wrapping a `struct Foo` or `struct Foo *` and `SWIGTYPE_p_unsigned_short` is used for `unsigned short *`.

`$null`
Used in input typemaps to return early from JNI functions that have either void or a non-void return type. Example:

>     %typemap(check) int * %{
>       if (error) {
>         SWIG_exception(SWIG_IndexError, "Array element error");
>         return $null;
>       }
>     %}

If the typemap gets put into a function with void as return, $null will expand to nothing:

>     JNIEXPORT void JNICALL Java_jnifn(...) {
>         if (error) {
>           SWIG_exception(SWIG_IndexError, "Array element error");
>           return ;
>         }
>       ...
>     }

otherwise $null expands to NULL

>     JNIEXPORT jobject JNICALL Java_jnifn(...) {
>         if (error) {
>           SWIG_exception(SWIG_IndexError, "Array element error");
>           return NULL;
>         }
>       ...
>     }

`$javainput, $jnicall and $owner`
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 `true` if %newobject has been used, otherwise `false`. $javainput is analogous to the $input special variable. It is replaced by the parameter name.

Here is an example:

>     %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(); };
>     %}

The generated proxy code is then:

>     public static Class bar(Class cls, int ush) {
>       return new Class(exampleJNI.bar(Class.getCPtr(cls), ush), false);
>     }

Here $javainput has been replaced by `cls` and `ush`. $jnicall has been replaced by the native method call, `exampleJNI.bar(...)` and $owner has been replaced by `false`. If %newobject is used by adding the following at the beginning of our example:

>     %newobject bar(Class cls, unsigned short ush);

The generated code constructs the return type using `true` indicating the proxy class `Class` is responsible for destroying the C++ memory allocated for it in `bar`:

>     public static Class bar(Class cls, int ush) {
>       return new Class(exampleJNI.bar(Class.getCPtr(cls), ush), true);
>     }

### 15.7.6 Typemaps for both C and C++ compilation

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

>     const jclass clazz = (*jenv)->FindClass(jenv, "java/lang/String");

whereas C++ code compilation of the same function call is a member function call using a class pointer like

>     const jclass clazz = jenv->FindClass("java/lang/String");

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

>     const jclass clazz = JCALL1(FindClass, jenv, "java/lang/String");

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.

### 15.7.7 Java code typemaps

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

`%typemap(javabase)`

> base (extends) for Java class: empty default

`%typemap(javaclassmodifiers)`

> class modifiers for the Java class: default is "public"

`%typemap(javacode)`

> Java code is copied verbatim to the Java class: empty default

`%typemap(javadestruct, methodname="delete")`

> destructor wrapper - the `delete()` method (proxy classes only), used for all classes except those which have a base class : default calls C++ destructor (or frees C memory) and resets `swigCPtr` and `swigCMemOwn` flags
> Note that the `delete()` method name is configurable and is specified by the `methodname` attribute.

`%typemap(javadestruct_derived, methodname="delete")`

> destructor wrapper - the `delete()` method (proxy classes only), same as "javadestruct" but only used for derived classes : default calls C++ destructor (or frees C memory) and resets `swigCPtr` and `swigCMemOwn` flags
> Note that the `delete()` method name is configurable and is specified by the `methodname` attribute.

`%typemap(javaimports)`

> import statements for Java class: empty default

`%typemap(javainterfaces)`

> interfaces (extends) for Java class: empty default

`%typemap(javafinalize)`

> the `finalize()` method (proxy classes only): default calls the `delete()` method

`%typemap(javagetcptr)`

> the `getCPtr()` method: default returns the `swigCPtr` member variable

`%typemap(javaptrconstructormodifiers)`

> method modifier for the constructors taking a C pointer and the memory ownership flag: default is "protected"

In summary the contents of the typemaps make up a proxy class like this:

>     [ javaimports typemap ]
>     [ javamodifiers typemap ] class proxyclassname extends [ javabase typemap ] implements [ javainterfaces typemap ] {
>     [ javafinalize typemap ]
>     [ javaptrconstructormodifiers typemap ] proxyclassname(long cPtr, boolean cMemoryOwn) {...}
>     ... Other SWIG generated constructors ...
>     public void delete() [ javadestruct OR javadestruct_derived typemap ]
>     [ javagetcptr typemap ]
>     [ javacode typemap ]
>     ... proxy functions ...
>     }

Note the `delete()` methodname is configurable, see "javadestruct" and "javadestruct_derived" typemaps above.

The type wrapper class is similar in construction:

>     [ javaimports typemap ]
>     [ javamodifiers typemap ] class typewrappername extends [ javabase typemap ] implements [ javainterfaces typemap ] {
>     [ javaptrconstructormodifiers typemap ] proxyclassname(long cPtr, boolean bFutureUse) {...}
>     ... Other SWIG generated constructors ...
>     [ javagetcptr typemap ]
>     [ javacode typemap ]
>     }

The defaults can be overridden to tailor these classes and are often used to hide or expose the C/C++ pointer. Here is an example which will change the `getCPtr()` method from the default protected access to public access.

>     %typemap(javagetcptr) SWIGTYPE %{
>       public static long getCPtr($javaclassname obj) {
>         return (obj == null) ? 0 : obj.swigCPtr;
>       }
>     %}

Note that `SWIGTYPE` will target all proxy classes, but not all type wrapper classes. 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:

>     %typemap(javagetcptr) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [], SWIGTYPE (CLASS::*) %{
>       public static long getCPtr($javaclassname obj) {
>         return obj.swigCPtr;
>       }
>     %}

## 15.8 Typemap Examples

This section includes a few examples of typemaps. For more examples, you might look at the files "`java.swg`" and "`typemaps.i`" in the SWIG library.

### 15.8.1 Converting Java String arrays to char **

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 `char **` object.

>     %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)->GetArrayLength(jenv, $input);
>         $1 = (char **) malloc((size+1)*sizeof(char *));
>         /* make a copy of each string */
>         for (i = 0; i<size; i++) {
>             jstring j_string = (jstring)(*jenv)->GetObjectArrayElement(jenv, $input, i);
>             const char * c_string = (*jenv)->GetStringUTFChars(jenv, j_string, 0);
>             $1[i] = malloc(strlen((c_string)+1)*sizeof(const char *));
>             strcpy($1[i], c_string);
>             (*jenv)->ReleaseStringUTFChars(jenv, j_string, c_string);
>             (*jenv)->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<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)->FindClass(jenv, "java/lang/String");

>         while ($1[len]) len++;
>         jresult = (*jenv)->NewObjectArray(jenv, len, clazz, NULL);
>         /* exception checking omitted */

>         for (i=0; i<len; i++) {
>           temp_string = (*jenv)->NewStringUTF(jenv, *result++);
>           (*jenv)->SetObjectArrayElement(jenv, jresult, i, temp_string);
>           (*jenv)->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 visa 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 &values[0];
>     }

>     %}

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:

>     // File main.java

>     public class main {

>       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<args.length; i++)
>             System.out.println(i + ":" + args[i]);
>       }
>     }

When compiled and run we get:

>     $ java main
>     argv[0] = Cat
>     argv[1] = Dog
>     argv[2] = Cow
>     argv[3] = Goat
>     0:Dave
>     1:Mike
>     2:Susan
>     3:John
>     4:Michelle

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.

### 15.8.2 Expanding a Java object to multiple arguments

Suppose that you had a collection of C functions with arguments such as the following:

>     int foo(int argc, char **argv);

In the previous example, a typemap was written to pass a Java String array as the `char **argv`. This allows the function to be used from Java as follows:

>     example.foo(4, new String[]{"red", "green", "blue", "white"});

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:

>     %typemap(in) (int argc, char **argv) {
>         int i = 0;
>         $1 = (*jenv)->GetArrayLength(jenv, $input);
>         $2 = (char **) malloc(($1+1)*sizeof(char *));
>         /* make a copy of each string */
>         for (i = 0; i<$1; i++) {
>             jstring j_string = (jstring)(*jenv)->GetObjectArrayElement(jenv, $input, i);
>             const char * c_string = (*jenv)->GetStringUTFChars(jenv, j_string, 0);
>             $2[i] = malloc(strlen((c_string)+1)*sizeof(const char *));
>             strcpy($2[i], c_string);
>             (*jenv)->ReleaseStringUTFChars(jenv, j_string, c_string);
>             (*jenv)->DeleteLocalRef(jenv, j_string);
>         }
>         $2[i] = 0;
>     }

>     %typemap(freearg) (int argc, char **argv) {
>         int i;
>         for (i=0; i<$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"

When writing a multiple-argument typemap, each of the types is referenced by a variable such as `$1` or `$2`. The typemap code simply fills in the appropriate values from the supplied Java parameter.

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:

>     example.foo(new String[]{"red", "green", "blue", "white"});

### 15.8.3 Using typemaps to return arguments

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 `typemaps.i` 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.

Now we are going to outline an alternative approach to using arrays for C pointers. The INOUT typemap uses a `double[]` array for receiving and returning the `double*` parameters. In this approach we are able to use a Java class `myDouble` instead of `double[]` arrays where the C pointer `double*` is required. Here is our example function:

>     /* Returns a status value and two values in out1 and out2 */
>     int spam(double a, double b, double *out1, double *out2);

If we define a structure `MyDouble` containing a `double` member variable and use some typemaps we can solve this problem. For example we could put the following through SWIG:

>     %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 OUTVALUE 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->FindClass("MyDouble");
>         jfieldID fid = jenv->GetFieldID(clazz, "swigCPtr", "J");
>         jlong cPtr = jenv->GetLongField($input, fid);
>         MyDouble *pMyDouble = NULL;
>         *(MyDouble *)&pMyDouble = *(MyDouble *)&cPtr;
>         $1 = &pMyDouble->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);

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.

What the typemaps do are make the named `double*` function parameters use our new `MyDouble` wrapper structure. The "in" typemap takes this structure, gets the C++ pointer to it, takes the `double value` member variable and passes it to the C++ `spam` function. In Java, when the function returns, we use the SWIG created `getValue()` function to get the output value. The following Java program demonstrates this:

>     // File: main.java

>     public class main {

>       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());
>       }
>     }

When compiled and run we get:

>     $ java main
>     1 12.0  340.0

### 15.8.4 Adding Java downcasts to polymorphic return types

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 follow code:

>     %include "std_string.i"

>     #include <iostream>
>     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 << "Ambulance started" << endl;
>         }
>         void sound_siren() {
>             cout << vol << " siren sounded!" << endl;
>         }
>     ...
>     };

>     Vehicle *vehicle_factory() {
>         return new Ambulance("Very loud");
>     }

If we execute the following Java code:

>     Vehicle vehicle = example.vehicle_factory();
>     vehicle.start();

>     Ambulance ambulance = (Ambulance)vehicle;
>     ambulance.sound_siren();

We get:

>     Ambulance started
>     java.lang.ClassCastException
>             at main.main(main.java:16)

Even though we know from examination of the C++ code that `vehicle_factory` returns an object of type `Ambulance`, 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 `vehicle_factory()`. Usually this is not a problem as virtual functions do work by default, such as in the case of `start()`. There are a few solutions to getting downcasts to work.

The first is not to use a Java cast but a call to C++ to make the cast. Add this to your code:

>     %exception Ambulance::dynamic_cast(Vehicle *vehicle) {
>         $action
>         if (!result) {
>             jclass excep = jenv->FindClass("java/lang/ClassCastException");
>             if (excep) {
>                 jenv->ThrowNew(excep, "dynamic_cast exception");
>             }
>         }
>     }
>     %extend Ambulance {
>         static Ambulance *dynamic_cast(Vehicle *vehicle) {
>             return dynamic_cast<Ambulance *>(vehicle);
>         }
>     };

It would then be used from Java like this

>     Ambulance ambulance = Ambulance.dynamic_cast(vehicle);
>     ambulance.sound_siren();

Should `vehicle` not be of type `ambulance` then a Java `ClassCastException` 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 `vehicle_factory`:

>     %typemap(out) Vehicle * {
>         Ambulance *downcast = dynamic_cast<Ambulance *>($1);
>         *(Ambulance **)&$result = downcast;
>     }

>     %typemap(javaout) Vehicle * {
>         return new Ambulance($jnicall, $owner);
>       }

Here we are using our knowledge that `vehicle_factory` always returns type `Ambulance` so that the Java proxy is created as a type `Ambulance`. If `vehicle_factory` can manufacture any type of `Vehicle` 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:

>     class FireEngine : public Vehicle {
>     public:
>         FireEngine() {}
>         virtual void start() {
>             cout << "FireEngine started" << endl;
>         }
>         void roll_out_hose() {
>             cout << "Hose rolled out" << endl;
>         }
>      ...
>     };
>     Vehicle *vehicle_factory(int vehicle_number) {
>         if (vehicle_number == 0)
>             return new Ambulance("Very loud");
>         else
>             return new FireEngine();
>     }

To be able to downcast with this sort of Java code:

>     FireEngine fireengine = (FireEngine)example.vehicle_factory(1);
>     fireengine.roll_out_hose();
>     Ambulance ambulance = (Ambulance)example.vehicle_factory(0);
>     ambulance.sound_siren();

the following typemaps 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.

>     %typemap(jni) Vehicle * "jobject"
>     %typemap(jtype) Vehicle * "Vehicle"
>     %typemap(jstype) Vehicle * "Vehicle"
>     %typemap(javaout) Vehicle * {
>         return $jnicall;
>       }

>     %typemap(out) Vehicle * {
>         Ambulance *ambulance = dynamic_cast<Ambulance *>($1);
>         FireEngine *fireengine = dynamic_cast<FireEngine *>($1);
>         if (ambulance) {
>             // call the Ambulance(long cPtr, boolean cMemoryOwn) constructor
>             jclass clazz = jenv->FindClass("Ambulance");
>             if (clazz) {
>                 jmethodID mid = jenv->GetMethodID(clazz, "", "(JZ)V");
>                 if (mid) {
>                     jlong cptr = 0;
>                     *(Ambulance **)&cptr = ambulance;
>                     $result = jenv->NewObject(clazz, mid, cptr, false);
>                 }
>             }
>         } else if (fireengine) {
>             // call the FireEngine(long cPtr, boolean cMemoryOwn) constructor
>             jclass clazz = jenv->FindClass("FireEngine");
>             if (clazz) {
>                 jmethodID mid = jenv->GetMethodID(clazz, "", "(JZ)V");
>                 if (mid) {
>                     jlong cptr = 0;
>                     *(FireEngine **)&cptr = fireengine;
>                     $result = jenv->NewObject(clazz, mid, cptr, false);
>                 }
>             }
>         }
>         else {
>             cout << "Unexpected type " << endl;
>         }

>         if (!$result)
>             cout << "Failed to create new java object" << endl;
>     }

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.

### 15.8.5 Adding an equals method to the Java classes

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 `equals()` method to check whether two objects are equivalent. An equals method is easily added to all proxy classes. For example:

>     %typemap(javacode) SWIGTYPE %{
>       public boolean equals(Object obj) {
>         boolean equal = false;
>         if (obj instanceof $javaclassname)
>           equal = ((($javaclassname)obj).swigCPtr == this.swigCPtr);
>         return equal;
>       }
>     %}

>     class Foo { };
>     Foo* returnFoo(Foo *foo) { return foo; }

The following would display `false` without the `javacode` typemap above. With the typemap defining the `equals` method the result is `true`.

>     Foo foo1 = new Foo();
>     Foo foo2 = example.returnFoo(foo1);
>     System.out.println("foo1? " + foo1.equals(foo2));

### 15.8.6 Void pointers and a common Java base class

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 `swigCPtr` 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 `swigCPtr` 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:

>     %typemap(javabase) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [], SWIGTYPE (CLASS::*) "SWIG"

>     %typemap(javacode) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [], SWIGTYPE (CLASS::*) %{
>       protected long getPointer() {
>         return swigCPtr;
>       }
>     %}

Define new base class called SWIG:

>     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);
>       }
>     }

This example contains some useful functionality which you may want in your code.

- It has an `equals()` method. Unlike the previous example, the method code isn't replicated in all classes.
- 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.

## 15.9 Java class polymorphism (aka "directors" and "upcalls")

### 15.9.1 What are directors?

Like the Python module, Java supports the directors feature. The directors feature creates a hidden C++ director class that overrides the wrapped C++ class's virtual methods. The hidden C++ class upcalls from C++ to Java when a Java object is derived from Java proxy class and the called method is overridden by the derived subclass. The director class calls the wrapped C++ class's method if the called method isn't overridden by the proxy-derived Java class. If the wrapped C++ class's method is pure virtual, the director class throws a Java RuntimeException as a reminder.

Consider the following SWIG interface file:

    %module(directors="1") example

    %feature("director") example

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

Notes:

1. `%module(directors="1") example` enables the directors feature for the interface file. The director feature is not turned on by default.
2. `%feature("director") example` enables the director feature for all classes in the SWIG interface file. The director feature can be enabled for individual classes using `%feature("director") director_example`

The following `director_derived` Java class overrides the C++ and Java proxy class `director_example`'s upcall_method() method. When C++ code invokes `director_example::upcall_method()`, the SWIG-generated C++ code redirects the call via JNI to the Java `director_derived` subclass. The following code would output "director_derived::upcall_method() invoked". Naturally, the SWIG generated C++ code and the generated Java intermediate class marshall and convert arguments between C++ and Java when needed.

    public class director_derived extends director_example
    {
      public director_derived()
      { }

      public void upcall_method()
      {
        System.out.println("director_derived::upcall_method() invoked.");
      }
    }

### 15.9.2 Director-specific typemaps

The Java directors feature requires the `%typemap(directorin)`, the `%typemap(javadirectorin)` and the `%typemap(javadirectorout)` type maps in order to work properly. The `%typemap(javapackage)` is an optional typemap used to identify the Java package path for individual C++/SWIG-generated proxy classes.

#### 15.9.2.1 %typemap(directorin)

The `%typemap(directorin)` type map 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. For example, integers are converted as follows:

    %typemap(directorin,parse="I") int "$input = (jint) $1;"

`$input` is the SWIG name of the JNI temporary variable passed to Java in the upcall. The `parse="I"` will put an `I` into the JNI field descriptor that identifies the Java method that will be upcalled. For more about JNI field descriptors and their importance, refer to Sun's JNI documentation.

A typemap for C character strings is:

    %typemap(directorin,parse="Ljava/lang/String;") char *
    %{ $input = jenv->NewStringUTF($1); %}

User-defined types have the default jnidesc typemap "`L$packagepath/$javaclassname;`" where `$packagepath` is the package name passed from the SWIG command line and `$javaclassname` is the Java proxy class' name. If the Java package name is not set, '$packagepath/' will be removed from the resulting output JNI field descriptor. DO NOT FORGET THE ';' terminating JNI field descriptors starting with 'L' (aka Java objects). If the ';' is left out, Java will generate a "method not found" warning.

#### 15.9.2.2 %typemap(javadirectorin)

This typemap specifies argument conversion in the generated Java upcall code. Normally, this typemap should be specified as:

    %typemap(javadirectorin) user_def_class_here "$jniinput"

`$jniinput` is the variable name passed from JNI to the intermediate class method's upcall code. For the default typemaps provided by the Java module, nothing special is done. The default handling for pointers and references, such as the `SWIGTYPE &` javadirectorin typemap, a temporary object is created to encapsulate the corresponding C++ object.

#### 15.9.2.3 %typemap(javadirectorout)

This typemap specifies argument conversion from the generated Java upcall code. Normally, this typemap should be specified as:

    %typemap(javadirectorout) user_def_class_here "$javacall"

$javacall is the SWIG-generated call to the derived class's method, which is about to be upcalled. For the default typemaps provided by the Java module, nothing special is done. The default handling for pointers and references, such as `SWIGTYPE &` javadirectorout typemap, the pointer is extracted from the object returned by the derived class's method call and returned back to the C++ code.

#### 15.9.2.4 %typemap(javapackage)

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. For example:
``

    // class Foo is handled in a different interface file:
    %import "Foo.i"

    %feature("director") Example;

    %inline {
      class Bar { };

      class Example {
      public:
        virtual ~Example();
        void     ping(Foo *arg1, Bar *arg2);
      };
    }

Assume that the Foo class is part of the Java package wombat.foo but the above interface file is part of the Java package wombat.example. Without the `javapackage` typemap, SWIG will assume that the Foo class belongs to wombat.example class. The corrected interface file looks like:
`

    // class Foo is handled in a different interface file:
    %import "Foo.i"
    %typemap("javapackage") Foo "wombat.foo";
    %feature("director") Example;

    %inline {
      class Bar { };

      class Example {
      public:
        virtual ~Example();
        void     ping(Foo *arg1, Bar *arg2);
      };
    }

`

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

    %typemap("javapackage") SWIGTYPE, SWIGTYPE *, SWIGTYPE & "package.for.most.classes";

    %typemap("javapackage") Package_2_class_one "package.for.other.classes";
    %typemap("javapackage") Package_3_class_two "package.for.another.set";
    /* etc */

The basic strategy here is to provide a default package typemap for the majority of the classes, only providing `javapackage` typemaps for the exceptions.

### 15.9.3 Director method recursion

The Java module's director code attempts to prevent recursion from the C++ shadow class's code to Java and back through the C++ shadow class. The most common reason for this loop is a typo in the Java derived class, e.g., ucpcall_method instead of upcall_method in the following Java code:

    public class director_derived extends director_example
    {
      public director_derived()
      { }

      public void ucpall_method()
      {
        System.out.println("director_derived::upcall_method() invoked.");
      }
    }

Another common typo is a mismatch between the arguments specified in the C++ method declaration and the Java subclass's method declaration. A `SWIG_JavaDirectorRicochet` exception is raised in Java when this particular problem is detected at runtime.

This feature can be turned off in the SWIG interface file can be turned off for the entire class,

    %feature("director:recursive") director_example

or selectively for individual methods:

    %feature("director:recursive") director_example::upcall_method()

### 15.9.4 Living with Java Directors

This section is intended to address frequently asked questions and frequently encountered problems when using Java directors.

1. When my program starts up, it complains that method_foo cannot be found in a Java method called swig_module_init. How do I fix this?

Open up the C++ wrapper source code file and look for `"method_foo"` (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.

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

Use the template's renamed name as the argument to the `javapackage` typemap:
``

    %template(VectorOfInt)          std::vector;
    %typemap(javapackage)           VectorOfInt             "your.package.here";

3. 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?

Normally, a non-director generated Java proxy class creates temporary Java objects as follows: ``

    public static void MyClass_method_upcall(MyClass self, long jarg1)
    {
      Foo           darg1 = new Foo(jarg1, false);

      self.method_upcall(darg1);
    }

Unfortunately, this loses the Java type information that is part of the underlying Foo director shadow class's java object pointer causing the type cast to fail. The SWIG Java module's director code attempts to correct the problem, but only for director-enabled classes, since the director class retains a global reference to its Java object. Thus, for director-enabled classes and only for director-enabled classes, the generated proxy Java code looks somthing like: `

    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);
    }

`
When you import a SWIG interface file containing class definitions, the classes you want to be director-enabled must be have the `feature("director")` 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.

The current "type symmetry" design will work for simple C++ inheritance, but will most likely fail for anything more compicated such as tree or diamond C++ inheritance hierarchies. Those who are interested in challenging problems are more than welcome to hack the `Java::Java_director_declaration` method in `Source/Modules/java.cxx`.

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

      public static Foo javaObjectFoo(Foo obj);

From your code, this method is invoked as follows:
`

    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 */
      }
    }

`
An good approach for managing downcasting is placing a static method in each derived class that performs the downcast from the superclass, e.g.,
`

    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 sublcass of Foo
          return null;
        }
      }
    }

`
Then change the code in MyClassDerived as follows:
`

    public class MyClassDerived extends MyClass {
      /* ... */
      public void method_upcall(Foo foo_object)
      {
        FooDerived    derived = FooDerived.downcastFooDerived(foo_object) : null);
        /* rest of your code here */
      }
    }

`
4. Why isn't the proxy class declared abstract? Why aren't the director upcall methods in the proxy class declared abstract?

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

    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 sublcass of Foo
          return null;
        }
      }
    }

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 `method_upcall()` method.

## 15.10 Odds and ends

### 15.10.1 JavaDoc comments

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 `%javamethodmodifiers` 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 `jniclassimports` or `jniclassclassmodifiers` pragmas can also be used for adding intermediary JNI class comments and likewise the `moduleimports` or `moduleclassmodifiers` pragmas for the module class. Here is an example adding in a proxy class and method comment:

>     %javamethodmodifiers Barmy::lose_marbles() "
>       /**
>         * Calling this method will make you mad.
>         * Use with <b>utmost</b> caution.
>         */
>       public";

>     %typemap(javaimports) Barmy "
>     /** The crazy class. Use as a last resort. */"

>     class Barmy {
>     public:
>       void lose_marbles() {}
>     };

Note the "public" added at the end of the `%javamethodmodifiers` as this is the default for this feature. The generated proxy class with JavaDoc comments is then as follows:

>     /** The crazy class. Use as a last resort. */
>     public class Barmy {
>     ...
>       /**
>         * Calling this method will make you mad.
>         * Use with <b>utmost</b> caution.
>         */
>       public void lose_marbles() {
>         ...
>       }
>     ...
>     }

### 15.10.2 Functional interface without proxy classes

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.

Consider the example we looked at when examining proxy classes:

>     class Foo {
>     public:
>          int x;
>          int spam(int num, Foo* foo);
>     };

When using `-noproxy`, 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:

>     public class example {
>       public static void set_Foo_x(SWIGTYPE_p_Foo self, int x) {...}
>       public static int get_Foo_x(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) {...}
>     }

This approach is not nearly as natural as using proxy classes as the functions need to be used like this:

>     SWIGTYPE_p_Foo foo = example.new_Foo();
>     example.set_Foo_x(foo, 10);
>     int var = example.get_Foo_x(foo);
>     example.Foo_spam(foo, 20, foo);
>     example.delete_Foo(foo);

Unlike proxy classes, there is no attempt at tracking memory. All destructors have to be called manually for example the `delete_Foo(foo)` call above.

### 15.10.3 Using your own JNI functions

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 `%native` directive. If you don't want SWIG to wrap your JNI function then of course you can simply use the `%ignore` directive. However, if you want SWIG to generate just the Java code for a JNI function then use the `%native` 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:

>     %native (HandRolled) void HandRolled(int, char *);
>     %{
>     JNIEXPORT void JNICALL Java_packageName_moduleName_HandRolled(JNIEnv *, jclass, jlong, jstring);
>     %}

No C JNI function will be generated and the `Java_packageName_moduleName_HandRolled` function will be accessible using the SWIG generated Java native method call in the intermediary JNI class which will look like this:

>       public final static native void HandRolled(int jarg1, String jarg2);

and as usual this function is wrapped by another which for a global C function would appear in the module class:

>       public static void HandRolled(int arg0, String arg1) {
>         exampleJNI.HandRolled(arg0, arg1);
>       }

The `packageName` and `moduleName` 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 for `int` and `char *`.

In summary the `%native` 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.

### 15.10.4 Performance concerns and hints

If you're directly manipulating huge arrays of complex objects from Java, performance may suffer greatly when using the array functions in `arrays_java.i`. 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.

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 `javafinalize` typemap:

>     %typemap(javafinalize) SWIGTYPE ""

However, you will have to be careful about memory management and make sure that you code in a call to the `delete()` member function. This method calls the C++ destructor or `free()` for C code.

## 15.11 Examples

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 `make` in each example directory, then `java main` to see them running. For the benefit of Windows users, there are also Visual C++ project files in a couple of the Windows Examples.