Page History

...

Ensure that every object placed in the HTTP session implements java.io.Serializable. The clustering feature serializes the objects when it distributes them to the other nodes in the cluster.

The deployment descriptor for your Web application, that is the web.xml file in the Web archive, must indicate that your Web application is distributable. To do this, insert the distributable element in the deployment descriptor.

Code Block

	XML
borderStyle	XML	solid
title	Excerpt from web.xml
borderStyle	XMLsolid

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
    <display-name> ... </display-name>
    <description> ... </description>
    <distributable> <distributable/>
  ...
</web-app>

Do not use stateful session Enterprise JavaBeans (EJBs). The clustering feature does not replicate stateful EJBs among the nodes in the cluster.
If your Web application uses a database, every node in the cluster can access the database. Ensure that the JDBC drivers are installed on every node and that the datasource objects are defined correctly on every node.
Do not depend on dynamic updates to the Java Naming and Directory Interface (JNDI). You need to configure all the JNDI names used by your application in every node of the cluster. The clustering feature does not replicate JNDI changes among the nodes in the cluster.

...

For every node in the cluster, update server.xml as follows after the server is stopped:
Code Block
XML
borderStyle solidXML
title Excerpt from server.xml
borderStyle solidXML
... <Engine name="Catalina" defaultHost="${ServerHostname}" jvmRoute="nodeId"> ...
where
- nodeId is a node identifier that is unique among all the nodes in the cluster. If you are using mod_jk, make sure that the jvmRoute attribute value matches your worker name in workers.properties.
Restart the server to enable the new configuration.

...

The template for your Web application deployment plan is shown as follows. See Creating deployment plans for Web applications for more information about the parameters.

Code Block

	XML
	borderStyle	solidXML
