Chapter 12. Switch from JackRabbit to ModeShape

Guvnor supports running on either JackRabbit and ModeShape as the underlaying JCR-2.0 implementation. By default Guvnor ships using JackRabbit. However if you want to switch to using ModeShape then you need to install ModeShape as a service in JBossAS-5.x. Check the ModeShape project and download and install ModeShape 'kit' version 2.5.0 or later. After installing the kit, you should have a modeshape-service.jar directory in your deploy directory. Since ModeShape 2.5.0 only support deployment to JBoss-5.x, make sure to also use the guvnor-5.2.0-jboss-as-5.1.war. Now we can remove some jars from the guvnor WAR that are no longer needed, and in fact will cause classloading issues if you don't remove them:

[localhost]$ rm -f WEB-INF/lib/jackrabbit-*
[localhost]$ rm -f WEB-INF/lib/hibernate-* WEB-INF/persistence-api-1.0.jar WEB-INF/lucene-*.jar
[localhost]$ rm -f WEB-INF/lib/jcr-2.0.jar

Next you need to edit the WEB-INF/components.xml file to switch over to ModeShape. Comment out the JackRabbit section and uncomment the ModeShape section:


<component name="repositoryConfiguration">

   <!-- JackRabbit

   <property name="properties">

      <key>org.drools.repository.configurator</key>

      <value>org.drools.repository.jackrabbit.JackrabbitRepositoryConfigurator</value>

   -->

   <!--  the root directory for the repo storage the directory must exist. -->

   <!--  <key>repository.root.directory</key><value>/opt/yourpath</value>  -->

   <!--

   </property>

   -->

   <!-- ModeShape

      passwords for the background users (admin and mailman), these need to match the setting

      you provided for JAAS (used by ModeShape only).

   -->

   <property name="properties">

      <key>org.drools.repository.configurator</key>    

      <value>org.drools.repository.modeshape.ModeShapeRepositoryConfigurator</value>

      

      <key>org.modeshape.jcr.URL</key>                 

      <value>jndi:jcr/local?repositoryName=repository</value>

      

      <key>org.drools.repository.secure.passwords</key>

      <value>false</value>

      

      <key>org.drools.repository.admin.password</key>

      <value>admin</value>

      

      <key>org.drools.repository.mailman.password</key>

      <value>mailman</value>

   </property>

</component>

Note that you can use encrypted passwords by setting the org.drools.repository.secure.passwords setting to true. To encrypt a password use:

[localhost]$ java -cp client/jboss-logging-spi.jar:common/lib/jbosssx.jar org.jboss.resource.security.SecureIdentityLoginModule <password>

ModeShape does not support 'trusted' access like JackRabbit does, and by default uses JAAS for authentication and authorization. For more detail on Guvnor and Security see the next section about Security. To use JAAS and the modeshape policy comment out the defaultAuthenticator section and uncomment the jaas-configuration section, and change the policy name from 'other' to 'modeshape':


<!-- SECURITY IDENTITY CONFIGURATION -->

<!--

    default (will take any username, useful if you want to keep track of

    users but not authenticate

<security:identity authenticate-method="#{defaultAuthenticator.authenticate}" />

-->

<!--

    NO authentication. This will bypass the login screen when you hit the

    app. Everyone is "guest"

    <security:identity

    authenticate-method="#{nilAuthenticator.authenticate}"/>

-->

<!--

    FOR EXAMPLE: the following one will use the jaas configuration called

    "other" - which in jboss AS means you can use properties files for

    users:

-->

    <security:identity authenticate-method="#{authenticator.authenticate}"

    jaas-config-name="modeshape"/>

<!--

    as JAAS is used you can use container specific ones to link up to your

    login services, eg LDAP/AD etc

-->

You may have noticed the settings of two passwords in the modeshape property settings for the 'admin' and 'mailman' users. These users are used by guvnor to perform background tasks. Now that we are no longer allowing for anyone to run as 'guest', we need to ass these two users to the modeshape users and roles files. Open the conf/props/modeshape-users.properties file and add the mailman and admin users,

admin=admin
mailman=mailman

Finally open the conf/props/modeshape-roles.properties file and add the admin and mailman roles,

admin=connect,admin
mailman=connect,readonly,readwrite

By default JackRabbit uses InMemory storage, which is configured in the modeshape-service.jar/modeshape-config.xml. To change this we recommend reading the modeshape documentation. To use a referenced JNDI data source, replace the <mode:source></mode:source> segment with the following:


<mode:source jcr:name="store" mode:classname="org.modeshape.connector.store.jpa.JpaSource"

mode:dataSourceJndiName="your JNDI name"

mode:model="Simple"

mode:dialect="org.hibernate.dialect.HSQLDialect"

mode:referentialIntegrityEnforced="true"

mode:largeValueSizeInBytes="10000"

mode:retryLimit="3"

mode:compressData="false"

mode:predefinedWorkspaceNames="default,system"

mode:showSql="false"

mode:autoGenerateSchema="update"

mode:creatingWorkspacesAllowed="true"

mode:defaultWorkspaceName="default" />

Alternatively you can connect directly to a JDBC data source, use the same <mode:source> fragment as for JNDI except replace the mode:dataSourceJndiName attribute with these attributes:


mode:driverClassName=org.hsqldb.jdbcDriver

mode:username=sa

mode:password=

mode:url=jdbc:hsqldb:mem:target

mode:maximumConnectionsInPool=5

For purposes of illustration, the HSQL DB is being used, but simply replace the attribute values with the appropriate driver class name, username, password, and database URL. Don't forget to add a dependency to your JDBC jar, so the JDBC driver available in the classpath.