2.2.4. Configuring JCR in cluster

2.2.4.1. JBoss Cache configuration

Environment requirements

Any RDBMS which supports cluster environment like MySQL, PostgreSQL, MS SQL, Oracle, DB2 or Sybase. It is necessary to notice that HSQLDB is not in this list.
Shared storage. The simplest thing is to use shared FS like NFS or SMB mounted in operation system, but they are rather slow. The best thing is to use SAN (Storage Area Network).
Fast network between JCR nodes.
Every node of cluster MUST have the same mounted Network File System with the read and write permissions on it.
"/mnt/tornado" - path to the mounted Network File System (all cluster nodes must use the same NFS).
Every node of cluster MUST use the same database.
The same clusters on different nodes MUST have the same names (for example, if Indexer cluster in workspace production on the first node has the name "production_indexer_cluster", then indexer clusters in workspace production on all other nodes MUST have the same name "production_indexer_cluster" ).

JBossTS Transaction Service and JBossCache Transaction Manager are used. This can be checked via exo-configuration.xml as bellow:


<component>

<key>org.jboss.cache.transaction.TransactionManagerLookup</key>

<type>org.jboss.cache.GenericTransactionManagerLookup</type>

</component>



<component>

    <key>org.exoplatform.services.transaction.TransactionService</key>

    <type>org.exoplatform.services.transaction.jbosscache.JBossTransactionsService</type>

    <init-params>

    <value-param>

    <name>timeout</name>

    <value>300</value>

    </value-param>

    </init-params>

</component>

Configuration requirements

Configuration of every workspace in repository must contain the following parts:

Value Storage configuration:


<value-storages>

   <value-storage id="system" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage">

      <properties>

         <property name="path" value="/mnt/tornado/temp/values/production" />    

      </properties>

      <filters>

         <filter property-type="Binary" />

      </filters>

   </value-storage>

</value-storages>

Path: Path within NFS where ValueStorage will hold its data.

Cache configuration:


<cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.JBossCacheWorkspaceStorageCache">

   <properties>

      <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-data.xml" />     

      <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" />                     

      <property name="jbosscache-cluster-name" value="JCR_Cluster_cache" />                              

      <property name="jgroups-multiplexer-stack" value="false" />

      <property name="jbosscache-shareable" value="true" />

   </properties>

</cache>

	`jbosscache-configuration`: Path to the configuration template.
	`jgroups-configuration`: Path to JGroups configuration that should not be anymore jgroups' stack definitions but a normal jgroups configuration format with the shared transport configured by simply setting the `singleton_name` jgroups property to a unique name (it must remain unique from one portal container to another). This file is also pre-bundled with templates and is recommended for use.
	`jbosscache-cluster-name`: Name of cluster group. It should be different for each workspace and each workspace component. For example: `<repository_name>-<ws_name>-<component(cache\\|lock\\|index)>`.
	`jgroups-multiplexer-stack`: Set to "false" in order to disable the multiplexer stack as now it is recommended to use the JGroups' shared transport instead.
	`jbosscache-shareable`: Set to "true" in order to share the same JBoss Cache instance between several workspaces.

Indexer configuration:

You must replace or add to the <query-handler> block, the changesfilter-class parameter equals with:


<property name="changesfilter-class" value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter"/>

Then, add the JBossCache-oriented configuration. The configuration should look like:


<query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">

   <properties>

      <property name="changesfilter-class" value="org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter" />

      <property name="index-dir" value="/mnt/tornado/temp/jcrlucenedb/production" />                       

      <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-indexer.xml" />    

      <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" />                       

      <property name="jbosscache-cluster-name" value="JCR_Cluster_indexer" />                              

      <property name="jgroups-multiplexer-stack" value="false" />

      <property name="jbosscache-shareable" value="true" />

      <property name="max-volatile-time" value="60" />

   </properties>

</query-handler>

	`index-dir`: Path within NFS where ValueStorage will hold its data.
	`jbosscache-configuration`: Path to the JBoss Cache configuration for indexer.
	`jgroups-configuration`: Path to the JGroups configuration.
	`jboss-cache-cluster-name`: JBoss Cache indexer cluster name.
	`max-volatile-time`: Indicate that the latest changes in index will be visible for each cluster node not later than in a specific time (for example, the volatile time is set to 60s in this configuration). This property is not mandatory but recommended.

These properties have the same meaning and restrictions as in the previous code block except the last one max-volatile-time.

Lock Manager configuration:

This may be the hardest element to configure, because you have to define access to the database where locks will be stored. Replace the existing lock-manager with configuration shown below:


<lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl">

   <properties>

      <property name="time-out" value="15m" />

      <property name="jbosscache-configuration" value="jar:/conf/portal/test-jbosscache-lock.xml" />       

      <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" />                       

      <property name="jbosscache-cluster-name" value="JCR_Cluster_locks" />                                

      <property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks"/>                              

      <property name="jbosscache-cl-cache.jdbc.table.create" value="true"/>

      <property name="jbosscache-cl-cache.jdbc.table.drop" value="false"/>

      <property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_pk"/>

      <property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn"/>

      <property name="jbosscache-cl-cache.jdbc.node.column" value="node"/>

      <property name="jbosscache-cl-cache.jdbc.parent.column" value="parent"/>

      <property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr"/>

      <property name="jgroups-multiplexer-stack" value="false" />

      <property name="jbosscache-shareable" value="true" />

   </properties>

</lock-manager>

	`jbosscache-configuration`: Path to the JBoss Cache configuration for lock manager.
	`jgroups-configuration`: Path to the JGroups configuration.
	`jboss-cache-cluster-name`: JBoss Cache locks cluster name.
	`jbosscache-cl-cache.jdbc.table.name`: Name of the DB table where lock's data will be stored.
	`jbosscache-cl-cache.jdbc.table.create`: Whether to create it or not. Usually set to "true".
	`jbosscache-cl-cache.jdbc.table.drop`: Whether to drop on a start or not. Use "false".
	`jbosscache-cl-cache.jdbc.table.primarykey`: Name of column with pk.
	`jbosscache-cl-cache.jdbc.fqn.column`: Name of one more column. If you are not sure how to use, follow the example above (if much interested, please refer to JBossCache JDBCCacheLoader documentation).
	`jbosscache-cl-cache.jdbc.node.column`: Name of one more column. If you are not sure how to use, follow the example above (if much interested, please refer to JBossCache JDBCCacheLoader documentation).
	`jbosscache-cl-cache.jdbc.parent.column`: Name of one more column. If you are not sure how to use, follow the example above if you are not sure (if much interested, please refer to JBossCache JDBCCacheLoader documentation)
	`jbosscache-cl-cache.jdbc.datasource`: Name of the datasource configured in Container datasource, where you want to store locks. The best idea is to use the same as for workspace.

Few properties are the same as in the previous components, but here you can see some strange "jbosscache-cl-cache.jdbc.*" properties. They define access parameters for the database where the lock is persisted.