title	geronimo-web.xml
borderStyle	XMLsolid

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.2"
         xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2">

    <dep:environment>
      <dep:moduleId>
        <dep:groupId>org.mygroup</dep:groupId>
        <dep:artifactId>web-cluster-server1</dep:artifactId>
        <dep:version>2.2</dep:version>
        <dep:type>war</dep:type>
      </dep:moduleId>
      <dep:dependencies>
      	<dep:dependency>
      	<dep:groupId>console.realm</dep:groupId>
        <dep:artifactId>geronimo-properties-realm</dep:artifactId>
        <dep:version>1.0</dep:version>
        <dep:type>car</dep:type>
        </dep:dependency>
      </dep:dependencies>
      <dep:hidden-classes/>
      <dep:non-overridable-classes/>
    </dep:environment>

    <context-root>/servlet-examples-cluster</context-root>

    <security-realm-name>geronimo-properties-realm</security-realm-name>
    <security>
      <default-principal>
        <principal name="anonymous" class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"/>
      </default-principal>
      <role-mappings>
        <role role-name="tomcat">
          <principal name="admin" class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"/>
        </role>
      </role-mappings>
    </security>

    <cluster>TomcatCluster</cluster>
    <gbean class="org.apache.geronimo.tomcat.cluster.CatalinaClusterGBean" name="TomcatCluster">
        <attribute name="className">org.apache.catalina.ha.tcp.SimpleTcpCluster</attribute>
        <attribute name="initParams"/>
        <reference name="ClusterManager">          
            <name>TomcatClusterManager</name>                
        </reference>
        <reference name="TomcatValveChain">
            <name>ReplicationValve</name>
        </reference>
        <reference name="ClusterListenerChain">
            <name>ClusterSessionListener</name>
        </reference>
        <reference name="Channel">
            <name>TomcatGroupChannel</name>
        </reference>
    </gbean>
  <!-- Cluster Manager -->
    <gbean name="TomcatClusterManager" class="org.apache.geronimo.tomcat.cluster.ClusterManagerGBean">
        <attribute name="className">org.apache.catalina.ha.session.DeltaManager</attribute>
        <attribute name="initParams">name=${clusterName}
           channelSendOptions=6
           expireSessionsOnShutdown=false
           notifyListenersOnReplication=true
           mapSendOptions=6</attribute>
    </gbean>
  <!-- Cluster Channel -->
    <gbean class="org.apache.geronimo.tomcat.cluster.ChannelGBean" name="TomcatGroupChannel">
        <attribute name="className">org.apache.catalina.tribes.group.GroupChannel</attribute>
        <attribute name="initParams"/>
        <reference name="Membership">
            <name>TomcatMembership</name>
        </reference>
        <reference name="Receiver">
            <name>TomcatReceiver</name>
        </reference>
        <reference name="Sender">
            <name>TomcatSender</name>
        </reference>
        <reference name="ChannelInterceptor">
            <name>TomcatChannelInterceptor</name>
        </reference>
    </gbean>
  <!-- Cluster Membership -->
    <gbean class="org.apache.geronimo.tomcat.cluster.MembershipServiceGBean" name="TomcatMembership">
        <attribute name="className">org.apache.catalina.tribes.membership.McastService</attribute>
        <attribute name="initParams">
            mcastAddr=228.0.0.4
            mcastPort=45564
            mcastFrequency=500
            mcastDropTime=3000
        </attribute>
    </gbean>
  <!-- Cluster Receiver -->
    <gbean class="org.apache.geronimo.tomcat.cluster.ReceiverGBean" name="TomcatReceiver">
        <attribute name="className">org.apache.catalina.tribes.transport.nio.NioReceiver</attribute>
        <attribute name="initParams">
            tcpListenAddress=auto
            tcpListenPort=4001
            tcpSelectorTimeout=100
            tcpThreadCount=6
        </attribute>
    </gbean>
  <!-- Cluster Sender -->
    <gbean class="org.apache.geronimo.tomcat.cluster.SenderGBean" name="TomcatSender">
        <attribute name="className">org.apache.catalina.tribes.transport.ReplicationTransmitter</attribute>
        <attribute name="initParams">
            replicationMode=pooled
            waitForAck=true
        </attribute>
    </gbean>
  <!-- Cluster Valves-->
    <gbean class="org.apache.geronimo.tomcat.ValveGBean" name="ReplicationValve">
        <attribute name="className">org.apache.catalina.ha.tcp.ReplicationValve</attribute>
        <attribute name="initParams">filter=.*\.gif;.*\.js;.*\.css;.*\.png;.*\.jpeg;.*\.jpg;.*\.htm;.*\.html;.*\.txt;</attribute>
        <reference name="NextValve">
        	<name>JvmRouteBinderValve</name>
        </reference>
    </gbean>
  <!-- Cluster Route Binder -->
    <gbean class="org.apache.geronimo.tomcat.ValveGBean" name="JvmRouteBinderValve">
        <attribute name="className">org.apache.catalina.ha.session.JvmRouteBinderValve</attribute>
        <attribute name="initParams">enabled=true</attribute>
    </gbean>
  <!-- Cluster Listener -->
    <gbean class="org.apache.geronimo.tomcat.cluster.ClusterListenerGBean" name="ClusterSessionListener">
        <attribute name="className">org.apache.catalina.ha.session.ClusterSessionListener</attribute>
        <reference name="NextListener">
            <name>JvmRouteSessionIDBinderListener</name>
        </reference>
    </gbean>
  <!-- Cluster Binder Listener-->
    <gbean class="org.apache.geronimo.tomcat.cluster.ClusterListenerGBean" name="JvmRouteSessionIDBinderListener">
        <attribute name="className">org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener</attribute>
    </gbean>
  <!-- Cluster Channel Interceptor -->
    <gbean class="org.apache.geronimo.tomcat.cluster.ChannelInterceptorGBean" name="TomcatChannelInterceptor">
        <attribute name="className">org.apache.catalina.tribes.group.interceptors.TcpFailureDetector</attribute>
    </gbean>
</web-app>

...

The following code snippet is part of a clustering example that uses unicast configuration. Static members are defined using org.apache.geronimo.tomcat.cluster.StaticMemberGBean. You have to define each static member within your deployment plan to make sure that your application is clustered successfully, and make sure that TCP ports for session replication are defined consistently on each node.

Code Block

	XML
borderStyle	XML	solid
title	excerpt from geronimo-web.xml
borderStyle	XMLsolid

