<?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-manager.html">

  &project;

  <properties>
    <author email="fhanik@apache.org">Filip Hanik</author>
    <title>The ClusterManager object</title>
  </properties>

<body>

<section name="Table of Contents">
<toc/>
</section>

<section name="Introduction">
  <p>A cluster manager is an extension to Tomcat's session manager interface, 
  <code>org.apache.catalina.Manager</code>.
  A cluster manager must implement the
  <code>org.apache.catalina.ha.ClusterManager</code> and is solely  responsible
  for how the session is replicated.<br/>
  There are currently two different managers, the
  <code>org.apache.catalina.ha.session.DeltaManager</code> replicates deltas of
  session data to all members in the cluster. This implementation is proven and
  works very well, but has a limitation as it requires the cluster members to be
  homogeneous, all nodes must deploy the same applications and be exact
  replicas. The <code>org.apache.catalina.ha.session.BackupManager</code> also
  replicates deltas but only to one backup node. The location of the backup node
  is known to all nodes in the cluster. It also supports heterogeneous
  deployments, so the manager knows at what locations the web application is
  deployed.</p>
</section>

<section name="The &lt;Manager&gt;">
  <p>The <code>&lt;Manager&gt;</code> element defined inside the
  <code>&lt;Cluster&gt;</code> element is the template defined for all web
  applications that are marked <code>&lt;distributable/&gt;</code> in their
  <code>web.xml</code> file. However, you can still override the manager
  implementation on a per web application basis, by putting the
  <code>&lt;Manager&gt;</code> inside the <code>&lt;Context&gt;</code> element
  either in the <code><a href="context.html">context.xml</a></code> file or the
  <code><a href="index.html">server.xml</a></code> file.</p> 
</section>

