diff options
Diffstat (limited to 'Examples/java')
78 files changed, 3645 insertions, 0 deletions
diff --git a/Examples/java/callback/Makefile b/Examples/java/callback/Makefile new file mode 100644 index 0000000..14c3017 --- /dev/null +++ b/Examples/java/callback/Makefile @@ -0,0 +1,18 @@ +TOP = ../.. +SWIG = $(TOP)/../preinst-swig +CXXSRCS = example.cxx +TARGET = example +INTERFACE = example.i +SWIGOPT = + +all:: java + +java:: + $(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \ + SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' java_cpp + javac *.java + +clean:: + $(MAKE) -f $(TOP)/Makefile java_clean + +check: all diff --git a/Examples/java/callback/example.cxx b/Examples/java/callback/example.cxx new file mode 100644 index 0000000..450d756 --- /dev/null +++ b/Examples/java/callback/example.cxx @@ -0,0 +1,4 @@ +/* File : example.cxx */ + +#include "example.h" + diff --git a/Examples/java/callback/example.h b/Examples/java/callback/example.h new file mode 100644 index 0000000..1a0e8c4 --- /dev/null +++ b/Examples/java/callback/example.h @@ -0,0 +1,23 @@ +/* File : example.h */ + +#include <cstdio> +#include <iostream> + +class Callback { +public: + virtual ~Callback() { std::cout << "Callback::~Callback()" << std:: endl; } + virtual void run() { std::cout << "Callback::run()" << std::endl; } +}; + + +class Caller { +private: + Callback *_callback; +public: + Caller(): _callback(0) {} + ~Caller() { delCallback(); } + void delCallback() { delete _callback; _callback = 0; } + void setCallback(Callback *cb) { delCallback(); _callback = cb; } + void call() { if (_callback) _callback->run(); } +}; + diff --git a/Examples/java/callback/example.i b/Examples/java/callback/example.i new file mode 100644 index 0000000..90beda0 --- /dev/null +++ b/Examples/java/callback/example.i @@ -0,0 +1,13 @@ +/* File : example.i */ +%module(directors="1") example +%{ +#include "example.h" +%} + +%include "std_string.i" + +/* turn on director wrapping Callback */ +%feature("director") Callback; + +%include "example.h" + diff --git a/Examples/java/callback/index.html b/Examples/java/callback/index.html new file mode 100644 index 0000000..c254520 --- /dev/null +++ b/Examples/java/callback/index.html @@ -0,0 +1,20 @@ +<html> +<head> +<title>SWIG:Examples:java:callback</title> +</head> + +<body bgcolor="#ffffff"> + + +<tt>SWIG/Examples/python/extend/</tt> +<hr> + +<H2>Implementing C++ callbacks in Java</H2> + +<p> +This example illustrates how to use directors to implement C++ callbacks in Java. +</p> + +<hr> +</body> +</html> diff --git a/Examples/java/callback/runme.java b/Examples/java/callback/runme.java new file mode 100644 index 0000000..4090f0a --- /dev/null +++ b/Examples/java/callback/runme.java @@ -0,0 +1,56 @@ +public class runme +{ + static { + try { + System.loadLibrary("example"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String[] args) + { + System.out.println("Adding and calling a normal C++ callback"); + System.out.println("----------------------------------------"); + + Caller caller = new Caller(); + Callback callback = new Callback(); + + caller.setCallback(callback); + caller.call(); + caller.delCallback(); + + callback = new JavaCallback(); + + System.out.println(); + System.out.println("Adding and calling a Java callback"); + System.out.println("------------------------------------"); + + caller.setCallback(callback); + caller.call(); + caller.delCallback(); + + // Test that a double delete does not occur as the object has already been deleted from the C++ layer. + // Note that the garbage collector can also call the delete() method via the finalizer (callback.finalize()) + // at any point after here. + callback.delete(); + + System.out.println(); + System.out.println("java exit"); + } +} + +class JavaCallback extends Callback +{ + public JavaCallback() + { + super(); + } + + public void run() + { + System.out.println("JavaCallback.run()"); + } +} + diff --git a/Examples/java/check.list b/Examples/java/check.list new file mode 100644 index 0000000..9728342 --- /dev/null +++ b/Examples/java/check.list @@ -0,0 +1,15 @@ +# see top-level Makefile.in +callback +class +constants +enum +extend +funcptr +multimap +native +pointer +reference +simple +template +typemap +variables diff --git a/Examples/java/class/Makefile b/Examples/java/class/Makefile new file mode 100644 index 0000000..14c3017 --- /dev/null +++ b/Examples/java/class/Makefile @@ -0,0 +1,18 @@ +TOP = ../.. +SWIG = $(TOP)/../preinst-swig +CXXSRCS = example.cxx +TARGET = example +INTERFACE = example.i +SWIGOPT = + +all:: java + +java:: + $(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \ + SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' java_cpp + javac *.java + +clean:: + $(MAKE) -f $(TOP)/Makefile java_clean + +check: all diff --git a/Examples/java/class/example.cxx b/Examples/java/class/example.cxx new file mode 100644 index 0000000..1e8e203 --- /dev/null +++ b/Examples/java/class/example.cxx @@ -0,0 +1,28 @@ +/* File : example.c */ + +#include "example.h" +#define M_PI 3.14159265358979323846 + +/* Move the shape to a new location */ +void Shape::move(double dx, double dy) { + x += dx; + y += dy; +} + +int Shape::nshapes = 0; + +double Circle::area(void) { + return M_PI*radius*radius; +} + +double Circle::perimeter(void) { + return 2*M_PI*radius; +} + +double Square::area(void) { + return width*width; +} + +double Square::perimeter(void) { + return 4*width; +} diff --git a/Examples/java/class/example.dsp b/Examples/java/class/example.dsp new file mode 100644 index 0000000..fbe87e7 --- /dev/null +++ b/Examples/java/class/example.dsp @@ -0,0 +1,162 @@ +# Microsoft Developer Studio Project File - Name="example" - Package Owner=<4>
+# Microsoft Developer Studio Generated Build File, Format Version 6.00
+# ** DO NOT EDIT **
+
+# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102
+
+CFG=example - Win32 Release
+!MESSAGE This is not a valid makefile. To build this project using NMAKE,
+!MESSAGE use the Export Makefile command and run
+!MESSAGE
+!MESSAGE NMAKE /f "example.mak".
+!MESSAGE
+!MESSAGE You can specify a configuration when running NMAKE
+!MESSAGE by defining the macro CFG on the command line. For example:
+!MESSAGE
+!MESSAGE NMAKE /f "example.mak" CFG="example - Win32 Release"
+!MESSAGE
+!MESSAGE Possible choices for configuration are:
+!MESSAGE
+!MESSAGE "example - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library")
+!MESSAGE "example - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library")
+!MESSAGE
+
+# Begin Project
+# PROP AllowPerConfigDependencies 0
+# PROP Scc_ProjName ""
+# PROP Scc_LocalPath ""
+CPP=cl.exe
+MTL=midl.exe
+RSC=rc.exe
+
+!IF "$(CFG)" == "example - Win32 Debug"
+
+# PROP BASE Use_MFC 0
+# PROP BASE Use_Debug_Libraries 1
+# PROP BASE Output_Dir "Debug"
+# PROP BASE Intermediate_Dir "Debug"
+# PROP BASE Target_Dir ""
+# PROP Use_MFC 0
+# PROP Use_Debug_Libraries 1
+# PROP Output_Dir "Debug"
+# PROP Intermediate_Dir "Debug"
+# PROP Ignore_Export_Lib 0
+# PROP Target_Dir ""
+# ADD BASE CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /GZ /c
+# ADD CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /I "$(JAVA_INCLUDE)" /I "$(JAVA_INCLUDE)\win32" /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /GZ /c
+# ADD BASE MTL /nologo /D "_DEBUG" /mktyplib203 /win32
+# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32
+# ADD BASE RSC /l 0x809 /d "_DEBUG"
+# ADD RSC /l 0x809 /d "_DEBUG"
+BSC32=bscmake.exe
+# ADD BASE BSC32 /nologo
+# ADD BSC32 /nologo
+LINK32=link.exe
+# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /debug /machine:I386 /pdbtype:sept
+# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /debug /machine:I386 /out:"example.dll" /pdbtype:sept
+# Begin Special Build Tool
+SOURCE="$(InputPath)"
+PostBuild_Desc=Java compile post-build step
+PostBuild_Cmds=echo on "%JAVA_BIN%\javac" *.java
+# End Special Build Tool
+
+!ELSEIF "$(CFG)" == "example - Win32 Release"
+
+# PROP BASE Use_MFC 0
+# PROP BASE Use_Debug_Libraries 0
+# PROP BASE Output_Dir "Release"
+# PROP BASE Intermediate_Dir "Release"
+# PROP BASE Target_Dir ""
+# PROP Use_MFC 0
+# PROP Use_Debug_Libraries 0
+# PROP Output_Dir "Release"
+# PROP Intermediate_Dir "Release"
+# PROP Ignore_Export_Lib 0
+# PROP Target_Dir ""
+# ADD BASE CPP /nologo /MT /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /c
+# ADD CPP /nologo /MT /W3 /GX /O2 /I "$(JAVA_INCLUDE)" /I "$(JAVA_INCLUDE)\win32" /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /c
+# ADD BASE MTL /nologo /D "NDEBUG" /mktyplib203 /win32
+# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32
+# ADD BASE RSC /l 0x809 /d "NDEBUG"
+# ADD RSC /l 0x809 /d "NDEBUG"
+BSC32=bscmake.exe
+# ADD BASE BSC32 /nologo
+# ADD BSC32 /nologo
+LINK32=link.exe
+# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /machine:I386
+# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /machine:I386 /out:"example.dll"
+# Begin Special Build Tool
+SOURCE="$(InputPath)"
+PostBuild_Desc=Java compile post-build step
+PostBuild_Cmds=echo on "%JAVA_BIN%\javac" *.java
+# End Special Build Tool
+
+!ENDIF
+
+# Begin Target
+
+# Name "example - Win32 Debug"
+# Name "example - Win32 Release"
+# Begin Group "Source Files"
+
+# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat"
+# Begin Source File
+
+SOURCE=.\example.cxx
+# End Source File
+# Begin Source File
+
+SOURCE=.\example_wrap.cxx
+# End Source File
+# End Group
+# Begin Group "Header Files"
+
+# PROP Default_Filter "h;hpp;hxx;hm;inl"
+# Begin Source File
+
+SOURCE=.\example.h
+# End Source File
+# End Group
+# Begin Group "Resource Files"
+
+# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe"
+# End Group
+# Begin Source File
+
+SOURCE=.\example.i
+
+!IF "$(CFG)" == "example - Win32 Debug"
+
+# Begin Custom Build
+InputPath=.\example.i
+InputName=example
+
+"$(InputName)_wrap.cxx" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"
+ echo In order to function correctly, please ensure the following environment variables are correctly set:
+ echo JAVA_INCLUDE: %JAVA_INCLUDE%
+ echo JAVA_BIN: %JAVA_BIN%
+ echo on
+ ..\..\..\swig.exe -c++ -java $(InputPath)
+
+# End Custom Build
+
+!ELSEIF "$(CFG)" == "example - Win32 Release"
+
+# Begin Custom Build
+InputPath=.\example.i
+InputName=example
+
+"$(InputName)_wrap.cxx" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"
+ echo In order to function correctly, please ensure the following environment variables are correctly set:
+ echo JAVA_INCLUDE: %JAVA_INCLUDE%
+ echo JAVA_BIN: %JAVA_BIN%
+ echo on
+ ..\..\..\swig.exe -c++ -java $(InputPath)
+
+# End Custom Build
+
+!ENDIF
+
+# End Source File
+# End Target
+# End Project
diff --git a/Examples/java/class/example.h b/Examples/java/class/example.h new file mode 100644 index 0000000..46d9013 --- /dev/null +++ b/Examples/java/class/example.h @@ -0,0 +1,39 @@ +/* File : example.h */ + +class Shape { +public: + Shape() { + nshapes++; + } + virtual ~Shape() { + nshapes--; + }; + double x, y; + void move(double dx, double dy); + virtual double area(void) = 0; + virtual double perimeter(void) = 0; + static int nshapes; +}; + +class Circle : public Shape { +private: + double radius; +public: + Circle(double r) : radius(r) { }; + virtual double area(void); + virtual double perimeter(void); +}; + +class Square : public Shape { +private: + double width; +public: + Square(double w) : width(w) { }; + virtual double area(void); + virtual double perimeter(void); +}; + + + + + diff --git a/Examples/java/class/example.i b/Examples/java/class/example.i new file mode 100644 index 0000000..75700b3 --- /dev/null +++ b/Examples/java/class/example.i @@ -0,0 +1,10 @@ +/* File : example.i */ +%module example + +%{ +#include "example.h" +%} + +/* Let's just grab the original header file here */ +%include "example.h" + diff --git a/Examples/java/class/index.html b/Examples/java/class/index.html new file mode 100644 index 0000000..cf9130c --- /dev/null +++ b/Examples/java/class/index.html @@ -0,0 +1,197 @@ +<html> +<head> +<title>SWIG:Examples:java:class</title> +</head> + +<body bgcolor="#ffffff"> + + +<tt>SWIG/Examples/java/class/</tt> +<hr> + +<H2>Wrapping a simple C++ class</H2> + +<p> +This example illustrates the high level form of C++ class wrapping performed +by SWIG. In this case, a C++ class has a proxy Java class, which +provides access to C++ class members. + +<h2>The C++ Code</h2> + +Suppose you have some C++ classes described by the following (and admittedly lame) +header file: + +<blockquote> +<pre> +/* File : example.h */ + +class Shape { +public: + Shape() { + nshapes++; + } + virtual ~Shape() { + nshapes--; + }; + double x, y; + void move(double dx, double dy); + virtual double area() = 0; + virtual double perimeter() = 0; + static int nshapes; +}; + +class Circle : public Shape { +private: + double radius; +public: + Circle(double r) : radius(r) { }; + virtual double area(); + virtual double perimeter(); +}; + +class Square : public Shape { +private: + double width; +public: + Square(double w) : width(w) { }; + virtual double area(); + virtual double perimeter(); +}; +</pre> +</blockquote> + +<h2>The SWIG interface</h2> + +A simple SWIG interface for this can be built by simply grabbing the header file +like this: + +<blockquote> +<pre> +/* File : example.i */ +%module example + +%{ +#include "example.h" +%} + +/* Let's just grab the original header file here */ +%include "example.h" +</pre> +</blockquote> + +Note: when creating a C++ extension, you must run SWIG with the <tt>-c++</tt> option like this: +<blockquote> +<pre> +% swig -c++ -java example.i +</pre> +</blockquote> + +<h2>A sample Java program</h2> + +Click <a href="runme.java">here</a> to see a Java program that calls the C++ functions from Java. + +<h2>Key points</h2> + +<ul> +<li>To create a new object, you call a constructor like this: + +<blockquote> +<pre> +Circle c = new Circle(10); +</pre> +</blockquote> + +<p> +<li>To access member data, a pair of accessor functions are used. +For example: + +<blockquote> +<pre> +c.setX(15); // Set member data +x = c.getX(); // Get member data +</pre> +</blockquote> + +<p> +<li>To invoke a member function, you simply do this + +<blockquote> +<pre> +System.out.println( "The area is " + c.area() ); +</pre> +</blockquote> + +<p> +<li>To invoke a destructor, simply do this + +<blockquote> +<pre> +c.delete(); // Deletes a shape +</pre> +</blockquote> + +<p> +<li>Static member variables are wrapped with java static get and set access functions. For example: + +<blockquote> +<pre> +n = Shape.getNshapes(); // Get a static data member +Shape.setNshapes(13); // Set a static data member +</pre> +</blockquote> + +</ul> + +<h2>General Comments</h2> + +<ul> +<li>This high-level interface using proxy classes is not the only way to handle C++ code. +A low level interface using c functions to access member variables and member functions is the alternative SWIG +approach. This entails passing around the c pointer or c++ 'this' pointer and as such it is not difficult to crash the JVM. +The abstraction of the underlying pointer by the java proxy classes far better fits the java programming paradigm. + +<p> +<li>SWIG *does* know how to properly perform upcasting of objects in an inheritance +hierarchy (including multiple inheritance). However Java classes can only derive from one base class so multiple inheritance +is not implemented. Java classes can implement more than one interface so there is scope for improvement in the future. + +<p> +<li>A wide variety of C++ features are not currently supported by SWIG. Here is the +short and incomplete list: + +<p> +<ul> +<li>Overloaded methods and functions. SWIG wrappers don't know how to resolve name +conflicts so you must give an alternative name to any overloaded method name using the +%name directive like this: + +<blockquote> +<pre> +void foo(int a); +%name(foo2) void foo(double a, double b); +</pre> +</blockquote> + +<p> +<li>Overloaded operators. Not supported at all. The only workaround for this is +to write a helper function. For example: + +<blockquote> +<pre> +%inline %{ + Vector *vector_add(Vector *a, Vector *b) { + ... whatever ... + } +%} +</pre> +</blockquote> + +<p> +<li>Namespaces. Not supported at all. Won't be supported until SWIG2.0 (if at all). + +</ul> +</ul> + +<hr> +</body> +</html> diff --git a/Examples/java/class/runme.java b/Examples/java/class/runme.java new file mode 100644 index 0000000..e1ea0d7 --- /dev/null +++ b/Examples/java/class/runme.java @@ -0,0 +1,70 @@ +// This example illustrates how C++ classes can be used from Java using SWIG. +// The Java class gets mapped onto the C++ class and behaves as if it is a Java class. + +public class runme { + static { + try { + System.loadLibrary("example"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + // ----- Object creation ----- + + System.out.println( "Creating some objects:" ); + Circle c = new Circle(10); + System.out.println( " Created circle " + c ); + Square s = new Square(10); + System.out.println( " Created square " + s ); + + // ----- Access a static member ----- + + System.out.println( "\nA total of " + Shape.getNshapes() + " shapes were created" ); + + // ----- Member data access ----- + + // Notice how we can do this using functions specific to + // the 'Circle' class. + c.setX(20); + c.setY(30); + + // Now use the same functions in the base class + Shape shape = s; + shape.setX(-10); + shape.setY(5); + + System.out.println( "\nHere is their current position:" ); + System.out.println( " Circle = (" + c.getX() + " " + c.getY() + ")" ); + System.out.println( " Square = (" + s.getX() + " " + s.getY() + ")" ); + + // ----- Call some methods ----- + + System.out.println( "\nHere are some properties of the shapes:" ); + Shape[] shapes = {c,s}; + for (int i=0; i<shapes.length; i++) + { + System.out.println( " " + shapes[i].toString() ); + System.out.println( " area = " + shapes[i].area() ); + System.out.println( " perimeter = " + shapes[i].perimeter() ); + } + + // Notice how the area() and perimeter() functions really + // invoke the appropriate virtual method on each object. + + // ----- Delete everything ----- + + System.out.println( "\nGuess I'll clean up now" ); + + // Note: this invokes the virtual destructor + // You could leave this to the garbage collector + c.delete(); + s.delete(); + + System.out.println( Shape.getNshapes() + " shapes remain" ); + System.out.println( "Goodbye" ); + } +} diff --git a/Examples/java/constants/Makefile b/Examples/java/constants/Makefile new file mode 100644 index 0000000..2b3d35c --- /dev/null +++ b/Examples/java/constants/Makefile @@ -0,0 +1,18 @@ +TOP = ../.. +SWIG = $(TOP)/../preinst-swig +CXXSRCS = +TARGET = example +INTERFACE = example.i +SWIGOPT = + +all:: java + +java:: + $(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \ + SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' java_cpp + javac *.java + +clean:: + $(MAKE) -f $(TOP)/Makefile java_clean + +check: all diff --git a/Examples/java/constants/example.i b/Examples/java/constants/example.i new file mode 100644 index 0000000..76665fc --- /dev/null +++ b/Examples/java/constants/example.i @@ -0,0 +1,30 @@ +/* File : example.i */ +%module example + +/* Force the generated Java code to use the C constant values rather than making a JNI call */ +%javaconst(1); + +/* A few preprocessor macros */ + +#define ICONST 42 +#define FCONST 2.1828 +#define CCONST 'x' +#define CCONST2 '\n' +#define SCONST "Hello World" +#define SCONST2 "\"Hello World\"" + +/* This should work just fine */ +#define EXPR ICONST + 3*(FCONST) + +/* This shouldn't do anything */ +#define EXTERN extern + +/* Neither should this (BAR isn't defined) */ +#define FOO (ICONST + BAR) + +/* The following directives also produce constants */ + +%constant int iconst = 37; +%constant double fconst = 3.14; + + diff --git a/Examples/java/constants/index.html b/Examples/java/constants/index.html new file mode 100644 index 0000000..9f1e95a --- /dev/null +++ b/Examples/java/constants/index.html @@ -0,0 +1,52 @@ +<html> +<head> +<title>SWIG:Examples:java:constants</title> +</head> + +<body bgcolor="#ffffff"> + +<tt>SWIG/Examples/java/constants/</tt> +<hr> + +<H2>Wrapping C Constants</H2> + +<p> +When SWIG encounters C preprocessor macros and C declarations that look like constants, +it creates Java constant with an identical value. Click <a href="example.i">here</a> +to see a SWIG interface with some constant declarations in it. + + +<h2>Accessing Constants from Java</h2> +Click <a href="../../../Doc/Manual/Java.html#constants">here</a> for the section on constants in the SWIG and Java documentation. +<p> + +Click <a href="runme.java">here</a> to see a Java program that prints out the values +of the constants contained in the above file.</p> +<h2>Key points</h2> +<ul> +<li>The values of preprocessor macros are converted into Java constants. +<li>Types are inferred by syntax (e.g., "3" is an integer and "3.5" is a float). +<li>Character constants such as 'x' are converted into Java strings. +<li>C string literals such as "Hello World" are converted into Java strings. +<li>Macros that are not fully defined are simply ignored. For example: +<blockquote> +<pre> +#define EXTERN extern +</pre> +</blockquote> +is ignored because SWIG has no idea what type of variable this would be. + +<p> +<li>Expressions are allowed provided that all of their components are defined. Otherwise, the constant is ignored. + +<li>Certain C declarations involving 'const' are also turned into Java constants. +<li>The constants that appear in a SWIG interface file do not have to appear in any sort +of matching C source file since the creation of a constant does not require linkage +to a stored value (i.e., a value held in a C global variable or memory location). +</ul> + +<hr> + + +</body> +</html> diff --git a/Examples/java/constants/runme.java b/Examples/java/constants/runme.java new file mode 100644 index 0000000..2c67d86 --- /dev/null +++ b/Examples/java/constants/runme.java @@ -0,0 +1,44 @@ +import java.lang.reflect.*; + +public class runme { + static { + try { + System.loadLibrary("example"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + System.out.println("ICONST = " + example.ICONST + " (should be 42)"); + System.out.println("FCONST = " + example.FCONST + " (should be 2.1828)"); + System.out.println("CCONST = " + example.CCONST + " (should be 'x')"); + System.out.println("CCONST2 = " + example.CCONST2 + " (this should be on a new line)"); + System.out.println("SCONST = " + example.SCONST + " (should be 'Hello World')"); + System.out.println("SCONST2 = " + example.SCONST2 + " (should be '\"Hello World\"')"); + System.out.println("EXPR = " + example.EXPR + " (should be 48.5484)"); + System.out.println("iconst = " + example.iconst + " (should be 37)"); + System.out.println("fconst = " + example.fconst + " (should be 3.14)"); + +// Use reflection to check if these variables are defined: + try + { + System.out.println("EXTERN = " + example.class.getField("EXTERN") + " (Arg! This shouldn't print anything)"); + } + catch (NoSuchFieldException e) + { + System.out.println("EXTERN isn't defined (good)"); + } + + try + { + System.out.println("FOO = " + example.class.getField("FOO") + " (Arg! This shouldn't print anything)"); + } + catch (NoSuchFieldException e) + { + System.out.println("FOO isn't defined (good)"); + } + } +} diff --git a/Examples/java/enum/Makefile b/Examples/java/enum/Makefile new file mode 100644 index 0000000..14c3017 --- /dev/null +++ b/Examples/java/enum/Makefile @@ -0,0 +1,18 @@ +TOP = ../.. +SWIG = $(TOP)/../preinst-swig +CXXSRCS = example.cxx +TARGET = example +INTERFACE = example.i +SWIGOPT = + +all:: java + +java:: + $(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \ + SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' java_cpp + javac *.java + +clean:: + $(MAKE) -f $(TOP)/Makefile java_clean + +check: all diff --git a/Examples/java/enum/example.cxx b/Examples/java/enum/example.cxx new file mode 100644 index 0000000..df7bb63 --- /dev/null +++ b/Examples/java/enum/example.cxx @@ -0,0 +1,37 @@ +/* File : example.cxx */ + +#include "example.h" +#include <stdio.h> + +void Foo::enum_test(speed s) { + if (s == IMPULSE) { + printf("IMPULSE speed\n"); + } else if (s == WARP) { + printf("WARP speed\n"); + } else if (s == LUDICROUS) { + printf("LUDICROUS speed\n"); + } else { + printf("Unknown speed\n"); + } +} + +void enum_test(color c, Foo::speed s) { + if (c == RED) { + printf("color = RED, "); + } else if (c == BLUE) { + printf("color = BLUE, "); + } else if (c == GREEN) { + printf("color = GREEN, "); + } else { + printf("color = Unknown color!, "); + } + if (s == Foo::IMPULSE) { + printf("speed = IMPULSE speed\n"); + } else if (s == Foo::WARP) { + printf("speed = WARP speed\n"); + } else if (s == Foo::LUDICROUS) { + printf("speed = LUDICROUS speed\n"); + } else { + printf("speed = Unknown speed!\n"); + } +} diff --git a/Examples/java/enum/example.h b/Examples/java/enum/example.h new file mode 100644 index 0000000..9119cd9 --- /dev/null +++ b/Examples/java/enum/example.h @@ -0,0 +1,13 @@ +/* File : example.h */ + +enum color { RED, BLUE, GREEN }; + +class Foo { + public: + Foo() { } + enum speed { IMPULSE=10, WARP=20, LUDICROUS=30 }; + void enum_test(speed s); +}; + +void enum_test(color c, Foo::speed s); + diff --git a/Examples/java/enum/example.i b/Examples/java/enum/example.i new file mode 100644 index 0000000..fb65689 --- /dev/null +++ b/Examples/java/enum/example.i @@ -0,0 +1,14 @@ +/* File : example.i */ +%module example + +%{ +#include "example.h" +%} + +/* Force the generated Java code to use the C enum values rather than making a JNI call */ +%javaconst(1); + +/* Let's just grab the original header file here */ + +%include "example.h" + diff --git a/Examples/java/enum/index.html b/Examples/java/enum/index.html new file mode 100644 index 0000000..20daf26 --- /dev/null +++ b/Examples/java/enum/index.html @@ -0,0 +1,29 @@ +<html> +<head> +<title>SWIG:Examples:java:enum</title> +</head> + +<body bgcolor="#ffffff"> + + +<tt>SWIG/Examples/java/enum/</tt> +<hr> + +<H2>Wrapping enumerations</H2> + +<p> +This example tests SWIG's ability to wrap enumerations. +SWIG wraps enums in numerous different ways. The default approach is to wrap +each enum with the typesafe enum pattern. Enums are handled as integers in the JNI layer. +See the documentation for the other approaches for wrapping enums. + + +<ul> +<li><a href="example.h">example.h</a>. Header file containing some enums. +<li><a href="example.i">example.i</a>. Interface file. +<li><a href="runme.java">runme.java</a>. Sample Java program. +</ul> + +<hr> +</body> +</html> diff --git a/Examples/java/enum/runme.java b/Examples/java/enum/runme.java new file mode 100644 index 0000000..56e49af --- /dev/null +++ b/Examples/java/enum/runme.java @@ -0,0 +1,38 @@ + +public class runme { + static { + try { + System.loadLibrary("example"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + // Print out the value of some enums + System.out.println("*** color ***"); + System.out.println(" " + color.RED + " = " + color.RED.swigValue()); + System.out.println(" " + color.BLUE + " = " + color.BLUE.swigValue()); + System.out.println(" " + color.GREEN + " = " + color.GREEN.swigValue()); + + System.out.println("\n*** Foo::speed ***"); + System.out.println(" Foo::" + Foo.speed.IMPULSE + " = " + Foo.speed.IMPULSE.swigValue()); + System.out.println(" Foo::" + Foo.speed.WARP + " = " + Foo.speed.WARP.swigValue()); + System.out.println(" Foo::" + Foo.speed.LUDICROUS + " = " + Foo.speed.LUDICROUS.swigValue()); + + System.out.println("\nTesting use of enums with functions\n"); + + example.enum_test(color.RED, Foo.speed.IMPULSE); + example.enum_test(color.BLUE, Foo.speed.WARP); + example.enum_test(color.GREEN, Foo.speed.LUDICROUS); + + System.out.println( "\nTesting use of enum with class method" ); + Foo f = new Foo(); + + f.enum_test(Foo.speed.IMPULSE); + f.enum_test(Foo.speed.WARP); + f.enum_test(Foo.speed.LUDICROUS); + } +} diff --git a/Examples/java/extend/Makefile b/Examples/java/extend/Makefile new file mode 100644 index 0000000..14c3017 --- /dev/null +++ b/Examples/java/extend/Makefile @@ -0,0 +1,18 @@ +TOP = ../.. +SWIG = $(TOP)/../preinst-swig +CXXSRCS = example.cxx +TARGET = example +INTERFACE = example.i +SWIGOPT = + +all:: java + +java:: + $(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \ + SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' java_cpp + javac *.java + +clean:: + $(MAKE) -f $(TOP)/Makefile java_clean + +check: all diff --git a/Examples/java/extend/example.cxx b/Examples/java/extend/example.cxx new file mode 100644 index 0000000..450d756 --- /dev/null +++ b/Examples/java/extend/example.cxx @@ -0,0 +1,4 @@ +/* File : example.cxx */ + +#include "example.h" + diff --git a/Examples/java/extend/example.h b/Examples/java/extend/example.h new file mode 100644 index 0000000..b27ab97 --- /dev/null +++ b/Examples/java/extend/example.h @@ -0,0 +1,56 @@ +/* File : example.h */ + +#include <cstdio> +#include <iostream> +#include <vector> +#include <string> +#include <cmath> + +class Employee { +private: + std::string name; +public: + Employee(const char* n): name(n) {} + virtual std::string getTitle() { return getPosition() + " " + getName(); } + virtual std::string getName() { return name; } + virtual std::string getPosition() const { return "Employee"; } + virtual ~Employee() { printf("~Employee() @ %p\n", this); } +}; + + +class Manager: public Employee { +public: + Manager(const char* n): Employee(n) {} + virtual std::string getPosition() const { return "Manager"; } +}; + + +class EmployeeList { + std::vector<Employee*> list; +public: + EmployeeList() { + list.push_back(new Employee("Bob")); + list.push_back(new Employee("Jane")); + list.push_back(new Manager("Ted")); + } + void addEmployee(Employee *p) { + list.push_back(p); + std::cout << "New employee added. Current employees are:" << std::endl; + std::vector<Employee*>::iterator i; + for (i=list.begin(); i!=list.end(); i++) { + std::cout << " " << (*i)->getTitle() << std::endl; + } + } + const Employee *get_item(int i) { + return list[i]; + } + ~EmployeeList() { + std::vector<Employee*>::iterator i; + std::cout << "~EmployeeList, deleting " << list.size() << " employees." << std::endl; + for (i=list.begin(); i!=list.end(); i++) { + delete *i; + } + std::cout << "~EmployeeList empty." << std::endl; + } +}; + diff --git a/Examples/java/extend/example.i b/Examples/java/extend/example.i new file mode 100644 index 0000000..c8ec32e --- /dev/null +++ b/Examples/java/extend/example.i @@ -0,0 +1,15 @@ +/* File : example.i */ +%module(directors="1") example +%{ +#include "example.h" +%} + +%include "std_vector.i" +%include "std_string.i" + +/* turn on director wrapping for Manager */ +%feature("director") Employee; +%feature("director") Manager; + +%include "example.h" + diff --git a/Examples/java/extend/index.html b/Examples/java/extend/index.html new file mode 100644 index 0000000..c7c2c12 --- /dev/null +++ b/Examples/java/extend/index.html @@ -0,0 +1,19 @@ +<html> +<head> +<title>SWIG:Examples:java:extend</title> +</head> + +<body bgcolor="#ffffff"> + + +<tt>SWIG/Examples/java/extend/</tt> +<hr> + +<H2>Extending a simple C++ class in Java</H2> + +<p> +This example illustrates the extending of a C++ class with cross language polymorphism. + +<hr> +</body> +</html> diff --git a/Examples/java/extend/runme.java b/Examples/java/extend/runme.java new file mode 100644 index 0000000..629bb14 --- /dev/null +++ b/Examples/java/extend/runme.java @@ -0,0 +1,88 @@ +// This file illustrates the cross language polymorphism using directors. + + +// CEO class, which overrides Employee::getPosition(). + +class CEO extends Manager { + public CEO(String name) { + super(name); + } + public String getPosition() { + return "CEO"; + } + // Public method to stop the SWIG proxy base class from thinking it owns the underlying C++ memory. + public void disownMemory() { + swigCMemOwn = false; + } +} + + +public class runme { + static { + try { + System.loadLibrary("example"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + + // Create an instance of CEO, a class derived from the Java proxy of the + // underlying C++ class. The calls to getName() and getPosition() are standard, + // the call to getTitle() uses the director wrappers to call CEO.getPosition(). + + CEO e = new CEO("Alice"); + System.out.println( e.getName() + " is a " + e.getPosition() ); + System.out.println( "Just call her \"" + e.getTitle() + "\"" ); + System.out.println( "----------------------" ); + + + // Create a new EmployeeList instance. This class does not have a C++ + // director wrapper, but can be used freely with other classes that do. + + EmployeeList list = new EmployeeList(); + + // EmployeeList owns its items, so we must surrender ownership of objects we add. + e.disownMemory(); + list.addEmployee(e); + System.out.println( "----------------------" ); + + // Now we access the first four items in list (three are C++ objects that + // EmployeeList's constructor adds, the last is our CEO). The virtual + // methods of all these instances are treated the same. For items 0, 1, and + // 2, all methods resolve in C++. For item 3, our CEO, getTitle calls + // getPosition which resolves in Java. The call to getPosition is + // slightly different, however, because of the overidden getPosition() call, since + // now the object reference has been "laundered" by passing through + // EmployeeList as an Employee*. Previously, Java resolved the call + // immediately in CEO, but now Java thinks the object is an instance of + // class Employee. So the call passes through the + // Employee proxy class and on to the C wrappers and C++ director, + // eventually ending up back at the Java CEO implementation of getPosition(). + // The call to getTitle() for item 3 runs the C++ Employee::getTitle() + // method, which in turn calls getPosition(). This virtual method call + // passes down through the C++ director class to the Java implementation + // in CEO. All this routing takes place transparently. + + System.out.println( "(position, title) for items 0-3:" ); + + System.out.println( " " + list.get_item(0).getPosition() + ", \"" + list.get_item(0).getTitle() + "\"" ); + System.out.println( " " + list.get_item(1).getPosition() + ", \"" + list.get_item(1).getTitle() + "\"" ); + System.out.println( " " + list.get_item(2).getPosition() + ", \"" + list.get_item(2).getTitle() + "\"" ); + System.out.println( " " + list.get_item(3).getPosition() + ", \"" + list.get_item(3).getTitle() + "\"" ); + System.out.println( "----------------------" ); + + // Time to delete the EmployeeList, which will delete all the Employee* + // items it contains. The last item is our CEO, which gets destroyed as well. + list.delete(); + System.out.println( "----------------------" ); + + // All done. + + System.out.println( "java exit" ); + + } +} diff --git a/Examples/java/funcptr/Makefile b/Examples/java/funcptr/Makefile new file mode 100644 index 0000000..968c92c --- /dev/null +++ b/Examples/java/funcptr/Makefile @@ -0,0 +1,18 @@ +TOP = ../.. +SWIG = $(TOP)/../preinst-swig +SRCS = example.c +TARGET = example +INTERFACE = example.i +SWIGOPT = + +all:: java + +java:: + $(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \ + SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' java + javac *.java + +clean:: + $(MAKE) -f $(TOP)/Makefile java_clean + +check: all diff --git a/Examples/java/funcptr/example.c b/Examples/java/funcptr/example.c new file mode 100644 index 0000000..5c4a3da --- /dev/null +++ b/Examples/java/funcptr/example.c @@ -0,0 +1,19 @@ +/* File : example.c */ + +int do_op(int a, int b, int (*op)(int,int)) { + return (*op)(a,b); +} + +int add(int a, int b) { + return a+b; +} + +int sub(int a, int b) { + return a-b; +} + +int mul(int a, int b) { + return a*b; +} + +int (*funcvar)(int,int) = add; diff --git a/Examples/java/funcptr/example.h b/Examples/java/funcptr/example.h new file mode 100644 index 0000000..9936e24 --- /dev/null +++ b/Examples/java/funcptr/example.h @@ -0,0 +1,9 @@ +/* file: example.h */ + +extern int do_op(int,int, int (*op)(int,int)); +extern int add(int,int); +extern int sub(int,int); +extern int mul(int,int); + +extern int (*funcvar)(int,int); + diff --git a/Examples/java/funcptr/example.i b/Examples/java/funcptr/example.i new file mode 100644 index 0000000..8b3bef6 --- /dev/null +++ b/Examples/java/funcptr/example.i @@ -0,0 +1,16 @@ +/* File : example.i */ +%module example +%{ +#include "example.h" +%} + +/* Wrap a function taking a pointer to a function */ +extern int do_op(int a, int b, int (*op)(int, int)); + +/* Now install a bunch of "ops" as constants */ +%constant int (*ADD)(int,int) = add; +%constant int (*SUB)(int,int) = sub; +%constant int (*MUL)(int,int) = mul; + +extern int (*funcvar)(int,int); + diff --git a/Examples/java/funcptr/index.html b/Examples/java/funcptr/index.html new file mode 100644 index 0000000..56d3baa --- /dev/null +++ b/Examples/java/funcptr/index.html @@ -0,0 +1,91 @@ +<html> +<head> +<title>SWIG:Examples:java:funcptr</title> +</head> + +<body bgcolor="#ffffff"> + + +<tt>SWIG/Examples/java/funcptr/</tt> +<hr> + +<H2>Pointers to Functions</H2> + +<p> +Okay, just what in the heck does SWIG do with a declaration like this? + +<blockquote> +<pre> +int do_op(int a, int b, int (*op)(int, int)); +</pre> +</blockquote> + +Well, it creates a wrapper as usual. Of course, that does raise some +questions about the third argument (the pointer to a function). + +<p> +In this case, SWIG will wrap the function pointer as it does for all other +pointers. However, in order to actually call this function from a Java program, +you will need to pass some kind of C function pointer object. In C, +this is easy, you just supply a function name as an argument like this: + +<blockquote> +<pre> +/* Some callback function */ +int add(int a, int b) { + return a+b; +} +... +int r = do_op(x,y,add); +</pre> +</blockquote> + +To make this work with SWIG, you will need to do a little extra work. Specifically, +you need to create some function pointer objects using the %constant directive like this: + +<blockquote> +<pre> +%constant(int (*)(int,int)) ADD = add; +</pre> +</blockquote> + +Now, in a Java program, you would do this: + +<blockquote> +<pre> +int r = do_op(x,y, example.ADD) +</pre> +</blockquote> +where <tt>example</tt> is the module name. + +<h2>An Example</h2> + +Here are some files that illustrate this with a simple example: + +<ul> +<li><a href="example.c">example.c</a> +<li><a href="example.h">example.h</a> +<li><a href="example.i">example.i</a> (SWIG interface) +<li><a href="runme.java">runme.java</a> (Sample program) +</ul> + +<h2>Notes</h2> + +<ul> +<li>The value of a function pointer must correspond to a function written in C or C++. +It is not possible to pass an arbitrary Java function in as a substitute for a C +function pointer. + +<p> +<li>A Java function can be used as a C/C++ callback if you write some +clever typemaps and are very careful about how you create your extension. +This is an advanced topic not covered here. +</ul> + +<hr> +</body> +</html> + + + + diff --git a/Examples/java/funcptr/runme.java b/Examples/java/funcptr/runme.java new file mode 100644 index 0000000..cd34c1b --- /dev/null +++ b/Examples/java/funcptr/runme.java @@ -0,0 +1,33 @@ + +public class runme { + + static { + try { + System.loadLibrary("example"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) { + + + int a = 37; + int b = 42; + + // Now call our C function with a bunch of callbacks + + System.out.println( "Trying some C callback functions" ); + System.out.println( " a = " + a ); + System.out.println( " b = " + b ); + System.out.println( " ADD(a,b) = " + example.do_op(a,b,example.ADD) ); + System.out.println( " SUB(a,b) = " + example.do_op(a,b,example.SUB) ); + System.out.println( " MUL(a,b) = " + example.do_op(a,b,example.MUL) ); + + System.out.println( "Here is what the C callback function classes are called in Java" ); + System.out.println( " ADD = " + example.ADD.getClass().getName() ); + System.out.println( " SUB = " + example.SUB.getClass().getName() ); + System.out.println( " MUL = " + example.MUL.getClass().getName() ); + } +} diff --git a/Examples/java/index.html b/Examples/java/index.html new file mode 100644 index 0000000..007e14d --- /dev/null +++ b/Examples/java/index.html @@ -0,0 +1,65 @@ +<html> +<head> +<title>SWIG:Examples:java</title> +</head> + +<body bgcolor="#ffffff"> +<H1>SWIG Java Examples</H1> + +<p> +The following examples illustrate the use of SWIG with Java. + +<ul> +<li><a href="simple/index.html">simple</a>. A minimal example showing how SWIG can +be used to wrap a C function, a global variable, and a constant. +<li><a href="native/index.html">native</a>. Comparing the manual and the SWIG approach to calling native code. +<li><a href="typemap/index.html">typemap</a>. Modifying the Java module's default behaviour by using typemaps. +<li><a href="constants/index.html">constants</a>. This shows how preprocessor macros and +certain C declarations are turned into constants. +<li><a href="variables/index.html">variables</a>. An example showing how to access C global variables. +<li><a href="enum/index.html">enum</a>. Wrapping enumerations. +<li><a href="class/index.html">class</a>. How to wrap a simple C++ class. +<li><a href="reference/index.html">reference</a>. C++ references. +<li><a href="pointer/index.html">pointer</a>. Simple pointer handling. +<li><a href="template/index.html">template</a>. C++ templates. +<li><a href="funcptr/index.html">funcptr</a>. Pointers to functions. +<li><a href="callback/index.html">callback</a>. C++ callbacks using directors. +<li><a href="extend/index.html">extend</a>. Polymorphism using directors. +</ul> + +<h2>Running the examples</h2> +Please see the <a href="../../Doc/Manual/Windows.html">Windows</a> page in the main manual for information on using the examples on Windows. <p> + +On Unix most of the examples work by making the Makefile before executing the program runme.java. The Makefile will output the swig generated JNI c code as well as the Java wrapper classes. Additionally the JNI c/c++ code is compiled into the shared object (dynamic link library) which is needed for dynamic linking to the native code. The Makefiles also compile the Java files using javac. +<p> +Ensure that the dynamic link library file is in the appropriate path before executing the Java program. For example in Unix, libexample.so must be in the LD_LIBRARY_PATH. +<p> +A Unix example: +<blockquote> +<pre> +$ make +$ export LD_LIBRARY_PATH=. #ksh +$ java runme +</pre> +</blockquote> +<p> + +</ul> + +<h2>Compatibility</h2> + +The examples have been extensively tested on the following platforms: + +<ul> +<li>Solaris +<li>Linux +<li>Cygwin +<li>Windows +</ul> + +Your mileage may vary. If you experience a problem, please let us know by +contacting us on the <a href="http://www.swig.org/mail.html">mailing lists</a>. +</body> +</html> + + diff --git a/Examples/java/multimap/Makefile b/Examples/java/multimap/Makefile new file mode 100644 index 0000000..968c92c --- /dev/null +++ b/Examples/java/multimap/Makefile @@ -0,0 +1,18 @@ +TOP = ../.. +SWIG = $(TOP)/../preinst-swig +SRCS = example.c +TARGET = example +INTERFACE = example.i +SWIGOPT = + +all:: java + +java:: + $(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \ + SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' java + javac *.java + +clean:: + $(MAKE) -f $(TOP)/Makefile java_clean + +check: all diff --git a/Examples/java/multimap/example.c b/Examples/java/multimap/example.c new file mode 100644 index 0000000..b8360fa --- /dev/null +++ b/Examples/java/multimap/example.c @@ -0,0 +1,53 @@ +/* File : example.c */ +#include <stdio.h> +#include <stdlib.h> +#include <ctype.h> + +/* Compute the greatest common divisor of positive integers */ +int gcd(int x, int y) { + int g; + g = y; + while (x > 0) { + g = x; + x = y % x; + y = g; + } + return g; +} + +int gcdmain(int argc, char *argv[]) { + int x,y; + if (argc != 3) { + printf("usage: gcd x y\n"); + return -1; + } + x = atoi(argv[1]); + y = atoi(argv[2]); + printf("gcd(%d,%d) = %d\n", x,y,gcd(x,y)); + return 0; +} + +int count(char *bytes, int len, char c) { + int i; + int count = 0; + for (i = 0; i < len; i++) { + if (bytes[i] == c) count++; + } + return count; +} + +void capitalize(char *str, int len) { + int i; + for (i = 0; i < len; i++) { + str[i] = (char)toupper(str[i]); + } +} + +void circle(double x, double y) { + double a = x*x + y*y; + if (a > 1.0) { + printf("Bad points %g, %g\n", x,y); + } else { + printf("Good points %g, %g\n", x,y); + } +} diff --git a/Examples/java/multimap/example.dsp b/Examples/java/multimap/example.dsp new file mode 100644 index 0000000..8e1f841 --- /dev/null +++ b/Examples/java/multimap/example.dsp @@ -0,0 +1,158 @@ +# Microsoft Developer Studio Project File - Name="example" - Package Owner=<4>
+# Microsoft Developer Studio Generated Build File, Format Version 6.00
+# ** DO NOT EDIT **
+
+# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102
+
+CFG=example - Win32 Release
+!MESSAGE This is not a valid makefile. To build this project using NMAKE,
+!MESSAGE use the Export Makefile command and run
+!MESSAGE
+!MESSAGE NMAKE /f "example.mak".
+!MESSAGE
+!MESSAGE You can specify a configuration when running NMAKE
+!MESSAGE by defining the macro CFG on the command line. For example:
+!MESSAGE
+!MESSAGE NMAKE /f "example.mak" CFG="example - Win32 Release"
+!MESSAGE
+!MESSAGE Possible choices for configuration are:
+!MESSAGE
+!MESSAGE "example - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library")
+!MESSAGE "example - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library")
+!MESSAGE
+
+# Begin Project
+# PROP AllowPerConfigDependencies 0
+# PROP Scc_ProjName ""
+# PROP Scc_LocalPath ""
+CPP=cl.exe
+MTL=midl.exe
+RSC=rc.exe
+
+!IF "$(CFG)" == "example - Win32 Debug"
+
+# PROP BASE Use_MFC 0
+# PROP BASE Use_Debug_Libraries 1
+# PROP BASE Output_Dir "Debug"
+# PROP BASE Intermediate_Dir "Debug"
+# PROP BASE Target_Dir ""
+# PROP Use_MFC 0
+# PROP Use_Debug_Libraries 1
+# PROP Output_Dir "Debug"
+# PROP Intermediate_Dir "Debug"
+# PROP Ignore_Export_Lib 0
+# PROP Target_Dir ""
+# ADD BASE CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /GZ /c
+# ADD CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /I "$(JAVA_INCLUDE)" /I "$(JAVA_INCLUDE)\win32" /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /GZ /c
+# ADD BASE MTL /nologo /D "_DEBUG" /mktyplib203 /win32
+# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32
+# ADD BASE RSC /l 0x809 /d "_DEBUG"
+# ADD RSC /l 0x809 /d "_DEBUG"
+BSC32=bscmake.exe
+# ADD BASE BSC32 /nologo
+# ADD BSC32 /nologo
+LINK32=link.exe
+# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /debug /machine:I386 /pdbtype:sept
+# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /debug /machine:I386 /out:"example.dll" /pdbtype:sept
+# Begin Special Build Tool
+SOURCE="$(InputPath)"
+PostBuild_Desc=Java compile post-build step
+PostBuild_Cmds=echo on "%JAVA_BIN%\javac" *.java
+# End Special Build Tool
+
+!ELSEIF "$(CFG)" == "example - Win32 Release"
+
+# PROP BASE Use_MFC 0
+# PROP BASE Use_Debug_Libraries 0
+# PROP BASE Output_Dir "Release"
+# PROP BASE Intermediate_Dir "Release"
+# PROP BASE Target_Dir ""
+# PROP Use_MFC 0
+# PROP Use_Debug_Libraries 0
+# PROP Output_Dir "Release"
+# PROP Intermediate_Dir "Release"
+# PROP Ignore_Export_Lib 0
+# PROP Target_Dir ""
+# ADD BASE CPP /nologo /MT /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /c
+# ADD CPP /nologo /MT /W3 /GX /O2 /I "$(JAVA_INCLUDE)" /I "$(JAVA_INCLUDE)\win32" /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /c
+# ADD BASE MTL /nologo /D "NDEBUG" /mktyplib203 /win32
+# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32
+# ADD BASE RSC /l 0x809 /d "NDEBUG"
+# ADD RSC /l 0x809 /d "NDEBUG"
+BSC32=bscmake.exe
+# ADD BASE BSC32 /nologo
+# ADD BSC32 /nologo
+LINK32=link.exe
+# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /machine:I386
+# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /machine:I386 /out:"example.dll"
+# Begin Special Build Tool
+SOURCE="$(InputPath)"
+PostBuild_Desc=Java compile post-build step
+PostBuild_Cmds=echo on "%JAVA_BIN%\javac" *.java
+# End Special Build Tool
+
+!ENDIF
+
+# Begin Target
+
+# Name "example - Win32 Debug"
+# Name "example - Win32 Release"
+# Begin Group "Source Files"
+
+# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat"
+# Begin Source File
+
+SOURCE=.\example.c
+# End Source File
+# Begin Source File
+
+SOURCE=.\example_wrap.c
+# End Source File
+# End Group
+# Begin Group "Header Files"
+
+# PROP Default_Filter "h;hpp;hxx;hm;inl"
+# End Group
+# Begin Group "Resource Files"
+
+# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe"
+# End Group
+# Begin Source File
+
+SOURCE=.\example.i
+
+!IF "$(CFG)" == "example - Win32 Debug"
+
+# Begin Custom Build
+InputPath=.\example.i
+InputName=example
+
+"$(InputName)_wrap.c" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"
+ echo In order to function correctly, please ensure the following environment variables are correctly set:
+ echo JAVA_INCLUDE: %JAVA_INCLUDE%
+ echo JAVA_BIN: %JAVA_BIN%
+ echo on
+ ..\..\..\swig.exe -java $(InputPath)
+
+# End Custom Build
+
+!ELSEIF "$(CFG)" == "example - Win32 Release"
+
+# Begin Custom Build
+InputPath=.\example.i
+InputName=example
+
+"$(InputName)_wrap.c" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"
+ echo In order to function correctly, please ensure the following environment variables are correctly set:
+ echo JAVA_INCLUDE: %JAVA_INCLUDE%
+ echo JAVA_BIN: %JAVA_BIN%
+ echo on
+ ..\..\..\swig.exe -java $(InputPath)
+
+# End Custom Build
+
+!ENDIF
+
+# End Source File
+# End Target
+# End Project
diff --git a/Examples/java/multimap/example.i b/Examples/java/multimap/example.i new file mode 100644 index 0000000..8d67282 --- /dev/null +++ b/Examples/java/multimap/example.i @@ -0,0 +1,109 @@ +/* File : example.i */ +%module example + +%{ +extern int gcd(int x, int y); +extern int gcdmain(int argc, char *argv[]); +extern int count(char *bytes, int len, char c); +extern void capitalize (char *str, int len); +extern void circle (double cx, double cy); +extern int squareCubed (int n, int *OUTPUT); +%} + +extern int gcd(int x, int y); + +%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" + +%typemap(in) (int argc, char *argv[]) (jstring *jsarray) { +int i; + + $1 = (*jenv)->GetArrayLength(jenv, $input); + if ($1 == 0) { + SWIG_JavaThrowException(jenv, SWIG_JavaIndexOutOfBoundsException, "Array must contain at least 1 element"); + return $null; + } + $2 = (char **) malloc(($1+1)*sizeof(char *)); + jsarray = (jstring *) malloc($1*sizeof(jstring)); + for (i = 0; i < $1; i++) { + jsarray[i] = (jstring) (*jenv)->GetObjectArrayElement(jenv, $input, i); + $2[i] = (char *) (*jenv)->GetStringUTFChars(jenv, jsarray[i], 0); + } + $2[i] = 0; +} + +%typemap(argout) (int argc, char *argv[]) "" /* override char *[] default */ + +%typemap(freearg) (int argc, char *argv[]) { +int i; + for (i = 0; i < $1; i++) { + (*jenv)->ReleaseStringUTFChars(jenv, jsarray$argnum[i], $2[i]); + } + free($2); +} + +extern int gcdmain(int argc, char *argv[]); + +%typemap(jni) (char *bytes, int len) "jstring" +%typemap(jtype) (char *bytes, int len) "String" +%typemap(jstype) (char *bytes, int len) "String" + +%typemap(javain) (char *bytes, int len) "$javainput" + +%typemap(in) (char *bytes, int len) { + $1 = ($1_type)(*jenv)->GetStringUTFChars(jenv, $input, 0); + $2 = (*jenv)->GetStringUTFLength(jenv, $input); +} + +%typemap(freearg) (char *bytes, int len) %{ + (*jenv)->ReleaseStringUTFChars(jenv, $input, $1); +%} + +extern int count(char *bytes, int len, char c); + +/* This example shows how to wrap a function that mutates a c string. A one + * element Java string array is used so that the string can be returned modified.*/ + +%typemap(jni) (char *str, int len) "jobjectArray" +%typemap(jtype) (char *str, int len) "String[]" +%typemap(jstype) (char *str, int len) "String[]" + +%typemap(javain) (char *str, int len) "$javainput" + +%typemap(in) (char *str, int len) (jstring js) { + int index = 0; + js = (jstring) (*jenv)->GetObjectArrayElement(jenv, $input, index); + $1 = (char *) (*jenv)->GetStringUTFChars(jenv, js, 0); + $2 = (*jenv)->GetStringUTFLength(jenv, js); +} + +/* Return the mutated string as a modified element in the array. */ +%typemap(argout) (char *str, int len) { + jstring newstring = (*jenv)->NewStringUTF(jenv, $1); + (*jenv)->SetObjectArrayElement(jenv, $input, 0, newstring); +} + +/* Release memory */ +%typemap(freearg) (char *str, int len) { + (*jenv)->ReleaseStringUTFChars(jenv, js$argnum, $1); +} + +extern void capitalize(char *str, int len); + +/* A multi-valued constraint. Force two arguments to lie + inside the unit circle */ + +%typemap(check) (double cx, double cy) { + double a = $1*$1 + $2*$2; + if (a > 1.0) { + SWIG_JavaThrowException(jenv, SWIG_JavaIllegalArgumentException, "$1_name and $2_name must be in unit circle"); + return; + } +} + +extern void circle(double cx, double cy); + + diff --git a/Examples/java/multimap/runme.java b/Examples/java/multimap/runme.java new file mode 100644 index 0000000..738330e --- /dev/null +++ b/Examples/java/multimap/runme.java @@ -0,0 +1,40 @@ + +public class runme { + + static { + try { + System.loadLibrary("example"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) { + + // Call our gcd() function + int x = 42; + int y = 105; + int g = example.gcd(x,y); + System.out.println("The gcd of " + x + " and " + y + " is " + g); + + // Call the gcdmain() function + String[] args = {"gcdmain","42","105"}; + example.gcdmain(args); + + // Call the count function + System.out.println(example.count("Hello World", 'l')); + + // Call the capitalize function + String[] capitalizeMe = {"hello world"}; + example.capitalize(capitalizeMe); + System.out.println(capitalizeMe[0]); + } +} + + + + + + + diff --git a/Examples/java/native/Makefile b/Examples/java/native/Makefile new file mode 100644 index 0000000..92afbd4 --- /dev/null +++ b/Examples/java/native/Makefile @@ -0,0 +1,18 @@ +TOP = ../.. +SWIG = $(TOP)/../preinst-swig +SRCS = +TARGET = example +INTERFACE = example.i +SWIGOPT = + +all:: java + +java:: + $(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \ + SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' java + javac *.java + +clean:: + $(MAKE) -f $(TOP)/Makefile java_clean + +check: all diff --git a/Examples/java/native/example.i b/Examples/java/native/example.i new file mode 100644 index 0000000..851b6fd --- /dev/null +++ b/Examples/java/native/example.i @@ -0,0 +1,56 @@ +/* File : example.i */ +%module example + +%{ +#include <string.h> + +typedef struct point { + int x; + int y; +} Point; + + +Point *point_create(int x, int y) { + Point *p = (Point *) malloc(sizeof(Point)); + p->x = x; + p->y = y; + + return p; +} + +static char *point_toString(char *format, Point *p) { + static char buf[80]; + + sprintf(buf, format, p->x, p->y); + + return buf; +} + +/* this function will be wrapped by SWIG */ +char *point_toString1(Point *p) { + return point_toString("(%d,%d)", p); +} + +/* this one we wrapped manually*/ +JNIEXPORT jstring JNICALL Java_exampleJNI_point_1toString2(JNIEnv *jenv, jclass jcls, jlong jpoint) { + Point * p; + jstring result; + + (void)jcls; + + p = *(Point **)&jpoint; + + result = (*jenv)->NewStringUTF(jenv, point_toString("[%d,%d]", p)); + + return result; +} +%} + + +Point *point_create(int x, int y); +char *point_toString1(Point *p); + +/* give access to free() for memory cleanup of the malloc'd Point */ +extern void free(void *memblock); + +%native(point_toString2) char *point_toString2(Point *p); diff --git a/Examples/java/native/index.html b/Examples/java/native/index.html new file mode 100644 index 0000000..1ca51c1 --- /dev/null +++ b/Examples/java/native/index.html @@ -0,0 +1,33 @@ +<html> +<head> +<title>SWIG:Examples:java:native</title> +</head> + +<body bgcolor="#ffffff"> + + +<tt>SWIG/Examples/java/native/</tt> +<hr> + +<H2>SWIG wrapped and manually wrapped functions in Java</H2> + +Click <a href="../../../Doc/Manual/Java.html#using_own_jni_functions">here</a> for the relevant section in the SWIG and Java documentation. +<p> +This example compares wrapping a c global function using the manual way and the SWIG way. +</p> + +<ul> +<li><a href="example.i">example.i</a>. Interface file comparing code wrapped by SWIG and wrapped manually. +<li><a href="runme.java">runme.java</a>. Sample Java program showing calls to both manually wrapped and SWIG wrapped c functions. +</ul> + +<h2>Notes</h2> + +<ul> +<li>SWIG writes all the awkward JNI code for you. You just have to tell SWIG which functions to wrap. +<li>If memory is allocated in c it needs to be free'd. A function, such as free(), can be provided with access from Java to free the memory. +</ul> + +<hr> +</body> +</html> diff --git a/Examples/java/native/runme.java b/Examples/java/native/runme.java new file mode 100644 index 0000000..e9a18b2 --- /dev/null +++ b/Examples/java/native/runme.java @@ -0,0 +1,19 @@ + +public class runme { + + static { + try { + System.loadLibrary("example"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) { + SWIGTYPE_p_Point p = example.point_create(1, 2); + System.out.println("auto wrapped : " + example.point_toString1(p)); + System.out.println("manual wrapped: " + example.point_toString2(p)); + example.free(new SWIGTYPE_p_void(SWIGTYPE_p_Point.getCPtr(p), false)); //clean up c allocated memory + } +} diff --git a/Examples/java/pointer/Makefile b/Examples/java/pointer/Makefile new file mode 100644 index 0000000..968c92c --- /dev/null +++ b/Examples/java/pointer/Makefile @@ -0,0 +1,18 @@ +TOP = ../.. +SWIG = $(TOP)/../preinst-swig +SRCS = example.c +TARGET = example +INTERFACE = example.i +SWIGOPT = + +all:: java + +java:: + $(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \ + SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' java + javac *.java + +clean:: + $(MAKE) -f $(TOP)/Makefile java_clean + +check: all diff --git a/Examples/java/pointer/example.c b/Examples/java/pointer/example.c new file mode 100644 index 0000000..b877d9a --- /dev/null +++ b/Examples/java/pointer/example.c @@ -0,0 +1,16 @@ +/* File : example.c */ + +void add(int *x, int *y, int *result) { + *result = *x + *y; +} + +void sub(int *x, int *y, int *result) { + *result = *x - *y; +} + +int divide(int n, int d, int *r) { + int q; + q = n/d; + *r = n - q*d; + return q; +} diff --git a/Examples/java/pointer/example.i b/Examples/java/pointer/example.i new file mode 100644 index 0000000..a8ac794 --- /dev/null +++ b/Examples/java/pointer/example.i @@ -0,0 +1,30 @@ +/* File : example.i */ +%module example + +%{ +extern void add(int *, int *, int *); +extern void sub(int *, int *, int *); +extern int divide(int, int, int *); +%} + +/* This example illustrates a couple of different techniques + for manipulating C pointers */ + +/* First we'll use the pointer library */ +extern void add(int *x, int *y, int *result); +%include cpointer.i +%pointer_functions(int, intp); + +/* Next we'll use some typemaps */ + +%include typemaps.i +extern void sub(int *INPUT, int *INPUT, int *OUTPUT); + +/* Next we'll use typemaps and the %apply directive */ + +%apply int *OUTPUT { int *r }; +extern int divide(int n, int d, int *r); + + + + diff --git a/Examples/java/pointer/index.html b/Examples/java/pointer/index.html new file mode 100644 index 0000000..e20fe33 --- /dev/null +++ b/Examples/java/pointer/index.html @@ -0,0 +1,165 @@ +<html> +<head> +<title>SWIG:Examples:java:pointer</title> +</head> + +<body bgcolor="#ffffff"> + +<tt>SWIG/Examples/java/pointer/</tt> +<hr> + +<H2>Simple Pointer Handling</H2> + +<p> +This example illustrates a couple of techniques for handling +simple pointers in SWIG. The prototypical example is a C function +that operates on pointers such as this: + +<blockquote> +<pre> +void add(int *x, int *y, int *r) { + *r = *x + *y; +} +</pre> +</blockquote> + +By default, SWIG wraps this function exactly as specified and creates +an interface that expects pointer objects for arguments. +SWIG wraps a C pointer with a type wrapper class, for example, SWIGTYPE_p_int for an int*. +The only problem is how does one go about creating these objects from a Java program? +<p> + + +<h2>Possible Solutions</h2> + +<ul> +<li>Write some helper functions to explicitly create objects. For +example: + +<blockquote> +<pre> +int *new_int(int ivalue) { + int *i = (int *) malloc(sizeof(ivalue)); + *i = ivalue; + return i; +} +int get_int(int *i) { + return *i; +} + +void delete_int(int *i) { + free(i); +} +</pre> +</blockquote> + +<p> +<li>The SWIG pointer library provides an easier way. <br> +For example, in the interface file +you would do this: + +<blockquote> +<pre> +%include cpointer.i +%pointer_functions(int, intp); +</pre> +</blockquote> + +and from Java you would use pointers like this: + +<blockquote> +<pre> +SWIGTYPE_p_int a = example.new_intp(); +SWIGTYPE_p_int b = example.new_intp(); +SWIGTYPE_p_int c = example.new_intp(); +example.intp_assign(a,37); +example.intp_assign(b,42); + +// Note that getCPtr() has package access by default +System.out.println(" a =" + Long.toHexString(SWIGTYPE_p_int.getCPtr(a))); +System.out.println(" b =" + Long.toHexString(SWIGTYPE_p_int.getCPtr(b))); +System.out.println(" c =" + Long.toHexString(SWIGTYPE_p_int.getCPtr(c))); + +// Call the add() function with some pointers +example.add(a,b,c); + +// Now get the result +int res = example.intp_value(c); +System.out.println(" 37 + 42 =" + res); + +// Clean up the pointers +example.delete_intp(a); +example.delete_intp(b); +example.delete_intp(c); +</pre> +</blockquote> + +<p> +<li>Use the SWIG typemap library. This library allows you to completely +change the way arguments are processed by SWIG. For example: + +<blockquote> +<pre> +%include "typemaps.i" +void add(int *INPUT, int *INPUT, int *OUTPUT); +</pre> +</blockquote> + +And in a Java program: + +<blockquote> +<pre> +int[] r = {0}; +example.sub(37,42,r); +System.out.println("Result =" + r[0]); +</pre> +</blockquote> +Needless to say, this is substantially easier although a bit unusual. + +<p> +<li>A final alternative is to use the typemaps library in combination +with the %apply directive. This allows you to change the names of parameters +that behave as input or output parameters. For example: + +<blockquote> +<pre> +%include "typemaps.i" +%apply int *INPUT {int *x, int *y}; +%apply int *OUTPUT {int *r}; + +void add(int *x, int *y, int *r); +void sub(int *x, int *y, int *r); +void mul(int *x, int *y, int *r); +... etc ... +</pre> +</blockquote> + +</ul> + +<h2>Example</h2> + +The following example illustrates the use of these features for pointer +extraction. + +<ul> +<li> <a href="example.c">example.c</a> (C Source) +<li> <a href="example.i">example.i</a> (Swig interface) +<li> <a href="runme.java">runme.java</a> (Java program) +</ul> + +<h2>Notes</h2> + +<ul> +<li>Since pointers are used for so many different things (arrays, output values, +etc...) the complexity of pointer handling can be as complicated as you want to +make it. + +<p> +<li>More documentation on the typemaps.i and cpointer.i library files can be +found in the SWIG user manual. The files also contain documentation. + +</ul> + +<hr> +</body> +</html> diff --git a/Examples/java/pointer/runme.java b/Examples/java/pointer/runme.java new file mode 100644 index 0000000..f32f980 --- /dev/null +++ b/Examples/java/pointer/runme.java @@ -0,0 +1,55 @@ + +public class runme { + + static { + try { + System.loadLibrary("example"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) { + + // First create some objects using the pointer library. + System.out.println("Testing the pointer library"); + SWIGTYPE_p_int a = example.new_intp(); + SWIGTYPE_p_int b = example.new_intp(); + SWIGTYPE_p_int c = example.new_intp(); + example.intp_assign(a,37); + example.intp_assign(b,42); + + // Note that getCPtr() has package access by default + System.out.println(" a =" + Long.toHexString(SWIGTYPE_p_int.getCPtr(a))); + System.out.println(" b =" + Long.toHexString(SWIGTYPE_p_int.getCPtr(b))); + System.out.println(" c =" + Long.toHexString(SWIGTYPE_p_int.getCPtr(c))); + + // Call the add() function with some pointers + example.add(a,b,c); + + // Now get the result + int res = example.intp_value(c); + System.out.println(" 37 + 42 =" + res); + + // Clean up the pointers + example.delete_intp(a); + example.delete_intp(b); + example.delete_intp(c); + + // Now try the typemap library + // Now it is no longer necessary to manufacture pointers. + // Instead we use a single element array which in Java is modifiable. + + System.out.println("Trying the typemap library"); + int[] r = {0}; + example.sub(37,42,r); + System.out.println(" 37 - 42 = " + r[0]); + + // Now try the version with return value + + System.out.println("Testing return value"); + int q = example.divide(42,37,r); + System.out.println(" 42/37 = " + q + " remainder " + r[0]); + } +} diff --git a/Examples/java/reference/Makefile b/Examples/java/reference/Makefile new file mode 100644 index 0000000..14c3017 --- /dev/null +++ b/Examples/java/reference/Makefile @@ -0,0 +1,18 @@ +TOP = ../.. +SWIG = $(TOP)/../preinst-swig +CXXSRCS = example.cxx +TARGET = example +INTERFACE = example.i +SWIGOPT = + +all:: java + +java:: + $(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \ + SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' java_cpp + javac *.java + +clean:: + $(MAKE) -f $(TOP)/Makefile java_clean + +check: all diff --git a/Examples/java/reference/example.cxx b/Examples/java/reference/example.cxx new file mode 100644 index 0000000..8a513bf --- /dev/null +++ b/Examples/java/reference/example.cxx @@ -0,0 +1,46 @@ +/* File : example.cxx */ + +/* Deal with Microsoft's attempt at deprecating C standard runtime functions */ +#if !defined(SWIG_NO_CRT_SECURE_NO_DEPRECATE) && defined(_MSC_VER) +# define _CRT_SECURE_NO_DEPRECATE +#endif + +#include "example.h" +#include <stdio.h> +#include <stdlib.h> + +Vector operator+(const Vector &a, const Vector &b) { + Vector r; + r.x = a.x + b.x; + r.y = a.y + b.y; + r.z = a.z + b.z; + return r; +} + +char *Vector::print() { + static char temp[512]; + sprintf(temp,"Vector %p (%g,%g,%g)", this, x,y,z); + return temp; +} + +VectorArray::VectorArray(int size) { + items = new Vector[size]; + maxsize = size; +} + +VectorArray::~VectorArray() { + delete [] items; +} + +Vector &VectorArray::operator[](int index) { + if ((index < 0) || (index >= maxsize)) { + printf("Panic! Array index out of bounds.\n"); + exit(1); + } + return items[index]; +} + +int VectorArray::size() { + return maxsize; +} + diff --git a/Examples/java/reference/example.h b/Examples/java/reference/example.h new file mode 100644 index 0000000..4915adb --- /dev/null +++ b/Examples/java/reference/example.h @@ -0,0 +1,26 @@ +/* File : example.h */ + +class Vector { +private: + double x,y,z; +public: + Vector() : x(0), y(0), z(0) { }; + Vector(double x, double y, double z) : x(x), y(y), z(z) { }; + friend Vector operator+(const Vector &a, const Vector &b); + char *print(); +}; + +class VectorArray { +private: + Vector *items; + int maxsize; +public: + VectorArray(int maxsize); + ~VectorArray(); + Vector &operator[](int); + int size(); +}; + + + + diff --git a/Examples/java/reference/example.i b/Examples/java/reference/example.i new file mode 100644 index 0000000..6daa3b1 --- /dev/null +++ b/Examples/java/reference/example.i @@ -0,0 +1,46 @@ +/* File : example.i */ + +/* This file has a few "typical" uses of C++ references. */ + +%module example + +%{ +#include "example.h" +%} + +class Vector { +public: + Vector(double x, double y, double z); + ~Vector(); + char *print(); +}; + +/* This helper function calls an overloaded operator */ +%inline %{ +Vector addv(Vector &a, Vector &b) { + return a+b; +} +%} + +/* Wrapper around an array of vectors class */ + +class VectorArray { +public: + VectorArray(int maxsize); + ~VectorArray(); + int size(); + + /* This wrapper provides an alternative to the [] operator */ + %extend { + Vector &get(int index) { + return (*$self)[index]; + } + void set(int index, Vector &a) { + (*$self)[index] = a; + } + } +}; + + + + diff --git a/Examples/java/reference/index.html b/Examples/java/reference/index.html new file mode 100644 index 0000000..33c80c5 --- /dev/null +++ b/Examples/java/reference/index.html @@ -0,0 +1,147 @@ +<html> +<head> +<title>SWIG:Examples:java:reference</title> +</head> + +<body bgcolor="#ffffff"> + + +<tt>SWIG/Examples/java/reference/</tt> +<hr> + +<H2>C++ Reference Handling</H2> + +<p> +This example tests SWIG's handling of C++ references. Since C++ +references are closely related to pointers (as both refer to a +location in memory), SWIG simply collapses all references into +pointers when creating wrappers. + +<h2>Some examples</h2> + +References are most commonly used as function parameter. For example, +you might have an operator like this: + +<blockquote> +<pre> +Vector operator+(const Vector &a, const Vector &b) { + Vector result; + result.x = a.x + b.x; + result.y = a.y + b.y; + result.z = a.z + b.z; + return result; +} +</pre> +</blockquote> + +or a function: + +<blockquote> +<pre> +Vector addv(const Vector &a, const Vector &b) { + Vector result; + result.x = a.x + b.x; + result.y = a.y + b.y; + result.z = a.z + b.z; + return result; +} +</pre> +</blockquote> + +In these cases, SWIG transforms everything into a pointer and creates a wrapper +that looks like this: + +<blockquote> +<pre> +Vector wrap_addv(Vector *a, Vector *b) { + return addv(*a,*b); +} +</pre> +</blockquote> + +Occasionally, a reference is used as a return value of a function +when the return result is to be used as an lvalue in an expression. +The prototypical example is an operator like this: + +<blockquote> +<pre> +Vector &operator[](int index); +</pre> +</blockquote> + +or a method: + +<blockquote> +<pre> +Vector &get(int index); +</pre> +</blockquote> + +For functions returning references, a wrapper like this is created: + +<blockquote> +<pre> +Vector *wrap_Object_get(Object *self, int index) { + Vector &result = self->get(index); + return &result; +} +</pre> +</blockquote> + +The following <a href="example.h">header file</a> contains some class +definitions with some operators and use of references. + +<h2>SWIG Interface</h2> + +SWIG does NOT support overloaded operators so it can not directly build +an interface to the classes in the above file. However, a number of workarounds +can be made. For example, an overloaded operator can be stuck behind a function +call such as the <tt>addv()</tt> function above. Array access can be handled +with a pair of set/get functions like this: + +<blockquote> +<pre> +class VectorArray { +public: + ... + %addmethods { + Vector &get(int index) { + return (*self)[index]; + } + void set(int index, Vector &a) { + (*self)[index] = a; + } + } + ... +} +</pre> +</blockquote> + +Click <a href="example.i">here</a> to see a SWIG interface file with these additions. + +<h2>Sample Java program</h2> + +Click <a href="runme.java">here</a> to see a Java program that manipulates some C++ references. + +<h2>Notes:</h2> + +<ul> +<li>C++ references primarily provide notational convenience for C++ +source code. However, Java only supports the 'x.a' +notation so it doesn't much matter. + +<p> +<li>When a program returns a reference, a pointer is returned. +Unlike return by value, memory is not allocated to hold the +return result. + +<p> +<li>SWIG has particular trouble handling various combinations of references +and pointers. This is side effect of an old parsing scheme and +type representation that will be replaced in future versions. + +</ul> + +<hr> +</body> +</html> diff --git a/Examples/java/reference/runme.java b/Examples/java/reference/runme.java new file mode 100644 index 0000000..6a2d9bf --- /dev/null +++ b/Examples/java/reference/runme.java @@ -0,0 +1,79 @@ +// This example illustrates the manipulation of C++ references in Java. + +public class runme { + static { + try { + System.loadLibrary("example"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + System.out.println( "Creating some objects:" ); + Vector a = new Vector(3,4,5); + Vector b = new Vector(10,11,12); + + System.out.println( " Created " + a.print() ); + System.out.println( " Created " + b.print() ); + + // ----- Call an overloaded operator ----- + + // This calls the wrapper we placed around + // + // operator+(const Vector &a, const Vector &) + // + // It returns a new allocated object. + + System.out.println( "Adding a+b" ); + Vector c = example.addv(a,b); + System.out.println( " a+b = " + c.print() ); + + // Note: Unless we free the result, a memory leak will occur if the -noproxy commandline + // is used as the proxy classes define finalizers which call the delete() method. When + // -noproxy is not specified the memory management is controlled by the garbage collector. + // You can still call delete(). It will free the c++ memory immediately, but not the + // Java memory! You then must be careful not to call any member functions as it will + // use a NULL c pointer on the underlying c++ object. We set the Java object to null + // which will then throw a Java exception should we attempt to use it again. + c.delete(); + c = null; + + // ----- Create a vector array ----- + + System.out.println( "Creating an array of vectors" ); + VectorArray va = new VectorArray(10); + System.out.println( " va = " + va.toString() ); + + // ----- Set some values in the array ----- + + // These operators copy the value of Vector a and Vector b to the vector array + va.set(0,a); + va.set(1,b); + + // This works, but it would cause a memory leak if -noproxy was used! + + va.set(2,example.addv(a,b)); + + + // Get some values from the array + + System.out.println( "Getting some array values" ); + for (int i=0; i<5; i++) + System.out.println( " va(" + i + ") = " + va.get(i).print() ); + + // Watch under resource meter to check on this + System.out.println( "Making sure we don't leak memory." ); + for (int i=0; i<1000000; i++) + c = va.get(i%10); + + // ----- Clean up ----- + // This could be omitted. The garbage collector would then clean up for us. + System.out.println( "Cleaning up" ); + va.delete(); + a.delete(); + b.delete(); + } +} diff --git a/Examples/java/simple/Makefile b/Examples/java/simple/Makefile new file mode 100644 index 0000000..968c92c --- /dev/null +++ b/Examples/java/simple/Makefile @@ -0,0 +1,18 @@ +TOP = ../.. +SWIG = $(TOP)/../preinst-swig +SRCS = example.c +TARGET = example +INTERFACE = example.i +SWIGOPT = + +all:: java + +java:: + $(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \ + SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' java + javac *.java + +clean:: + $(MAKE) -f $(TOP)/Makefile java_clean + +check: all diff --git a/Examples/java/simple/example.c b/Examples/java/simple/example.c new file mode 100644 index 0000000..1c2af78 --- /dev/null +++ b/Examples/java/simple/example.c @@ -0,0 +1,18 @@ +/* File : example.c */ + +/* A global variable */ +double Foo = 3.0; + +/* Compute the greatest common divisor of positive integers */ +int gcd(int x, int y) { + int g; + g = y; + while (x > 0) { + g = x; + x = y % x; + y = g; + } + return g; +} + + diff --git a/Examples/java/simple/example.dsp b/Examples/java/simple/example.dsp new file mode 100644 index 0000000..8e1f841 --- /dev/null +++ b/Examples/java/simple/example.dsp @@ -0,0 +1,158 @@ +# Microsoft Developer Studio Project File - Name="example" - Package Owner=<4>
+# Microsoft Developer Studio Generated Build File, Format Version 6.00
+# ** DO NOT EDIT **
+
+# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102
+
+CFG=example - Win32 Release
+!MESSAGE This is not a valid makefile. To build this project using NMAKE,
+!MESSAGE use the Export Makefile command and run
+!MESSAGE
+!MESSAGE NMAKE /f "example.mak".
+!MESSAGE
+!MESSAGE You can specify a configuration when running NMAKE
+!MESSAGE by defining the macro CFG on the command line. For example:
+!MESSAGE
+!MESSAGE NMAKE /f "example.mak" CFG="example - Win32 Release"
+!MESSAGE
+!MESSAGE Possible choices for configuration are:
+!MESSAGE
+!MESSAGE "example - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library")
+!MESSAGE "example - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library")
+!MESSAGE
+
+# Begin Project
+# PROP AllowPerConfigDependencies 0
+# PROP Scc_ProjName ""
+# PROP Scc_LocalPath ""
+CPP=cl.exe
+MTL=midl.exe
+RSC=rc.exe
+
+!IF "$(CFG)" == "example - Win32 Debug"
+
+# PROP BASE Use_MFC 0
+# PROP BASE Use_Debug_Libraries 1
+# PROP BASE Output_Dir "Debug"
+# PROP BASE Intermediate_Dir "Debug"
+# PROP BASE Target_Dir ""
+# PROP Use_MFC 0
+# PROP Use_Debug_Libraries 1
+# PROP Output_Dir "Debug"
+# PROP Intermediate_Dir "Debug"
+# PROP Ignore_Export_Lib 0
+# PROP Target_Dir ""
+# ADD BASE CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /GZ /c
+# ADD CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /I "$(JAVA_INCLUDE)" /I "$(JAVA_INCLUDE)\win32" /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /GZ /c
+# ADD BASE MTL /nologo /D "_DEBUG" /mktyplib203 /win32
+# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32
+# ADD BASE RSC /l 0x809 /d "_DEBUG"
+# ADD RSC /l 0x809 /d "_DEBUG"
+BSC32=bscmake.exe
+# ADD BASE BSC32 /nologo
+# ADD BSC32 /nologo
+LINK32=link.exe
+# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /debug /machine:I386 /pdbtype:sept
+# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /debug /machine:I386 /out:"example.dll" /pdbtype:sept
+# Begin Special Build Tool
+SOURCE="$(InputPath)"
+PostBuild_Desc=Java compile post-build step
+PostBuild_Cmds=echo on "%JAVA_BIN%\javac" *.java
+# End Special Build Tool
+
+!ELSEIF "$(CFG)" == "example - Win32 Release"
+
+# PROP BASE Use_MFC 0
+# PROP BASE Use_Debug_Libraries 0
+# PROP BASE Output_Dir "Release"
+# PROP BASE Intermediate_Dir "Release"
+# PROP BASE Target_Dir ""
+# PROP Use_MFC 0
+# PROP Use_Debug_Libraries 0
+# PROP Output_Dir "Release"
+# PROP Intermediate_Dir "Release"
+# PROP Ignore_Export_Lib 0
+# PROP Target_Dir ""
+# ADD BASE CPP /nologo /MT /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /c
+# ADD CPP /nologo /MT /W3 /GX /O2 /I "$(JAVA_INCLUDE)" /I "$(JAVA_INCLUDE)\win32" /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /c
+# ADD BASE MTL /nologo /D "NDEBUG" /mktyplib203 /win32
+# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32
+# ADD BASE RSC /l 0x809 /d "NDEBUG"
+# ADD RSC /l 0x809 /d "NDEBUG"
+BSC32=bscmake.exe
+# ADD BASE BSC32 /nologo
+# ADD BSC32 /nologo
+LINK32=link.exe
+# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /machine:I386
+# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /machine:I386 /out:"example.dll"
+# Begin Special Build Tool
+SOURCE="$(InputPath)"
+PostBuild_Desc=Java compile post-build step
+PostBuild_Cmds=echo on "%JAVA_BIN%\javac" *.java
+# End Special Build Tool
+
+!ENDIF
+
+# Begin Target
+
+# Name "example - Win32 Debug"
+# Name "example - Win32 Release"
+# Begin Group "Source Files"
+
+# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat"
+# Begin Source File
+
+SOURCE=.\example.c
+# End Source File
+# Begin Source File
+
+SOURCE=.\example_wrap.c
+# End Source File
+# End Group
+# Begin Group "Header Files"
+
+# PROP Default_Filter "h;hpp;hxx;hm;inl"
+# End Group
+# Begin Group "Resource Files"
+
+# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe"
+# End Group
+# Begin Source File
+
+SOURCE=.\example.i
+
+!IF "$(CFG)" == "example - Win32 Debug"
+
+# Begin Custom Build
+InputPath=.\example.i
+InputName=example
+
+"$(InputName)_wrap.c" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"
+ echo In order to function correctly, please ensure the following environment variables are correctly set:
+ echo JAVA_INCLUDE: %JAVA_INCLUDE%
+ echo JAVA_BIN: %JAVA_BIN%
+ echo on
+ ..\..\..\swig.exe -java $(InputPath)
+
+# End Custom Build
+
+!ELSEIF "$(CFG)" == "example - Win32 Release"
+
+# Begin Custom Build
+InputPath=.\example.i
+InputName=example
+
+"$(InputName)_wrap.c" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"
+ echo In order to function correctly, please ensure the following environment variables are correctly set:
+ echo JAVA_INCLUDE: %JAVA_INCLUDE%
+ echo JAVA_BIN: %JAVA_BIN%
+ echo on
+ ..\..\..\swig.exe -java $(InputPath)
+
+# End Custom Build
+
+!ENDIF
+
+# End Source File
+# End Target
+# End Project
diff --git a/Examples/java/simple/example.i b/Examples/java/simple/example.i new file mode 100644 index 0000000..24093b9 --- /dev/null +++ b/Examples/java/simple/example.i @@ -0,0 +1,7 @@ +/* File : example.i */ +%module example + +%inline %{ +extern int gcd(int x, int y); +extern double Foo; +%} diff --git a/Examples/java/simple/index.html b/Examples/java/simple/index.html new file mode 100644 index 0000000..9729e6d --- /dev/null +++ b/Examples/java/simple/index.html @@ -0,0 +1,108 @@ +<html> +<head> +<title>SWIG:Examples:java:simple</title> +</head> + +<body bgcolor="#ffffff"> + + +<tt>SWIG/Examples/java/simple/</tt> +<hr> + +<H2>Simple Java Example</H2> + +<p> +This example illustrates how you can hook Java to a very simple C program containing +a function and a global variable. + +<h2>The C Code</h2> + +Suppose you have the following C code: + +<blockquote> +<pre> +/* File : example.c */ + +/* A global variable */ +double Foo = 3.0; + +/* Compute the greatest common divisor of positive integers */ +int gcd(int x, int y) { + int g; + g = y; + while (x > 0) { + g = x; + x = y % x; + y = g; + } + return g; +} +</pre> +</blockquote> + +<h2>The SWIG interface</h2> + +Here is a simple SWIG interface file: + +<blockquote> +<pre> +/* File: example.i */ +%module example + +extern int gcd(int x, int y); +extern double Foo; +</pre> +</blockquote> + +<h2>Compilation</h2> + +<ol> +<li><tt>swig -java <a href="example.i">example.i</a></tt> +<p> +<li>Compile <tt><a href="example_wrap.c">example_wrap.c</a></tt> and <tt><a href="example.c">example.c</a></tt> +to create the extension <tt>libexample.so (unix)</tt>. +</ol> + +<h2>Using the extension</h2> + +Click <a href="runme.java">here</a> to see a program that calls our C functions from Java. +<p> +Compile the java files <tt><a href="example.java">example.java</a></tt> and <tt><a href="runme.java">runme.java</a></tt> +to create the class files example.class and runme.class before running runme in the JVM. Ensure that the libexample.so file is in your LD_LIBRARY_PATH before running. For example: +<blockquote> +<pre> +export LD_LIBRARY_PATH=. #ksh +javac *.java +java runme +</pre> +</blockquote> + +<h2>Key points</h2> + +<ul> +<li>Use the <tt>loadLibrary</tt> statement from java to load and access the generated java classes. For example: +<blockquote> +<pre> +System.loadLibrary("example"); +</pre> +</blockquote> + +<li>C functions work just like Java functions. For example: +<blockquote> +<pre> +int g = example.gcd(42,105); +</pre> +</blockquote> + +<li>C global variables are accessed through get and set functions in the module class. For example: +<blockquote> +<pre> +double a = example.get_Foo(); +example.set_Foo(20.0); +</pre> +</blockquote> +</ul> + +<hr> +</body> +</html> diff --git a/Examples/java/simple/runme.java b/Examples/java/simple/runme.java new file mode 100644 index 0000000..92880e8 --- /dev/null +++ b/Examples/java/simple/runme.java @@ -0,0 +1,32 @@ + +public class runme { + + static { + try { + System.loadLibrary("example"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) { + // Call our gcd() function + + int x = 42; + int y = 105; + int g = example.gcd(x,y); + System.out.println("The gcd of " + x + " and " + y + " is " + g); + + // Manipulate the Foo global variable + + // Output its current value + System.out.println("Foo = " + example.getFoo()); + + // Change its value + example.setFoo(3.1415926); + + // See if the change took effect + System.out.println("Foo = " + example.getFoo()); + } +} diff --git a/Examples/java/template/Makefile b/Examples/java/template/Makefile new file mode 100644 index 0000000..2b3d35c --- /dev/null +++ b/Examples/java/template/Makefile @@ -0,0 +1,18 @@ +TOP = ../.. +SWIG = $(TOP)/../preinst-swig +CXXSRCS = +TARGET = example +INTERFACE = example.i +SWIGOPT = + +all:: java + +java:: + $(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \ + SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' java_cpp + javac *.java + +clean:: + $(MAKE) -f $(TOP)/Makefile java_clean + +check: all diff --git a/Examples/java/template/example.h b/Examples/java/template/example.h new file mode 100644 index 0000000..7401df6 --- /dev/null +++ b/Examples/java/template/example.h @@ -0,0 +1,32 @@ +/* File : example.h */ + +// Some template definitions + +template<class T> T max(T a, T b) { return a>b ? a : b; } + +template<class T> class vector { + T *v; + int sz; + public: + vector(int _sz) { + v = new T[_sz]; + sz = _sz; + } + T &get(int index) { + return v[index]; + } + void set(int index, T &val) { + v[index] = val; + } +#ifdef SWIG + %extend { + T getitem(int index) { + return $self->get(index); + } + void setitem(int index, T val) { + $self->set(index,val); + } + } +#endif +}; + diff --git a/Examples/java/template/example.i b/Examples/java/template/example.i new file mode 100644 index 0000000..8f94c4d --- /dev/null +++ b/Examples/java/template/example.i @@ -0,0 +1,17 @@ +/* File : example.i */ +%module example + +%{ +#include "example.h" +%} + +/* Let's just grab the original header file here */ +%include "example.h" + +/* Now instantiate some specific template declarations */ + +%template(maxint) max<int>; +%template(maxdouble) max<double>; +%template(vecint) vector<int>; +%template(vecdouble) vector<double>; + diff --git a/Examples/java/template/index.html b/Examples/java/template/index.html new file mode 100644 index 0000000..f4408e5 --- /dev/null +++ b/Examples/java/template/index.html @@ -0,0 +1,102 @@ +<html> +<head> +<title>SWIG:Examples:java:template</title> +</head> + +<body bgcolor="#ffffff"> + + +<tt>SWIG/Examples/java/template/</tt> +<hr> + +<H2>C++ template support</H2> + +<p> +This example illustrates how C++ templates can be used from Java using SWIG. + +<h2>The C++ Code</h2> + +Lets take a templated function and a templated class as follows: + +<blockquote> +<pre> +/* File : example.h */ + +// Some template definitions + +template<class T> T max(T a, T b) { return a>b ? a : b; } + +template<class T> class vector { + T *v; + int sz; + public: + vector(int _sz) { + v = new T[_sz]; + sz = _sz; + } + T &get(int index) { + return v[index]; + } + void set(int index, T &val) { + v[index] = val; + } +#ifdef SWIG + %addmethods { + T getitem(int index) { + return self->get(index); + } + void setitem(int index, T val) { + self->set(index,val); + } + } +#endif +}; +</pre> +</blockquote> +The %addmethods is used for a neater interface from Java as the functions <tt>get</tt> and <tt>set</tt> use C++ references to primitive types. These are tricky to use from Java as they end up as a pointer in Java (Java long). + +<h2>The SWIG interface</h2> + +A simple SWIG interface for this can be built by simply grabbing the header file +like this: + +<blockquote> +<pre> +/* File : example.i */ +%module example + +%{ +#include "example.h" +%} + +/* Let's just grab the original header file here */ +%include "example.h" + +/* Now instantiate some specific template declarations */ + +%template(maxint) max<int>; +%template(maxdouble) max<double>; +%template(vecint) vector<int>; +%template(vecdouble) vector<double>; +</pre> +</blockquote> + +Note that SWIG parses the templated function <tt>max</tt> and templated class <tt>vector</tt> and so knows about them. However to generate code for use from Java, SWIG has to be told which class/type to use as the template parameter. The SWIG directive %template is used for this. + +<h2>A sample Java program</h2> + +Click <a href="runme.java">here</a> to see a Java program that calls the C++ functions from Java. + +<h2>Notes</h2> +Use templated classes just like you would any other SWIG generated Java class. Use the classnames specified by the %template directive. + +<blockquote> +<pre> +vecdouble dv = new vecdouble(1000); +dv.setitem(i, 12.34)); +</pre> +</blockquote> + +<hr> +</body> +</html> diff --git a/Examples/java/template/runme.java b/Examples/java/template/runme.java new file mode 100644 index 0000000..5d1097b --- /dev/null +++ b/Examples/java/template/runme.java @@ -0,0 +1,45 @@ +// This example illustrates how C++ templates can be used from Java. + +public class runme { + static { + try { + System.loadLibrary("example"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + // Call some templated functions + System.out.println(example.maxint(3,7)); + System.out.println(example.maxdouble(3.14,2.18)); + + // Create some class + + vecint iv = new vecint(100); + vecdouble dv = new vecdouble(1000); + + for (int i=0; i<100; i++) + iv.setitem(i,2*i); + + for (int i=0; i<1000; i++) + dv.setitem(i, 1.0/(i+1)); + + { + int sum = 0; + for (int i=0; i<100; i++) + sum = sum + iv.getitem(i); + + System.out.println(sum); + } + + { + double sum = 0.0; + for (int i=0; i<1000; i++) + sum = sum + dv.getitem(i); + System.out.println(sum); + } + } +} diff --git a/Examples/java/typemap/Makefile b/Examples/java/typemap/Makefile new file mode 100644 index 0000000..92afbd4 --- /dev/null +++ b/Examples/java/typemap/Makefile @@ -0,0 +1,18 @@ +TOP = ../.. +SWIG = $(TOP)/../preinst-swig +SRCS = +TARGET = example +INTERFACE = example.i +SWIGOPT = + +all:: java + +java:: + $(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \ + SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' java + javac *.java + +clean:: + $(MAKE) -f $(TOP)/Makefile java_clean + +check: all diff --git a/Examples/java/typemap/example.i b/Examples/java/typemap/example.i new file mode 100644 index 0000000..7c97e66 --- /dev/null +++ b/Examples/java/typemap/example.i @@ -0,0 +1,101 @@ +/* File : example.i */ +%module example +%{ +/* + example of a function that returns a value in the char * argument + normally used like: + + char buf[bigenough]; + f1(buf); +*/ + +void f1(char *s) { + if(s != NULL) { + sprintf(s, "hello world"); + } +} + +void f2(char *s) { + f1(s); +} + +void f3(char *s) { + f1(s); +} + +%} + +/* default behaviour is that of input arg, Java cannot return a value in a + * string argument, so any changes made by f1(char*) will not be seen in the Java + * string passed to the f1 function. +*/ +void f1(char *s); + +%include various.i + +/* use the BYTE argout typemap to get around this. Changes in the string by + * f2 can be seen in Java. */ +void f2(char *BYTE); + + + +/* Alternative approach uses a StringBuffer typemap for argout */ + +/* Define the types to use in the generated JNI C code and Java code */ +%typemap(jni) char *SBUF "jobject" +%typemap(jtype) char *SBUF "StringBuffer" +%typemap(jstype) char *SBUF "StringBuffer" + +/* How to convert Java(JNI) type to requested C type */ +%typemap(in) char *SBUF { + + $1 = NULL; + if($input != NULL) { + /* Get the String from the StringBuffer */ + jmethodID setLengthID; + jclass sbufClass = (*jenv)->GetObjectClass(jenv, $input); + jmethodID toStringID = (*jenv)->GetMethodID(jenv, sbufClass, "toString", "()Ljava/lang/String;"); + jstring js = (jstring) (*jenv)->CallObjectMethod(jenv, $input, toStringID); + + /* Convert the String to a C string */ + const char *pCharStr = (*jenv)->GetStringUTFChars(jenv, js, 0); + + /* Take a copy of the C string as the typemap is for a non const C string */ + jmethodID capacityID = (*jenv)->GetMethodID(jenv, sbufClass, "capacity", "()I"); + jint capacity = (*jenv)->CallIntMethod(jenv, $input, capacityID); + $1 = (char *) malloc(capacity+1); + strcpy($1, pCharStr); + + /* Release the UTF string we obtained with GetStringUTFChars */ + (*jenv)->ReleaseStringUTFChars(jenv, js, pCharStr); + + /* Zero the original StringBuffer, so we can replace it with the result */ + setLengthID = (*jenv)->GetMethodID(jenv, sbufClass, "setLength", "(I)V"); + (*jenv)->CallVoidMethod(jenv, $input, setLengthID, (jint) 0); + } +} + +/* How to convert the C type to the Java(JNI) type */ +%typemap(argout) char *SBUF { + + if($1 != NULL) { + /* Append the result to the empty StringBuffer */ + jstring newString = (*jenv)->NewStringUTF(jenv, $1); + jclass sbufClass = (*jenv)->GetObjectClass(jenv, $input); + jmethodID appendStringID = (*jenv)->GetMethodID(jenv, sbufClass, "append", "(Ljava/lang/String;)Ljava/lang/StringBuffer;"); + (*jenv)->CallObjectMethod(jenv, $input, appendStringID, newString); + + /* Clean up the string object, no longer needed */ + free($1); + $1 = NULL; + } +} +/* Prevent the default freearg typemap from being used */ +%typemap(freearg) char *SBUF "" + +/* Convert the jstype to jtype typemap type */ +%typemap(javain) char *SBUF "$javainput" + +/* apply the new typemap to our function */ +void f3(char *SBUF); + diff --git a/Examples/java/typemap/index.html b/Examples/java/typemap/index.html new file mode 100644 index 0000000..5dd5919 --- /dev/null +++ b/Examples/java/typemap/index.html @@ -0,0 +1,32 @@ +<html> +<head> +<title>SWIG:Examples:java:typemap</title> +</head> + +<body bgcolor="#ffffff"> + + +<tt>SWIG/Examples/java/typemap/</tt> +<hr> + +<H2>Typemaps in Java</H2> + +<p> +This example shows how typemaps can be used to modify the default behaviour of the Java SWIG module. + +<ul> +<li><a href="example.i">example.i</a>. Interface file. +<li><a href="runme.java">runme.java</a>. Sample Java program. +</ul> + +<h2>Notes</h2> + +<ul> +<li>Shows how to pass strings to Java from c and visa versa. +<li>Typemaps can modify the default behaviour of the Java SWIG module. +<li>The default c to java mapping can be modified using typemaps. +</ul> + +<hr> +</body> +</html> diff --git a/Examples/java/typemap/runme.java b/Examples/java/typemap/runme.java new file mode 100644 index 0000000..fcbcc30 --- /dev/null +++ b/Examples/java/typemap/runme.java @@ -0,0 +1,26 @@ + +public class runme { + + static { + try { + System.loadLibrary("example"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) { + String s = "brave new world"; + example.f1(s); + System.out.println("f1(String): " + s); + + byte b[] = new byte[25]; + example.f2(b); + System.out.println("f2(byte[]): " + new String(b)); + + StringBuffer sb = new StringBuffer(20); + example.f3(sb); + System.out.println("f3(StringBuffer): " + sb); + } +} diff --git a/Examples/java/variables/Makefile b/Examples/java/variables/Makefile new file mode 100644 index 0000000..968c92c --- /dev/null +++ b/Examples/java/variables/Makefile @@ -0,0 +1,18 @@ +TOP = ../.. +SWIG = $(TOP)/../preinst-swig +SRCS = example.c +TARGET = example +INTERFACE = example.i +SWIGOPT = + +all:: java + +java:: + $(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \ + SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' java + javac *.java + +clean:: + $(MAKE) -f $(TOP)/Makefile java_clean + +check: all diff --git a/Examples/java/variables/example.c b/Examples/java/variables/example.c new file mode 100644 index 0000000..aa4ffe9 --- /dev/null +++ b/Examples/java/variables/example.c @@ -0,0 +1,91 @@ +/* File : example.c */ + +/* I'm a file containing some C global variables */ + +/* Deal with Microsoft's attempt at deprecating C standard runtime functions */ +#if !defined(SWIG_NO_CRT_SECURE_NO_DEPRECATE) && defined(_MSC_VER) +# define _CRT_SECURE_NO_DEPRECATE +#endif + +#include <stdio.h> +#include <stdlib.h> +#include "example.h" + +int ivar = 0; +short svar = 0; +long lvar = 0; +unsigned int uivar = 0; +unsigned short usvar = 0; +unsigned long ulvar = 0; +signed char scvar = 0; +unsigned char ucvar = 0; +char cvar = 0; +float fvar = 0; +double dvar = 0; +char *strvar = 0; +const char cstrvar[] = "Goodbye"; +int *iptrvar = 0; +char name[256] = "Dave"; +char path[256] = "/home/beazley"; + + +/* Global variables involving a structure */ +Point *ptptr = 0; +Point pt = { 10, 20 }; + +/* A variable that we will make read-only in the interface */ +int status = 1; + +/* A debugging function to print out their values */ + +void print_vars() { + printf("ivar = %d\n", ivar); + printf("svar = %d\n", svar); + printf("lvar = %ld\n", lvar); + printf("uivar = %u\n", uivar); + printf("usvar = %u\n", usvar); + printf("ulvar = %lu\n", ulvar); + printf("scvar = %d\n", scvar); + printf("ucvar = %u\n", ucvar); + printf("fvar = %g\n", fvar); + printf("dvar = %g\n", dvar); + printf("cvar = %c\n", cvar); + printf("strvar = %s\n", strvar ? strvar : "(null)"); + printf("cstrvar = %s\n", cstrvar ? cstrvar : "(null)"); + printf("iptrvar = %p\n", iptrvar); + printf("name = %s\n", name); + printf("ptptr = %p (%d, %d)\n", ptptr, ptptr ? ptptr->x : 0, ptptr ? ptptr->y : 0); + printf("pt = (%d, %d)\n", pt.x, pt.y); + printf("status = %d\n", status); +} + +/* A function to create an integer (to test iptrvar) */ + +int *new_int(int value) { + int *ip = (int *) malloc(sizeof(int)); + *ip = value; + return ip; +} + +/* A function to create a point */ + +Point *new_Point(int x, int y) { + Point *p = (Point *) malloc(sizeof(Point)); + p->x = x; + p->y = y; + return p; +} + +char * Point_print(Point *p) { + static char buffer[256]; + if (p) { + sprintf(buffer,"(%d,%d)", p->x,p->y); + } else { + sprintf(buffer,"null"); + } + return buffer; +} + +void pt_print() { + printf("(%d, %d)\n", pt.x, pt.y); +} diff --git a/Examples/java/variables/example.h b/Examples/java/variables/example.h new file mode 100644 index 0000000..0f7e895 --- /dev/null +++ b/Examples/java/variables/example.h @@ -0,0 +1,6 @@ +/* File: example.h */ + +typedef struct { + int x,y; +} Point; + diff --git a/Examples/java/variables/example.i b/Examples/java/variables/example.i new file mode 100644 index 0000000..591b871 --- /dev/null +++ b/Examples/java/variables/example.i @@ -0,0 +1,49 @@ +/* File : example.i */ +%module example +%{ +#include "example.h" +%} + +/* Some global variable declarations */ +%inline %{ +extern int ivar; +extern short svar; +extern long lvar; +extern unsigned int uivar; +extern unsigned short usvar; +extern unsigned long ulvar; +extern signed char scvar; +extern unsigned char ucvar; +extern char cvar; +extern float fvar; +extern double dvar; +extern char *strvar; +extern const char cstrvar[]; +extern int *iptrvar; +extern char name[256]; + +extern Point *ptptr; +extern Point pt; +%} + + +/* Some read-only variables */ + +%immutable; + +%inline %{ +extern int status; +extern char path[256]; +%} + +%mutable; + +/* Some helper functions to make it easier to test */ +%inline %{ +extern void print_vars(); +extern int *new_int(int value); +extern Point *new_Point(int x, int y); +extern char *Point_print(Point *p); +extern void pt_print(); +%} + diff --git a/Examples/java/variables/index.html b/Examples/java/variables/index.html new file mode 100644 index 0000000..07b19d4 --- /dev/null +++ b/Examples/java/variables/index.html @@ -0,0 +1,85 @@ +<html> +<head> +<title>SWIG:Examples:java:variables</title> +</head> + +<body bgcolor="#ffffff"> + +<tt>SWIG/Examples/java/variables/</tt> +<hr> + +<H2>Wrapping C Global Variables</H2> + +<p> +When a C global variable appears in an interface file, SWIG tries to +wrap it using a technique known as "variable linking." The idea is +pretty simple---we try to create a Java variable that magically +retrieves or updates the value of the underlying C variable when it is +accessed. Click <a href="example.i">here</a> to see a SWIG interface with some variable +declarations in it. + + +<p>Click <a href="../../../Doc/Manual/Java.html#global_variables">here</a> for the section on global variables in the SWIG and Java documentation.</p> +<h2>Manipulating Variables from Java</h2> + +C variables are accessed through getters and setters from Java. Unfortunately this is the only way to get current values from variables because it is not possible to overload the dot operator in Java. All global variables are accessible from the module class. For example if the module class is called 'example', the global variable + +<blockquote> +<pre> +double foo; +</pre> +</blockquote> + +will be accessed in the Java module as +<blockquote> +<pre> +example.get_foo(); +example.set_foo(12.3); +</pre> +</blockquote> + +Click <a href="runme.java">here</a> to see the example program that updates and prints +out the values of the variables using this technique. + +<h2>Key points</h2> + +<ul> +<li>When a global variable has the type "<tt>char *</tt>", SWIG manages it as a character +string. However, whenever the value of such a variable is set from Java, the old +value is destroyed using <tt>free()</tt> or <tt>delete</tt> (the choice of which depends +on whether or not SWIG was run with the -c++ option). +<li><tt>signed char</tt> and <tt>unsigned char</tt> are handled as small 8-bit integers. +<li>String array variables such as '<tt>char name[256]</tt>' are managed as Java strings, but +when setting the value, the result is truncated to the maximum length of the array. Furthermore, the string is assumed to be null-terminated. +<li>When structures and classes are used as global variables, they are mapped into pointers. +Getting the "value" returns a pointer to the global variable. Setting the value of a structure results in a memory copy from a pointer to the global. +</ul> + +<h2>Creating read-only variables</h2> + +The <tt>%immutable</tt> and <tt>%mutable</tt> directives can be used to +specify a collection of read-only variables. For example: + +<blockquote> +<pre> +%immutable; +int status; +double blah; +... +%mutable; +</pre> +</blockquote> + +The <tt>%immutable</tt> directive remains in effect until it is explicitly disabled +using the <tt>%mutable</tt> directive. + +<h2>Comments</h2> +<ul> +<li>Management of global variables is one of the most problematic aspects +of C/C++ wrapping because the Java interface and resulting memory management +is much trickier than simply creating a wrapper function. +</ul> + +</body> +</html> +<hr> diff --git a/Examples/java/variables/runme.java b/Examples/java/variables/runme.java new file mode 100644 index 0000000..361a30f --- /dev/null +++ b/Examples/java/variables/runme.java @@ -0,0 +1,97 @@ +// This example illustrates global variable access from Java. + +import java.lang.reflect.*; + +public class runme { + static { + try { + System.loadLibrary("example"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) { + +// Try to set the values of some global variables + + example.setIvar(42); + example.setSvar((short)-31000); + example.setLvar(65537); + example.setUivar(123456); + example.setUsvar(61000); + example.setUlvar(654321); + example.setScvar((byte)-13); + example.setUcvar((short)251); + example.setCvar('S'); + example.setFvar((float)3.14159); + example.setDvar(2.1828); + example.setStrvar("Hello World"); + example.setIptrvar(example.new_int(37)); + example.setPtptr(example.new_Point(37,42)); + example.setName("Bill"); + + // Now print out the values of the variables + + System.out.println( "Variables (values printed from Java)" ); + + System.out.println( "ivar =" + example.getIvar() ); + System.out.println( "svar =" + example.getSvar() ); + System.out.println( "lvar =" + example.getLvar() ); + System.out.println( "uivar =" + example.getUivar() ); + System.out.println( "usvar =" + example.getUsvar() ); + System.out.println( "ulvar =" + example.getUlvar() ); + System.out.println( "scvar =" + example.getScvar() ); + System.out.println( "ucvar =" + example.getUcvar() ); + System.out.println( "fvar =" + example.getFvar() ); + System.out.println( "dvar =" + example.getDvar() ); + System.out.println( "cvar =" + (char)example.getCvar() ); + System.out.println( "strvar =" + example.getStrvar() ); + System.out.println( "cstrvar =" + example.getCstrvar() ); + System.out.println( "iptrvar =" + Long.toHexString(SWIGTYPE_p_int.getCPtr(example.getIptrvar())) ); + System.out.println( "name =" + example.getName() ); + System.out.println( "ptptr =" + Long.toHexString(SWIGTYPE_p_Point.getCPtr(example.getPtptr())) + example.Point_print(example.getPtptr()) ); + System.out.println( "pt =" + Long.toHexString(SWIGTYPE_p_Point.getCPtr(example.getPt())) + example.Point_print(example.getPt()) ); + + System.out.println( "\nVariables (values printed from C)" ); + + example.print_vars(); + + System.out.println( "\nNow I'm going to try and modify some read only variables" ); + + System.out.println( " Trying to set 'path'" ); + try { + Method m = example.class.getDeclaredMethod("setPath", new Class[] {String.class}); + m.invoke(example.class, new Object[] {"Whoa!"} ); + System.out.println( "Hey, what's going on?!?! This shouldn't work" ); + } + catch (NoSuchMethodException e) { + System.out.println( "Good." ); + } + catch (Throwable t) { + System.out.println( "You shouldn't see this!" ); + } + + System.out.println( " Trying to set 'status'" ); + try { + Method m = example.class.getDeclaredMethod("setStatus", new Class[] {Integer.class}); + m.invoke(example.class, new Object[] {new Integer(0)} ); + System.out.println( "Hey, what's going on?!?! This shouldn't work" ); + } + catch (NoSuchMethodException e) { + System.out.println( "Good." ); + } + catch (Throwable t) { + System.out.println( "You shouldn't see this!" ); + } + + System.out.println( "\nI'm going to try and update a structure variable.\n" ); + + example.setPt(example.getPtptr()); + + System.out.println( "The new value is" ); + example.pt_print(); + System.out.println( "You should see the value" + example.Point_print(example.getPtptr()) ); + } +} |