The Cluster Valve object

Table of Contents

Introduction

A cluster valve is no different from any other Tomcat Valve. The cluster valves are interceptors in the invocation chain for HTTP requests, and the clustering implementation uses these valves to make intelligent decision around data and when data should be replicated.

A cluster valve must implement the org.apache.catalina.ha.ClusterValve interface. This is a simple interface that extends the org.apache.catalina.Valve interface.

org.apache.catalina.ha.tcp.ReplicationValve

The ReplicationValve will notify the cluster at the end of a HTTP request so that the cluster can make a decision whether there is data to be replicated or not.

Attributes

Attribute Description
className Set value to org.apache.catalina.ha.tcp.ReplicationValve
filter For known file extensions or urls, you can use this Valve to notify the cluster that the session has not been modified during this request and the cluster doesn't have to probe the session managers for changes. If the request matches this filter pattern, the cluster assumes there has been no session change. An example filter would look like filter=".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt" . The filter is a regular expression using java.util.regex.
primaryIndicator Boolean value, so to true, and the replication valve will insert a request attribute with the name defined by the primaryIndicatorName attribute. The value inserted into the request attribute is either Boolean.TRUE or Boolean.FALSE
primaryIndicatorName Default value is org.apache.catalina.ha.tcp.isPrimarySession The value defined here is the name of the request attribute that contains the boolean value if the session is primary on this server or not.
statistics Boolean value. Set to true if you want the valve to collect request statistics. Default value is false

org.apache.catalina.ha.session.JvmRouteBinderValve

In case of a mod_jk failover, the JvmRouteBinderValve will replace the jvmWorker attribute in the session Id, to make future requests stick to this node. If you want fallback capability, don't enable this valve, but if you want your failover to stick, and for mod_jk not to have to keep probing the node that went down, you use this valve.

Attributes

Attribute Description
className org.apache.catalina.ha.session.JvmRouteBinderValve
enabled Default value is true Runtime attribute to turn on and off turn over of the session's jvmRoute value.
sessionIdAttribute Old sessionid before failover is registered in request attributes with this attribute. Default attribute name is org.apache.catalina.ha.session.JvmRouteOrignalSessionID.

org.apache.catalina.ha.authenticator.ClusterSingleSignOn

The ClusterSingleSignOn supports feature of single sign on in cluster. By using ClusterSingleSignOn, the security identity authenticated by one web application is recognized by other web applications on the same virtual host, and it is propagated to other nodes in the cluster.

See the Single Sign On special feature on the Host element for more information.

Note: ClusterSingleSignOn can be configured at host level cluster only.

Attributes

Attribute Description
className

Java class name of the implementation to use. This MUST be set to org.apache.catalina.ha.authenticator.ClusterSingleSignOn.

cookieDomain

Sets the host domain to be used for sso cookies.

mapSendOptions

The Valve uses a replicated map. You can setup the flag for how this map sends messages. The default value is 6 (synchronous). Note that if you use asynchronous messaging it is possible for update messages to be processed by the receiving node in a different order to the order in which they were sent.

requireReauthentication

Default false. Flag to determine whether each request needs to be reauthenticated to the security Realm. If "true", this Valve uses cached security credentials (username and password) to reauthenticate to the Realm each request associated with an SSO session. If "false", the Valve can itself authenticate requests based on the presence of a valid SSO cookie, without rechecking with the Realm.

rpcTimeout

The Valve uses a replicated map. This is the timeout for messages that transfer state to/from the other nodes in the cluster. If not specified, a default value of 15000 milliseconds is used.

terminateOnStartFailure

Set to true if you wish this Valve to fail if the underlying replication fails to start. If the Valve fails, then the associated container will fail to start. If you set this attribute to false, and the underlying replications fails to start, the Valve will start and it will attempt to join the cluster and start replication as part of the heartbeat process. If not specified, the default value of false is used.

accessTimeout The timeout for a ping message. If a remote map does not respond within this timeout period, its regarded as disappeared. Default value is 5000 milliseconds.

Comments

Notice: This comments section collects your suggestions on improving documentation for Apache Tomcat.

If you have trouble and need help, read Find Help page and ask your question on the tomcat-users mailing list. Do not ask such questions here. This is not a Q&A section.

The Apache Comments System is explained here. Comments may be removed by our moderators if they are either implemented or considered invalid/off-topic.