[jboss-cvs] JBossAS SVN: r59894 - in branches/Branch_4_2/tomcat/docs: html and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Sun Jan 21 15:12:52 EST 2007
Author: dimitris at jboss.org
Date: 2007-01-21 15:12:52 -0500 (Sun, 21 Jan 2007)
New Revision: 59894
Added:
branches/Branch_4_2/tomcat/docs/html/jboss-web-clustering.html
branches/Branch_4_2/tomcat/docs/jboss-web-clustering.xml
Removed:
branches/Branch_4_2/tomcat/docs/html/tc5-clustering.html
branches/Branch_4_2/tomcat/docs/tc5-clustering.xml
Log:
tomcat -> JBossWeb
Copied: branches/Branch_4_2/tomcat/docs/html/jboss-web-clustering.html (from rev 59885, branches/Branch_4_2/tomcat/docs/html/tc5-clustering.html)
===================================================================
--- branches/Branch_4_2/tomcat/docs/html/jboss-web-clustering.html (rev 0)
+++ branches/Branch_4_2/tomcat/docs/html/jboss-web-clustering.html 2007-01-21 20:12:52 UTC (rev 59894)
@@ -0,0 +1,56 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>Tomcat 5 Clustering In JBoss Release 3.2.6</title><link rel="stylesheet" href="html.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.62.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="d0e1"></a>Tomcat 5 Clustering In JBoss Release 3.2.6</h1></div><div><div class="author"><h3 class="author"><span class="firstname">Ben</span> <span class="surname">Wang</span></h3></div></div><div><p class="pubdate">August, 2004</p></div></div><div></div><hr></div><div class="toc"><dl><dt><span class="section"><a href="#d0e14">1. Introduction</a></span></dt><dt><span class="section"><a href="#d0e23">2. Software Design</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e28">2.1. Class Responsibility</a></span></dt><dt><span class="section"><a href="#d0e105">2.2. Deployment Process</a></span></dt></dl></dd><dt><s!
pan class="section"><a href="#d0e128">3. Features</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e133">3.1. Tomcat level aspect</a></span></dt><dt><span class="section"><a href="#d0e225">3.2. JBossCache level aspect</a></span></dt><dt><span class="section"><a href="#d0e255">3.3. Deprecated</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e284">4. What's New?</a></span></dt><dt><span class="section"><a href="#d0e305">5. Test Case</a></span></dt><dt><span class="section"><a href="#d0e313">6. Sample Usage</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e14"></a>1. Introduction</h2></div></div><div></div></div><p>Nowadays http web clustering (or failover) typically employs either a hardware or software front-end load balancer to distribute the load (with capability of session affinity). And the session state replication is then delegated to the web contain!
er. Naturally, JBoss also has a session replication layer for Tomcat s
ince release 3.x.</p><p>In JBoss release 3.2.6, we have re-factored the Tomcat 5 http session replication framework using JBossCache (http://www.jboss.org/products/jbosscache) as the underlying in-memory replication store. JBossCache is an open-source replicated, transactional, and fine-grained cache system. Using JBossCache as the framework for session replication offers separation of replication layer concerns (e.g., replication mode, lock behavior, partitioning, persistence, and transaction) from the Tomcat session handling logics (e.g., sticky session, replication granularity, and trigger). The end result is a reduced development effort in Tomcat application layer and more robust behavior in the overall system.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e23"></a>2. Software Design</h2></div></div><div></div></div><p>This section describes briefly the high level design and the web applicat!
ion deployment process pertaining to the session replication.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e28"></a>2.1. Class Responsibility</h3></div></div><div></div></div><p>The following is a class diagram focusing on the http session replication using JBossCache as the distributed store service under Tomcat5. </p><div class="figure"><a name="d0e33"></a><p class="title"><b>Figure 1. Tomcat5 http session replication class diagram</b></p><div class="mediaobject"><img src="resources/HttpSessionRepl.gif" alt="Tomcat5 http session replication class diagram"></div></div><p>In addition to the JBossCacheService class that provides replication service, there are three main interfaces: </p><div class="itemizedlist"><ul type="disc"><li><p><tt class="literal">org.jboss.web.tomcat.service.session.SnapshotManger.</tt> Interface that defines the API to check for necessary session replication. Note that it has a referen!
ce to JBossManager to perform session replication. Two concrete implem
entation classes are: </p><div class="itemizedlist"><ul type="circle"><li><tt class="literal">org.jboss.web.tomcat.service.session.InstantSnapshotManager</tt> . Use of this snapshot manager will check for dirty session after every single http request (through <tt class="literal">org.jboss.web.tomcat.service.session.ClusteredSessionValve</tt> ). If a session is dirty, it will then be replicated. </li><li><tt class="literal">org.jboss.web.tomcat.service.session.IntervalSnapshotManager</tt> . Use of this snapshot manager will check for dirty session(s) only periodically (with a configurable timer interval). The dirty session(s) will be replicated when the timer kicks in. </li></ul></div></li><li><p><tt class="literal">org.apache.catalina.Manager.</tt> This is a Tomcat catalina interface that handles the session management. The JBossCacheManager is the implemented class that also manages both in-memory session and the sessions located in the distributed store.</p><p>The reason t!
hat we need to use the in-memory session instance is because of the web class loader can be different from the system one. As a result, we will need to keep a "serialized" version of the session data in the distributed store (done via <tt class="literal">org.jboss.invocation.MarshalledValue</tt>) so that the class loading scope will be correct. Otherwise, it will be simply too expensive to retrieve and de-serialize every time from the underneath store.</p><p>This manager is also called periodically by catalina to process expired session(s) (or session timeout). When a session is timed-out, it will be deleted from the store. However, the operation is local only. That is, the delete operation will not replicate to other cluster nodes since the other nodes will have similar expiring process in place already. Therefore, the session will be expired simultaneously from the whole cluster view.</p></li><li><p><tt class="literal">org.apache.catalina.Session.</tt> This is a catalina !
interface that manages the session attributes and track the session li
fe time itself. We have two different concrete implementation classes in this release: </p><div class="itemizedlist"><ul type="circle"><li><tt class="literal">org.jboss.web.tomcat.service.session.SessionBasedClusteredSession.</tt> This corresponds to the setting in <tt class="literal">jboss-web.xml</tt> of <tt class="literal">replication-granulairty</tt> set to <tt class="literal">session.</tt> That is, whenever a session attribute is changed, it will replicate the whole session, regardless. </li><li><tt class="literal">org.jboss.web.tomcat.service.session.AttributeBasedClusteredSession.</tt> This corresponds to the setting in <tt class="literal">jboss-web.xml</tt> of <tt class="literal">replication-granulairty</tt> set to <tt class="literal">attribute.</tt> That is, whenever a session attribute is changed, it will replicate only the modified attribute. Note that this option which is finer grain in nature has the potential for session replication performance boost, especiall!
y when the session is carrying a large amount of data. </li></ul></div></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e105"></a>2.2. Deployment Process</h3></div></div><div></div></div><p>When a user deploys (or hot-deploys) a web application, the JBoss <tt class="literal">org.jboss.web.tomcat.service.TomcatDeployer</tt> will first determine if the web application is declared <tt class="literal">distributable.</tt> If it is, JBoss will instantiate <tt class="literal">JBossCacheManager</tt>, create <tt class="literal">SnapshotManager</tt> and then add a <tt class="literal">ClusteredSessionValve</tt> to the Tomcat interceptor chain. As a result, every single http request will be intercepted by this valve to process the necessary session replication (through <tt class="literal">SnapshotManager</tt>).</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="cl!
ear: both"><a name="d0e128"></a>3. Features</h2></div></div><div>
</div></div><p>Here are the features provided with this release. For clarity, we will divide them into Tomcat and JBossCache level aspects, meaning the configuration will be done either from JBossCache or the TC5 layer.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e133"></a>3.1. Tomcat level aspect</h3></div></div><div></div></div><p>In <tt class="literal">jbossweb-tomcat5.0/META-INF/jboss-service.xml</tt> , you can configure the followings: </p><div class="itemizedlist"><ul type="disc"><li><tt class="literal">SnapshotMode</tt><div class="itemizedlist"><ul type="circle"><li><tt class="literal">instant</tt> Session replication is performed during each HTTP request. But whether it is instantaneously or not also depends on the replication mode (synchronous or asynchronous) in JBossCache setting. </li><li><tt class="literal">Interval</tt> Replicated during a specified time interval. There is an accompanying flag, <tt class=!
"literal">SnapshotInterval</tt>, that indicates the snapshot interval in milliseconds. The <tt class="literal">IntervalSnapshotManager</tt> will perform session dirty check every <tt class="literal">SnapshotInterval.</tt> This manager keeps track of the dirty session(s) internally.</li></ul></div></li><li><p><tt class="literal">UseJK</tt> A flag indicating whether to use the Apache mod_jk(2) for the front end software load balancing with sticky session combined with JvmRoute. If set to true, it will insert a JvmRouteFilter to intercept every request during deployment and replace the JvmRoute if it detects a failover in runtime. In addition, you will need to set the JvmRoute inside Tomcat, e.g., <tt class="literal"><Engine name="jboss.web" jmvRoute="Node1" defaultHost="localhost"></tt> in <tt class="literal">jbossweb-tomcat4.0/server.xml</tt>.</p></li></ul></div><p>Note that the above configuration parameters are applied to per Tomcat instance. Change of the parameter !
will cause Tomcat to re-deploy.</p><p>In each web application, you can
also specify in <tt class="literal">jboss-web.xml</tt> to customize the clustering behavior. Specifically, there is an element called <tt class="literal">replication-config</tt> that contains two sub-elements so far: </p><div class="itemizedlist"><ul type="disc"><li><tt class="literal">replication-trigger</tt> It determines what triggers a session replication (or when is a session is considered dirty). It has 4 options: <div class="itemizedlist"><ul type="circle"><li><p><tt class="literal">ACCESS</tt> Indicating if accessing the session is considered dirty. If set, it is considered dirty with pure access and thus will cause replication. Note that a session is "accessed" during each http request regardless. It will update the access time stamp in the session instance as well. Since the time stamp may not be updated in other clustering nodes (because of no replication), this may cause session in other nodes to expire before the active node if http request does not retrieve or!
modify any session attributes. </p><p>When this option is set, the session timestamps will be synchronized throughout the cluster nodes. Note that use of this option can have a significant performance impact so you will need to use with caution.</p></li><li><tt class="literal">SET_AND_GET</tt> Every session get and set attributes are considered dirty. This option also can have significant performance impact as well.</li><li><tt class="literal">SET_AND_NON_PRIMITIVE_GET</tt> Session get and non-primitive get are considered dirty. For example, the http session request may retrieve a non-primitive object instance from the attribute and then modify the instance. If we don't specify that non-primitive get is considered dirty, then the modification will not be replication properly. This is the default value. </li><li><tt class="literal">SET</tt> Only set attribute operation is considered dirty. If you are certain that only set attribute operation is necessary for replication, th!
is option will be most optimized in term of performance.</li></ul></di
v></li><li><tt class="literal">replication-granularity</tt><div class="itemizedlist"><ul type="circle"><li><tt class="literal">session</tt> Replication is per session instance. As long as it is considered modified when the snapshot manager is called, the whole session object will be serialized. </li><li><tt class="literal">attribute</tt> Replication is only for the dirty attributes plus some session data, like, lastAccessTime. For session that carries large amount of data, this option can increase replication performance. </li><li><tt class="literal">field</tt> Will need aop (aspect-oriented programming) and be available in 4.0.4. User can have control of even finer grain replication through its own object graph. For example, if one stores another map object into the session as an attribute, we can track the dirty field down to the value object inside the map. </li></ul></div></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="tit!
le"><a name="d0e225"></a>3.2. JBossCache level aspect</h3></div></div><div></div></div><p>The main configuration file is <tt class="literal">jboss-web-cluster-service.xml</tt> of which is basically a minimum version of JBossCache configuration xml file (more details later). </p><div class="itemizedlist"><ul type="disc"><li><tt class="literal">CacheMode</tt><div class="itemizedlist"><ul type="circle"><li><tt class="literal">REPL_SYNC</tt> Replication is synchronous and call is blocking until replication succeeds or fails. That is, replication will be completed before the http request returns. </li><li><tt class="literal">REPLY_ASYNC</tt> Replication is asynchronous and call is non-blocking. Does not wait for results for the http request to return. When session state replication is allowed to have some latency, this is useful and will have a much better performance throughput. </li></ul></div></li></ul></div><p>In the future release, we will also add the following featur!
es from JBossCache. </p><div class="itemizedlist"><ul type="disc"><li>
(sub)-Partitioning. This feature will partition the cluster into different sub-partitions such that replication only happens in the sub-partition nodes. With this feature, the session replication cluster can then be easily scaled. </li><li> Persistence. Persist the session data to the backed store. Currently, clustered session does not support any persistency. </li><li> Eviction policy and cache data overflow memory size or time-based eviction policy with overflow to back end persistent store. This is useful for users who have long running sessions that needs to support passivation. </li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e255"></a>3.3. Deprecated</h3></div></div><div></div></div><p>The following features have been deprecated in the new release: </p><div class="itemizedlist"><ul type="disc"><li><p><tt class="literal">replication-type</tt> in <tt class="literal">jboss-web.xml.</tt> User should di!
rectly configure the replication type from <tt class="literal">jboss-web-cluster-service.xml</tt> with the element <tt class="literal"><tt class="literal">CacheMode</tt></tt>.</p></li><li><p><tt class="literal">UseLocalCache</tt> in <tt class="literal">jbossweb-tomcat5.0/META-INF/jboss-service.xml.</tt> Local in-vm session is used by default now.</p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e284"></a>4. What's New?</h2></div></div><div></div></div><p>JBossCache can be configured through a xml configuration and deployed under JBoss3.2.6 as a MBean service. Since JBossCache is used not only for clustering but also for <tt class="literal">SSO</tt> (single sign on) replication as well, we have introduced a JBossCache clustering MBean service for everyone to share (such as <tt class="literal">SSO</tt> replication). The xml configuration file will be called <tt class="literal">!
jboss-web-cluster-service.xml</tt>. Once the file is deployed, a MBean
called <tt class="literal">TomcatClusteringCache</tt> will be created.</p><p>In the file, there are JBossCache configuration parameters but customized for the JBossWeb clustering. Here is a snippet of the xml:</p><pre class="programlisting"><server>
+<mbean code="org.jboss.cache.TreeCache" name="jboss.cache:service=TomcatClusteringCache">
+ <depends>jboss:service=Naming</depends>
+ <depends>jboss:service=TransactionManager</depends>
+
+<!--
+ Configure the TransactionManager. Default should be JBossTransactionManager.
+-->
+ <attribute name="TransactionManagerLookupClass">org.jboss.cache.JBossTransactionManagerLookup</attribute>
+
+<!--
+ Valid modes are LOCAL
+ REPL_ASYNC
+ REPL_SYNC
+-->
+ <attribute name="CacheMode">REPL_ASYNC</attribute>
+
+<!--
+ Name of cluster. Needs to be the same for all clusters, in order
+ to find each other
+-->
+ <attribute name="ClusterName">TOMCAT-Cluster</attribute>
+
+<!--
+ JGroups protocol stack properties. Can also be a URL,
+ e.g. file:/home/bela/default.xml
+ <attribute name="ClusterProperties"></attribute>
+-->
+<attribute name="ClusterConfig">
+ <config>
+ <UDP mcast_addr="228.1.2.5" mcast_port="45566" ip_ttl="64" ip_mcast="true"
+ mcast_send_buf_size="150000" mcast_recv_buf_size="80000" ucast_send_buf_size="150000"
+ ucast_recv_buf_size="80000" loopback="false" />
+ ... more config params here ...
+ </config>
+</attribute>
+
+</mbean>
+</server>
+</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e305"></a>5. Test Case</h2></div></div><div></div></div><p>All http session clustering test cases are located under <tt class="literal">JBoss-3.2/testsuite/src/main/org/jboss/test/cluster/apache-tomcat</tt> directory.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e313"></a>6. Sample Usage</h2></div></div><div></div></div><p>In this section, we describe how to setup a sample web application for http session replication. User should refer to other documentation on how to setup a front end load balancer (e.g., Apache mod_jk(2)).</p><p>To run a web application session replication under the new JBossWeb clustering, you will need to set the application to be distributable as usual. For example, in <tt class="literal">web.xml</tt> (under the web app <tt class="literal">WEB-!
INF</tt> directory), </p><pre class="programlisting"><web-app>
+ <distributable/>
+ ...
+</web-app>
+</pre><p>Next, you can create an optional <tt class="literal">jboss-web.xml</tt> (also under <tt class="literal">WEB-INF</tt> directory) that has the following options: </p><pre class="programlisting"><jboss-web>
+ <replication-config>
+ <replication-trigger>SET_AND_NON_PRIMITIVE_GET</replication-trigger>
+ <replication-granularity>SESSION</replication-granularity>
+ </replication-config>
+</jboss-web>
+</pre><p>In addition, you will need to start jboss from <tt class="literal">all</tt> configuration directory. Under the new <tt class="literal">all</tt> configuration, it includes the JBossCache library and also the <tt class="literal">jboss-web-cluster-service.xml</tt>file to deploy the cache as a specific JBossWeb clustering MBean service.</p><p>Finally, before you start JBoss, you can edit <tt class="literal">jboss-service.xml</tt> under <tt class="literal">jbossweb-tomcat5.0/META-INF</tt> directory for the following: </p><pre class="programlisting"><jboss-service>
+ <attribute name="SnapshotMode">instant</attribute>
+ <attribute name="UseJK">false</attribute>
+</jboss-service>
+</pre><p>You are now ready to use http session replication!</p></div></div></body></html>
\ No newline at end of file
Deleted: branches/Branch_4_2/tomcat/docs/html/tc5-clustering.html
===================================================================
--- branches/Branch_4_2/tomcat/docs/html/tc5-clustering.html 2007-01-21 20:07:36 UTC (rev 59893)
+++ branches/Branch_4_2/tomcat/docs/html/tc5-clustering.html 2007-01-21 20:12:52 UTC (rev 59894)
@@ -1,56 +0,0 @@
-<html><head>
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
- <title>Tomcat 5 Clustering In JBoss Release 3.2.6</title><link rel="stylesheet" href="html.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.62.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="d0e1"></a>Tomcat 5 Clustering In JBoss Release 3.2.6</h1></div><div><div class="author"><h3 class="author"><span class="firstname">Ben</span> <span class="surname">Wang</span></h3></div></div><div><p class="pubdate">August, 2004</p></div></div><div></div><hr></div><div class="toc"><dl><dt><span class="section"><a href="#d0e14">1. Introduction</a></span></dt><dt><span class="section"><a href="#d0e23">2. Software Design</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e28">2.1. Class Responsibility</a></span></dt><dt><span class="section"><a href="#d0e105">2.2. Deployment Process</a></span></dt></dl></dd><dt><s!
pan class="section"><a href="#d0e128">3. Features</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e133">3.1. Tomcat level aspect</a></span></dt><dt><span class="section"><a href="#d0e225">3.2. JBossCache level aspect</a></span></dt><dt><span class="section"><a href="#d0e255">3.3. Deprecated</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e284">4. What's New?</a></span></dt><dt><span class="section"><a href="#d0e305">5. Test Case</a></span></dt><dt><span class="section"><a href="#d0e313">6. Sample Usage</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e14"></a>1. Introduction</h2></div></div><div></div></div><p>Nowadays http web clustering (or failover) typically employs either a hardware or software front-end load balancer to distribute the load (with capability of session affinity). And the session state replication is then delegated to the web contain!
er. Naturally, JBoss also has a session replication layer for Tomcat s
ince release 3.x.</p><p>In JBoss release 3.2.6, we have re-factored the Tomcat 5 http session replication framework using JBossCache (http://www.jboss.org/products/jbosscache) as the underlying in-memory replication store. JBossCache is an open-source replicated, transactional, and fine-grained cache system. Using JBossCache as the framework for session replication offers separation of replication layer concerns (e.g., replication mode, lock behavior, partitioning, persistence, and transaction) from the Tomcat session handling logics (e.g., sticky session, replication granularity, and trigger). The end result is a reduced development effort in Tomcat application layer and more robust behavior in the overall system.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e23"></a>2. Software Design</h2></div></div><div></div></div><p>This section describes briefly the high level design and the web applicat!
ion deployment process pertaining to the session replication.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e28"></a>2.1. Class Responsibility</h3></div></div><div></div></div><p>The following is a class diagram focusing on the http session replication using JBossCache as the distributed store service under Tomcat5. </p><div class="figure"><a name="d0e33"></a><p class="title"><b>Figure 1. Tomcat5 http session replication class diagram</b></p><div class="mediaobject"><img src="resources/HttpSessionRepl.gif" alt="Tomcat5 http session replication class diagram"></div></div><p>In addition to the JBossCacheService class that provides replication service, there are three main interfaces: </p><div class="itemizedlist"><ul type="disc"><li><p><tt class="literal">org.jboss.web.tomcat.service.session.SnapshotManger.</tt> Interface that defines the API to check for necessary session replication. Note that it has a referen!
ce to JBossManager to perform session replication. Two concrete implem
entation classes are: </p><div class="itemizedlist"><ul type="circle"><li><tt class="literal">org.jboss.web.tomcat.service.session.InstantSnapshotManager</tt> . Use of this snapshot manager will check for dirty session after every single http request (through <tt class="literal">org.jboss.web.tomcat.service.session.ClusteredSessionValve</tt> ). If a session is dirty, it will then be replicated. </li><li><tt class="literal">org.jboss.web.tomcat.service.session.IntervalSnapshotManager</tt> . Use of this snapshot manager will check for dirty session(s) only periodically (with a configurable timer interval). The dirty session(s) will be replicated when the timer kicks in. </li></ul></div></li><li><p><tt class="literal">org.apache.catalina.Manager.</tt> This is a Tomcat catalina interface that handles the session management. The JBossCacheManager is the implemented class that also manages both in-memory session and the sessions located in the distributed store.</p><p>The reason t!
hat we need to use the in-memory session instance is because of the web class loader can be different from the system one. As a result, we will need to keep a "serialized" version of the session data in the distributed store (done via <tt class="literal">org.jboss.invocation.MarshalledValue</tt>) so that the class loading scope will be correct. Otherwise, it will be simply too expensive to retrieve and de-serialize every time from the underneath store.</p><p>This manager is also called periodically by catalina to process expired session(s) (or session timeout). When a session is timed-out, it will be deleted from the store. However, the operation is local only. That is, the delete operation will not replicate to other cluster nodes since the other nodes will have similar expiring process in place already. Therefore, the session will be expired simultaneously from the whole cluster view.</p></li><li><p><tt class="literal">org.apache.catalina.Session.</tt> This is a catalina !
interface that manages the session attributes and track the session li
fe time itself. We have two different concrete implementation classes in this release: </p><div class="itemizedlist"><ul type="circle"><li><tt class="literal">org.jboss.web.tomcat.service.session.SessionBasedClusteredSession.</tt> This corresponds to the setting in <tt class="literal">jboss-web.xml</tt> of <tt class="literal">replication-granulairty</tt> set to <tt class="literal">session.</tt> That is, whenever a session attribute is changed, it will replicate the whole session, regardless. </li><li><tt class="literal">org.jboss.web.tomcat.service.session.AttributeBasedClusteredSession.</tt> This corresponds to the setting in <tt class="literal">jboss-web.xml</tt> of <tt class="literal">replication-granulairty</tt> set to <tt class="literal">attribute.</tt> That is, whenever a session attribute is changed, it will replicate only the modified attribute. Note that this option which is finer grain in nature has the potential for session replication performance boost, especiall!
y when the session is carrying a large amount of data. </li></ul></div></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e105"></a>2.2. Deployment Process</h3></div></div><div></div></div><p>When a user deploys (or hot-deploys) a web application, the JBoss <tt class="literal">org.jboss.web.tomcat.service.TomcatDeployer</tt> will first determine if the web application is declared <tt class="literal">distributable.</tt> If it is, JBoss will instantiate <tt class="literal">JBossCacheManager</tt>, create <tt class="literal">SnapshotManager</tt> and then add a <tt class="literal">ClusteredSessionValve</tt> to the Tomcat interceptor chain. As a result, every single http request will be intercepted by this valve to process the necessary session replication (through <tt class="literal">SnapshotManager</tt>).</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="cl!
ear: both"><a name="d0e128"></a>3. Features</h2></div></div><div>
</div></div><p>Here are the features provided with this release. For clarity, we will divide them into Tomcat and JBossCache level aspects, meaning the configuration will be done either from JBossCache or the TC5 layer.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e133"></a>3.1. Tomcat level aspect</h3></div></div><div></div></div><p>In <tt class="literal">jbossweb-tomcat5.0/META-INF/jboss-service.xml</tt> , you can configure the followings: </p><div class="itemizedlist"><ul type="disc"><li><tt class="literal">SnapshotMode</tt><div class="itemizedlist"><ul type="circle"><li><tt class="literal">instant</tt> Session replication is performed during each HTTP request. But whether it is instantaneously or not also depends on the replication mode (synchronous or asynchronous) in JBossCache setting. </li><li><tt class="literal">Interval</tt> Replicated during a specified time interval. There is an accompanying flag, <tt class=!
"literal">SnapshotInterval</tt>, that indicates the snapshot interval in milliseconds. The <tt class="literal">IntervalSnapshotManager</tt> will perform session dirty check every <tt class="literal">SnapshotInterval.</tt> This manager keeps track of the dirty session(s) internally.</li></ul></div></li><li><p><tt class="literal">UseJK</tt> A flag indicating whether to use the Apache mod_jk(2) for the front end software load balancing with sticky session combined with JvmRoute. If set to true, it will insert a JvmRouteFilter to intercept every request during deployment and replace the JvmRoute if it detects a failover in runtime. In addition, you will need to set the JvmRoute inside Tomcat, e.g., <tt class="literal"><Engine name="jboss.web" jmvRoute="Node1" defaultHost="localhost"></tt> in <tt class="literal">jbossweb-tomcat4.0/server.xml</tt>.</p></li></ul></div><p>Note that the above configuration parameters are applied to per Tomcat instance. Change of the parameter !
will cause Tomcat to re-deploy.</p><p>In each web application, you can
also specify in <tt class="literal">jboss-web.xml</tt> to customize the clustering behavior. Specifically, there is an element called <tt class="literal">replication-config</tt> that contains two sub-elements so far: </p><div class="itemizedlist"><ul type="disc"><li><tt class="literal">replication-trigger</tt> It determines what triggers a session replication (or when is a session is considered dirty). It has 4 options: <div class="itemizedlist"><ul type="circle"><li><p><tt class="literal">ACCESS</tt> Indicating if accessing the session is considered dirty. If set, it is considered dirty with pure access and thus will cause replication. Note that a session is "accessed" during each http request regardless. It will update the access time stamp in the session instance as well. Since the time stamp may not be updated in other clustering nodes (because of no replication), this may cause session in other nodes to expire before the active node if http request does not retrieve or!
modify any session attributes. </p><p>When this option is set, the session timestamps will be synchronized throughout the cluster nodes. Note that use of this option can have a significant performance impact so you will need to use with caution.</p></li><li><tt class="literal">SET_AND_GET</tt> Every session get and set attributes are considered dirty. This option also can have significant performance impact as well.</li><li><tt class="literal">SET_AND_NON_PRIMITIVE_GET</tt> Session get and non-primitive get are considered dirty. For example, the http session request may retrieve a non-primitive object instance from the attribute and then modify the instance. If we don't specify that non-primitive get is considered dirty, then the modification will not be replication properly. This is the default value. </li><li><tt class="literal">SET</tt> Only set attribute operation is considered dirty. If you are certain that only set attribute operation is necessary for replication, th!
is option will be most optimized in term of performance.</li></ul></di
v></li><li><tt class="literal">replication-granularity</tt><div class="itemizedlist"><ul type="circle"><li><tt class="literal">session</tt> Replication is per session instance. As long as it is considered modified when the snapshot manager is called, the whole session object will be serialized. </li><li><tt class="literal">attribute</tt> Replication is only for the dirty attributes plus some session data, like, lastAccessTime. For session that carries large amount of data, this option can increase replication performance. </li><li><tt class="literal">field</tt> Will need aop (aspect-oriented programming) and be available in 4.0.4. User can have control of even finer grain replication through its own object graph. For example, if one stores another map object into the session as an attribute, we can track the dirty field down to the value object inside the map. </li></ul></div></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="tit!
le"><a name="d0e225"></a>3.2. JBossCache level aspect</h3></div></div><div></div></div><p>The main configuration file is <tt class="literal">tc5-cluster-service.xml</tt> of which is basically a minimum version of JBossCache configuration xml file (more details later). </p><div class="itemizedlist"><ul type="disc"><li><tt class="literal">CacheMode</tt><div class="itemizedlist"><ul type="circle"><li><tt class="literal">REPL_SYNC</tt> Replication is synchronous and call is blocking until replication succeeds or fails. That is, replication will be completed before the http request returns. </li><li><tt class="literal">REPLY_ASYNC</tt> Replication is asynchronous and call is non-blocking. Does not wait for results for the http request to return. When session state replication is allowed to have some latency, this is useful and will have a much better performance throughput. </li></ul></div></li></ul></div><p>In the future release, we will also add the following features fro!
m JBossCache. </p><div class="itemizedlist"><ul type="disc"><li> (sub)
-Partitioning. This feature will partition the cluster into different sub-partitions such that replication only happens in the sub-partition nodes. With this feature, the session replication cluster can then be easily scaled. </li><li> Persistence. Persist the session data to the backed store. Currently, clustered session does not support any persistency. </li><li> Eviction policy and cache data overflow memory size or time-based eviction policy with overflow to back end persistent store. This is useful for users who have long running sessions that needs to support passivation. </li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e255"></a>3.3. Deprecated</h3></div></div><div></div></div><p>The following features have been deprecated in the new release: </p><div class="itemizedlist"><ul type="disc"><li><p><tt class="literal">replication-type</tt> in <tt class="literal">jboss-web.xml.</tt> User should directly!
configure the replication type from <tt class="literal">tc5-cluster-service.xml</tt> with the element <tt class="literal"><tt class="literal">CacheMode</tt></tt>.</p></li><li><p><tt class="literal">UseLocalCache</tt> in <tt class="literal">jbossweb-tomcat5.0/META-INF/jboss-service.xml.</tt> Local in-vm session is used by default now.</p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e284"></a>4. What's New?</h2></div></div><div></div></div><p>JBossCache can be configured through a xml configuration and deployed under JBoss3.2.6 as a MBean service. Since JBossCache is used not only for clustering but also for <tt class="literal">SSO</tt> (single sign on) replication as well, we have introduced a JBossCache tc5 clustering MBean service for everyone to share (such as <tt class="literal">SSO</tt> replication). The xml configuration file will be called <tt class="literal">tc5-clus!
ter-service.xml</tt>. Once the file is deployed, a MBean called <tt cl
ass="literal">TomcatClusteringCache</tt> will be created.</p><p>In the file, there are JBossCache configuration parameters but customized for the tc5 clustering. Here is a snippet of the xml:</p><pre class="programlisting"><server>
-<mbean code="org.jboss.cache.TreeCache" name="jboss.cache:service=TomcatClusteringCache">
- <depends>jboss:service=Naming</depends>
- <depends>jboss:service=TransactionManager</depends>
-
-<!--
- Configure the TransactionManager. Default should be JBossTransactionManager.
--->
- <attribute name="TransactionManagerLookupClass">org.jboss.cache.JBossTransactionManagerLookup</attribute>
-
-<!--
- Valid modes are LOCAL
- REPL_ASYNC
- REPL_SYNC
--->
- <attribute name="CacheMode">REPL_ASYNC</attribute>
-
-<!--
- Name of cluster. Needs to be the same for all clusters, in order
- to find each other
--->
- <attribute name="ClusterName">TOMCAT-Cluster</attribute>
-
-<!--
- JGroups protocol stack properties. Can also be a URL,
- e.g. file:/home/bela/default.xml
- <attribute name="ClusterProperties"></attribute>
--->
-<attribute name="ClusterConfig">
- <config>
- <UDP mcast_addr="228.1.2.5" mcast_port="45566" ip_ttl="64" ip_mcast="true"
- mcast_send_buf_size="150000" mcast_recv_buf_size="80000" ucast_send_buf_size="150000"
- ucast_recv_buf_size="80000" loopback="false" />
- ... more config params here ...
- </config>
-</attribute>
-
-</mbean>
-</server>
-</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e305"></a>5. Test Case</h2></div></div><div></div></div><p>All http session clustering test cases are located under <tt class="literal">JBoss-3.2/testsuite/src/main/org/jboss/test/cluster/apache-tomcat</tt> directory.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e313"></a>6. Sample Usage</h2></div></div><div></div></div><p>In this section, we describe how to setup a sample web application for http session replication. User should refer to other documentation on how to setup a front end load balancer (e.g., Apache mod_jk(2)).</p><p>To run a web application session replication under the new tc5 clustering, you will need to set the application to be distributable as usual. For example, in <tt class="literal">web.xml</tt> (under the web app <tt class="literal">WEB-INF</!
tt> directory), </p><pre class="programlisting"><web-app>
- <distributable/>
- ...
-</web-app>
-</pre><p>Next, you can create an optional <tt class="literal">jboss-web.xml</tt> (also under <tt class="literal">WEB-INF</tt> directory) that has the following options: </p><pre class="programlisting"><jboss-web>
- <replication-config>
- <replication-trigger>SET_AND_NON_PRIMITIVE_GET</replication-trigger>
- <replication-granularity>SESSION</replication-granularity>
- </replication-config>
-</jboss-web>
-</pre><p>In addition, you will need to start jboss from <tt class="literal">all</tt> configuration directory. Under the new <tt class="literal">all</tt> configuration, it includes the JBossCache library and also the <tt class="literal">tc5-cluster-service.xml</tt>file to deploy the cache as a specific tc5 clustering MBean service.</p><p>Finally, before you start JBoss, you can edit <tt class="literal">jboss-service.xml</tt> under <tt class="literal">jbossweb-tomcat5.0/META-INF</tt> directory for the following: </p><pre class="programlisting"><jboss-service>
- <attribute name="SnapshotMode">instant</attribute>
- <attribute name="UseJK">false</attribute>
-</jboss-service>
-</pre><p>You are now ready to use http session replication!</p></div></div></body></html>
\ No newline at end of file
Copied: branches/Branch_4_2/tomcat/docs/jboss-web-clustering.xml (from rev 59885, branches/Branch_4_2/tomcat/docs/tc5-clustering.xml)
===================================================================
--- branches/Branch_4_2/tomcat/docs/jboss-web-clustering.xml (rev 0)
+++ branches/Branch_4_2/tomcat/docs/jboss-web-clustering.xml 2007-01-21 20:12:52 UTC (rev 59894)
@@ -0,0 +1,463 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" [
+<!ENTITY JBossCache "<literal>JBossCache</literal>">
+<!ENTITY TreeCache "<literal>TreeCache</literal>">
+<!ENTITY TreeCacheAop "<literal>TreeCacheAop</literal>">
+]>
+<article lang="en">
+ <articleinfo>
+ <title>Tomcat 5 Clustering In JBoss Release 3.2.6</title>
+
+ <author><firstname>Ben</firstname> <surname>Wang</surname></author>
+
+ <email>ben.wang at jboss.com</email>
+
+ <pubdate>August, 2004</pubdate>
+ </articleinfo>
+
+ <section>
+ <title id="s1">Introduction</title>
+
+ <para>Nowadays http web clustering (or failover) typically employs either
+ a hardware or software front-end load balancer to distribute the load
+ (with capability of session affinity). And the session state replication
+ is then delegated to the web container. Naturally, JBoss also has a
+ session replication layer for Tomcat since release 3.x.</para>
+
+ <para>In JBoss release 3.2.6, we have re-factored the Tomcat 5 http
+ session replication framework using JBossCache
+ (http://www.jboss.org/products/jbosscache) as the underlying in-memory
+ replication store. JBossCache is an open-source replicated, transactional,
+ and fine-grained cache system. Using JBossCache as the framework for
+ session replication offers separation of replication layer concerns (e.g.,
+ replication mode, lock behavior, partitioning, persistence, and
+ transaction) from the Tomcat session handling logics (e.g., sticky
+ session, replication granularity, and trigger). The end result is a
+ reduced development effort in Tomcat application layer and more robust
+ behavior in the overall system.</para>
+ </section>
+
+ <section>
+ <title id="s1a">Software Design</title>
+
+ <para>This section describes briefly the high level design and the web
+ application deployment process pertaining to the session
+ replication.</para>
+
+ <section>
+ <title>Class Responsibility</title>
+
+ <para>The following is a class diagram focusing on the http session
+ replication using JBossCache as the distributed store service under
+ Tomcat5. <figure>
+ <title>Tomcat5 http session replication class diagram</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="HttpSessionRepl.gif" />
+ </imageobject>
+ </mediaobject>
+ </figure></para>
+
+ <para>In addition to the JBossCacheService class that provides
+ replication service, there are three main interfaces: <itemizedlist>
+ <listitem>
+ <para><literal>org.jboss.web.tomcat.service.session.SnapshotManger.</literal>
+ Interface that defines the API to check for necessary session
+ replication. Note that it has a reference to JBossManager to
+ perform session replication. Two concrete implementation classes
+ are: <itemizedlist>
+ <listitem>
+
+
+ <literal>org.jboss.web.tomcat.service.session.InstantSnapshotManager</literal>
+
+ . Use of this snapshot manager will check for dirty session after every single http request (through
+
+ <literal>org.jboss.web.tomcat.service.session.ClusteredSessionValve</literal>
+
+ ). If a session is dirty, it will then be replicated.
+ </listitem>
+
+ <listitem>
+
+
+ <literal>org.jboss.web.tomcat.service.session.IntervalSnapshotManager</literal>
+
+ . Use of this snapshot manager will check for dirty session(s) only periodically (with a configurable timer interval). The dirty session(s) will be replicated when the timer kicks in.
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+
+ <listitem>
+ <para><literal>org.apache.catalina.Manager.</literal> This is a
+ Tomcat catalina interface that handles the session management. The
+ JBossCacheManager is the implemented class that also manages both
+ in-memory session and the sessions located in the distributed
+ store.</para>
+
+ <para>The reason that we need to use the in-memory session
+ instance is because of the web class loader can be different from
+ the system one. As a result, we will need to keep a "serialized"
+ version of the session data in the distributed store (done via
+ <literal>org.jboss.invocation.MarshalledValue</literal>) so that
+ the class loading scope will be correct. Otherwise, it will be
+ simply too expensive to retrieve and de-serialize every time from
+ the underneath store.</para>
+
+ <para>This manager is also called periodically by catalina to
+ process expired session(s) (or session timeout). When a session is
+ timed-out, it will be deleted from the store. However, the
+ operation is local only. That is, the delete operation will not
+ replicate to other cluster nodes since the other nodes will have
+ similar expiring process in place already. Therefore, the session
+ will be expired simultaneously from the whole cluster view.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>org.apache.catalina.Session.</literal> This is a
+ catalina interface that manages the session attributes and track
+ the session life time itself. We have two different concrete
+ implementation classes in this release: <itemizedlist>
+ <listitem>
+
+
+ <literal>org.jboss.web.tomcat.service.session.SessionBasedClusteredSession.</literal>
+
+ This corresponds to the setting in
+
+ <literal>jboss-web.xml</literal>
+
+ of
+
+ <literal>replication-granulairty</literal>
+
+ set to
+
+ <literal>session.</literal>
+
+ That is, whenever a session attribute is changed, it will replicate the whole session, regardless.
+ </listitem>
+
+ <listitem>
+
+
+ <literal>org.jboss.web.tomcat.service.session.AttributeBasedClusteredSession.</literal>
+
+ This corresponds to the setting in
+
+ <literal>jboss-web.xml</literal>
+
+ of
+
+ <literal>replication-granulairty</literal>
+
+ set to
+
+ <literal>attribute.</literal>
+
+ That is, whenever a session attribute is changed, it will replicate only the modified attribute. Note that this option which is finer grain in nature has the potential for session replication performance boost, especially when the session is carrying a large amount of data.
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Deployment Process</title>
+
+ <para>When a user deploys (or hot-deploys) a web application, the JBoss
+ <literal>org.jboss.web.tomcat.service.TomcatDeployer</literal> will first
+ determine if the web application is declared
+ <literal>distributable.</literal> If it is, JBoss will instantiate
+ <literal>JBossCacheManager</literal>, create
+ <literal>SnapshotManager</literal> and then add a
+ <literal>ClusteredSessionValve</literal> to the Tomcat interceptor
+ chain. As a result, every single http request will be intercepted by
+ this valve to process the necessary session replication (through
+ <literal>SnapshotManager</literal>).</para>
+ </section>
+ </section>
+
+ <section>
+ <title id="s2">Features</title>
+
+ <para>Here are the features provided with this release. For clarity, we
+ will divide them into Tomcat and JBossCache level aspects, meaning the
+ configuration will be done either from JBossCache or the TC5 layer.</para>
+
+ <section>
+ <title id="s21">Tomcat level aspect</title>
+
+ <para>In
+ <literal>jbossweb-tomcat5.0/META-INF/jboss-service.xml</literal> , you
+ can configure the followings: <itemizedlist>
+ <listitem>
+ <literal>SnapshotMode</literal>
+
+ <itemizedlist><listitem> <literal>instant</literal> Session
+ replication is performed during each HTTP request. But whether it
+ is instantaneously or not also depends on the replication mode
+ (synchronous or asynchronous) in JBossCache setting. </listitem>
+ <listitem> <literal>Interval</literal> Replicated during a
+ specified time interval. There is an accompanying flag,
+ <literal>SnapshotInterval</literal>, that indicates the snapshot
+ interval in milliseconds. The
+ <literal>IntervalSnapshotManager</literal> will perform session
+ dirty check every <literal>SnapshotInterval.</literal> This
+ manager keeps track of the dirty session(s)
+ internally.</listitem></itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para><literal>UseJK</literal> A flag indicating whether to use
+ the Apache mod_jk(2) for the front end software load balancing
+ with sticky session combined with JvmRoute. If set to true, it
+ will insert a JvmRouteFilter to intercept every request during
+ deployment and replace the JvmRoute if it detects a failover in
+ runtime. In addition, you will need to set the JvmRoute inside
+ Tomcat, e.g., <literal><Engine name="jboss.web"
+ jmvRoute="Node1" defaultHost="localhost"></literal> in
+ <literal>jbossweb-tomcat4.0/server.xml</literal>.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>Note that the above configuration parameters are applied to per
+ Tomcat instance. Change of the parameter will cause Tomcat to
+ re-deploy.</para>
+
+ <para>In each web application, you can also specify in
+ <literal>jboss-web.xml</literal> to customize the clustering behavior.
+ Specifically, there is an element called
+ <literal>replication-config</literal> that contains two sub-elements so
+ far: <itemizedlist>
+ <listitem>
+
+
+ <literal>replication-trigger</literal>
+
+ It determines what triggers a session replication (or when is a session is considered dirty). It has 4 options:
+
+ <itemizedlist><listitem><para><literal>ACCESS</literal> Indicating
+ if accessing the session is considered dirty. If set, it is
+ considered dirty with pure access and thus will cause replication.
+ Note that a session is "accessed" during each http request
+ regardless. It will update the access time stamp in the session
+ instance as well. Since the time stamp may not be updated in other
+ clustering nodes (because of no replication), this may cause
+ session in other nodes to expire before the active node if http
+ request does not retrieve or modify any session attributes.
+ </para><para>When this option is set, the session timestamps will
+ be synchronized throughout the cluster nodes. Note that use of
+ this option can have a significant performance impact so you will
+ need to use with caution.</para></listitem> <listitem>
+ <literal>SET_AND_GET</literal> Every session get and set
+ attributes are considered dirty. This option also can have
+ significant performance impact as well.</listitem> <listitem>
+ <literal>SET_AND_NON_PRIMITIVE_GET</literal> Session get and
+ non-primitive get are considered dirty. For example, the http
+ session request may retrieve a non-primitive object instance from
+ the attribute and then modify the instance. If we don't specify
+ that non-primitive get is considered dirty, then the modification
+ will not be replication properly. This is the default value.
+ </listitem> <listitem> <literal>SET</literal> Only set attribute
+ operation is considered dirty. If you are certain that only set
+ attribute operation is necessary for replication, this option will
+ be most optimized in term of
+ performance.</listitem></itemizedlist>
+
+
+ </listitem>
+
+ <listitem>
+ <literal>replication-granularity</literal>
+
+ <itemizedlist><listitem> <literal>session</literal> Replication is
+ per session instance. As long as it is considered modified when
+ the snapshot manager is called, the whole session object will be
+ serialized. </listitem> <listitem> <literal>attribute</literal>
+ Replication is only for the dirty attributes plus some session
+ data, like, lastAccessTime. For session that carries large amount
+ of data, this option can increase replication performance.
+ </listitem> <listitem> <literal>field</literal> Will need aop
+ (aspect-oriented programming) and be
+ available in 4.0.4. User can have control of even finer grain
+ replication through its own object graph. For example, if one
+ stores another map object into the session as an attribute, we can
+ track the dirty field down to the value object inside the map.
+ </listitem></itemizedlist>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title id="s22">JBossCache level aspect</title>
+
+ <para>The main configuration file is
+ <literal>tc5-cluster-service.xml</literal> of which is basically a
+ minimum version of JBossCache configuration xml file (more details
+ later). <itemizedlist>
+ <listitem>
+ <literal>CacheMode</literal>
+
+ <itemizedlist><listitem> <literal>REPL_SYNC</literal> Replication
+ is synchronous and call is blocking until replication succeeds or
+ fails. That is, replication will be completed before the http
+ request returns. </listitem> <listitem>
+ <literal>REPLY_ASYNC</literal> Replication is asynchronous and
+ call is non-blocking. Does not wait for results for the http
+ request to return. When session state replication is allowed to
+ have some latency, this is useful and will have a much better
+ performance throughput. </listitem></itemizedlist>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>In the future release, we will also add the following features
+ from JBossCache. <itemizedlist>
+ <listitem>
+ (sub)-Partitioning. This feature will partition the cluster into different sub-partitions such that replication only happens in the sub-partition nodes. With this feature, the session replication cluster can then be easily scaled.
+ </listitem>
+
+ <listitem>
+ Persistence. Persist the session data to the backed store. Currently, clustered session does not support any persistency.
+ </listitem>
+
+ <listitem>
+ Eviction policy and cache data overflow memory size or time-based eviction policy with overflow to back end persistent store. This is useful for users who have long running sessions that needs to support passivation.
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title id="s23">Deprecated</title>
+
+ <para>The following features have been deprecated in the new release:
+ <itemizedlist>
+ <listitem>
+ <para><literal>replication-type</literal> in
+ <literal>jboss-web.xml.</literal> User should directly configure
+ the replication type from
+ <literal>tc5-cluster-service.xml</literal> with the element
+ <literal><literal>CacheMode</literal></literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>UseLocalCache</literal> in
+ <literal>jbossweb-tomcat5.0/META-INF/jboss-service.xml.</literal>
+ Local in-vm session is used by default now.</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+ </section>
+
+ <section>
+ <title id="s3">What's New?</title>
+
+ <para>JBossCache can be configured through a xml configuration and
+ deployed under JBoss3.2.6 as a MBean service. Since JBossCache is used not
+ only for clustering but also for <literal>SSO</literal> (single sign on)
+ replication as well, we have introduced a JBossCache tc5 clustering MBean
+ service for everyone to share (such as <literal>SSO</literal>
+ replication). The xml configuration file will be called
+ <literal>tc5-cluster-service.xml</literal>. Once the file is deployed, a
+ MBean called <literal>TomcatClusteringCache</literal> will be
+ created.</para>
+
+ <para>In the file, there are JBossCache configuration parameters but
+ customized for the tc5 clustering. Here is a snippet of the xml:</para>
+
+ <programlisting><server>
+<mbean code="org.jboss.cache.TreeCache" name="jboss.cache:service=TomcatClusteringCache">
+ <depends>jboss:service=Naming</depends>
+ <depends>jboss:service=TransactionManager</depends>
+
+<!--
+ Configure the TransactionManager. Default should be JBossTransactionManager.
+-->
+ <attribute name="TransactionManagerLookupClass">org.jboss.cache.JBossTransactionManagerLookup</attribute>
+
+<!--
+ Valid modes are LOCAL
+ REPL_ASYNC
+ REPL_SYNC
+-->
+ <attribute name="CacheMode">REPL_ASYNC</attribute>
+
+<!--
+ Name of cluster. Needs to be the same for all clusters, in order
+ to find each other
+-->
+ <attribute name="ClusterName">TOMCAT-Cluster</attribute>
+
+<!--
+ JGroups protocol stack properties. Can also be a URL,
+ e.g. file:/home/bela/default.xml
+ <attribute name="ClusterProperties"></attribute>
+-->
+<attribute name="ClusterConfig">
+ <config>
+ <UDP mcast_addr="228.1.2.5" mcast_port="45566" ip_ttl="64" ip_mcast="true"
+ mcast_send_buf_size="150000" mcast_recv_buf_size="80000" ucast_send_buf_size="150000"
+ ucast_recv_buf_size="80000" loopback="false" />
+ ... more config params here ...
+ </config>
+</attribute>
+
+</mbean>
+</server>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Test Case</title>
+
+ <para>All http session clustering test cases are located under
+ <literal>JBoss-3.2/testsuite/src/main/org/jboss/test/cluster/apache-tomcat</literal>
+ directory.</para>
+ </section>
+
+ <section>
+ <title>Sample Usage</title>
+
+ <para>In this section, we describe how to setup a sample web application
+ for http session replication. User should refer to other documentation on
+ how to setup a front end load balancer (e.g., Apache mod_jk(2)).</para>
+
+ <para>To run a web application session replication under the new tc5
+ clustering, you will need to set the application to be distributable as
+ usual. For example, in <literal>web.xml</literal> (under the web app
+ <literal>WEB-INF</literal> directory), <programlisting><web-app>
+ <distributable/>
+ ...
+</web-app>
+</programlisting></para>
+
+ <para>Next, you can create an optional <literal>jboss-web.xml</literal>
+ (also under <literal>WEB-INF</literal> directory) that has the following
+ options: <programlisting><jboss-web>
+ <replication-config>
+ <replication-trigger>SET_AND_NON_PRIMITIVE_GET</replication-trigger>
+ <replication-granularity>SESSION</replication-granularity>
+ </replication-config>
+</jboss-web>
+</programlisting></para>
+
+ <para>In addition, you will need to start jboss from
+ <literal>all</literal> configuration directory. Under the new
+ <literal>all</literal> configuration, it includes the JBossCache library
+ and also the <literal>tc5-cluster-service.xml</literal>file to deploy the
+ cache as a specific tc5 clustering MBean service.</para>
+
+ <para>Finally, before you start JBoss, you can edit
+ <literal>jboss-service.xml</literal> under
+ <literal>jbossweb-tomcat5.0/META-INF</literal> directory for the
+ following: <programlisting><jboss-service>
+ <attribute name="SnapshotMode">instant</attribute>
+ <attribute name="UseJK">false</attribute>
+</jboss-service>
+</programlisting></para>
+
+ <para>You are now ready to use http session replication!</para>
+ </section>
+</article>
\ No newline at end of file
Deleted: branches/Branch_4_2/tomcat/docs/tc5-clustering.xml
===================================================================
--- branches/Branch_4_2/tomcat/docs/tc5-clustering.xml 2007-01-21 20:07:36 UTC (rev 59893)
+++ branches/Branch_4_2/tomcat/docs/tc5-clustering.xml 2007-01-21 20:12:52 UTC (rev 59894)
@@ -1,463 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" [
-<!ENTITY JBossCache "<literal>JBossCache</literal>">
-<!ENTITY TreeCache "<literal>TreeCache</literal>">
-<!ENTITY TreeCacheAop "<literal>TreeCacheAop</literal>">
-]>
-<article lang="en">
- <articleinfo>
- <title>Tomcat 5 Clustering In JBoss Release 3.2.6</title>
-
- <author><firstname>Ben</firstname> <surname>Wang</surname></author>
-
- <email>ben.wang at jboss.com</email>
-
- <pubdate>August, 2004</pubdate>
- </articleinfo>
-
- <section>
- <title id="s1">Introduction</title>
-
- <para>Nowadays http web clustering (or failover) typically employs either
- a hardware or software front-end load balancer to distribute the load
- (with capability of session affinity). And the session state replication
- is then delegated to the web container. Naturally, JBoss also has a
- session replication layer for Tomcat since release 3.x.</para>
-
- <para>In JBoss release 3.2.6, we have re-factored the Tomcat 5 http
- session replication framework using JBossCache
- (http://www.jboss.org/products/jbosscache) as the underlying in-memory
- replication store. JBossCache is an open-source replicated, transactional,
- and fine-grained cache system. Using JBossCache as the framework for
- session replication offers separation of replication layer concerns (e.g.,
- replication mode, lock behavior, partitioning, persistence, and
- transaction) from the Tomcat session handling logics (e.g., sticky
- session, replication granularity, and trigger). The end result is a
- reduced development effort in Tomcat application layer and more robust
- behavior in the overall system.</para>
- </section>
-
- <section>
- <title id="s1a">Software Design</title>
-
- <para>This section describes briefly the high level design and the web
- application deployment process pertaining to the session
- replication.</para>
-
- <section>
- <title>Class Responsibility</title>
-
- <para>The following is a class diagram focusing on the http session
- replication using JBossCache as the distributed store service under
- Tomcat5. <figure>
- <title>Tomcat5 http session replication class diagram</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="HttpSessionRepl.gif" />
- </imageobject>
- </mediaobject>
- </figure></para>
-
- <para>In addition to the JBossCacheService class that provides
- replication service, there are three main interfaces: <itemizedlist>
- <listitem>
- <para><literal>org.jboss.web.tomcat.service.session.SnapshotManger.</literal>
- Interface that defines the API to check for necessary session
- replication. Note that it has a reference to JBossManager to
- perform session replication. Two concrete implementation classes
- are: <itemizedlist>
- <listitem>
-
-
- <literal>org.jboss.web.tomcat.service.session.InstantSnapshotManager</literal>
-
- . Use of this snapshot manager will check for dirty session after every single http request (through
-
- <literal>org.jboss.web.tomcat.service.session.ClusteredSessionValve</literal>
-
- ). If a session is dirty, it will then be replicated.
- </listitem>
-
- <listitem>
-
-
- <literal>org.jboss.web.tomcat.service.session.IntervalSnapshotManager</literal>
-
- . Use of this snapshot manager will check for dirty session(s) only periodically (with a configurable timer interval). The dirty session(s) will be replicated when the timer kicks in.
- </listitem>
- </itemizedlist></para>
- </listitem>
-
- <listitem>
- <para><literal>org.apache.catalina.Manager.</literal> This is a
- Tomcat catalina interface that handles the session management. The
- JBossCacheManager is the implemented class that also manages both
- in-memory session and the sessions located in the distributed
- store.</para>
-
- <para>The reason that we need to use the in-memory session
- instance is because of the web class loader can be different from
- the system one. As a result, we will need to keep a "serialized"
- version of the session data in the distributed store (done via
- <literal>org.jboss.invocation.MarshalledValue</literal>) so that
- the class loading scope will be correct. Otherwise, it will be
- simply too expensive to retrieve and de-serialize every time from
- the underneath store.</para>
-
- <para>This manager is also called periodically by catalina to
- process expired session(s) (or session timeout). When a session is
- timed-out, it will be deleted from the store. However, the
- operation is local only. That is, the delete operation will not
- replicate to other cluster nodes since the other nodes will have
- similar expiring process in place already. Therefore, the session
- will be expired simultaneously from the whole cluster view.</para>
- </listitem>
-
- <listitem>
- <para><literal>org.apache.catalina.Session.</literal> This is a
- catalina interface that manages the session attributes and track
- the session life time itself. We have two different concrete
- implementation classes in this release: <itemizedlist>
- <listitem>
-
-
- <literal>org.jboss.web.tomcat.service.session.SessionBasedClusteredSession.</literal>
-
- This corresponds to the setting in
-
- <literal>jboss-web.xml</literal>
-
- of
-
- <literal>replication-granulairty</literal>
-
- set to
-
- <literal>session.</literal>
-
- That is, whenever a session attribute is changed, it will replicate the whole session, regardless.
- </listitem>
-
- <listitem>
-
-
- <literal>org.jboss.web.tomcat.service.session.AttributeBasedClusteredSession.</literal>
-
- This corresponds to the setting in
-
- <literal>jboss-web.xml</literal>
-
- of
-
- <literal>replication-granulairty</literal>
-
- set to
-
- <literal>attribute.</literal>
-
- That is, whenever a session attribute is changed, it will replicate only the modified attribute. Note that this option which is finer grain in nature has the potential for session replication performance boost, especially when the session is carrying a large amount of data.
- </listitem>
- </itemizedlist></para>
- </listitem>
- </itemizedlist></para>
- </section>
-
- <section>
- <title>Deployment Process</title>
-
- <para>When a user deploys (or hot-deploys) a web application, the JBoss
- <literal>org.jboss.web.tomcat.service.TomcatDeployer</literal> will first
- determine if the web application is declared
- <literal>distributable.</literal> If it is, JBoss will instantiate
- <literal>JBossCacheManager</literal>, create
- <literal>SnapshotManager</literal> and then add a
- <literal>ClusteredSessionValve</literal> to the Tomcat interceptor
- chain. As a result, every single http request will be intercepted by
- this valve to process the necessary session replication (through
- <literal>SnapshotManager</literal>).</para>
- </section>
- </section>
-
- <section>
- <title id="s2">Features</title>
-
- <para>Here are the features provided with this release. For clarity, we
- will divide them into Tomcat and JBossCache level aspects, meaning the
- configuration will be done either from JBossCache or the TC5 layer.</para>
-
- <section>
- <title id="s21">Tomcat level aspect</title>
-
- <para>In
- <literal>jbossweb-tomcat5.0/META-INF/jboss-service.xml</literal> , you
- can configure the followings: <itemizedlist>
- <listitem>
- <literal>SnapshotMode</literal>
-
- <itemizedlist><listitem> <literal>instant</literal> Session
- replication is performed during each HTTP request. But whether it
- is instantaneously or not also depends on the replication mode
- (synchronous or asynchronous) in JBossCache setting. </listitem>
- <listitem> <literal>Interval</literal> Replicated during a
- specified time interval. There is an accompanying flag,
- <literal>SnapshotInterval</literal>, that indicates the snapshot
- interval in milliseconds. The
- <literal>IntervalSnapshotManager</literal> will perform session
- dirty check every <literal>SnapshotInterval.</literal> This
- manager keeps track of the dirty session(s)
- internally.</listitem></itemizedlist>
- </listitem>
-
- <listitem>
- <para><literal>UseJK</literal> A flag indicating whether to use
- the Apache mod_jk(2) for the front end software load balancing
- with sticky session combined with JvmRoute. If set to true, it
- will insert a JvmRouteFilter to intercept every request during
- deployment and replace the JvmRoute if it detects a failover in
- runtime. In addition, you will need to set the JvmRoute inside
- Tomcat, e.g., <literal><Engine name="jboss.web"
- jmvRoute="Node1" defaultHost="localhost"></literal> in
- <literal>jbossweb-tomcat4.0/server.xml</literal>.</para>
- </listitem>
- </itemizedlist></para>
-
- <para>Note that the above configuration parameters are applied to per
- Tomcat instance. Change of the parameter will cause Tomcat to
- re-deploy.</para>
-
- <para>In each web application, you can also specify in
- <literal>jboss-web.xml</literal> to customize the clustering behavior.
- Specifically, there is an element called
- <literal>replication-config</literal> that contains two sub-elements so
- far: <itemizedlist>
- <listitem>
-
-
- <literal>replication-trigger</literal>
-
- It determines what triggers a session replication (or when is a session is considered dirty). It has 4 options:
-
- <itemizedlist><listitem><para><literal>ACCESS</literal> Indicating
- if accessing the session is considered dirty. If set, it is
- considered dirty with pure access and thus will cause replication.
- Note that a session is "accessed" during each http request
- regardless. It will update the access time stamp in the session
- instance as well. Since the time stamp may not be updated in other
- clustering nodes (because of no replication), this may cause
- session in other nodes to expire before the active node if http
- request does not retrieve or modify any session attributes.
- </para><para>When this option is set, the session timestamps will
- be synchronized throughout the cluster nodes. Note that use of
- this option can have a significant performance impact so you will
- need to use with caution.</para></listitem> <listitem>
- <literal>SET_AND_GET</literal> Every session get and set
- attributes are considered dirty. This option also can have
- significant performance impact as well.</listitem> <listitem>
- <literal>SET_AND_NON_PRIMITIVE_GET</literal> Session get and
- non-primitive get are considered dirty. For example, the http
- session request may retrieve a non-primitive object instance from
- the attribute and then modify the instance. If we don't specify
- that non-primitive get is considered dirty, then the modification
- will not be replication properly. This is the default value.
- </listitem> <listitem> <literal>SET</literal> Only set attribute
- operation is considered dirty. If you are certain that only set
- attribute operation is necessary for replication, this option will
- be most optimized in term of
- performance.</listitem></itemizedlist>
-
-
- </listitem>
-
- <listitem>
- <literal>replication-granularity</literal>
-
- <itemizedlist><listitem> <literal>session</literal> Replication is
- per session instance. As long as it is considered modified when
- the snapshot manager is called, the whole session object will be
- serialized. </listitem> <listitem> <literal>attribute</literal>
- Replication is only for the dirty attributes plus some session
- data, like, lastAccessTime. For session that carries large amount
- of data, this option can increase replication performance.
- </listitem> <listitem> <literal>field</literal> Will need aop
- (aspect-oriented programming) and be
- available in 4.0.4. User can have control of even finer grain
- replication through its own object graph. For example, if one
- stores another map object into the session as an attribute, we can
- track the dirty field down to the value object inside the map.
- </listitem></itemizedlist>
- </listitem>
- </itemizedlist></para>
- </section>
-
- <section>
- <title id="s22">JBossCache level aspect</title>
-
- <para>The main configuration file is
- <literal>tc5-cluster-service.xml</literal> of which is basically a
- minimum version of JBossCache configuration xml file (more details
- later). <itemizedlist>
- <listitem>
- <literal>CacheMode</literal>
-
- <itemizedlist><listitem> <literal>REPL_SYNC</literal> Replication
- is synchronous and call is blocking until replication succeeds or
- fails. That is, replication will be completed before the http
- request returns. </listitem> <listitem>
- <literal>REPLY_ASYNC</literal> Replication is asynchronous and
- call is non-blocking. Does not wait for results for the http
- request to return. When session state replication is allowed to
- have some latency, this is useful and will have a much better
- performance throughput. </listitem></itemizedlist>
- </listitem>
- </itemizedlist></para>
-
- <para>In the future release, we will also add the following features
- from JBossCache. <itemizedlist>
- <listitem>
- (sub)-Partitioning. This feature will partition the cluster into different sub-partitions such that replication only happens in the sub-partition nodes. With this feature, the session replication cluster can then be easily scaled.
- </listitem>
-
- <listitem>
- Persistence. Persist the session data to the backed store. Currently, clustered session does not support any persistency.
- </listitem>
-
- <listitem>
- Eviction policy and cache data overflow memory size or time-based eviction policy with overflow to back end persistent store. This is useful for users who have long running sessions that needs to support passivation.
- </listitem>
- </itemizedlist></para>
- </section>
-
- <section>
- <title id="s23">Deprecated</title>
-
- <para>The following features have been deprecated in the new release:
- <itemizedlist>
- <listitem>
- <para><literal>replication-type</literal> in
- <literal>jboss-web.xml.</literal> User should directly configure
- the replication type from
- <literal>tc5-cluster-service.xml</literal> with the element
- <literal><literal>CacheMode</literal></literal>.</para>
- </listitem>
-
- <listitem>
- <para><literal>UseLocalCache</literal> in
- <literal>jbossweb-tomcat5.0/META-INF/jboss-service.xml.</literal>
- Local in-vm session is used by default now.</para>
- </listitem>
- </itemizedlist></para>
- </section>
- </section>
-
- <section>
- <title id="s3">What's New?</title>
-
- <para>JBossCache can be configured through a xml configuration and
- deployed under JBoss3.2.6 as a MBean service. Since JBossCache is used not
- only for clustering but also for <literal>SSO</literal> (single sign on)
- replication as well, we have introduced a JBossCache tc5 clustering MBean
- service for everyone to share (such as <literal>SSO</literal>
- replication). The xml configuration file will be called
- <literal>tc5-cluster-service.xml</literal>. Once the file is deployed, a
- MBean called <literal>TomcatClusteringCache</literal> will be
- created.</para>
-
- <para>In the file, there are JBossCache configuration parameters but
- customized for the tc5 clustering. Here is a snippet of the xml:</para>
-
- <programlisting><server>
-<mbean code="org.jboss.cache.TreeCache" name="jboss.cache:service=TomcatClusteringCache">
- <depends>jboss:service=Naming</depends>
- <depends>jboss:service=TransactionManager</depends>
-
-<!--
- Configure the TransactionManager. Default should be JBossTransactionManager.
--->
- <attribute name="TransactionManagerLookupClass">org.jboss.cache.JBossTransactionManagerLookup</attribute>
-
-<!--
- Valid modes are LOCAL
- REPL_ASYNC
- REPL_SYNC
--->
- <attribute name="CacheMode">REPL_ASYNC</attribute>
-
-<!--
- Name of cluster. Needs to be the same for all clusters, in order
- to find each other
--->
- <attribute name="ClusterName">TOMCAT-Cluster</attribute>
-
-<!--
- JGroups protocol stack properties. Can also be a URL,
- e.g. file:/home/bela/default.xml
- <attribute name="ClusterProperties"></attribute>
--->
-<attribute name="ClusterConfig">
- <config>
- <UDP mcast_addr="228.1.2.5" mcast_port="45566" ip_ttl="64" ip_mcast="true"
- mcast_send_buf_size="150000" mcast_recv_buf_size="80000" ucast_send_buf_size="150000"
- ucast_recv_buf_size="80000" loopback="false" />
- ... more config params here ...
- </config>
-</attribute>
-
-</mbean>
-</server>
-</programlisting>
- </section>
-
- <section>
- <title>Test Case</title>
-
- <para>All http session clustering test cases are located under
- <literal>JBoss-3.2/testsuite/src/main/org/jboss/test/cluster/apache-tomcat</literal>
- directory.</para>
- </section>
-
- <section>
- <title>Sample Usage</title>
-
- <para>In this section, we describe how to setup a sample web application
- for http session replication. User should refer to other documentation on
- how to setup a front end load balancer (e.g., Apache mod_jk(2)).</para>
-
- <para>To run a web application session replication under the new tc5
- clustering, you will need to set the application to be distributable as
- usual. For example, in <literal>web.xml</literal> (under the web app
- <literal>WEB-INF</literal> directory), <programlisting><web-app>
- <distributable/>
- ...
-</web-app>
-</programlisting></para>
-
- <para>Next, you can create an optional <literal>jboss-web.xml</literal>
- (also under <literal>WEB-INF</literal> directory) that has the following
- options: <programlisting><jboss-web>
- <replication-config>
- <replication-trigger>SET_AND_NON_PRIMITIVE_GET</replication-trigger>
- <replication-granularity>SESSION</replication-granularity>
- </replication-config>
-</jboss-web>
-</programlisting></para>
-
- <para>In addition, you will need to start jboss from
- <literal>all</literal> configuration directory. Under the new
- <literal>all</literal> configuration, it includes the JBossCache library
- and also the <literal>tc5-cluster-service.xml</literal>file to deploy the
- cache as a specific tc5 clustering MBean service.</para>
-
- <para>Finally, before you start JBoss, you can edit
- <literal>jboss-service.xml</literal> under
- <literal>jbossweb-tomcat5.0/META-INF</literal> directory for the
- following: <programlisting><jboss-service>
- <attribute name="SnapshotMode">instant</attribute>
- <attribute name="UseJK">false</attribute>
-</jboss-service>
-</programlisting></para>
-
- <para>You are now ready to use http session replication!</para>
- </section>
-</article>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list