Howto: Clustering with JOnAS

By Georges Goebel and Marc Calvisi
03 March 2005
Version : 2.2

This guide describes how to configure Apache, Tomcat, and JOnAS to install a cluster.

This configuration uses the Apache/Tomcat plug-in mod_jk. This plug-in allows use of the Apache HTTP server in front of one or several Tomcat JSP/Servlet engines, and provides the capability of forwarding some of the HTTP requests (typically those concerning the dynamic pages, i.e. JSP and Servlet requests) to Tomcat instances.

It also uses the In-Memory-Session-Replication technique based on the group communication protocol JavaGroups to provide failover at servlet/JSP level.

For the load balancing at EJB level, a clustered JNDI called cmi is used.

This document describes one architecture with all the clustering functionalities available in JOnAS, the configuration of architectures integrating one of those functionalities, and other possible configurations.

The content of this guide is the following:

Architecture

The architecture with all the clustering functionality available in JOnAS is: Apache as the front-end HTTP server, JOnAS/Tomcat as J2EE Container, and a shared database.
    At the Servlet / JSP level, the mod_jk plug-in provides Load Balancing / High Availability and the Tomcat-Replication module provides Failover.
    At the EJB level, the clustered JNDI cmi provides Load Balancing / High Availability.
    The database is shared by the JOnAS servers.

The versions assumed here are: Apache 2.0, Mod_jk 1.2.8, JOnAS 4.4..x/Tomcat 5.5.x package.

The architecture presented in this document is shown in the following illustration:

architecture

This architecture provides:

However, failover at EJB level is not available. This means that no State Replication is provided. The mechanism to provide failover at EJB level is under development and will be available in a coming version of JOnAS.

Products Installation

This chapter provides information about installing Apache, mod_jk and JOnAS / Tomcat. The versions assumed here are: Apache 2.0, mod_jk 1.2.8 and the package JOnAS 4.4.x /Tomcat 5.0.x.

Installing Apache


Install Apache HTTP server from scratch :
  1. Download Apache HTTP server source code from the Apache site.
  2. Extract the source code.
    gunzip httpd-2_0_XX.tar.gz
    tar xvf httpd-2_0_XX.tar
  3. Compile and Install.
    ./configure
    make
    make install

    Note: A binary version is also available for installation at the Apache site.
Run and Stop Apache HTTP server:
  1. Run Apache HTTP server.
    /usr/local/apache2/apachectl start
  2. Stop Apache HTTP server.
    /usr/local/apache2/apachectl stop
For further information about installing Apache HTTP server please refer to Apache Site.

Installing the package JOnAS / Tomcat

Refer to Installing JOnAS with a web container from scratch.

Load balancing at web level with mod_jk or Enhydra Director

This chapter describes how to configure Apache, Tomcat, mod_jk, and JOnAS to run the architecture shown in the following illustration:

archi1

This example uses mod_jk, but an alternative configuration using Enhydra Director is also possible. (see config)

Configuring the JK Module

JK module principles

Mod_jk is a plug-in that handles the communication between Apache and Tomcat.
Mod_jk uses the concept of worker. A worker is a Tomcat instance that is running to perform servlet requests coming from the web server. Each worker is identified to the web server by the host on which it is located, the port where it listens, and the communication protocol used to exchange messages. In this configuration there is one worker for each Tomcat instance and one worker that will handle the load balancing (this is a specific worker with no host and no port number). All workers are defined in a file called worker.properties.

Note: this module can also be used for site partitioning.

Install Mod_jk

The easiest way to obtain this plug-in is to download the binary from the Tomcat Site and place it in the directory libexec (for unix) or modules (for windows or Mandrake) of the Apache installation directory.
For further installion information, refer to the Tomcat Site.

Configure Mod_jk

This depends on the distribution being used. Create a file tomcat_jk.conf and workers.properties in "$APACHE_HOME/conf/jk/".

Configure Apache

Configure Tomcat

To configure Tomcat, perform the following configuration steps for each Tomcat server.
  1. Configure Tomcat for the connector AJP13. In the file conf/server.xml of the JOnAS installation directory, add (if not already there):

    <!-- Define an AJP 1.3 Connector on port 9009 -->
    <Connector
        port="9009" minProcessors="5" maxProcessors="75"
        acceptCount="10" debug="20" protocol="AJP/1.3"/>
    Explanations:
      port: The TCP port number on which this Connector will create a server socket and await incoming connections.
      minProcessor: The minimum number of processors to start at intialization time. If not specified, this attribute is set to 5.
      maxProcessor: The maximum number of processors allowed.
      acceptCount: The maximum queue length for incoming connection requests when all possible requests processing threads are in use. Any requests received when the queue is full will be refused.
      debug: The debugging detail level of log messages generated by this component, with higher numbers creating more detailed output.
      protocol: This attribute must be AJP/1.3 to use the AJP handler.

    Note: Refer to the AJP Connector documentation.

  2. Define the jvmRoute.
    In the file conf/server.xml of the JOnAS installation directory, add a unique route to the Catalina engine.
    Replace the line:
    <Engine name="Standalone" defaultHost="localhost" debug="0">
    with:
    <Engine jvmRoute="worker1" name="Standalone" defaultHost="localhost" debug="0">

    Explanations:
      name: Logical name of this Engine, used in log and error messages
      jvmRoute: Uniquely identifies the Tomcat server to the Apache server
    Name has been specified in the workers.properties
      defaultHost: Identifies the Host that will process requests directed to host names on this server
      debug: The level of debugging detail logged by this Engine

    Note: The jvmRoute name should be the same as the name of the associated worker defined in worker.properties. This will ensure the Session affinity.
               Refer to the Engine Container documentation.

