+
+@node Invoking grmiregistry
+@chapter Invoking grmiregistry
+
+@c man title grmiregistry Remote object registry
+
+@c man begin SYNOPSIS grmiregistry
+@command{grmic} [@option{OPTION}] @dots{} [@var{port}]
+@ignore
+ [@option{--help}]
+ [@option{--version}]
+@end ignore
+@c man end
+
+@c man begin DESCRIPTION grmiregistry
+
+@command{grmiregistry} starts a remote object registry on the current
+host. If no port number is specified, then port 1099 is used.
+
+@c FIXME: Add real information here.
+@c This really isn't much more than the --help output.
+
+@c man end
+
+@c man begin OPTIONS grmiregistry
+
+@table @gcctabopt
+@item --help
+Print a help message, then exit.
+
+@item --version
+Print version information, then exit.
+@end table
+
+@c man end
+
+
+@node About CNI
+@chapter About CNI
+
+This documents CNI, the Compiled 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).
+
+@menu
+* Basic concepts:: Introduction to using CNI@.
+* Packages:: How packages are mapped to C++.
+* Primitive types:: Handling primitive Java types in C++.
+* Reference types:: Handling Java reference types in C++.
+* Interfaces:: How Java interfaces map to C++.
+* Objects and Classes:: C++ and Java classes.
+* Class Initialization:: How objects are initialized.
+* Object allocation:: How to create Java objects in C++.
+* Memory allocation:: How to allocate and free memory.
+* Arrays:: Dealing with Java arrays in C++.
+* Methods:: Java methods in C++.
+* Strings:: Information about Java Strings.
+* Mixing with C++:: How CNI can interoperate with C++.
+* Exception Handling:: How exceptions are handled.
+* Synchronization:: Synchronizing between Java and C++.
+* Invocation:: Starting the Java runtime from C++.
+* Reflection:: Using reflection from C++.
+@end menu
+
+
+@node Basic concepts
+@section Basic concepts
+
+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.
+
+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
+@command{gcj} uses the same compiler technology as G++ (the GNU
+C++ compiler), it is possible to make the intersection of the two
+languages use the same ABI (object representation and calling
+conventions). The key idea in CNI 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.
+
+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++.)
+
+@noindent A CNI C++ source file must have:
+
+@example
+#include <gcj/cni.h>
+@end example
+
+@noindent and then must include one header file for each Java class it uses, e.g.:
+
+@example
+#include <java/lang/Character.h>
+#include <java/util/Date.h>
+#include <java/lang/IndexOutOfBoundsException.h>
+@end example
+
+@noindent These header files are automatically generated by @code{gcjh}.
+
+
+CNI provides some functions and macros to make using Java objects and
+primitive types from C++ easier. In general, these CNI functions and
+macros start with the @code{Jv} prefix, for example the function
+@code{JvNewObjectArray}. This convention is used to avoid conflicts
+with other libraries. Internal functions in CNI start with the prefix
+@code{_Jv_}. 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.
+
+
+@subsection Limitations
+
+Whilst a Java class is just a C++ class that doesn't mean that you are
+freed from the shackles of Java, a @acronym{CNI} C++ class must adhere to the
+rules of the Java programming language.
+
+For example: it is not possible to declare a method in a CNI class
+that will take a C string (@code{char*}) as an argument, or to declare a
+member variable of some non-Java datatype.
+
+
+@node Packages
+@section Packages
+
+The only global names in Java are class names, and packages. A
+@dfn{package} 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.
+
+A Java package is mapped to a C++ @dfn{namespace}. The Java class
+@code{java.lang.String} is in the package @code{java.lang}, which is a
+sub-package of @code{java}. The C++ equivalent is the class
+@code{java::lang::String}, which is in the namespace @code{java::lang}
+which is in the namespace @code{java}.
+
+@noindent Here is how you could express this:
+
+@example
+(// @r{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
+@{
+ ...
+@};
+@end example
+
+@noindent The @code{gcjh} tool automatically generates the necessary namespace
+declarations.
+
+
+@subsection Leaving out package names
+
+Always using the fully-qualified name of a java class can be
+tiresomely verbose. Using the full qualified name also ties the code
+to a single package making code changes necessary should the class
+move from one package to another. The Java @code{package} declaration
+specifies that the following class declarations are in the named
+package, without having to explicitly name the full package
+qualifiers. The @code{package} declaration can be
+followed by zero or more @code{import} 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
+@code{using} declaration and directive.
+
+@noindent In Java:
+
+@example
+import @var{package-name}.@var{class-name};
+@end example
+
+@noindent allows the program text to refer to @var{class-name} as a shorthand for
+the fully qualified name: @code{@var{package-name}.@var{class-name}}.
+
+
+@noindent To achieve the same effect C++, you have to do this:
+
+@example
+using @var{package-name}::@var{class-name};
+@end example
+
+
+@noindent Java can also cause imports on demand, like this:
+
+@example
+import @var{package-name}.*;
+@end example
+
+@noindent Doing this allows any class from the package @var{package-name} to be
+referred to only by its class-name within the program text.
+
+
+@noindent The same effect can be achieved in C++ like this:
+
+@example
+using namespace @var{package-name};
+@end example
+
+
+@node Primitive types
+@section Primitive types
+
+Java provides 8 @dfn{primitives} types which represent integers, floats,
+characters and booleans (and also the void type). C++ has its own
+very similar concrete types. Such types in C++ however are not always
+implemented in the same way (an int might be 16, 32 or 64 bits for example)
+so CNI provides a special C++ type for each primitive Java type:
+
+@multitable @columnfractions .20 .25 .60
+@item @strong{Java type} @tab @strong{C/C++ typename} @tab @strong{Description}
+@item @code{char} @tab @code{jchar} @tab 16 bit Unicode character
+@item @code{boolean} @tab @code{jboolean} @tab logical (true or false) values
+@item @code{byte} @tab @code{jbyte} @tab 8-bit signed integer
+@item @code{short} @tab @code{jshort} @tab 16 bit signed integer
+@item @code{int} @tab @code{jint} @tab 32 bit signed integer
+@item @code{long} @tab @code{jlong} @tab 64 bit signed integer
+@item @code{float} @tab @code{jfloat} @tab 32 bit IEEE floating point number
+@item @code{double} @tab @code{jdouble} @tab 64 bit IEEE floating point number
+@item @code{void} @tab @code{void} @tab no value
+@end multitable
+
+When referring to a Java type You should always use these C++ typenames (e.g.: @code{jint})
+to avoid disappointment.
+
+
+@subsection Reference types associated with primitive types
+
+In Java each primitive type has an associated reference type,
+e.g.: @code{boolean} has an associated @code{java.lang.Boolean.TYPE} class.
+In order to make working with such classes easier GCJ provides the macro
+@code{JvPrimClass}:
+
+@deffn macro JvPrimClass type
+Return a pointer to the @code{Class} object corresponding to the type supplied.
+
+@example
+JvPrimClass(void) @result{} java.lang.Void.TYPE
+@end example
+
+@end deffn
+
+
+@node Reference types
+@section Reference types
+
+A Java reference type is treated as a class in C++. Classes and
+interfaces are handled this way. A Java reference is translated to a
+C++ pointer, so for instance a Java @code{java.lang.String} becomes,
+in C++, @code{java::lang::String *}.
+
+CNI provides a few built-in typedefs for the most common classes:
+@multitable @columnfractions .30 .25 .60
+@item @strong{Java type} @tab @strong{C++ typename} @tab @strong{Description}
+@item @code{java.lang.Object} @tab @code{jobject} @tab Object type
+@item @code{java.lang.String} @tab @code{jstring} @tab String type
+@item @code{java.lang.Class} @tab @code{jclass} @tab Class type
+@end multitable
+@cindex jobject
+@cindex jstring
+@cindex jclass
+
+Every Java class or interface has a corresponding @code{Class}
+instance. These can be accessed in CNI via the static @code{class$}
+field of a class. The @code{class$} field is of type @code{Class}
+(and not @code{Class *}), so you will typically take the address of
+it.
+@cindex class$
+
+Here is how you can refer to the class of @code{String}, which in
+Java would be written @code{String.class}:
+
+@example
+using namespace java::lang;
+doSomething (&String::class$);
+@end example
+
+
+@node Interfaces
+@section Interfaces
+
+A Java class can @dfn{implement} zero or more
+@dfn{interfaces}, in addition to inheriting from
+a single base class.
+
+@acronym{CNI} allows CNI code to implement methods of interfaces.
+You can also call methods through interface references, with some
+limitations.
+
+@acronym{CNI} doesn't understand interface inheritance at all yet. So,
+you can only call an interface method when the declared type of the
+field being called matches the interface which declares that
+method. The workaround is to cast the interface reference to the right
+superinterface.
+
+For example if you have:
+
+@example
+interface A
+@{
+ void a();
+@}
+
+interface B extends A
+@{
+ void b();
+@}
+@end example
+
+and declare a variable of type @code{B} in C++, you can't call
+@code{a()} unless you cast it to an @code{A} first.
+
+@node Objects and Classes
+@section Objects and Classes
+
+@subsection Classes
+
+All Java classes are derived from @code{java.lang.Object}. C++ does
+not have a unique root class, but we use the C++ class
+@code{java::lang::Object} as the C++ version of the
+@code{java.lang.Object} Java class. All other Java classes are mapped
+into corresponding C++ classes derived from @code{java::lang::Object}.
+
+Interface inheritance (the @code{implements} keyword) is currently not
+reflected in the C++ mapping.
+
+
+@subsection Object fields
+
+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 @emph{in front of} 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.)
+
+The fields are laid out in the same order, alignment, and size as in
+C++. Specifically, 8-bit and 16-bit native types (@code{byte},
+@code{short}, @code{char}, and @code{boolean}) are @emph{not} 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.
+
+If you include the @code{gcjh}-generated header for a
+class, you can access fields of Java classes in the @emph{natural}
+way. For example, given the following Java class:
+
+@example
+public class Int
+@{
+ public int i;
+ public Int (int i) @{ this.i = i; @}
+ public static Int zero = new Int(0);
+@}
+@end example
+
+you can write:
+
+@example
+#include <gcj/cni.h>;
+#include <Int>;
+
+Int*
+mult (Int *p, jint k)
+@{
+ if (k == 0)
+ return Int::zero; // @r{Static member access.}
+ return new Int(p->i * k);
+@}
+@end example
+
+
+@subsection Access specifiers
+
+CNI 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.
+
+
+
+@node Class Initialization
+@section Class Initialization
+
+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
+@code{String} objects corresponding to string literals in
+the code.
+
+The GCJ compiler inserts calls to @code{JvInitClass} 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.
+
+First, @code{libgcj} will make sure a class is initialized before an
+instance of that object is created. This is one of the
+responsibilities of the @code{new} operation. This is taken care of
+both in Java code, and in C++ code. When G++ sees a @code{new} of a
+Java class, it will call a routine in @code{libgcj} to allocate the
+object, and that routine will take care of initializing the class.
+Note however that this does not happen for Java arrays; you must
+allocate those using the appropriate CNI function. 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.
+
+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 @code{JvInitClass}
+before doing anything else in the method (unless you are sure
+it is safe to leave it out).
+
+Accessing a static field also requires the class of the
+field to be initialized. The Java compiler will generate code
+to call @code{JvInitClass} 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 from C++.
+
+
+@node Object allocation
+@section Object allocation
+
+New Java objects are allocated using a
+@dfn{class instance creation expression}, e.g.:
+
+@example
+new @var{Type} ( ... )
+@end example
+
+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}, you can allocate a new Java object
+using standard C++ syntax and the C++ compiler will allocate
+memory from the garbage collector. If you have overloaded
+constructors, the compiler will choose the correct one
+using standard C++ overload resolution rules.
+
+@noindent For example:
+
+@example
+java::util::Hashtable *ht = new java::util::Hashtable(120);
+@end example
+
+
+@node Memory allocation
+@section Memory allocation
+
+When allocating memory in @acronym{CNI} methods it is best to handle
+out-of-memory conditions by throwing a Java exception. These
+functions are provided for that purpose:
+
+@deftypefun void* JvMalloc (jsize @var{size})
+Calls malloc. Throws @code{java.lang.OutOfMemoryError} if allocation
+fails.
+@end deftypefun
+
+@deftypefun void* JvRealloc (void* @var{ptr}, jsize @var{size})
+Calls realloc. Throws @code{java.lang.OutOfMemoryError} if
+reallocation fails.
+@end deftypefun
+
+@deftypefun void JvFree (void* @var{ptr})
+Calls free.
+@end deftypefun
+
+@node Arrays
+@section Arrays
+
+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
+@code{java.lang.Object}). An array-valued variable is one that
+contains a reference (pointer) to an array object.
+
+Referencing a Java array in C++ code is done using the
+@code{JArray} template, which as defined as follows:
+
+@example
+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]; @}
+@};
+@end example
+
+
+There are a number of @code{typedef}s which correspond to @code{typedef}s
+from the @acronym{JNI}. Each is the type of an array holding objects
+of the relevant type:
+
+@example
+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;
+@end example
+
+
+@deftypemethod {template<class T>} T* elements (JArray<T> @var{array})
+This template function can be used to get a pointer to the elements of
+the @code{array}. For instance, you can fetch a pointer to the
+integers that make up an @code{int[]} like so:
+
+@example
+extern jintArray foo;
+jint *intp = elements (foo);
+@end example
+
+The name of this function may change in the future.
+@end deftypemethod
+
+
+@deftypefun jobjectArray JvNewObjectArray (jsize @var{length}, jclass @var{klass}, jobject @var{init})
+This creates a new array whose elements have reference type.
+@code{klass} is the type of elements of the array and
+@code{init} is the initial value put into every slot in the array.
+@end deftypefun
+
+@example
+using namespace java::lang;
+JArray<String *> *array
+ = (JArray<String *> *) JvNewObjectArray(length, &String::class$, NULL);
+@end example
+
+
+@subsection Creating arrays
+
+For each primitive type there is a function which can be used to
+create a new array of that type. The name of the function is of the
+form:
+
+@example
+JvNew@var{Type}Array
+@end example
+
+@noindent For example:
+
+@example
+JvNewBooleanArray
+@end example
+
+@noindent can be used to create an array of Java primitive boolean types.
+
+@noindent The following function definition is the template for all such functions:
+
+@deftypefun jbooleanArray JvNewBooleanArray (jint @var{length})
+Creates an array @var{length} indices long.
+@end deftypefun
+
+@deftypefun jsize JvGetArrayLength (jarray @var{array})
+Returns the length of the @var{array}.
+@end deftypefun
+
+
+@node Methods
+@section Methods
+
+Java methods are mapped directly into C++ methods.
+The header files generated by @code{gcjh}
+include the appropriate method definitions.
+Basically, the generated methods have the same names and
+@emph{corresponding} types as the Java methods,
+and are called in the natural manner.
+
+@subsection Overloading
+
+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 @code{gcjh} the C++ compiler will choose
+the expected one.
+
+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 @dfn{mangling},
+and the encoded name is the @dfn{mangled name}.
+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 @emph{same} encoding scheme.
+
+@subsection Static methods
+
+Static Java methods are invoked in @acronym{CNI} using the standard
+C++ syntax, using the @code{::} operator rather
+than the @code{.} operator.
+
+@noindent For example:
+
+@example
+jint i = java::lang::Math::round((jfloat) 2.3);
+@end example
+
+@noindent C++ method definition syntax is used to define a static native method.
+For example:
+
+@example
+#include <java/lang/Integer>
+java::lang::Integer*
+java::lang::Integer::getInteger(jstring str)
+@{
+ ...
+@}
+@end example
+
+
+@subsection Object Constructors
+
+Constructors are called implicitly as part of object allocation
+using the @code{new} operator.
+
+@noindent For example:
+
+@example
+java::lang::Integer *x = new java::lang::Integer(234);
+@end example
+
+Java does not allow a constructor to be a native method.
+This limitation can be coded round however because a constructor
+can @emph{call} a native method.
+
+
+@subsection Instance methods
+
+Calling a Java instance method from a C++ @acronym{CNI} method is done
+using the standard C++ syntax, e.g.:
+
+@example
+// @r{First create the Java object.}
+java::lang::Integer *x = new java::lang::Integer(234);
+// @r{Now call a method.}
+jint prim_value = x->intValue();
+if (x->longValue == 0)
+ ...
+@end example
+
+@noindent Defining a Java native instance method is also done the natural way:
+
+@example
+#include <java/lang/Integer.h>
+
+jdouble
+java::lang:Integer::doubleValue()
+@{
+ return (jdouble) value;
+@}
+@end example
+
+
+@subsection Interface methods
+
+In Java you can call a method using an interface reference. This is
+supported, but not completely. @xref{Interfaces}.
+
+
+
+
+@node Strings
+@section Strings
+
+@acronym{CNI} provides a number of utility functions for
+working with Java Java @code{String} objects.
+The names and interfaces are analogous to those of @acronym{JNI}.
+
+
+@deftypefun jstring JvNewString (const jchar* @var{chars}, jsize @var{len})
+Returns a Java @code{String} object with characters from the array of
+Unicode characters @var{chars} up to the index @var{len} in that array.
+@end deftypefun
+
+@deftypefun jstring JvNewStringLatin1 (const char* @var{bytes}, jsize @var{len})
+Returns a Java @code{String} made up of @var{len} bytes from @var{bytes}.
+@end deftypefun
+
+
+@deftypefun jstring JvNewStringLatin1 (const char* @var{bytes})
+As above but the length of the @code{String} is @code{strlen(@var{bytes})}.
+@end deftypefun
+
+@deftypefun jstring JvNewStringUTF (const char* @var{bytes})
+Returns a @code{String} which is made up of the UTF encoded characters
+present in the C string @var{bytes}.
+@end deftypefun
+
+@deftypefun jchar* JvGetStringChars (jstring @var{str})
+Returns a pointer to an array of characters making up the @code{String} @var{str}.
+@end deftypefun
+
+@deftypefun int JvGetStringUTFLength (jstring @var{str})
+Returns the number of bytes required to encode the contents of the
+@code{String} @var{str} in UTF-8.
+@end deftypefun
+
+@deftypefun jsize JvGetStringUTFRegion (jstring @var{str}, jsize @var{start}, jsize @var{len}, char* @var{buf})
+Puts the UTF-8 encoding of a region of the @code{String} @var{str} into
+the buffer @code{buf}. The region to fetch is marked by @var{start} and @var{len}.
+
+Note that @var{buf} is a buffer, not a C string. It is @emph{not}
+null terminated.
+@end deftypefun
+
+
+@node Mixing with C++
+@section Interoperating with C/C++
+
+Because @acronym{CNI} is designed to represent Java classes and methods it
+cannot be mixed readily with C/C++ types.
+
+One important restriction is that Java classes cannot have non-Java
+type instance or static variables and cannot have methods which take
+non-Java types as arguments or return non-Java types.
+
+@noindent None of the following is possible with CNI:
+
+@example
+
+class ::MyClass : public java::lang::Object
+@{
+ char* variable; // @r{char* is not a valid Java type.}
+@}
+
+
+uint
+::SomeClass::someMethod (char *arg)
+@{
+ .
+ .
+ .
+@} // @r{@code{uint} is not a valid Java type, neither is @code{char*}}
+@end example
+
+@noindent Of course, it is ok to use C/C++ types within the scope of a method:
+
+
+@example
+jint
+::SomeClass::otherMethod (jstring str)
+@{
+ char *arg = ...
+ .
+ .
+ .
+@}
+@end example
+
+@subsection RawData
+
+The above restriction can be problematic, so @acronym{CNI} includes the
+@code{gnu.gcj.RawData} class. The @code{RawData} class is a
+@dfn{non-scanned reference} type. In other words variables declared
+of type @code{RawData} can contain any data and are not checked by the
+compiler or memory manager in any way.
+
+This means that you can put C/C++ data structures (including classes)
+in your @acronym{CNI} classes, as long as you use the appropriate cast.
+
+@noindent Here are some examples:
+
+@example
+
+class ::MyClass : public java::lang::Object
+@{
+ gnu.gcj.RawData string;
+
+ MyClass ();
+ gnu.gcj.RawData getText ();
+ void printText ();
+@}
+
+::MyClass::MyClass ()
+@{
+ char* text = ...
+ string = text;
+@}
+
+gnu.gcj.RawData
+::MyClass::getText ()
+@{
+ return string;
+@}
+
+void
+::MyClass::printText ()
+@{
+ printf("%s\n", (char*) string);
+@}
+@end example
+
+
+@subsection RawDataManaged
+
+@code{gnu.gcj.RawDataManaged} is another type used to indicate special data used
+by native code. Unlike the @code{RawData} type, fields declared as
+@code{RawDataManaged} will be "marked" by the memory manager and
+considered for garbage collection.
+
+Native data which is allocated using CNI's @code{JvAllocBytes()}
+function and stored in a @code{RawDataManaged} will be automatically
+freed when the Java object it is associated with becomes unreachable.
+
+@subsection Native memory allocation
+
+@deftypefun void* JvAllocBytes (jsize @var{size})
+Allocates @var{size} bytes from the heap. The memory returned is zeroed.
+This memory is not scanned for pointers by the garbage collector, but will
+be freed if no references to it are discovered.
+
+This function can be useful if you need to associate some native data with a
+Java object. Using a CNI's special @code{RawDataManaged} type, native data
+allocated with @code{JvAllocBytes} will be automatically freed when the Java
+object itself becomes unreachable.
+@end deftypefun
+
+@subsection Posix signals
+
+On Posix based systems the @code{libgcj} library uses several signals
+internally. @acronym{CNI} code should not attempt to use the same
+signals as doing so may cause @code{libgcj} and/or the @acronym{CNI}
+code to fail.
+
+SIGSEGV is used on many systems to generate
+@code{NullPointerExceptions}. SIGCHLD is used internally by
+@code{Runtime.exec()}. Several other signals (that vary from platform to
+platform) can be used by the memory manager and by
+@code{Thread.interrupt()}.
+
+@node Exception Handling
+@section Exception Handling
+
+While C++ and Java share a common exception handling framework,
+things are not yet perfectly integrated. The main issue is that the
+run-time type information facilities of the two
+languages are not integrated.
+
+Still, things work fairly well. You can throw a Java exception from
+C++ using the ordinary @code{throw} construct, and this
+exception can be caught by Java code. Similarly, you can catch an
+exception thrown from Java using the C++ @code{catch}
+construct.
+
+@noindent Here is an example:
+
+@example
+if (i >= count)
+ throw new java::lang::IndexOutOfBoundsException();
+@end example
+
+Normally, G++ 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:
+
+@example
+struct S @{ ~S(); @};
+
+extern void bar(); // @r{Is implemented in Java and may throw exceptions.}
+
+void foo()
+@{
+ S s;
+ bar();
+@}
+@end example
+
+The usual effect of an incorrect guess is a link failure, complaining of
+a missing routine called @code{__gxx_personality_v0}.
+
+You can inform the compiler that Java exceptions are to be used in a
+translation unit, irrespective of what it might think, by writing
+@code{#pragma GCC java_exceptions} at the head of the
+file. This @code{#pragma} must appear before any
+functions that throw or catch exceptions, or run destructors when
+exceptions are thrown through them.
+
+@node Synchronization
+@section Synchronization
+
+Each Java object has an implicit monitor.
+The Java VM uses the instruction @code{monitorenter} to acquire
+and lock a monitor, and @code{monitorexit} to release it.
+
+The corresponding CNI macros are @code{JvMonitorEnter} and
+@code{JvMonitorExit} (JNI has similar methods @code{MonitorEnter}
+and @code{MonitorExit}).
+
+
+The Java source language does not provide direct access to these primitives.
+Instead, there is a @code{synchronized} statement that does an
+implicit @code{monitorenter} before entry to the block,
+and does a @code{monitorexit} on exit from the block.
+Note that the lock has to be released even when the block is abnormally
+terminated by an exception, which means there is an implicit
+@code{try finally} surrounding synchronization locks.
+
+From C++, it makes sense to use a destructor to release a lock.
+@acronym{CNI} defines the following utility class:
+
+@example
+class JvSynchronize() @{
+ jobject obj;
+ JvSynchronize(jobject o) @{ obj = o; JvMonitorEnter(o); @}
+ ~JvSynchronize() @{ JvMonitorExit(obj); @}
+@};
+@end example
+
+So this Java code:
+
+@example
+synchronized (OBJ)
+@{
+ CODE
+@}
+@end example
+
+@noindent might become this C++ code:
+
+@example
+@{
+ JvSynchronize dummy (OBJ);
+ CODE;
+@}
+@end example
+
+Java also has methods with the @code{synchronized} attribute.
+This is equivalent to wrapping the entire method body in a
+@code{synchronized} 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 @command{gcj}
+the @code{synchronized} 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 other words, you need to manually add @code{JvSynchronize}
+in a @code{native synchronized} method.
+
+@node Invocation
+@section Invocation
+
+CNI permits C++ applications to make calls into Java classes, in addition to
+allowing Java code to call into C++. Several functions, known as the
+@dfn{invocation API}, are provided to support this.
+
+@deftypefun jint JvCreateJavaVM (JvVMInitArgs* @var{vm_args})
+
+Initializes the Java runtime. This function performs essential initialization
+of the threads interface, garbage collector, exception handling and other key
+aspects of the runtime. It must be called once by an application with
+a non-Java @code{main()} function, before any other Java or CNI calls are made.
+It is safe, but not recommended, to call @code{JvCreateJavaVM()} more than
+once provided it is only called from a single thread.
+The @var{vmargs} parameter can be used to specify initialization parameters
+for the Java runtime. It may be @code{NULL}.
+
+JvVMInitArgs represents a list of virtual machine initialization
+arguments. @code{JvCreateJavaVM()} ignores the version field.
+
+@example
+typedef struct JvVMOption
+@{
+ // a VM initialization option
+ char* optionString;
+ // extra information associated with this option
+ void* extraInfo;
+@} JvVMOption;
+
+typedef struct JvVMInitArgs
+@{
+ // for compatibility with JavaVMInitArgs
+ jint version;
+
+ // number of VM initialization options
+ jint nOptions;
+
+ // an array of VM initialization options
+ JvVMOption* options;
+
+ // true if the option parser should ignore unrecognized options
+ jboolean ignoreUnrecognized;
+@} JvVMInitArgs;
+@end example
+
+@code{JvCreateJavaVM()} returns @code{0} upon success, or @code{-1} if
+the runtime is already initialized.
+
+@emph{Note:} In GCJ 3.1, the @code{vm_args} parameter is ignored. It
+is recognized and used as of release 4.0.
+@end deftypefun
+
+@deftypefun java::lang::Thread* JvAttachCurrentThread (jstring @var{name}, java::lang::ThreadGroup* @var{group})
+Registers an existing thread with the Java runtime. This must be called once
+from each thread, before that thread makes any other Java or CNI calls. It
+must be called after @code{JvCreateJavaVM}.
+@var{name} specifies a name for the thread. It may be @code{NULL}, in which
+case a name will be generated.
+@var{group} is the ThreadGroup in which this thread will be a member. If it
+is @code{NULL}, the thread will be a member of the main thread group.
+The return value is the Java @code{Thread} object that represents the thread.
+It is safe to call @code{JvAttachCurrentThread()} more than once from the same
+thread. If the thread is already attached, the call is ignored and the current
+thread object is returned.
+@end deftypefun
+
+@deftypefun jint JvDetachCurrentThread ()
+Unregisters a thread from the Java runtime. This should be called by threads
+that were attached using @code{JvAttachCurrentThread()}, after they have
+finished making calls to Java code. This ensures that any resources associated
+with the thread become eligible for garbage collection.
+This function returns @code{0} upon success, or @code{-1} if the current thread
+is not attached.
+@end deftypefun
+
+@subsection Handling uncaught exceptions
+
+If an exception is thrown from Java code called using the invocation API, and
+no handler for the exception can be found, the runtime will abort the
+application. In order to make the application more robust, it is recommended
+that code which uses the invocation API be wrapped by a top-level try/catch
+block that catches all Java exceptions.
+
+@subsection Example
+
+The following code demonstrates the use of the invocation API. In this
+example, the C++ application initializes the Java runtime and attaches
+itself. The @code{java.lang.System} class is initialized in order to
+access its @code{out} field, and a Java string is printed. Finally, the thread
+is detached from the runtime once it has finished making Java calls. Everything
+is wrapped with a try/catch block to provide a default handler for any uncaught
+exceptions.
+
+The example can be compiled with @command{c++ -c test.cc; gcj test.o}.
+
+@example
+// test.cc
+#include <gcj/cni.h>
+#include <java/lang/System.h>
+#include <java/io/PrintStream.h>
+#include <java/lang/Throwable.h>
+
+int main(int argc, char *argv[])
+@{
+ using namespace java::lang;
+
+ try
+ @{
+ JvCreateJavaVM(NULL);
+ JvAttachCurrentThread(NULL, NULL);
+
+ String *message = JvNewStringLatin1("Hello from C++");
+ JvInitClass(&System::class$);
+ System::out->println(message);
+
+ JvDetachCurrentThread();
+ @}
+ catch (Throwable *t)
+ @{
+ System::err->println(JvNewStringLatin1("Unhandled Java exception:"));
+ t->printStackTrace();
+ @}
+@}
+@end example
+
+@node Reflection
+@section Reflection
+
+Reflection is possible with CNI code, it functions similarly to how it
+functions with JNI@.
+
+@c clean this up... I mean, what are the types jfieldID and jmethodID in JNI?
+The types @code{jfieldID} and @code{jmethodID}
+are as in JNI@.
+
+@noindent The functions:
+
+@itemize
+@item @code{JvFromReflectedField},
+@item @code{JvFromReflectedMethod},
+@item @code{JvToReflectedField}
+@item @code{JvToFromReflectedMethod}
+@end itemize
+
+@noindent will be added shortly, as will other functions corresponding to JNI@.
+
+
+@node System properties
+@chapter System properties
+
+The runtime behavior of the @code{libgcj} library can be modified by setting
+certain system properties. These properties can be compiled into the program
+using the @code{-D@var{name}[=@var{value}]} option to @command{gcj} or by
+setting them explicitly in the program by calling the
+@code{java.lang.System.setProperty()} method. Some system properties are only
+used for informational purposes (like giving a version number or a user name).
+A program can inspect the current value of a property by calling the
+@code{java.lang.System.getProperty()} method.
+
+@menu
+* Standard Properties:: Standard properties supported by @code{libgcj}
+* GNU Classpath Properties:: Properties found in Classpath based libraries
+* libgcj Runtime Properties:: Properties specific to @code{libgcj}
+@end menu
+
+@node Standard Properties
+@section Standard Properties
+
+The following properties are normally found in all implementations of the core
+libraries for the Java language.
+
+@table @gcctabopt
+
+@item java.version
+The @code{libgcj} version number.
+
+@item java.vendor
+Set to @samp{The Free Software Foundation, Inc.}
+
+@item java.vendor.url
+Set to @uref{http://gcc.gnu.org/java/}.
+
+@item java.home
+The directory where @code{gcj} was installed. Taken from the @code{--prefix}
+option given to @command{configure}.
+
+@item java.class.version
+The class format version number supported by the libgcj byte code interpreter.
+(Currently @samp{46.0})
+
+@item java.vm.specification.version
+The Virtual Machine Specification version implemented by @code{libgcj}.
+(Currently @samp{1.0})
+
+@item java.vm.specification.vendor
+The name of the Virtual Machine specification designer.
+
+@item java.vm.specification.name
+The name of the Virtual Machine specification
+(Set to @samp{Java Virtual Machine Specification}).
+
+@item java.vm.version
+The @command{gcj} version number.
+
+@item java.vm.vendor
+Set to @samp{The Free Software Foundation, Inc.}
+
+@item java.vm.name
+Set to @samp{GNU libgcj}.
+
+@item java.specification.version
+The Runtime Environment specification version implemented by @code{libgcj}.
+(Currently set to @samp{1.3})
+
+@item java.specification.vendor
+The Runtime Environment specification designer.
+
+@item java.specification.name
+The name of the Runtime Environment specification
+(Set to @samp{Java Platform API Specification}).
+
+@item java.class.path
+The paths (jar files, zip files and directories) used for finding class files.
+
+@item java.library.path
+Directory path used for finding native libraries.
+
+@item java.io.tmpdir
+The directory used to put temporary files in.
+
+@item java.compiler
+Name of the Just In Time compiler to use by the byte code interpreter.
+Currently not used in @code{libgcj}.
+
+@item java.ext.dirs
+Directories containing jar files with extra libraries. Will be used when
+resolving classes.
+
+@item java.protocol.handler.pkgs
+A @samp{|} separated list of package names that is used to find classes that
+implement handlers for @code{java.net.URL}.
+
+@item java.rmi.server.codebase
+A list of URLs that is used by the @code{java.rmi.server.RMIClassLoader}
+to load classes from.
+
+@item jdbc.drivers
+A list of class names that will be loaded by the @code{java.sql.DriverManager}
+when it starts up.
+
+@item file.separator
+The separator used in when directories are included in a filename
+(normally @samp{/} or @samp{\} ).
+
+@item file.encoding
+The default character encoding used when converting platform native files to
+Unicode (usually set to @samp{8859_1}).
+
+@item path.separator
+The standard separator used when a string contains multiple paths
+(normally @samp{:} or @samp{;}), the string is usually not a valid character
+to use in normal directory names.)
+
+@item line.separator
+The default line separator used on the platform (normally @samp{\n}, @samp{\r}
+or a combination of those two characters).
+
+@item policy.provider
+The class name used for the default policy provider returned by
+@code{java.security.Policy.getPolicy}.
+
+@item user.name
+The name of the user running the program. Can be the full name, the login name
+or empty if unknown.
+
+@item user.home
+The default directory to put user specific files in.
+
+@item user.dir
+The current working directory from which the program was started.
+
+@item user.language
+The default language as used by the @code{java.util.Locale} class.
+
+@item user.region
+The default region as used by the @code{java.util.Local} class.
+
+@item user.variant
+The default variant of the language and region local used.
+
+@item user.timezone
+The default timezone as used by the @code{java.util.TimeZone} class.
+
+@item os.name
+The operating system/kernel name that the program runs on.
+
+@item os.arch
+The hardware that we are running on.
+
+@item os.version
+The version number of the operating system/kernel.
+
+@item awt.appletWarning
+The string to display when an untrusted applet is displayed.
+Returned by @code{java.awt.Window.getWarningString()} when the window is
+``insecure''.
+
+@item awt.toolkit
+The class name used for initializing the default @code{java.awt.Toolkit}.
+Defaults to @code{gnu.awt.gtk.GtkToolkit}.
+
+@item http.proxyHost
+Name of proxy host for http connections.
+
+@item http.proxyPort
+Port number to use when a proxy host is in use.
+
+@end table
+
+@node GNU Classpath Properties
+@section GNU Classpath Properties
+
+@code{libgcj} is based on the GNU Classpath (Essential Libraries for Java) a
+GNU project to create free core class libraries for use with virtual machines
+and compilers for the Java language. The following properties are common to
+libraries based on GNU Classpath.
+
+@table @gcctabopt
+
+@item gcj.dumpobject
+Enables printing serialization debugging by the @code{java.io.ObjectInput} and
+@code{java.io.ObjectOutput} classes when set to something else then the empty
+string. Only used when running a debug build of the library.
+
+@item gnu.classpath.vm.shortname
+This is a succinct name of the virtual machine. For @code{libgcj},
+this will always be @samp{libgcj}.
+
+@item gnu.classpath.home.url
+A base URL used for finding system property files (e.g.,
+@file{classpath.security}). By default this is a @samp{file:} URL
+pointing to the @file{lib} directory under @samp{java.home}.
+
+@end table
+
+@node libgcj Runtime Properties
+@section libgcj Runtime Properties
+
+The following properties are specific to the @code{libgcj} runtime and will
+normally not be found in other core libraries for the java language.
+
+@table @gcctabopt
+
+@item java.fullversion
+The combination of @code{java.vm.name} and @code{java.vm.version}.
+
+@item java.vm.info
+Same as @code{java.fullversion}.
+
+@item impl.prefix
+Used by the @code{java.net.DatagramSocket} class when set to something else
+then the empty string. When set all newly created @code{DatagramSocket}s will
+try to load a class @code{java.net.[impl.prefix]DatagramSocketImpl} instead of
+the normal @code{java.net.PlainDatagramSocketImpl}.
+
+@item gnu.gcj.progname
+The class or binary name that was used to invoke the program. This will be
+the name of the "main" class in the case where the @code{gij} front end is
+used, or the program binary name in the case where an application is compiled
+to a native binary.
+
+@item gnu.gcj.user.realname
+The real name of the user, as taken from the password file. This may
+not always hold only the user's name (as some sites put extra
+information in this field). Also, this property is not available on
+all platforms.
+
+@item gnu.gcj.runtime.NameFinder.use_addr2line
+Whether an external process, @command{addr2line}, should be used to determine
+line number information when tracing the stack. Setting this to @code{false}
+may suppress line numbers when printing stack traces and when using
+the java.util.logging infrastructure. However, performance may improve
+significantly for applications that print stack traces or make logging calls
+frequently.
+
+@item gnu.gcj.runtime.NameFinder.show_raw
+Whether the address of a stack frame should be printed when the line
+number is unavailable. Setting this to @code{true} will cause the name
+of the object and the offset within that object to be printed when no
+line number is available. This allows for off-line decoding of
+stack traces if necessary debug information is available. The default
+is @code{false}, no raw addresses are printed.
+
+@item gnu.gcj.runtime.NameFinder.remove_unknown
+Whether stack frames for non-java code should be included in a stack
+trace. The default value is @code{true}, stack frames for non-java
+code are suppressed. Setting this to @code{false} will cause any
+non-java stack frames to be printed in addition to frames for the java
+code.
+
+@item gnu.gcj.runtime.VMClassLoader.library_control
+This controls how shared libraries are automatically loaded by the
+built-in class loader. If this property is set to @samp{full}, a full
+search is done for each requested class. If this property is set to
+@samp{cache}, then any failed lookups are cached and not tried again.
+If this property is set to @samp{never} (the default), then lookups
+are never done. For more information, @xref{Extensions}.
+
+@item gnu.gcj.runtime.endorsed.dirs
+This is like the standard @code{java.endorsed.dirs}, property, but
+specifies some extra directories which are searched after the standard
+endorsed directories. This is primarily useful for telling
+@code{libgcj} about additional libraries which are ordinarily
+incorporated into the JDK, and which should be loaded by the bootstrap
+class loader, but which are not yet part of @code{libgcj} itself for
+some reason.
+
+@item gnu.gcj.jit.compiler
+@c FIXME we should probably have a whole node on this...
+This is the full path to @command{gcj} executable which should be
+used to compile classes just-in-time when
+@code{ClassLoader.defineClass} is called. If not set, @command{gcj}
+will not be invoked by the runtime; this can also be controlled via
+@code{Compiler.disable}.
+
+@item gnu.gcj.jit.options
+This is a space-separated string of options which should be passed to
+@command{gcj} when in JIT mode. If not set, a sensible default is
+chosen.
+
+@item gnu.gcj.jit.cachedir
+This is the directory where cached shared library files are
+stored. If not set, JIT compilation is disabled. This should never
+be set to a directory that is writable by any other user.
+
+@item gnu.gcj.precompiled.db.path
+This is a sequence of file names, each referring to a file created by
+@command{gcj-dbtool}. These files will be used by @code{libgcj} to
+find shared libraries corresponding to classes that are loaded from
+bytecode. @code{libgcj} often has a built-in default database; it
+can be queried using @code{gcj-dbtool -p}.
+
+@end table
+
+