JBoss.orgCommunity Documentation

Chapter 13. Switch from JackRabbit to ModeShape

Guvnor supports running on either JackRabbit and ModeShape as the underlying 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-eap-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/beans.xml file to switch over to ModeShape. Comment out the JackRabbit section and uncomment the ModeShape section:


  <guvnorRepository:GuvnorBootstrapConfiguration>
    <s:modifies/>

    <!-- JackRabbit  -->
    <guvnorRepository:properties>
      <s:entry><s:key>org.drools.repository.configurator</s:key><s:value>org.drools.repository.jackrabbit.JackrabbitRepositoryConfigurator</s:value></s:entry>
      <!--  the root directory for the repo storage the directory must exist. -->
      <!--<s:entry><s:key>repository.root.directory</s:key><s:value>/opt/yourpath</s:value></s:entry>-->
    </guvnorRepository:properties>

    <!-- ModeShape -->
    <!--
      passwords for the background users (logInAdmin and mailman), these need to match the setting
      you provided for JAAS (used by ModeShape only).
    -->
    <!--<guvnorRepository:properties>-->
      <!--<s:entry><s:key>org.drools.repository.configurator</s:key><s:value>org.drools.repository.modeshape.ModeShapeRepositoryConfigurator</s:value></s:entry>-->
      <!--<s:entry><s:key>org.modeshape.jcr.URL</s:key><s:value>jndi:jcr/local?repositoryName=brms</s:value></s:entry>-->
      <!--<s:entry><s:key>org.drools.repository.secure.passwords</s:key><s:value>false</s:value></s:entry>-->
      <!--<s:entry><s:key>org.drools.repository.logInAdmin.password</s:key><s:value>logInAdmin</s:value></s:entry>-->
      <!--<s:entry><s:key>org.drools.repository.mailman.password</s:key><s:value>mailman</s:value></s:entry>-->
    <!--</guvnorRepository:properties>-->

  </guvnorRepository:GuvnorBootstrapConfiguration>

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:IdentityImpl>
    <s:modifies/>

    <!-- No real authentication: demo authentication for demo purposes -->
    <security:authenticatorClass>org.drools.guvnor.server.security.DemoAuthenticator</security:authenticatorClass>

    <!-- JAAS based authentication -->
    <!--<security:authenticatorName>jaasAuthenticator</security:authenticatorName>-->

    <!-- IDM based authentication (supports LDAP, see Seam 3 and PicketLink IDM documentation) -->
    <!--<security:authenticatorClass>org.jboss.seam.security.management.IdmAuthenticator</security:authenticator>-->
  </security:IdentityImpl>

  <!--<security:jaas.JaasAuthenticator>-->
    <!--<s:modifies/>-->
    <!--
      The following one will use the jaas configuration called "other",
      which in jboss AS means you can use properties files for users.
    -->
    <!--<jaasConfigName>other</jaasConfigName>-->
  <!--</security:jaas.JaasAuthenticator>-->

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.