...
    <cluster>TomcatCluster</cluster>
        <gbean name="TomcatCluster" class="org.apache.geronimo.tomcat.cluster.CatalinaClusterGBean">
            <attribute name="className">org.apache.catalina.ha.tcp.SimpleTcpCluster</attribute>
            <attribute name="initParams"/>
            <reference name="ClusterListenerChain"> 
                    <name>TomcatClusterListenerChain</name>
            </reference>
            <reference name="TomcatValveChain">
                    <name>ReplicationValve</name>  
            </reference>
            <reference name="Channel">
                    <name>TomcatChannel</name>
            </reference>
            <reference name="ClusterManager"> 
                    <name>TomcatClusterManager</name>
            </reference>
        </gbean>

        <gbean name="TomcatClusterListenerChain" class="org.apache.geronimo.tomcat.cluster.ClusterListenerGBean">
            <attribute name="className">org.apache.catalina.ha.session.ClusterSessionListener</attribute>
            <attribute name="initParams"/>
        </gbean>

        <gbean name="ReplicationValve" class="org.apache.geronimo.tomcat.ValveGBean">
            <attribute name="className">org.apache.catalina.ha.tcp.ReplicationValve</attribute>
            <attribute name="initParams">.*\.gif;.*\.js;.*\.jpg;.*\.png;.*\.htm;.*\.html;.*\.css;.*\.txt;</attribute>
            <reference name="NextValve">
        			<type>TomcatValve</type>
            	                <name>JvmRouteBinderValve</name>
            </reference>
        </gbean>

        <gbean name="JvmRouteBinderValve" class="org.apache.geronimo.tomcat.ValveGBean">
            <attribute name="className">org.apache.catalina.ha.session.JvmRouteBinderValve</attribute>
            <attribute name="initParams">enabled=true</attribute>
        </gbean>

        <gbean name="TomcatClusterManager" class="org.apache.geronimo.tomcat.cluster.ClusterManagerGBean">
            <attribute name="className">org.apache.catalina.ha.session.DeltaManager</attribute>
            <attribute name="initParams">name=${clusterName}
                                         channelSendOptions=6
                                         expireSessionsOnShutdown=false
                                         notifyListenersOnReplication=true
                                         mapSendOptions=6
            </attribute>
        </gbean>

        <gbean name="TomcatChannel" class="org.apache.geronimo.tomcat.cluster.ChannelGBean">
            <attribute name="className">org.apache.catalina.tribes.group.GroupChannel</attribute>
            <attribute name="initParams"/>
            <reference name="Membership"> 
                    <name>ClusterMembership</name>
            </reference>
            <reference name="Receiver">
                    <name>ClusterReceiver</name>                
            </reference>
            <reference name="Sender">                
                    <name>ClusterSender</name>
            </reference>
            <reference name="ChannelInterceptor">
                    <name>DisableMcastInterceptor</name>                
            </reference>
        </gbean>

        <gbean name="ClusterMembership" class="org.apache.geronimo.tomcat.cluster.MembershipServiceGBean">
            <attribute name="className">org.apache.catalina.tribes.membership.McastService</attribute>
            <attribute name="initParams">address=228.0.0.4
                                         port=45564
                                         frequency=500
                                         dropTime=3000
            </attribute>
        </gbean>

        <gbean name="ClusterReceiver" class="org.apache.geronimo.tomcat.cluster.ReceiverGBean">
            <attribute name="className">org.apache.catalina.tribes.transport.nio.NioReceiver</attribute>
            <attribute name="initParams">address=IPAddress1
                                         port=TCP_port1
                                         selectorTimeout=100
                                         maxThreads=6
            </attribute>
        </gbean>

        <gbean name="ClusterSender" class="org.apache.geronimo.tomcat.cluster.SenderGBean">
            <attribute name="className">org.apache.catalina.tribes.transport.ReplicationTransmitter</attribute>
        </gbean>

        <gbean name="DisableMcastInterceptor" class="org.apache.geronimo.tomcat.cluster.ChannelInterceptorGBean">
            <attribute name="className">org.apache.geronimo.tomcat.interceptor.DisableMcastInterceptor</attribute>
            <attribute name="initParams"/>
            <reference name="NextInterceptor">
                    <name>TcpPingInterceptor</name>                
            </reference>
        </gbean>

        <gbean name="TcpPingInterceptor" class="org.apache.geronimo.tomcat.cluster.ChannelInterceptorGBean">
            <attribute name="className">org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor</attribute>
            <attribute name="initParams">Interval=60</attribute>
            <reference name="NextInterceptor">
                    <name>TcpFailureDetector</name>                
            </reference>
        </gbean>

        <gbean name="TcpFailureDetector" class="org.apache.geronimo.tomcat.cluster.ChannelInterceptorGBean">
            <attribute name="className">org.apache.catalina.tribes.group.interceptors.TcpFailureDetector</attribute>
            <attribute name="initParams"/>
            <reference name="NextInterceptor">                
                    <name>StaticMember1Interceptor</name>                
            </reference>
        </gbean>

        <gbean name="StaticMember1Interceptor" class="org.apache.geronimo.tomcat.cluster.ChannelInterceptorGBean">
            <attribute name="className">org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor</attribute>
            <attribute name="initParams"/>
            <reference name="StaticMember">
                    <name>StaticMember2</name>                
            </reference>
            <reference name="NextInterceptor">                
                    <name>MessageDispatch15Interceptor</name> 
            </reference>
        </gbean>

        <gbean name="MessageDispatch15Interceptor" class="org.apache.geronimo.tomcat.cluster.ChannelInterceptorGBean">
            <attribute name="className">org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor</attribute>
            <attribute name="initParams"/>
            <reference name="NextInterceptor">
                    <name>ThroughputInterceptor</name>                
            </reference>
        </gbean>

        <gbean name="ThroughputInterceptor" class="org.apache.geronimo.tomcat.cluster.ChannelInterceptorGBean">
            <attribute name="className">org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor</attribute>
            <attribute name="initParams"/>
        </gbean>

        <gbean name="StaticMember2" class="org.apache.geronimo.tomcat.cluster.StaticMemberGBean">
            <attribute name="className">org.apache.catalina.tribes.membership.StaticMember</attribute>
            <attribute name="initParams">port=TCP_port2
                                         securePort=-1
                                         host=IPAddress2
                                         domain=test-domain
                                         UniqueId={2,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0}
            </attribute>
        </gbean>
