source: trunk/src/gcc/libjava/doc/cni.sgml@ 869

<!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 &lt;gcj/cni.h&gt;
</programlisting></para>

<para>
You then include header files for the various Java classes you need
to use:
<programlisting>
#include &lt;java/lang/Character.h&gt;
#include &lt;java/util/Date.h&gt;
#include &lt;java/lang/IndexOutOfBoundsException.h&gt;
</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;
    ...
  }
}