Tomcat Native Clustering

Clustering and farming

Staring from Geronimo version 2.2, Web applications and Stateful SessionBeans can be clustered by WADI. To cluster these components, their Geronimo deployment descriptors are augmented with specific XML elements. These elements define various clustering parameters controlling how underlying WADI's components are wired and set up upon application deployment.

Clustering Configurations

Install the following two configurations, shipped out-of-the-box with JEE5 assemblies, to support the clustering:

• org.apache.geronimo.configs/clustering//car: it defines the runtime dependencies that clustered Web applications or EJB modules must have. For instance, it imports the geronimo-clustering JAR into the classpath of such modules. Also, it defines a Node GBean defining the unique name of this Geronimo instance in the cluster.
  To give a specific name to your Geronimo instance, you can reconfigure this module by updating the clusterNodeName property defined within var/config/config-substitutions.properties:

  clusterNodeName=MyOwnNodeName
  

• org.apache.geronimo.configs/wadi-clustering//car: it defines WADI specific GBeans that are used to further configure the behaviour of clustered applications and the WADI group communication service shared by all clustered applications to communicate with each others.
  You can use this module to override the DefaultBackingStrategyFactory GBean to configure the default number of replicas, which is set to 2 and maintained across the cluster for a given HTTP session or SFSB instance.

These configurations are automatically started when clustered applications are started. Hence, you should not start them explicitly.

Creating a Static Wadi Configuration

Wadi can be configured to use unicast instead of multicast. To accomplish this configuration, multiple additions need to be added to the wadi-cluster module configuraton in config.xml.

Modifying DispatchHolder GBean Configuration

To successfully use a unicast configuraton, use the disableMCastService attribute to disable the multicast broadcast service.

<gbean name="DefaultDispatcherHolder">
    <attribute name="disableMCastService">true</attribute>
</gbean>

You can specify the receiver port that the DispatcherHolder will listen on for session updates. If no port is specified, then the first available port starting at port 4000 will be chosen automatically.

<gbean name="DefaultDispatcherHolder">
    <attribute name="disableMCastService">true</attribute>
    <attribute name="receiverPort">4003</attribute>
</gbean>

For a static configuration, you need to define a list of static members. Each static member will have its own gbean configuration in config.xml in the wadi-cluster module. The DefaultDispatchHolder takes a reference to the first static member in the list.

<gbean name="DefaultDispatcherHolder">
    <attribute name="disableMCastService">true</attribute>
    <attribute name="receiverPort">4003</attribute>
    <reference name="staticMember">
        <pattern>
            <groupId>org.apache.geronimo.configs</groupId>
            <artifactId>wadi-clustering</artifactId>
            <version>2.2-SNAPSHOT</version>
            <type>car</type>
            <name>firstStaticMember</name>
        </pattern>
    </reference>
</gbean>

Defining A Static Member

You need to define each static member in the configuration in config.xml. A sample configuration is as follows:

<gbean name="org.apache.geronimo.configs/wadi-clustering/2.2-SNAPSHOT/car?ServiceModule=org.apache.geronimo.configs/wadi-clustering/2.2-SNAPSHOT/car,j2eeType=GBean,name=firstStaticMember"
       gbeanInfo="org.apache.geronimo.clustering.wadi.WadiStaticMember">
    <attribute name="className">org.apache.catalina.tribes.membership.StaticMember</attribute>
    <attribute name="port">4001</attribute>
    <attribute name="securePort">-1</attribute>
    <attribute name="domain">test-domain</attribute>
    <attribute name="UniqueId">0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0</attribute>
    <attribute name="host">9.27.163.151</attribute>
    <reference name="nextWadiStaticMember">
        <pattern>
            <groupId>org.apache.geronimo.configs</groupId>
            <artifactId>wadi-clustering</artifactId>
            <version>2.2-SNAPSHOT</version>
            <type>car</type>
            <name>secondStaticMember</name>
        </pattern>
    </reference>
</gbean>

Static Member Attributes

• className (required) - The static member class name within tomcat.
• port - receiver port of the static member.
• securePort - secure receiver port.
• domain (required) = cluster domain.
• UniqueId (required) = Unique identifier for this static member.
• host (required) = hostname or ip address of the static member.
• nextWadiStaticMember = The next static member in the member list. This can be left blank or left out completely if there are no more static members.

