/tags/rel-1-3-15/SWIG/Examples/java/class/index.html
HTML | 199 lines | 156 code | 43 blank | 0 comment | 0 complexity | a1d06e69421ab67bb198db6af3273b06 MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0
1<html>
2<head>
3<title>SWIG:Examples:java:class</title>
4</head>
5
6<body bgcolor="#ffffff">
7
8
9<tt>SWIG/Examples/java/class/</tt>
10<hr>
11
12<H2>Wrapping a simple C++ class</H2>
13
14<tt>$Header$</tt><br>
15
16<p>
17This example illustrates the high level form of C++ class wrapping performed
18by SWIG. In this case, a C++ class has a proxy Java class, which
19provides access to C++ class members.
20
21<h2>The C++ Code</h2>
22
23Suppose you have some C++ classes described by the following (and admittedly lame)
24header file:
25
26<blockquote>
27<pre>
28/* File : example.h */
29
30class Shape {
31public:
32 Shape() {
33 nshapes++;
34 }
35 virtual ~Shape() {
36 nshapes--;
37 };
38 double x, y;
39 void move(double dx, double dy);
40 virtual double area() = 0;
41 virtual double perimeter() = 0;
42 static int nshapes;
43};
44
45class Circle : public Shape {
46private:
47 double radius;
48public:
49 Circle(double r) : radius(r) { };
50 virtual double area();
51 virtual double perimeter();
52};
53
54class Square : public Shape {
55private:
56 double width;
57public:
58 Square(double w) : width(w) { };
59 virtual double area();
60 virtual double perimeter();
61};
62</pre>
63</blockquote>
64
65<h2>The SWIG interface</h2>
66
67A simple SWIG interface for this can be built by simply grabbing the header file
68like this:
69
70<blockquote>
71<pre>
72/* File : example.i */
73%module example
74
75%{
76#include "example.h"
77%}
78
79/* Let's just grab the original header file here */
80%include "example.h"
81</pre>
82</blockquote>
83
84Note: when creating a C++ extension, you must run SWIG with the <tt>-c++</tt> option like this:
85<blockquote>
86<pre>
87% swig -c++ -java example.i
88</pre>
89</blockquote>
90
91<h2>A sample Java program</h2>
92
93Click <a href="main.java">here</a> to see a Java program that calls the C++ functions from Java.
94
95<h2>Key points</h2>
96
97<ul>
98<li>To create a new object, you call a constructor like this:
99
100<blockquote>
101<pre>
102Circle c = new Circle(10);
103</pre>
104</blockquote>
105
106<p>
107<li>To access member data, a pair of accessor functions are used.
108For example:
109
110<blockquote>
111<pre>
112c.setX(15); // Set member data
113x = c.getX(); // Get member data
114</pre>
115</blockquote>
116
117<p>
118<li>To invoke a member function, you simply do this
119
120<blockquote>
121<pre>
122System.out.println( "The area is " + c.area() );
123</pre>
124</blockquote>
125
126<p>
127<li>To invoke a destructor, simply do this
128
129<blockquote>
130<pre>
131c.delete(); // Deletes a shape
132</pre>
133</blockquote>
134
135<p>
136<li>Static member variables are wrapped with java static get and set access functions. For example:
137
138<blockquote>
139<pre>
140n = Shape.getNshapes(); // Get a static data member
141Shape.setNshapes(13); // Set a static data member
142</pre>
143</blockquote>
144
145</ul>
146
147<h2>General Comments</h2>
148
149<ul>
150<li>This high-level interface using shadow classes is not the only way to handle C++ code.
151A low level interface using c functions to access member variables and member functions is the alternative SWIG
152approach. This entails passing around the c pointer or c++ 'this' pointer and as such it is not difficult to crash the JVM.
153The abstraction of the underlying pointer by the java shadow classes far better fits the java programming paradigm.
154
155<p>
156<li>SWIG *does* know how to properly perform upcasting of objects in an inheritance
157hierarchy (including multiple inheritance). However Java classes can only derive from one base class so multiple inheritance
158is not implemented. Java classes can implement more than one interface so there is scope for improvement in the future.
159
160<p>
161<li>A wide variety of C++ features are not currently supported by SWIG. Here is the
162short and incomplete list:
163
164<p>
165<ul>
166<li>Overloaded methods and functions. SWIG wrappers don't know how to resolve name
167conflicts so you must give an alternative name to any overloaded method name using the
168%name directive like this:
169
170<blockquote>
171<pre>
172void foo(int a);
173%name(foo2) void foo(double a, double b);
174</pre>
175</blockquote>
176
177<p>
178<li>Overloaded operators. Not supported at all. The only workaround for this is
179to write a helper function. For example:
180
181<blockquote>
182<pre>
183%inline %{
184 Vector *vector_add(Vector *a, Vector *b) {
185 ... whatever ...
186 }
187%}
188</pre>
189</blockquote>
190
191<p>
192<li>Namespaces. Not supported at all. Won't be supported until SWIG2.0 (if at all).
193
194</ul>
195</ul>
196
197<hr>
198</body>
199</html>