What is JavaHL?
JavaHL is a part of the Subversion project. Specifically, it is the Java language binding for the Subversion API. Subversion provides a layered API design that is delivered as native libraries (DLL's). The Subversion command line is simply one consumer of this API. The API is rich in functionality but is also maintained for backwards compatibility. This is the reason there are so many great Subversion clients and tools available, because there is a rich and stable API that provides all of the functionality you need.
Subversion is written in C to provide excellent cross platform support, but also because C produces libraries that are easy to consume from virtually any other language. The Subversion project provides and maintains language bindings for Java, Perl, Python and Ruby. The latter three are provided via the SWIG library and its ability to interface languages with native libraries. JavaHL is a "High Level" API and is provided with custom written C++ code to serve as the JNI bridge between Java code and the native libraries. This design allows us to provide a nice Java API into Subversion.
JavaHL consists of essentially four parts:
- A relatively thin layer of Java code that provides the API that consumers can talk to from Java.
- A C++ library (the JavaHL library or libsvnjavahl-1). The Java layer talks to this layer using Java Native Interface (JNI) calls. The C++ layer is where the "High Level" API is implemented. For example, Java may provide a simple API that says "Commit this list of files, using this commit message". The C++ layer takes care of memory management and performing all of the lower level Subversion API calls it takes to complete the request.
- The Subversion libraries themselves. These are the same libraries that the command line client would install and use. Also, other Subversion clients, such as TortoiseSVN or AnkhSVN would also use these same libraries.
- Subversion library dependencies. Subversion needs a number of external libraries to operate. The biggest is the Apache Portable Runtime (APR), but it also needs libraries like Neon for the HTTP client and OpenSSL to handle encryption etc.
All four of these layers are needed for JavaHL to work and be used in an application.
Why does Subclipse need JavaHL?
Subclipse is written in Java, so it needs to use the JavaHL library to be able to use the Subversion API. Subclipse includes the Java layer of JavaHL. If you look at the previous entry, you see that JavaHL needs three other layers for it to actually work (essentially the native libraries).
Why doesn't Subclipse provide everything I need to use JavaHL?
On Windows we do provide everything you need. We cannot do it, for technical reasons, on any other operating system. It has to do with how native libraries are loaded on different operating systems. There is no way to deliver all three of the native layers in a way that the libraries will be found when used from Java and Eclipse. The only way for them to be found is if they are properly installed in the specific locations those operating systems look for libraries. Windows library loading has a quirk we are able to exploit from Java. Basically, we can load the dependencies in reverse order and then as we load each library since its dependencies are already loaded into memory, the loader does not try to load them.
How do I get JavaHL?
This will vary by operating system:
Windows 32-bit
Subclipse includes everything you need. You just have to be sure to have installed the JavaHL plugin from our Eclipse update site.
Windows 64-bit
As of the Subclipse 1.8.x releases, native 64-bit Windows binaries are included with Subclipse so it includes everything you need. For earlier releases of Subclipse follow these instructions:
If you are using a 32-bit JVM, then Subclipse should just work. If you use a 64-bit JVM then you need to provide a 64-bit version of JavaHL. One such distribution is SlikSVN which you can get here:
http://www.sliksvn.com/en/download
With that package installed, Subclipse should find JavaHL on PATH and just work.
SASL on Windows
If you are using SASL for authentication with the svn:// protocol you need additional Windows binaries. SASL requires auth plugins to be installed and configured in the registry. Since we use the Windows DLL's that ?CollabNet provides the best way to handle this is to install the Windows command line client that ?CollabNet provides. The installer will install the additional SASL plugins and configure the Windows registry. The JavaHL binaries will automatically make use of these plugins once they are installed. You can download the installer from:
http://www.open.collab.net/downloads/subversion/
OS X
The easiest thing to do is download and install the OSX package that is provided on openCollabNet. This installs Subversion, including the JavaHL library, into /opt/subversion. It then makes a symlink for the JavaHL library into /Library/Java/Extensions. This is a global location that the OSX JVM looks in when loading libraries via JNI. So basically, if you install this package, there is nothing else you need to do. It is OK to install this after you have installed Subclipse. These binaries are Universal including 32 and 64-bit variants which can be important if you use different JVM's.
?MacPorts also provides an easy Subversion and JavaHL package, however on Snow Leopard ?MacPorts is still compiling these packages as simple 32-bit binaries. If you use the default Snow Leopard JVM which is 64-bit you will get an error like this when JavaHL is loaded:
Failed to load JavaHL Library.
These are the errors that were encountered:
no libsvnjavahl-1 in java.library.path
no svnjavahl-1 in java.library.path
/opt/local/lib/libsvnjavahl-1.0.0.0.dylib: no suitable image found. Did find: /opt/local/lib/libsvnjavahl-1.0.0.0.dylib: mach-o, but wrong architecture
Note the error about wrong architecture. This is because the 64-bit JVM cannot load a 32-bit native library. The ?CollabNet binaries for OSX do not have this problem because they include both 32-bit and 64-bit versions.
Linux
This is the most complicated because there are so many distributions.
CollabNet provides a client RPM for Red Hat that includes JavaHL (http://www.collab.net/downloads/subversion/redhat.html). In my experience, this RPM works on other Linux distributions. On RPM-based distributions like CentOS or Suse, it should just be a matter of installing the RPM. On Debian-based systems, I was able to use the alien package to install the RPM.
Of course many Linux distributions, such as Ubuntu, do a good job of providing up to date Subversion packages, and most of these now provide JavaHL as well. Typically, the JavaHL library is in a separate package that is dependent on the main Subversion package. In Debian/Ubuntu the package name is libsvn-java so you can just run this command to install the library:
Once you have the library installed, you still have to tell Java (when used for Eclipse) where to find the library. The JVM on Linux does not look in a lot of the standard locations to find the libraries. This could obviously change in the future. For example, Debian/Ubuntu uses a standard location of /usr/lib/jni for libraries to be used from Java. However, the Sun JVM does not currently look in this location. The easiest way to tell Java where to find the JavaHL library is to specify the following when starting the JVM:
-Djava.library.path=/usr/lib/jni
CollabNet Subversion installs into /opt/CollabNet_Subversion. So if you are using that package, you need this:
-Djava.library.path=/opt/CollabNet_Subversion/lib
The name of the library is libsvnjavahl-1.so. The path you specify should contain this file.
Eclipse provides its own mechanism for providing this setting. Eclipse comes with a file named eclipse.ini. This file is looked at when the Eclipse launcher starts the JVM and appends settings to the JVM when launching it. Specifically, you should see a line that says "-vmargs". Add a newline after this line and insert the above line to pass the setting the JVM needs. Each argument needs to be on its own line, so be sure to add a new line and then put the entire string above on its own line. Here is an example of this file from Eclipse 3.4:
-showsplash
org.eclipse.platform
-framework
plugins/org.eclipse.osgi_3.4.0.v20080605-1900.jar
-vmargs
-Djava.library.path=/opt/CollabNet_Subversion/lib
-Dosgi.requiredJavaVersion=1.5
-Xms40m
-Xmx512m
-XX:MaxPermSize=256m
Troubleshooting
You can tell if JavaHL has loaded by looking at the Eclipse preferences under Team > SVN. If the library loaded correctly you will see the version of the library, otherwise it will show "Not available". If a version of the library that is too old to use is found, then we do not load the library and it will show as "Not available".
A common problem that Linux users have run into is that they edit the eclipse.ini file to point to the path where the library is loaded but it still does not work. Something to check if this happens to you is whether the settings in the INI file are being used. A lot of users customize the launcher they create to run Eclipse and they include some command line options for starting Eclipse. When you do this, it appears that the Eclipse launcher does not use any of the settings in the INI file. The easiest way to see this is happening is to do Help > About in Eclipse and then choose Configuration Settings. If you look through the settings you should eventually be able to see the command line settings used for the JVM. If you do not see the java.library.path line then it was not used.
Client loads OK on Linux, but locks/crashes Eclipse on first operation
There is currently a bug in the new support for GNOME keyring in Subversion 1.6. It works OK when using the command line, but not when other users of the libraries use it. Until this is fixed, you can workaround the problem by turning off this feature. To do this, open the file ~/.subversion/config and add the following:
[auth]
### Set password stores used by Subversion. They should be
### delimited by spaces or commas. The order of values determines
### the order in which password stores are used.
### Valid password stores:
### gnome-keyring (Unix-like systems)
### kwallet (Unix-like systems)
### keychain (Mac OS X)
### windows-cryptoapi (Windows)
password-stores =
The empty value for "password-stores" disables the feature. Passwords will be stored in plain text in the auth folder as with all previous version of Subversion.
Testing JavaHL Library
If all of the above has not helped and you are having problems getting the JavaHL library to load or run, it can help to run the Subversion JavaHL JUnit tests on your installation. Typically, this will give the same errors you get in Subclipse, but it can be easier to perform trial and error and diagnose the problem.
To make it easy to run the tests, we have bundled up the Subversion tests, JUnit and the JavaHL classes into a single JAR file. You can download the tests for Subversion 1.6 with the following link:
javahltests.jar
This JAR file will only work with the Subversion 1.6.x version of the JavaHL libraries. To run the tests do the following:
Create a new folder and copy the JAR file into it. Then open a terminal and cd to the folder you created and run:
$ java -jar javahltests.jar
.........................................
.........
Time: 145.805
OK (50 tests)
The tests create a bunch of repositories and working copies, so run these from a folder you can easily delete or cleanup. Also, you will want to be sure you run the tests using the same JVM that you are using for Eclipse. Finally, you will need to make sure the JavaHL library is on your PATH. So you will probably need to run it something like this:
$ java -Djava.library.path=/opt/CollabNet_Subversion/lib -jar javahltests.jar
.........................................
.........
Time: 145.805
OK (50 tests)
