+++ /dev/null
-<!DOCTYPE article PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
-<article>
-<artheader>
-<title>The Cygnus Native Interface for C++/Java Integration</title>
-<subtitle>Writing native Java methods in natural C++</subtitle>
-<authorgroup>
-<corpauthor>Cygnus Solutions</corpauthor>
-</authorgroup>
-<date>March, 2000</date>
-</artheader>
-
-<abstract><para>
-This documents CNI, the Cygnus Native Interface,
-which is is a convenient way to write Java native methods using C++.
-This is a more efficient, more convenient, but less portable
-alternative to the standard JNI (Java Native Interface).</para>
-</abstract>
-
-<sect1><title>Basic Concepts</title>
-<para>
-In terms of languages features, Java is mostly a subset
-of C++. Java has a few important extensions, plus a powerful standard
-class library, but on the whole that does not change the basic similarity.
-Java is a hybrid object-oriented language, with a few native types,
-in addition to class types. It is class-based, where a class may have
-static as well as per-object fields, and static as well as instance methods.
-Non-static methods may be virtual, and may be overloaded. Overloading is
-resolved at compile time by matching the actual argument types against
-the parameter types. Virtual methods are implemented using indirect calls
-through a dispatch table (virtual function table). Objects are
-allocated on the heap, and initialized using a constructor method.
-Classes are organized in a package hierarchy.
-</para>
-<para>
-All of the listed attributes are also true of C++, though C++ has
-extra features (for example in C++ objects may be allocated not just
-on the heap, but also statically or in a local stack frame). Because
-<acronym>gcj</acronym> uses the same compiler technology as
-<acronym>g++</acronym> (the GNU C++ compiler), it is possible
-to make the intersection of the two languages use the same
-<acronym>ABI</acronym> (object representation and calling conventions).
-The key idea in <acronym>CNI</acronym> is that Java objects are C++ objects,
-and all Java classes are C++ classes (but not the other way around).
-So the most important task in integrating Java and C++ is to
-remove gratuitous incompatibilities.
-</para>
-<para>
-You write CNI code as a regular C++ source file. (You do have to use
-a Java/CNI-aware C++ compiler, specifically a recent version of G++.)</para>
-<para>
-You start with:
-<programlisting>
-#include <gcj/cni.h>
-</programlisting></para>
-
-<para>
-You then include header files for the various Java classes you need
-to use:
-<programlisting>
-#include <java/lang/Character.h>
-#include <java/util/Date.h>
-#include <java/lang/IndexOutOfBoundsException.h>
-</programlisting></para>
-
-<para>
-In general, <acronym>CNI</acronym> functions and macros start with the
-`<literal>Jv</literal>' prefix, for example the function
-`<literal>JvNewObjectArray</literal>'. This convention is used to
-avoid conflicts with other libraries.
-Internal functions in <acronym>CNI</acronym> start with the prefix
-`<literal>_Jv_</literal>'. You should not call these;
-if you find a need to, let us know and we will try to come up with an
-alternate solution. (This manual lists <literal>_Jv_AllocBytes</literal>
-as an example; <acronym>CNI</acronym> should instead provide
-a <literal>JvAllocBytes</literal> function.)</para>
-<para>
-These header files are automatically generated by <command>gcjh</command>.
-</para>
-</sect1>
-
-<sect1><title>Packages</title>
-<para>
-The only global names in Java are class names, and packages.
-A <firstterm>package</firstterm> can contain zero or more classes, and
-also zero or more sub-packages.
-Every class belongs to either an unnamed package or a package that
-has a hierarchical and globally unique name.
-</para>
-<para>
-A Java package is mapped to a C++ <firstterm>namespace</firstterm>.
-The Java class <literal>java.lang.String</literal>
-is in the package <literal>java.lang</literal>, which is a sub-package
-of <literal>java</literal>. The C++ equivalent is the
-class <literal>java::lang::String</literal>,
-which is in the namespace <literal>java::lang</literal>,
-which is in the namespace <literal>java</literal>.
-</para>
-<para>
-Here is how you could express this:
-<programlisting>
-// Declare the class(es), possibly in a header file:
-namespace java {
- namespace lang {
- class Object;
- class String;
- ...
- }
-}
-
-class java::lang::String : public java::lang::Object
-{
- ...
-};
-</programlisting>
-</para>
-<para>
-The <literal>gcjh</literal> tool automatically generates the
-nessary namespace declarations.</para>
-
-<sect2><title>Nested classes as a substitute for namespaces</title>
-<para>
-<!-- FIXME the next line reads poorly jsm -->
-It is not that long since g++ got complete namespace support,
-and it was very recent (end of February 1999) that <literal>libgcj</literal>
-was changed to uses namespaces. Releases before then used
-nested classes, which are the C++ equivalent of Java inner classes.
-They provide similar (though less convenient) functionality.
-The old syntax is:
-<programlisting>
-class java {
- class lang {
- class Object;
- class String;
- };
-};
-</programlisting>
-The obvious difference is the use of <literal>class</literal> instead
-of <literal>namespace</literal>. The more important difference is
-that all the members of a nested class have to be declared inside
-the parent class definition, while namespaces can be defined in
-multiple places in the source. This is more convenient, since it
-corresponds more closely to how Java packages are defined.
-The main difference is in the declarations; the syntax for
-using a nested class is the same as with namespaces:
-<programlisting>
-class java::lang::String : public java::lang::Object
-{ ... }
-</programlisting>
-Note that the generated code (including name mangling)
-using nested classes is the same as that using namespaces.</para>
-</sect2>
-
-<sect2><title>Leaving out package names</title>
-<para>
-<!-- FIXME next line reads poorly jsm -->
-Having to always type the fully-qualified class name is verbose.
-It also makes it more difficult to change the package containing a class.
-The Java <literal>package</literal> declaration specifies that the
-following class declarations are in the named package, without having
-to explicitly name the full package qualifiers.
-The <literal>package</literal> declaration can be followed by zero or
-more <literal>import</literal> declarations, which allows either
-a single class or all the classes in a package to be named by a simple
-identifier. C++ provides something similar
-with the <literal>using</literal> declaration and directive.
-</para>
-<para>
-A Java simple-type-import declaration:
-<programlisting>
-import <replaceable>PackageName</replaceable>.<replaceable>TypeName</replaceable>;
-</programlisting>
-allows using <replaceable>TypeName</replaceable> as a shorthand for
-<literal><replaceable>PackageName</replaceable>.<replaceable>TypeName</replaceable></literal>.
-The C++ (more-or-less) equivalent is a <literal>using</literal>-declaration:
-<programlisting>
-using <replaceable>PackageName</replaceable>::<replaceable>TypeName</replaceable>;
-</programlisting>
-</para>
-<para>
-A Java import-on-demand declaration:
-<programlisting>
-import <replaceable>PackageName</replaceable>.*;
-</programlisting>
-allows using <replaceable>TypeName</replaceable> as a shorthand for
-<literal><replaceable>PackageName</replaceable>.<replaceable>TypeName</replaceable></literal>
-The C++ (more-or-less) equivalent is a <literal>using</literal>-directive:
-<programlisting>
-using namespace <replaceable>PackageName</replaceable>;
-</programlisting>
-</para>
-</sect2>
-</sect1>
-
-<sect1><title>Primitive types</title>
-<para>
-Java provides 8 <quote>primitives</quote> types:
-<literal>byte</literal>, <literal>short</literal>, <literal>int</literal>,
-<literal>long</literal>, <literal>float</literal>, <literal>double</literal>,
-<literal>char</literal>, and <literal>boolean</literal>.
-These are the same as the following C++ <literal>typedef</literal>s
-(which are defined by <literal>gcj/cni.h</literal>):
-<literal>jbyte</literal>, <literal>jshort</literal>, <literal>jint</literal>,
-<literal>jlong</literal>, <literal>jfloat</literal>,
-<literal>jdouble</literal>,
-<literal>jchar</literal>, and <literal>jboolean</literal>.
-You should use the C++ typenames
-(<ForeignPhrase><Abbrev>e.g.</Abbrev></ForeignPhrase> <literal>jint</literal>),
-and not the Java types names
-(<ForeignPhrase><Abbrev>e.g.</Abbrev></ForeignPhrase> <literal>int</literal>),
-even if they are <quote>the same</quote>.
-This is because there is no guarantee that the C++ type
-<literal>int</literal> is a 32-bit type, but <literal>jint</literal>
-<emphasis>is</emphasis> guaranteed to be a 32-bit type.
-
-<informaltable frame="all" colsep="1" rowsep="0">
-<tgroup cols="3">
-<thead>
-<row>
-<entry>Java type</entry>
-<entry>C/C++ typename</entry>
-<entry>Description</entry>
-</thead>
-<tbody>
-<row>
-<entry>byte</entry>
-<entry>jbyte</entry>
-<entry>8-bit signed integer</entry>
-</row>
-<row>
-<entry>short</entry>
-<entry>jshort</entry>
-<entry>16-bit signed integer</entry>
-</row>
-<row>
-<entry>int</entry>
-<entry>jint</entry>
-<entry>32-bit signed integer</entry>
-</row>
-<row>
-<entry>long</entry>
-<entry>jlong</entry>
-<entry>64-bit signed integer</entry>
-</row>
-<row>
-<entry>float</entry>
-<entry>jfloat</entry>
-<entry>32-bit IEEE floating-point number</entry>
-</row>
-<row>
-<entry>double</entry>
-<entry>jdouble</entry>
-<entry>64-bit IEEE floating-point number</entry>
-</row>
-<row>
-<entry>char</entry>
-<entry>jchar</entry>
-<entry>16-bit Unicode character</entry>
-</row>
-<row>
-<entry>boolean</entry>
-<entry>jboolean</entry>
-<entry>logical (Boolean) values</entry>
-</row>
-<row>
-<entry>void</entry>
-<entry>void</entry>
-<entry>no value</entry>
-</row>
-</tbody></tgroup>
-</informaltable>
-</para>
-
-<para>
-<funcsynopsis>
-<funcdef><function>JvPrimClass</function></funcdef>
-<paramdef><parameter>primtype</parameter></paramdef>
-</funcsynopsis>
-This is a macro whose argument should be the name of a primitive
-type, <ForeignPhrase><Abbrev>e.g.</Abbrev></ForeignPhrase>
-<literal>byte</literal>.
-The macro expands to a pointer to the <literal>Class</literal> object
-corresponding to the primitive type.
-<ForeignPhrase><Abbrev>E.g.</Abbrev></ForeignPhrase>,
-<literal>JvPrimClass(void)</literal>
-has the same value as the Java expression
-<literal>Void.TYPE</literal> (or <literal>void.class</literal>).
-</para>
-
-</sect1>
-
-<sect1><title>Objects and Classes</title>
-<sect2><title>Classes</title>
-<para>
-All Java classes are derived from <literal>java.lang.Object</literal>.
-C++ does not have a unique <quote>root</quote>class, but we use
-a C++ <literal>java::lang::Object</literal> as the C++ version
-of the <literal>java.lang.Object</literal> Java class. All
-other Java classes are mapped into corresponding C++ classes
-derived from <literal>java::lang::Object</literal>.</para>
-<para>
-Interface inheritance (the <quote><literal>implements</literal></quote>
-keyword) is currently not reflected in the C++ mapping.</para>
-</sect2>
-<sect2><title>Object references</title>
-<para>
-We implement a Java object reference as a pointer to the start
-of the referenced object. It maps to a C++ pointer.
-(We cannot use C++ references for Java references, since
-once a C++ reference has been initialized, you cannot change it to
-point to another object.)
-The <literal>null</literal> Java reference maps to the <literal>NULL</literal>
-C++ pointer.
-</para>
-<para>
-Note that in some Java implementations an object reference is implemented as
-a pointer to a two-word <quote>handle</quote>. One word of the handle
-points to the fields of the object, while the other points
-to a method table. Gcj does not use this extra indirection.
-</para>
-</sect2>
-<sect2><title>Object fields</title>
-<para>
-Each object contains an object header, followed by the instance
-fields of the class, in order. The object header consists of
-a single pointer to a dispatch or virtual function table.
-(There may be extra fields <quote>in front of</quote> the object,
-for example for
-memory management, but this is invisible to the application, and
-the reference to the object points to the dispatch table pointer.)
-</para>
-<para>
-The fields are laid out in the same order, alignment, and size
-as in C++. Specifically, 8-bite and 16-bit native types
-(<literal>byte</literal>, <literal>short</literal>, <literal>char</literal>,
-and <literal>boolean</literal>) are <emphasis>not</emphasis>
-widened to 32 bits.
-Note that the Java VM does extend 8-bit and 16-bit types to 32 bits
-when on the VM stack or temporary registers.</para>
-<para>
-If you include the <literal>gcjh</literal>-generated header for a
-class, you can access fields of Java classes in the <quote>natural</quote>
-way. Given the following Java class:
-<programlisting>
-public class Int
-{
- public int i;
- public Integer (int i) { this.i = i; }
- public static zero = new Integer(0);
-}
-</programlisting>
-you can write:
-<programlisting>
-#include <gcj/cni.h>
-#include <Int.h>
-Int*
-mult (Int *p, jint k)
-{
- if (k == 0)
- return Int::zero; // static member access.
- return new Int(p->i * k);
-}
-</programlisting>
-</para>
-<para>
-<acronym>CNI</acronym> does not strictly enforce the Java access
-specifiers, because Java permissions cannot be directly mapped
-into C++ permission. Private Java fields and methods are mapped
-to private C++ fields and methods, but other fields and methods
-are mapped to public fields and methods.
-</para>
-</sect2>
-</sect1>
-
-<sect1><title>Arrays</title>
-<para>
-While in many ways Java is similar to C and C++,
-it is quite different in its treatment of arrays.
-C arrays are based on the idea of pointer arithmetic,
-which would be incompatible with Java's security requirements.
-Java arrays are true objects (array types inherit from
-<literal>java.lang.Object</literal>). An array-valued variable
-is one that contains a reference (pointer) to an array object.
-</para>
-<para>
-Referencing a Java array in C++ code is done using the
-<literal>JArray</literal> template, which as defined as follows:
-<programlisting>
-class __JArray : public java::lang::Object
-{
-public:
- int length;
-};
-
-template<class T>
-class JArray : public __JArray
-{
- T data[0];
-public:
- T& operator[](jint i) { return data[i]; }
-};
-</programlisting></para>
-<para>
-<funcsynopsis>
- <funcdef>template<class T> T *<function>elements</function></funcdef>
- <paramdef>JArray<T> &<parameter>array</parameter></paramdef>
-</funcsynopsis>
- This template function can be used to get a pointer to the
- elements of the <parameter>array</parameter>.
- For instance, you can fetch a pointer
- to the integers that make up an <literal>int[]</literal> like so:
-<programlisting>
-extern jintArray foo;
-jint *intp = elements (foo);
-</programlisting>
-The name of this function may change in the future.</para>
-<para>
-There are a number of typedefs which correspond to typedefs from JNI.
-Each is the type of an array holding objects of the appropriate type:
-<programlisting>
-typedef __JArray *jarray;
-typedef JArray<jobject> *jobjectArray;
-typedef JArray<jboolean> *jbooleanArray;
-typedef JArray<jbyte> *jbyteArray;
-typedef JArray<jchar> *jcharArray;
-typedef JArray<jshort> *jshortArray;
-typedef JArray<jint> *jintArray;
-typedef JArray<jlong> *jlongArray;
-typedef JArray<jfloat> *jfloatArray;
-typedef JArray<jdouble> *jdoubleArray;
-</programlisting>
-</para>
-<para>
- You can create an array of objects using this function:
-<funcsynopsis>
- <funcdef>jobjectArray <function>JvNewObjectArray</function></funcdef>
- <paramdef>jint <parameter>length</parameter></paramdef>
- <paramdef>jclass <parameter>klass</parameter></paramdef>
- <paramdef>jobject <parameter>init</parameter></paramdef>
- </funcsynopsis>
- Here <parameter>klass</parameter> is the type of elements of the array;
- <parameter>init</parameter> is the initial
- value to be put into every slot in the array.
-</para>
-<para>
-For each primitive type there is a function which can be used
- to create a new array holding that type. The name of the function
- is of the form
- `<literal>JvNew<<replaceable>Type</replaceable>>Array</literal>',
- where `<<replaceable>Type</replaceable>>' is the name of
- the primitive type, with its initial letter in upper-case. For
- instance, `<literal>JvNewBooleanArray</literal>' can be used to create
- a new array of booleans.
- Each such function follows this example:
-<funcsynopsis>
- <funcdef>jbooleanArray <function>JvNewBooleanArray</function></funcdef>
- <paramdef>jint <parameter>length</parameter></paramdef>
-</funcsynopsis>
-</para>
-<para>
-<funcsynopsis>
- <funcdef>jsize <function>JvGetArrayLength</function></funcdef>
- <paramdef>jarray <parameter>array</parameter></paramdef>
- </funcsynopsis>
- Returns the length of <parameter>array</parameter>.</para>
-</sect1>
-
-<sect1><title>Methods</title>
-
-<para>
-Java methods are mapped directly into C++ methods.
-The header files generated by <literal>gcjh</literal>
-include the appropriate method definitions.
-Basically, the generated methods have the same names and
-<quote>corresponding</quote> types as the Java methods,
-and are called in the natural manner.</para>
-
-<sect2><title>Overloading</title>
-<para>
-Both Java and C++ provide method overloading, where multiple
-methods in a class have the same name, and the correct one is chosen
-(at compile time) depending on the argument types.
-The rules for choosing the correct method are (as expected) more complicated
-in C++ than in Java, but given a set of overloaded methods
-generated by <literal>gcjh</literal> the C++ compiler will choose
-the expected one.</para>
-<para>
-Common assemblers and linkers are not aware of C++ overloading,
-so the standard implementation strategy is to encode the
-parameter types of a method into its assembly-level name.
-This encoding is called <firstterm>mangling</firstterm>,
-and the encoded name is the <firstterm>mangled name</firstterm>.
-The same mechanism is used to implement Java overloading.
-For C++/Java interoperability, it is important that both the Java
-and C++ compilers use the <emphasis>same</emphasis> encoding scheme.
-</para>
-</sect2>
-
-<sect2><title>Static methods</title>
-<para>
-Static Java methods are invoked in <acronym>CNI</acronym> using the standard
-C++ syntax, using the `<literal>::</literal>' operator rather
-than the `<literal>.</literal>' operator. For example:
-</para>
-<programlisting>
-jint i = java::lang::Math::round((jfloat) 2.3);
-</programlisting>
-<para>
-<!-- FIXME this next sentence seems ungammatical jsm -->
-Defining a static native method uses standard C++ method
-definition syntax. For example:
-<programlisting>
-#include <java/lang/Integer.h>
-java::lang::Integer*
-java::lang::Integer::getInteger(jstring str)
-{
- ...
-}
-</programlisting>
-</sect2>
-
-<sect2><title>Object Constructors</title>
-<para>
-Constructors are called implicitly as part of object allocation
-using the <literal>new</literal> operator. For example:
-<programlisting>
-java::lang::Int x = new java::lang::Int(234);
-</programlisting>
-</para>
-<para>
-<!-- FIXME rewrite needed here, mine may not be good jsm -->
-Java does not allow a constructor to be a native method.
-Instead, you could define a private method which
-you can have the constructor call.
-</para>
-</sect2>
-
-<sect2><title>Instance methods</title>
-<para>
-<!-- FIXME next para week, I would remove a few words from some sentences jsm -->
-Virtual method dispatch is handled essentially the same way
-in C++ and Java -- <abbrev>i.e.</abbrev> by doing an
-indirect call through a function pointer stored in a per-class virtual
-function table. C++ is more complicated because it has to support
-multiple inheritance, but this does not effect Java classes.
-However, G++ has historically used a different calling convention
-that is not compatible with the one used by <acronym>gcj</acronym>.
-During 1999, G++ will switch to a new ABI that is compatible with
-<acronym>gcj</acronym>. Some platforms (including Linux) have already
-changed. On other platforms, you will have to pass
-the <literal>-fvtable-thunks</literal> flag to g++ when
-compiling <acronym>CNI</acronym> code. Note that you must also compile
-your C++ source code with <literal>-fno-rtti</literal>.
-</para>
-<para>
-Calling a Java instance method in <acronym>CNI</acronym> is done
-using the standard C++ syntax. For example:
-<programlisting>
- java::lang::Number *x;
- if (x->doubleValue() > 0.0) ...
-</programlisting>
-</para>
-<para>
-Defining a Java native instance method is also done the natural way:
-<programlisting>
-#include <java/lang/Integer.h>
-jdouble
-java::lang:Integer::doubleValue()
-{
- return (jdouble) value;
-}
-</programlisting>
-</para>
-</sect2>
-
-<sect2><title>Interface method calls</title>
-<para>
-In Java you can call a method using an interface reference.
-This is not yet supported in <acronym>CNI</acronym>.</para>
-</sect2>
-</sect1>
-
-<sect1><title>Object allocation</title>
-
-<para>
-New Java objects are allocated using a
-<firstterm>class-instance-creation-expression</firstterm>:
-<programlisting>
-new <replaceable>Type</replaceable> ( <replaceable>arguments</replaceable> )
-</programlisting>
-The same syntax is used in C++. The main difference is that
-C++ objects have to be explicitly deleted; in Java they are
-automatically deleted by the garbage collector.
-Using <acronym>CNI</acronym>, you can allocate a new object
-using standard C++ syntax. The C++ compiler is smart enough to
-realize the class is a Java class, and hence it needs to allocate
-memory from the garbage collector. If you have overloaded
-constructors, the compiler will choose the correct one
-using standard C++ overload resolution rules. For example:
-<programlisting>
-java::util::Hashtable *ht = new java::util::Hashtable(120);
-</programlisting>
-</para>
-<para>
-<funcsynopsis>
- <funcdef>void *<function>_Jv_AllocBytes</function></funcdef>
- <paramdef>jsize <parameter>size</parameter></paramdef>
-</funcsynopsis>
- Allocate <parameter>size</parameter> bytes. This memory is not
- scanned by the garbage collector. However, it will be freed by
-the GC if no references to it are discovered.
-</para>
-</sect1>
-
-<sect1><title>Interfaces</title>
-<para>
-A Java class can <firstterm>implement</firstterm> zero or more
-<firstterm>interfaces</firstterm>, in addition to inheriting from
-a single base class.
-An interface is a collection of constants and method specifications;
-it is similar to the <firstterm>signatures</firstterm> available
-as a G++ extension. An interface provides a subset of the
-functionality of C++ abstract virtual base classes, but they
-are currently implemented differently.
-CNI does not currently provide any support for interfaces,
-or calling methods from an interface pointer.
-This is partly because we are planning to re-do how
-interfaces are implemented in <acronym>gcj</acronym>.
-</para>
-</sect1>
-
-<sect1><title>Strings</title>
-<para>
-<acronym>CNI</acronym> provides a number of utility functions for
-working with Java <literal>String</literal> objects.
-The names and interfaces are analogous to those of <acronym>JNI</acronym>.
-</para>
-
-<para>
-<funcsynopsis>
- <funcdef>jstring <function>JvNewString</function></funcdef>
- <paramdef>const jchar *<parameter>chars</parameter></paramdef>
- <paramdef>jsize <parameter>len</parameter></paramdef>
- </funcsynopsis>
- Creates a new Java String object, where
- <parameter>chars</parameter> are the contents, and
- <parameter>len</parameter> is the number of characters.
-</para>
-
-<para>
-<funcsynopsis>
- <funcdef>jstring <function>JvNewStringLatin1</function></funcdef>
- <paramdef>const char *<parameter>bytes</parameter></paramdef>
- <paramdef>jsize <parameter>len</parameter></paramdef>
- </funcsynopsis>
- Creates a new Java String object, where <parameter>bytes</parameter>
- are the Latin-1 encoded
- characters, and <parameter>len</parameter> is the length of
- <parameter>bytes</parameter>, in bytes.
-</para>
-
-<para>
-<funcsynopsis>
- <funcdef>jstring <function>JvNewStringLatin1</function></funcdef>
- <paramdef>const char *<parameter>bytes</parameter></paramdef>
- </funcsynopsis>
- Like the first JvNewStringLatin1, but computes <parameter>len</parameter>
- using <literal>strlen</literal>.
-</para>
-
-<para>
-<funcsynopsis>
- <funcdef>jstring <function>JvNewStringUTF</function></funcdef>
- <paramdef>const char *<parameter>bytes</parameter></paramdef>
- </funcsynopsis>
- Creates a new Java String object, where <parameter>bytes</parameter> are
- the UTF-8 encoded characters of the string, terminated by a null byte.
-</para>
-
-<para>
-<funcsynopsis>
- <funcdef>jchar *<function>JvGetStringChars</function></funcdef>
- <paramdef>jstring <parameter>str</parameter></paramdef>
- </funcsynopsis>
- Returns a pointer to the array of characters which make up a string.
-</para>
-
-<para>
-<funcsynopsis>
- <funcdef> int <function>JvGetStringUTFLength</function></funcdef>
- <paramdef>jstring <parameter>str</parameter></paramdef>
- </funcsynopsis>
- Returns number of bytes required to encode contents
- of <parameter>str</parameter> as UTF-8.
-</para>
-
-<para>
-<funcsynopsis>
- <funcdef> jsize <function>JvGetStringUTFRegion</function></funcdef>
- <paramdef>jstring <parameter>str</parameter></paramdef>
- <paramdef>jsize <parameter>start</parameter></paramdef>
- <paramdef>jsize <parameter>len</parameter></paramdef>
- <paramdef>char *<parameter>buf</parameter></paramdef>
- </funcsynopsis>
- This puts the UTF-8 encoding of a region of the
- string <parameter>str</parameter> into
- the buffer <parameter>buf</parameter>.
- The region of the string to fetch is specifued by
- <parameter>start</parameter> and <parameter>len</parameter>.
- It is assumed that <parameter>buf</parameter> is big enough
- to hold the result. Note
- that <parameter>buf</parameter> is <emphasis>not</emphasis> null-terminated.
-</para>
-</sect1>
-
-<sect1><title>Class Initialization</title>
-<para>
-Java requires that each class be automatically initialized at the time
-of the first active use. Initializing a class involves
-initializing the static fields, running code in class initializer
-methods, and initializing base classes. There may also be
-some implementation specific actions, such as allocating
-<classname>String</classname> objects corresponding to string literals in
-the code.</para>
-<para>
-The Gcj compiler inserts calls to <literal>JvInitClass</literal> (actually
-<literal>_Jv_InitClass</literal>) at appropriate places to ensure that a
-class is initialized when required. The C++ compiler does not
-insert these calls automatically - it is the programmer's
-responsibility to make sure classes are initialized. However,
-this is fairly painless because of the conventions assumed by the Java
-system.</para>
-<para>
-First, <literal>libgcj</literal> will make sure a class is initialized
-before an instance of that object is created. This is one
-of the responsibilities of the <literal>new</literal> operation. This is
-taken care of both in Java code, and in C++ code. (When the G++
-compiler sees a <literal>new</literal> of a Java class, it will call
-a routine in <literal>libgcj</literal> to allocate the object, and that
-routine will take care of initializing the class.) It follows that you can
-access an instance field, or call an instance (non-static)
-method and be safe in the knowledge that the class and all
-of its base classes have been initialized.</para>
-<para>
-Invoking a static method is also safe. This is because the
-Java compiler adds code to the start of a static method to make sure
-the class is initialized. However, the C++ compiler does not
-add this extra code. Hence, if you write a native static method
-using CNI, you are responsible for calling <literal>JvInitClass</literal>
-before doing anything else in the method (unless you are sure
-it is safe to leave it out).</para>
-<para>
-Accessing a static field also requires the class of the
-field to be initialized. The Java compiler will generate code
-to call <literal>_Jv_InitClass</literal> before getting or setting the field.
-However, the C++ compiler will not generate this extra code,
-so it is your responsibility to make sure the class is
-initialized before you access a static field.</para>
-</sect1>
-<sect1><title>Exception Handling</title>
-<para>
-While C++ and Java share a common exception handling framework,
-things are not yet perfectly integrated. The main issue is that the
-<quote>run-time type information</quote> facilities of the two
-languages are not integrated.</para>
-<para>
-Still, things work fairly well. You can throw a Java exception from
-C++ using the ordinary <literal>throw</literal> construct, and this
-exception can be caught by Java code. Similarly, you can catch an
-exception thrown from Java using the C++ <literal>catch</literal>
-construct.
-<para>
-Note that currently you cannot mix C++ catches and Java catches in
-a single C++ translation unit. We do intend to fix this eventually.
-</para>
-<para>
-Here is an example:
-<programlisting>
-if (i >= count)
- throw new java::lang::IndexOutOfBoundsException();
-</programlisting>
-</para>
-<para>
-Normally, GNU C++ will automatically detect when you are writing C++
-code that uses Java exceptions, and handle them appropriately.
-However, if C++ code only needs to execute destructors when Java
-exceptions are thrown through it, GCC will guess incorrectly. Sample
-problematic code:
-<programlisting>
- struct S { ~S(); };
- extern void bar(); // is implemented in Java and may throw exceptions
- void foo()
- {
- S s;
- bar();
- }
-</programlisting>
-The usual effect of an incorrect guess is a link failure, complaining of
-a missing routine called <literal>__gxx_personality_v0</literal>.
-</para>
-<para>
-You can inform the compiler that Java exceptions are to be used in a
-translation unit, irrespective of what it might think, by writing
-<literal>#pragma GCC java_exceptions</literal> at the head of the
-file. This <literal>#pragma</literal> must appear before any
-functions that throw or catch exceptions, or run destructors when
-exceptions are thrown through them.</para>
-</sect1>
-
-<sect1><title>Synchronization</title>
-<para>
-Each Java object has an implicit monitor.
-The Java VM uses the instruction <literal>monitorenter</literal> to acquire
-and lock a monitor, and <literal>monitorexit</literal> to release it.
-The JNI has corresponding methods <literal>MonitorEnter</literal>
-and <literal>MonitorExit</literal>. The corresponding CNI macros
-are <literal>JvMonitorEnter</literal> and <literal>JvMonitorExit</literal>.
-</para>
-<para>
-The Java source language does not provide direct access to these primitives.
-Instead, there is a <literal>synchronized</literal> statement that does an
-implicit <literal>monitorenter</literal> before entry to the block,
-and does a <literal>monitorexit</literal> on exit from the block.
-Note that the lock has to be released even the block is abnormally
-terminated by an exception, which means there is an implicit
-<literal>try</literal>-<literal>finally</literal>.
-</para>
-<para>
-From C++, it makes sense to use a destructor to release a lock.
-CNI defines the following utility class.
-<programlisting>
-class JvSynchronize() {
- jobject obj;
- JvSynchronize(jobject o) { obj = o; JvMonitorEnter(o); }
- ~JvSynchronize() { JvMonitorExit(obj); }
-};
-</programlisting>
-The equivalent of Java's:
-<programlisting>
-synchronized (OBJ) { CODE; }
-</programlisting>
-can be simply expressed:
-<programlisting>
-{ JvSynchronize dummy(OBJ); CODE; }
-</programlisting>
-</para>
-<para>
-Java also has methods with the <literal>synchronized</literal> attribute.
-This is equivalent to wrapping the entire method body in a
-<literal>synchronized</literal> statement.
-(Alternatively, an implementation could require the caller to do
-the synchronization. This is not practical for a compiler, because
-each virtual method call would have to test at run-time if
-synchronization is needed.) Since in <literal>gcj</literal>
-the <literal>synchronized</literal> attribute is handled by the
-method implementation, it is up to the programmer
-of a synchronized native method to handle the synchronization
-(in the C++ implementation of the method).
-In otherwords, you need to manually add <literal>JvSynchronize</literal>
-in a <literal>native synchornized</literal> method.</para>
-</sect1>
-
-<sect1><title>Reflection</title>
-<para>The types <literal>jfieldID</literal> and <literal>jmethodID</literal>
-are as in JNI.</para>
-<para>
-The function <literal>JvFromReflectedField</literal>,
-<literal>JvFromReflectedMethod</literal>,
-<literal>JvToReflectedField</literal>, and
-<literal>JvToFromReflectedMethod</literal> (as in Java 2 JNI)
-will be added shortly, as will other functions corresponding to JNI.</para>
-
-<sect1><title>Using gcjh</title>
-<para>
- The <command>gcjh</command> is used to generate C++ header files from
- Java class files. By default, <command>gcjh</command> generates
- a relatively straightforward C++ header file. However, there
- are a few caveats to its use, and a few options which can be
- used to change how it operates:
-</para>
-<variablelist>
-<varlistentry>
-<term><literal>--classpath</literal> <replaceable>path</replaceable></term>
-<term><literal>--CLASSPATH</literal> <replaceable>path</replaceable></term>
-<term><literal>-I</literal> <replaceable>dir</replaceable></term>
-<listitem><para>
- These options can be used to set the class path for gcjh.
- Gcjh searches the class path the same way the compiler does;
- these options have their familiar meanings.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><literal>-d <replaceable>directory</replaceable></literal></term>
-<listitem><para>
-Puts the generated <literal>.h</literal> files
-beneath <replaceable>directory</replaceable>.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><literal>-o <replaceable>file</replaceable></literal></term>
-<listitem><para>
- Sets the name of the <literal>.h</literal> file to be generated.
- By default the <literal>.h</literal> file is named after the class.
- This option only really makes sense if just a single class file
- is specified.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><literal>--verbose</literal></term>
-<listitem><para>
- gcjh will print information to stderr as it works.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><literal>-M</literal></term>
-<term><literal>-MM</literal></term>
-<term><literal>-MD</literal></term>
-<term><literal>-MMD</literal></term>
-<listitem><para>
- These options can be used to generate dependency information
- for the generated header file. They work the same way as the
- corresponding compiler options.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><literal>-prepend <replaceable>text</replaceable></literal></term>
-<listitem><para>
-This causes the <replaceable>text</replaceable> to be put into the generated
- header just after class declarations (but before declaration
- of the current class). This option should be used with caution.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><literal>-friend <replaceable>text</replaceable></literal></term>
-<listitem><para>
-This causes the <replaceable>text</replaceable> to be put into the class
-declaration after a <literal>friend</literal> keyword.
-This can be used to declare some
- other class or function to be a friend of this class.
- This option should be used with caution.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><literal>-add <replaceable>text</replaceable></literal></term>
-<listitem><para>
-The <replaceable>text</replaceable> is inserted into the class declaration.
-This option should be used with caution.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><literal>-append <replaceable>text</replaceable></literal></term>
-<listitem><para>
-The <replaceable>text</replaceable> is inserted into the header file
-after the class declaration. One use for this is to generate
-inline functions. This option should be used with caution.
-</listitem>
-</varlistentry>
-</variablelist>
-<para>
-All other options not beginning with a <literal>-</literal> are treated
-as the names of classes for which headers should be generated.</para>
-<para>
-gcjh will generate all the required namespace declarations and
-<literal>#include</literal>'s for the header file.
-In some situations, gcjh will generate simple inline member
-functions. Note that, while gcjh puts <literal>#pragma
-interface</literal> in the generated header file, you should
-<emphasis>not</emphasis> put <literal>#pragma implementation</literal>
-into your C++ source file. If you do, duplicate definitions of
-inline functions will sometimes be created, leading to link-time
-errors.
-</para>
-<para>
-There are a few cases where gcjh will fail to work properly:</para>
-<para>
-gcjh assumes that all the methods and fields of a class have ASCII
-names. The C++ compiler cannot correctly handle non-ASCII
-identifiers. gcjh does not currently diagnose this problem.</para>
-<para>
-gcjh also cannot fully handle classes where a field and a method have
-the same name. If the field is static, an error will result.
-Otherwise, the field will be renamed in the generated header; `__'
-will be appended to the field name.</para>
-<para>
-Eventually we hope to change the C++ compiler so that these
-restrictions can be lifted.</para>
-</sect1>
-
-</article>
projects / msp430-gcc.git / blobdiff