SWIG and Java

# 15 SWIG and Java

- Preliminaries
  - Running SWIG
  - Additional Commandline Options
  - Getting the right header files
  - Compiling a dynamic module
  - Using your module
  - Compilation problems and compiling with C++
- Building Java Extensions under Windows
  - Running SWIG from Developer Studio
  - Using NMAKE
- A tour of basic C/C++ wrapping
  - Modules, packages and generated Java classes
  - Functions
  - Global variables
  - Constants
  - Enumerations
  - Pointers
  - Arrays
  - Structures
  - C++ classes
  - C++ inheritance
  - Pointers, references and pass by value
  - C++ overloaded functions
  - C++ namespaces
  - C++ templates
  - C++ Smart Pointers
- Further details on the generated Java classes
  - The JNI class
    - The 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
- Tips and techniques
  - Input and output parameters using primitive pointers and references
  - Simple pointers
  - Unbounded C Arrays
  - More on C arrays using the SWIG library
- Java typemaps
  - Default primitive type mappings
  - bit JVMs
  - What is a typemap?
  - Typemaps for mapping C/C++ types to Java types
  - Typemap 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
  - Pointer handling
  - Adding an equals method to the Java classes
  - Void pointers, null pointers and a common Java base class
- Odds and ends
  - Functional interface without proxy classes
  - Dynamic linking problems
  - Using your own JNI methods
  - Performance concerns and hints
  - Known bugs
- Examples

This chapter describes SWIG's support of Java. Java is one of the few non-scripting language modules in SWIG and an advantage of using Java over scripting languages is its type safety. The 100% Pure Java effort is a commendable concept, however in the real world programmers 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 Java functions 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 SWIG isn't particularly useful as the appropriate JNI code will have to be written by hand.

## 15.1 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.1.1 Running SWIG

The basics of getting a SWIG Java module up and running can be seen from one of SWIG's example Makefiles, but is also described here. To build a Java module, run SWIG using the `-java` option.

>     %swig -java example.i

This will produce a C or C++ file and many Java files. The file `example_wrap.c` contains all of the C code needed to build a Java module. To build a Java module, you will need to compile the file `example_wrap.c` to create a shared library.

### 15.1.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 <java package> | set the name of the package for the generated classes
-noproxy | Use the low-level functional interface, that is, do not generate proxy classes a.k.a. shadow classes

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

### 15.1.3 Getting the right header files

In order to compile, you need to locate the "jni.h" and "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.1.4 Compiling a dynamic module

The JNI code exists in a dynamic module or shared object and gets loaded by the JVM. To build a shared object 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

Unfortunately, the process of building a shared object file varies on every single machine so you may need to read up on the man pages for your C compiler and linker.

When building a dynamic module, the name of the output file is important. If the name of your SWIG module is "`example`", the name of the corresponding object 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.1.5 Using your module

To use your 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
>     $

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

For the most part, compiling a Java module is straightforward, but there are a number of potential problems :

- In order to build C++ modules, you may need to link with the C++ compiler using a command like ``c++ -shared example_wrap.o example.o -o libexample.so`'
- If building a dynamic C++ module using g++, you may also need to link against `libgcc.a`, `libg++.a`, and `libstc++.a` libraries.
- Make sure you are using the version of JDK header files matches the version of Java that you are running.

## 15.2 Building Java Extensions under Windows

Building a SWIG extension to Java under 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 to build extensions, you will need to have a JDK installed on your machine in order to read the JNI header files.

### 15.2.1 Running SWIG from Developer Studio

If you are developing your application within Microsoft developer studio, SWIG can be invoked as a custom build option. The process roughly follows these steps:

- 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`). Note: If using C++, choose a different suffix for the wrapper file `example_wrap.cxx`. Don't worry if the wrapper file doesn't exist yet--Developer 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.

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

Alternatively, SWIG extensions can be built by writing a Makefile for NMAKE. 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 building a Java extension

>     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 extension, run NMAKE (you may need to run `vcvars32` first). This is a pretty simplistic Makefile, but hopefully its enough to get you started.

## 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`, a 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. 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.

### 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 generated code looks like this:

>     public class example {
>       // 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();
>     }

Although these are final static variables, 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 using `%javaconst(1)` For example:

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

generates:

>     public class example {
>       // 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 above example also demonstrates how you can target particular constants 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.

### 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, STOUT, PILSNER };

generates:

>     public class example {
>       // 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();
>     }

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

Underneath the covers, pointers to C/C++ objects traverse the JNI boundary held in a Java `long`. 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). 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 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 Arrays