<section name="Attributes">
  <subsection name="Common Attributes">
    <attributes>
      <attribute name="className" required="true">
      </attribute>
      <attribute name="name" required="false">
        <b>The name of this cluster manager, the name is used to identify a
        session manager on a node. The name might get modified by the
        <code>Cluster</code> element to make it unique in the container.</b>
      </attribute>
      <attribute name="defaultMode" required="false">
        <b>Deprecated since 6.0.0</b>
      </attribute>
      <attribute name="notifyListenersOnReplication" required="false">
        Set to <code>true</code> if you wish to have session listeners notified
        when session attributes are being replicated or removed across Tomcat
        nodes in the cluster.
      </attribute>
      <attribute name="expireSessionsOnShutdown" required="false">
        When a web application is being shutdown, Tomcat issues an expire call
        to each session to notify all the listeners. If you wish for all
        sessions to expire on all nodes when a shutdown occurs on one node, set
        this value to <code>true</code>. Default value is <code>false</code>.
      </attribute>
    </attributes>
  </subsection> 
  <subsection name="org.apache.catalina.ha.session.DeltaManager Attributes">
    <attributes>
      <attribute name="domainReplication" required="false">
        <b>Deprecated since 6.0.0</b><br/>
        If you wish sessions to be replicated only to members that have the 
        same logical domain set, use 
        <code><a href="cluster-interceptor.html">DomainFilterInterceptor </a></code>.
      </attribute>
      <attribute name="expireSessionsOnShutdown" required="false">
        When a web application is being shutdown, Tomcat issues an expire call
        to each session to notify all the listeners. If you wish for all
        sessions to expire on all nodes when a shutdown occurs on one node, set
        this value to <code>true</code>.
        Default value is <code>false</code>.
      </attribute>
      <attribute name="maxActiveSessions" required="false">
        The maximum number of active sessions that will be created by this
        Manager, or -1 (the default) for no limit. For this manager, all
        sessions are counted as active sessions irrespective if whether or not
        the current node is the primary node for the session.
      </attribute>
      <attribute name="notifySessionListenersOnReplication" required="false">
        Set to <code>true</code> if you wish to have session listeners notified
        when sessions are created and expired across Tomcat nodes in the
        cluster.
      </attribute>
      <attribute name="notifyContainerListenersOnReplication" required="false">
        Set to <code>true</code> if you wish to have container listeners notified
        across Tomcat nodes in the cluster.
      </attribute>
      <attribute name="stateTransferTimeout" required="false">
        The time in seconds to wait for a session state transfer to complete
        from another node when a node is starting up.
        Default value is <code>60</code> seconds.
      </attribute>
      <attribute name="sessionAttributeNameFilter" required="false">
        <p>A regular expression used to filter which session attributes will be
        replicated. An attribute will only be replicated if its name matches
        this pattern. If the pattern is zero length or <code>null</code>, all
        attributes are eligible for replication. The pattern is anchored so the
        session attribute name must fully match the pattern. As an example, the
        value <code>(userName|sessionHistory)</code> will only replicate the
        two session attributes named <code>userName</code> and
        <code>sessionHistory</code>. If not specified, the default value of
        <code>null</code> will be used.</p>
      </attribute>
      <attribute name="sessionAttributeValueClassNameFilter" required="false">
        <p>A regular expression used to filter which session attributes will be
        replicated. An attribute will only be replicated if the implementation
        class name of the value matches this pattern. If the pattern is zero
        length or <code>null</code>, all attributes are eligible for
        replication. The pattern is anchored so the fully qualified class name
        must fully match the pattern. If not specified, the default value of
        <code>null</code> will be used unless a <code>SecurityManager</code> is
        enabled in which case the default will be
        <code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)</code>.</p>
      </attribute>
      <attribute name="warnOnSessionAttributeFilterFailure" required="false">
        <p>If <strong>sessionAttributeNameFilter</strong> or
        <strong>sessionAttributeValueClassNameFilter</strong> blocks an
        attribute, should this be logged at <code>WARN</code> level? If
        <code>WARN</code> level logging is disabled then it will be logged at
        <code>DEBUG</code>. The default value of this attribute is
        <code>false</code> unless a <code>SecurityManager</code> is enabled in
        which case the default will be <code>true</code>.</p>
      </attribute>
    </attributes>
  </subsection>
  <subsection name="org.apache.catalina.ha.session.BackupManager Attributes">
    <attributes>
      <attribute name="mapSendOptions" required="false">
        The backup manager uses a replicated map, this map is sending and
        receiving messages. You can setup the flag for how this map is sending
        messages, the default value is <code>6</code>(synchronous).<br/>
        Note that if you use asynchronous messaging it is possible for update
        messages for a session to be processed by the receiving node in a
        different order to the order in which they were sent.
      </attribute>
      <attribute name="maxActiveSessions" required="false">
        The maximum number of active sessions that will be created by this
        Manager, or -1 (the default) for no limit. For this manager, only
        sessions where the current node is the primary node for the session are
        considered active sessions.
      </attribute>
      <attribute name="rpcTimeout" required="false">
        Timeout for RPC message used for broadcast and transfer state from 
        another map.
        Default value is <code>15000</code> milliseconds.
      </attribute>
      <attribute name="sessionAttributeNameFilter" required="false">
        <p>A regular expression used to filter which session attributes will be
        replicated. An attribute will only be replicated if its name matches
        this pattern. If the pattern is zero length or <code>null</code>, all
        attributes are eligible for replication. The pattern is anchored so the
        session attribute name must fully match the pattern. As an example, the
        value <code>(userName|sessionHistory)</code> will only replicate the
        two session attributes named <code>userName</code> and
        <code>sessionHistory</code>. If not specified, the default value of
        <code>null</code> will be used.</p>
      </attribute>
      <attribute name="sessionAttributeValueClassNameFilter" required="false">
        <p>A regular expression used to filter which session attributes will be
        replicated. An attribute will only be replicated if the implementation
        class name of the value matches this pattern. If the pattern is zero
        length or <code>null</code>, all attributes are eligible for
        replication. The pattern is anchored so the fully qualified class name
        must fully match the pattern. If not specified, the default value of
        <code>null</code> will be used unless a <code>SecurityManager</code> is
        enabled in which case the default will be
        <code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)</code>.</p>
      </attribute>
      <attribute name="warnOnSessionAttributeFilterFailure" required="false">
        <p>If <strong>sessionAttributeNameFilter</strong> or
        <strong>sessionAttributeValueClassNameFilter</strong> blocks an
        attribute, should this be logged at <code>WARN</code> level? If
        <code>WARN</code> level logging is disabled then it will be logged at
        <code>DEBUG</code>. The default value of this attribute is
        <code>false</code> unless a <code>SecurityManager</code> is enabled in
        which case the default will be <code>true</code>.</p>
      </attribute>
    </attributes>
  </subsection>
</section>
</body>
</document>
