jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Minor tweaks

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@5290 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton 2003-11-10 22:34:35 +00:00
commit c7d78b6c13
1 changed files with 10 additions and 48 deletions
Download patch file Download diff file Expand all files Collapse all files

58
SWIG/Doc/Manual/Java.html
View file

@ -67,7 +67,6 @@
<li><a href="#n42">Director classes</a> <li><a href="#n42">Director classes</a>
<li><a href="#n43">Overhead and code bloat</a> <li><a href="#n43">Overhead and code bloat</a>
<li><a href="#n44">Simple directors example</a> <li><a href="#n44">Simple directors example</a>
<li><a href="#n45">Director method recursion</a>
</ul> </ul>
<li><a href="#n46">Common customization features</a> <li><a href="#n46">Common customization features</a>
<ul> <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. 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. 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. 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. SWIG enables a Java program to easily call into C/C++ code from Java.
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. 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> <p>
Java is one of the few non-scripting language modules in SWIG. 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. 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. 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. 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> <a name="java_directors_example"></a>
@ -2353,44 +2353,6 @@ directorDerived::upcall_method() invoked.
</pre> </pre>
</blockquote> </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="common_customization"></a>
<a name="n46"></a><H2>15.6 Common customization features</H2> <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(); ambulance.sound_siren();
</pre></blockquote> </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. 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> <blockquote><pre>
%typemap(jni) Vehicle * "jobject" %typemap(jni) Vehicle *vehicle_factory "jobject"
%typemap(jtype) Vehicle * "Vehicle" %typemap(jtype) Vehicle *vehicle_factory "Vehicle"
%typemap(jstype) Vehicle * "Vehicle" %typemap(jstype) Vehicle *vehicle_factory "Vehicle"
%typemap(javaout) Vehicle * { %typemap(javaout) Vehicle *vehicle_factory {
return $jnicall; return $jnicall;
} }
%typemap(out) Vehicle * { %typemap(out) Vehicle *vehicle_factory {
Ambulance *ambulance = dynamic_cast&lt;Ambulance *&gt;($1); Ambulance *ambulance = dynamic_cast&lt;Ambulance *&gt;($1);
FireEngine *fireengine = dynamic_cast&lt;FireEngine *&gt;($1); FireEngine *fireengine = dynamic_cast&lt;FireEngine *&gt;($1);
if (ambulance) { if (ambulance) {