China
Korea
Japan
JavaHL FAQ
This page will attempt to answer some questions about the Subversion JavaHL library and its role in the CollabNet Desktop.
Contents
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
Subclipse includes everything you need. You just have to be sure to have installed the JavaHL plugin from our Eclipse update site.
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.
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 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.
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 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.
