The portal associates with each user a http session in order to keep specific objects such as:

Replicating the portal session ensures that this state will be kept in sync on the cluster, e.g The user will see exactly the same portlet window on every node of the cluster. The activation of the portal session replication is made through the configuration of the web application that is the main entry point of the portal. This setting is available in the file jboss-portal.sar/portal-server.war/WEB-INF/web.xml

<web-app>
   <description>JBoss Portal</description>
   <!-- Comment/Uncomment to enable portal session replication -->
   <distributable/>
   ...
</web-app>

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>
   <property name="cache.object_name">portal:service=TreeCacheProvider,type=hibernate
   </property>

<!--
   | Comment in clustered mode
   <property name="cache.provider_configuration_file_resource_path">
   conf/hibernate/instance/ehcache.xml</property>
   <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
   -->
   <mbean
   code="org.jboss.cache.TreeCache"
   name="portal:service=TreeCache,type=hibernate">
   <depends>jboss:service=Naming</depends>
   <depends>jboss:service=TransactionManager</depends>
   <attribute name="TransactionManagerLookupClass">
   org.jboss.cache.JBossTransactionManagerLookup</attribute>
   <attribute name="IsolationLevel">REPEATABLE_READ</attribute>
   <attribute name="CacheMode">REPL_SYNC</attribute>
   <attribute name="ClusterName">portal.hibernate</attribute>
   </mbean>

   <mbean
   code="org.jboss.portal.core.hibernate.JBossTreeCacheProvider"
   name="portal:service=TreeCacheProvider,type=hibernate">
   <depends optional-attribute-name="CacheName">portal:service=TreeCache,type=hibernate
   </depends>
   </mbean>

More information can be found here.

JBoss Portal leverages the servlet container authentication for its own authentication mechanism. When the user is authenticated on one particular node he will have to reauthenticate again if a different node of the cluster (during a failover for instance) is used. This is valid only for the FORM based authentication which is the default form of authentication that JBoss Portal uses. Fortunately JBoss provides transparent reauthentication of the user called JBoss clustered SSO. Its configuration can be found in $JBOSS_HOME/server/all/deploy/jboss-web.deployer/server.xml and you will need to uncomment the following valve:

<Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" />

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.

The mandatory step to make JBoss Portal able to replicate portlet sessions is to configure the portal web application to be distributed as explained in Section 13.3.1, “Portal Session Replication”

In order to activate portlet session replication you need to:

<web-app>
   ...
   <listener>
      <listener-class> org.jboss.portal.portlet.session.SessionListener </listener-class>
   </listener>
   ...
</web-app>

<portlet-app>
   ...
   <portlet>
      <portlet-name>YourPortlet</portlet-name>
      ...
      <session-config>
         <distributed>true</distributed>
      </session-config>
      ...
   </portlet>
   ...
</portlet-app>

As we noted above there are advantages as well as limitations to the clustering configuration

public void processAction(ActionRequest req, ActionResponse resp)
               throws PortletException, IOException
{
   ...
   if ("addItem".equals(action))
   {
      PortletSession session = req.getPortletSession();
      ShoppingCart cart = (PortletSession)session.getAttribute("cart");
      cart.addItem(item);

      // Perform an explicit set in order to signal to the container that the object
      // state has changed
      session.setAttribute("cart", cart);
   }
   ...
}