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 via the director feature.
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.
Android uses Java JNI and also works with SWIG. Please read the Android chapter in conjunction with this one if you are targeting Android.
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 lists 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. Assuming you have code you need to link to in a file called example.c, in order 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 -fPIC -c example_wrap.c -I/usr/java/include -I/usr/java/include/solaris $ gcc -fPIC -c example.c $ ld -G example_wrap.o example.o -o libexample.so
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.
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 option 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 option 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
SWIG won't create the directory, so make sure it exists beforehand.
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 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 named C++ namespaces and they can be mapped to Java packages, however, the default wrapping flattens the namespaces, effectively ignoring them. So by default, the namespace names do not appear in the module nor do namespaces result in a module that is broken up into submodules or packages. For example, if you have a file like this,
%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.
The default behaviour described above can be improved via the nspace feature. Note that it only works for classes, structs, unions and enums declared within a named C++ namespace. When the nspace feature is used, the C++ namespaces are converted into Java packages of the same name. Proxy classes are thus declared within a package and this proxy makes numerous calls to the JNI intermediary class which is declared in the unnamed package by default. As Java does not support types declared in a named package accessing types declared in an unnamed package, the -package commandline option described earlier generally should be used to provide a parent package. So if SWIG is run using the -package com.myco option, a wrapped class, MyWorld::Material::Color, can then be accessed as com.myco.MyWorld.Material.Color. If you don't specify a package, you will get the following warning:
example.i:16: Warning 826: The nspace feature is used on 'MyWorld::Material::Color' without -package. The generated code may not compile as Java does not support types declared in a named package accessing types declared in an unnamed package.
If it is undesirable to have a single top level package, the nspace feature may be used without the -package commandline option (and the resulting warning ignored) if all of the types exposed using SWIG are placed in a package using the nspace feature and the 'jniclasspackage' pragma is used to specify a package for the JNI intermediary class.
If the resulting use of the nspace feature and hence packages results in a proxy class in one package deriving or using a proxy class from another package, you will need to open up the visibility for the pointer constructor and getCPtr method from the default 'protected' to 'public' with the SWIG_JAVABODY_PROXY macro. See Java code typemaps.
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