SWIG will handle arrays and are simple to use. Let's consider an example:

>     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[3];
>     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 0 0
>     global_array: 100 101 102 103

Note that for assigning array variables the length of the C variable is used, so as the example demonstrates 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 using arrays is 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 array library which can also be used and this approach is covered later.

### 15.3.8 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 in a similar manner as global arrays. Consider this example:

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

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

>     Bar b = new Bar();
>     int[] x1 = new int[16];
>     for (int i=0; i<x1.length; i++)
>         x1[i] = 99;
>     b.setX(x1);
>     int[] x2 = b.getX();

The two integer arrays, `x1` and `x2` are two different arrays but are of the same size and the same member values.

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.9 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.10 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.11 Pointers, references 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

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.

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.12 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.13 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.14 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.15 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 JNI class is considered.

### 15.4.1 The 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 function 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 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);
>     }

The JNI class contains the complete Java - C/C++ interface so all function calls go via the 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 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 JNI class can be changed from its default which 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 JNI class pragmas

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

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

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

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

The `jniclasscode` pragma is quite useful for adding in a static block for loading the shared object / 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 JNI class access attribute to public.

>     %pragma(java) jniclassclassmodifiers="public"

All the methods in the 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 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 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 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 ...
>     }

### 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 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;
>           super.delete();
>         }
>         swigCPtr = 0;
>       }

>       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 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, even create a null pointer, you will have to use some typemaps specific to the Java module to achieve this. The section on Java typemaps details how to specify a pure Java base class.

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 JNI function return types, namely those that have a void return and those that do not. This is useful for typemaps that will be used in JNI functions returning all return types. See the section on Typemap 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.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 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 do this is to apply the array typemaps that come with SWIG:

>     %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 the 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.6.4 More on C arrays using the SWIG library

The previous section shows how unbounded C arrays can be used with the SWIG array library. The library can also be used when the array syntax is used. The default array typemaps must be cleared first:

>     %clear int[ANY];

>     int sumitems(int first[], int nitems);
>     int bloggs[10];

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

A Java example:

>     SWIGTYPE_p_int bloggs = example.getBloggs();
>     for (int i=0; i<10000; i++) {                           // Set some values
>       example.intArray_setitem(bloggs,i,i);
>     }

>     int sum = example.sumitems(bloggs,10000);
>     System.out.println("Sum = " + sum);

Note that the `getBloggs()` function gets a pointer to the `Bloggs` array. If you were to use the generated `setBloggs(SWIGTYPE_p_int value)` function all the elements in `Bloggs` would be set from an array assuming the pointer in `value` points to an array of equal size to `Bloggs`.

## 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* | String | jstring

Arrays are implemented using the same mappings, for example a C array, `unsigned short[SIZE]`, is mapped to a Java array, `int[SIZE]`. Note that SWIG treats the C `char` type as a character and `char*` as a string. 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, double d[], unsigned long long e);

The module class method would be:

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

The JNI class would use the same types:

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

and the JNI function would look like this:

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

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 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 can be used with Java. The most important of these implement the mapping of C/C++ types to Java types. There are three of them:

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

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
char * | BYTE | various.i | input output | byte[] | Java byte array is converted to char array which is released afterwards
char ** | STRING_IN | various.i | input | String[] | \0 terminated array of \0 terminated strings the array is malloc-ed and released afterwards
char ** | STRING_OUT | various.i | output | String[] | &char* the argument is the address of an '\0' terminated string
char ** | STRING_RET | various.i | return | String[] | \0 terminated array of \0 terminated strings the array is not free'd.
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 ouput | String | Use for std::string mapping to Java String.

If a %typemap(in) is written, a %typemap(freearg) and %typemap(argout) may also need to be written. This is because 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. Take a look at the default typemaps in `java.swg`.

### 15.7.5 Typemap 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;
>         }
>       ...
>     }

### 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(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 ] proxyclassname(long cPtr, boolean cMemoryOwn) {...}
>     ... Other SWIG generated constructors ...
>     ... SWIG generated delete() method  ...
>     [ javagetcptr typemap ]
>     [ javacode typemap ]
>     ... proxy functions ...
>     }

The type wrapper class is similar in construction:

