JBoss.orgCommunity Documentation

Chapter 6. java configuration

6.1. JBoss AS
6.1.1. Lifecycle listener
6.1.2. Connectors
6.1.3. Node Identity
6.1.4. Non-Clustered Mode
6.1.5. Clustered Mode
6.2. JBoss Web & Tomcat
6.2.1. Lifecycle Listener
6.2.2. Additional Tomcat dependencies

The entry point for configuring mod_cluster withing JBoss AS is the server.xml file within JBoss Web service.  This file is located at $JBOSS_HOME/server/profile/deploy/jbossweb.sar/server.xml

mod_cluster leverages a <Listener/> to inform itself of web container lifecycle events, e.g. deploy/undeploy of a web application, startup/shutdown of the server, etc.

We use the generic MicrocontainerIntegrationLifecycleListener to delegate all lifecycle events to a bean deployed by the JBoss microcontainer.

mod_cluster 1.0.x is wired directly to the Catalina container API.  Catalina lifecycle events are delegated directly to mod_cluster's core service.

<Listener className="org.jboss.web.tomcat.service.deployers.MicrocontainerIntegrationLifecycleListener" 
          delegateBeanName="ModClusterService"/><!-- Non-clustered mode --> 
<!--Listener className="org.jboss.web.tomcat.service.deployers.MicrocontainerIntegrationLifecycleListener" 
          delegateBeanName="HAModClusterService"/--><!-- Clustered mode -->

To ensure that the delegate bean exists before the JBoss Web service starts, and that the bean does not get destroyed until the service shuts down, we must add an explicit microcontainer dependency to the JBoss Web service.  To do this, update the WebServer bean contained in $JBOSS_HOME/server/profile/deploy/jbossweb.sar/META-INF/jboss-beans.xml with the appropriate dependency:

<bean name="WebServer" class="org.jboss.web.tomcat.service.deployers.TomcatService"> 
  <!-- ... --> 
  <depends>ModClusterService</depends><!-- Non-clustered mode --> 
  <!--depends>HAModClusterService</depends--><!-- Clustered mode --> 
  <!-- ... --> 

For details of how to configure ModClusterService or HAModClusterService refer to the appropriate section.

Like mod_jk and mod_proxy_balancer, mod_cluster identifies each node via a unique jvm route.  The is specified using the jvmRoute attribute of the Engine within server.xml.

Users must define jvm routes manually, perhaps using system property expansion, e.g. jvmRoute="${jboss.mod_cluster.jvmRoute}"

mod_cluster can operate in 2 modes: non-clustered or clustered.  In non-clustered mode, each JBoss server node communicates with a httpd proxy directly, and do not communicate with each other.  Non-clustered mode is powered by the ModClusterService, whose definition varies depending on the version of mod_cluster in use.

In general, ModClusterService defines:

In version 1.0.x, all mod_cluster configuration properties are members of the ModClusterService bean itself:

<bean name="ModClusterService" class="org.jboss.modcluster.ModClusterService" mode="On Demand"> 
    <parameter class="org.jboss.modcluster.load.LoadBalanceFactorProvider"> 
      <inject bean="DynamicLoadBalanceFactorProvider"/> 
  <!-- Configuration properties go here --> 
  <property name="advertise">true</property> 

mod_cluster can operate in 2 modes: non-clustered or clustered.  In clustered mode, a single JBoss node (the HA singleton master) communicates with the httpd proxy on behalf of the other nodes in the cluster.  This mode offers the following advantages over non-clustered mode:

  1. The state of each proxy will be kept in sync on each node in the cluster.

  2. Proxies will be proactively notified of view changes, most notably, crashed members, allowing a proxy to gracefully reconfigure itself to avoiding failover processing.

  3. Adds domain management functionality, providing the ability to enable, disable, or gracefully stop all nodes sharing the same domain.  A domain is a logical grouping of nodes, typically representing a replication "buddy group".

Clustered mode is instrumented using JBoss clustering technologies and is configured via the HAModClusterService bean, the definition of which varies slightly between mod_cluster versions.

In general, HAModClusterService defines:

  1. A set of configuration properties

  2. A mechanism for providing the load balance factor to a proxy

  3. An HAPartition, the JBoss clustering group communication building block.  The default HAPartition is defined in:$JBOSS_HOME/server/profile/deploy/cluster/hapartition-jboss-beans.xml

<bean name="HAModClusterService" class="org.jboss.modcluster.ha.HAModClusterService" mode="On Demand"> 
    <parameter class="org.jboss.ha.framework.interfaces.HAPartition"> 
      <inject bean="HAPartition"/> 
    <parameter class="org.jboss.modcluster.config.ha.HAModClusterConfig"> 
      <inject bean="HAModClusterConfig"/> 
    <parameter class="org.jboss.modcluster.load.LoadBalanceFactorProvider"> 
      <inject bean="DynamicLoadBalanceFactorProvider"/> 
    <parameter class="org.jboss.ha.framework.interfaces.HASingletonElectionPolicy"> 
      <bean class="org.jboss.ha.singleton.HASingletonElectionPolicySimple"/> 
<bean name="HAModClusterConfig" class="org.jboss.modcluster.config.ha.HAModClusterConfig" mode="On Demand"> 
  <property name="advertise">true</property> 

In the absence of the ability for complex configuration, mod_cluster's entire configuration for JBoss Web or Tomcat resides entirely within $CATALINA_HOME/conf/server.xml.

This adds the following constraints to mod_cluster's feature set:

The entry point for JBoss Web and Tomcat configuration is the ModClusterListener.  All mod_cluster configuration properties are defined as attributes of the Listener element.

<Listener className="org.jboss.modcluster.ModClusterListener"