PageRenderTime 27ms CodeModel.GetById 17ms app.highlight 5ms RepoModel.GetById 1ms app.codeStats 1ms

/trunk/Examples/java/class/index.html

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