Clustering of Web-applications

Updating your Deployment Descriptors

Deployment descriptors and deployment plans must be updated as follows:

• deployment descriptor, for example, web.xml: the Web application must be marked as distributable. In other words, the optional "distributable" element must be defined:

  <web-app>
  .....
      <distributable/>
  .....
  </web-app>
  

• deployment plan, for example geronimo-web.xml: if you are deploying the Web application to embedded Jetty, then the "clustering-wadi" substitution group must be defined. If you are deploying to embedded Tomcat, then you should use the "tomcat-clustering-wadi" substitution group. These substitution groups are defined by the XSDs geronimo-clustering-wadi-X.xsd and geronimo-tomcat-clustering-wadi-X.xsd respectively which are included in the schema folder of a Geronimo server installation.
  Both of these elements provide a Web application specific clustering configuration, which overrides the default clustering configuration. This default clustering configuration is defined by the GBean WADIJettyClusteringBuilder declared by org.apache.geronimo.configs/jetty6-clustering-builder-wadi//car.
  Here is an example Geronimo deployment descriptor targeted at Jetty embedded:

  <?xml version="1.0" encoding="UTF-8"?>
  <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/jetty-1.2">
  
      <environment>
          <moduleId>
              <groupId>yourGroupId</groupId>
              <artifactId>yourArtifactId</artifactId>
              <version>YourVersion</version>
              <type>war</type>
          </moduleId>
      </environment>
  
     <context-root>/yourPath</context-root>
  
     <clustering-wadi/>
  
  </web-app>
  

If you are using a Tomcat assembly of Geronimo distribution, replace <clustering-wadi/> with <tomcat-clustering-wadi/> element in the deployment plan.

Jetty Web-application Clustering Configurations

Install the following two configurations, shipped out-of-the-box with JEE5 assemblies, to support the clustering:

• org.apache.geronimo.configs/jetty6-clustering-wadi//car: it defines runtime dependencies and Jetty6 clustering contracts.
• org.apache.geronimo.configs/jetty6-clustering-builder-wadi//car: it defines deployment time dependencies along with a JettyClusteringBuilder GBean declaring the default clustering configuration.
  This configuration must be running when a clustered Web application is started. If it is not running, then the substitution group clustering-wadi is not properly recognized and the deployment fails.

Tomcat Web-application Clustering Configurations

Tomcat configurations mirror Jetty's except that jetty6-X artifact IDs should be replaced by tomcat6-X.

Clustering of SFSB

Geronimo uses the OpenEJB container for providing EJB services. And Geronimo now has some basic support for SFSB clustering such as state replication between cluster members. Basically the server cluster members maintain membership information using multicast heartbeats and the ejb client maintains a list of servers to change target server based on availability. Each multicast packet contains a single URI that advertises a service, its group, and its location in the form of "cluster1:ejb:ejbd://thehost:4201".

Updating Geronimo EJB deployment plan

The Geronimo-specific deployment plan for an EJB application, which is usually packaged as an EJB JAR file, is called "openejb-jar.xml". The openejb-jar.xml deployment plan is used in conjunction with the ejb-jar.xml Java EE deployment plan to deploy enterprise applications to the Geronimo application server.
To enable WADI clustering for SFSB, add openejb-clustering-wadi into the deployment plan as follows:

<openejb-jar xmlns="http://openejb.apache.org/xml/ns/openejb-jar-2.2" 
             xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.2"> 
...
  <openejb-clustering-wadi/>
</openejb-jar>

Updating server configuration

Install the following two configurations, shipped out-of-the-box with JEE5 assemblies, to support the clustering:

• org.apache.geronimo.configs/openejb-clustering-wadi//car: it defines runtime dependencies and OpenEJB clustering contracts.
• org.apache.geronimo.configs/openejb-clustering-builder-wadi//car: it defines deployment time dependencies along with a OpenEJBClusteringBuilder GBean declaring the default clustering configuration.
  This configuration must be running when a clustered SFSB is started. If it is not running, then the substitution group openejb-clustering-wadi is not properly recognized and the deployment fails.