>     [ javaimports typemap ]
>     [ javamodifiers typemap ] class typewrappername extends [ javabase typemap ] implements [ javainterfaces typemap ] {
>     [ javaptrconstructormodifiers ] 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.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 [] %{
>       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[]"

>     /* 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[]"

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

>     /* 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 and use some typemaps we can solve this problem, for example we could put the following through SWIG:

>     %module example

>     %{
>     /* 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;
>     };
>     %}

>     /* Define a new structure to use instead of double* */
>     %inline %{
>     typedef struct {
>         double value;
>     } MyDouble;
>     %}

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

>     /* This tells SWIG what Java type to use */
>     %typemap(jtype) double* OutValue "MyDouble"
>     %typemap(jstype) double* OutValue "MyDouble"

>     /* This tells SWIG what the matching JNI type for the Java type is */
>     %typemap(jni) double* OutValue "jobject"

>     /* 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, is then able to get the 'double value' member variable to pass 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 Pointer handling

C pointers in the Java module are held in a simple Java long, whereas other SWIG language modules use an encoding of the pointer in a string. These scripting languages use the SWIG runtime type checker for type checking as they do not support static type checking by a compiler. The pointer is stored in a Java long which is a 64 bit number. However most JVMs are 32 bit applications so any JNI code must also be compiled as 32 bit. This means that the pointers in JNI code are also 32 bits. What happens for various reasons is on big endian machines the pointer is stored in the high order 4bytes, whereas on little endian machines the pointer is stored in the low order 4bytes. As a result, care must be taken if you intend to manipulate the pointer directly from Java.

### 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, null 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 [] "SWIG"

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

>       public static $javaclassname createNull() {
>         return new $javaclassname(0, false);
>       }
>     %}

Define new base class called SWIG:

>     public abstract class SWIG {
>       protected abstract long getPointer();

>       public boolean isNull() {
>         return (getPointer() == 0);
>       }

>       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 has an additional function in each class to determine whether a pointer is NULL.
- It enables void pointers to be created.
- 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 Odds and ends

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

The code to load a native library is `System.loadLibrary("name")`. This can fail and it can be due to a number of reasons.

The most common is an incorrect naming of the native library for the name passed to the `loadLibrary` function. The text passed to the `loadLibrary` function must not include the the extension name in the text, that is .dll or .so. The text must be name and not libname for all platforms. On Windows the native library must then be called name.dll and on Unix 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 Unix make sure that your LD_LIBRARY_PATH contains the path to the native library. On Windows make sure the path environment variable contains the path to the native library. SWIG code usually works if you have LD_LIBRARY_PATH set to '.' (or no modification to path in Windows).

The native library will also not load if there are any unresolved symbols in the compiled C/C++ code. Unresolved symbols will be described if you use the -verbose:jni commandline switch when running Java.

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.

### 15.9.3 Using your own JNI methods

Perhaps you have some hand written JNI functions that you want to use in addition to the SWIG generated JNI functions? This can be accomplished using the `%native` directive or the `%ignore` directive depending on what you want.

If you don't want SWIG to wrap your JNI function as you have written the Java native function declaration in addition to the JNI function, simply use the `%ignore` directive.

Alternatively you may want SWIG to help out and do some work by using the `%native` directive, for example:

>     %typemap (jtype) SomeCType "SomeJavaClass";
>     %typemap (jstype) SomeCType "SomeJavaClass";
>     %native (HandRolledJavaName) int HandRolledCName(long, char*, SomeCType);
>     %{
>     JNIEXPORT jint JNICALL
>     Java_modulename_HandRolled ( JNIEnv *jenv, jclass jcls, jint net, jstring path, jobject SomeJavaClass)
>     {
>     /* implementation */
>     }
>     %}

No C/C++ code will be generated and the `Java_modulename_HandRolled` function will be unmodified and accessible using the SWIG generated Java native function call which will look something like this:

>       public final static native int HandRolledJavaName(int jarg1, String jarg2, SomeJavaClass jarg3);

What is happening here is the `%native` directive is telling SWIG to generate the module Java native method declaration, but not the JNI C code for a (possibly non-existent) C function called `HandRolledCName`. To accomplish this SWIG needs to be told about the mapping of (possibly non-existent) C types to Java types, either using the built in mapping (char* -> String) or the supplied one using the jtype typemap (SomeCType -> SomeJavaClass). This directive is only really useful if you want to mix your own JNI code and the SWIG generated code into one C/C++ file or mix your own JNI function calls into a SWIG generated Java class.

### 15.9.4 Performance concerns and hints

If you're directly manipulating huge arrays of complex objects from Java, performance may suffer greatly. In these cases, you should consider implementing the functions in C or think of ways to optimize the problem. 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.9.5 Known bugs

Known bugs at release:

- Pointers to member functions don't work yet.

If you need these, have a go at writing your own typemaps.

## 15.10 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 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 examples.