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 --> 
  <!-- ... --> 
</bean>

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

Like mod_jk and mod_proxy_balancer, mod_cluster requires a connector in your server.xml on which to forward web requests.  mod_cluster is not confined to AJP, but can use HTTP as well.  If multiple possible connectors are available, mod_cluster uses the following algorithm to choose between them: 

e.g.

<Server> 
  <!-- ... --> 
  <Service name="jboss.web"> 
    <Connector protocol="HTTP/1.1" port="${jboss.web.http.port}" address="${jboss.bind.address}" redirectPort="${jboss.web.https.port}"/> 
    <Connector protocol="AJP/1.3" port="${jboss.web.ajp.port}" address="${jboss.bind.address}" redirectPort="${jboss.web.https.port}"/> 
    <Engine name="jboss.web" defaultHost="localhost"> 
      <!-- ... --> 
    </Engine> 
  </Service> 
</Server>

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"> 
  <constructor> 
    <parameter class="org.jboss.modcluster.load.LoadBalanceFactorProvider"> 
      <inject bean="DynamicLoadBalanceFactorProvider"/> 
    </parameter> 
  </constructor> 
  <!-- Configuration properties go here --> 
  <property name="advertise">true</property> 
</bean>

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:

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:

<bean name="HAModClusterService" class="org.jboss.modcluster.ha.HAModClusterService" mode="On Demand"> 
  <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:service=ModCluster",exposedInterface=org.jboss.modcluster.ha.HAModClusterServiceMBean.class)</annotation> 
  <constructor> 
    <parameter class="org.jboss.ha.framework.interfaces.HAPartition"> 
      <inject bean="HAPartition"/> 
    </parameter> 
    <parameter class="org.jboss.modcluster.config.ha.HAModClusterConfig"> 
      <inject bean="HAModClusterConfig"/> 
    </parameter> 
    <parameter class="org.jboss.modcluster.load.LoadBalanceFactorProvider"> 
      <inject bean="DynamicLoadBalanceFactorProvider"/> 
    </parameter> 
    <parameter class="org.jboss.ha.framework.interfaces.HASingletonElectionPolicy"> 
      <bean class="org.jboss.ha.singleton.HASingletonElectionPolicySimple"/> 
    </parameter> 
  </constructor> 
</bean> 
<bean name="HAModClusterConfig" class="org.jboss.modcluster.config.ha.HAModClusterConfig" mode="On Demand"> 
  <property name="advertise">true</property> 
</bean>

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" 
          advertise="true"/>

mod_cluster uses jboss-logging, which exists in JBoss Web, but not in Tomcat. Consequently, to use mod_cluster with Tomcat, it is necessary to add jboss-logging-spi.jar to $CATALINA_HOME/lib.