I had quite a few problems initially deploying Jackrabbit on Websphere 5.1, so I thought I would document the process to help anyone else who wants to deploy on this environment. I did this using jackrabbit 1.3 on Websphere 5.1, so I can’t guarantee it will work the same on other versions.
Admittedly I did not know much about using the JCA (Java Connector Architecture) before I started, so I attribute some of my difficulties to my own ignorance.
If you are interested in a good example of how to use JCA connectors on Websphere, there is a good tutorial available at: http://www-128.ibm.com/developerworks/ibm/library/i-supply1a/
Initially I got Jackrabbit working in WebSphere by deploying it as a Resource Environment Provider in a similar manner as described here: http://epesh.blog-city.com/jackrabbit_and_glassfish_v2.htm
Only, this is not a good way of deploying it as multiple web apps are not in fact sharing the same repository in memory in this model, and running multiple repositories against the same physical filesystem is not supported in Jackrabbit. The correct way of deploying a shared jackrabbit repository in Websphere is as a resource adapter. This provides a single shared jackrabbit instance and also provides things like connection pooling for connections to jackrabbit. This can then be accessed by looking it up via JNDI.
I also have to admit to a certain ignorance about basic JNDI concepts, but the Sun tutorial really helped me to understand it better: http://java.sun.com/products/jndi/tutorial/
Here is the steps I took to get it working:
1) Edit the ra.xml in the resource adapter
- Download the jackrabbit-jca-1.3.rar file from the jackrabbit site
- Unzip the contents to a directory
- Find the ra.xml file inside the META-INF directory
- Edit it to read as follows:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE connector PUBLIC
'-//Sun Microsystems, Inc.//DTD Connector 1.0//EN'
'http://java.sun.com/dtd/connector_1_0.dtd'>
<connector>
<display-name>Jackrabbit JCR Adapter</display-name>
<vendor-name>Apache.org</vendor-name>
<spec-version>>1.0</spec-version>
<eis-type>JCR Adapter</eis-type>
<version>>1.0</version>
<license>
<description>ASF</description>
<license-required>false</license-required>
</license>
<resourceadapter>
<managedconnectionfactory-class>
org.apache.jackrabbit.jca.JCAManagedConnectionFactory
</managedconnectionfactory-class>
<connectionfactory-interface>
javax.jcr.Repository
</connectionfactory-interface>
<connectionfactory-impl-class>
org.apache.jackrabbit.jca.JCARepositoryHandle
</connectionfactory-impl-class>
<connection-interface>
javax.jcr.Session
</connection-interface>
<connection-impl-class>
org.apache.jackrabbit.jca.JCASessionHandle
</connection-impl-class>
<transaction-support>NoTransaction</transaction-support>
<config-property>
<config-property-name>HomeDir</config-property-name>
<config-property-type>java.lang.String</config-property-type>
</config-property>
<config-property>
<config-property-name>ConfigFile</config-property-name>
<config-property-type>java.lang.String</config-property-type>
</config-property>
<authentication-mechanism>
<authentication-mechanism-type>
SimpleCredentials
</authentication-mechanism-type>
<credential-interface>
javax.jcr.SimpleCredentials
</credential-interface>
</authentication-mechanism>
<reauthentication-support>false</reauthentication-support>
</resourceadapter>
</connector>
Now, re-zip the directory and name it jackrabbit-jca-1.3.rar
2) Deploy the Resource Adapter
- To deploy your newly edited resource adapter in Websphere into the admin console:
- Click Resources > Resource Adapters
- Click “Install RAR”
- Click browser and select your RAR file created above
- Click “Next”
- Leave all the boxes empty on the next page and click “OK”
- If you get a ConfigServiceException at this point you may need to set some config manually – scroll down to the bottom of this entry for details on how to do this
- Go back to Resources > Resource Adapters
- Click “New”
- Give your new resource a name (I used Jackrabbit)
- Select jackrabbit-jca-1.3.rar from the archive path drop-down
- Click “Apply”
3) Create a connection factory
- Scroll down and click “J2C Connection Factories”
- Click “New”
- Give your factory a name (I went for Jackrabbit again)
- Type the jndi name you want to use (I went for jcr/local)
- Select “BASIC_PASSWORD” from the authentication preference
- Set both authentication aliases to (none)
- Set mapping-configuration alias to DefaultPrincipalMapping
- Click “Apply”
- Scroll down and click “Custom Properties”
- Set the values of HomeDir and ConfigFile to appropriate values
- Save your changes to the master configuration.
4) Make use of your repository
- You should now be able to make use of your repository using code something like this:
InitialContext ctx = new InitialContext();
repository = (Repository) ctx.lookup("jcr/local");
SimpleCredentials cred = new SimpleCredentials("login","password".toCharArray());
Session session = repository.login(cred, null);
Workspace workspace = session.getWorkspace();
Potential Problems
I thought I would mention some of the problems I had setting this up so you can avoid making similar mistakes.
Firstly, make sure your repository.xml is correct, and especially make sure that you have the LoginModule element included – something like:
<loginmodule class="org.apache.jackrabbit.core.security.SimpleLoginModule">
<param name="anonymousId" value="anonymous"/>
</loginmodule>
Note – the reason I had to specify ‘NoTransaction’ in the config is to work around a bug that I discovered which I have reported to the development team – more details here: http://issues.apache.org/jira/browse/JCR-861
UPDATE: Looks like as of version 1.4 my bug has been fixed 
ConfigServiceException
In some cases when deploying Jackrabbit on WebSphere I came across this exception:
com.ibm.websphere.management.exception.ConfigServiceException
at com.ibm.ws.management.configservice.WorkspaceHelper
.getTemplate(WorkspaceHelper.java:274)
at com.ibm.ws.management.configservice.WorkspaceHelper
.getTemplate(WorkspaceHelper.java:208)
at com.ibm.ws.management.configservice.MOFUtil.newRefObject(MOFUtil.java:78)
at com.ibm.ws.management.configservice.MOFUtil.createRefObject(MOFUtil.java:1053)
at com.ibm.ws.management.configservice.MOFUtil.createRefObject(MOFUtil.java:314)
at com.ibm.ws.management.configservice.DocAccessor
.createRootConfigObject(DocAccessor.java:137)
...etc...
To get over this:
First – follow the instructions above, and when you get the error above, do the following:
1) Create a Resource Adapter
- In the admin console, click Resources > Resource Adapters
- Click New
- Give your adapter a name (e.g. jackrabbit)
- In the Archive Path, choose to specify the path, and type:
${CONNECTOR_INSTALL_ROOT}/jackrabbit-jca-1.3.rar
Click Apply
Save your changes to the master repository
2) Edit the Resource Adapter config manually
– Find the resources.xml file for your server instance, this should be in a path like this:
[base_dir]/config/cells/[cellname]/nodes/
[nodename]/servers/[servername]/
Open the file, and find the section that looks like this:
<resources.j2c:J2CResourceAdapter xmi:id="J2CResourceAdapter_1179115582274" name="jackrabbit"
archivePath="${CONNECTOR_INSTALL_ROOT}/jackrabbit-jca-1.3.rar">
<propertySet xmi:id="J2EEResourcePropertySet_1179115582274">
<resourceProperties xmi:id="J2EEResourceProperty_1179115582274"
name="TransactionResourceRegistration" type="java.lang.String" value="dynamic"
description="Type of transaction resource registration (enlistment). Valid values are
either "static" (immediate) or "dynamic" (deferred)."/>
<resourceProperties xmi:id="J2EEResourceProperty_1179115582275"
name="InactiveConnectionSupport" type="java.lang.Boolean" value="true"
description="Specify whether connection handles support implicit reactivation. (Smart
Handle support). Value may be "true" or "false"."/>
</propertySet>
</resources.j2c:J2CResourceAdapter>
And change the resourceProperties elements:
<resources.j2c:J2CResourceAdapter xmi:id="J2CResourceAdapter_1179115582274" name="jackrabbit"
archivePath="${CONNECTOR_INSTALL_ROOT}/jackrabbit-jca-1.3.rar">
<propertySet xmi:id="J2EEResourcePropertySet_1179115582274">
<resourceProperties xmi:id="J2EEResourceProperty_1179115582274"
name="HomeDir" type="java.lang.String"/>
<resourceProperties xmi:id="J2EEResourceProperty_1179115582275"
name="ConfigFile" type="java.lang.String"/>
</propertySet>
</resources.j2c:J2CResourceAdapter>
Restart WebSphere so the changes get picked up and go back to step 3 in the instructions at the start of this post.