From 29275e3fc8ee300cdcd994e7b9e6ce9a2e59622f Mon Sep 17 00:00:00 2001 From: William S Fulton Date: Mon, 16 Jun 2003 22:33:14 +0000 Subject: [PATCH] maketoc update git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@4909 626c5289-ae23-0410-ae9c-e8d60b6d4f22 --- SWIG/Doc/Manual/Java.html | 283 +++++++++++++++++++------------------- 1 file changed, 145 insertions(+), 138 deletions(-) diff --git a/SWIG/Doc/Manual/Java.html b/SWIG/Doc/Manual/Java.html index 29d86501d..4a523e4f0 100644 --- a/SWIG/Doc/Manual/Java.html +++ b/SWIG/Doc/Manual/Java.html @@ -7,109 +7,113 @@

15 SWIG and Java

+
  • A tour of basic C/C++ wrapping -
  • Further details on the generated Java classes +
  • Further details on the generated Java classes -
  • Common customization features +
  • Common customization features -
  • Tips and techniques +
  • Tips and techniques -
  • Java typemaps +
  • Java typemaps -
  • Typemap Examples +
  • Typemap Examples -
  • Odds and ends +
  • Odds and ends -
  • Examples +
  • Examples + + This chapter describes SWIG's support of Java. It covers most SWIG features, but certain low-level details are covered in less depth than in earlier chapters.

    15.1 Overview

    + The 100% Pure Java effort is a commendable concept, however in the real world programmers often either need to re-use their existing code or in some situations want to take advantage of Java but are forced into using some native (C/C++) code. The Java extension to SWIG makes it very easy to plumb in existing C/C++ code for access from Java, as SWIG writes the Java Native Interface (JNI) code for you. @@ -137,7 +141,7 @@ SWIG is a powerful tool and the rest of the chapter details how the default code 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. -

    15.1 Preliminaries

    +

    15.2 Preliminaries

    SWIG 1.1 works with JDKs from JDK 1.1 to JDK1.4 (Java 2 SDK1.4) and should also work with any later versions. @@ -151,7 +155,8 @@ Run make -k check 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.

    -

    15.1.1 Running SWIG

    +

    15.2.1 Running SWIG

    + Suppose that you defined a SWIG module such as the following: @@ -188,7 +193,7 @@ The name of the wrapper file is derived from the name of the input file. For ex input file is example.i, the name of the wrapper file is example_wrap.c. To change this, you can use the -o option. -

    15.1.2 Additional Commandline Options

    +

    15.2.2 Additional Commandline Options

    The following table list the additional commandline options available for the Java module. They can also be seen by using: @@ -214,7 +219,7 @@ The following table list the additional commandline options available for the Ja
    Their use will become clearer by the time you have finished reading this section on SWIG and Java. -

    15.1.3 Getting the right header files

    +

    15.2.3 Getting the right header files

    In order to compile the C/C++ wrappers, the compiler needs the jni.h and jni_md.h header files which are part of the JDK. @@ -227,7 +232,7 @@ They are usually in directories like this:

    The exact location may vary on your machine, but the above locations are typical.

    -

    15.1.4 Compiling a dynamic module

    +

    15.2.4 Compiling a dynamic module

    The JNI code exists in a dynamic module or shared library (DLL on Windows) and gets loaded by the JVM. @@ -253,7 +258,7 @@ If the name of your SWIG module is "example", the name of the correspon The name of the module is specified using the %module directive or -module command line option.

    -

    15.1.5 Using your module

    +

    15.2.5 Using your module

    To load your shared native library module in Java, simply use Java's System.loadLibrary method in a Java class:

    @@ -283,7 +288,8 @@ $ If it doesn't work have a look at the following section which discusses problems loading the shared library. -

    15.9.3 Dynamic linking problems

    +

    15.2.6 Dynamic linking problems

    + As shown in the previous section the code to load a native library (shared library) is System.loadLibrary("name"). This can fail with an UnsatisfiedLinkError exception and can be due to a number of reasons. @@ -344,7 +350,8 @@ The SWIG Wiki also has The following section also contains some C++ specific linking problems and solutions. -

    15.1.6 Compilation problems and compiling with C++

    +

    15.2.7 Compilation problems and compiling with C++

    + On most machines, shared library files should be linked using the C++ compiler. For example: @@ -387,7 +394,7 @@ $ Finally make sure the version of JDK header files matches the version of Java that you are running as incompatibilities could lead to compilation problems or unpredictable behaviour. -

    15.2 Building on Windows

    +

    15.2.8 Building on Windows

    Building on Windows is roughly similar to the process used with Unix. @@ -395,7 +402,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.

    -

    15.2.1 Running SWIG from Visual Studio

    +

    15.2.8.1 Running SWIG from Visual Studio

    If you are developing your application within Microsoft Visual studio, SWIG can be invoked as a custom build option. @@ -426,7 +433,7 @@ The Java classes that SWIG output should also be compiled into .class files. To run the native code in the DLL (example.dll), make sure that it is in your path then run your Java program which uses it, as described in the previous section. If the library fails to load have a look at Dynamic linking problems. -

    15.2.2 Using NMAKE

    +

    15.2.8.2 Using NMAKE

    Alternatively, a Makefile for use by NMAKE can be written. @@ -484,7 +491,7 @@ Of course you may want to make changes for it to work for C++ by adding in the - -

    15.3 A tour of basic C/C++ wrapping

    +

    15.3 A tour of basic C/C++ wrapping

    By default, SWIG attempts to build a natural Java interface @@ -492,7 +499,7 @@ to your C/C++ code. Functions are wrapped as functions, classes are wrapped as variables are wrapped with JavaBean type getters and setters and so forth. This section briefly covers the essential aspects of this wrapping. -

    15.3.1 Modules, packages and generated Java classes

    +

    15.3.1 Modules, packages and generated Java classes

    The SWIG %module directive specifies the name of the Java @@ -513,7 +520,7 @@ or example_wrap.c. These C or C++ files complete the contents of the m The generated Java classes can be placed into a Java package by using the -package commandline option. -

    15.3.2 Functions

    +

    15.3.2 Functions

    There is no such thing as a global Java function so global C functions are wrapped as static methods in @@ -544,7 +551,7 @@ System.out.println(example.fact(4)); -

    15.3.3 Global variables

    +

    15.3.3 Global variables

    C/C++ global variables are fully supported by SWIG. @@ -615,7 +622,7 @@ extern char *path; // Read-only (due to %immutable) -

    15.3.4 Constants

    +

    15.3.4 Constants

    C/C++ constants are wrapped as Java static final variables. @@ -677,7 +684,7 @@ will be accessed using a getter as described in the previous section. They are not wrapped as constants. -

    15.3.5 Enumerations

    +

    15.3.5 Enumerations

    Enumerations are wrapped as final static integers in Java and are also initialised using a JNI call. For example: @@ -733,7 +740,7 @@ also telling the C compiler about it, the wrapper code won't compile.

    -

    15.3.6 Pointers

    +

    15.3.6 Pointers

    C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with @@ -821,7 +828,7 @@ What happens for various reasons is on big endian machines the pointer is stored As a result, care must be taken if you intend to manipulate the pointer directly from Java. -

    15.3.7 Structures

    +

    15.3.7 Structures

    If you wrap a C structure, it is wrapped by a Java class with getters and setters for access to the @@ -963,7 +970,7 @@ x.setA(3); // Modify x.a - this is the same as b.f.a -

    15.3.8 C++ classes

    +

    15.3.8 C++ classes

    C++ classes are wrapped by Java classes as well. For example, if you have this class, @@ -1017,7 +1024,7 @@ int bar = Spam.getBar(); -

    15.3.9 C++ inheritance

    +

    15.3.9 C++ inheritance

    SWIG is fully aware of issues related to C++ inheritance. Therefore, if you have @@ -1067,7 +1074,7 @@ then the Java function spam() accepts instances of Foo or inst Note that Java does not support multiple inheritance so any multiple inheritance in the C++ code is not going to work. A warning is given when multiple inheritance is detected and only the first base class is used. -

    15.3.10 Pointers, references, arrays and pass by value

    +

    15.3.10 Pointers, references, arrays and pass by value

    In C++, there are many different ways a function might receive @@ -1114,7 +1121,7 @@ Since the third function (spam7) returns a value, newly allocated memory is used 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). -

    15.3.10.1 Null pointers

    +

    15.3.10.1 Null pointers

    Working with null pointers is easy. @@ -1134,7 +1141,7 @@ example.spam4(null); // Array - ok For spam1 and spam4 above the Java null gets translated into a NULL pointer for passing to the C/C++ function. The converse also occurs, that is, NULL pointers are translated into null Java objects when returned from a C/C++ function. -

    15.3.11 C++ overloaded functions

    +

    15.3.11 C++ overloaded functions

    C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example, @@ -1231,7 +1238,7 @@ void spam(short); // Ignored

    -

    15.3.12 C++ namespaces

    +

    15.3.12 C++ namespaces

    SWIG is aware of C++ namespaces, but namespace names do not appear in @@ -1283,7 +1290,7 @@ If you have more than one namespace and your want to keep their symbols separate, consider wrapping them as separate SWIG modules. Each SWIG module can be placed into a separate package. -

    15.3.13 C++ templates

    +

    15.3.13 C++ templates

    C++ templates don't present a huge problem for SWIG. However, in order @@ -1326,7 +1333,7 @@ int second = p.getSecond(); Obviously, there is more to template wrapping than shown in this example. More details can be found in the SWIG and C++ chapter. -

    15.3.14 C++ Smart Pointers

    +

    15.3.14 C++ Smart Pointers

    In certain C++ programs, it is common to use classes that have been wrapped by @@ -1398,7 +1405,7 @@ Foo f = p.__deref__(); // Returns underlying Foo * -

    15.4 Further details on the generated Java classes

    +

    15.4 Further details on the generated Java classes

    In the previous section, a high-level view of Java wrapping was @@ -1410,7 +1417,7 @@ However, a number of low-level details were omitted. This section provides a br of how the proxy classes work and then covers the type wrapper classes. First, the crucial intermediary JNI class is considered. -

    15.4.1 The intermediary JNI class

    +

    15.4.1 The intermediary JNI class

    In the "SWIG basics" and "SWIG and C++" chapters, @@ -1504,7 +1511,7 @@ The module directive attribute jniclassname is used to achieve this: If name is the same as modulename then the module class name gets changed from modulename to modulenameModule. -

    15.4.1.1 The intermediary JNI class pragmas

    +

    15.4.1.1 The intermediary JNI class pragmas

    The intermediary JNI class can be tailored through the use of pragmas, but is not commonly done. The pragmas for this class are: @@ -1575,7 +1582,7 @@ For example, let's change the intermediary JNI class access attribute to public. All the methods in the intermediary JNI class will then be callable outside of the package as the method modifiers are public by default. -

    15.4.2 The Java module class

    +

    15.4.2 The Java module class

    All global functions and variable getters/setters appear in the module class. For our example, there is just one function: @@ -1600,7 +1607,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 Foo can be passed to the egg function, whereas any long can be passed to the egg function in the intermediary JNI class. -

    15.4.2.1 The Java module class pragmas

    +

    15.4.2.1 The Java module class pragmas

    The module class can be tailored through the use of pragmas, in the same manner as the intermediary JNI class. The pragmas are similarly named and are used in the same way. The complete list follows: @@ -1644,7 +1651,7 @@ The pragma code appears in the generated module class like this: -

    15.4.3 Java proxy classes

    +

    15.4.3 Java proxy classes

    A Java proxy class is generated for each structure, union or C++ class that is wrapped. @@ -1714,7 +1721,7 @@ int y = f.spam(5, new Foo()); -

    15.4.3.1 Memory management

    +

    15.4.3.1 Memory management

    Each proxy class has an ownership flag swigCMemOwn. The value of this @@ -1846,7 +1853,7 @@ Obj obj = Factory.createObj(); // obj.swigCMemOwn = true; -

    15.4.3.2 Inheritance

    +

    15.4.3.2 Inheritance

    Java proxy classes will mirror C++ inheritance chains. For example, given the base class Base and its derived class Derived: @@ -1951,7 +1958,7 @@ If Derived is provided by the C++ code, you could for example add in a There is a caveat and that is any C++ code will not know about your pure Java class Extended so this type of derivation is restricted.

    -

    15.4.3.3 Proxy classes and garbage collection

    +

    15.4.3.3 Proxy classes and garbage collection

    By default each proxy class has a delete() and a finalize() method. @@ -2022,7 +2029,7 @@ The section on Java typemaps details how to specify -

    15.4.4 Type wrapper classes

    +

    15.4.4 Type wrapper classes

    The generated type wrapper class, for say an int *, looks like this: @@ -2096,7 +2103,7 @@ public static void spam(SWIGTYPE_p_int x, SWIGTYPE_p_int y, int z) { ... }

    -

    15.5 Common customization features

    +

    15.5 Common customization features

    An earlier section presented the absolute basics of C/C++ wrapping. If you do nothing @@ -2106,7 +2113,7 @@ types of functionality might be missing or the interface to certain functions mi be awkward. This section describes some common SWIG features that are used to improve the interface to existing C/C++ code. -

    15.5.1 C/C++ helper functions

    +

    15.5.1 C/C++ helper functions

    Sometimes when you create a module, it is missing certain bits of functionality. For @@ -2164,7 +2171,7 @@ Admittedly, this is not the most elegant looking approach. However, it works an hard to implement. It is possible to improve on this using Java code, typemaps, and other customization features as covered in later sections, but sometimes helper functions are a quick and easy solution to difficult cases. -

    15.5.2 Class extension with %extend

    +

    15.5.2 Class extension with %extend

    One of the more interesting features of SWIG is that it can extend @@ -2218,7 +2225,7 @@ Vector(2,3,4) %extend works with both C and C++ code. It does not modify the underlying object in any way---the extensions only show up in the Java interface. -

    15.5.3 Exception handling with %exception

    +

    15.5.3 Exception handling with %exception

    If a C or C++ function throws an error, you may want to convert that error into a Java @@ -2317,7 +2324,7 @@ It is however possible to write JNI calls which will compile under both C and C+ The language-independent exception.i library file can also be used to raise exceptions. See the SWIG Library chapter. -

    15.5.4 Method access with %javamethodmodifiers

    +

    15.5.4 Method access with %javamethodmodifiers

    A Java feature called %javamethodmodifiers can be used to change the method modifiers from the default public. It applies to both module class methods and proxy class methods. For example: @@ -2339,7 +2346,7 @@ protected static void protect_me() { -

    15.6 Tips and techniques

    +

    15.6 Tips and techniques

    Although SWIG is largely automatic, there are certain types of wrapping problems that @@ -2347,7 +2354,7 @@ require additional user input. Examples include dealing with output parameter strings and arrays. This chapter discusses the common techniques for solving these problems. -

    15.6.1 Input and output parameters using primitive pointers and references

    +

    15.6.1 Input and output parameters using primitive pointers and references

    A common problem in some C programs is handling parameters passed as simple pointers or references. For @@ -2489,7 +2496,7 @@ void foo(Bar *OUTPUT); will not have the intended effect since typemaps.i does not define an OUTPUT rule for Bar. -

    15.6.2 Simple pointers

    +

    15.6.2 Simple pointers

    If you must work with simple pointers such as int * or double * another approach to using @@ -2542,7 +2549,7 @@ System.out.println("3 + 4 = " + result); See the SWIG Library chapter for further details. -

    15.6.3 Wrapping C arrays with Java arrays

    +

    15.6.3 Wrapping C arrays with Java arrays

    SWIG can wrap arrays in a more natural Java manner than the default by using the arrays_java.i library file. @@ -2599,7 +2606,7 @@ When arrays are used in functions like populate, the size of the C arra Please be aware that the typemaps in this library are not efficient as all the elements are copied from the Java array to a C array whenever the array is passed to and from JNI code. There is an alternative approach using the SWIG array library and this is covered in the next. -

    15.6.4 Unbounded C Arrays

    +

    15.6.4 Unbounded C Arrays

    Sometimes a C function expects an array to be passed as a pointer. For example, @@ -2725,7 +2732,7 @@ well suited for applications in which you need to create buffers, package binary data, etc. -

    15.7 Java typemaps

    +

    15.7 Java typemaps

    This section describes how you can modify SWIG's default wrapping behavior @@ -2745,7 +2752,7 @@ 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. -

    15.7.1 Default primitive type mappings

    +

    15.7.1 Default primitive type mappings

    The following table lists the default type mapping from Java to C/C++.

    @@ -2876,7 +2883,7 @@ There is no perfect mapping between Java and C as Java doesn't support all the u However, the mappings allow the full range of values for each C type from Java.

    -

    15.7.2 Sixty four bit JVMs

    +

    15.7.2 Sixty four bit JVMs

    If you are using a 64 bit JVM you may have to override the C long, but probably not C int default mappings. @@ -2887,7 +2894,7 @@ Note that the Java write once run anywhere philosophy holds true for all pure Ja Unfortunately it won't of course hold true for JNI code. -

    15.7.3 What is a typemap?

    +

    15.7.3 What is a typemap?

    A typemap is nothing more than a code generation rule that is attached to @@ -2987,7 +2994,7 @@ int c = example.count('e',"Hello World"); -

    15.7.4 Typemaps for mapping C/C++ types to Java types

    +

    15.7.4 Typemaps for mapping C/C++ types to Java types

    The typemaps available to the Java module include the common typemaps listed in the main typemaps section. @@ -3164,7 +3171,7 @@ These are listed below: -

    15.7.5 Java special variables

    +

    15.7.5 Java special variables

    The standard SWIG special variables are available for use within typemaps as described in the Typemaps documentation, for example $1, $input,$result etc. @@ -3264,7 +3271,7 @@ public static Class bar(Class cls, int ush) { -

    15.7.6 Typemaps for both C and C++ compilation

    +

    15.7.6 Typemaps for both C and C++ compilation

    JNI calls must be written differently depending on whether the code is being compiled as C or C++. @@ -3293,7 +3300,7 @@ The C calling convention is emitted by default and the C++ calling convention is If you do not intend your code to be targeting both C and C++ then your typemaps can use the appropriate JNI calling convention and need not use the JCALLx macros.

    -

    15.7.7 Java code typemaps

    +

    15.7.7 Java code typemaps

    Most of SWIG's typemaps are used for the generation of C/C++ code. The typemaps in this section are used solely for the generation of Java code. Elements of proxy classes and type wrapper classes come from the following typemaps (the defaults). @@ -3411,7 +3418,7 @@ Note that SWIGTYPE will target all proxy classes, but not all type wrap

    -

    15.8 Typemap Examples

    +

    15.8 Typemap Examples

    This section includes a few examples of typemaps. For more examples, you @@ -3419,7 +3426,7 @@ might look at the files "java.swg" and "typemaps.i" in the SWIG library. -

    15.8.1 Converting Java String arrays to char **

    +

    15.8.1 Converting Java String arrays to char **

    A common problem in many C programs is the processing of command line arguments, which are usually passed in an array of NULL terminated strings. @@ -3551,7 +3558,7 @@ the C function. The "out" typemap is used for function return values. Lastly the "jni", "jtype" and "jstype" typemaps are also required to specify what Java types to use. -

    15.8.2 Expanding a Java object to multiple arguments

    +

    15.8.2 Expanding a Java object to multiple arguments

    Suppose that you had a collection of C functions with arguments @@ -3624,7 +3631,7 @@ example.foo(new String[]{"red", "green", "blue", "white"}); -

    15.8.3 Using typemaps to return arguments

    +

    15.8.3 Using typemaps to return arguments

    A common problem in some C programs is that values may be returned in function parameters rather than in the return value of a function. @@ -3724,7 +3731,7 @@ $ java main 1 12.0 340.0 -

    15.8.4 Adding Java downcasts to polymorphic return types

    +

    15.8.4 Adding Java downcasts to polymorphic return types

    SWIG support for polymorphism works in that the appropriate virtual function is called. However, the default generated code does not allow for downcasting. @@ -3904,7 +3911,7 @@ There are other solutions to this problem, but this last example demonstrates so SWIG usually generates code which constructs the proxy classes using Java code as it is easier to handle error conditions and is faster. 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. -

    15.8.5 Adding an equals method to the Java classes

    +

    15.8.5 Adding an equals method to the Java classes

    When a pointer is returned from a JNI function, it is wrapped using a new Java proxy class or type wrapper class. @@ -3939,7 +3946,7 @@ System.out.println("foo1? " + foo1.equals(foo2)); -

    15.8.6 Void pointers and a common Java base class

    +

    15.8.6 Void pointers and a common Java base class

    One might wonder why the common code that SWIG emits for the proxy and type wrapper classes is not pushed into a base class. @@ -3992,10 +3999,10 @@ This example contains some useful functionality which you may want in your code. -

    15.9 Odds and ends

    +

    15.9 Odds and ends

    -

    15.9.1 JavaDoc comments

    +

    15.9.1 JavaDoc comments

    The SWIG documentation system is currently deprecated. @@ -4046,7 +4053,7 @@ public class Barmy { -

    15.9.2 Functional interface without proxy classes

    +

    15.9.2 Functional interface without proxy classes

    It is possible to run SWIG in a mode that does not produce proxy classes by using the -noproxy commandline option. @@ -4097,7 +4104,7 @@ Unlike proxy classes, there is no attempt at tracking memory. All destructors have to be called manually for example the delete_Foo(foo) call above. -

    15.9.4 Using your own JNI functions

    +

    15.9.3 Using your own JNI functions

    You may have some hand written JNI functions that you want to use in addition to the SWIG generated JNI functions. @@ -4137,7 +4144,7 @@ In summary the %native directive is telling SWIG to generate the Java c This directive is only really useful if you want to mix your own hand crafted JNI code and the SWIG generated code into one Java class or package. -

    15.9.5 Performance concerns and hints

    +

    15.9.4 Performance concerns and hints

    If you're directly manipulating huge arrays of complex objects from Java, performance may suffer greatly when using the array functions in arrays_java.i. @@ -4155,7 +4162,7 @@ This method calls the C++ destructor or free() for C code. -

    15.10 Examples

    +

    15.10 Examples

    The directory Examples/java has a number of further examples. @@ -4165,4 +4172,4 @@ If your SWIG installation went well Unix users should be able to type makeWindows Examples. - + \ No newline at end of file