http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/class-loader-howto.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/class-loader-howto.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/class-loader-howto.html new file mode 100644 index 0000000..524ccad --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/class-loader-howto.html @@ -0,0 +1,164 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - Class Loader HOW-TO</title><meta content="Craig R. McClanahan" name="author"><meta content="Yoav Shapira" name="author"><style media="print" type="text/css"> + .noPrint {display: none;} + td#mainBody {width: 100%;} + </style></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/";><img border="0" alt=" + The Apache Tomcat Servlet/JSP Container + " align="right" src="./images/tomcat.gif"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1></td><td><!--APACHE LOGO--><a href="http://www.apache.org/";><img border="0" alt="Apache Logo" align="right" src="./images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td class="noPrint" nowrap valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ";>FAQ</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a hr ef="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-ho sting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/";>JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions";>Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td id="mainBody" align="left" valign="top" width="80%"><h1>Apache Tomcat 6.0</h1> <h2>Class Loader HOW-TO</h2><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote> +<ul><li><a href="#Overview">Overview</a></li><li><a href="#Class_Loader_Definitions">Class Loader Definitions</a></li><li><a href="#XML_Parsers_and_JSE_5">XML Parsers and JSE 5</a></li><li><a href="#Running_under_a_security_manager">Running under a security manager</a></li></ul> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote> + +<p>Like many server applications, Tomcat 6 installs a variety of class loaders +(that is, classes that implement <code>java.lang.ClassLoader</code>) to allow +different portions of the container, and the web applications running on the +container, to have access to different repositories of available classes and +resources. This mechanism is used to provide the functionality defined in the +Servlet Specification, version 2.4 -- in particular, Sections 9.4 and 9.6.</p> + +<p>In a J2SE 2 (that is, J2SE 1.2 or later) environment, class loaders are +arranged in a parent-child tree. Normally, when a class loader is asked to +load a particular class or resource, it delegates the request to a parent +class loader first, and then looks in its own repositories only if the parent +class loader(s) cannot find the requested class or resource. The model for +web application class loaders differs slightly from this, as discussed below, +but the main principles are the same.</p> + +<p>When Tomcat 6 is started, it creates a set of class loaders that are +organized into the following parent-child relationships, where the parent +class loader is above the child class loader:</p> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> + Bootstrap + | + System + | + Common + / \ + Webapp1 Webapp2 ... +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<p>The characteristics of each of these class loaders, including the source +of classes and resources that they make visible, are discussed in detail in +the following section.</p> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Class Loader Definitions"><!--()--></a><a name="Class_Loader_Definitions"><strong>Class Loader Definitions</strong></a></font></td></tr><tr><td><blockquote> + +<p>As indicated in the diagram above, Tomcat 6 creates the following class +loaders as it is initialized:</p> +<ul> +<li><strong>Bootstrap</strong> - This class loader contains the basic runtime + classes provided by the Java Virtual Machine, plus any classes from JAR + files present in the System Extensions directory + (<code>$JAVA_HOME/jre/lib/ext</code>). <em>NOTE</em> - Some JVMs may + implement this as more than one class loader, or it may not be visible + (as a class loader) at all.</li> +<li><strong>System</strong> - This class loader is normally initialized from + the contents of the <code>CLASSPATH</code> environment variable. All such + classes are visible to both Tomcat internal classes, and to web + applications. However, the standard Tomcat 6 startup scripts + (<code>$CATALINA_HOME/bin/catalina.sh</code> or + <code>%CATALINA_HOME%\bin\catalina.bat</code>) totally ignore the contents + of the <code>CLASSPATH</code> environment variable itself, and instead + build the System class loader from the following repositories: + <ul> + <li><em>$CATALINA_HOME/bin/bootstrap.jar</em> - Contains the main() method + that is used to initialize the Tomcat 6 server, and the class loader + implementation classes it depends on.</li> + <li><em>$CATALINA_HOME/bin/tomcat-juli.jar</em> - Package renamed Commons + logging API, and java.util.logging LogManager.</li> + </ul></li> +<li><strong>Common</strong> - This class loader contains additional classes + that are made visible to both Tomcat internal classes and to all web + applications. Normally, application classes should <strong>NOT</strong> + be placed here. All unpacked classes and resources in + <code>$CATALINA_HOME/lib</code>, as well as classes and + resources in JAR files are made visible through this + class loader. By default, that includes the following: + <ul> + <li><em>annotations-api.jar</em> - JEE annotations classes.</li> + <li><em>catalina.jar</em> - Implementation of the Catalina servlet + container portion of Tomcat 6.</li> + <li><em>catalina-ant.jar</em> - Tomcat Catalina Ant tasks.</li> + <li><em>catalina-ha.jar</em> - High availability package.</li> + <li><em>catalina-tribes.jar</em> - Group communication package.</li> + <li><em>el-api.jar</em> - EL 2.1 API.</li> + <li><em>jasper.jar</em> - Jasper 2 Compiler and Runtime.</li> + <li><em>jasper-el.jar</em> - Jasper 2 EL implementation.</li> + <li><em>jasper-jdt.jar</em> - Eclipse JDT 3.2 Java compiler.</li> + <li><em>jsp-api.jar</em> - JSP 2.1 API.</li> + <li><em>servlet-api.jar</em> - Servlet 2.5 API.</li> + <li><em>tomcat-coyote.jar</em> - Tomcat connectors and utility classes.</li> + <li><em>tomcat-dbcp.jar</em> - package renamed database connection + pool based on Commons DBCP.</li> + <li><em>tomcat-i18n-**.jar</em> - Optional JARs containing resource bundles + for other languages. As default bundles are also included in each + individual JAR, they can be safely removed if no internationalization + of messages is needed.</li> + </ul></li> +<li><strong>WebappX</strong> - A class loader is created for each web + application that is deployed in a single Tomcat 6 instance. All unpacked + classes and resources in the <code>/WEB-INF/classes</code> directory of + your web application archive, plus classes and resources in JAR files + under the <code>/WEB-INF/lib</code> directory of your web application + archive, are made visible to the containing web application, but to + no others.</li> +</ul> + +<p>As mentioned above, the web application class loader diverges from the +default Java 2 delegation model (in accordance with the recommendations in the +Servlet Specification, version 2.3, section 9.7.2 Web Application Classloader). +When a request to load a +class from the web application's <em>WebappX</em> class loader is processed, +this class loader will look in the local repositories <strong>first</strong>, +instead of delegating before looking. There are exceptions. Classes which are +part of the JRE base classes cannot be overriden. For some classes (such as +the XML parser components in J2SE 1.4+), the J2SE 1.4 endorsed feature can be +used. +Last, any JAR containing servlet API classes will be ignored by the +classloader. +All other class loaders in Tomcat 6 follow the usual delegation pattern.</p> + +<p>Therefore, from the perspective of a web application, class or resource +loading looks in the following repositories, in this order:</p> +<ul> +<li>Bootstrap classes of your JVM</li> +<li>System class loader classes (described above)</li> +<li><em>/WEB-INF/classes</em> of your web application</li> +<li><em>/WEB-INF/lib/*.jar</em> of your web application</li> +<li><em>$CATALINA_HOME/lib</em></li> +<li><em>$CATALINA_HOME/lib/*.jar</em></li> +</ul> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="XML Parsers and JSE 5"><!--()--></a><a name="XML_Parsers_and_JSE_5"><strong>XML Parsers and JSE 5</strong></a></font></td></tr><tr><td><blockquote> + +<p>Among many other changes, the JSE 5 release packages the JAXP APIs, and +a version of Xerces, inside the JRE. This has impacts on applications that +wish to use their own XML parser.</p> + +<p>In previous versions of Tomcat, you could simply replace the XML parser +in the <code>$CATALINA_HOME/common/lib</code> directory to change the parser +used by all web applications. However, this technique will not be effective +when you are running on JSE 5, because the usual class loader delegation +process will always choose the implementation inside the JDK in preference +to this one.</p> + +<p>JDK 1.5 supports a mechanism called the "Endorsed Standards Override +Mechanism" to allow replacement of APIs created outside of the JCP (i.e. +DOM and SAX from W3C). It can also be used to update the XML parser +implementation. For more information, see: +<a href="http://java.sun.com/j2se/1.5/docs/guide/standards/index.html";> +http://java.sun.com/j2se/1.5/docs/guide/standards/index.html</a>.</p> + +<p>Tomcat utilizes this mechanism by including the system property setting +<code>-Djava.endorsed.dirs=$JAVA_ENDORSED_DIRS</code> in the +command line that starts the container.</p> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Running under a security manager"><!--()--></a><a name="Running_under_a_security_manager"><strong>Running under a security manager</strong></a></font></td></tr><tr><td><blockquote> + +<p>When running under a security manager the locations from which classes +are permitted to be loaded will also depend on the contents of your policy +file. See <a href="security-manager-howto.html">Security Manager HOW-TO</a> +for further information.</p> + +</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em> + Copyright © 1999-2010, Apache Software Foundation + </em></font></div></td></tr></table></body></html> \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/cluster-howto.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/cluster-howto.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/cluster-howto.html new file mode 100644 index 0000000..9db8acc --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/cluster-howto.html @@ -0,0 +1,576 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - Clustering/Session Replication HOW-TO</title><meta content="Filip Hanik" name="author"><meta content="Peter Rossbach" name="author"><style media="print" type="text/css"> + .noPrint {display: none;} + td#mainBody {width: 100%;} + </style></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/";><img border="0" alt=" + The Apache Tomcat Servlet/JSP Container + " align="right" src="./images/tomcat.gif"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1></td><td><!--APACHE LOGO--><a href="http://www.apache.org/";><img border="0" alt="Apache Logo" align="right" src="./images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td class="noPrint" nowrap valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ";>FAQ</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a hr ef="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-ho sting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/";>JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions";>Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td id="mainBody" align="left" valign="top" width="80%"><h1>Apache Tomcat 6.0</h1> <h2>Clustering/Session Replication HOW-TO</h2><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Important Note"><!--()--></a><a name="Important_Note"><strong>Important Note</strong></a></font></td></tr><tr><td><blockquote> +<p><b>You can also check the <a href="config/cluster.html">configuration reference documentation.</a></b> +</p> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote> +<ul><li><a href="#For_the_impatient">For the impatient</a></li><li><a href="#Cluster_Basics">Cluster Basics</a></li><li><a href="#Overview">Overview</a></li><li><a href="#Cluster_Information">Cluster Information</a></li><li><a href="#Bind_session_after_crash_to_failover_node">Bind session after crash to failover node</a></li><li><a href="#Configuration_Example">Configuration Example</a></li><li><a href="#Cluster_Architecture">Cluster Architecture</a></li><li><a href="#How_it_Works">How it Works</a></li><li><a href="#FAQ">FAQ</a></li></ul> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="For the impatient"><!--()--></a><a name="For_the_impatient"><strong>For the impatient</strong></a></font></td></tr><tr><td><blockquote> + <p> + Simply add <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre><Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/></pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src= "./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + to your <code><Engine></code> or your <code><Host></code> element to enable clustering. + </p> + <p> + Using the above configuration will enable all-to-all session replication + using the <code>DeltaManager</code> to replicate session deltas. By all-to-all we mean that the session gets replicated to all the other + nodes in the cluster. This works great for smaller cluster but we don't recommend it for larger clusters(a lot of tomcat nodes). + Also when using the delta manager it will replicate to all nodes, even nodes that don't have the application deployed.<br> + To get around this problem, you'll want to use the BackupManager. This manager only replicates the session data to one backup + node, and only to nodes that have the application deployed. Downside of the BackupManager: not quite as battle tested as the delta manager. + <br> + Here are some of the important default values:<br> + 1. Multicast address is 228.0.0.4<br> + 2. Multicast port is 45564 (the port and the address together determine cluster membership.<br> + 3. The IP broadcasted is <code>java.net.InetAddress.getLocalHost().getHostAddress()</code> (make sure you don't broadcast 127.0.0.1, this is a common error)<br> + 4. The TCP port listening for replication messages is the first available server socket in range <code>4000-4100</code><br> + 5. Two listeners are configured <code>ClusterSessionListener</code> and <code>JvmRouteSessionIDBinderListener</code><br> + 6. Two interceptors are configured <code>TcpFailureDetector</code> and <code>MessageDispatch15Interceptor</code><br> + The following is the default cluster configuration:<br> + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> + <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster" + channelSendOptions="8"> + + <Manager className="org.apache.catalina.ha.session.DeltaManager" + expireSessionsOnShutdown="false" + notifyListenersOnReplication="true"/> + + <Channel className="org.apache.catalina.tribes.group.GroupChannel"> + <Membership className="org.apache.catalina.tribes.membership.McastService" + address="228.0.0.4" + port="45564" + frequency="500" + dropTime="3000"/> + <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver" + address="auto" + port="4000" + autoBind="100" + selectorTimeout="5000" + maxThreads="6"/> + + <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter"> + <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/> + </Sender> + <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/> + <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/> + </Channel> + + <Valve className="org.apache.catalina.ha.tcp.ReplicationValve" + filter=""/> + <Valve className="org.apache.catalina.ha.session.JvmRouteBinderValve"/> + + <Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer" + tempDir="/tmp/war-temp/" + deployDir="/tmp/war-deploy/" + watchDir="/tmp/war-listen/" + watchEnabled="false"/> + + <ClusterListener className="org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener"/> + <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/> + </Cluster> + </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + </p> + <p>Will cover this section in more detail later in this document.</p> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Cluster Basics"><!--()--></a><a name="Cluster_Basics"><strong>Cluster Basics</strong></a></font></td></tr><tr><td><blockquote> + +<p>To run session replication in your Tomcat 6.0 container, the following steps +should be completed:</p> +<ul> + <li>All your session attributes must implement <code>java.io.Serializable</code></li> + <li>Uncomment the <code>Cluster</code> element in server.xml</li> + <li>If you have defined custom cluster valves, make sure you have the <code>ReplicationValve</code> defined as well under the Cluster element in server.xml</li> + <li>If your Tomcat instances are running on the same machine, make sure the <code>tcpListenPort</code> + attribute is unique for each instance, in most cases Tomcat is smart enough to resolve this on it's own by autodetecting available ports in the range 4000-4100</li> + <li>Make sure your <code>web.xml</code> has the <code><distributable/></code> element + or set at your <code><Context distributable="true" /></code></li> + <li>If you are using mod_jk, make sure that jvmRoute attribute is set at your Engine <code><Engine name="Catalina" jvmRoute="node01" ></code> + and that the jvmRoute attribute value matches your worker name in workers.properties</li> + <li>Make sure that all nodes have the same time and sync with NTP service!</li> + <li>Make sure that your loadbalancer is configured for sticky session mode.</li> +</ul> +<p>Load balancing can be achieved through many techniques, as seen in the +<a href="balancer-howto.html">Load Balancing</a> chapter.</p> +<p>Note: Remember that your session state is tracked by a cookie, so your URL must look the same from the out + side otherwise, a new session will be created.</p> +<p>Note: Clustering support currently requires the JDK version 1.5 or later.</p> +<p>The Cluster module uses the Tomcat JULI logging framework, so you can configure logging + through the regular logging.properties file. To track messages, you can enable logging on the key:<code>org.apache.catalina.tribes.MESSAGES</code></p> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote> + +<p>To enable session replication in Tomcat, three different paths can be followed to achieve the exact same thing:</p> +<ol> + <li>Using session persistence, and saving the session to a shared file system (PersistenceManager + FileStore)</li> + <li>Using session persistence, and saving the session to a shared database (PersistenceManager + JDBCStore)</li> + <li>Using in-memory-replication, using the SimpleTcpCluster that ships with Tomcat 6 (lib/catalina-tribes.jar + lib/catalina-ha.jar)</li> +</ol> + +<p>In this release of session replication, Tomcat can perform an all-to-all replication of session state using the <code>DeltaManager</code> or + perform backup replication to only one node using the <code>BackupManager</code>. + The all-to-all replication is an algorithm that is only efficient when the clusters are small. For larger clusters, to use + a primary-secondary session replication where the session will only be stored at one backup server simply setup the BackupManager. <br> + Currently you can use the domain worker attribute (mod_jk > 1.2.8) to build cluster partitions + with the potential of having a more scaleable cluster solution with the DeltaManager(you'll need to configure the domain interceptor for this). + In order to keep the network traffic down in an all-to-all environment, you can split your cluster + into smaller groups. This can be easily achieved by using different multicast addresses for the different groups. + A very simple setup would look like this: + </p> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> + DNS Round Robin + | + Load Balancer + / \ + Cluster1 Cluster2 + / \ / \ + Tomcat1 Tomcat2 Tomcat3 Tomcat4 +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<p>What is important to mention here, is that session replication is only the beginning of clustering. + Another popular concept used to implement clusters is farming, i.e., you deploy your apps only to one + server, and the cluster will distribute the deployments across the entire cluster. + This is all capabilities that can go into with the FarmWarDeployer (s. cluster example at <code>server.xml</code>)</p> +<p>In the next section will go deeper into how session replication works and how to configure it.</p> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Cluster Information"><!--()--></a><a name="Cluster_Information"><strong>Cluster Information</strong></a></font></td></tr><tr><td><blockquote> +<p>Membership is established using multicast heartbeats. + Hence, if you wish to subdivide your clusters, you can do this by + changing the multicast IP address or port in the <code><Membership></code> element. +</p> +<p> + The heartbeat contains the IP address of the Tomcat node and the TCP port that + Tomcat listens to for replication traffic. All data communication happens over TCP. +</p> +<p> + The <code>ReplicationValve</code> is used to find out when the request has been completed and initiate the + replication, if any. Data is only replicated if the session has changed (by calling setAttribute or removeAttribute + on the session). +</p> +<p> + One of the most important performance considerations is the synchronous versus asynchronous replication. + In a synchronous replication mode the request doesn't return until the replicated session has been + sent over the wire and reinstantiated on all the other cluster nodes. + Synchronous vs. asynchronous is configured using the <code>channelSendOptions</code> + flag and is an integer value. The default value for the <code>SimpleTcpCluster/DeltaManager</code> combo is + 8, which is asynchronous. You can read more on the <a href="tribes/introduction.html">send flag(overview)</a> or the + <a href="http://tomcat.apache.org/tomcat-6.0-doc/api/org/apache/catalina/tribes/Channel.html";>send flag(javadoc)</a>. + During async replication, the request is returned before the data has been replicated. async replication yields shorter + request times, and synchronous replication guarantees the session to be replicated before the request returns. +</p> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Bind session after crash to failover node"><!--()--></a><a name="Bind_session_after_crash_to_failover_node"><strong>Bind session after crash to failover node</strong></a></font></td></tr><tr><td><blockquote> +<p> + If you are using mod_jk and not using sticky sessions or for some reasons sticky session don't + work, or you are simply failing over, the session id will need to be modified as it previously contained + the worker id of the previous tomcat (as defined by jvmRoute in the Engine element). + To solve this, we will use the JvmRouteBinderValve. +</p> +<p> + The JvmRouteBinderValve rewrites the session id to ensure that the next request will remain sticky + (and not fall back to go to random nodes since the worker is no longer available) after a fail over. + The valve rewrites the JSESSIONID value in the cookie with the same name. + Not having this valve in place, will make it harder to ensure stickyness in case of a failure for the mod_jk module. +</p> +<p> + By default, if no valves are configured, the JvmRouteBinderValve is added on. + The cluster message listener called JvmRouteSessionIDBinderListener is also defined by default and is used to actually rewrite the + session id on the other nodes in the cluster once a fail over has occurred. + Remember, if you are adding your own valves or cluster listeners in server.xml then the defaults are no longer valid, + make sure that you add in all the appropriate valves and listeners as defined by the default. +</p> +<p> + <b>Hint:</b><br> + With attribute <i>sessionIdAttribute</i> you can change the request attribute name that included the old session id. + Default attribute name is <i>org.apache.catalina.cluster.session.JvmRouteOrignalSessionID</i>. +</p> +<p> + <b>Trick:</b><br> + You can enable this mod_jk turnover mode via JMX before you drop a node to all backup nodes! + Set enable true on all JvmRouteBinderValve backups, disable worker at mod_jk + and then drop node and restart it! Then enable mod_jk Worker and disable JvmRouteBinderValves again. + This use case means that only requested session are migrated. +</p> + + + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Configuration Example"><!--()--></a><a name="Configuration_Example"><strong>Configuration Example</strong></a></font></td></tr><tr><td><blockquote> + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> + <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster" + channelSendOptions="6"> + + <Manager className="org.apache.catalina.ha.session.BackupManager" + expireSessionsOnShutdown="false" + notifyListenersOnReplication="true" + mapSendOptions="6"/> + <!-- + <Manager className="org.apache.catalina.ha.session.DeltaManager" + expireSessionsOnShutdown="false" + notifyListenersOnReplication="true"/> + --> + <Channel className="org.apache.catalina.tribes.group.GroupChannel"> + <Membership className="org.apache.catalina.tribes.membership.McastService" + address="228.0.0.4" + port="45564" + frequency="500" + dropTime="3000"/> + <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver" + address="auto" + port="5000" + selectorTimeout="100" + maxThreads="6"/> + + <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter"> + <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/> + </Sender> + <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/> + <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/> + <Interceptor className="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor"/> + </Channel> + + <Valve className="org.apache.catalina.ha.tcp.ReplicationValve" + filter=".*\.gif;.*\.js;.*\.jpg;.*\.png;.*\.htm;.*\.html;.*\.css;.*\.txt;"/> + + <Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer" + tempDir="/tmp/war-temp/" + deployDir="/tmp/war-deploy/" + watchDir="/tmp/war-listen/" + watchEnabled="false"/> + + <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/> + </Cluster> + </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + <p> + Break it down!! + </p> + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> + <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster" + channelSendOptions="6"> + </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + <p> + The main element, inside this element all cluster details can be configured. + The <code>channelSendOptions</code> is the flag that is attached to each message sent by the + SimpleTcpCluster class or any objects that are invoking the SimpleTcpCluster.send method. + The description of the send flags is available at <a href="http://tomcat.apache.org/tomcat-6.0-doc/api/org/apache/catalina/tribes/Channel.html";> + our javadoc site</a> + The <code>DeltaManager</code> sends information using the SimpleTcpCluster.send method, while the backup manager + sends it itself directly through the channel. + <br>For more info, Please visit the <a href="config/cluster.html">reference documentation</a> + </p> + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> + <Manager className="org.apache.catalina.ha.session.BackupManager" + expireSessionsOnShutdown="false" + notifyListenersOnReplication="true" + mapSendOptions="6"/> + <!-- + <Manager className="org.apache.catalina.ha.session.DeltaManager" + expireSessionsOnShutdown="false" + notifyListenersOnReplication="true"/> + --> + </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + <p> + This is a template for the manager configuration that will be used if no manager is defined in the <Context> + element. In Tomcat 5.x each webapp marked distributable had to use the same manager, this is no longer the case + since Tomcat 6 you can define a manager class for each webapp, so that you can mix managers in your cluster. + Obviously the managers on one node's application has to correspond with the same manager on the same application on the other node. + If no manager has been specified for the webapp, and the webapp is marked <distributable/> Tomcat will take this manager configuration + and create a manager instance cloning this configuration. + <br>For more info, Please visit the <a href="config/cluster-manager.html">reference documentation</a> + </p> + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> + <Channel className="org.apache.catalina.tribes.group.GroupChannel"> + </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + <p> + The channel element is <a href="tribes/introduction.html">Tribes</a>, the group communication framework + used inside Tomcat. This element encapsulates everything that has to do with communication and membership logic. + <br>For more info, Please visit the <a href="config/cluster-channel.html">reference documentation</a> + </p> + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> + <Membership className="org.apache.catalina.tribes.membership.McastService" + address="228.0.0.4" + port="45564" + frequency="500" + dropTime="3000"/> + </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + <p> + Membership is done using multicasting. Please note that Tribes also supports static memberships using the + <code>StaticMembershipInterceptor</code> if you want to extend your membership to points beyond multicasting. + The address attribute is the multicast address used and the port is the multicast port. These two together + create the cluster separation. If you want a QA cluster and a production cluster, the easiest config is to + have the QA cluster be on a separate multicast address/port combination the the production cluster.<br> + The membership component broadcasts TCP adress/port of itselt to the other nodes so that communication between + nodes can be done over TCP. Please note that the address being broadcasted is the one of the + <code>Receiver.address</code> attribute. + <br>For more info, Please visit the <a href="config/cluster-membership.html">reference documentation</a> + </p> + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> + <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver" + address="auto" + port="5000" + selectorTimeout="100" + maxThreads="6"/> + </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + <p> + In tribes the logic of sending and receiving data has been broken into two functional components. The Receiver, as the name suggests + is responsible for receiving messages. Since the Tribes stack is thread less, (a popular improvement now adopted by other frameworks as well), + there is a thread pool in this component that has a maxThreads and minThreads setting.<br> + The address attribute is the host address that will be broadcasted by the membership component to the other nodes. + <br>For more info, Please visit the <a href="config/cluster-receiver.html">reference documentation</a> + </p> + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> + + <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter"> + <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/> + </Sender> + </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + <p> + The sender component, as the name indicates is responsible for sending messages to other nodes. + The sender has a shell component, the <code>ReplicationTransmitter</code> but the real stuff done is done in the + sub component, <code>Transport</code>. + Tribes support having a pool of senders, so that messages can be sent in parallel and if using the NIO sender, + you can send messages concurrently as well.<br> + Concurrently means one message to multiple senders at the same time and Parallel means multiple messages to multiple senders + at the same time. + <br>For more info, Please visit the <a href="config/cluster-sender.html">reference documentation</a> + </p> + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> + <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/> + <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/> + <Interceptor className="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor"/> + </Channel> + </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + <p> + Tribes uses a stack to send messages through. Each element in the stack is called an interceptor, and works much like the valves do + in the Tomcat servlet container. + Using interceptors, logic can be broken into more managable pieces of code. The interceptors configured above are:<br> + TcpFailureDetector - verifies crashed members through TCP, if multicast packets get dropped, this interceptor protects against false positives, + ie the node marked as crashed even though it still is alive and running.<br> + MessageDispatch15Interceptor - dispatches messages to a thread (thread pool) to send message asynchrously.<br> + ThroughputInterceptor - prints out simple stats on message traffic.<br> + Please note that the order of interceptors is important. the way they are defined in server.xml is the way they are represented in the + channel stack. Think of it as a linked list, with the head being the first most interceptor and the tail the last. + <br>For more info, Please visit the <a href="config/cluster-interceptor.html">reference documentation</a> + </p> + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> + <Valve className="org.apache.catalina.ha.tcp.ReplicationValve" + filter=".*\.gif;.*\.js;.*\.jpg;.*\.png;.*\.htm;.*\.html;.*\.css;.*\.txt;"/> + </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + <p> + The cluster uses valves to track requests to web applications, we've mentioned the ReplicationValve and the JvmRouteBinderValve above. + The <Cluster> element itself is not part of the pipeline in Tomcat, instead the cluster adds the valve to its parent container. + If the <Cluster> elements is configured in the <Engine> element, the valves get added to the engine and so on. + <br>For more info, Please visit the <a href="config/cluster-valve.html">reference documentation</a> + </p> + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> + <Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer" + tempDir="/tmp/war-temp/" + deployDir="/tmp/war-deploy/" + watchDir="/tmp/war-listen/" + watchEnabled="false"/> + </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + <p> + The default tomcat cluster supports farmed deployment, ie, the cluster can deploy and undeploy applications on the other nodes. + The state of this component is currently in flux but will be addressed soon. There was a change in the deployment algorithm + between Tomcat 5.0 and 5.5 and at that point, the logic of this component changed to where the deploy dir has to match the + webapps directory. + <br>For more info, Please visit the <a href="config/cluster-deployer.html">reference documentation</a> + </p> + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> + <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/> + </Cluster> + </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + <p> + Since the SimpleTcpCluster itself is a sender and receiver of the Channel object, components can register themselves as listeners to + the SimpleTcpCluster. The listener above <code>ClusterSessionListener</code> listens for DeltaManager replication messages + and applies the deltas to the manager that in turn applies it to the session. + <br>For more info, Please visit the <a href="config/cluster-listener.html">reference documentation</a> + </p> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Cluster Architecture"><!--()--></a><a name="Cluster_Architecture"><strong>Cluster Architecture</strong></a></font></td></tr><tr><td><blockquote> + +<p><b>Component Levels:</b> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> + Server + | + Service + | + Engine + | \ + | --- Cluster --* + | + Host + | + ------ + / \ + Cluster Context(1-N) + | \ + | -- Manager + | \ + | -- DeltaManager + | -- BackupManager + | + --------------------------- + | \ + Channel \ + ----------------------------- \ + | \ + Interceptor_1 .. \ + | \ + Interceptor_N \ + ----------------------------- \ + | | | \ + Receiver Sender Membership \ + -- Valve + | \ + | -- ReplicationValve + | -- JvmRouteBinderValve + | + -- LifecycleListener + | + -- ClusterListener + | \ + | -- ClusterSessionListener + | -- JvmRouteSessionIDBinderListener + | + -- Deployer + \ + -- FarmWarDeployer + + +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> +</p> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="How it Works"><!--()--></a><a name="How_it_Works"><strong>How it Works</strong></a></font></td></tr><tr><td><blockquote> +<p>To make it easy to understand how clustering works, We are gonna take you through a series of scenarios. + In the scenario we only plan to use two tomcat instances <code>TomcatA</code> and <code>TomcatB</code>. + We will cover the following sequence of events:</p> + +<ol> +<li><code>TomcatA</code> starts up</li> +<li><code>TomcatB</code> starts up (Wait that TomcatA start is complete)</li> +<li><code>TomcatA</code> receives a request, a session <code>S1</code> is created.</li> +<li><code>TomcatA</code> crashes</li> +<li><code>TomcatB</code> receives a request for session <code>S1</code></li> +<li><code>TomcatA</code> starts up</li> +<li><code>TomcatA</code> receives a request, invalidate is called on the session (<code>S1</code>)</li> +<li><code>TomcatB</code> receives a request, for a new session (<code>S2</code>)</li> +<li><code>TomcatA</code> The session <code>S2</code> expires due to inactivity.</li> +</ol> + +<p>Ok, now that we have a good sequence, we will take you through exactly what happens in the session repliction code</p> + +<ol> +<li><b><code>TomcatA</code> starts up</b> + <p> + Tomcat starts up using the standard start up sequence. When the Host object is created, a cluster object is associated with it. + When the contexts are parsed, if the distributable element is in place in web.xml + Tomcat asks the Cluster class (in this case <code>SimpleTcpCluster</code>) to create a manager + for the replicated context. So with clustering enabled, distributable set in web.xml + Tomcat will create a <code>DeltaManager</code> for that context instead of a <code>StandardManager</code>. + The cluster class will start up a membership service (multicast) and a replication service (tcp unicast). + More on the architecture further down in this document. + </p><p></p> +</li> +<li><b><code>TomcatB</code> starts up</b> + <p> + When TomcatB starts up, it follows the same sequence as TomcatA did with one exception. + The cluster is started and will establish a membership (TomcatA,TomcatB). + TomcatB will now request the session state from a server that already exists in the cluster, + in this case TomcatA. TomcatA responds to the request, and before TomcatB starts listening + for HTTP requests, the state has been transferred from TomcatA to TomcatB. + In case TomcatA doesn't respond, TomcatB will time out after 60 seconds, and issue a log + entry. The session state gets transferred for each web application that has distributable in + its web.xml. Note: To use session replication efficiently, all your tomcat instances should be + configured the same. + </p><p></p> +</li> +<li><B><code>TomcatA</code> receives a request, a session <code>S1</code> is created.</B> + <p> + The request coming in to TomcatA is treated exactly the same way as without session replication. + The action happens when the request is completed, the <code>ReplicationValve</code> will intercept + the request before the response is returned to the user. + At this point it finds that the session has been modified, and it uses TCP to replicata the + session to TomcatB. Once the serialized data has been handed off to the operating systems TCP logic, + the request returns to the user, back through the valve pipeline. + For each request the entire session is replicated, this allows code that modifies attributes + in the session without calling setAttribute or removeAttribute to be replicated. + a useDirtyFlag configuration parameter can be used to optimize the number of times + a session is replicated. + </p><p></p> + +</li> +<li><b><code>TomcatA</code> crashes</b> + <p> + When TomcatA crashes, TomcatB receives a notification that TomcatA has dropped out + of the cluster. TomcatB removes TomcatA from its membership list, and TomcatA will no longer + be notified of any changes that occurs in TomcatB. + The load balancer will redirect the requests from TomcatA to TomcatB and all the sessions + are current. + </p><p></p> +</li> +<li><b><code>TomcatB</code> receives a request for session <code>S1</code></b> + <p>Nothing exciting, TomcatB will process the request as any other request. + </p><p></p> +</li> +<li><b><code>TomcatA</code> starts up</b> + <p>Upon start up, before TomcatA starts taking new request and making itself + available to it will follow the start up sequence described above 1) 2). + It will join the cluster, contact TomcatB for the current state of all the sessions. + And once it receives the session state, it finishes loading and opens its HTTP/mod_jk ports. + So no requests will make it to TomcatA until it has received the session state from TomcatB. + </p><p></p> +</li> +<li><b><code>TomcatA</code> receives a request, invalidate is called on the session (<code>S1</code>)</b> + <p>The invalidate is call is intercepted, and the session is queued with invalidated sessions. + When the request is complete, instead of sending out the session that has changed, it sends out + an "expire" message to TomcatB and TomcatB will invalidate the session as well. + </p><p></p> + +</li> +<li><b><code>TomcatB</code> receives a request, for a new session (<code>S2</code>)</b> + <p>Same scenario as in step 3) + </p><p></p> + + +</li> +<li><code>TomcatA</code> The session <code>S2</code> expires due to inactivity. + <p>The invalidate is call is intercepted the same was as when a session is invalidated by the user, + and the session is queued with invalidated sessions. + At this point, the invalidet session will not be replicated across until + another request comes through the system and checks the invalid queue. + </p><p></p> +</li> +</ol> + +<p>Phuuuhh! :)</p> + +<p><b>Membership</b> + Clustering membership is established using very simple multicast pings. + Each Tomcat instance will periodically send out a multicast ping, + in the ping message the instance will broad cast its IP and TCP listen port + for replication. + If an instance has not received such a ping within a given timeframe, the + member is considered dead. Very simple, and very effective! + Of course, you need to enable multicasting on your system. +</p> + +<p><b>TCP Replication</b> + Once a multicast ping has been received, the member is added to the cluster + Upon the next replication request, the sending instance will use the host and + port info and establish a TCP socket. Using this socket it sends over the serialized data. + The reason I choose TCP sockets is because it has built in flow control and guaranteed delivery. + So I know, when I send some data, it will make it there :) +</p> + +<p><b>Distributed locking and pages using frames</b> + Tomcat does not keep session instances in sync across the cluster. + The implementation of such logic would be to much overhead and cause all + kinds of problems. If your client accesses the same session + simultanously using multiple requests, then the last request + will override the other sessions in the cluster. +</p> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="FAQ"><strong>FAQ</strong></a></font></td></tr><tr><td><blockquote> +<p>Please see <a href="http://wiki.apache.org/tomcat/FAQ/Clustering";>the clustering section of the FAQ</a>.</p> +</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em> + Copyright © 1999-2010, Apache Software Foundation + </em></font></div></td></tr></table></body></html> \ No newline at end of file
