JBoss.orgCommunity Documentation

Chapter 14. Clustering Configuration

14.1. Introduction
14.2. Considerations
14.3. JBoss Portal Clustered Services
14.3.1. Portal Session Replication
14.3.2. Hibernate clustering
14.3.3. Identity clustering
14.3.4. CMS clustering
14.4. Setup
14.5. Portlet Session Replication
14.5.1. JBoss Portal configuration
14.5.2. Portlet configuration
14.5.3. Limitations

This section covers configuring JBoss Portal for a clustered environment.

JBoss Portal leverages various clustered services that are found in JBoss Application Server. This section briefly details how each is leveraged:

When you want to run JBoss Portal on a cluster there are a few things to keep in mind:

JBoss Portal leverages hibernate for its database access. In order to improve performances it uses the caching features provided by hibernate. On a cluster the cache needs to be replicated in order to avoid state inconsistencies. Hibernate is configured with JBoss Cache which performs that synchronization transparently. Therefore the different hibernate services must be configured to use JBoss Cache. The following hibernate configurations needs to use a replicated JBoss Cache :

The cache configuration should look like :

   | Uncomment in clustered mode : use transactional replicated cache
   <property name="cache.provider_class">org.jboss.portal.core.hibernate.JMXTreeCacheProvider
   <property name="cache.object_name">portal:service=TreeCacheProvider,type=hibernate

   | Comment in clustered mode
   <property name="cache.provider_configuration_file_resource_path">
   <property name="cache.provider_class">org.hibernate.cache.EhCacheProvider</property>

Also we need to ensure that the cache is deployed by having in the file jboss-portal.sar/META-INF/jboss-service.xml the cache service uncommented :

   | Uncomment in clustered mode : replicated cache for hibernate
   <attribute name="TransactionManagerLookupClass">
   <attribute name="IsolationLevel">REPEATABLE_READ</attribute>
   <attribute name="CacheMode">REPL_SYNC</attribute>
   <attribute name="ClusterName">portal.hibernate</attribute>

   <depends optional-attribute-name="CacheName">portal:service=TreeCache,type=hibernate

More information can be found here.

The CMS backend storage relies on the Apache Jackrabbit project. Jackrabbit does not support clustering out of the box. So the portal run the Jackrabbit service on one node of the cluster using the HA-Singleton technology. The file jboss-portal.sar/portal-cms.sar/META-INF/jboss-service.xml contains the configuration. We will not reproduce it in this documentation as the changes are quite complex and numerous. Access from all nodes of the cluster is provided by a proxy bound in HA-JNDI. In order to avoid any bottleneck JBoss Cache is leveraged to cache CMS content cluster wide.

We are going to outline how to setup a two node cluster on the same machine in order to test JBoss Portal HA. The only missing part from the full fledged setup is the addition of a load balancer in front of Apache Tomcat. However a lot of documentation exist on the subject. A detailed step by step setup of Apache and mod_jk is available from the JBoss Wiki.

As we need two application servers running at the same time, we must avoid any conflict. For instance we will need Apache Tomcat to bind its socket on two different ports otherwise a network conflict will occur. We will leverage the service binding manager this chapter of the JBoss AS documentation.

The first step is to copy the all configuration of JBoss into two separate configurations that we name ports-01 and ports-02 :

>cd $JBOSS_HOME/server
>cp -r all ports-01
>cp -r all ports-02

Edit the file $JBOSS_HOME/server/ports-01/conf/jboss-service.xml and uncomment the service binding manager :

<mbean code="org.jboss.services.binding.ServiceBindingManager"
   <attribute name="ServerName">ports-01</attribute>
   <attribute name="StoreURL">
   <attribute name="StoreFactoryClassName">org.jboss.services.binding.XMLServicesStoreFactory</attribute>

Edit the file $JBOSS_HOME/server/ports-02/conf/jboss-service.xml, uncomment the service binding manager and change the value ports-01 into ports-02:

<mbean code="org.jboss.services.binding.ServiceBindingManager"
   <attribute name="ServerName">ports-02</attribute>
   <attribute name="StoreURL">
   <attribute name="StoreFactoryClassName">

Setup a database that will be shared by the two nodes and obviously we cannot use an embedded database. For instance using postgresql we would need to copy the file portal-postgresql-ds.xml into $JBOSS_HOME/server/ports-01/deploy and $JBOSS_HOME/server/ports-02/deploy.

Copy JBoss Portal HA to the deploy directory of the two configurations.

JBoss Cache

To improve CMS performance JBoss Cache is leveraged to cache the content cluster wide. We recommend that you use the following version of JBoss Cache for best performance:

  • JBoss Cache 1.4.0.SP1 and above
  • JGroups 2.2.7 or 2.2.8

When building from source the following command: {core}/build.xml deploy-ha automatically upgrades your JBoss Cache version.

Alternative: If upgrading your JBoss Cache version is not an option, the following configuration change is needed in the jboss-portal-ha.sar/portal-cms.sar/META-INF/jboss-service.xml. Replace the following configuration in the cms.pm.cache:service=TreeCache Mbean:

   Configuring the PortalCMSCacheLoader
   CacheLoader configuration for 1.4.0
<attribute name="CacheLoaderConfiguration">

with the following configuration:

   Configuring the PortalCMSCacheLoader
   CacheLoader configuratoon for 1.2.4SP2
<attribute name="CacheLoaderClass">org.jboss.portal.cms.hibernate.state.PortalCMSCacheLoader
<attribute name="CacheLoaderConfig" replace="false"></attribute>
<attribute name="CacheLoaderPassivation">false</attribute>
<attribute name="CacheLoaderPreload"></attribute>
<attribute name="CacheLoaderShared">false</attribute>
<attribute name="CacheLoaderFetchTransientState">false</attribute>
<attribute name="CacheLoaderFetchPersistentState">false</attribute>
<attribute name="CacheLoaderAsynchronous">false</attribute>

Finally we can start both servers, open two shells and execute :

>cd $JBOSS_HOME/bin
>sh run.sh -c ports-01

>cd $JBOSS_HOME/bin
>sh run.sh -c ports-02

Web containers offer the capability to replicate sessions of web applications. In the context of a portal using portlets the use case is different. The portal itself is a web application that benefits of web application session replication. We have to make the distinction between local or remote portlets :

The servlet specification is very loose on the subject of replication and does not state anything about the replication of sessions during a dispatched request. JBoss Portal offers a portlet session replication mechanism that leverages the usage of the portal session instead which has several advantages

There are, however, some limitations. For example, you can only replicate portlet-scoped attributes of a portlet session. This means that any application-scoped attribute are not replicated.