...

...

Sample multicast configuration code

Code Block

	xml
	xml
title	server.xmlxml

...
     <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster" channelSendOptions="8">
                    <Manager className="org.apache.catalina.ha.session.DeltaManager" expireSessionsOnShutdown="false" notifyListenersOnReplication="true" name="${clusterName}" channelSendOptions="6" mapSendOptions="6"/>
                    <Channel className="org.apache.catalina.tribes.group.GroupChannel">
                        <Membership className="org.apache.catalina.tribes.membership.McastService" address="228.0.0.4" port="45564" frequency="500" dropTime="3000" />
                        <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver" address="auto" port="4000" autoBind="100" selectorTimeout="5000" maxThreads="6" />
                        <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter">
                            <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender" />
                        </Sender>                        
                        <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector" interval="60"/>                        
                        
                        <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor" />
                        <Interceptor className="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor" />                        
                    </Channel>
                    <Valve className="org.apache.catalina.ha.tcp.ReplicationValve" filter=".*\.gif;.*\.js;.*\.jpg;.*\.png;.*\.htm;.*\.html;.*\.css;.*\.txt;" />
                    <Valve className="org.apache.catalina.ha.session.JvmRouteBinderValve" />
                    <ClusterListener className="org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener" />
                    <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener" />
      </Cluster>
...

Sample unicast configuration code

Code Block

	xml
	xml
title	server.xmlxml

...
    <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster" channelSendOptions="8">
                    <Manager className="org.apache.catalina.ha.session.DeltaManager" expireSessionsOnShutdown="false" notifyListenersOnReplication="true" name="${clusterName}" channelSendOptions="6" mapSendOptions="6"/>
                    <Channel className="org.apache.catalina.tribes.group.GroupChannel">
                        <Membership className="org.apache.catalina.tribes.membership.McastService" address="228.0.0.4" port="45564" frequency="500" dropTime="3000" />
                        <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver" address="auto" port="4000" autoBind="100" selectorTimeout="5000" maxThreads="6" />
                        <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter">
                            <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender" />
                        </Sender>
                        <Interceptor className="org.apache.geronimo.tomcat.interceptor.DisableMcastInterceptor" />
                        <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector" interval="60"/>                        
                        <Interceptor className="org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor">
                            <Member port="TCP_port" securePort="-1" host="IPAddress" domain="test-domain" UniqueId="{1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0}" />
                        </Interceptor>
                        <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor" />
                        <Interceptor className="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor" />                        
                    </Channel>
                    <Valve className="org.apache.catalina.ha.tcp.ReplicationValve" filter=".*\.gif;.*\.js;.*\.jpg;.*\.png;.*\.htm;.*\.html;.*\.css;.*\.txt;" />
                    <Valve className="org.apache.catalina.ha.session.JvmRouteBinderValve" />
                    <ClusterListener className="org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener" />
                    <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener" />
      </Cluster>
...

...

Child pages

Versions Compared

Old Version 6

New Version Current

Key

Sample multicast configuration code

Sample unicast configuration code