Native support for SVN

This page describes an advanced feature of FishEye's Subversion support. It explores the technical background, and some of the issues you may encounter, if you wish to use the native JavaHL access feature.

For most users we recommend that you use the default SVNKit Subversion access client that is bundled with FishEye. You are only likely to need the native JavaHL access described on this page for certain edge case repositories.

FishEye Subversion access

FishEye interacts with Subversion repositories though a layer, defined by the Apache Subversion project, known as JavaHL. This is the high-level Java language binding for Subversion. There are two implementations of the JavaHL interface available:

Bundled SVNKit

The SVNKit implementation is a largely Java-based implementation provided by the SVNKit project. It is bundled with FishEye and is the default JavaHL implementation used. As a Java implementation it operates on all of FishEye's supported platforms.

Native JavaHL

The JNI-based implementation, coupled with a shared dynamic library, is referred to here as native JavaHL. As a native library, native JavaHL is platform-dependent. The shared library is C-based and must be compatible with the remaining Subversion client components installed on the platform. It varies across each platform and distribution.

Native vs. bundled

Given that FishEye bundles the SVNKit implementation, why might you want to use the native implementation of JavaHL? In general our recommendation is to stick with the bundled SVNKit implementation. It is the simplest to use and works in the widest variety of scenarios. Nevertheless, there are some scenarios where it may be desirable to use the native implementation, if it is available.

The two implementations have quite different characteristics – these can affect the decision about which to use. Here is a high-level list of some of the considerations we have encountered over the years:

Aspect	SVNKit - bundled with FishEye	Native JavaHL - platform dependent
Memory Usage	SVNKit uses the Java Heap. It therefore shares the heap that is being used for all FishEye's operations. It does benefit, however, from Java's garbage collection mechanism and we have not seen any memory leaks.	The native JavaHL implementation uses the native process heap and not the Java heap. It can increase the overall process memory usage but does not interfere with the Java heap usage. In some rare instances, we have seen memory leaks in the C-based JavaHL code. As FishEye is a long running service, these can cause problems over the life of the FishEye process.
Speed	In general, when using any of the Subversion network protocols, the JavaHL implementation speed is not a significant factor in the overall speed of Subversion operations as they are dominated by the network latency. Even for file:// access SVNKit is rarely the bottleneck.	If you are using file:// access to talk to a Subversion repository on the same server, then native JavaHL will most likely give the highest performance.
Compatibility	SVNKit has proven to be highly compatible with Subversion across all releases. The project is very responsive to bug reports when any differences become apparent. As an alternative implementation of JavaHL there will be differences between the SVNKit and the native Subversion JavaHL. This may affect some edge case repositories.	JavaHL uses predominantly the same code as Subversion itself so it is virtually 100% compatible.
Availability	SVNKit works on all of FishEye's supported platforms	It can be difficult to get an install of the JavaHL jar and shared library that is compatible with the version of Subversion installed on your platform.

Native JavaHL support

The native JavaHL interface and implementation naturally change with every release of Subversion. Normally these changes are incremental and backward compatible.

The compatibility matrix for recent FishEye versions is:

	SVNKit	Native JavaHL 1.6 client	Native JavaHL 1.7 client	Native JavaHL 1.8 client
