Subversion Java integration
		     ===========================

$LastChangedDate$


Contents:

     I. STATUS
    II. PREREQUISITES
   III. WHY INTERFACES?
    IV. WHY NOT 100% PURE JAVA?
     V. WHY SWIG?
    VI. TODO


I.     STATUS

       A SWIG-based JNI implementation of Java bindings for Subversion
       are under development. They can be built via the
       "swig-java-lib swig-java-java" targets of the source tree's
       top-level make file.  If you don't have such a Makefile, see
       the INSTALL document in the same directory for further
       instructions.

       The Subversion SWIG/Java bindings still require extensive
       development to be reach a functional state.  Consumption by end
       users is not yet advised.  Interest by developers is greatly
       appreciated, and should be directed to Subversion's dev@
       mailing list.

       Alternate Java bindings for Subversion, JavaHL (based on the
       Sun JDK's javah), exist and are already in use by Subclipse
       <http://subclipse.tigris.org/>.  Years ago, hand-coded JNI
       bindings were initiated by Alexander Mueller (xela), with the
       intent of producing a desktop GUI client.  They were eventually
       discarded in favor of a C++/wxWindows implementation which
       wraps the C reference libraries.  Developers of the SWIG/Java
       implementation are encouraged to refer to JavaHL and xela's
       initial work for guidance.


II.    PREQUISITES

       Subversion's SWIG/Java bindings support JRE version 1.3 and
       higher to run, and JDK 1.3 or higher to build.  To run, it
       requires that the path to Subverion's native libraries are in
       Java's java.library.path (e.g. specified via a
       -Djava.library.path=... argument to the JVM).


III.   WHY INTERFACES?

  A.   They present an API which is familiar to Java programmers,
       regardless of the implementation generation method
       (e.g. hand-coded, SWIG, etc.).

  B.   They will allow for the possibility of multiple sets of Java
       bindings for Subversion, all presenting an uniform API.


IV.    WHY NOT 100% PURE JAVA?

       tigris.org's C library is the reference implementation of a
       Subversion client's logic, and is the most robust client
       implementation available.  An alternative to its rapidly
       maturing code base and active developer community which is of
       similar quality would require significant effort, effort more
       efficiently contributed towards further development of the
       loadable libraries shared by all existing implementations.


V.     WHY SWIG?

       It's likely that Greg Stein has already answered this on the
       dev@subversion.tigris.org mailing list.  Search the archive
       (http://subversion.tigris.org/servlets/SearchList?list=dev) and
       fill in this space with answers of his from there.

       The main accessor class for the SWIG-generated Java code is
       org.tigris.subversion.swig.Subversion.  It consists of a set of
       static methods which wrap the raw and hard to understand
       generated code.


VI.    TODO

  A.   Adjust the build system to make the native libraries loadable.

       libapr currently isn't getting loaded properly, and once it is, we
       may experience similar problems with the other SWIG-generated native
       code (Justin Erenkrantz noted that JNI does not promise to
       auto-load undefined symbols).

       * Makefile generator should write a Makefile which somehow gets
         libapr.so auto-loaded.

       * Makefile generator should either 1) create a
         libsvn_swig_java.so which statically links in all the
         SWIG-generated C code to make loading the native library from
         Java easy.  To do this, the xxx.{lo,la} in
         java_xxx_{DEPS,OBJECTS} should basically be moved into
         libsvn_swig_java_{DEPS,OBJECTS} in build-outputs.mk.

         Or 2), the SWIG .i files would be responsible for loading
         their own native libraries:
         
           %pragma(java) jniclasscode=%{
             static {
               try {
                   System.loadLibrary("example");
               } catch (UnsatisfiedLinkError e) {
                 System.err.println("Native code library failed to load");
                 e.printStackTrace();
                 System.exit(1);
               }
             }
           %}

       Gustav Munkby (grd) proposed both these options.

  B.   Build out the unit tests run by the check-swig-java target of the
       top-level build system.

  C.   Start making the client library functional:

       * Add a file (to an existing working copy)
       * Update to a specific global revision
       * Commit a file
       * Check out a working copy
       * etc.