From c7d78b6c132da108a2c888b6f3baee333b535ece Mon Sep 17 00:00:00 2001
From: William S Fulton <wsf@fultondesigns.co.uk>
Date: Mon, 10 Nov 2003 22:34:35 +0000
Subject: [PATCH] Minor tweaks

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@5290 626c5289-ae23-0410-ae9c-e8d60b6d4f22
---
 SWIG/Doc/Manual/Java.html | 58 +++++++--------------------------------
 1 file changed, 10 insertions(+), 48 deletions(-)

diff --git a/SWIG/Doc/Manual/Java.html b/SWIG/Doc/Manual/Java.html
index 6d0da9846..73440799f 100644
--- a/SWIG/Doc/Manual/Java.html
+++ b/SWIG/Doc/Manual/Java.html
@@ -67,7 +67,6 @@
 <li><a href="#n42">Director classes</a>
 <li><a href="#n43">Overhead and code bloat</a>
 <li><a href="#n44">Simple directors example</a>
-<li><a href="#n45">Director method recursion</a>
 </ul>
 <li><a href="#n46">Common customization features</a>
 <ul>
@@ -131,8 +130,10 @@ The Java extension to SWIG makes it very easy to plumb in existing C/C++ code fo
 It is different to using the 'javah' tool as SWIG will wrap existing C/C++ code, whereas javah takes 'native' Java function declarations and creates C/C++ function prototypes.
 SWIG wraps C/C++ code using Java proxy classes and is very useful if you want to have access to large amounts of C/C++ code from Java.
 If only one or two JNI functions are needed then using SWIG may be overkill.
-An important point to note is that SWIG enables a Java program to easily call into C/C++ code and not visa-versa.
-If you primarily want calls from C/C++ into Java then currently SWIG isn't particularly useful as the appropriate JNI code will have to be written by hand. 
+SWIG enables a Java program to easily call into C/C++ code from Java.
+Historically, SWIG was not able to generate any code to call into Java code from C++.
+However, SWIG now supports full cross language polymorphism and code is generated to call up from C++ to Java when wrapping C++ virtual methods.
+
 <p>
 
 Java is one of the few non-scripting language modules in SWIG.
@@ -2289,7 +2290,6 @@ Although directors make it natural to mix native C++ objects with Java objects (
 one should be aware of the obvious fact that method calls to Java objects from C++ will be much slower than calls to C++ objects.
 Additionally, compared to classes that do not use directors, the call routing in the director methods adds a small overhead.
 This situation can be optimized by selectively enabling director methods (using the %feature directive) for only those methods that are likely to be extended in Java.
-The <a href="#java_director_recursive">Director method recursion</a> section details how to reduce some overhead involved in recursion checking code which is generated by default.
 
 
 <a name="java_directors_example"></a>
@@ -2353,44 +2353,6 @@ directorDerived::upcall_method() invoked.
 </pre>
 </blockquote>
 
-<a name="java_director_recursive"></a>
-<a name="n45"></a><H3>15.5.5 Director method recursion</H3>
-
-
-<p>
-The Java module's director code attempts to prevent recursion from the C++ proxy class's code to Java and back through the C++ proxy class.
-The most common reason for this loop is a typo in the Java derived class, e.g., <i>pucall_method</i> instead of <i>upcall_method</i> in the following Java code:
-<blockquote>
-<pre>
-public class directorDerived extends DirectorBase {
-  public directorDerived() {
-  }
-
-  public void pucall_method() {
-    System.out.println("directorDerived::upcall_method() invoked.");
-  }
-}
-</pre>
-</blockquote>
-Another common typo is a mismatch between the arguments specified in the C++ method declaration and the Java subclass's method declaration.
-A <code>SWIG_JavaDirectorRicochet</code> exception is raised in Java when this particular problem is detected at runtime.
-</p>
-
-<p>
-This feature can be turned off in the SWIG interface file for the entire class,
-<blockquote>
-<pre>
-%feature("director:recursive") DirectorBase
-</pre>
-</blockquote>
-or selectively for individual methods:
-<blockquote>
-<pre>
-%feature("director:recursive") DirectorBase::upcall_method()
-</pre>
-</blockquote>
-
-
 <a name="common_customization"></a>
 <a name="n46"></a><H2>15.6 Common customization features</H2>
 
@@ -4345,18 +4307,18 @@ Ambulance ambulance = (Ambulance)example.vehicle_factory(0);
 ambulance.sound_siren();
 </pre></blockquote>
 
-the following typemaps will achieve this. 
+the following typemaps targeted at the <tt>vehicle_factory</tt> function will achieve this. 
 Note that in this case, the Java class is constructed using JNI code rather than passing a pointer across the JNI boundary in a Java long for construction in Java code.
 
 <blockquote><pre>
-%typemap(jni) Vehicle * "jobject"
-%typemap(jtype) Vehicle * "Vehicle"
-%typemap(jstype) Vehicle * "Vehicle"
-%typemap(javaout) Vehicle * {
+%typemap(jni) Vehicle *vehicle_factory "jobject"
+%typemap(jtype) Vehicle *vehicle_factory "Vehicle"
+%typemap(jstype) Vehicle *vehicle_factory "Vehicle"
+%typemap(javaout) Vehicle *vehicle_factory {
     return $jnicall;
   }
 
-%typemap(out) Vehicle * {
+%typemap(out) Vehicle *vehicle_factory {
     Ambulance *ambulance = dynamic_cast&lt;Ambulance *&gt;($1);
     FireEngine *fireengine = dynamic_cast&lt;FireEngine *&gt;($1);
     if (ambulance) {