<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-valve.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Valve object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
A cluster valve is no different from any other <a href="valve.html">Tomcat <code>Valve</code></a>.
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.
</p>
<p>
A cluster valve must implement the <code>org.apache.catalina.ha.ClusterValve</code> interface.
This is a simple interface that extends the <code>org.apache.catalina.Valve</code> interface.
</p>
</section>
<section name="org.apache.catalina.ha.tcp.ReplicationValve">
The <code>ReplicationValve</code> 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.
<subsection name="Attributes">
<attributes>
<attribute name="className" required="true">
Set value to <code>org.apache.catalina.ha.tcp.ReplicationValve</code>
</attribute>
<attribute name="filter" required="false">
For known file extensions or urls, you can use a filter 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 there is a filter match, the cluster assumes there has been no session change.
An example filter would look like <code>filter=".*\.gif;.*\.js;.*\.jpg;.*\.png;.*\.htm;.*\.html;.*\.css;.*\.txt;"</code>
The filter uses regular expressions and each filter is delimited by a semi colon.
<code>Pattern#compile(java.lang.String)</code>
</attribute>
<attribute name="primaryIndicator" required="false">
Boolean value, so to true, and the replication valve will insert a request attribute with the name
defined by the <code>primaryIndicatorName</code> attribute.
The value inserted into the request attribute is either <code>Boolean.TRUE</code> or
<code>Boolean.FALSE</code>
</attribute>
<attribute name="primaryIndicatorName" required="false">
Default value is <code>org.apache.catalina.ha.tcp.isPrimarySession</code>
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.
</attribute>
<attribute name="statistics" required="false">
Boolean value. Set to <code>true</code> if you want the valve to collect request statistics.
Default value is <code>false</code>
</attribute>
</attributes>
</subsection>
</section>
<section name="org.apache.catalina.ha.session.JvmRouteBinderValve">
In case of a mod_jk failover, the <code>JvmRouteBinderValve</code> will replace the
<code>jvmWorker</code> attribute in the session Id, to make future requests stick to this
node. If you want failback 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.
<subsection name="Attributes">
<attributes>
<attribute name="className" required="true">
<code>org.apache.catalina.ha.session.JvmRouteBinderValve</code>
</attribute>
<attribute name="enabled" required="false">
Default value is <code>true</code>
Runtime attribute to turn on and off turn over of the session's jvmRoute value.
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>