Here is how to generate the Java interface to PLplot using swig.

PREREQUISITE: swig.  Version 1.3.36 works fine for me, but it has been a long
time since we have had any version dependency problems for swig.

(1) Install a Java SDK (Software Development Kit).  I use a free version
from Debian Lenny consisting of gcj, gij, and fastjar, but apparently other
free java versions and also proprietary versions of java work fine.

(2) If the java include files are not in a default include directory then
you need to tell CMake where they are.  I use (although I am not sure
whether this is necessary any longer)

export CMAKE_INCLUDE_PATH=/usr/lib/gcc/x86_64-linux-gnu/4.3/include

(3) The rest is highly automated.  We use a CMake-based build system
so we run "cmake" to configure the build, "make" to build, and "make
install" to install.  For more details see our wiki at
<https://sourceforge.net/p/plplot/wiki>.

For the curious, here are some more details about the 'make' and 'make
install' steps above.

'make' automatically runs swig on plplotjavac.i
(which does an include of ../swig-support/plplotcapi.i) to generate all the
interface files that are needed for further processing.  To understand these
two *.i files and what they do, you should read the latest java interface
documentation from swig.  The result is a complete
interface (aside from the limitations mentioned below) for Java to the
PLplot common API.

The files generated by swig are necessary java files and plplotjavac_wrap.c.
'make' builds the java interface shared object module (DLL)
plplotjavac_wrap.SOBJEXT from plplotjavac_wrap.c. 'make' also builds the
class files corresponding to the swig-generated java files, the configured
config.java file, and the PLStream.java file which is hand-crafted (swig
might be able to do this in future) so that calling a method in the class
will ensure the stream is correctly set before calling the underlying API
function.  The relevant java files and corresponding class files that are
compiled from them make up the plplot.core package.

'make install' installs the relevant java and class files that are part of
the plplot.core package in $prefix/share/java/plplot/core,
installs the shared object module (DLL) plplotjavac_wrap.SOBJEXT for the
java PLplot interface in the $prefix/lib/jni, and also installs
(from ../../examples/java) the example java scripts and corresponding class
files that are part of the plplot.examples package into
$prefix/share/plplot5.3.1/java/plplot/examples. For more details about the
examples, please see ../../examples/java/README.javademos or the installed
version of that file in $prefix/share/plplot$version/examples/java/. Copies of
the java files are also in this directory for convenience.
At the end of the install process all the files in
$prefix/share/java/plplot/ are bundled into a jar file
$prefix/share/java/plplot.jar and the plplot directory is
deleted.

Here is how to add a new function to the Java API for PLplot:

Edit ../swig-support/plplotcapi.i.  (If you want just a Java interface to
this PLplot function and not a python or any other interface, then wrap your
entry with #ifdef SWIG_JAVA ... #endif, but ordinarily you will be adding
functions for all swig-generated interfaces so you will not use a java-only
#ifdef at all.) Find a function with the same argument types that you have
in your new function, and copy those argument types and argument names
*EXACTLY*.  The typedefs in plplotjavac.i process argument type and argument
name patterns to produce the required java files and java interface code. So
give it the same pattern (white space doesn't matter), and you will get the
same argument processing that worked before for the old function. In the
unlikely event that you have a new pattern of argument list, then it is time
to dig into the Java interface documentation for swig.

Finally, hand edit PLStream.java to add typically 3 lines of boiler-plate
code for each added function copying the appropriate pattern from other
functions.

Limitation of the current swig-generated Java interface to PLplot:

* A user-friendly (UF) wrapper to the raw java interface should be made to
give us a variety of different simplified argument lists similarly to the
way plplot.py wraps the plplotc extension module.  I assume that java is
more powerful than C so that it makes sense to write the UF interface in
java rather than C. Note the raw interface only allows two-dimensional xg,
and yg arrays to plcont, plshades, and plshade. The options of no xg, yg,
and one-dimensional xg, and yg should also be allowed for the UI interface.
Also note the raw interface to plparseopts demands you must be explicit
about ORing in pls.PL_PARSE_NOPROGRAM to the parse mode parameter.  This
idiosyncrasy of Java should be hidden for the UF interface.

Alan W. Irwin (2009-12-01)