subversion/bindings/javahl/README

About JavaHL
------------

JavaHL provides a (mostly native, using JNI and javah) implementation of
a high level Java API for Subversion, which was originally targeted for
implementors of GUI clients and IDE plug-ins for Subversion.  JavaHL
currently provides a minimal-but-complete set of APIs which expose the
core Subversion C API to Java.  It requires a JRE 1.8+ (runtime).

It is currently quite mature, and can be considered for production use.


Build system
------------

JavaHL should compile and run under Linux, Win32, and Mac OS X with
JDK 1.8+ and a C++ compiler with a complete implementation of
C++98 (for example, GCC 3.2 and older cannot compile JavaHL 1.9+).

Its build will produce both a native library (libsvnjavahl-1.so on Unix
or libsvnjavahl-1.dll on Win32) and a platform independent archive of
Java bytecode (svn-javahl.jar).

To build JavaHL on non-Win32 platforms, just add "--enable-javahl" to
the configure script's parameters.  "--with-jdk" can be provided to
specify the path to a jdk.  "--enable-maintainer-mode" will compile
Java bytecode with debugging information.

The following make targets are provided:

javahl                build JavaHL
install-javahl        install JavaHL
check-javahl          run JavaHL tests
check-all-javahl      run all JavaHL tests, including tests for
                      deprecated backward-compatibility APIs.

(In order to run check-javahl, you must have specified a path to a JUnit
jar file with --with-junit when running configure; JUnit version 4.11
has been tested.  JUnit can be downloaded from https://junit.org/ .)


MacOS X:

After building libsvnjavahl.dylib, you must rename it to
libsvnjavahl.jnilib. Make install-javahl creates a symbolic
link with the appropriate name.

Additionally, it should probably be installed in
/Library/Java/Extensions instead of wherever the build system chose to
install it; patches to our build system to do this automatically are
welcome.

Windows:

In MS Visual Studio, make sure that the bin directory of the JDK is in
your path and that the include and the include\win32 directories are
in the include path.

To build, use the project/target "__JAVAHL__" of the main subversion
workspace.  The private project/workspace is not used anymore.


Success stories
---------------

Subclipse, Eclipse IDE plug-in
<https://marketplace.eclipse.org/content/subclipse/>
SmartSVN, cross-platform Subversion client (https://www.smartsvn.com/)


Why not 100% pure Java?
-----------------------

Though 100% pure Java is often preferred by Java programmers, such an
implementation would require significant effort to create, debug, and
update a duplicate of _at least_ the entire Subversion client libraries
in Java, taking the maintainers' time away from improving Subversion
itself.  The official Subversion C libraries are the reference
implementation of a Subversion client's logic, and are the most robust
client implementation available.  Using JNI allows the effort that has
gone into the existing libraries to be leveraged from Java, and allows
developer time to me more efficiently spent on further development of the
underlying libraries shared by many implementations.

The SVNKit <https://svnkit.com/> client library (formerly known as
JavaSVN) is a 100% pure Java implementation, and attempts to track the
latest changes to Subversion's core libraries; however, this is an
independent project and the Subversion project cannot make any promises
as to its compatibility with the official Subversion implementation.


TODO
----

o Transition all of the implementation to the new-style jniwrapper.
o Expose more of Subversion's core libraries through JNI.
o More JUnit test cases.
o Refactor the JUnit tests to use the improved features of JUnit 4.
o Improve JavaDoc and coding style.