Configuring JOnAS

In the JOnAS-specific deployment descriptor, add the tag shared for the entity beans involved and set it to true. When this flag is set to true, multiple instances of the same entity bean in different JOnAS servers can access a common database concurrently.

The following is an example of a deployment descriptor with the flag shared:

<jonas-ejb-jar>
  <jonas-entity>
    <ejb-name>Id_1</ejb-name>
    <jndi-name>clusterId_1</jndi-name>
    <shared>true</shared>
    <jdbc-mapping>
      <jndi-name>jdbc_1</jndi-name>
      <jdbc-table-name>clusterIdentityEC</jdbc-table-name>
      <cmp-field-jdbc-mapping>
        <field-name>name</field-name>
        <jdbc-field-name>c_name</jdbc-field-name>
      </cmp-field-jdbc-mapping>
      <cmp-field-jdbc-mapping>
        <field-name>number</field-name>
        <jdbc-field-name>c_number</jdbc-field-name>
      </cmp-field-jdbc-mapping>
      <finder-method-jdbc-mapping>
        <jonas-method>
          <method-name>findByNumber</method-name>
        </jonas-method>
        <jdbc-where-clause>where c_number = ?</jdbc-where-clause>
      </finder-method-jdbc-mapping>
      <finder-method-jdbc-mapping>
        <jonas-method>
          <method-name>findAll</method-name>
        </jonas-method>
        <jdbc-where-clause></jdbc-where-clause>
      </finder-method-jdbc-mapping>
    </jdbc-mapping>
  </jonas-entity>
</jonas-ejb-jar>

Running a Web Application

The web application is now ready to run, be sure to follow the launching order:
  1. Start the jonas servers: jonas start.
  2. Restart Apache: /usr/local/apache2/bin/apachectl restart.
  3. Use a browser to access the welcome page, usually index.html.

Note: It is mportant to adhere to the launching order; otherwise, it will not work correctly.

Session Replication at web level

The intent of this chapter is to configure Apache, Tomcat, and JOnAS to run the following architecture:

archi2

The term session replication is used when the current service state is being replicated across multiple application instances. Session replication occurs when the information stored in an HttpSession is replicated from, in this example, one servlet engine instance to another. This could be data such as items contained in a shopping cart or information being entered on an insurance application. Anything being stored in the session must be replicated for the service to failover without a disruption.

The solution chosen for achieving Session replication is called all-to-all replication. Tomcat uses a proprietary protocol based on TCP for the all-to-all replication.

The follow describes the steps for achieving Session replication with JOnAS.

Running your Web Application

The web application is now ready to run in the cluster:
  1. Start the JOnAS servers: jonas start.
  2. Restart Apache: /usr/local/apache2/bin/apachectl restart.
  3. Use a browser to access the welcome page, usually index.html.

Load Balancing at EJB level

The intent of this chapter is to configure JOnAS to run the following architecture:

archi3

CMI Principles

CMI is a new ORB used by JOnAS to provide clustering for load balancing and high availability. Several instances of JOnAS can be started together in a cluster to share their EJBs. It is possible to start the same EJB on each JOnAS, or to distribute their load. A URL referencing several JOnAS instances can be provided to the clients. At lookup time, a client randomly chooses one of the available servers to request the required bean. Each JOnAS instance has the knowledge (through Javagroups) of the distribution of the Beans in the cluster. An answer to a lookup is a special clustered stub, containing stubs to each instance known in the cluster. Each method call on the Home of the bean can be issued by the stub to a new instance, to balance the load on the cluster. The default algorithm used for load distribution is currently a weighted round robin.

CMI Configuration

In the case of EJB level clustering (CMI), the client may be either a fat Java client (e.g. a Swing application), or a Web application (i.e. Servlets/JSPs running within JOnAS). In the second case, the JOnAS server running the Web client should be configured in the same way as the other nodes of the cluster.

Note 1: The multicast address and group name must be the same for all JOnAS servers in the cluster.

Note 2: If Tomcat Replication associated to cmi is used, the multicast addresses of the two configurations must be different.

Clustering databases with C-JDBC

With C-JDBC it is possible to cluster databases. Refer to HowTo setup a C-JDBC Database.

Preview of a coming version

A solution that enables failover at EJB level is currently under development. This signifies state replication for stateful session beans and entity beans.
This will enable the following architecture:

archi5

Used symbols

node A node (computer) that hosts one or more servers 
WebCont A web container EJBCont An ejb container
JOnASWeb A JOnAS instance that hosts a web container JOnASEJB A JOnAS instance that hosts an ejb container
FullJOnAS A JOnAS instance that hosts a web container and an ejb container
Apache An Apache server with the mod_jk module

References