FishEye 3.3
1.8 Subversion Server
1.7 Subversion Server
1.6 Subversion Server
FishEye 3.1 – 3.2
1.8 Subversion Server (not file:// access)				Unsupported
1.8 Subversion Server (file:// access)				Unsupported
1.7 Subversion Server				Unsupported
1.6 Subversion Server				Unsupported
FishEye 3.0 and earlier
1.7 Subversion Server (not file:// access)
1.7 Subversion Server (file:// access)
1.6 Subversion Server any access

Note that:

FishEye 3.1, and later, is not compatible with the JavaHL 1.6 client (or older versions) – it uses the org.apache.subversion package which is not provided in 1.6 JavaHL builds
From FishEye 3.1, you must use a 1.7 or later JavaHL library if you want native JavaHL access.

The change from Subversion 1.6 to Subversion 1.7 was much more significant and for a number of FishEye's usages of the interface, it broke compatibility.

In Subversion 1.7, the JavaHL interfaces were updated and moved from the org.tigris.subversion package to the org.apache.subversion package. This coincided with the move of the Subversion project to the Apache Software Foundation. In addition to moving the package, the interface was modernized in a number of ways:

Extended use of callbacks.
Use of Java collections rather than native arrays.
Properties were clarified as byte arrays rather than Java Strings.
Use of typed Enums rather than primitive integer and char fields.

The existing org.tigris package was retained in most 1.7 distributions and was implemented as an adapter layer over the new org.apache package classes. Unfortunately a number of incompatibilities in the adapter layer meant that FishEye could not use the 1.7 native implementation:

Property returning methods were wrapped in a String constructor to convert from the byte[] type of the new interface to the String type used in the old interface. This meant that any null returns would throw NullPointerExceptions rather than returning null Strings.
Some of the callbacks were changed from plain interfaces to being interface extensions of the corresponding callback in the new package. This changed the type definition of the callback from an untyped Map to a typed Map. This caused ClassCastExceptions because the code is expecting a map containing byte[] but the underlying code was passing in a map containing strings.

For this reason, FishEye did not support native access using the 1.7 native library prior to FishEye 3.1.

Installing JavaHL for your platform

Atlassian FishEye bundles the SVNKit library to make connecting to your Subversion repository a painless process out of the box. If you do wish to use native JavaHL, it is your responsibility to install it onto your platform. Different organizations have different operating procedures and policies regarding how and what packages they are able to install on production servers.

In some cases the distribution you use will not provide a compatible JavaHL from an official package. In this case you will either need to build everything from source yourself (hard) or use a package from a Subversion vendor. We have used packages from two vendors over time, CollabNet and Wandisco. More recently, we have found it easier to use the Wandisco packages for JavaHL support.

The following sections detail our experiences when we investigated deploying JavaHL 1.7 on a variety of platforms. This is not a definitive list or guide. It is to give you an idea of the some of the issues you are likely to encounter getting a compatible JavaHL install working on a range of platforms and distributions.

32-bit / 64-bit: The DLL file is platform dependent so it needs to match the architecture of your VM. The JAR file however, contains only metadata for the JVM about how to load the DLL so the same JAR will work across 32-bit and 64-bit operating systems as long as the subversion binaries match.

Windows 7

Windows does not include a Subversion client by default so you will need to install a Subversion package. We installed the 1.7.11 "client only" install from Wandisco.This installs Subversion, including the javahl components, in C:\Program Files\WANdisco\Subversion. It is interesting to note that the JavaHL package in this install does not include the org.tigris package adapter layer.

Ubuntu 12

Ubuntu provides pckages for both core subversion and the JavaHL library for Subversion. We installed these for Subversion 1.7.5 as follows:

sudo apt-get install subversion
sudo apt-get install libsvn-java

Unfortunately the version installed seems to have a consistent assertion failue:

java: /build/buildd/subversion-1.7.5/subversion/libsvn_subr/dirent_uri.c:1519: uri_skip_ancestor: Assertion `svn_uri_is_canonical(child_uri, ((void *)0))' failed.

We then removed the two Subversion packages from Ubuntu itself:

sudo apt-get remove libsvn-java
sudo apt-get remove subversion

We installed the Wandisco packages by downloading and running the Wandisco installer:

svn1.7_ubuntu_wandisco-precise.sh

This configures the Wandisco servers as a source of packages and installs the core Subversion install. At the time of writing this installed 1.7.11. Once installed, reinstall the javahl package:

sudo apt-get install libsvn-java

This will now come from the Wandisco package repository. The location of the shared library and JavaHL jar is:

/usr/lib/jni/libsvnjavahl-1.so
/usr/share/java/svn-javahl.jar

CentOS 6.4

If you install the Subversion packages (subversion and subversion-javahl) using yum, you will have a 1.6.11 install of Subversion which is not compatible with FishEye if you wish to use JavaHL as descibed above.

If you have previously upgraded to a version of SVN 1.7 before 1.7.11 you may see the message below in your logs. If you do, please upgrade to the Wandisco SVN 1.7 as described below:

java: /build/buildd/subversion-1.7.5/subversion/libsvn_subr/dirent_uri.c:1519: uri_skip_ancestor: Assertion `svn_uri_is_canonical(child_uri, ((void *)0))' failed.

You will need to remove the standard yum packages and use a Wandisco install, svn1.7_centos6_wandisco.sh. This installs plain subversion and configures the Wandisco servers as a source of packages. You can then use yum to install subversion-javahl. The following files are installed:

$ repoquery --list subversion-javahl
/usr/lib/libsvnjavahl-1.so
/usr/lib/svn-javahl/svn-javahl.jar
/usr/lib64/libsvnjavahl-1.so
/usr/lib64/svn-javahl/svn-javahl.jar

If you are using a 64bit JVM, use the /usr/lib64 library, otherwise use the 32bit library in /usr/lib.

JavaHL considerations when upgrading FishEye

If you are currently using SVNKit with FishEye (the default), then you do not have to do anything when upgrading to FishEye 3.1 and later. FishEye will continue to use the bundled SVNKit library.

FishEye's Admin UI now displays information about the Subversion client in use – click Server, under 'Global Settings'. With no native client, configured, the display would look like:

If you have been using native JavaHL prior to FishEye 3.1, FishEye will detect that you have configured a pre-1.7 version of JavaHL and fallback to the bundled SVNKit client and start up normally. You will see the following in the Server section of the admin UI:

You can use the FishEye admin UI to update the JavaHL client information to point FishEye to a 1.7 or later JavaHL jar and shared library. FishEye will perform some checks that the configured library supplies the correct classes. You will need to restart for the changes to take effect. If there are problems with the JavaHL library on restart, FishEye will again fallback to SVNKit. Once you have updated the configuration, FishEye will show a message that the configuration has been changed and a restart is required:

Upon restart, the display will show the operation of the native library and its version:

Page tree