This chapter describes SWIG's support of Java. It covers most SWIG features, but certain low-level details are covered in less depth than in earlier chapters.
The 100% Pure Java effort is a commendable concept, however in the real world programmers often either need to re-use their existing code or in some situations want to take advantage of Java but are forced into using some native (C/C++) code. The Java extension to SWIG makes it very easy to plumb in existing C/C++ code for access from Java, as SWIG writes the Java Native Interface (JNI) code for you. It is different to using the 'javah' tool as SWIG will wrap existing C/C++ code, whereas javah takes 'native' Java function declarations and creates C/C++ function prototypes. SWIG wraps C/C++ code using Java proxy classes and is very useful if you want to have access to large amounts of C/C++ code from Java. If only one or two JNI functions are needed then using SWIG may be overkill. SWIG enables a Java program to easily call into C/C++ code from Java. Historically, SWIG was not able to generate any code to call into Java code from C++. However, SWIG now supports full cross language polymorphism and code is generated to call up from C++ to Java when wrapping C++ virtual methods.
Java is one of the few non-scripting language modules in SWIG. As SWIG utilizes the type safety that the Java language offers, it takes a somewhat different approach to that used for scripting languages. In particular runtime type checking and the runtime library are not used by Java. This should be borne in mind when reading the rest of the SWIG documentation. This chapter on Java is relatively self contained and will provide you with nearly everything you need for using SWIG and Java. However, the "SWIG Basics" chapter will be a useful read in conjunction with this one.
This chapter starts with a few practicalities on running SWIG and compiling the generated code. If you are looking for the minimum amount to read, have a look at the sections up to and including the tour of basic C/C++ wrapping section which explains how to call the various C/C++ code constructs from Java. Following this section are details of the C/C++ code and Java classes that SWIG generates. Due to the complexities of C and C++ there are different ways in which C/C++ code could be wrapped and called from Java. SWIG is a powerful tool and the rest of the chapter details how the default code wrapping can be tailored. Various customisation tips and techniques using SWIG directives are covered. The latter sections cover the advanced techniques of using typemaps for complete control of the wrapping process.
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.
Suppose that you defined a SWIG module such as the following:
/* File: example.i */
%module test
%{
#include "stuff.h"
%}
int fact(int n);
To build a Java module, run SWIG using the -java option :
%swig -java example.i
If building C++, add the -c++ option:
$ swig -c++ -java example.i
This creates two different files; a C/C++ source file example_wrap.c or example_wrap.cxx and numerous Java files. The generated C/C++ source file contains the JNI wrapper code that needs to be compiled and linked with the rest of your C/C++ application.
The name of the wrapper file is derived from the name of the input file. For example, if the input file is example.i, the name of the wrapper file is example_wrap.c. To change this, you can use the -o option. It is also possible to change the output directory that the Java files are generated into using -outdir.
The module name, specified with %module, determines the name of various generated classes as discussed later. Note that the module name does not define a Java package and by default, the generated Java classes do not have a Java package. The -package option described below can specify a Java package name to use.
The following sections have further practical examples and details on how you might go about compiling and using the generated files.
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 | |
|---|---|
| -nopgcpp | suppress the premature garbage collection prevention parameter |
| -noproxy | generate the low-level functional interface instead of proxy classes |
| -package <name> | set name of the Java package to <name> |
Their use will become clearer by the time you have finished reading this section on SWIG and Java.
In order to compile the C/C++ wrappers, the compiler needs the jni.h and jni_md.h header files which are part of the JDK. They are usually in directories like this:
/usr/java/include /usr/java/include/<operating_system>
The exact location may vary on your machine, but the above locations are typical.
The JNI code exists in a dynamic module or shared library (DLL on Windows) and gets loaded by the JVM. To build a shared library file, you need to compile your module in a manner similar to the following (shown for Solaris):
$ swig -java example.i $ gcc -c example_wrap.c -I/usr/java/include -I/usr/java/include/solaris $ ld -G example_wrap.o -o libexample.so
The exact commands for doing this vary from platform to platform. However, SWIG tries to guess the right options when it is installed. Therefore, you may want to start with one of the examples in the Examples/java directory. If that doesn't work, you will need to read the man-pages for your compiler and linker to get the right set of options. You might also check the SWIG Wiki for additional information. JNI compilation is a useful reference for compiling on different platforms.
Important
If you are going to use optimisations turned on with gcc (for example -O2), ensure you also compile with -fno-strict-aliasing. The GCC optimisations have become
more aggressive from gcc-4.0 onwards and will result in code that fails with strict aliasing optimisations turned on. See the C/C++ to Java typemaps section for more details.
The name of the shared library output file is important. If the name of your SWIG module is "example", the name of the corresponding shared library file should be "libexample.so" (or equivalent depending on your machine, see Dynamic linking problems for more information). The name of the module is specified using the %module directive or -module command line option.
To load your shared native library module in Java, simply use Java's System.loadLibrary method in a Java class:
// runme.java
public class runme {
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 runme 24 $
If it doesn't work have a look at the following section which discusses problems loading the shared library.
As shown in the previous section the code to load a native library (shared library) is System.loadLibrary("name"). This can fail with an UnsatisfiedLinkError exception and can be due to a number of reasons.
You may get an exception similar to this:
$ java runme
Exception in thread "main" java.lang.UnsatisfiedLinkError: no example in java.library.path
at java.lang.ClassLoader.loadLibrary(ClassLoader.java:1312)
at java.lang.Runtime.loadLibrary0(Runtime.java:749)
at java.lang.System.loadLibrary(System.java:820)
at runme.<clinit>(runme.java:5)
The most common cause for this is an incorrect naming of the native library for the name passed to the loadLibrary function. The string passed to the loadLibrary function must not include the file extension name in the string, that is .dll or .so. The string must be name and not libname for all platforms. On Windows the native library must then be called name.dll and on most Unix systems it must be called libname.so.
Another common reason for the native library not loading is because it is not in your path. On Windows make sure the path environment variable contains the path to the native library. On Unix make sure that your LD_LIBRARY_PATH contains the path to the native library. Adding paths to LD_LIBRARY_PATH can slow down other programs on your system so you may want to consider alternative approaches. For example you could recompile your native library with extra path information using -rpath if you're using GNU, see the GNU linker documentation (ld man page). You could use a command such as ldconfig (Linux) or crle (Solaris) to add additional search paths to the default system configuration (this requires root access and you will need to read the man pages).
The native library will also not load if there are any unresolved symbols in the compiled C/C++ code. The following exception is indicative of this:
$ java runme
Exception in thread "main" java.lang.UnsatisfiedLinkError: libexample.so: undefined
symbol: fact
at java.lang.ClassLoader$NativeLibrary.load(Native Method)
at java.lang.ClassLoader.loadLibrary0(ClassLoader.java, Compiled Code)
at java.lang.ClassLoader.loadLibrary(ClassLoader.java, Compiled Code)
at java.lang.Runtime.loadLibrary0(Runtime.java, Compiled Code)
at java.lang.System.loadLibrary(System.java, Compiled Code)
at runme.<clinit>(runme.java:5)
$
This error usually indicates that you forgot to include some object files or libraries in the linking of the native library file. Make sure you compile both the SWIG wrapper file and the code you are wrapping into the native library file. If you forget to compile and link in the SWIG wrapper file into your native library file, you will get a message similar to the following:
$ java runme Exception in thread "main" java.lang.UnsatisfiedLinkError: exampleJNI.gcd(II)I at exampleJNI.gcd(Native Method) at example.gcd(example.java:12) at runme.main(runme.java:18)
where gcd is the missing JNI function that SWIG generated into the wrapper file. Also make sure you pass all of the required libraries to the linker. The java -verbose:jni commandline switch is also a great way to get more information on unresolved symbols. One last piece of advice is to beware of the common faux pas of having more than one native library version in your path.
In summary, ensure that you are using the correct C/C++ compiler and linker combination and options for successful native library loading. If you are using the examples that ship with SWIG, then the Examples/Makefile must have these set up correctly for your system. The SWIG installation package makes a best attempt at getting these correct but does not get it right 100% of the time. The SWIG Wiki also has some settings for commonly used compiler and operating system combinations. The following section also contains some C++ specific linking problems and solutions.
On most machines, shared library files should be linked using the C++ compiler. For example:
% swig -c++ -java example.i % g++ -c -fpic example.cxx % g++ -c -fpic example_wrap.cxx -I/usr/java/j2sdk1.4.1/include -I/usr/java/ j2sdk1.4.1/include/linux % g++ -shared example.o example_wrap.o -o libexample.so
In addition to this, you may need to include additional library files to make it work. For example, if you are using the Sun C++ compiler on Solaris, you often need to add an extra library -lCrun like this:
% swig -c++ -java example.i % CC -c example.cxx % CC -c example_wrap.cxx -I/usr/java/include -I/usr/java/include/solaris % CC -G example.o example_wrap.o -L/opt/SUNWspro/lib -o libexample.so -lCrun
If you aren't entirely sure about the linking for C++, you might look at an existing C++ program. On many Unix machines, the ldd command will list library dependencies. This should give you some clues about what you might have to include when you link your shared library. For example:
$ ldd swig
libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000)
libm.so.6 => /lib/libm.so.6 (0x4005b000)
libc.so.6 => /lib/libc.so.6 (0x40077000)
/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
$
Finally make sure the version of JDK header files matches the version of Java that you are running as incompatibilities could lead to compilation problems or unpredictable behaviour.
Building on Windows is roughly similar to the process used with Unix. You will want to produce a DLL that can be loaded by the Java Virtual Machine. This section covers the process of using SWIG with Microsoft Visual C++ 6 although the procedure may be similar with other compilers. In order for everything to work, you will need to have a JDK installed on your machine in order to read the JNI header files.
If you are developing your application within Microsoft Visual studio, SWIG can be invoked as a custom build option. The Examples\java directory has a few Windows Examples containing Visual Studio project (.dsp) files. The process to re-create the project files for a C project are roughly:
Note: If using C++, choose a C++ suffix for the wrapper file, for example example_wrap.cxx. Use _wrap.cxx instead of _wrap.c in the instructions above and add -c++ when invoking swig.
Now, assuming all went well, SWIG will be automatically invoked when you build your project. When doing a build, any changes made to the interface file will result in SWIG being automatically invoked to produce a new version of the wrapper file.
The Java classes that SWIG output should also be compiled into .class files. To run the native code in the DLL (example.dll), make sure that it is in your path then run your Java program which uses it, as described in the previous section. If the library fails to load have a look at Dynamic linking problems.
Alternatively, a Makefile for use by NMAKE can be written. Make sure the environment variables for MSVC++ are available and the MSVC++ tools are in your path. Now, just write a short Makefile like this :
# Makefile for using SWIG and Java for C code
SRCS = example.c
IFILE = example
INTERFACE = $(IFILE).i
WRAPFILE = $(IFILE)_wrap.c
# Location of the Visual C++ tools (32 bit assumed)
TOOLS = c:\msdev
TARGET = example.dll
CC = $(TOOLS)\bin\cl.exe
LINK = $(TOOLS)\bin\link.exe
INCLUDE32 = -I$(TOOLS)\include
MACHINE = IX86
# C Library needed to build a DLL
DLLIBC = msvcrt.lib oldnames.lib
# Windows libraries that are apparently needed
WINLIB = kernel32.lib advapi32.lib user32.lib gdi32.lib comdlg32.lib winspool.lib
# Libraries common to all DLLs
LIBS = $(DLLIBC) $(WINLIB)
# Linker options
LOPT = -debug:full -debugtype:cv /NODEFAULTLIB /RELEASE /NOLOGO \
/MACHINE:$(MACHINE) -entry:_DllMainCRTStartup@12 -dll
# C compiler flags
CFLAGS = /Z7 /Od /c /nologo
JAVA_INCLUDE = -ID:\jdk1.3\include -ID:\jdk1.3\include\win32
java::
swig -java -o $(WRAPFILE) $(INTERFACE)
$(CC) $(CFLAGS) $(JAVA_INCLUDE) $(SRCS) $(WRAPFILE)
set LIB=$(TOOLS)\lib
$(LINK) $(LOPT) -out:example.dll $(LIBS) example.obj example_wrap.obj
javac *.java
To build the DLL and compile the java code, run NMAKE (you may need to run vcvars32 first). This is a pretty simplistic Makefile, but hopefully its enough to get you started. Of course you may want to make changes for it to work for C++ by adding in the -c++ command line switch for swig and replacing .c with .cxx.
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.
The SWIG %module directive specifies the name of the Java module. When you specify `%module example', the module name determines the name of some of the generated files in the module. The generated code consists of a module class file example.java, an intermediary JNI class file, exampleJNI.java as well as numerous other Java proxy class files. Each proxy class is named after the structs, unions and classes you are wrapping. You may also get a constants interface file if you are wrapping any unnamed enumerations or constants, for example exampleConstants.java. When choosing a module name, make sure you don't use the same name as one of the generated proxy class files nor a Java keyword. Sometimes a C/C++ type cannot be wrapped by a proxy class, for example a pointer to a primitive type. In these situations a type wrapper class is generated. Wrapping an enum generates an enum class, either a proper Java enum or a Java class that simulates the enums pattern. Details of all these generated classes will unfold as you read this section.
The JNI (C/C++) code is generated into a file which also contains the module name, for example example_wrap.cxx or example_wrap.c. These C or C++ files complete the contents of the module.
The generated Java classes can be placed into a Java package by using the -package commandline option. This is often combined with the -outdir to specify a package directory for generating the Java files.
swig -java -package com.bloggs.swig -outdir com/bloggs/swig example.i
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));
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
...
%inline %{
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:
%{
extern char *path;
%}
%immutable;
extern char *path;
%mutable;
The %immutable directive stays in effect until it is explicitly disabled or cleared using %mutable. See the Creating read-only variables section for further details.
If you just want to make a specific variable immutable, supply a declaration name. For example:
%{
extern char *path;
%}
%immutable path;
...
extern char *path; // Read-only (due to %immutable)
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 initialized by making a JNI call to get their value. The constants are generated into the constants interface and look like this:
public interface exampleConstants {
public final static double PI = exampleJNI.PI_get();
public final static String VERSION = exampleJNI.VERSION_get();
public final static int FOO = exampleJNI.FOO_get();
public final static String path = exampleJNI.path_get();
}
Note that SWIG has inferred the C type and used an appropriate Java type that will fit the range of all possible values for the C type. By default SWIG generates runtime constants. They are not compiler constants that can, for example, be used in a switch statement. This can be changed by using the %javaconst(flag) directive. It works like all the other %feature directives. The default is %javaconst(0). It is possible to initialize all wrapped constants from pure Java code by placing a %javaconst(1) before SWIG parses the constants. Putting it at the top of your interface file would ensure this. Here is an example:
%javaconst(1); %javaconst(0) BIG; %javaconst(0) LARGE; #define EXPRESSION (0x100+5) #define BIG 1000LL #define LARGE 2000ULL
generates:
public interface exampleConstants {
public final static int EXPRESSION = (0x100+5);
public final static long BIG = exampleJNI.BIG_get();
public final static java.math.BigInteger LARGE = exampleJNI.LARGE_get();
}
Note that SWIG has inferred the C long long type from BIG and used an appropriate Java type (long) as a Java long is the smallest sized Java type that will take all possible values for a C long long. Similarly for LARGE.
Be careful using the %javaconst(1) directive as not all C code will compile as Java code. For example neither the 1000LL value for BIG nor 2000ULL for LARGE above would generate valid Java code. The example demonstrates how you can target particular constants (BIG and LARGE) with %javaconst. SWIG doesn't use %javaconst(1) as the default as it tries to generate code that will always compile. However, using a %javaconst(1) at the top of your interface file is strongly recommended as the preferred compile time constants will be generated and most C constants will compile as Java code and in any case the odd constant that doesn't can be fixed using %javaconst(0).
There is an alternative directive which can be used for these rare constant values that won't compile as Java code. This is the %javaconstvalue(value) directive, where value is a Java code replacement for the C constant and can be either a string or a number. This is useful if you do not want to use either the parsed C value nor a JNI call, such as when the C parsed value will not compile as Java code and a compile time constant is required. The same example demonstrates this:
%javaconst(1);
%javaconstvalue("new java.math.BigInteger(\"2000\")") LARGE;
%javaconstvalue(1000) BIG;
#define EXPRESSION (0x100+5)
#define BIG 1000LL
#define LARGE 2000ULL
Note the string quotes for "2000" are escaped. The following is then generated:
public interface exampleConstants {
public final static int EXPRESSION = (0x100+5);
public final static long BIG = 1000;
public final static java.math.BigInteger LARGE = new java.math.BigInteger("2000");
}
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. The exception to this rule are static const integral values defined within a class/struct, where they are wrapped as constants, eg:.
struct Maths {
static const int FIVE = 5;
};
Compatibility Note: In SWIG-1.3.19 and earlier releases, the constants were generated into the module class and the constants interface didn't exist. Backwards compatibility is maintained as the module class implements the constants interface (even though some consider this type of interface implementation to be bad practice):
public class example implements exampleConstants {
}
You thus have the choice of accessing these constants from either the module class or the constants interface, for example, example.EXPRESSION or exampleConstants.EXPRESSION. Or if you decide this practice isn't so bad and your own class implements exampleConstants, you can of course just use EXPRESSION.
SWIG handles both named and unnamed (anonymous) enumerations. There is a choice of approaches to wrapping named C/C++ enums. This is due to historical reasons as SWIG's initial support for enums was limited and Java did not originally have support for enums. Each approach has advantages and disadvantages and it is important for the user to decide which is the most appropriate solution. There are four approaches of which the first is the default approach based on the so called Java typesafe enum pattern. The second generates proper Java enums. The final two approaches use simple integers for each enum item. Before looking at the various approaches for wrapping named C/C++ enums, anonymous enums are considered.
There is no name for anonymous enums and so they are handled like constants. For example:
enum { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
is wrapped into the constants interface, in a similar manner as constants (see previous section):
public interface exampleConstants {
public final static int ALE = exampleJNI.ALE_get();
public final static int LAGER = exampleJNI.LAGER_get();
public final static int STOUT = exampleJNI.STOUT_get();
public final static int PILSNER = exampleJNI.PILSNER_get();
public final static int PILZ = exampleJNI.PILZ_get();
}
The %javaconst(flag) and %javaconstvalue(value) directive introduced in the previous section on constants can also be used with enums. As is the case for constants, the default is %javaconst(0) as not all C values will compile as Java code. However, it is strongly recommended to add in a %javaconst(1) directive at the top of your interface file as it is only on very rare occasions that this will produce code that won't compile under Java. Using %javaconst(1) will ensure compile time constants are generated, thereby allowing the enum values to be used in Java switch statements. Example usage:
%javaconst(1);
%javaconst(0) PILSNER;
enum { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
generates:
public interface exampleConstants {
public final static int ALE = 0;
public final static int LAGER = 10;
public final static int STOUT = LAGER + 1;
public final static int PILSNER = exampleJNI.PILSNER_get();
public final static int PILZ = PILSNER;
}
As in the case of constants, you can access them through either the module class or the constants interface, for example, example.ALE or exampleConstants.ALE.
This is the default approach to wrapping named enums. The typesafe enum pattern is a relatively well known construct to work around the lack of enums in versions of Java prior to JDK 1.5. It basically defines a class for the enumeration and permits a limited number of final static instances of the class. Each instance equates to an enum item within the enumeration. The implementation is in the "enumtypesafe.swg" file. Let's look at an example:
%include "enumtypesafe.swg" // optional as typesafe enums are the default
enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
will generate:
public final class Beverage {
public final static Beverage ALE = new Beverage("ALE");
public final static Beverage LAGER = new Beverage("LAGER", exampleJNI.LAGER_get());
public final static Beverage STOUT = new Beverage("STOUT");
public final static Beverage PILSNER = new Beverage("PILSNER");
public final static Beverage PILZ = new Beverage("PILZ", exampleJNI.PILZ_get());
[... additional support methods omitted for brevity ...]
}
See Typesafe enum classes to see the omitted support methods. Note that the enum item with an initializer (LAGER) is initialized with the enum value obtained via a JNI call. However, as with anonymous enums and constants, use of the %javaconst directive is strongly recommended to change this behaviour:
%include "enumtypesafe.swg" // optional as typesafe enums are the default
%javaconst(1);
enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
will generate:
public final class Beverage {
public final static Beverage ALE = new Beverage("ALE");
public final static Beverage LAGER = new Beverage("LAGER", 10);
public final static Beverage STOUT = new Beverage("STOUT");
public final static Beverage PILSNER = new Beverage("PILSNER");
public final static Beverage PILZ = new Beverage("PILZ", PILSNER);
[... additional support methods omitted for brevity ...]
}
The generated code is easier to read and more efficient as a true constant is used instead of a JNI call. As is the case for constants, the default is %javaconst(0) as not all C values will compile as Java code. However, it is recommended to add in a %javaconst(1) directive at the top of your interface file as it is only on very rare occasions that this will produce code that won't compile under Java. The %javaconstvalue(value) directive can also be used for typesafe enums. Note that global enums are generated into a Java class within whatever package you are using. C++ enums defined within a C++ class are generated into a static final inner Java class within the Java proxy class.
Typesafe enums have their advantages over using plain integers in that they they can be used in a typesafe manner. However, there are limitations. For example, they cannot be used in switch statements and serialization is an issue. Please look at the following references for further information: Replace Enums with Classes in Effective Java Programming on the Sun website, Create enumerated constants in Java JavaWorld article, Java Tip 133: More on typesafe enums and Java Tip 122: Beware of Java typesafe enumerations JavaWorld tips.
Note that the syntax required for using typesafe enums is the same as that for proper Java enums. This is useful during the period that a project has to support legacy versions of Java. When upgrading to JDK 1.5 or later, proper Java enums could be used instead, without users having to change their code. The following section details proper Java enum generation.
Proper Java enums were only introduced in JDK 1.5 so this approach is only compatible with more recent versions of Java. Java enums have been designed to overcome all the limitations of both typesafe and type unsafe enums and should be the choice solution, provided older versions of Java do not have to be supported. In this approach, each named C/C++ enum is wrapped by a Java enum. Java enums, by default, do not support enums with initializers. Java enums are in many respects similar to Java classes in that they can be customised with additional methods. SWIG takes advantage of this feature to facilitate wrapping C/C++ enums that have initializers. In order to wrap all possible C/C++ enums using proper Java enums, the "enums.swg" file must be used. Let's take a look at an example.
%include "enums.swg"
%javaconst(1);
enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
will generate:
public enum Beverage {
ALE,
LAGER(10),
STOUT,
PILSNER,
PILZ(PILSNER);
[... additional support methods omitted for brevity ...]
}
See Proper Java enum classes to see the omitted support methods. The generated Java enum has numerous additional methods to support enums with initializers, such as LAGER above. Note that as with the typesafe enum pattern, enum items with initializers are by default initialized with the enum value obtained via a JNI call. However, this is not the case above as we have used the recommended %javaconst(1) to avoid the JNI call. The %javaconstvalue(value) directive covered in the Constants section can also be used for proper Java enums.
The additional support methods need not be generated if none of the enum items have initializers and this is covered later in the Simpler Java enums for enums without initializers section.
In this approach each enum item in a named enumeration is wrapped as a static final integer in a class named after the C/C++ enum name. This is a commonly used pattern in Java to simulate C/C++ enums, but it is not typesafe. However, the main advantage over the typesafe enum pattern is enum items can be used in switch statements. In order to use this approach, the "enumtypeunsafe.swg" file must be used. Let's take a look at an example.
%include "enumtypeunsafe.swg"
%javaconst(1);
enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
will generate:
public final class Beverage {
public final static int ALE = 0;
public final static int LAGER = 10;
public final static int STOUT = LAGER + 1;
public final static int PILSNER = STOUT + 1;
public final static int PILZ = PILSNER;
}
As is the case previously, the default is %javaconst(0) as not all C/C++ values will compile as Java code. However, again it is recommended to add in a %javaconst(1) directive. and the %javaconstvalue(value) directive covered in the Constants section can also be used for type unsafe enums. Note that global enums are generated into a Java class within whatever package you are using. C++ enums defined within a C++ class are generated into a static final inner Java class within the Java proxy class.
Note that unlike typesafe enums, this approach requires users to mostly use different syntax compared with proper Java enums. Thus the upgrade path to proper enums provided in JDK 1.5 is more painful.
This approach is similar to the type unsafe approach. Each enum item is also wrapped as a static final integer. However, these integers are not generated into a class named after the C/C++ enum. Instead, global enums are generated into the constants interface. Also, enums defined in a C++ class have their enum items generated directly into the Java proxy class rather than an inner class within the Java proxy class. In fact, this approach is effectively wrapping the enums as if they were anonymous enums and the resulting code is as per anonymous enums. The implementation is in the "enumsimple.swg" file.
Compatibility Note: SWIG-1.3.21 and earlier versions wrapped all enums using this approach. The type unsafe approach is preferable to this one and this simple approach is only included for backwards compatibility with these earlier versions of SWIG.
C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with incomplete type information. Here is a rather simple interface:
%module example FILE *fopen(const char *filename, const char *mode); int fputs(const char *, FILE *); int fclose(FILE *);
When wrapped, you will be able to use the functions in a natural way from Java. For example:
SWIGTYPE_p_FILE f = example.fopen("junk","w");
example.fputs("Hello World\n", f);
example.fclose(f);
C pointers in the Java module are stored in a Java long and cross the JNI boundary held within this 64 bit number. Many other SWIG language modules use an encoding of the pointer in a string. These scripting languages use the SWIG runtime type checker for dynamic type checking as they do not support static type checking by a compiler. In order to implement static type checking of pointers within Java, they are wrapped by a simple Java class. In the example above the FILE * pointer is wrapped with a type wrapper class called SWIGTYPE_p_FILE.
Once obtained, a type wrapper object can be freely passed around to different C functions that expect to receive an object of that type. The only thing you can't do is dereference the pointer from Java. Of course, that isn't much of a concern in this example.
As much as you might be inclined to modify a pointer value directly from Java, don't. The value is not necessarily the same as the logical memory address of the underlying object. The value will vary depending on the native byte-ordering of the platform (i.e., big-endian vs. little-endian). Most JVMs are 32 bit applications so any JNI code must also be compiled as 32 bit. The net result is pointers in JNI code are also 32 bits and are stored in the high order 4 bytes on big-endian machines and in the low order 4 bytes on little-endian machines. By design it is also not possible to manually cast a pointer to a new type by using Java casts as it is particularly dangerous especially when casting C++ objects. If you need to cast a pointer or change its value, consider writing some helper functions instead. For example:
%inline %{
/* C-style cast */
Bar *FooToBar(Foo *f) {
return (Bar *) f;
}
/* C++-style cast */
Foo *BarToFoo(Bar *b) {
return dynamic_cast<Foo*>(b);
}
Foo *IncrFoo(Foo *f, int i) {
return f+i;
}
%}
Also, if working with C++, you should always try to use the new C++ style casts. For example, in the above code, the C-style cast may return a bogus result whereas as the C++-style cast will return a NULL pointer if the conversion can't be performed.
If you wrap a C structure, it is wrapped by a Java class with getters and setters for access to the member variables. For example,
struct Vector {
double x,y,z;
};
is used as follows:
Vector v = new Vector(); v.setX(3.5); v.setY(7.2); double x = v.getX(); double y = v.getY();
The variable setters and getters are also based on the JavaBean design pattern already covered under the Global variables section. Similar access is provided for unions and the public data members of C++ classes.
This object is actually an instance of a Java class that has been wrapped around a pointer to the C structure. This instance doesn't actually do anything--it just serves as a proxy. The pointer to the C object is held in the Java proxy class in much the same way as pointers are held by type wrapper classes. Further details about Java proxy classes are covered a little later.
const members of a structure are read-only. Data members can also be forced to be read-only using the %immutable directive. For example:
struct Foo {
...
%immutable;
int x; /* Read-only members */
char *name;
%mutable;
...
};
When char * members of a structure are wrapped, the contents are assumed to be dynamically allocated using malloc or new (depending on whether or not SWIG is run with the -c++ option). When the structure member is set, the old contents will be released and a new value created. If this is not the behavior you want, you will have to use a typemap (described later).
If a structure contains arrays, access to those arrays is managed through pointers. For example, consider this:
struct Bar {
int x[16];
};
If accessed in Java, you will see behavior like this:
Bar b = new Bar(); SWIGTYPE_p_int x = b.getX();
This pointer can be passed around to functions that expect to receive an int * (just like C). You can also set the value of an array member using another pointer. For example:
Bar b = new Bar(); SWIGTYPE_p_int x = b.getX(); Bar c = new Bar(); c.setX(x); // Copy contents of b.x to c.x
For array assignment (setters not getters), SWIG copies the entire contents of the array starting with the data pointed to by b.x. In this example, 16 integers would be copied. Like C, SWIG makes no assumptions about bounds checking---if you pass a bad pointer, you may get a segmentation fault or access violation. The default wrapping makes it hard to set or get just one element of the array and so array access from Java is somewhat limited. This can be changed easily though by using the approach outlined later in the Wrapping C arrays with Java arrays and Unbounded C Arrays sections.
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
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();
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.
In C++, there are many different ways a function might receive and manipulate objects. For example:
void spam1(Foo *x); // Pass by pointer void spam2(Foo &x); // Pass by reference void spam3(Foo x); // Pass by value void spam4(Foo x[]); // Array of objects
In Java, there is no detailed distinction like this--specifically, there are only instances of classes. There are no pointers nor references. Because of this, SWIG unifies all of these types together in the wrapper code. For instance, if you actually had the above functions, it is perfectly legal to do this from Java:
Foo f = new Foo(); // Create a Foo example.spam1(f); // Ok. Pointer example.spam2(f); // Ok. Reference example.spam3(f); // Ok. Value. example.spam4(f); // Ok. Array (1 element)
Similar behavior occurs for return values. For example, if you had functions like this,
Foo *spam5(); Foo &spam6(); Foo spam7();
then all three functions will return a pointer to some Foo object. Since the third function (spam7) returns a value, newly allocated memory is used to hold the result and a pointer is returned (Java will release this memory when the returned object's finalizer is run by the garbage collector).
Working with null pointers is easy. A Java null can be used whenever a method expects a proxy class or typewrapper class. However, it is not possible to pass null to C/C++ functions that take parameters by value or by reference. If you try you will get a NullPointerException.
example.spam1(null); // Pointer - ok example.spam2(null); // Reference - NullPointerException example.spam3(null); // Value - NullPointerException example.spam4(null); // Array - ok
For spam1 and spam4 above the Java null gets translated into a NULL pointer for passing to the C/C++ function. The converse also occurs, that is, NULL pointers are translated into null Java objects when returned from a C/C++ function.
C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example, if you have two functions like this:
%module example void foo(int); void foo(char *c);
You can use them in Java in a straightforward manner:
example.foo(3); // foo(int)
example.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 cannot 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(515): Overloaded method spam(unsigned short) ignored. Method spam(int) at example.i:11 used.
To fix this, you either need to either rename or ignore one of the methods. For example:
%rename(spam_ushort) spam(unsigned short); ... void spam(int); void spam(unsigned short); // Now renamed to spam_ushort
or
%ignore spam(unsigned short); ... void spam(int); void spam(unsigned short); // Ignored
Any function with a default argument is wrapped by generating an additional function for each argument that is defaulted. For example, if we have the following C++:
%module example void defaults(double d=10.0, int i=0);
The following methods are generated in the Java module class:
public class example {
public static void defaults(double d, int i) { ... }
public static void defaults(double d) { ... }
public static void defaults() { ... }
}
It is as if SWIG had parsed three separate overloaded methods. The same approach is taken for static methods, constructors and member methods.
Compatibility note: Versions of SWIG prior to SWIG-1.3.23 wrapped these with a single wrapper method and so the default values could not be taken advantage of from Java. Further details on default arguments and how to restore this approach are given in the more general Default arguments section.
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 you want to keep their symbols separate, consider wrapping them as separate SWIG modules. Each SWIG module can be placed into a separate package.
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 <utility>
%}
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.
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 *
In the previous section, a high-level view of Java wrapping was presented. A key component of this wrapping is that structures and classes are wrapped by Java proxy classes and type wrapper classes are used in situations where no proxies are generated. This provides a very natural, type safe Java interface to the C/C++ code and fits in with the Java programming paradigm. However, a number of low-level details were omitted. This section provides a brief overview of how the proxy classes work and then covers the type wrapper classes. Finally enum classes are covered. First, the crucial intermediary JNI class is considered.
In the "SWIG basics" and "SWIG and C++" chapters, details of low-level structure and class wrapping are described. To summarize those chapters, if you have a global function and class like this
class Foo {
public:
int x;
int spam(int num, Foo* foo);
};
void egg(Foo* chips);
then SWIG transforms the class into a set of low-level procedural wrappers. These procedural wrappers essentially perform the equivalent of this C++ code:
Foo *new_Foo() {
return new Foo();
}
void delete_Foo(Foo *f) {
delete f;
}
int Foo_x_get(Foo *f) {
return f->x;
}
void Foo_x_set(Foo *f, int value) {
f->x = value;
}
int Foo_spam(Foo *f, int num, Foo* foo) {
return f->spam(num, foo);
}
These procedural function names don't actually exist, but their functionality appears inside the generated JNI functions. The JNI functions have to follow a particular naming convention so the function names are actually:
SWIGEXPORT jlong JNICALL Java_exampleJNI_new_1Foo(JNIEnv *jenv, jclass jcls);
SWIGEXPORT void JNICALL Java_exampleJNI_delete_1Foo(JNIEnv *jenv, jclass jcls,
jlong jarg1);
SWIGEXPORT void JNICALL Java_exampleJNI_Foo_1x_1set(JNIEnv *jenv, jclass jcls,
jlong jarg1, jobject jarg1_, jint jarg2);
SWIGEXPORT jint JNICALL Java_exampleJNI_Foo_1x_1get(JNIEnv *jenv, jclass jcls,
jlong jarg1, jobject jarg1_);
SWIGEXPORT jint JNICALL Java_exampleJNI_Foo_1spam(JNIEnv *jenv, jclass jcls,
jlong jarg1, jobject jarg1_, jint jarg2,
jlong jarg3, jobject jarg3_);
SWIGEXPORT void JNICALL Java_exampleJNI_egg(JNIEnv *jenv, jclass jcls,
jlong jarg1, jobject jarg1_);
For every JNI C function there has to be a static native Java function. These appear in the intermediary JNI class:
class exampleJNI {
public final static native long new_Foo();
public final static native void delete_Foo(long jarg1);
public final static native void Foo_x_set(long jarg1, Foo jarg1_, int jarg2);
public final static native int Foo_x_get(long jarg1, Foo jarg1_);
public final static native int Foo_spam(long jarg1, Foo jarg1_, int jarg2,
long jarg3, Foo jarg3_);
public final static native void egg(long jarg1, Foo jarg1_);
}
This class contains the complete Java - C/C++ interface so all function calls go via this class. As this class acts as a go-between for all JNI calls to C/C++ code from the Java proxy classes, type wrapper classes and module class, it is known as the intermediary JNI class.
You may notice that SWIG uses a Java long wherever a pointer or class object needs to be marshalled across the Java-C/C++ boundary. This approach leads to minimal JNI code which makes for better performance as JNI code involves a lot of string manipulation. SWIG favours generating Java code over JNI code as Java code is compiled into byte code and avoids the costly string operations needed in JNI code. This approach has a downside though as the proxy class might get collected before the native method has completed. You might notice above that there is an additional parameters with a underscore postfix, eg jarg1_. These are added in order to prevent premature garbage collection when marshalling proxy classes.
The functions in the intermediary JNI class cannot be accessed outside of its package. Access to them is gained through the module class for globals otherwise the appropriate proxy class.
The name of the intermediary JNI class can be changed from its default, that is, the module name with JNI appended after it. The module directive attribute jniclassname is used to achieve this:
%module (jniclassname="name") modulename
If name is the same as modulename then the module class name gets changed from modulename to modulenameModule.
The intermediary JNI class can be tailored through the use of pragmas, but is not commonly done. The pragmas for this class are:
| Pragma | Description |
| jniclassbase | Base class for the intermediary JNI class |
| jniclassclassmodifiers | Class modifiers and class type for the intermediary JNI class |
| jniclasscode | Java code is copied verbatim into the intermediary JNI class |
| jniclassimports | Java code, usually one or more import statements, placed before the intermediary JNI class definition |
| jniclassinterfaces | Comma separated interface classes for the intermediary JNI class |
The pragma code appears in the generated intermediary JNI class where you would expect:
[ jniclassimports pragma ]
[ jniclassclassmodifiers pragma ] jniclassname extends [ jniclassbase pragma ]
implements [ jniclassinterfaces pragma ] {
[ jniclasscode pragma ]
... SWIG generated native methods ...
}
The jniclasscode pragma is quite useful for adding in a static block for loading the shared library / dynamic link library and demonstrates how pragmas work:
%pragma(java) jniclasscode=%{
static {
try {
System.loadLibrary("example");
} catch (UnsatisfiedLinkError e) {
System.err.println("Native code library failed to load. \n" + e);
System.exit(1);
}
}
%}
Pragmas will take either "" or %{ %} as delimiters. For example, let's change the intermediary JNI class access to public.
%pragma(java) jniclassclassmodifiers="public class"
All the methods in the intermediary JNI class will then be callable outside of the package as the method modifiers are public by default.
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), chips);
}
}
The module class is necessary as there is no such thing as a global in Java so all the C globals are put into this class. They are generated as static functions and so must be accessed as such by using the module name in the static function call:
example.egg(new Foo());
The primary reason for having the module class wrapping the calls in the intermediary JNI class is to implement static type checking. In this case only a Foo can be passed to the egg function, whereas any long can be passed to the egg function in the intermediary JNI class.
The module class can be tailored through the use of pragmas, in the same manner as the intermediary JNI class. The pragmas are similarly named and are used in the same way. The complete list follows:
| Pragma | Description |
| modulebase | Base class for the module class |
| moduleclassmodifiers | Class modifiers and class type 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 ] modulename extends [ modulebase pragma ]
implements [ moduleinterfaces pragma ] {
[ modulecode pragma ]
... SWIG generated wrapper functions ...
}
See The intermediary JNI class pragmas section for further details on using pragmas.
A Java proxy class is generated for each structure, union or C++ class that is wrapped. Proxy classes have also been called peer classes. 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 static long getCPtr(Foo obj) {
return (obj == null) ? 0 : obj.swigCPtr;
}
protected void finalize() {
delete();
}
public synchronized void delete() {
if(swigCPtr != 0 && swigCMemOwn) {
swigCMemOwn = false;
exampleJNI.delete_Foo(swigCPtr);
}
swigCPtr = 0;
}
public void setX(int value) {
exampleJNI.Foo_x_set(swigCPtr, this, value);
}
public int getX() {
return exampleJNI.Foo_x_get(swigCPtr, this);
}
public int spam(int num, Foo foo) {
return exampleJNI.Foo_spam(swigCPtr, this, num, Foo.getCPtr(foo), foo);
}
public Foo() {
this(exampleJNI.new_Foo(), true);
}
}
This class merely holds a pointer to the underlying C++ object (swigCPtr). It also contains all the methods in the C++ class it is proxying plus getters and setters for public member variables. These functions call the native methods in the intermediary JNI class. The advantage of having this extra layer is the type safety that the proxy class functions offer. It adds static type checking which leads to fewer surprises at runtime. For example, you can see that if you attempt to use the spam() function it will only compile when the parameters passed are an int and a Foo. From a user's point of view, it makes the class work as if it were a Java class:
Foo f = new Foo(); f.setX(3); int y = f.spam(5, new Foo());
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 can be achieved by using a typemap to customise the proxy class with pure Java code as detailed later in the section on Java 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; ...
Some memory management issues are quite tricky to fix and may only be noticeable after using for a long time. One such issue is premature garbage collection of an object created from Java and resultant usage from C++ code. The section on typemap examples cover two such scenarios, Memory management for objects passed to the C++ layer and Memory management when returning references to member variables
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 static long getCPtr(Base obj) {
return (obj == null) ? 0 : obj.swigCPtr;
}
protected void finalize() {
delete();
}
public synchronized void delete() {
if(swigCPtr != 0 && swigCMemOwn) {
swigCMemOwn = false;
exampleJNI.delete_Base(swigCPtr);
}
swigCPtr = 0;
}
public double foo() {
return exampleJNI.Base_foo(swigCPtr, this);
}
public Base() {
this(exampleJNI.new_Base(), true);
}
}
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.SWIGDerivedUpcast(cPtr), cMemoryOwn);
swigCPtr = cPtr;
}
protected static long getCPtr(Derived obj) {
return (obj == null) ? 0 : obj.swigCPtr;
}
protected void finalize() {
delete();
}
public synchronized void delete() {
if(swigCPtr != 0 && swigCMemOwn) {
swigCMemOwn = false;
exampleJNI.delete_Derived(swigCPtr);
}
swigCPtr = 0;
super.delete();
}
public double foo() {
return exampleJNI.Derived_foo(swigCPtr, this);
}
public Derived() {
this(exampleJNI.new_Derived(), true);
}
}
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 SWIGDerivedUpcast() call converts the pointer from a Derived * to a Base *. This is a necessity 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. However, true cross language polymorphism can be achieved using the directors feature.
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. When a program exits, the garbage collector does not guarantee to call all finalizers. An insight into the reasoning behind this can be obtained from Hans Boehm's Destructors, Finalizers, and Synchronization paper. Depending on what the finalizers do and which operating system you use, this may or may not be a problem.
If the delete() call into JNI code is just for memory handling, there is not a problem when run on most operating systems, for example Windows and Unix. Say your JNI code creates memory on the heap which your finalizers should clean up, the finalizers may or may not be called before the program exits. In Windows and Unix all memory that a process uses is returned to the system on exit, so this isn't a problem. This is not the case in some operating systems like vxWorks. If however, your finalizer calls into JNI code invoking the C++ destructor which in turn releases a TCP/IP socket for example, there is no guarantee that it will be released. Note that with long running programs the garbage collector will eventually run, thereby calling any unreferenced object's finalizers.
Some not so ideal solutions are:
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 documentation says:
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.
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.
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 inadvertently used again a Java null pointer exception is thrown, the alternative would crash the JVM by using a null C pointer. For example given a SWIG generated class A:
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.
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.
See the How to Handle Java Finalization's Memory-Retention Issues article for alternative approaches to managing memory by avoiding finalizers altogether.
As covered earlier, the C/C++ struct/class pointer is stored in the proxy class as a Java long and when needed is passed into the native method where it is cast into the appropriate type. This approach provides very fast marshalling but could be susceptible to premature garbage collection. Consider the following C++ code:
class Wibble {
};
void wobble(Wibble &w);
The module class contains the Java wrapper for the global wobble method:
public class example {
...
public static void wobble(Wibble w) {
exampleJNI.wobble(Wibble.getCPtr(w), w);
}
}
where example is the name of the module. All native methods go through the intermediary class which has the native method declared as such:
public class exampleJNI {
...
public final static native void wobble(long jarg1, Wibble jarg1_);
}
The second parameter, jarg1_, is the premature garbage collection prevention parameter and is added to the native method parameter list whenever a C/C++ struct or class is marshalled as a Java long. In order to understand why, consider the alternative where the intermediary class method is declared without the additional parameter:
public class exampleJNI {
...
public final static native void wobble(long jarg1);
}
and the following simple call to wobble:
{
Wibble w = new Wibble();
example.wobble(w);
}
The hotspot compiler effectively sees something like:
{
Wibble w = new Wibble();
long w_ptr = Wibble.getCPtr(w);
// w is no longer reachable
exampleJNI.wobble(w_ptr);
}
The Wibble object is no longer reachable after the point shown as in this bit of code, the Wibble object is not referenced again after this point. This means that it is a candidate for garbage collection. Should wobble be a long running method, it is quite likely that the finalizer for the Wibble instance will be called. This in turn will call its underlying C++ destructor which is obviously disastrous while the method wobble is running using this object. Even if wobble is not a long running method, it is possible for the Wibble instance to be finalized. By passing the Wibble instance into the native method, it will not be finalized as the JVM guarantees not to finalize any objects until the native method returns. Effectively, the code then becomes
{
Wibble w = new Wibble();
long w_ptr = Wibble.getCPtr(w);
exampleJNI.wobble(w_ptr, w);
// w is no longer reachable
}
and therefore there is no possibility of premature garbage collection. In practice, this premature garbage collection was only ever observed in Sun's server JVM from jdk-1.3 onwards and in Sun's client JVM from jdk-1.6 onwards.
The premature garbage collection prevention parameter for proxy classes is generated by default whenever proxy classes are passed by value, reference or with a pointer. The implementation for this extra parameter generation requires the "jtype" typemap to contain long and the "jstype" typemap to contain the name of a proxy class.
The additional parameter does impose a slight performance overhead and the parameter generation can be suppressed globally with the -nopgcpp commandline option. More selective suppression is possible with the 'nopgcpp' attribute in the "jtype" Java typemap. The attribute is a flag and so should be set to "1" to enable the suppression, or it can be omitted or set to "0" to disable. For example:
%typemap(jtype, nopgcpp="1") Wibble & "long"
Compatibility note: The generation of this additional parameter did not occur in versions prior to SWIG-1.3.30.
Single threaded Java applications using JNI need to consider thread safety. The same applies for the C# module where the .NET wrappers use PInvoke. Consider the C++ class:
class Test {
string str;
public:
Test() : str("initial") {}
};
and the Java proxy class generated by SWIG:
public class Test {
private long swigCPtr;
protected boolean swigCMemOwn;
protected Test(long cPtr, boolean cMemoryOwn) {
swigCMemOwn = cMemoryOwn;
swigCPtr = cPtr;
}
protected static long getCPtr(Test obj) {
return (obj == null) ? 0 : obj.swigCPtr;
}
protected void finalize() {
delete();
}
// Call C++ destructor
public synchronized void delete() {
if(swigCPtr != 0 && swigCMemOwn) {
swigCMemOwn = false;
exampleJNI.delete_Test(swigCPtr);
}
swigCPtr = 0;
}
// Call C++ constructor
public Test() {
this(exampleJNI.new_Test(), true);
}
}
It has two methods that call JNI methods, namely, exampleJNI.new_Test() for the C++ constructor and exampleJNI.delete_Test() for the C++ destructor. If the garbage collector collects an instance of this class, ie delete() is not explicitly called, then the C++ destructor will be run in a different thread to the main thread. This is because when an object is marked for garbage collection, any objects with finalizers are added to a finalization queue and the objects in the finalization queue have their finalize() methods run in a separate finalization thread. Therefore, if the C memory allocator is not thread safe, then the heap will get corrupted sooner or later, when a concurrent C++ delete and new are executed. It is thus essential, even in single threaded usage, to link to the C multi-thread runtime libraries, for example, use the /MD option for Visual C++ on Windows. Alternatively, lock all access to C++ functions that have heap allocation/deallocation.
Note that some of the STL in Visual C++ 6 is not thread safe, so although code might be linked to the multithread runtime libraries, undefined behaviour might still occur in a single threaded Java program. Similarly some older versions of Sun Studio have bugs in the multi-threaded implementation of the std::string class and so will lead to undefined behaviour in these supposedly single threaded Java applications.
The following innocuous Java usage of Test is an example that will crash very quickly on a multiprocessor machine if the JNI compiled code is linked against the single thread C runtime libraries.
for (int i=0; i<100000; i++) {
System.out.println("Iteration " + i);
for (int k=0; k<10; k++) {
Test test = new Test();
}
System.gc();
}
The generated type wrapper class, for say an int *, looks like this:
public class SWIGTYPE_p_int {
private long swigCPtr;
protected SWIGTYPE_p_int(long cPtr, boolean bFutureUse) {
swigCPtr = cPtr;
}
protected SWIGTYPE_p_int() {
swigCPtr = 0;
}
protected static long getCPtr(SWIGTYPE_p_int obj) {
return obj.swigCPtr;
}
}
The methods do not have public access, so by default it is impossible to do anything with objects of this class other than pass them around. The methods in the class are part of the inner workings of SWIG. If you need to mess around with pointers you will have to use some typemaps specific to the Java module to achieve this. The section on Java typemaps details how to modify the generated code.
Note that if you use a pointer or reference to a proxy class in a function then no type wrapper class is generated because the proxy class can be used as the function parameter. If however, you need anything more complicated like a pointer to a pointer to a proxy class then a typewrapper class is generated for your use.
Note that SWIG generates a type wrapper class and not a proxy class when it has not parsed the definition of a type that gets used. For example, say SWIG has not parsed the definition of class Snazzy because it is in a header file that you may have forgotten to use the %include directive on. Should SWIG parse Snazzy * being used in a function parameter, it will then generates a type wrapper class around a Snazzy pointer. Also recall from earlier that SWIG will use a pointer when a class is passed by value or by reference:
void spam(Snazzy *x, Snazzy &y, Snazzy z);
Should SWIG not know anything about Snazzy then a SWIGTYPE_p_Snazzy must be used for all 3 parameters in the spam function. The Java function generated is:
public static void spam(SWIGTYPE_p_Snazzy x, SWIGTYPE_p_Snazzy y, SWIGTYPE_p_Snazzy z) {
...
}
Note that typedefs are tracked by SWIG and the typedef name is used to construct the type wrapper class name. For example, consider the case where Snazzy is a typedef to an int which SWIG does parse:
typedef int Snazzy; void spam(Snazzy *x, Snazzy &y, Snazzy z);
Because the typedefs have been tracked the Java function generated is:
public static void spam(SWIGTYPE_p_int x, SWIGTYPE_p_int y, int z) { ... }
SWIG can generate three types of enum classes. The Enumerations section discussed these but omitted all the details. The following sub-sections detail the various types of enum classes that can be generated.
The following example demonstrates the typesafe enum classes which SWIG generates:
%include "enumtypesafe.swg"
%javaconst(1);
enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
The following is the code that SWIG generates:
public final class Beverage {
public final static Beverage ALE = new Beverage("ALE");
public final static Beverage LAGER = new Beverage("LAGER", 10);
public final static Beverage STOUT = new Beverage("STOUT");
public final static Beverage PILSNER = new Beverage("PILSNER");
public final static Beverage PILZ = new Beverage("PILZ", PILSNER);
public final int swigValue() {
return swigValue;
}
public String toString() {
return swigName;
}
public static Beverage swigToEnum(int swigValue) {
if (swigValue < swigValues.length && swigValue >= 0 &&
swigValues[swigValue].swigValue == swigValue)
return swigValues[swigValue];
for (int i = 0; i < swigValues.length; i++)
if (swigValues[i].swigValue == swigValue)
return swigValues[i];
throw new IllegalArgumentException("No enum " + Beverage.class + " with value " +
swigValue);
}
private Beverage(String swigName) {
this.swigName = swigName;
this.swigValue = swigNext++;
}
private Beverage(String swigName, int swigValue) {
this.swigName = swigName;
this.swigValue = swigValue;
swigNext = swigValue+1;
}
private Beverage(String swigName, Beverage swigEnum) {
this.swigName = swigName;
this.swigValue = swigEnum.swigValue;
swigNext = this.swigValue+1;
}
private static Beverage[] swigValues = { ALE, LAGER, STOUT, PILSNER, PILZ };
private static int swigNext = 0;
private final int swigValue;
private final String swigName;
}
As can be seen, there are a fair number of support methods for the typesafe enum pattern. The typesafe enum pattern involves creating a fixed number of static instances of the enum class. The constructors are private to enforce this. Three constructors are available - two for C/C++ enums with an initializer and one for those without an initializer. Note that the two enums with initializers, LAGER and PILZ, each call one the two different initializer constructors. In order to use one of these typesafe enums, the swigToEnum static method must be called to return a reference to one of the static instances. The JNI layer returns the enum value from the C/C++ world as an integer and this method is used to find the appropriate Java enum static instance. The swigValue method is used for marshalling in the other direction. The toString method is overridden so that the enum name is available.
The following example demonstrates the Java enums approach:
%include "enums.swg"
%javaconst(1);
enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
SWIG will generate the following Java enum:
public enum Beverage {
ALE,
LAGER(10),
STOUT,
PILSNER,
PILZ(PILSNER);
public final int swigValue() {
return swigValue;
}
public static Beverage swigToEnum(int swigValue) {
Beverage[] swigValues = Beverage.class.getEnumConstants();
if (swigValue < swigValues.length && swigValue >= 0 &&
swigValues[swigValue].swigValue == swigValue)
return swigValues[swigValue];
for (Beverage swigEnum : swigValues)
if (swigEnum.swigValue == swigValue)
return swigEnum;
throw new IllegalArgumentException("No enum " + Beverage.class +
" with value " + swigValue);
}
private Beverage() {
this.swigValue = SwigNext.next++;
}
private Beverage(int swigValue) {
this.swigValue = swigValue;
SwigNext.next = swigValue+1;
}
private Beverage(Beverage swigEnum) {
this.swigValue = swigEnum.swigValue;
SwigNext.next = this.swigValue+1;
}
private final int swigValue;
private static class SwigNext {
private static int next = 0;
}
}
The enum items appear first. Like the typesafe enum pattern, the constructors are private. The constructors are required to handle C/C++ enums with initializers. The next variable is in the SwigNext inner class rather than in the enum class as static primitive variables cannot be modified from within enum constructors. Marshalling between Java enums and the C/C++ enum integer value is handled via the swigToEnum and swigValue methods. All the constructors and methods in the Java enum are required just to handle C/C++ enums with initializers. These needn't be generated if the enum being wrapped does not have any initializers and the Simpler Java enums for enums without initializers section describes how typemaps can be used to achieve this.
The following example demonstrates type unsafe enums:
%include "enumtypeunsafe.swg"
%javaconst(1);
enum Beverage { ALE, LAGER=10, STOUT, PILSNER, PILZ=PILSNER };
SWIG will generate the following simple class:
public final class Beverage {
public final static int ALE = 0;
public final static int LAGER = 10;
public final static int STOUT = LAGER + 1;
public final static int PILSNER = STOUT + 1;
public final static int PILZ = PILSNER;
}
Proxy classes provide a natural, object-oriented way to wrap C++ classes. as described earlier, each proxy instance has an associated C++ instance, and method calls from Java to the proxy are passed to the C++ instance transparently via C wrapper functions.
This arrangement is asymmetric in the sense that no corresponding mechanism exists to pass method calls down the inheritance chain from C++ to Java. In particular, if a C++ class has been extended in Java (by deriving from the proxy class), these classes will not be visible from C++ code. Virtual method calls from C++ are thus not able to access the lowest implementation in the inheritance chain.
SWIG can address this problem and make the relationship between C++ classes and proxy classes more symmetric. To achieve this goal, new classes called directors are introduced at the bottom of the C++ inheritance chain. The job of the directors is to route method calls correctly, either to C++ implementations higher in the inheritance chain or to Java implementations lower in the inheritance chain. The upshot is that C++ classes can be extended in Java and from C++ these extensions look exactly like native C++ classes. Neither C++ code nor Java code needs to know where a particular method is implemented: the combination of proxy classes, director classes, and C wrapper functions transparently takes care of all the cross-language method routing.
The director feature is disabled by default. To use directors you must make two changes to the interface file. First, add the "directors" option to the %module directive, like this:
%module(directors="1") modulename
Without this option no director code will be generated. Second, you must use the %feature("director") directive to tell SWIG which classes and methods should get directors. The %feature directive can be applied globally, to specific classes, and to specific methods, like this:
// generate directors for all classes that have virtual methods
%feature("director");
// generate directors for all virtual methods in class Foo
%feature("director") Foo;
// generate a director for just Foo::bar()
%feature("director") Foo::bar;
You can use the %feature("nodirector") directive to turn off directors for specific classes or methods. So for example,
%feature("director") Foo;
%feature("nodirector") Foo::bar;
will generate directors for all virtual methods of class Foo except bar().
Directors can also be generated implicitly through inheritance. In the following, class Bar will get a director class that handles the methods one() and two() (but not three()):
%feature("director") Foo;
class Foo {
public:
virtual void one();
virtual void two();
};
class Bar: public Foo {
public:
virtual void three();
};
For each class that has directors enabled, SWIG generates a new class that derives from both the class in question and a special Swig::Director class. These new classes, referred to as director classes, can be loosely thought of as the C++ equivalent of the Java proxy classes. The director classes store a pointer to their underlying Java proxy classes.
For simplicity let's ignore the Swig::Director class and refer to the original C++ class as the director's base class. By default, a director class extends all virtual methods in the inheritance chain of its base class (see the preceding section for how to modify this behavior). Thus all virtual method calls, whether they originate in C++ or in Java via proxy classes, eventually end up in at the implementation in the director class. The job of the director methods is to route these method calls to the appropriate place in the inheritance chain. By "appropriate place" we mean the method that would have been called if the C++ base class and its Java derived classes were seamlessly integrated. That seamless integration is exactly what the director classes provide, transparently skipping over all the messy JNI glue code that binds the two languages together.
In reality, the "appropriate place" is one of only two possibilities: C++ or Java. Once this decision is made, the rest is fairly easy. If the correct implementation is in C++, then the lowest implementation of the method in the C++ inheritance chain is called explicitly. If the correct implementation is in Java, the Java API is used to call the method of the underlying Java object (after which the usual virtual method resolution in Java automatically finds the right implementation).
Enabling directors for a class will generate a new director method for every virtual method in the class' inheritance chain. This alone can generate a lot of code bloat for large hierarchies. Method arguments that require complex conversions to and from Java types can result in large director methods. For this reason it is recommended that directors are selectively enabled only for specific classes that are likely to be extended in Java and used in C++.
Although directors make it natural to mix native C++ objects with Java objects (as director objects), one should be aware of the obvious fact that method calls to Java objects from C++ will be much slower than calls to C++ objects. Additionally, compared to classes that do not use directors, the call routing in the director methods adds a small overhead. This situation can be optimized by selectively enabling director methods (using the %feature directive) for only those methods that are likely to be extended in Java.
Consider the following SWIG interface file:
%module(directors="1") example;
%feature("director") DirectorBase;
class DirectorBase {
public:
virtual ~DirectorBase() {}
virtual void upcall_method() {}
};
void callup(DirectorBase *director) {
director->upcall_method();
}
The following DirectorDerived Java class is derived from the Java proxy class DirectorBase and overrides upcall_method().
When C++ code invokes upcall_method(), the SWIG-generated C++ code redirects the call via JNI to the Java DirectorDerived subclass.
Naturally, the SWIG generated C++ code and the generated Java intermediate class marshal and convert arguments between C++ and Java when needed.
public class DirectorDerived extends DirectorBase {
public DirectorDerived() {
}
public void upcall_method() {
System.out.println("DirectorDerived::upcall_method() invoked.");
}
}
Running the following Java code
DirectorDerived director = new DirectorDerived(); example.callup(director);
will result in the following being output:
DirectorDerived::upcall_method() invoked.
Depending on your operating system and version of Java and how you are using threads, you might find the JVM hangs on exit. There are a couple of solutions to try out. The preferred solution requires jdk-1.4 and later and uses AttachCurrentThreadAsDaemon instead of AttachCurrentThread whenever a call into the JVM is required. This can be enabled by defining the SWIG_JAVA_ATTACH_CURRENT_THREAD_AS_DAEMON macro when compiling the C++ wrapper code. For older JVMs define SWIG_JAVA_NO_DETACH_CURRENT_THREAD instead, to avoid the DetachCurrentThread call but this will result in a memory leak instead. For further details inspect the source code in the java/director.swg library file.
Macros can be defined on the commandline when compiling your C++ code, or alternatively added to the C++ wrapper file as shown below:
%insert("runtime") %{
#define SWIG_JAVA_NO_DETACH_CURRENT_THREAD
%}
When using directors, the protected virtual methods are also wrapped. These methods are wrapped with a protected Java proxy method, so the only way that Java code can access these is from within a Java class derived from the director class.
Members which are protected and non-virtual can also be accessed when using the 'allprotected' mode. The allprotected mode requires directors and is turned on by setting the allprotected option in addition to the directors option in the %module directive, like this:
%module(directors="1", allprotected="1") modulename
Protected member variables and methods (both static and non-static) will then be wrapped with protected access in the Java proxy class.
Note: Neither the directors option nor the allprotected mode support types defined with protected scope. This includes any enums or typedefs declared in the protected section of the C++ class.
The following simple example is a class with numerous protected members, including the constructor and destructor:
%module(directors="1", allprotected="1") example
%feature("director") ProtectedBase;
// Ignore use of unsupported types (those defined in the protected section)
%ignore ProtectedBase::typedefs;
%inline %{
class ProtectedBase {
protected:
ProtectedBase() {}
virtual ~ProtectedBase() {}
virtual void virtualMethod() const {}
void nonStaticMethod(double d) const {}
static void staticMethod(int i) {}
int instanceMemberVariable;
static int staticMemberVariable;
// unsupported: types defined with protected access and the methods/variables which use them
typedef int IntegerType;
IntegerType typedefs(IntegerType it) { return it; }
};
int ProtectedBase::staticMemberVariable = 10;
%}
Note that the IntegerType has protected scope and the members which use this type must be ignored as they cannot be wrapped.
The proxy methods are protected, so the only way the protected members can be accessed is within a class that derives from the director class, such as the following:
class MyProtectedBase extends ProtectedBase
{
public MyProtectedBase() {
}
public void accessProtected() {
virtualMethod();
nonStaticMethod(1.2);
staticMethod(99);
setInstanceMemberVariable(5);
int i = getInstanceMemberVariable();
setStaticMemberVariable(10);
i = getStaticMemberVariable();
}
}
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.
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.
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.
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. It is detailed in full in the Exception handling with %exception section.
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 runme.main(runme.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);
If no declaration name is given to %exception, it is applied to all wrapper functions. The $action is a SWIG special variable and is replaced by the C/C++ function call being wrapped. The return $null; handles all native method return types, namely those that have a void return and those that do not. This is useful for typemaps that will be used in native method returning all return types. See the section on Java special variables for further explanation.
C++ exceptions are also easy to handle. We can catch the C++ exception and rethrow it as a Java exception like this:
%exception getitem {
try {
$action
} catch (std::out_of_range &e) {
jclass clazz = jenv->FindClass("java/lang/Exception");
jenv->ThrowNew(clazz, "Range error");
return $null;
}
}
class FooClass {
public:
FooClass *getitem(int index); // Might throw std::out_of_range exception
...
};
In the example above, java.lang.Exception is a checked exception class and so ought to be declared in the throws clause of getitem. Classes can be specified for adding to the throws clause using %javaexception(classes) instead of %exception, where classes is a string containing one or more comma separated Java classes. The %clearjavaexception feature is the equivalent to %clearexception and clears previously declared exception handlers. The %nojavaexception feature is the equivalent to %noexception and disables the exception handler. See Clearing features for the difference on disabling and clearing features.
%javaexception("java.lang.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 FooClass {
public:
FooClass *getitem(int index); // Might throw std::out_of_range exception
...
};
The generated proxy method now generates a throws clause containing java.lang.Exception:
public class FooClass {
...
public FooClass getitem(int index) throws java.lang.Exception { ... }
...
}
The examples above first use the C JNI calling syntax then the C++ JNI calling syntax. The C++ calling syntax will not compile as C and also vice versa. It is however possible to write JNI calls which will compile under both C and C++ and is covered in the 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. The typemap example Handling C++ exception specifications as Java exceptions provides further exception handling capabilities.
A Java feature called %javamethodmodifiers can be used to change the method modifiers from the default public. It applies to both module class methods and proxy class methods. For example:
%javamethodmodifiers protect_me() "protected"; void protect_me();
Will produce the method in the module class with protected access.
protected static void protect_me() {
exampleJNI.protect_me();
}
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.
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.
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"
%inline %{
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.
SWIG can wrap arrays in a more natural Java manner than the default by using the arrays_java.i library file. Let's consider an example:
%include "arrays_java.i";
int array[4];
void populate(int x[]) {
int i;
for (i=0; i<4; i++)
x[i] = 100 + i;
}
These one dimensional arrays can then be used as if they were Java arrays:
int[] array = new int[4];
example.populate(array);
System.out.print("array: ");
for (int i=0; i<array.length; i++)
System.out.print(array[i] + " ");
example.setArray(array);
int[] global_array = example.getArray();
System.out.print("\nglobal_array: ");
for (int i=0; i<array.length; i++)
System.out.print(global_array[i] + " ");
Java arrays are always passed by reference, so any changes a function makes to the array will be seen by the calling function. Here is the output after running this code:
array: 100 101 102 103 global_array: 100 101 102 103
Note that for assigning array variables the length of the C variable is used, so it is possible to use a Java array that is bigger than the C code will cope with. Only the number of elements in the C array will be used. However, if the Java array is not large enough then you are likely to get a segmentation fault or access violation, just like you would in C. When arrays are used in functions like populate, the size of the C array passed to the function is determined by the size of the Java array.
Please be aware that the typemaps in this library are not efficient as all the elements are copied from the Java array to a C array whenever the array is passed to and from JNI code. There is an alternative approach using the SWIG array library and this is covered in the next section.
Sometimes a C function expects an array to be passed as a pointer. For example,
int sumitems(int *first, int nitems) {
int i, sum = 0;
for (i = 0; i < nitems; i++) {
sum += first[i];
}
return sum;
}
One of the ways to wrap this is to apply the Java array typemaps that come in the arrays_java.i library file:
%include "arrays_java.i"
%apply int[] {int *};
The ANY size will ensure the typemap is applied to arrays of all sizes. You could narrow the typemap matching rules by specifying a particular array size. Now you can use a pure Java array and pass it to the C code:
int[] array = new int[10000000]; // Array of 10-million integers
for (int i=0; i<array.length; i++) { // Set some values
array[i] = i;
}
int sum = example.sumitems(array,10000);
System.out.println("Sum = " + sum);
and the sum would be displayed:
Sum = 49995000
This approach is probably the most natural way to use arrays. However, it suffers from performance problems when using large arrays as a lot of copying of the elements occurs in transferring the array from the Java world to the C++ world. An alternative approach to using Java arrays for C arrays is to use an alternative SWIG library file carrays.i. This approach can be more efficient for large arrays as the array is accessed one element at a time. For example:
%include "carrays.i" %array_functions(int, intArray);
The %array_functions(type,name) macro generates four helper functions that can be used to create and destroy arrays and operate on elements. In this case, the functions are as follows:
int *new_intArray(int nelements); void delete_intArray(int *x); int intArray_getitem(int *x, int index); void intArray_setitem(int *x, int index, int value);
In Java, you would use the functions like this:
SWIGTYPE_p_int array = example.new_intArray(10000000); // Array of 10-million integers
for (int i=0; i<10000; i++) { // Set some values
example.intArray_setitem(array,i,i);
}
int sum = example.sumitems(array,10000);
System.out.println("Sum = " + sum);
If you replace %array_functions(int,intp) by %array_class(int,intp), the interface is more class-like and a couple more helper functions are available for casting between the array and the type wrapper class.
%include "carrays.i" %array_class(int, intArray);
The %array_class(type, name) macro creates wrappers for an unbounded array object that can be passed around as a simple pointer like int * or double *. For instance, you will be able to do this in Java:
intArray array = new intArray(10000000); // Array of 10-million integers
for (int i=0; i<10000; i++) { // Set some values
array.setitem(i,i);
}
int sum = example.sumitems(array.cast(),10000);
System.out.println("Sum = " + sum);
The array "object" created by %array_class() does not encapsulate pointers inside a special array object. In fact, there is no bounds checking or safety of any kind (just like in C). Because of this, the arrays created by this library are extremely low-level indeed. You can't iterate over them nor can you even query their length. In fact, any valid memory address can be accessed if you want (negative indices, indices beyond the end of the array, etc.). Needless to say, this approach is not going to suit all applications. On the other hand, this low-level approach is extremely efficient and well suited for applications in which you need to create buffers, package binary data, etc.
Unlike some languages supported by SWIG, Java has a true garbage collection subsystem. Other languages will free SWIG wrapped objects when their reference count reaches zero. Java only schedules these objects for finalization, which may not occur for some time. Because SWIG objects are allocated on the C heap, Java users may find the JVM memory use quickly exceeds the assigned limits, as memory fills with unfinalized proxy objects. Forcing garbage collection is clearly an undesirable solution.
An elegant fix for C++ users is to override new and delete using the following code (here shown included in a SWIG interface file)
/* File: java_heap.i */
%module test
%{
#include <stdexcept>
#include "jni.h"
/**
* A stash area embedded in each allocation to hold java handles
*/
struct Jalloc {
jbyteArray jba;
jobject ref;
};
static JavaVM *cached_jvm = 0;
JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *jvm, void *reserved) {
cached_jvm = jvm;
return JNI_VERSION_1_2;
}
static JNIEnv * JNU_GetEnv() {
JNIEnv *env;
jint rc = cached_jvm->GetEnv((void **)&env, JNI_VERSION_1_2);
if (rc == JNI_EDETACHED)
throw std::runtime_error("current thread not attached");
if (rc == JNI_EVERSION)
throw std::runtime_error("jni version not supported");
return env;
}
void * operator new(size_t t) {
if (cached_jvm != 0) {
JNIEnv *env = JNU_GetEnv();
jbyteArray jba = env->NewByteArray((int) t + sizeof(Jalloc));
if (env->ExceptionOccurred())
throw bad_alloc();
void *jbuffer = static_cast<void *>(env->GetByteArrayElements(jba, 0));
if (env->ExceptionOccurred())
throw bad_alloc();
Jalloc *pJalloc = static_cast<Jalloc *>(jbuffer);
pJalloc->jba = jba;
/* Assign a global reference so byte array will persist until delete'ed */
pJalloc->ref = env->NewGlobalRef(jba);
if (env->ExceptionOccurred())
throw bad_alloc();
return static_cast<void *>(static_cast<char *>(jbuffer) + sizeof(Jalloc));
}
else { /* JNI_OnLoad not called, use malloc and mark as special */
Jalloc *pJalloc = static_cast<Jalloc *>(malloc((int) t + sizeof(Jalloc)));
if (!pJalloc)
throw bad_alloc();
pJalloc->ref = 0;
return static_cast<void *>(
static_cast<char *>(static_cast<void *>(pJalloc)) + sizeof(Jalloc));
}
}
void operator delete(void *v) {
if (v != 0) {
void *buffer = static_cast<void *>( static_cast<char *>(v) - sizeof(Jalloc));
Jalloc *pJalloc = static_cast<Jalloc *>(buffer);
if (pJalloc->ref) {
JNIEnv *env = JNU_GetEnv();
env->DeleteGlobalRef(pJalloc->ref);
env->ReleaseByteArrayElements(pJalloc->jba, static_cast<jbyte *>(buffer), 0);
}
else {
free(buffer);
}
}
}
%}
...
This code caches the Java environment during initialization, and when new is called, a Java ByteArray is allocated to provide the SWIG objects with space in the Java heap. This has the combined effect of re-asserting the Java virtual machine's limit on memory allocation, and puts additional pressure on the garbage collection system to run more frequently. This code is made slightly more complicated because allowances must be made if new is called before the JNI_OnLoad is executed. This can happen during static class initialization, for example.
Unfortunately, because most Java implementations call malloc and free, this solution will not work for C wrapped structures. However, you are free to make functions that allocate and free memory from the Java heap using this model and use these functions in place of malloc and free in your own code.
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:
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.
The following table lists the default type mapping from Java to C/C++.
| C/C++ type | Java type | JNI type |
| bool const bool & |
boolean | jboolean |
| char const char & |
char | jchar |
| signed char const signed char & |
byte | jbyte |
| unsigned char const unsigned char & |
short | jshort |
| short const short & |
short | jshort |
| unsigned short const unsigned short & |
int | jint |
| int const int & |
int | jint |
| unsigned int const unsigned int & |
long | jlong |
| long const long & |
int | jint |
| unsigned long const unsigned long & |
long | jlong |
| long long const long long & |
long | jlong |
| unsigned long long const unsigned long long & |
java.math.BigInteger | jobject |
| float const float & |
float | jfloat |
| double const double & |
double | jdouble |
| char * char [] |
String | jstring |
Note that SWIG wraps the C char type as a character. Pointers and arrays of this type are wrapped as strings. The signed char type can be used if you want to treat char as a signed number rather than a character. Also note that all const references to primitive types are treated as if they are passed by value.
Given the following C function:
void func(unsigned short a, char *b, const long &c, unsigned long long d);
The module class method would be:
public static void func(int a, String b, int c, java.math.BigInteger d) {...}
The intermediary JNI class would use the same types:
public final static native void func(int jarg1, String jarg2, int jarg3,
java.math.BigInteger jarg4);
and the JNI function would look like this:
SWIGEXPORT void JNICALL Java_exampleJNI_func(JNIEnv *jenv, jclass jcls,
jint jarg1, jstring jarg2, jint jarg3, jobject jarg4) {...}
The mappings for C int and C long are appropriate for 32 bit applications which are used in the 32 bit JVMs. There is no perfect mapping between Java and C as Java doesn't support all the unsigned C data types. However, the mappings allow the full range of values for each C type from Java.
The previous section covered the primitive type mappings. Non-primitive types such as classes and structs are mapped using pointers on the C/C++ side and storing the pointer into a Java long variable which is held by the proxy class or type wrapper class. This applies whether the type is marshalled as a pointer, by reference or by value. It also applies for any unknown/incomplete types which use type wrapper classes.
So in summary, the C/C++ pointer to non-primitive types is cast into the 64 bit Java long type and therefore the JNI type is a jlong. The Java type is either the proxy class or type wrapper class.
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.
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);
}
%inline %{
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);
}
%inline %{
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);
}
%inline %{
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");
The typemaps available to the Java module include the common typemaps listed in the main typemaps section. There are a number of additional typemaps which are necessary for using SWIG with Java. The most important of these implement the mapping of C/C++ types to Java types:
| Typemap | Description |
| jni | JNI C types. These provide the default mapping of types from C/C++ to JNI for use in the JNI (C/C++) code. |
| jtype | Java intermediary types. These provide the default mapping of types from C/C++ to Java for use in the native functions in the intermediary JNI class. The type must be the equivalent Java type for the JNI C type specified in the "jni" typemap. |
| jstype | Java types. These provide the default mapping of types from C/C++ to Java for use in the Java module class, proxy classes and type wrapper classes. |
| javain | Conversion from jstype to jtype. These are Java code typemaps which transform the type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap) to the type used in the Java intermediary JNI class (as specified in the "jtype" typemap). In other words the typemap provides the conversion to the native method call parameter types. |
| javaout | Conversion from jtype to jstype. These are Java code typemaps which transform the type used in the Java intermediary JNI class (as specified in the "jtype" typemap) to the Java type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap). In other words the typemap provides the conversion from the native method call return type. |
| javadirectorin | Conversion from jtype to jstype for director methods. These are Java code typemaps which transform the type used in the Java intermediary JNI class (as specified in the "jtype" typemap) to the Java type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap). This typemap provides the conversion for the parameters in the director methods when calling up from C++ to Java. See Director typemaps. |
| javadirectorout | Conversion from jstype to jtype for director methods. These are Java code typemaps which transform the type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap) to the type used in the Java intermediary JNI class (as specified in the "jtype" typemap). This typemap provides the conversion for the return type in the director methods when returning from the C++ to Java upcall. See Director typemaps. |
| directorin | Conversion from C++ type to jni type for director methods. These are C++ typemaps which convert the parameters used in the C++ director method to the appropriate JNI intermediary type. The conversion is done in JNI code prior to calling the Java function from the JNI code. See Director typemaps. |
| directorout | Conversion from jni type to C++ type for director methods. These are C++ typemaps which convert the JNI return type used in the C++ director method to the appropriate C++ return type. The conversion is done in JNI code after calling the Java function from the JNI code. See Director typemaps. |
If you are writing your own typemaps to handle a particular type, you will normally have to write a collection of them. The default typemaps are in "java.swg" and so might be a good place for finding typemaps to base any new ones on.
The "jni", "jtype" and "jstype" typemaps are usually defined together to handle the Java to C/C++ type mapping. An "in" typemap should be accompanied by a "javain" typemap and likewise an "out" typemap by a "javaout" typemap. If an "in" typemap is written, a "freearg" and "argout" typemap may also need to be written as some types have a default "freearg" and/or "argout" typemap which may need overriding. The "freearg" typemap sometimes releases memory allocated by the "in" typemap. The "argout" typemap sometimes sets values in function parameters which are passed by reference in Java.
Note that the "in" typemap marshals the JNI type held in the "jni" typemap to the real C/C++ type and for the opposite direction, the "out" typemap marshals the real C/C++ type to the JNI type held in the "jni" typemap. For non-primitive types the "in" and "out" typemaps are responsible for casting between the C/C++ pointer and the 64 bit jlong type. There is no portable way to cast a pointer into a 64 bit integer type and the approach taken by SWIG is mostly portable, but breaks C/C++ aliasing rules. In summary, these rules state that a pointer to any type must never be dereferenced by a pointer to any other incompatible type. The following code snippet might aid in understand aliasing rules better:
short a;
short* pa = 0;
int i = 0x1234;
a = (short)i; /* okay */
a = *(short*)&i; /* breaks aliasing rules */
An email posting, Aliasing, pointer casts and gcc 3.3 elaborates further on the subject. In SWIG, the "in" and "out" typemaps for pointers are typically
%typemap(in) struct Foo * %{
$1 = *(struct Foo **)&$input; /* cast jlong into C ptr */
%}
%typemap(out) struct Bar * %{
*(struct Bar **)&$result = $1; /* cast C ptr into jlong */
%}
struct Bar {...};
struct Foo {...};
struct Bar * FooBar(struct Foo *f);
resulting in the following code which breaks the aliasing rules:
SWIGEXPORT jlong JNICALL Java_exampleJNI_FooBar(JNIEnv *jenv, jclass jcls,
jlong jarg1, jobject jarg1_) {
jlong jresult = 0 ;
struct Foo *arg1 = (struct Foo *) 0 ;
struct Bar *result = 0 ;
(void)jenv;
(void)jcls;
(void)jarg1_;
arg1 = *(struct Foo **)&jarg1;
result = (struct Bar *)FooBar(arg1);
*(struct Bar **)&jresult = result;
return jresult;
}
If you are using gcc as your C compiler, you might get a "dereferencing type-punned pointer will break strict-aliasing rules" warning about this. Please see Compiling a dynamic module to avoid runtime problems with these strict aliasing rules.
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 and Default typemaps for non-primitive types covered earlier. There are other type mapping typemaps in the Java library. These are listed below:
| C Type | Typemap | File | Kind | Java Type | Function |
| primitive pointers and references | INPUT | typemaps.i | input | Java basic types | Allows values to be used for C functions taking pointers for data input. |
| primitive pointers and references | OUTPUT | typemaps.i | output | Java basic type arrays | Allows values held within an array to be used for C functions taking pointers for data output. |
| primitive pointers and references | INOUT | typemaps.i | input output |
Java basic type arrays | Allows values held within an array to be used for C functions taking pointers for data input and output. |
| string wstring |
[unnamed] | std_string.i | input output |
String | Use for std::string mapping to Java String. |
| arrays of primitive types | [unnamed] | arrays_java.i | input output |
arrays of primitive Java types | Use for mapping C arrays to Java arrays. |
| arrays of classes/structs/unions | JAVA_ARRAYSOFCLASSES macro | arrays_java.i | input output |
arrays of proxy classes | Use for mapping C arrays to Java arrays. |
| arrays of enums | ARRAYSOFENUMS | arrays_java.i | input output |
int[] | Use for mapping C arrays to Java arrays (typeunsafe and simple enum wrapping approaches only). |
| char * | BYTE | various.i | input | byte[] | Java byte array is converted to char array |
| char ** | STRING_ARRAY | various.i | input output |
String[] | Use for mapping NULL terminated arrays of C strings to Java String arrays |
There are a few additional typemap attributes that the Java module supports.
The first of these is the 'throws' attribute. The throws attribute is optional and specified after the typemap name and contains one or more comma separated classes for adding to the throws clause for any methods that use that typemap. It is analogous to the %javaexception feature's throws attribute.
%typemap(typemapname, throws="ExceptionClass1, ExceptionClass2") type { ... }
The attribute is necessary for supporting Java checked exceptions and can be added to just about any typemap. The list of typemaps include all the C/C++ (JNI) typemaps in the "Typemaps" chapter and the Java specific typemaps listed in the previous section, barring the "jni", "jtype" and "jstype" typemaps as they could never contain code to throw an exception.
The throws clause is generated for the proxy method as well as the JNI method in the JNI intermediary class. If a method uses more than one typemap and each of those typemaps have classes specified in the throws clause, the union of the exception classes is added to the throws clause ensuring there are no duplicate classes. See the NaN exception example for further usage.
The "jtype" typemap has the optional 'nopgcpp' attribute which can be used to suppress the generation of the premature garbage collection prevention parameter.
The "javain" typemap has the optional 'pre', 'post' and 'pgcppname' attributes. These are used for generating code before and after the JNI call in the proxy class or module class. The 'pre' attribute contains code that is generated before the JNI call and the 'post' attribute contains code generated after the JNI call. The 'pgcppname' attribute is used to change the premature garbage collection prevention parameter name passed to the JNI function. This is sometimes needed when the 'pre' typemap creates a temporary variable which is then passed to the JNI function.
Note that when the 'pre' or 'post' attributes are specified and the associated type is used in a constructor, a constructor helper function is generated. This is necessary as the Java proxy constructor wrapper makes a call to a support constructor using a this call. In Java the this call must be the first statement in the constructor body. The constructor body thus calls the helper function and the helper function instead makes the JNI call, ensuring the 'pre' code is called before the JNI call is made. There is a Date marshalling example showing 'pre', 'post' and 'pgcppname' attributes in action.
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
This special variable works like the other special variables
and $javaclassname is similar to $1_type. It expands to the class name for use in Java given a pointer.
SWIG wraps unions, structs and classes using pointers and in this case it expands to the Java proxy class name.
For example, $javaclassname is replaced by the proxy classname Foo when wrapping a Foo * and
$&javaclassname expands to the proxy classname when wrapping the C/C++ type Foo and $*javaclassname
expands to the proxy classname when wrapping Foo *&.
If the type does not have an associated proxy class, it expands to the type wrapper class name, for example,
SWIGTYPE_p_unsigned_short is generated when wrapping 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_JavaThrowException(jenv, SWIG_JavaIndexOutOfBoundsException, "Array element error");
return $null;
}
%}
If the typemap gets put into a function with void as return, $null will expand to nothing:
SWIGEXPORT void JNICALL Java_jnifn(...) {
if (error) {
SWIG_JavaThrowException(jenv, SWIG_JavaIndexOutOfBoundsException, "Array element error");
return ;
}
...
}
otherwise $null expands to NULL
SWIGEXPORT jobject JNICALL Java_jnifn(...) {
if (error) {
SWIG_JavaThrowException(jenv, SWIG_JavaIndexOutOfBoundsException, "Array element error");
return NULL;
}
...
}
$javainput, $jnicall and $owner
The $javainput special variable is used in "javain" typemaps and $jnicall and $owner are used in "javaout" typemaps.
$jnicall is analogous to $action in %exception. It is replaced by the call to the native method in the intermediary JNI class.
$owner is replaced by either true if %newobject has been used, otherwise false.
$javainput is analogous to the $input special variable. It is replaced by the parameter name.
Here is an example:
%typemap(javain) Class "Class.getCPtr($javainput)"
%typemap(javain) unsigned short "$javainput"
%typemap(javaout) Class * {
return new Class($jnicall, $owner);
}
%inline %{
class Class {...};
Class * bar(Class cls, unsigned short ush) { return new Class(); };
%}
The generated proxy code is then:
public static Class bar(Class cls, int ush) {
return new Class(exampleJNI.bar(Class.getCPtr(cls), cls, ush), false);
}
Here $javainput has been replaced by cls and ush. $jnicall has been replaced by the native method call, exampleJNI.bar(...) and $owner has been replaced by false. If %newobject is used by adding the following at the beginning of our example:
%newobject bar(Class cls, unsigned short ush);
The generated code constructs the return type using true indicating the proxy class Class is responsible for destroying the C++ memory allocated for it in bar:
public static Class bar(Class cls, int ush) {
return new Class(exampleJNI.bar(Class.getCPtr(cls), cls, ush), true);
}
$static
This special variable expands to either static or nothing depending on whether the class is an inner Java class or not.
It is used in the "javaclassmodifiers" typemap so that global classes can be wrapped as Java proxy classes and nested C++ classes/enums
can be wrapped with the Java equivalent, that is, static inner proxy classes.
$jniinput, $javacall and $packagepath
These special variables are used in the directors typemaps. See Director specific typemaps for details.
$module
This special variable expands to the module name, as specified by %module or the -module commandline option.
$imclassname
This special variable expands to the intermediary class name. Usually this is the same as '$moduleJNI',
unless the jniclassname attribute is specified in the %module directive.
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.
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)
%typemap(javabody)
%typemap(javabody_derived)
%typemap(javaclassmodifiers)
%typemap(javacode)
%typemap(javadestruct, methodname="delete", methodmodifiers="public synchronized")
%typemap(javadestruct_derived, methodname="delete", methodmodifiers="public synchronized")
%typemap(javaimports)
%typemap(javainterfaces)
%typemap(javafinalize)
Compatibility Note: In SWIG-1.3.21 and earlier releases, typemaps called "javagetcptr" and "javaptrconstructormodifiers" were available. These are deprecated and the "javabody" typemap can be used instead.
In summary the contents of the typemaps make up a proxy class like this:
[ javaimports typemap ]
[ javaclassmodifiers typemap ] javaclassname extends [ javabase typemap ]
implements [ javainterfaces typemap ] {
[ javabody or javabody_derived typemap ]
[ javafinalize typemap ]
public synchronized void delete() [ javadestruct OR javadestruct_derived typemap ]
[ javacode typemap ]
... proxy functions ...
}
Note the delete() methodname and method modifiers are configurable, see "javadestruct" and "javadestruct_derived" typemaps above.
The type wrapper class is similar in construction:
[ javaimports typemap ]
[ javaclassmodifiers typemap ] javaclassname extends [ javabase typemap ]
implements [ javainterfaces typemap ] {
[ javabody typemap ]
[ javacode typemap ]
}
The enum class is also similar in construction:
[ javaimports typemap ]
[ javaclassmodifiers typemap ] javaclassname extends [ javabase typemap ]
implements [ javainterfaces typemap ] {
... Enum values ...
[ javabody typemap ]
[ javacode typemap ]
}
The "javaimports" typemap is ignored if the enum class is wrapped by an inner Java class, that is when wrapping an enum declared within a C++ class.
The defaults can be overridden to tailor these classes. Here is an example which will change the getCPtr method and constructor from the default protected access to public access. This has a practical application if you are invoking SWIG more than once and generating the wrapped classes into different packages in each invocation. If the classes in one package are using the classes in another package, then these methods need to be public.
%typemap(javabody) SWIGTYPE %{
private long swigCPtr;
protected boolean swigCMemOwn;
public $javaclassname(long cPtr, boolean cMemoryOwn) {
swigCMemOwn = cMemoryOwn;
swigCPtr = cPtr;
}
public static long getCPtr($javaclassname obj) {
return (obj == null) ? 0 : obj.swigCPtr;
}
%}
The typemap code is the same that is in "java.swg", barring the two method modifiers. Note that SWIGTYPE will target all proxy classes, but not the type wrapper classes. Also the above typemap is only used for proxy classes that are potential base classes. To target proxy classes that are derived from a wrapped class as well, the "javabody_derived" typemap should also be overridden.
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(javabody) SWIGTYPE *, SWIGTYPE &, SWIGTYPE [], SWIGTYPE (CLASS::*) %{
private long swigCPtr;
public $javaclassname(long cPtr, boolean bFutureUse) {
swigCPtr = cPtr;
}
protected $javaclassname() {
swigCPtr = 0;
}
public static long getCPtr($javaclassname obj) {
return (obj == null) ? 0 : obj.swigCPtr;
}
%}
Again this is the same that is in "java.swg", barring the method modifier for getCPtr.
The Java directors feature requires the "javadirectorin", "javadirectorout", "directorin" and the "directorout" typemaps in order to work properly. The "javapackage" typemap is an optional typemap used to identify the Java package path for individual SWIG generated proxy classes.
%typemap(directorin)
The "directorin" typemap is used for converting arguments in the C++ director class to the appropriate JNI type before the upcall to Java. This typemap also specifies the JNI field descriptor for the type in the "descriptor" attribute. For example, integers are converted as follows:
%typemap(directorin,descriptor="I") int "$input = (jint) $1;"
$input is the SWIG name of the JNI temporary variable passed to Java in the upcall.
The descriptor="I" will put an I into the JNI field descriptor that identifies the Java method that will be called from C++.
For more about JNI field descriptors and their importance, refer to the JNI documentation mentioned earlier.
A typemap for C character strings is:
%typemap(directorin,descriptor="Ljava/lang/String;") char *
%{ $input = jenv->NewStringUTF($1); %}
User-defined types have the default "descriptor" attribute "L$packagepath/$javaclassname;" where $packagepath
is the package name passed from the SWIG command line and $javaclassname is the Java proxy class' name.
If the -package commandline option is not used to specify the package, then '$packagepath/' will be removed from the resulting output JNI field descriptor.
Do not forget the terminating ';' for JNI field descriptors starting with 'L'.
If the ';' is left out, Java will generate a "method not found" runtime error.
%typemap(directorout)
The "directorout" typemap is used for converting the JNI return type in the C++ director class to the appropriate C++ type after the upcall to Java. For example, integers are converted as follows:
%typemap(directorout) int %{ $result = (int)$input; %}
$input is the SWIG name of the JNI temporary variable returned from Java after the upcall.
$result is the resulting output.
A typemap for C character strings is:
%typemap(directorout) char * {
$1 = 0;
if ($input) {
$result = (char *)jenv->GetStringUTFChars($input, 0);
if (!$1) return $null;
}
}
%typemap(javadirectorin)
Conversion from jtype to jstype for director methods. These are Java code typemaps which transform the type used in the Java intermediary JNI class (as specified in the "jtype" typemap) to the Java type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap). This typemap provides the conversion for the parameters in the director methods when calling up from C++ to Java.
For primitive types, this typemap is usually specified as:
%typemap(javadirectorin) int "$jniinput"
The $jniinput special variable is analogous to $javainput special variable.
It is replaced by the input parameter name.
%typemap(javadirectorout)
Conversion from jstype to jtype for director methods. These are Java code typemaps which transform the type used in the Java module class, proxy classes and type wrapper classes (as specified in the "jstype" typemap) to the type used in the Java intermediary JNI class (as specified in the "jtype" typemap). This typemap provides the conversion for the return type in the director methods when returning from the C++ to Java upcall.
For primitive types, this typemap is usually specified as:
%typemap(javadirectorout) int "$javacall"
The $javacall special variable is analogous to the $jnicall special variable.
It is replaced by the call to the target Java method.
The target method is the method in the Java proxy class which overrides the virtual C++ method in the C++ base class.
%typemap(javapackage)
The "javapackage" typemap is optional; it serves to identify a class's Java package. This typemap should be used in conjunction with classes that are defined outside of the current SWIG interface file. For example:
// class Foo is handled in a different interface file:
%import "Foo.i"
%feature("director") Example;
%inline {
class Bar { };
class Example {
public:
virtual ~Example();
void ping(Foo *arg1, Bar *arg2);
};
}
Assume that the Foo class is part of the Java package com.wombat.foo but the above interface file is part of the Java package com.wombat.example. Without the "javapackage" typemap, SWIG will assume that the Foo class belongs to com.wombat.example class. The corrected interface file looks like:
// class Foo is handled in a different interface file:
%import "Foo.i"
%typemap("javapackage") Foo, Foo *, Foo & "com.wombat.foo";
%feature("director") Example;
%inline {
class Bar { };
class Example {
public:
virtual ~Example();
void ping(Foo *arg1, Bar *arg2);
};
}
SWIG looks up the package based on the actual type (plain Foo, Foo pointer and Foo reference), so it is important to associate all three types with the desired package.
Practically speaking, you should create a separate SWIG interface file, which is %import-ed into each SWIG interface file, when you have multiple Java packages.
Note the helper macros below, OTHER_PACKAGE_SPEC and ANOTHER_PACKAGE_SPEC, which reduce the amount of extra typing.
"TYPE..." is useful when passing templated types to the macro, since multiargument template types appear to the SWIG preprocessor as multiple macro arguments.
%typemap("javapackage") SWIGTYPE, SWIGTYPE *, SWIGTYPE &
"package.for.most.classes";
%define OTHER_PACKAGE_SPEC(TYPE...)
%typemap("javapackage") TYPE, TYPE *, TYPE & "package.for.other.classes";
%enddef
%define ANOTHER_PACKAGE_SPEC(TYPE...)
%typemap("javapackage") TYPE, TYPE *, TYPE & "package.for.another.set";
%enddef
OTHER_PACKAGE_SPEC(Package_2_class_one)
ANOTHER_PACKAGE_SPEC(Package_3_class_two)
/* etc */
The basic strategy here is to provide a default package typemap for the majority of the classes, only providing "javapackage" typemaps for the exceptions.
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.
The default Proper Java enums approach to wrapping enums is somewhat verbose. This is to handle all possible C/C++ enums, in particular enums with initializers. The generated code can be simplified if the enum being wrapped does not have any initializers.
The following shows how to remove the support methods that are generated by default and instead use the methods in the Java enum base class java.lang.Enum and java.lang.Class for marshalling enums between C/C++ and Java. The type used for the typemaps below is enum SWIGTYPE which is the default type used for all enums. The "enums.swg" file should be examined in order to see the original overridden versions of the typemaps.
%include "enums.swg"
%typemap(javain) enum SWIGTYPE "$javainput.ordinal()"
%typemap(javaout) enum SWIGTYPE {
return $javaclassname.class.getEnumConstants()[$jnicall];
}
%typemap(javabody) enum SWIGTYPE ""
%inline %{
enum HairType { blonde, ginger, brunette };
void setHair(HairType h);
HairType getHair();
%}
SWIG will generate the following Java enum, which is somewhat simpler than the default:
public enum HairType {
blonde,
ginger,
brunette;
}
and the two Java proxy methods will be:
public static void setHair(HairType h) {
exampleJNI.setHair(h.ordinal());
}
public static HairType getHair() {
return HairType.class.getEnumConstants()[exampleJNI.getHair()];
}
For marshalling Java enums to C/C++ enums, the ordinal method is used to convert the Java enum into an integer value for passing to the JNI layer, see the "javain" typemap. For marshalling C/C++ enums to Java enums, the C/C++ enum value is cast to an integer in the C/C++ typemaps (not shown). This integer value is then used to index into the array of enum constants that the Java language provides. See the getEnumConstants method in the "javaout" typemap.
These typemaps can often be used as the default for wrapping enums as in many cases there won't be any enum initializers. In fact a good strategy is to always use these typemaps and to specifically handle enums with initializers using %apply. This would be done by using the original versions of these typemaps in "enums.swg" under another typemap name for applying using %apply.
This example demonstrates various ways in which C++ exceptions can be tailored and converted into Java exceptions. Let's consider a simple file class SimpleFile and an exception class FileException which it may throw on error:
%include "std_string.i" // for std::string typemaps
#include <string>
class FileException {
std::string message;
public:
FileException(const std::string& msg) : message(msg) {}
std::string what() {
return message;
}
};
class SimpleFile {
std::string filename;
public:
SimpleFile(const std::string& filename) : filename(filename) {}
void open() throw(FileException) {
...
}
};
As the open method has a C++ exception specification, SWIG will parse this and know that the method can throw an exception. The "throws" typemap is then used when SWIG encounters an exception specification. The default generic "throws" typemap looks like this:
%typemap(throws) SWIGTYPE, SWIGTYPE &, SWIGTYPE *, SWIGTYPE [ANY] %{
SWIG_JavaThrowException(jenv, SWIG_JavaRuntimeException,
"C++ $1_type exception thrown");
return $null;
%}
Basically SWIG will generate a C++ try catch block and the body of the "throws" typemap constitutes the catch block. The above typemap calls a SWIG supplied method which throws a java.lang.RuntimeException. This exception class is a runtime exception and therefore not a checked exception. If, however, we wanted to throw a checked exception, say java.io.IOException, then we could use the following typemap:
%typemap(throws, throws="java.io.IOException") FileException {
jclass excep = jenv->FindClass("java/io/IOException");
if (excep)
jenv->ThrowNew(excep, $1.what().c_str());
return $null;
}
Note that this typemap uses the 'throws' typemap attribute to ensure a throws clause is generated. The generated proxy method then specifies the checked exception by containing java.io.IOException in the throws clause:
public class SimpleFile {
...
public void open() throws java.io.IOException { ... }
}
Lastly, if you don't want to map your C++ exception into one of the standard Java exceptions, the C++ class can be wrapped and turned into a custom Java exception class. If we go back to our example, the first thing we must do is get SWIG to wrap FileException and ensure that it derives from java.lang.Exception. Additionally, we might want to override the java.lang.Exception.getMessage() method. The typemaps to use then are as follows:
%typemap(javabase) FileException "java.lang.Exception";
%typemap(javacode) FileException %{
public String getMessage() {
return what();
}
%}
This generates:
public class FileException extends java.lang.Exception {
...
public String getMessage() {
return what();
}
public FileException(String msg) { ... }
public String what() {
return exampleJNI.FileException_what(swigCPtr, this);
}
}
We could alternatively have used %rename to rename what() into getMessage().
A Java exception can be thrown from any Java or JNI code. Therefore, as most typemaps contain either Java or JNI code, just about any typemap could throw an exception. The following example demonstrates exception handling on a type by type basis by checking for 'Not a number' (NaN) whenever a parameter of type float is wrapped.
Consider the following C++ code:
bool calculate(float first, float second);
To validate every float being passed to C++, we could precede the code being wrapped by the following typemap which throws a runtime exception whenever the float is 'Not a Number':
%module example
%typemap(javain) float "$module.CheckForNaN($javainput)"
%pragma(java) modulecode=%{
/** Simply returns the input value unless it is not a number,
whereupon an exception is thrown. */
static protected float CheckForNaN(float num) {
if (Float.isNaN(num))
throw new RuntimeException("Not a number");
return num;
}
%}
Note that the CheckForNaN support method has been added to the module class using the modulecode pragma. The following shows the generated code of interest:
public class example {
...
/** Simply returns the input value unless it is not a number,
whereupon an exception is thrown. */
static protected float CheckForNaN(float num) {
if (Float.isNaN(num))
throw new RuntimeException("Not a number");
return num;
}
public static boolean calculate(float first, float second) {
return exampleJNI.calculate(example.CheckForNaN(first), example.CheckForNaN(second));
}
}
Note that the "javain" typemap is used for every occurrence of a float being used as an input. Of course, we could have targeted the typemap at a particular parameter by using float first, say, instead of just float.
The exception checking could alternatively have been placed into the 'pre' attribute that the "javain" typemap supports. The "javain" typemap above could be replaced with the following:
%typemap(javain, pre=" $module.CheckForNaN($javainput);") float "$javainput"
which would modify the calculate function to instead be generated as:
public class example {
...
public static boolean calculate(float first, float second) {
example.CheckForNaN(first);
example.CheckForNaN(second);
{
return exampleJNI.calculate(first, second);
}
}
}
See the Date marshalling example for an example using further "javain" typemap attributes.
If we decide that what we actually want is a checked exception instead of a runtime exception, we can change this easily enough. The proxy method that uses float as an input, must then add the exception class to the throws clause. SWIG can handle this as it supports the 'throws' typemap attribute for specifying classes for the throws clause. Thus we can modify the pragma and the typemap for the throws clause:
%typemap(javain, throws="java.lang.Exception") float "$module.CheckForNaN($javainput)"
%pragma(java) modulecode=%{
/** Simply returns the input value unless it is not a number,
whereupon an exception is thrown. */
static protected float CheckForNaN(float num) throws java.lang.Exception {
if (Float.isNaN(num))
throw new RuntimeException("Not a number");
return num;
}
%}
The calculate method now has a throws clause and even though the typemap is used twice for both float first and float second, the throws clause contains a single instance of java.lang.Exception:
public class example {
...
/** Simply returns the input value unless it is not a number,
whereupon an exception is thrown. */
static protected float CheckForNaN(float num) throws java.lang.Exception {
if (Float.isNaN(num))
throw new RuntimeException("Not a number");
return num;
}
public static boolean calculate(float first, float second) throws java.lang.Exception {
return exampleJNI.calculate(example.CheckForNaN(first), example.CheckForNaN(second));
}
}
If we were a martyr to the JNI cause, we could replace the succinct code within the "javain" typemap with a few pages of JNI code. If we had, we would have put it in the "in" typemap which, like all JNI and Java typemaps, also supports the 'throws' attribute.
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(char));
strcpy($1[i], c_string);
(*jenv)->ReleaseStringUTFChars(jenv, j_string, c_string);
(*jenv)->DeleteLocalRef(jenv, j_string);
}
$1[i] = 0;
}
/* This cleans up the memory we malloc'd before the function call */
%typemap(freearg) char ** {
int i;
for (i=0; i<size$argnum-1; i++)
free($1[i]);
free($1);
}
/* This allows a C function to return a char ** as a Java String array */
%typemap(out) char ** {
int i;
int len=0;
jstring temp_string;
const jclass clazz = (*jenv)->FindClass(jenv, "java/lang/String");
while ($1[len]) len++;
jresult = (*jenv)->NewObjectArray(jenv, len, clazz, NULL);
/* exception checking omitted */
for (i=0; i<len; i++) {
temp_string = (*jenv)->NewStringUTF(jenv, *result++);
(*jenv)->SetObjectArrayElement(jenv, jresult, i, temp_string);
(*jenv)->DeleteLocalRef(jenv, temp_string);
}
}
/* These 3 typemaps tell SWIG what JNI and Java types to use */
%typemap(jni) char ** "jobjectArray"
%typemap(jtype) char ** "String[]"
%typemap(jstype) char ** "String[]"
/* These 2 typemaps handle the conversion of the jtype to jstype typemap type
and vice versa */
%typemap(javain) char ** "$javainput"
%typemap(javaout) char ** {
return $jnicall;
}
/* Now a few test functions */
%inline %{
int print_args(char **argv) {
int i = 0;
while (argv[i]) {
printf("argv[%d] = %s\n", i, argv[i]);
i++;
}
return i;
}
char **get_args() {
static char *values[] = { "Dave", "Mike", "Susan", "John", "Michelle", 0};
return &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 runme.java
public class runme {
static {
try {
System.loadLibrary("example");
} catch (UnsatisfiedLinkError e) {
System.err.println("Native code library failed to load. " + e);
System.exit(1);
}
}
public static void main(String argv[]) {
String animals[] = {"Cat","Dog","Cow","Goat"};
example.print_args(animals);
String args[] = example.get_args();
for (int i=0; i<args.length; i++)
System.out.println(i + ":" + args[i]);
}
}
When compiled and run we get:
$ java runme 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.
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(char));
strcpy($2[i], c_string);
(*jenv)->ReleaseStringUTFChars(jenv, j_string, c_string);
(*jenv)->DeleteLocalRef(jenv, j_string);
}
$2[i] = 0;
}
%typemap(freearg) (int argc, char **argv) {
int i;
for (i=0; i<$1-1; i++)
free($2[i]);
free($2);
}
%typemap(jni) (int argc, char **argv) "jobjectArray"
%typemap(jtype) (int argc, char **argv) "String[]"
%typemap(jstype) (int argc, char **argv) "String[]"
%typemap(javain) (int argc, char **argv) "$javainput"
When writing a multiple-argument typemap, each of the types is referenced by a variable such as $1 or $2. The typemap code simply fills in the appropriate values from the supplied Java parameter.
With the above typemap in place, you will find it no longer necessary to supply the argument count. This is automatically set by the typemap code. For example:
example.foo(new String[]{"red", "green", "blue", "white"});
A common problem in some C programs is that values may be returned in function parameters rather than in the return value of a function. The typemaps.i file defines INPUT, OUTPUT and INOUT typemaps which can be used to solve some instances of this problem. This library file uses an array as a means of moving data to and from Java when wrapping a C function that takes non const pointers or non const references as parameters.
Now we are going to outline an alternative approach to using arrays for C pointers. The INOUT typemap uses a double[] array for receiving and returning the double* parameters. In this approach we are able to use a Java class myDouble instead of double[] arrays where the C pointer double* is required.
Here is our example function:
/* Returns a status value and two values in out1 and out2 */ int spam(double a, double b, double *out1, double *out2);
If we define a structure MyDouble containing a double member variable and use some typemaps we can solve this problem. For example we could put the following through SWIG:
%module example
/* Define a new structure to use instead of double * */
%inline %{
typedef struct {
double value;
} MyDouble;
%}
%{
/* Returns a status value and two values in out1 and out2 */
int spam(double a, double b, double *out1, double *out2) {
int status = 1;
*out1 = a*10.0;
*out2 = b*100.0;
return status;
};
%}
/*
This typemap will make any double * function parameters with name OUTVALUE take an
argument of MyDouble instead of double *. This will
allow the calling function to read the double * value after returning from the function.
*/
%typemap(in) double *OUTVALUE {
jclass clazz = jenv->FindClass("MyDouble");
jfieldID fid = jenv->GetFieldID(clazz, "swigCPtr", "J");
jlong cPtr = jenv->GetLongField($input, fid);
MyDouble *pMyDouble = NULL;
*(MyDouble **)&pMyDouble = *(MyDouble **)&cPtr;
$1 = &pMyDouble->value;
}
%typemap(jtype) double *OUTVALUE "MyDouble"
%typemap(jstype) double *OUTVALUE "MyDouble"
%typemap(jni) double *OUTVALUE "jobject"
%typemap(javain) double *OUTVALUE "$javainput"
/* Now we apply the typemap to the named variables */
%apply double *OUTVALUE { double *out1, double *out2 };
int spam(double a, double b, double *out1, double *out2);
Note that the C++ JNI calling convention has been used this time and so must be compiled as C++ and the -c++ commandline must be passed to SWIG. JNI error checking has been omitted for clarity.
What the typemaps do are make the named double* function parameters use our new MyDouble wrapper structure. The "in" typemap takes this structure, gets the C++ pointer to it, takes the double value member variable and passes it to the C++ spam function. In Java, when the function returns, we use the SWIG created getValue() function to get the output value. The following Java program demonstrates this:
// File: runme.java
public class runme {
static {
try {
System.loadLibrary("example");
} catch (UnsatisfiedLinkError e) {
System.err.println("Native code library failed to load. " + e);
System.exit(1);
}
}
public static void main(String argv[]) {
MyDouble out1 = new MyDouble();
MyDouble out2 = new MyDouble();
int ret = example.spam(1.2, 3.4, out1, out2);
System.out.println(ret + " " + out1.getValue() + " " + out2.getValue());
}
}
When compiled and run we get:
$ java runme 1 12.0 340.0
SWIG support for polymorphism works in that the appropriate virtual function is called. However, the default generated code does not allow for downcasting. Let's examine this with the following code:
%include "std_string.i"
#include <iostream>
using namespace std;
class Vehicle {
public:
virtual void start() = 0;
...
};
class Ambulance : public Vehicle {
string vol;
public:
Ambulance(string volume) : vol(volume) {}
virtual void start() {
cout << "Ambulance started" << endl;
}
void sound_siren() {
cout << vol << " siren sounded!" << endl;
}
...
};
Vehicle *vehicle_factory() {
return new Ambulance("Very loud");
}
If we execute the following Java code:
Vehicle vehicle = example.vehicle_factory(); vehicle.start(); Ambulance ambulance = (Ambulance)vehicle; ambulance.sound_siren();
We get:
Ambulance started
java.lang.ClassCastException
at runme.main(runme.java:16)
Even though we know from examination of the C++ code that vehicle_factory returns an object of type Ambulance, we are not able to use this knowledge to perform the downcast in Java. This occurs because the runtime type information is not completely passed from C++ to Java when returning the type from vehicle_factory(). Usually this is not a problem as virtual functions do work by default, such as in the case of start(). There are a few solutions to getting downcasts to work.
The first is not to use a Java cast but a call to C++ to make the cast. Add this to your code:
%exception Ambulance::dynamic_cast(Vehicle *vehicle) {
$action
if (!result) {
jclass excep = jenv->FindClass("java/lang/ClassCastException");
if (excep) {
jenv->ThrowNew(excep, "dynamic_cast exception");
}
}
}
%extend Ambulance {
static Ambulance *dynamic_cast(Vehicle *vehicle) {
return dynamic_cast<Ambulance *>(vehicle);
}
};
It would then be used from Java like this
Ambulance ambulance = Ambulance.dynamic_cast(vehicle); ambulance.sound_siren();
Should vehicle not be of type ambulance then a Java ClassCastException is thrown. The next solution is a purer solution in that Java downcasts can be performed on the types. Add the following before the definition of vehicle_factory:
%typemap(out) Vehicle * {
Ambulance *downcast = dynamic_cast<Ambulance *>($1);
*(Ambulance **)&$result = downcast;
}
%typemap(javaout) Vehicle * {
return new Ambulance($jnicall, $owner);
}
Here we are using our knowledge that vehicle_factory always returns type Ambulance so that the Java proxy is created as a type Ambulance. If vehicle_factory can manufacture any type of Vehicle and we want to be able to downcast using Java casts for any of these types, then a different approach is needed. Consider expanding our example with a new Vehicle type and a more flexible factory function:
class FireEngine : public Vehicle {
public:
FireEngine() {}
virtual void start() {
cout << "FireEngine started" << endl;
}
void roll_out_hose() {
cout << "Hose rolled out" << endl;
}
...
};
Vehicle *vehicle_factory(int vehicle_number) {
if (vehicle_number == 0)
return new Ambulance("Very loud");
else
return new FireEngine();
}
To be able to downcast with this sort of Java code:
FireEngine fireengine = (FireEngine)example.vehicle_factory(1); fireengine.roll_out_hose(); Ambulance ambulance = (Ambulance)example.vehicle_factory(0); ambulance.sound_siren();
the following typemaps targeted at the vehicle_factory function will achieve this. Note that in this case, the Java class is constructed using JNI code rather than passing a pointer across the JNI boundary in a Java long for construction in Java code.
%typemap(jni) Vehicle *vehicle_factory "jobject"
%typemap(jtype) Vehicle *vehicle_factory "Vehicle"
%typemap(jstype) Vehicle *vehicle_factory "Vehicle"
%typemap(javaout) Vehicle *vehicle_factory {
return $jnicall;
}
%typemap(out) Vehicle *vehicle_factory {
Ambulance *ambulance = dynamic_cast<Ambulance *>($1);
FireEngine *fireengine = dynamic_cast<FireEngine *>($1);
if (ambulance) {
// call the Ambulance(long cPtr, boolean cMemoryOwn) constructor
jclass clazz = jenv->FindClass("Ambulance");
if (clazz) {
jmethodID mid = jenv->GetMethodID(clazz, "<init>", "(JZ)V");
if (mid) {
jlong cptr = 0;
*(Ambulance **)&cptr = ambulance;
$result = jenv->NewObject(clazz, mid, cptr, false);
}
}
} else if (fireengine) {
// call the FireEngine(long cPtr, boolean cMemoryOwn) constructor
jclass clazz = jenv->FindClass("FireEngine");
if (clazz) {
jmethodID mid = jenv->GetMethodID(clazz, "<init>", "(JZ)V");
if (mid) {
jlong cptr = 0;
*(FireEngine **)&cptr = fireengine;
$result = jenv->NewObject(clazz, mid, cptr, false);
}
}
}
else {
cout << "Unexpected type " << endl;
}
if (!$result)
cout << "Failed to create new java object" << endl;
}
Better error handling would need to be added into this code. There are other solutions to this problem, but this last example demonstrates some more involved JNI code. SWIG usually generates code which constructs the proxy classes using Java code as it is easier to handle error conditions and is faster. Note that the JNI code above uses a number of string lookups to call a constructor, whereas this would not occur using byte compiled Java code.
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. The equals() method is usually accompanied by a hashCode() method in order to fulfill the requirement that the hash code is equal for equal objects. Pure Java code methods like these can be easily added:
%typemap(javacode) SWIGTYPE %{
public boolean equals(Object obj) {
boolean equal = false;
if (obj instanceof $javaclassname)
equal = ((($javaclassname)obj).swigCPtr == this.swigCPtr);
return equal;
}
public int hashCode() {
return (int)getPointer();
}
%}
class Foo { };
Foo* returnFoo(Foo *foo) { return foo; }
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));
One might wonder why the common code that SWIG emits for the proxy and type wrapper classes is not pushed into a base class. The reason is that although swigCPtr could be put into a common base class for all classes wrapping C structures, it would not work for C++ classes involved in an inheritance chain. Each class derived from a base needs a separate swigCPtr because C++ compilers sometimes use a different pointer value when casting a derived class to a base. Additionally as Java only supports single inheritance, it would not be possible to derive wrapped classes from your own pure Java classes if the base class has been 'used up' by SWIG. However, you may want to move some of the common code into a base class. Here is an example which uses a common base class for all proxy classes and type wrapper classes:
%typemap(javabase) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [],
SWIGTYPE (CLASS::*) "SWIG"
%typemap(javacode) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [],
SWIGTYPE (CLASS::*) %{
protected long getPointer() {
return swigCPtr;
}
%}
Define new base class called SWIG:
public abstract class SWIG {
protected abstract long getPointer();
public boolean equals(Object obj) {
boolean equal = false;
if (obj instanceof SWIG)
equal = (((SWIG)obj).getPointer() == this.getPointer());
return equal;
}
SWIGTYPE_p_void getVoidPointer() {
return new SWIGTYPE_p_void(getPointer(), false);
}
}
This example contains some useful functionality which you may want in your code.
Pointers to pointers are often used as output parameters in C factory type functions. These are a bit more tricky to handle. Consider the following situation where a Butler can be hired and fired:
typedef struct {
int hoursAvailable;
char *greeting;
} Butler;
// Note: HireButler will allocate the memory
// The caller must free the memory by calling FireButler()!!
extern int HireButler(Butler **ppButler);
extern void FireButler(Butler *pButler);
C code implementation:
int HireButler(Butler **ppButler) {
Butler *pButler = (Butler *)malloc(sizeof(Butler));
pButler->hoursAvailable = 24;
pButler->greeting = (char *)malloc(32);
strcpy(pButler->greeting, "At your service Sir");
*ppButler = pButler;
return 1;
}
void FireButler(Butler *pButler) {
free(pButler->greeting);
free(pButler);
}
Let's take two approaches to wrapping this code. The first is to provide a functional interface, much like the original C interface. The following Java code shows how we intend the code to be used:
Butler jeeves = new Butler();
example.HireButler(jeeves);
System.out.println("Greeting: " + jeeves.getGreeting());
System.out.println("Availability: " + jeeves.getHoursAvailable() + " hours per day");
example.FireButler(jeeves);
Resulting in the following output when run:
Greeting: At your service Sir Availability: 24 hours per day
Note the usage is very much like it would be used if we were writing C code, that is, explicit memory management is needed. No C memory is allocated in the construction of the Butler proxy class and the proxy class will not destroy the underlying C memory when it is collected. A number of typemaps and features are needed to implement this approach. The following interface file code should be placed before SWIG parses the above C code.
%module example
// Do not generate the default proxy constructor or destructor
%nodefaultctor Butler;
%nodefaultdtor Butler;
// Add in pure Java code proxy constructor
%typemap(javacode) Butler %{
/** This constructor creates the proxy which initially does not create nor own any C memory */
public Butler() {
this(0, false);
}
%}
// Type typemaps for marshalling Butler **
%typemap(jni) Butler ** "jobject"
%typemap(jtype) Butler ** "Butler"
%typemap(jstype) Butler ** "Butler"
// Typemaps for Butler ** as a parameter output type
%typemap(in) Butler ** (Butler *ppButler = 0) %{
$1 = &ppButler;
%}
%typemap(argout) Butler ** {
// Give Java proxy the C pointer (of newly created object)
jclass clazz = (*jenv)->FindClass(jenv, "Butler");
jfieldID fid = (*jenv)->GetFieldID(jenv, clazz, "swigCPtr", "J");
jlong cPtr = 0;
*(Butler **)&cPtr = *$1;
(*jenv)->SetLongField(jenv, $input, fid, cPtr);
}
%typemap(javain) Butler ** "$javainput"
Note that the JNI code sets the proxy's swigCPtr member variable to point to the newly created object. The swigCMemOwn remains unchanged (at false), so that the proxy does not own the memory.
Note: The old %nodefault directive disabled the default constructor and destructor at the same time. This is unsafe in most of the cases, and you can use the explicit %nodefaultctor and %nodefaultdtor directives to achieve the same result if needed.
The second approach offers a more object oriented interface to the Java user. We do this by making the Java proxy class's constructor call the HireButler() method to create the underlying C object. Additionally we get the proxy to take ownership of the memory so that the finalizer will call the FireButler() function. The proxy class will thus take ownership of the memory and clean it up when no longer needed. We will also prevent the user from being able to explicitly call the HireButler() and FireButler() functions. Usage from Java will simply be:
Butler jeeves = new Butler();
System.out.println("Greeting: " + jeeves.getGreeting());
System.out.println("Availability: " + jeeves.getHoursAvailable() + " hours per day");
Note that the Butler class is used just like any other Java class and no extra coding by the user needs to be written to clear up the underlying C memory as the finalizer will be called by the garbage collector which in turn will call the FireButler() function. To implement this, we use the above interface file code but remove the javacode typemap and add the following:
// Don't expose the memory allocation/de-allocation functions
%ignore FireButler(Butler *pButler);
%ignore HireButler(Butler **ppButler);
// Add in a custom proxy constructor and destructor
%extend Butler {
Butler() {
Butler *pButler = 0;
HireButler(&pButler);
return pButler;
}
~Butler() {
FireButler($self);
}
}
Note that the code in %extend is using a C++ type constructor and destructor, yet the generated code will still compile as C code, see Adding member functions to C structures. The C functional interface has been completely morphed into an object-oriented interface and the Butler class would behave much like any pure Java class and feel more natural to Java users.
This example shows how to prevent premature garbage collection of objects when the underlying C++ class returns a pointer or reference to a member variable.
Consider the following C++ code:
struct Wheel {
int size;
Wheel(int sz) : size(sz) {}
};
class Bike {
Wheel wheel;
public:
Bike(int val) : wheel(val) {}
Wheel& getWheel() { return wheel; }
};
and the following usage from Java after running the code through SWIG:
Wheel wheel = new Bike(10).getWheel();
System.out.println("wheel size: " + wheel.getSize());
// Simulate a garbage collection
System.gc();
System.runFinalization();
System.out.println("wheel size: " + wheel.getSize());
Don't be surprised that if the resulting output gives strange results such as...
wheel size: 10 wheel size: 135019664
What has happened here is the garbage collector has collected the Bike instance as it doesn't think it is needed any more. The proxy instance, wheel, contains a reference to memory that was deleted when the Bike instance was collected. In order to prevent the garbage collector from collecting the Bike instance a reference to the Bike must be added to the wheel instance. You can do this by adding the reference when the getWheel() method is called using the following typemaps.
%typemap(javacode) Wheel %{
// Ensure that the GC doesn't collect any Bike instance set from Java
private Bike bikeReference;
protected void addReference(Bike bike) {
bikeReference = bike;
}
%}
// Add a Java reference to prevent premature garbage collection and resulting use
// of dangling C++ pointer. Intended for methods that return pointers or
// references to a member variable.
%typemap(javaout) Wheel& getWheel {
long cPtr = $jnicall;
$javaclassname ret = null;
if (cPtr != 0) {
ret = new $javaclassname(cPtr, $owner);
ret.addReference(this);
}
return ret;
}
The code in the first typemap gets added to the Wheel proxy class. The code in the second typemap constitutes the bulk of the code in the generated getWheel() function:
public class Wheel {
...
// Ensure that the GC doesn't collect any bike set from Java
private Bike bikeReference;
protected void addReference(Bike bike) {
bikeReference = bike;
}
}
public class Bike {
...
public Wheel getWheel() {
long cPtr = exampleJNI.Bike_getWheel(swigCPtr, this);
Wheel ret = null;
if (cPtr != 0) {
ret = new Wheel(cPtr, false);
ret.addReference(this);
}
return ret;
}
}
Note the addReference call.
Managing memory can be tricky when using C++ and Java proxy classes. The previous example shows one such case and this example looks at memory management for a class passed to a C++ method which expects the object to remain in scope after the function has returned. Consider the following two C++ classes:
struct Element {
int value;
Element(int val) : value(val) {}
};
class Container {
Element* element;
public:
Container() : element(0) {}
void setElement(Element* e) { element = e; }
Element* getElement() { return element; }
};
and usage from C++
Container container;
Element element(20);
container.setElement(&element);
cout << "element.value: " << container.getElement()->value << endl;
and more or less equivalent usage from Java
Container container = new Container();
container.setElement(new Element(20));
System.out.println("element value: " + container.getElement().getValue());
The C++ code will always print out 20, but the value printed out may not be this in the Java equivalent code. In order to understand why, consider a garbage collection occuring...
Container container = new Container();
container.setElement(new Element(20));
// Simulate a garbage collection
System.gc();
System.runFinalization();
System.out.println("element value: " + container.getElement().getValue());
The temporary element created with new Element(20) could get garbage collected which ultimately means the container variable is holding a dangling pointer, thereby printing out any old random value instead of the expected value of 20. One solution is to add in the appropriate references in the Java layer...
public class Container {
...
// Ensure that the GC doesn't collect any Element set from Java
// as the underlying C++ class stores a shallow copy
private Element elementReference;
private long getCPtrAndAddReference(Element element) {
elementReference = element;
return Element.getCPtr(element);
}
public void setElement(Element e) {
exampleJNI.Container_setElement(swigCPtr, this, getCPtrAndAddReference(e), e);
}
}
The following typemaps will generate the desired code. The 'javain' typemap matches the input parameter type for the setElement method. The 'javacode' typemap simply adds in the specified code into the Java proxy class.
%typemap(javain) Element *e "getCPtrAndAddReference($javainput)"
%typemap(javacode) Container %{
// Ensure that the GC doesn't collect any element set from Java
// as the underlying C++ class stores a shallow copy
private Element elementReference;
private long getCPtrAndAddReference(Element element) {
elementReference = element;
return Element.getCPtr(element);
}
%}
The NaN Exception example is a simple example of the "javain" typemap and its 'pre' attribute. This example demonstrates how a C++ date class, say CDate, can be mapped onto the standard Java date class, java.util.GregorianCalendar by using the 'pre', 'post' and 'pgcppname' attributes of the "javain" typemap. The idea is that the GregorianCalendar is used wherever the C++ API uses a CDate. Let's assume the code being wrapped is as follows:
class CDate {
public:
CDate(int year, int month, int day);
int getYear();
int getMonth();
int getDay();
...
};
struct Action {
static int doSomething(const CDate &dateIn, CDate &dateOut);
Action(const CDate &date, CDate &dateOut);
};
Note that dateIn is const and therefore read only and dateOut is a non-const output type.
First let's look at the code that is generated by default, where the Java proxy class CDate is used in the proxy interface:
public class Action {
...
public static int doSomething(CDate dateIn, CDate dateOut) {
return exampleJNI.Action_doSomething(CDate.getCPtr(dateIn), dateIn,
CDate.getCPtr(dateOut), dateOut);
}
public Action(CDate date, CDate dateOut) {
this(exampleJNI.new_Action(CDate.getCPtr(date), date,
CDate.getCPtr(dateOut), dateOut), true);
}
}
The CDate & and const CDate & Java code is generated from the following two default typemaps:
%typemap(jstype) SWIGTYPE & "$javaclassname" %typemap(javain) SWIGTYPE & "$javaclassname.getCPtr($javainput)"
where '$javaclassname' is translated into the proxy class name, CDate and '$javainput' is translated into the name of the parameter, eg dateIn. From Java, the intention is then to call into a modifed API with something like:
java.util.GregorianCalendar calendarIn =
new java.util.GregorianCalendar(2011, java.util.Calendar.APRIL, 13, 0, 0, 0);
java.util.GregorianCalendar calendarOut = new java.util.GregorianCalendar();
// Note in calls below, calendarIn remains unchanged and calendarOut
// is set to a new value by the C++ call
Action.doSomething(calendarIn, calendarOut);
Action action = new Action(calendarIn, calendarOut);
To achieve this mapping, we need to alter the default code generation slightly so that at the Java layer, a GregorianCalendar is converted into a CDate. The JNI intermediary layer will still take a pointer to the underlying CDate class. The typemaps to achieve this are shown below.
%typemap(jstype) const CDate& "java.util.GregorianCalendar"
%typemap(javain,
pre=" CDate temp$javainput = new CDate($javainput.get(java.util.Calendar.YEAR), "
"$javainput.get(java.util.Calendar.MONTH), $javainput.get(java.util.Calendar.DATE));",
pgcppname="temp$javainput") const CDate &
"$javaclassname.getCPtr(temp$javainput)"
%typemap(jstype) CDate& "java.util.Calendar"
%typemap(javain,
pre=" CDate temp$javainput = new CDate($javainput.get(java.util.Calendar.YEAR), "
"$javainput.get(java.util.Calendar.MONTH), $javainput.get(java.util.Calendar.DATE));",
post=" $javainput.set(temp$javainput.getYear(), temp$javainput.getMonth(), "
"temp$javainput.getDay(), 0, 0, 0);",
pgcppname="temp$javainput") CDate &
"$javaclassname.getCPtr(temp$javainput)"
The resulting generated proxy code in the Action class follows:
public class Action {
...
public static int doSomething(java.util.GregorianCalendar dateIn,
java.util.Calendar dateOut) {
CDate tempdateIn = new CDate(dateIn.get(java.util.Calendar.YEAR),
dateIn.get(java.util.Calendar.MONTH),
dateIn.get(java.util.Calendar.DATE));
CDate tempdateOut = new CDate(dateOut.get(java.util.Calendar.YEAR),
dateOut.get(java.util.Calendar.MONTH),
dateOut.get(java.util.Calendar.DATE));
try {
return exampleJNI.Action_doSomething(CDate.getCPtr(tempdateIn), tempdateIn,
CDate.getCPtr(tempdateOut), tempdateOut);
} finally {
dateOut.set(tempdateOut.getYear(), tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
}
}
static private long SwigConstructAction(java.util.GregorianCalendar date,
java.util.Calendar dateOut) {
CDate tempdate = new CDate(date.get(java.util.Calendar.YEAR),
date.get(java.util.Calendar.MONTH),
date.get(java.util.Calendar.DATE));
CDate tempdateOut = new CDate(dateOut.get(java.util.Calendar.YEAR),
dateOut.get(java.util.Calendar.MONTH),
dateOut.get(java.util.Calendar.DATE));
try {
return exampleJNI.new_Action(CDate.getCPtr(tempdate), tempdate,
CDate.getCPtr(tempdateOut), tempdateOut);
} finally {
dateOut.set(tempdateOut.getYear(), tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
}
}
public Action(java.util.GregorianCalendar date, java.util.Calendar dateOut) {
this(Action.SwigConstructAction(date, dateOut), true);
}
}
A few things to note:
This section is intended to address frequently asked questions and frequently encountered problems when using Java directors.
Open up the C++ wrapper source code file and look for "method_foo" (include the double quotes, they are important!)
Look at the JNI field descriptor and make sure that each class that occurs in the descriptor has the correct package name in front of it.
If the package name is incorrect, put a "javapackage" typemap in your SWIG interface file.
Use the template's renamed name as the argument to the "javapackage" typemap:
%typemap(javapackage) std::vector<int> "your.package.here" %template(VectorOfInt) std::vector<int>;
When I pass class pointers or references through a C++ upcall and I try to type cast them, Java complains with a ClassCastException. What am I doing wrong?
Normally, a non-director generated Java proxy class creates temporary Java objects as follows:
public static void MyClass_method_upcall(MyClass self, long jarg1)
{
Foo darg1 = new Foo(jarg1, false);
self.method_upcall(darg1);
}
Unfortunately, this loses the Java type information that is part of the underlying Foo director proxy class's Java object pointer causing the type cast to fail. The SWIG Java module's director code attempts to correct the problem, but only for director-enabled classes, since the director class retains a global reference to its Java object. Thus, for director-enabled classes and only for director-enabled classes, the generated proxy Java code looks something like:
public static void MyClass_method_upcall(MyClass self, long jarg1,
Foo jarg1_object)
{
Foo darg1 = (jarg1_object != null ? jarg1_object : new Foo(jarg1, false));
self.method_upcall(darg1);
}
When you import a SWIG interface file containing class definitions, the classes you want to be director-enabled must be have the feature("director") enabled for type symmetry to work.
This applies even when the class being wrapped isn't a director-enabled class but takes parameters that are director-enabled classes.
The current "type symmetry" design will work for simple C++ inheritance, but will most likely fail for anything more complicated such as tree or diamond C++ inheritance hierarchies.
Those who are interested in challenging problems are more than welcome to hack the Java::Java_director_declaration method in Source/Modules/java.cxx.
If all else fails, you can use the downcastXXXXX() method to attempt to recover the director class's Java object pointer. For the Java Foo proxy class, the Foo director class's java object pointer can be accessed through the javaObjectFoo() method. The generated method's signature is:
public static Foo javaObjectFoo(Foo obj);
From your code, this method is invoked as follows:
public class MyClassDerived {
public void method_upcall(Foo foo_object)
{
FooDerived derived = (foo_object != null ?
(FooDerived) Foo.downcastFoo(foo_object) : null);
/* rest of your code here */
}
}
An good approach for managing downcasting is placing a static method in each derived class that performs the downcast from the superclass, e.g.,
public class FooDerived extends Foo {
/* ... */
public static FooDerived downcastFooDerived(Foo foo_object)
{
try {
return (foo_object != null ? (FooDerived) Foo.downcastFoo(foo_object);
}
catch (ClassCastException exc) {
// Wasn't a FooDerived object, some other subclass of Foo
return null;
}
}
}
Then change the code in MyClassDerived as follows:
public class MyClassDerived extends MyClass {
/* ... */
public void method_upcall(Foo foo_object)
{
FooDerived derived = FooDerived.downcastFooDerived(foo_object);
/* rest of your code here */
}
}
Why isn't the proxy class declared abstract? Why aren't the director upcall methods in the proxy class declared abstract?
Declaring the proxy class and its methods abstract would break the JNI argument marshalling and SWIG's downcall functionality (going from Java to C++.) Create an abstract Java subclass that inherits from the director-enabled class instead. Using the previous Foo class example:
public abstract class UserVisibleFoo extends Foo {
/** Make sure user overrides this method, it's where the upcall
* happens.
*/
public abstract void method_upcall(Foo foo_object);
/// Downcast from Foo to UserVisibleFoo
public static UserVisibleFoo downcastUserVisibleFoo(Foo foo_object)
{
try {
return (foo_object != null ? (FooDerived) Foo.downcastFoo(foo_object) : null);
}
catch (ClassCastException exc) {
// Wasn't a FooDerived object, some other subclass of Foo
return null;
}
}
}
This doesn't prevent the user from creating subclasses derived from Foo, however, UserVisibleFoo provides the safety net that reminds the user to override the method_upcall() method.
The SWIG documentation system is currently deprecated. When it is resurrected JavaDoc comments will be fully supported. If you can't wait for the full documentation system a couple of workarounds are available. The %javamethodmodifiers feature can be used for adding proxy class method comments and module class method comments. The "javaimports" typemap can be hijacked for adding in proxy class JavaDoc comments. The jniclassimports or jniclassclassmodifiers pragmas can also be used for adding intermediary JNI class comments and likewise the moduleimports or moduleclassmodifiers pragmas for the module class. Here is an example adding in a proxy class and method comment:
%javamethodmodifiers Barmy::lose_marbles() "
/**
* Calling this method will make you mad.
* Use with <b>utmost</b> caution.
*/
public";
%typemap(javaimports) Barmy "
/** The crazy class. Use as a last resort. */"
class Barmy {
public:
void lose_marbles() {}
};
Note the "public" added at the end of the %javamethodmodifiers as this is the default for this feature. The generated proxy class with JavaDoc comments is then as follows:
/** The crazy class. Use as a last resort. */
public class Barmy {
...
/**
* Calling this method will make you mad.
* Use with <b>utmost</b> caution.
*/
public void lose_marbles() {
...
}
...
}
It is possible to run SWIG in a mode that does not produce proxy classes by using the -noproxy commandline option. The interface is rather primitive when wrapping structures or classes and is accessed through function calls to the module class. All the functions in the module class are wrapped by functions with identical names as those in the intermediary JNI class.
Consider the example we looked at when examining proxy classes:
class Foo {
public:
int x;
int spam(int num, Foo* foo);
};
When using -noproxy, type wrapper classes are generated instead of proxy classes. Access to all the functions and variables is through a C like set of functions where the first parameter passed is the pointer to the class, that is an instance of a type wrapper class. Here is what the module class looks like:
public class example {
public static void Foo_x_get(SWIGTYPE_p_Foo self, int x) {...}
public static int Foo_x_get(SWIGTYPE_p_Foo self) {...}
public static int Foo_spam(SWIGTYPE_p_Foo self, int num, SWIGTYPE_p_Foo foo) {...}
public static SWIGTYPE_p_Foo new_Foo() {...}
public static void delete_Foo(SWIGTYPE_p_Foo self) {...}
}
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.Foo_x_set(foo, 10); int var = example.Foo_x_get(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.
You may have some hand written JNI functions that you want to use in addition to the SWIG generated JNI functions. Adding these to your SWIG generated package is possible using the %native directive. If you don't want SWIG to wrap your JNI function then of course you can simply use the %ignore directive. However, if you want SWIG to generate just the Java code for a JNI function then use the %native directive. The C types for the parameters and return type must be specified in place of the JNI types and the function name must be the native method name. For example:
%native (HandRolled) void HandRolled(int, char *);
%{
JNIEXPORT void JNICALL Java_packageName_moduleName_HandRolled(JNIEnv *, jclass,
jlong, jstring);
%}
No C JNI function will be generated and the Java_packageName_moduleName_HandRolled function will be accessible using the SWIG generated Java native method call in the intermediary JNI class which will look like this:
public final static native void HandRolled(int jarg1, String jarg2);
and as usual this function is wrapped by another which for a global C function would appear in the module class:
public static void HandRolled(int arg0, String arg1) {
exampleJNI.HandRolled(arg0, arg1);
}
The packageName and moduleName must of course be correct else you will get linker errors when the JVM dynamically loads the JNI function. You may have to add in some "jtype", "jstype", "javain" and "javaout" typemaps when wrapping some JNI types. Here the default typemaps work for int and char *.
In summary the %native directive is telling SWIG to generate the Java code to access the JNI C code, but not the JNI C function itself. This directive is only really useful if you want to mix your own hand crafted JNI code and the SWIG generated code into one Java class or package.
If you're directly manipulating huge arrays of complex objects from Java, performance may suffer greatly when using the array functions in arrays_java.i. Try and minimise the expensive JNI calls to C/C++ functions, perhaps by using temporary Java variables instead of accessing the information directly from the C/C++ object.
Java classes without any finalizers generally speed up code execution as there is less for the garbage collector to do. Finalizer generation can be stopped by using an empty javafinalize typemap:
%typemap(javafinalize) SWIGTYPE ""
However, you will have to be careful about memory management and make sure that you code in a call to the delete() member function. This method normally calls the C++ destructor or free() for C code.
The generated code can be debugged using both a Java debugger and a C++ debugger using the usual debugging techniques. Breakpoints can be set in either Java or C++ code and so both can be debugged simultaneously. Most debuggers do not understand both Java and C++, with one noteable exception of Sun Studio, where it is possible to step from Java code into a JNI method within one environment.
Alternatively, debugging can involve placing debug printout statements in the JNI layer using the %exception directive. See the special variables for %exception section. Many of the default typemaps can also be overidden and modified for adding in extra logging/debug display information.
The -Xcheck:jni and -Xcheck:nabounds Java executable options are useful for debugging to make sure the JNI code is behaving. The -verbose:jni and -verbose:gc are also useful options for monitoring code behaviour.
The directory Examples/java has a number of further examples. Take a look at these if you want to see some of the techniques described in action. The Examples/index.html file in the parent directory contains the SWIG Examples Documentation and is a useful starting point. If your SWIG installation went well Unix users should be able to type make in each example directory, then java main to see them running. For the benefit of Windows users, there are also Visual C++ project files in a couple of the Windows Examples. There are also many regression tests in the Examples/test-suite directory. Many of these have runtime tests in the java subdirectory.