6 files changed, 362 insertions, 0 deletions
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 &amp;a, const Vector &amp;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 &amp;a, const Vector &amp;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 &amp;operator[](int index);
+</pre>
+</blockquote>
+
+or a method:
+
+<blockquote>
+<pre>
+Vector &amp;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 &amp;result = self-&gt;get(index);
+    return &amp;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 &amp;get(int index) {
+      return (*self)[index];
+    }
+    void set(int index, Vector &amp;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();
+  }
+}