Launching a JCR Repository inside Equinox
Today I was contacted with a request to setup the
jcr/jackrabbit-server bundle in an OSGi framework such that a JCR Repository is being started and can be accessed from within the OSGi framework and over RMI from outside of the framework. It happens to be that the framework of choice has been Equinox.
So, to better support I decided to setup my own Equinox framework and install required bundles.
Getting the Equinox Framework
First of all, you need the Equinox OSGi framework. You can grab this from the Equinox download page at http://download.eclipse.org/eclipse/equinox/. I decided to use the latest release stuff, which at the time of this writing is 3.3.2. So I downloaded the framework jar file org.eclipse.osgi_3.3.2.R33x_v20080105.jar
One this has been downloaded, it can easily be started from the command line. As I required the console prompt, I added the
-console command line option:
The console gives you the
osgi> prompt to which I entered a first
ss command to get a short status of installed bundles. This lists just the system bundle with ID 0. This console is used by us to interactively install and start additional bundles, until we get a running Jackrabbit Repository.
To get a list of available commands just enter the
help command. Some commands which we will use later on are :
- ss – display a short status list of installed bundles
- status – display a long status list of installed bundles
- bundle <id> – display detailed information on the bundle with the given
<id>. This list includes registered and used services, import and export packages and some more information.
- install <url> – installs a bundle from the given
<url>. Note that this must be a real URL, that is to install a file from the local filesystem, the
file:protocoll must be specified.
- start <id> – starts the bundle with the given
- stop <id> – stops the bundle with the given
- uninstall <id> – uninstalls the bundle with the given
First we need to install OSGi Compendium Services bundles:
- The Compendium Services API bundle
- A LogService implementation
- A Configuration Admin Service implementation
- A Declarative Services implementation
The Compendium Services API bundle
We chose to mainly use Equinox implementations, so we get the org.eclipse.osgi.services_3.1.200.v20070605.jar bundle to install the OSGi Compendium Services API:
Note that bundles are not automatically started after the installation. Therefore we have to manually start the bundles after the installation. This manual start is only required after the installation. On framework restarts all bundles, which were started when the framework was last shutdown, are automatically restarted.
A LogService implementation
We continue with the LogService. Here we could of course also choose to use the Equinox implementation. But as I know, that Jackrabbit uses SLF4J for logging and some other components use log4j and Jakarta Commons Logging, I strongly suggest to use the LogService implementation from the Sling project. This bundle unifies all logging requests from the OSGi LogService and the SLF4J, log4j and Jakarta Commons Logging API into a single log channel. This makes problem traking much easier.
The Sling LogService implementation is available from the Apache Snapshot repository and may be directly installed into the OSGi framework:
We installed the LogService implementation early in the process to be able to get some logging in the future processing. You may have noticed, that LogService already kicked in writing logs to stdout. In the further steps you will notice, that each bundle installation and start will be accompanied with log messages.
A Configuration Admin Service implementation
Core configuration to launche the Jackrabbit repository is maintained using the OSGi Configuration Admin Service. For the moment this configuration just encompasses the filesystem location of the repository and the path to the repository configuration file. In the future this may be extended if configuration options for Jackrabbit may change.
For the sake of using Equinox bundles, lets take the Equinox implementation of the Configuration Admin Service available from org.eclipse.equinox.cm_3.2.0.v20070116.jar.
A Declarative Services implementation
The last OSGi Compendium Service implementation we need is Declarative Services. I of course also tried the Equinox implementation of this specification. But unfortunately the Sling Jackrabbit Repository bundle cannot be used with this implementation. This is of course not a good thing and we will try to find out, what is wrong here. This issue is tracked as SLING-408. So we take the Apache Felix implementation from org.apache.felix.scr-1.0.0.jar.
The next (and final) big step is to install and start the bundles required to embed and start the Jackrabbit repository. In short, we are going to install the following bundles:
- Jackrabbit Commons and Jakarta Commons Collections Bundles – Library bundles by the rest of the Jackrabbit bundles.
- Sling JCR API and Base Bundles – These bundles export the JCR API and the base implementation for session pooling on which the embedded Jackrabbit Repository of Sling is based.
- Jackrabbit Server and Text Extractors Bundle – The actual embedded Jackrabbit repository bundle and a library used for extended indexing and query support.
Commons Collections and Jackrabbit Commons
We start with the helper libraries Jakarta Commons Collections and Jackrabbit Commons. Fortunately the latest releases of both libraries already come built ready as OSGi bundles. So we just grab the respective libraries from the Maven 2 repository and install them as is:
Oops ! Bundle 7, the Jackrabbit Commons library bundle, fails to start. The reason for this is, that this library depends on the Content Repository for Java (JCR) API classes, which have not be installed yet and which are not available from the environment either.
This is not actually a problem because the Sling JCR API bundle exports just these packages. So lets just continue with the next steps.
Sling JCR API and Base Bundles
The Sling JCR API and Base Bundles can be installed directly from the Apache Snapshot Repository, which we just do now:
Now that we have installed the API and base bundles, we see that bundle 7 is now in the RESOLVED state. That is, the imports could now be completely resolved. In fact, the bundle has been resolved because the JCR Base Bundle (Bundle 9) requires the classes exported by bundle 7. So we can now start bundle 7:
Jackrabbit Repository Bundles
Finally we install and start the Jackrabbit Repository and Text Extractor Bundles:
Wow! After starting the Text Extractors and Jackrabbit Server bundles, the repository is immediately starting and is then available as an OSGi service of type
javax.jcr.Repository and over RMI using the RMI URL
That's it. Now, you can install more bundles and enjoy the fun of programming the Content Repository for Java API.
This is a complete list of the links to the files we needed during download. Note, that some links are behind a mirroring scripts (mostly the Equinox download links).
Equinox OSGi Framework
OSGi Compendium Services API
Sling OSGi LogService Implementation
Equinox OSGi Configuration Admin Service Implementation
Felix OSGi Declarative Service Implementation
Jakarta Commons Collections
Sling JCR API Bundle
Sling JCR Base Bundle
Sling Jackrabbit Text Extractors Bundle
Sling Jackrabbit Embedded Repository Bundle