Google Summer of Code 2006 on Apache Tomcat

Functionalities

I would have liked to participate to the Google Summer of Code 2006 on Apache Tomcat, but I wasn't selected. Anyway I developped two functionalities for the Tomcat server.

• The SingleSignOn for a Tomcat cluster.
• The use of JMS to send all the ClusterMessages between nodes in a Tomcat cluster.

Installation

You have to download the ClusterSingleSignOn patch for Tomcat 5.5 or ClusterSingleSignOn patch for Tomcat 6.0 and the JMS Cluster patch for Tomcat 5.5 and the jms library from geronimo. Then to install the patchs you have to apply it on a last svn snapshot from Tomcat and save the jms library in /usr/share/java. Afterwards you have to compile Tomcat like always with ant.

To configure the ClusterSingleSingOn in the file server.xml, you have to declare a Valve in the cluster Host like this :

• <Valve className="org.apache.catalina.ha.authenticator.ClusterSingleSignOn" />

To configure the JMS Cluster in the file server.xml, you have to declare a Cluster in the Host like this :

• You have to declare a JMS Connection Factory Resource and a JMS Topic Resource in GlobalNamingResources. You can use my JMS jndi howto. The unique server which works actually is ActiveMQ.
• <Resource name="jms/ActiveMQConnectionFactory" auth="Container" type="org.apache.activemq.ActiveMQConnectionFactory" description="JMS Connection Factory" factory="org.apache.activemq.jndi.JNDIReferenceFactory" brokerName="LocalActiveMQBroker"/>
• <Resource name="jms/ActiveMQTopic" auth="Container" type="org.apache.activemq.command.ActiveMQTopic" description="my Topic" factory="org.apache.activemq.jndi.JNDIReferenceFactory" physicalName="cluster.tomcat"/>
• Then the cluster comes that way
• <Cluster className="org.apache.catalina.cluster.jms.SimpleJmsCluster" managerClassName="org.apache.catalina.cluster.session.DeltaManager" expireSessionsOnShutdown="false" useDirtyFlag="true" persistent="false" connectionFactory="jms/ActiveMQConnectionFactory" topic="jms/ActiveMQTopic" clientId="node01" notifyListenersOnReplication="true" doClusterLog="true" clusterLogName="clusterlog"> <Membership className="org.apache.catalina.cluster.jms.MjmsService" mjmsFrequency="500" mjmsDropTime="3000"/> <Receiver className="org.apache.catalina.cluster.jms.ReplicationListener" /> <Sender className="org.apache.catalina.cluster.jms.ReplicationTransmitter" /> <Valve className="org.apache.catalina.cluster.tcp.ReplicationValve" filter=".*\.gif;.*\.js;.*\.jpg;.*\.png;.*\.htm;.*\.html;.*\.css;.*\.txt;"/> <Deployer className="org.apache.catalina.cluster.deploy.FarmWarDeployer" tempDir="/tmp/war-temp/" deployDir="/tmp/war-deploy/" watchDir="/tmp/war-listen/" watchEnabled="false"/> <ClusterListener className="org.apache.catalina.cluster.session.ClusterSessionListener"/> </Cluster>

If you want to do a benchmark, you can use tsung and adapt this test file.

Technicals comments

The new directory authenticator in org.apache.catalina.cluster

ClusterSingleSignOn.java	It is a SingleSignOn extension. It start the ClusterSingleSignOnListener and has some functions to call the SingleSignOn functions from the cluster environment.
ClusterSingleSignOnListener.java	It is a ClusterListener extension. It received the SingleSignOnMessage and call ClusterSingleSignOn on the right function.
mbeans-descriptors.xml	The descriptor for the JMX functionality. I don't know if I have to create a function to register the MBeans on the MBeans server or if the register function in SingleSignOn is enough. I have a doubt too on if I have to add in this file the SingleSingOn functions or not.
SingleSignOnMessage.java	It implements ClusterMessage to send between the nodes all the informations on the SSO such as the action, the SSO id, the Session id...

There is a small modification in the SingleSignOn class because sometimes principal can be null. Just a small verification...

The new directory jms in org.apache.catalina.cluster

ClusterJmsException.java	An Exception which happened when there is a problem with the connection to the MOM
Constants.java	Name of the package
mbeans-descriptors.xml	The descriptor for the JMX functionality.
MjmsMember.java	A membership implementation using simple jms. This is the representation of a jms member.
MjmsMessage.java	Contains the Member data, read and written by the MjmsService
MjmsService.java	A membership implementation using simple jms. This is the representation of a jms membership service. This class is responsible for maintaining a list of active cluster nodes in the cluster. If a node fails to send out a heartbeat, the node will be dismissed.
ReplicationListener.java	Implement the jms onMessage function. Receive the jms BytesMessage and convert them to ClusterMessage.
ReplicationTransmitter.java	Use the topicPublisher to send message to the MOM. Convert the message from ClusterMessage to jms BytesMessage.
SimpleJmsCluster.java	The cluster Valve. It uses the configuration to initialize the whole cluster.

In McastMembership I replaced all the references to McastMember by Member. In ReplicationTransmitter, MembershipService and McastService, I replaced the reference to SimpleTcpCluster by a reference to CatalinaCluster. In Member, I added the setMemberAliveTime method.

Links

• My applying on the apache wiki.
• The first patch to activate SingleSignOn on a Tomcat cluster.
• The tsung framework to do benchmarking.
• The submit of the clustersinglesignon patch on the mailing list.

Documentation

This is an howto which explain how to use Tomcat JMS Cluster.

---

© Fabien Carrion, 2006 - 2008.