<?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="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 webapp is deployed.<br/>
  We are planning to add more managers with even more sophisticated backup mechanism to support even larger clusters.
  Check back soon! 
  </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 webapplication 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">
      Set to true if you wish sessions to be replicated only to members that have the same logical
      domain set. If set to false, session replication will ignore the domain setting the 
      <code><a href="cluster-membership.html">&lt;Membership&gt;</a></code>
      element.
     </attribute>
     <attribute name="expireSessionsOnShutdown" required="false">
       When a webapplication 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="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>
    </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>(asynchronous).
     </attribute>
    </attributes>
  </subsection>
</section>
</body>
</document>
