This tag marks a web application as distributable, which means it is suitable for running in a distributed environment, such as a clustered Tomcat installation.

If marked as distributable, all new sessions, and changes to existing sessions will be replicated to other members of the cluster by the session-replicator, according to the replication rules in server.xml.

If an application is run in a cluster without being marked as distributable, session changes will only occur on a single JVM. Therefore, when the user connects to one of the other JVM's, their session will not be recognised, and a new session will be created. This may force them to log in again, establishing a 2nd session on the other JVM. As they switch between the two servers, various other problems may arise.

In a load-balanced cluster, user requests are sent to two or more JVM's. To implement session-failover, all applications running on the cluster must be distributable to properly maintain session state across the multiple servers.


The distributable tag is one of the only tags that is defined as a single self-closing tag. It is safe to use in a single JVM, but of course you won't be able to properly test your clustering, because there won't be any other members in the cluster to distribute the session to.

Use it in web.xml as follows:

<distributable />

Requirements of a distributable Tomcat application

For an application to be distributable in a Tomcat cluster, it must follow a few basic rules:

  • All session attributes must be serializable (must implement java.io.Serializable). Most native java objects, including data types such as Strings and Integers implement this functionality.
  • After changing any objects which are stored in the session, HttpSession.setAttribute() must be called to inform the session replicator that the session has changed.
  • Ideally, sessions should be kept relatively small, to ensure less network traffic between the each clustered VM.
  • Background processor threads such as mailer-threads, should ensure they are only running on one of the VMs, or have methods for dealing with multithreading across VM's. Static objects, synchronization and other traditional communication methods for locking resources are not possible, so care must be taken to ensure the application is cluster-ready.
  • Ideally, data should not be stored as flat files unless the file system will be common between all members of the cluster. For example, an image-upload system could store images directly into the database. If this is not possible, then a common file system can be achieved by using a SAN or NAS, replication of the image-store folder between servers, or by limiting the application to 2 clustered VMs which run on the same server.

More Information

metawerx specific

referring pages