Add some session values. Now stop the Tomcat you are on. The Apache error log, usually found in /var/log/http/error_log, reports the connection loss. Our dispatcher will no longer send requests to that worker. It checks regularly to see if the worker is back up, and will start using it again as soon as it is.

When you stop the worker you are using, you don't receive any errors. The dispatcher will automatically send any further requests to another worker. Your session, however, is lost. Any values you just added will no longer be there.

To prevent this session loss, we must get the two Tomcats to talk to each other.

Cluster the Tomcats

We now have Apache acting as a dispatcher for our two Tomcat workers. The next step is to get the two Tomcats to swap session data. Once they share session data, we can stop any one of the Tomcat workers without the user losing his work or state.

Edit server.xml and remove the comment tags from around the Cluster element on both servers. On server2, change the Receiver element's tcpListenPort to 4002. As both our Tomcat servers are on the same machine, the port needs to differ.

Edit the webapps/servlets-examples/WEB-INF/web.xml on both servers. Below the <display-name>..</display-name> element, include the line:

  <distributable /> 

Tomcat will only replicate those sessions for Web applications marked as distributable.

Start both servers back up. In catalina.out, you should notice the two servers discovering each other and communicating.

You can now stop either Tomcat and your session will not be lost. Add some values to your session and stop Tomcat, just as we did previously. This time, your values should remain. If we had not changed the servlet to print which server it runs on, we would not know anything had happened. Tomcat workers can come and go without the site users ever knowing. Neat!

Note: You cannot cluster different versions of Tomcat. For example 5.0.25 and 5.0.28 will not work. Data is sent between them in a serialized form, and Java will only deserialize an object to the same version of the classfile that serialized it.

Using the session

Objects placed on the session must implement java.io.Serializable for Tomcat's clustering to replicate them. Every session change is replicated to every other server in the cluster, so it is wise to use the session as little as possible.

Unless you perceive URL parameters to be a security risk, use URL parameters instead of the session. Work with the idea that users will copy the URL and email it to others—i.e., the application must be able to rebuild the state from the URL parameters.

When using HTTP basic authentication (over SSL or in a trusted environment), the user does not need to be on the session since the authentication details are sent in every request. You could write a servlet filter that retrieves the user details from the request, checks them, loads your User object, and puts it where the rest of the application can find it.

By reducing session usage to a minimum, the user's browsing experience becomes more natural—the browser's Forward and Back buttons will work as intended, bookmarking pages will work, as will sending URLs to other users.

Change the cluster dynamically: The jkstatus page

In the workers2.properties file, we defined a [status:status] element mapped to URI /jkstatus. Let's look at that in more depth.

Go to http://localhost/jkstatus. You should see something like this:

This is your workers2.properties file after Apache has digested it. Click the Scoreboard info link—if that page says no Scoreboard is available, check that you have the [shm:] element. That area of shared memory is the Scoreboard.

The most interesting aspect of the jkstatus worker is that it reloads the workers2.properties file when you hit that page. This means we can change the cluster configuration without restarting any servers.

For example, edit workers2.properties and disable server2 by adding the disabled property and increasing the ver number:

   [channel.socket:server2]     host=127.0.0.1     port=8010     tomcatId=server2     ver=1     disabled=1 

Go to /jkstatus, and you should notice a message in the top left corner saying something like:

  Updated config version to 4 Status information for child 6 

You should also see that the disabled field for server2 is set. Server2 will no longer accept any new sessions. Similarly, we could add a new Tomcat to the cluster by adding a new channel.socket entry.

By changing the owner of workers2.properties, we could edit it and reload it into the server without ever needing to reboot. We could add or remove cluster workers from an Ant or Maven task, from a shell script, from a CGI script, or even from a scheduled task such as a Unix cron job. Heck, we could even write a script that parsed Apache's log, calculated the current average load, and added or removed Tomcat workers as needed!

Simple scenarios

In the current setup, the two servers equally share the work. If server2 were on a less powerful machine, we might want to give it a lower percentage of the traffic. What percentage of the traffic a worker receives is set via the channel.socket element's lb_factor property. The smaller the number, the more often Tomcat will receive requests. The lb_factor property defaults to 1. To reduce server2's load, edit its entry to:

  [channel.socket:server2]    host=127.0.0.1    port=8010    tomcatId=server2    ver=1    lb_factor=2 

The other scenaro we might need is failover. For server2 to receive requests only if server1 fails, use the level property:

  [channel.socket:server1]    host=127.0.0.1    port=8009    tomcatId=server1    level=0    ver=2    [channel.socket:server2]    host=127.0.0.1    port=8010    tomcatId=server2    ver=2    level=1 

The level can be 0-3. All the lower-numbered levels are checked before any higher levels receive a request. Server2 will receive requests only if server1 no longer responds.

Note that we change the ver number for each edit so that jkstatus will reload the file.

Cleaning up

Having tested our Apache/Tomcat cluster, we can tidy up the server.xml. You can comment out the HTTP connector in the server.xml file, as it should not be accessible in production use. Another option is to use firewall rules to block those ports from the outside world. Then we can keep the connector for use in testing or for accessing administration applications not mapped by a [uri:] element in the workers2.properties file.

Conclusion

We started with one instance of Tomcat and lost traffic whenever we needed to work on it. Now we have Apache with any number of Tomcat workers behind it, and we can stop and start these at will. Requests and sessions are safe. We can change the cluster settings without restarting Apache.

A few years ago, you could only get this functionality with an expensive, proprietary, and cumbersome J2EE server. Today we can do it with Apache and Tomcat. Thanks to the Tomcat developers and the open source model!

Author Bio

Graham King is senior software engineer for KBC Financial Products in London, where he builds Java Web applications in an agile team. Previously he built a content-monetizing framework in Java for Go Internet, and prior to that wrote lots of C. In his spare time, he volunteers with the Greenpeace I.T. team, and is an enthusiastic hiker.

Resources