summaryrefslogtreecommitdiff
path: root/Doc/Manual/Java.html
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/Manual/Java.html')
-rw-r--r--Doc/Manual/Java.html263
1 files changed, 154 insertions, 109 deletions
diff --git a/Doc/Manual/Java.html b/Doc/Manual/Java.html
index f572ffa32..c6ef2b425 100644
--- a/Doc/Manual/Java.html
+++ b/Doc/Manual/Java.html
@@ -5,7 +5,7 @@
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#FFFFFF">
-<H1><a name="Java"></a>22 SWIG and Java</H1>
+<H1><a name="Java"></a>23 SWIG and Java</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@@ -154,7 +154,7 @@ It covers most SWIG features, but certain low-level details are covered in less
</p>
-<H2><a name="Java_overview"></a>22.1 Overview</H2>
+<H2><a name="Java_overview"></a>23.1 Overview</H2>
<p>
@@ -166,7 +166,7 @@ SWIG wraps C/C++ code using Java proxy classes and is very useful if you want to
If only one or two JNI functions are needed then using SWIG may be overkill.
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.
+However, SWIG now supports full cross language polymorphism and code is generated to call up from C++ to Java when wrapping C++ virtual methods via the director feature.
</p>
<p>
@@ -189,7 +189,7 @@ Various customisation tips and techniques using SWIG directives are covered.
The latter sections cover the advanced techniques of using typemaps for complete control of the wrapping process.
</p>
-<H2><a name="Java_preliminaries"></a>22.2 Preliminaries</H2>
+<H2><a name="Java_preliminaries"></a>23.2 Preliminaries</H2>
<p>
@@ -205,7 +205,7 @@ Run <tt>make -k check</tt> from the SWIG root directory after installing SWIG on
The Java module requires your system to support shared libraries and dynamic loading.
This is the commonly used method to load JNI code so your system will more than likely support this.</p>
-<H3><a name="Java_running_swig"></a>22.2.1 Running SWIG</H3>
+<H3><a name="Java_running_swig"></a>23.2.1 Running SWIG</H3>
<p>
@@ -264,7 +264,7 @@ The following sections have further practical examples and details on how you mi
compiling and using the generated files.
</p>
-<H3><a name="Java_commandline"></a>22.2.2 Additional Commandline Options</H3>
+<H3><a name="Java_commandline"></a>23.2.2 Additional Commandline Options</H3>
<p>
@@ -301,7 +301,7 @@ swig -java -help
Their use will become clearer by the time you have finished reading this section on SWIG and Java.
</p>
-<H3><a name="Java_getting_right_headers"></a>22.2.3 Getting the right header files</H3>
+<H3><a name="Java_getting_right_headers"></a>23.2.3 Getting the right header files</H3>
<p>
@@ -316,7 +316,7 @@ They are usually in directories like this:</p>
<p>
The exact location may vary on your machine, but the above locations are typical. </p>
-<H3><a name="Java_compiling_dynamic"></a>22.2.4 Compiling a dynamic module</H3>
+<H3><a name="Java_compiling_dynamic"></a>23.2.4 Compiling a dynamic module</H3>
<p>
@@ -352,7 +352,7 @@ The name of the shared library output file is important.
If the name of your SWIG module is "<tt>example</tt>", the name of the corresponding shared library file should be "<tt>libexample.so</tt>" (or equivalent depending on your machine, see <a href="#Java_dynamic_linking_problems">Dynamic linking problems</a> for more information).
The name of the module is specified using the <tt>%module</tt> directive or<tt> -module</tt> command line option.</p>
-<H3><a name="Java_using_module"></a>22.2.5 Using your module</H3>
+<H3><a name="Java_using_module"></a>23.2.5 Using your module</H3>
<p>
@@ -363,7 +363,7 @@ To load your shared native library module in Java, simply use Java's <tt>System.
public class runme {
static {
-  System.loadLibrary("example");
+  System.loadLibrary("example");
}
public static void main(String argv[]) {
@@ -387,7 +387,7 @@ $
If it doesn't work have a look at the following section which discusses problems loading the shared library.
</p>
-<H3><a name="Java_dynamic_linking_problems"></a>22.2.6 Dynamic linking problems</H3>
+<H3><a name="Java_dynamic_linking_problems"></a>23.2.6 Dynamic linking problems</H3>
<p>
@@ -474,7 +474,7 @@ The following section also contains some C++ specific linking problems and solut
</p>
-<H3><a name="Java_compilation_problems_cpp"></a>22.2.7 Compilation problems and compiling with C++</H3>
+<H3><a name="Java_compilation_problems_cpp"></a>23.2.7 Compilation problems and compiling with C++</H3>
<p>
@@ -527,7 +527,7 @@ Finally make sure the version of JDK header files matches the version of Java th
</p>
-<H3><a name="Java_building_windows"></a>22.2.8 Building on Windows</H3>
+<H3><a name="Java_building_windows"></a>23.2.8 Building on Windows</H3>
<p>
@@ -536,7 +536,7 @@ You will want to produce a DLL that can be loaded by the Java Virtual Machine.
This section covers the process of using SWIG with Microsoft Visual C++ 6 although the procedure may be similar with other compilers.
In order for everything to work, you will need to have a JDK installed on your machine in order to read the JNI header files.</p>
-<H4><a name="Java_visual_studio"></a>22.2.8.1 Running SWIG from Visual Studio</H4>
+<H4><a name="Java_visual_studio"></a>23.2.8.1 Running SWIG from Visual Studio</H4>
<p>
@@ -575,7 +575,7 @@ To run the native code in the DLL (example.dll), make sure that it is in your pa
If the library fails to load have a look at <a href="#Java_dynamic_linking_problems">Dynamic linking problems</a>.
</p>
-<H4><a name="Java_nmake"></a>22.2.8.2 Using NMAKE</H4>
+<H4><a name="Java_nmake"></a>23.2.8.2 Using NMAKE</H4>
<p>
@@ -634,7 +634,7 @@ Of course you may want to make changes for it to work for C++ by adding in the -
</p>
-<H2><a name="Java_basic_tour"></a>22.3 A tour of basic C/C++ wrapping</H2>
+<H2><a name="Java_basic_tour"></a>23.3 A tour of basic C/C++ wrapping</H2>
<p>
@@ -644,7 +644,7 @@ variables are wrapped with JavaBean type getters and setters and so forth.
This section briefly covers the essential aspects of this wrapping.
</p>
-<H3><a name="Java_module_packages_classes"></a>22.3.1 Modules, packages and generated Java classes</H3>
+<H3><a name="Java_module_packages_classes"></a>23.3.1 Modules, packages and generated Java classes</H3>
<p>
@@ -680,7 +680,7 @@ swig -java -package com.bloggs.swig -outdir com/bloggs/swig example.i
SWIG won't create the directory, so make sure it exists beforehand.
</p>
-<H3><a name="Java_functions"></a>22.3.2 Functions</H3>
+<H3><a name="Java_functions"></a>23.3.2 Functions</H3>
<p>
@@ -714,7 +714,7 @@ System.out.println(example.fact(4));
</pre></div>
-<H3><a name="Java_global_variables"></a>22.3.3 Global variables</H3>
+<H3><a name="Java_global_variables"></a>23.3.3 Global variables</H3>
<p>
@@ -801,7 +801,7 @@ extern char *path; // Read-only (due to %immutable)
</div>
-<H3><a name="Java_constants"></a>22.3.4 Constants</H3>
+<H3><a name="Java_constants"></a>23.3.4 Constants</H3>
<p>
@@ -941,7 +941,7 @@ Or if you decide this practice isn't so bad and your own class implements <tt>ex
</p>
-<H3><a name="Java_enumerations"></a>22.3.5 Enumerations</H3>
+<H3><a name="Java_enumerations"></a>23.3.5 Enumerations</H3>
<p>
@@ -955,7 +955,7 @@ The final two approaches use simple integers for each enum item.
Before looking at the various approaches for wrapping named C/C++ enums, anonymous enums are considered.
</p>
-<H4><a name="Java_anonymous_enums"></a>22.3.5.1 Anonymous enums</H4>
+<H4><a name="Java_anonymous_enums"></a>23.3.5.1 Anonymous enums</H4>
<p>
@@ -1018,7 +1018,7 @@ As in the case of constants, you can access them through either the module class
</p>
-<H4><a name="Java_typesafe_enums"></a>22.3.5.2 Typesafe enums</H4>
+<H4><a name="Java_typesafe_enums"></a>23.3.5.2 Typesafe enums</H4>
<p>
@@ -1112,7 +1112,7 @@ When upgrading to JDK 1.5 or later, proper Java enums could be used instead, wit
The following section details proper Java enum generation.
</p>
-<H4><a name="Java_proper_enums"></a>22.3.5.3 Proper Java enums</H4>
+<H4><a name="Java_proper_enums"></a>23.3.5.3 Proper Java enums</H4>
<p>
@@ -1165,7 +1165,7 @@ The additional support methods need not be generated if none of the enum items h
<a href="#Java_simpler_enum_classes">Simpler Java enums for enums without initializers</a> section.
</p>
-<H4><a name="Java_typeunsafe_enums"></a>22.3.5.4 Type unsafe enums</H4>
+<H4><a name="Java_typeunsafe_enums"></a>23.3.5.4 Type unsafe enums</H4>
<p>
@@ -1213,7 +1213,7 @@ Note that unlike typesafe enums, this approach requires users to mostly use diff
Thus the upgrade path to proper enums provided in JDK 1.5 is more painful.
</p>
-<H4><a name="Java_simple_enums"></a>22.3.5.5 Simple enums</H4>
+<H4><a name="Java_simple_enums"></a>23.3.5.5 Simple enums</H4>
<p>
@@ -1232,7 +1232,7 @@ SWIG-1.3.21 and earlier versions wrapped all enums using this approach.
The type unsafe approach is preferable to this one and this simple approach is only included for backwards compatibility with these earlier versions of SWIG.
</p>
-<H3><a name="Java_pointers"></a>22.3.6 Pointers</H3>
+<H3><a name="Java_pointers"></a>23.3.6 Pointers</H3>
<p>
@@ -1320,7 +1320,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return
a NULL pointer if the conversion can't be performed.
</p>
-<H3><a name="Java_structures"></a>22.3.7 Structures</H3>
+<H3><a name="Java_structures"></a>23.3.7 Structures</H3>
<p>
@@ -1488,7 +1488,7 @@ x.setA(3); // Modify x.a - this is the same as b.f.a
</div>
-<H3><a name="Java_classes"></a>22.3.8 C++ classes</H3>
+<H3><a name="Java_classes"></a>23.3.8 C++ classes</H3>
<p>
@@ -1551,7 +1551,7 @@ int bar = Spam.getBar();
</div>
-<H3><a name="Java_inheritance"></a>22.3.9 C++ inheritance</H3>
+<H3><a name="Java_inheritance"></a>23.3.9 C++ inheritance</H3>
<p>
@@ -1612,7 +1612,7 @@ Note that Java does not support multiple inheritance so any multiple inheritance
A warning is given when multiple inheritance is detected and only the first base class is used.
</p>
-<H3><a name="Java_pointers_refs_arrays"></a>22.3.10 Pointers, references, arrays and pass by value</H3>
+<H3><a name="Java_pointers_refs_arrays"></a>23.3.10 Pointers, references, arrays and pass by value</H3>
<p>
@@ -1667,7 +1667,7 @@ to hold the result and a pointer is returned (Java will release this memory
when the returned object's finalizer is run by the garbage collector).
</p>
-<H4><a name="Java_null_pointers"></a>22.3.10.1 Null pointers</H4>
+<H4><a name="Java_null_pointers"></a>23.3.10.1 Null pointers</H4>
<p>
@@ -1691,7 +1691,7 @@ For <tt>spam1</tt> and <tt>spam4</tt> above the Java <tt>null</tt> gets translat
The converse also occurs, that is, NULL pointers are translated into <tt>null</tt> Java objects when returned from a C/C++ function.
</p>
-<H3><a name="Java_overloaded_functions"></a>22.3.11 C++ overloaded functions</H3>
+<H3><a name="Java_overloaded_functions"></a>23.3.11 C++ overloaded functions</H3>
<p>
@@ -1806,7 +1806,7 @@ void spam(unsigned short); // Ignored
</pre>
</div>
-<H3><a name="Java_default_arguments"></a>22.3.12 C++ default arguments</H3>
+<H3><a name="Java_default_arguments"></a>23.3.12 C++ default arguments</H3>
<p>
@@ -1849,7 +1849,7 @@ Further details on default arguments and how to restore this approach are given
</p>
-<H3><a name="Java_namespaces"></a>22.3.13 C++ namespaces</H3>
+<H3><a name="Java_namespaces"></a>23.3.13 C++ namespaces</H3>
<p>
@@ -1922,12 +1922,14 @@ So if SWIG is run using the <tt>-package com.myco</tt> option, a wrapped class,
<div class="shell">
<pre>
-example.i:16: Error: The nspace feature used on 'MyWorld::Material::Color' is not supported unless a package is specified
-with -package - Java does not support types declared in a named package accessing types declared in an unnamed package.
+example.i:16: Error: The nspace feature used on 'MyWorld::Material::Color' is not supported unless
+a package is specified
+with -package - Java does not support types declared in a named package accessing types declared
+in an unnamed package.
</pre>
</div>
-<H3><a name="Java_templates"></a>22.3.14 C++ templates</H3>
+<H3><a name="Java_templates"></a>23.3.14 C++ templates</H3>
<p>
@@ -1976,7 +1978,7 @@ Obviously, there is more to template wrapping than shown in this example.
More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter.
</p>
-<H3><a name="Java_smart_pointers"></a>22.3.15 C++ Smart Pointers</H3>
+<H3><a name="Java_smart_pointers"></a>23.3.15 C++ Smart Pointers</H3>
<p>
@@ -2060,7 +2062,7 @@ Foo f = p.__deref__(); // Returns underlying Foo *
</pre>
</div>
-<H2><a name="Java_further_details"></a>22.4 Further details on the generated Java classes</H2>
+<H2><a name="Java_further_details"></a>23.4 Further details on the generated Java classes</H2>
<p>
@@ -2075,7 +2077,7 @@ Finally enum classes are covered.
First, the crucial intermediary JNI class is considered.
</p>
-<H3><a name="Java_imclass"></a>22.4.1 The intermediary JNI class</H3>
+<H3><a name="Java_imclass"></a>23.4.1 The intermediary JNI class</H3>
<p>
@@ -2195,7 +2197,7 @@ If <tt>name</tt> is the same as <tt>modulename</tt> then the module class name g
from <tt>modulename</tt> to <tt>modulenameModule</tt>.
</p>
-<H4><a name="Java_imclass_pragmas"></a>22.4.1.1 The intermediary JNI class pragmas</H4>
+<H4><a name="Java_imclass_pragmas"></a>23.4.1.1 The intermediary JNI class pragmas</H4>
<p>
@@ -2274,7 +2276,7 @@ For example, let's change the intermediary JNI class access to just the default
All the methods in the intermediary JNI class will then not be callable outside of the package as the method modifiers have been changed from public access to default access. This is useful if you want to prevent users calling these low level functions.
</p>
-<H3><a name="Java_module_class"></a>22.4.2 The Java module class</H3>
+<H3><a name="Java_module_class"></a>23.4.2 The Java module class</H3>
<p>
@@ -2305,7 +2307,7 @@ example.egg(new Foo());
The primary reason for having the module class wrapping the calls in the intermediary JNI class is to implement static type checking. In this case only a <tt>Foo</tt> can be passed to the <tt>egg</tt> function, whereas any <tt>long</tt> can be passed to the <tt>egg</tt> function in the intermediary JNI class.
</p>
-<H4><a name="Java_module_class_pragmas"></a>22.4.2.1 The Java module class pragmas</H4>
+<H4><a name="Java_module_class_pragmas"></a>23.4.2.1 The Java module class pragmas</H4>
<p>
@@ -2356,7 +2358,7 @@ See <a href="#Java_imclass_pragmas">The intermediary JNI class pragmas</a> secti
</p>
-<H3><a name="Java_proxy_classes"></a>22.4.3 Java proxy classes</H3>
+<H3><a name="Java_proxy_classes"></a>23.4.3 Java proxy classes</H3>
<p>
@@ -2432,7 +2434,7 @@ int y = f.spam(5, new Foo());
</pre>
</div>
-<H4><a name="Java_memory_management"></a>22.4.3.1 Memory management</H4>
+<H4><a name="Java_memory_management"></a>23.4.3.1 Memory management</H4>
<p>
@@ -2594,7 +2596,7 @@ and
</p>
-<H4><a name="Java_inheritance_mirroring"></a>22.4.3.2 Inheritance</H4>
+<H4><a name="Java_inheritance_mirroring"></a>23.4.3.2 Inheritance</H4>
<p>
@@ -2710,7 +2712,7 @@ However, true cross language polymorphism can be achieved using the <a href="#Ja
</p>
-<H4><a name="Java_proxy_classes_gc"></a>22.4.3.3 Proxy classes and garbage collection</H4>
+<H4><a name="Java_proxy_classes_gc"></a>23.4.3.3 Proxy classes and garbage collection</H4>
<p>
@@ -2743,7 +2745,7 @@ Call the <tt>System.runFinalizersOnExit(true)</tt> or <tt>Runtime.getRuntime().r
This method is inherently unsafe. It may result in finalizers being called on live objects while other threads are concurrently manipulating those objects, resulting in erratic behavior or deadlock.
</i></div>
<p>In many cases you will be lucky and find that it works, but it is not to be advocated.
-Have a look at <a href="http://java.sun.com">Sun's Java web site</a> and search for <tt>runFinalizersOnExit</tt>.
+Have a look at <a href="http://www.oracle.com/technetwork/java/index.html">Java web site</a> and search for <tt>runFinalizersOnExit</tt>.
</p></li>
<li><p>
@@ -2793,7 +2795,7 @@ The section on <a href="#Java_typemaps">Java typemaps</a> details how to specify
See the <a href="http://www.devx.com/Java/Article/30192">How to Handle Java Finalization's Memory-Retention Issues</a> article for alternative approaches to managing memory by avoiding finalizers altogether.
</p>
-<H4><a name="Java_pgcpp"></a>22.4.3.4 The premature garbage collection prevention parameter for proxy class marshalling</H4>
+<H4><a name="Java_pgcpp"></a>23.4.3.4 The premature garbage collection prevention parameter for proxy class marshalling</H4>
<p>
@@ -2915,7 +2917,7 @@ For example:
<b>Compatibility note:</b> The generation of this additional parameter did not occur in versions prior to SWIG-1.3.30.
</p>
-<H4><a name="Java_multithread_libraries"></a>22.4.3.5 Single threaded applications and thread safety</H4>
+<H4><a name="Java_multithread_libraries"></a>23.4.3.5 Single threaded applications and thread safety</H4>
<p>
@@ -3003,7 +3005,7 @@ for (int i=0; i&lt;100000; i++) {
</pre></div>
-<H3><a name="Java_type_wrapper_classes"></a>22.4.4 Type wrapper classes</H3>
+<H3><a name="Java_type_wrapper_classes"></a>23.4.4 Type wrapper classes</H3>
<p>
@@ -3090,7 +3092,7 @@ public static void spam(SWIGTYPE_p_int x, SWIGTYPE_p_int y, int z) { ... }
</div>
-<H3><a name="Java_enum_classes"></a>22.4.5 Enum classes</H3>
+<H3><a name="Java_enum_classes"></a>23.4.5 Enum classes</H3>
<p>
@@ -3099,7 +3101,7 @@ The <a href="#Java_enumerations">Enumerations</a> section discussed these but om
The following sub-sections detail the various types of enum classes that can be generated.
</p>
-<H4><a name="Java_typesafe_enums_classes"></a>22.4.5.1 Typesafe enum classes</H4>
+<H4><a name="Java_typesafe_enums_classes"></a>23.4.5.1 Typesafe enum classes</H4>
<p>
@@ -3183,7 +3185,7 @@ The <tt>swigValue</tt> method is used for marshalling in the other direction.
The <tt>toString</tt> method is overridden so that the enum name is available.
</p>
-<H4><a name="Java_proper_enums_classes"></a>22.4.5.2 Proper Java enum classes</H4>
+<H4><a name="Java_proper_enums_classes"></a>23.4.5.2 Proper Java enum classes</H4>
<p>
@@ -3261,7 +3263,7 @@ These needn't be generated if the enum being wrapped does not have any initializ
<a href="#Java_simpler_enum_classes">Simpler Java enums for enums without initializers</a> section describes how typemaps can be used to achieve this.
</p>
-<H4><a name="Java_typeunsafe_enums_classes"></a>22.4.5.3 Type unsafe enum classes</H4>
+<H4><a name="Java_typeunsafe_enums_classes"></a>23.4.5.3 Type unsafe enum classes</H4>
<p>
@@ -3292,7 +3294,7 @@ public final class Beverage {
</pre>
</div>
-<H2><a name="Java_directors"></a>22.5 Cross language polymorphism using directors</H2>
+<H2><a name="Java_directors"></a>23.5 Cross language polymorphism using directors</H2>
<p>
@@ -3314,7 +3316,7 @@ The upshot is that C++ classes can be extended in Java and from C++ these extens
Neither C++ code nor Java code needs to know where a particular method is implemented: the combination of proxy classes, director classes, and C wrapper functions transparently takes care of all the cross-language method routing.
</p>
-<H3><a name="Java_enabling_directors"></a>22.5.1 Enabling directors</H3>
+<H3><a name="Java_enabling_directors"></a>23.5.1 Enabling directors</H3>
<p>
@@ -3385,7 +3387,7 @@ public:
</pre>
</div>
-<H3><a name="Java_directors_classes"></a>22.5.2 Director classes</H3>
+<H3><a name="Java_directors_classes"></a>23.5.2 Director classes</H3>
<p>
@@ -3412,7 +3414,7 @@ If the correct implementation is in Java, the Java API is used to call the metho
</p>
-<H3><a name="Java_directors_overhead"></a>22.5.3 Overhead and code bloat</H3>
+<H3><a name="Java_directors_overhead"></a>23.5.3 Overhead and code bloat</H3>
<p>
@@ -3430,7 +3432,7 @@ This situation can be optimized by selectively enabling director methods (using
</p>
-<H3><a name="Java_directors_example"></a>22.5.4 Simple directors example</H3>
+<H3><a name="Java_directors_example"></a>23.5.4 Simple directors example</H3>
<p>
@@ -3495,7 +3497,7 @@ DirectorDerived::upcall_method() invoked.
</pre>
</div>
-<H3><a name="Java_directors_threading"></a>22.5.5 Director threading issues</H3>
+<H3><a name="Java_directors_threading"></a>23.5.5 Director threading issues</H3>
<p>
@@ -3515,7 +3517,7 @@ Macros can be defined on the commandline when compiling your C++ code, or altern
</pre>
</div>
-<H2><a name="Java_allprotected"></a>22.6 Accessing protected members</H2>
+<H2><a name="Java_allprotected"></a>23.6 Accessing protected members</H2>
<p>
@@ -3611,7 +3613,7 @@ class MyProtectedBase extends ProtectedBase
-<H2><a name="Java_common_customization"></a>22.7 Common customization features</H2>
+<H2><a name="Java_common_customization"></a>23.7 Common customization features</H2>
<p>
@@ -3623,7 +3625,7 @@ be awkward. This section describes some common SWIG features that are used
to improve the interface to existing C/C++ code.
</p>
-<H3><a name="Java_helper_functions"></a>22.7.1 C/C++ helper functions</H3>
+<H3><a name="Java_helper_functions"></a>23.7.1 C/C++ helper functions</H3>
<p>
@@ -3689,7 +3691,7 @@ hard to implement. It is possible to improve on this using Java code, typemaps,
customization features as covered in later sections, but sometimes helper functions are a quick and easy solution to difficult cases.
</p>
-<H3><a name="Java_class_extension"></a>22.7.2 Class extension with %extend</H3>
+<H3><a name="Java_class_extension"></a>23.7.2 Class extension with %extend</H3>
<p>
@@ -3752,7 +3754,7 @@ Vector(2,3,4)
in any way---the extensions only show up in the Java interface.
</p>
-<H3><a name="Java_exception_handling"></a>22.7.3 Exception handling with %exception and %javaexception</H3>
+<H3><a name="Java_exception_handling"></a>23.7.3 Exception handling with %exception and %javaexception</H3>
<p>
@@ -3911,7 +3913,7 @@ to raise exceptions. See the <a href="Library.html#Library">SWIG Library</a> ch
The typemap example <a href="#Java_exception_typemap">Handling C++ exception specifications as Java exceptions</a> provides further exception handling capabilities.
</p>
-<H3><a name="Java_method_access"></a>22.7.4 Method access with %javamethodmodifiers</H3>
+<H3><a name="Java_method_access"></a>23.7.4 Method access with %javamethodmodifiers</H3>
<p>
@@ -3937,7 +3939,7 @@ protected static void protect_me() {
</pre>
</div>
-<H2><a name="Java_tips_techniques"></a>22.8 Tips and techniques</H2>
+<H2><a name="Java_tips_techniques"></a>23.8 Tips and techniques</H2>
<p>
@@ -3947,7 +3949,7 @@ strings and arrays. This chapter discusses the common techniques for
solving these problems.
</p>
-<H3><a name="Java_input_output_parameters"></a>22.8.1 Input and output parameters using primitive pointers and references</H3>
+<H3><a name="Java_input_output_parameters"></a>23.8.1 Input and output parameters using primitive pointers and references</H3>
<p>
@@ -4121,7 +4123,7 @@ void foo(Bar *OUTPUT);
will not have the intended effect since <tt>typemaps.i</tt> does not define an OUTPUT rule for <tt>Bar</tt>.
</p>
-<H3><a name="Java_simple_pointers"></a>22.8.2 Simple pointers</H3>
+<H3><a name="Java_simple_pointers"></a>23.8.2 Simple pointers</H3>
<p>
@@ -4187,7 +4189,7 @@ System.out.println("3 + 4 = " + result);
See the <a href="Library.html#Library">SWIG Library</a> chapter for further details.
</p>
-<H3><a name="Java_c_arrays"></a>22.8.3 Wrapping C arrays with Java arrays</H3>
+<H3><a name="Java_c_arrays"></a>23.8.3 Wrapping C arrays with Java arrays</H3>
<p>
@@ -4254,7 +4256,7 @@ Please be aware that the typemaps in this library are not efficient as all the e
There is an alternative approach using the SWIG array library and this is covered in the next section.
</p>
-<H3><a name="Java_unbounded_c_arrays"></a>22.8.4 Unbounded C Arrays</H3>
+<H3><a name="Java_unbounded_c_arrays"></a>23.8.4 Unbounded C Arrays</H3>
<p>
@@ -4399,7 +4401,50 @@ well suited for applications in which you need to create buffers,
package binary data, etc.
</p>
-<H3><a name="Java_heap_allocations"></a>22.8.5 Overriding new and delete to allocate from Java heap</H3>
+<H3><a name="Java_binary_char"></a>Binary data vs Strings</H3>
+
+<p>
+By default SWIG handles <tt>char *</tt> as a string but there is a handy multi-argument typemap available as mentioned in <a href="Library.html#Library_nn10">Passing binary data</a>.
+The following simple example demonstrates using a byte array instead of passing the default string type and length to the wrapped function.
+</p>
+
+
+<div class="code">
+<pre>
+%apply (char *STRING, size_t LENGTH) { (const char data[], size_t len) }
+%inline %{
+void binaryChar1(const char data[], size_t len) {
+ printf("len: %d data: ", len);
+ for (size_t i=0; i&lt;len; ++i)
+ printf("%x ", data[i]);
+ printf("\n");
+}
+%}
+</pre>
+</div>
+
+<p>
+Calling from Java requires just the byte array to be passed in as the multi-argument typemap being applied reduces the number of arguments in the target language to one, from the original two:
+</p>
+
+<div class="code">
+<pre>
+byte[] data = "hi\0jk".getBytes();
+example.binaryChar1(data);
+</pre>
+</div>
+
+<p>
+resulting in the output
+</p>
+
+<div class="code"><pre>
+$ java runme
+len: 5 data: 68 69 0 6a 6b
+</pre></div>
+
+
+<H3><a name="Java_heap_allocations"></a>23.8.5 Overriding new and delete to allocate from Java heap</H3>
<p>
@@ -4516,7 +4561,7 @@ model and use these functions in place of malloc and free in your own
code.
</p>
-<H2><a name="Java_typemaps"></a>22.9 Java typemaps</H2>
+<H2><a name="Java_typemaps"></a>23.9 Java typemaps</H2>
<p>
@@ -4537,7 +4582,7 @@ Before proceeding, it should be stressed that typemaps are not a required
part of using SWIG---the default wrapping behavior is enough in most cases.
Typemaps are only used if you want to change some aspect of the generated code.
-<H3><a name="Java_default_primitive_type_mappings"></a>22.9.1 Default primitive type mappings</H3>
+<H3><a name="Java_default_primitive_type_mappings"></a>23.9.1 Default primitive type mappings</H3>
<p>
@@ -4689,7 +4734,7 @@ However, the mappings allow the full range of values for each C type from Java.
</p>
-<H3><a name="Java_default_non_primitive_typemaps"></a>22.9.2 Default typemaps for non-primitive types</H3>
+<H3><a name="Java_default_non_primitive_typemaps"></a>23.9.2 Default typemaps for non-primitive types</H3>
<p>
@@ -4704,7 +4749,7 @@ So in summary, the C/C++ pointer to non-primitive types is cast into the 64 bit
The Java type is either the proxy class or type wrapper class.
</p>
-<H3><a name="Java_jvm64"></a>22.9.3 Sixty four bit JVMs</H3>
+<H3><a name="Java_jvm64"></a>23.9.3 Sixty four bit JVMs</H3>
<p>
@@ -4717,7 +4762,7 @@ Unfortunately it won't of course hold true for JNI code.
</p>
-<H3><a name="Java_what_is_typemap"></a>22.9.4 What is a typemap?</H3>
+<H3><a name="Java_what_is_typemap"></a>23.9.4 What is a typemap?</H3>
<p>
@@ -4840,7 +4885,7 @@ int c = example.count('e',"Hello World");
</pre>
</div>
-<H3><a name="Java_typemaps_c_to_java_types"></a>22.9.5 Typemaps for mapping C/C++ types to Java types</H3>
+<H3><a name="Java_typemaps_c_to_java_types"></a>23.9.5 Typemaps for mapping C/C++ types to Java types</H3>
<p>
@@ -5100,7 +5145,7 @@ These are listed below:
</table>
-<H3><a name="Java_typemap_attributes"></a>22.9.6 Java typemap attributes</H3>
+<H3><a name="Java_typemap_attributes"></a>23.9.6 Java typemap attributes</H3>
<p>
@@ -5146,7 +5191,7 @@ The "javain" typemap has the optional 'pre', 'post' and 'pgcppname' attributes.
Note that when the 'pre' or 'post' attributes are specified and the associated type is used in a constructor, a constructor helper function is generated. This is necessary as the Java proxy constructor wrapper makes a call to a support constructor using a <i>this</i> call. In Java the <i>this</i> call must be the first statement in the constructor body. The constructor body thus calls the helper function and the helper function instead makes the JNI call, ensuring the 'pre' code is called before the JNI call is made. There is a <a href="#Java_date_marshalling">Date marshalling</a> example showing 'pre', 'post' and 'pgcppname' attributes in action.
</p>
-<H3><a name="Java_special_variables"></a>22.9.7 Java special variables</H3>
+<H3><a name="Java_special_variables"></a>23.9.7 Java special variables</H3>
<p>
@@ -5297,7 +5342,7 @@ This special variable expands to the intermediary class name. Usually this is th
unless the jniclassname attribute is specified in the <a href="Java.html#Java_module_directive">%module directive</a>.
</p>
-<H3><a name="Java_typemaps_for_c_and_cpp"></a>22.9.8 Typemaps for both C and C++ compilation</H3>
+<H3><a name="Java_typemaps_for_c_and_cpp"></a>23.9.8 Typemaps for both C and C++ compilation</H3>
<p>
@@ -5334,7 +5379,7 @@ If you do not intend your code to be targeting both C and C++ then your typemaps
</p>
-<H3><a name="Java_code_typemaps"></a>22.9.9 Java code typemaps</H3>
+<H3><a name="Java_code_typemaps"></a>23.9.9 Java code typemaps</H3>
<p>
@@ -5540,7 +5585,7 @@ For the typemap to be used in all type wrapper classes, all the different types
Again this is the same that is in "<tt>java.swg</tt>", barring the method modifier for <tt>getCPtr</tt>.
</p>
-<H3><a name="Java_directors_typemaps"></a>22.9.10 Director specific typemaps</H3>
+<H3><a name="Java_directors_typemaps"></a>23.9.10 Director specific typemaps</H3>
<p>
@@ -5765,7 +5810,7 @@ The basic strategy here is to provide a default package typemap for the majority
</div>
-<H2><a name="Java_typemap_examples"></a>22.10 Typemap Examples</H2>
+<H2><a name="Java_typemap_examples"></a>23.10 Typemap Examples</H2>
<p>
@@ -5775,7 +5820,7 @@ the SWIG library.
</p>
-<H3><a name="Java_simpler_enum_classes"></a>22.10.1 Simpler Java enums for enums without initializers</H3>
+<H3><a name="Java_simpler_enum_classes"></a>23.10.1 Simpler Java enums for enums without initializers</H3>
<p>
@@ -5854,7 +5899,7 @@ This would be done by using the original versions of these typemaps in "enums.sw
</p>
-<H3><a name="Java_exception_typemap"></a>22.10.2 Handling C++ exception specifications as Java exceptions</H3>
+<H3><a name="Java_exception_typemap"></a>23.10.2 Handling C++ exception specifications as Java exceptions</H3>
<p>
@@ -5979,7 +6024,7 @@ We could alternatively have used <tt>%rename</tt> to rename <tt>what()</tt> into
</p>
-<H3><a name="Java_nan_exception_typemap"></a>22.10.3 NaN Exception - exception handling for a particular type</H3>
+<H3><a name="Java_nan_exception_typemap"></a>23.10.3 NaN Exception - exception handling for a particular type</H3>
<p>
@@ -6134,7 +6179,7 @@ If we were a martyr to the JNI cause, we could replace the succinct code within
If we had, we would have put it in the "in" typemap which, like all JNI and Java typemaps, also supports the 'throws' attribute.
</p>
-<H3><a name="Java_converting_java_string_arrays"></a>22.10.4 Converting Java String arrays to char ** </H3>
+<H3><a name="Java_converting_java_string_arrays"></a>23.10.4 Converting Java String arrays to char ** </H3>
<p>
@@ -6234,7 +6279,7 @@ public class runme {
static {
try {
-  System.loadLibrary("example");
+  System.loadLibrary("example");
} catch (UnsatisfiedLinkError e) {
System.err.println("Native code library failed to load. " + e);
System.exit(1);
@@ -6278,7 +6323,7 @@ Lastly the "jni", "jtype" and "jstype" typemaps are also required to specify
what Java types to use.
</p>
-<H3><a name="Java_expanding_java_object"></a>22.10.5 Expanding a Java object to multiple arguments</H3>
+<H3><a name="Java_expanding_java_object"></a>23.10.5 Expanding a Java object to multiple arguments</H3>
<p>
@@ -6360,7 +6405,7 @@ example.foo(new String[]{"red", "green", "blue", "white"});
</div>
-<H3><a name="Java_using_typemaps_return_arguments"></a>22.10.6 Using typemaps to return arguments</H3>
+<H3><a name="Java_using_typemaps_return_arguments"></a>23.10.6 Using typemaps to return arguments</H3>
<p>
@@ -6453,7 +6498,7 @@ public class runme {
static {
try {
-  System.loadLibrary("example");
+  System.loadLibrary("example");
} catch (UnsatisfiedLinkError e) {
System.err.println("Native code library failed to load. " + e);
System.exit(1);
@@ -6478,7 +6523,7 @@ $ java runme
1 12.0 340.0
</pre></div>
-<H3><a name="Java_adding_downcasts"></a>22.10.7 Adding Java downcasts to polymorphic return types</H3>
+<H3><a name="Java_adding_downcasts"></a>23.10.7 Adding Java downcasts to polymorphic return types</H3>
<p>
@@ -6684,7 +6729,7 @@ SWIG usually generates code which constructs the proxy classes using Java code a
Note that the JNI code above uses a number of string lookups to call a constructor, whereas this would not occur using byte compiled Java code.
</p>
-<H3><a name="Java_adding_equals_method"></a>22.10.8 Adding an equals method to the Java classes</H3>
+<H3><a name="Java_adding_equals_method"></a>23.10.8 Adding an equals method to the Java classes</H3>
<p>
@@ -6728,7 +6773,7 @@ System.out.println("foo1? " + foo1.equals(foo2));
</div>
-<H3><a name="Java_void_pointers"></a>22.10.9 Void pointers and a common Java base class</H3>
+<H3><a name="Java_void_pointers"></a>23.10.9 Void pointers and a common Java base class</H3>
<p>
@@ -6787,7 +6832,7 @@ This example contains some useful functionality which you may want in your code.
<li> It also has a function which effectively implements a cast from the type of the proxy/type wrapper class to a void pointer. This is necessary for passing a proxy class or a type wrapper class to a function that takes a void pointer.
</ul>
-<H3><a name="Java_struct_pointer_pointer"></a>22.10.10 Struct pointer to pointer</H3>
+<H3><a name="Java_struct_pointer_pointer"></a>23.10.10 Struct pointer to pointer</H3>
<p>
@@ -6967,7 +7012,7 @@ The C functional interface has been completely morphed into an object-oriented i
the Butler class would behave much like any pure Java class and feel more natural to Java users.
</p>
-<H3><a name="Java_memory_management_member_variables"></a>22.10.11 Memory management when returning references to member variables</H3>
+<H3><a name="Java_memory_management_member_variables"></a>23.10.11 Memory management when returning references to member variables</H3>
<p>
@@ -7090,7 +7135,7 @@ public class Bike {
Note the <tt>addReference</tt> call.
</p>
-<H3><a name="Java_memory_management_objects"></a>22.10.12 Memory management for objects passed to the C++ layer</H3>
+<H3><a name="Java_memory_management_objects"></a>23.10.12 Memory management for objects passed to the C++ layer</H3>
<p>
@@ -7206,7 +7251,7 @@ The 'javacode' typemap simply adds in the specified code into the Java proxy cla
</div>
-<H3><a name="Java_date_marshalling"></a>22.10.13 Date marshalling using the javain typemap and associated attributes</H3>
+<H3><a name="Java_date_marshalling"></a>23.10.13 Date marshalling using the javain typemap and associated attributes</H3>
<p>
@@ -7383,7 +7428,7 @@ A few things to note:
-<H2><a name="Java_directors_faq"></a>22.11 Living with Java Directors</H2>
+<H2><a name="Java_directors_faq"></a>23.11 Living with Java Directors</H2>
<p>
@@ -7564,10 +7609,10 @@ public abstract class UserVisibleFoo extends Foo {
</li>
</ol>
-<H2><a name="Java_odds_ends"></a>22.12 Odds and ends</H2>
+<H2><a name="Java_odds_ends"></a>23.12 Odds and ends</H2>
-<H3><a name="Java_javadoc_comments"></a>22.12.1 JavaDoc comments</H3>
+<H3><a name="Java_javadoc_comments"></a>23.12.1 JavaDoc comments</H3>
<p>
@@ -7623,7 +7668,7 @@ public class Barmy {
-<H3><a name="Java_functional_interface"></a>22.12.2 Functional interface without proxy classes</H3>
+<H3><a name="Java_functional_interface"></a>23.12.2 Functional interface without proxy classes</H3>
<p>
@@ -7684,7 +7729,7 @@ All destructors have to be called manually for example the <tt>delete_Foo(foo)</
</p>
-<H3><a name="Java_using_own_jni_functions"></a>22.12.3 Using your own JNI functions</H3>
+<H3><a name="Java_using_own_jni_functions"></a>23.12.3 Using your own JNI functions</H3>
<p>
@@ -7734,7 +7779,7 @@ This directive is only really useful if you want to mix your own hand crafted JN
</p>
-<H3><a name="Java_performance"></a>22.12.4 Performance concerns and hints</H3>
+<H3><a name="Java_performance"></a>23.12.4 Performance concerns and hints</H3>
<p>
@@ -7755,7 +7800,7 @@ However, you will have to be careful about memory management and make sure that
This method normally calls the C++ destructor or <tt>free()</tt> for C code.
</p>
-<H3><a name="Java_debugging"></a>22.12.5 Debugging</H3>
+<H3><a name="Java_debugging"></a>23.12.5 Debugging</H3>
<p>
@@ -7777,7 +7822,7 @@ The -verbose:jni and -verbose:gc are also useful options for monitoring code beh
</p>
-<H2><a name="Java_examples"></a>22.13 Examples</H2>
+<H2><a name="Java_examples"></a>23.13 Examples</H2>
<p>
View Lorry Controller Status