[jboss-cvs] JBossAS SVN: r94334 - projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Oct 5 02:37:47 EDT 2009
Author: laubai
Date: 2009-10-05 02:37:47 -0400 (Mon, 05 Oct 2009)
New Revision: 94334
Modified:
projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_HTTP.xml
Log:
Integrated changes from JBPAPP-2646 for GA.
Modified: projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_HTTP.xml
===================================================================
--- projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_HTTP.xml 2009-10-05 06:34:15 UTC (rev 94333)
+++ projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_HTTP.xml 2009-10-05 06:37:47 UTC (rev 94334)
@@ -18,7 +18,7 @@
<para>State replication is directly handled by JBoss. When you run JBoss
in the <literal>all</literal> configuration, session state replication is
enabled by default. Just configure your web application as
- <literal><distributable></literal> in its <filename>web.xml</filename> (see below),
+ <literal><distributable></literal> in its <filename>web.xml</filename> (see <xref linkend="clustering-http-state"/>),
deploy it, and its session state is automtically replicated across all
JBoss instances in the cluster.</para>
<para>However, load-balancing is a different story; it is not handled by
@@ -44,9 +44,9 @@
example) will be lost and the clients will most probably need to login
on another node and restart with a new session. In many situations, it
is acceptable not to replicate HTTP sessions because all critical state
- is stored in a database. In other situations, losing a client session
- is not acceptable and, in this case, session state replication is the
- price one has to pay.</para>
+ is stored in a database or on the client. In other situations, losing a
+ client session is not acceptable and, in this case, session state
+ replication is the price one has to pay.</para>
</note>
<section id="clustering-http-modjk">
@@ -58,13 +58,13 @@
<section id="clustering-http-download">
<title>Download the software</title>
<para>First of all, make sure that you have Apache installed. You can download Apache directly from
- Apache web site at <literal>http://httpd.apache.org/</literal>. Its installation is pretty
+ Apache web site at <literal>http://httpd.apache.org/</literal>. Its installation is pretty
straightforward and requires no specific configuration. As several versions of Apache exist, we
- advise you to use version 2.0.x. We will consider, for the next sections, that you have installed
+ advise you to use the latest stable 2.2.x version. We will consider, for the next sections, that you have installed
Apache in the <literal>APACHE_HOME</literal> directory.</para>
<para>Next, download mod_jk binaries. Several versions of mod_jk exist as well. We strongly advise you
to use mod_jk 1.2.x, as both mod_jk and mod_jk2 are deprecated, unsupported and no further
- developments are going on in the community. The mod_jk 1.2.x binary can be downloaded from
+ development is going on in the community. The mod_jk 1.2.x binary can be downloaded from
<literal>http://www.apache.org/dist/jakarta/tomcat-connectors/jk/binaries/</literal>. Rename the
downloaded file to <literal>mod_jk.so</literal> and copy it under
<literal>APACHE_HOME/modules/</literal>.</para>
@@ -134,7 +134,7 @@
<para>The <literal>JkMount</literal> directive tells Apache which URLs it should forward to the
mod_jk module (and, in turn, to the Servlet containers). In the above file, all requests
with URL path <literal>/application/*</literal> are sent to the mod_jk load-balancer. This
- way, you can configure Apache to server static contents (or PHP contents) directly and only
+ way, you can configure Apache to serve static contents (or PHP contents) directly and only
use the loadbalancer for Java applications. If you only use mod_jk as a loadbalancer, you
can also forward all URLs (i.e., <literal>/*</literal>) to mod_jk.</para>
</listitem>
@@ -197,9 +197,9 @@
worker.status.type=status
</programlisting>
<para>Basically, the above file configures mod_jk to perform weighted round-robin load balancing with
- sticky sessions between two servlet containers (JBoss Tomcat) node1 and node2 listening on port
+ sticky sessions between two servlet containers (that is, JBoss AS instances) node1 and node2 listening on port
8009.</para>
- <para>In the <literal>works.properties</literal> file, each node is defined using the
+ <para>In the <literal>workers.properties</literal> file, each node is defined using the
<literal>worker.XXX</literal> naming convention where <literal>XXX</literal> represents an
arbitrary name you choose for each of the target Servlet containers. For each worker, you must specify the host name (or IP address) and the port number of the AJP13 connector running in the Servlet container.</para>
@@ -227,11 +227,11 @@
</section>
<section id="clustering-http-jboss">
<title>Configuring JBoss to work with mod_jk</title>
- <para>Finally, we must configure the JBoss Tomcat instances on all clustered nodes so that they can
+ <para>Finally, we must configure the JBoss AS instances on all clustered nodes so that they can
expect requests forwarded from the mod_jk loadbalancer.</para>
<para>On each clustered JBoss node, we have to name the node according to the name specified in
<literal>workers.properties</literal>. For instance, on JBoss instance node1, edit the
- <literal>JBOSS_HOME/server/all/deploy/jboss-web.deployer/server.xml</literal> file (replace
+ <literal>JBOSS_HOME/server/all/deploy/jbossweb.sar/server.xml</literal> file (replace
<literal>/all</literal> with your own server name if necessary). Locate the
<literal><Engine></literal> element and add an attribute <literal>jvmRoute</literal>:</para>
<programlisting>
@@ -243,25 +243,25 @@
</para>
<programlisting><![CDATA[
<!-- Define an AJP 1.3 Connector on port 8009 -->
-<Connector port="8009" address="${jboss.bind.address}" protocol="AJP/1.3"
-emptySessionPath="true" enableLookups="false" redirectPort="8443" /> ]]>
-</programlisting>
++<Connector protocol="AJP/1.3" port="8009" address="${jboss.bind.address}"
++ redirectPort="8443" />]]>
+ </programlisting>
-<para>Then, for each JBoss Tomcat instance in the cluster, we need to tell it that mod_jk is in use, so it can properly manage the <literal>jvmRoute</literal> appended to its session cookies so that mod_jk can properly route incoming requests. Edit the
+<!--<para>Then, for each JBoss Tomcat instance in the cluster, we need to tell it that mod_jk is in use, so it can properly manage the <literal>jvmRoute</literal> appended to its session cookies so that mod_jk can properly route incoming requests. Edit the
<literal>JBOSS_HOME/server/all/deploy/jbossweb-tomcat50.sar/META-INF/jboss-service.xml</literal>
file (replace <literal>/all</literal> with your own server name). Locate the
<literal><attribute></literal> element with a name of <literal>UseJK</literal>, and set
its value to <literal>true</literal>:</para>
<programlisting>
<attribute name="UseJK">true</attribute>
- </programlisting>
+ </programlisting>-->
<para>At this point, you have a fully working Apache+mod_jk load-balancer setup that will balance call
to the Servlet containers of your cluster while taking care of session stickiness (clients will
always use the same Servlet container).</para>
<note>
- <para>For more updated information on using mod_jk 1.2 with JBoss Tomcat, please refer to the JBoss
+ <para>For more updated information on using mod_jk 1.2 with JBoss AS, please refer to the JBoss
wiki page at
- <literal>http://wiki.jboss.org/wiki/Wiki.jsp?page=UsingMod_jk1.2WithJBoss</literal>.</para>
+ <literal>http://www.jboss.org/community/wiki/UsingModjk12WithJBoss</literal>.</para>
</note>
</section>
@@ -271,16 +271,16 @@
<para>The preceding discussion has been focused on using mod_jk as a load balancer. The content of the remainder our discussion of clustering HTTP services in JBoss Enterprise Application Platform applies no matter what load balancer is used.
</para>
- <para>In <xref linkend="clustering-http-nodes"/>, we covered how to use sticky sessions to make sure that a client in a session always hits the same server node in order to maintain the session state. However, sticky sessions by themselves are not an ideal solution. If a node goes down, all its session data is lost. A better and more reliable solution is to replicate session data across the nodes in the cluster. This way, the client can hit any server node and obtain the same session state.</para>
+ <para>In <xref linkend="clustering-http-nodes"/>, we covered how to use sticky sessions to make sure that a client in a session always hits the same server node in order to maintain the session state. However, sticky sessions by themselves are not an ideal solution. If a node goes down, all its session data is lost. A better and more reliable solution is to replicate session data across the nodes in the cluster. This way, if a server node fails or is shut down, the load balancer can fail over the next client request to any server node and obtain the same session state.</para>
- <para>The <literal>jboss.cache:service=TomcatClusteringCache</literal> MBean makes use of JBoss Cache to
+ <!--<para>The <literal>jboss.cache:service=TomcatClusteringCache</literal> MBean makes use of JBoss Cache to
provide HTTP session replication services to the JBoss Tomcat cluster. This MBean is defined in the <literal>deploy/jboss-web-cluster.sar/META-INF/jboss-service.xml file</literal>.</para>
<note>
- <para>Before JBoss Enterprise Application Platform 4.2.0, the location of the HTTP session cache configuration file was <literal>deploy/tc5-cluster.sar/META-INF/jboss-service.xml</literal>. <!-- Prior to Enterprise Application Platform 4.0.4 CR2, the file was named <literal>deploy/tc5-cluster-service.xml</literal>. --></para>
+ <para>Before JBoss Enterprise Application Platform 4.2.0, the location of the HTTP session cache configuration file was <literal>deploy/tc5-cluster.sar/META-INF/jboss-service.xml</literal>. Prior to Enterprise Application Platform 4.0.4 CR2, the file was named <literal>deploy/tc5-cluster-service.xml</literal>. </para>
</note>
<para>Below is a typical <literal>deploy/jbossweb-cluster.sar/META-INF/jboss-service.xml</literal> file. The
configuration attributes in the <literal>TomcatClusteringCache</literal> MBean are very similar to
- those in the JBoss Enterprise Application Platform cache configuration.<!--<xref linkend="jbosscache-cache"/>.--></para>
+ those in the JBoss Enterprise Application Platform cache configuration.<xref linkend="jbosscache-cache"/>.</para>
<programlisting>
<mbean code="org.jboss.cache.aop.TreeCacheAop"
name="jboss.cache:service=TomcatClusteringCache">
@@ -352,12 +352,12 @@
<para><emphasis role="bold">SyncReplTimeout</emphasis> sets the maximum number of milliseconds to wait for a response from all nodes in the cluster when a synchronous replication message is sent out. The default value is 20000; should be a few seconds longer than LockAcquisitionTimeout.</para>
</listitem>
- </itemizedlist>
+ </itemizedlist>-->
<section id="clustering-http-app">
<title>Enabling session replication in your application</title>
- <para>To enable clustering of your web application you must tag it as distributable in the
+ <para>To enable replication of your web application you must tag the application as distributable in the
<literal>web.xml</literal> descriptor. Here's an example:</para>
<programlisting><?xml version="1.0"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
@@ -365,72 +365,380 @@
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
version="2.4">
+
<emphasis role="bold"><distributable/></emphasis>
- <!-- ... -->
+
</web-app></programlisting>
<para> You can futher configure session replication using the <literal>replication-config</literal>
- element in the <literal>jboss-web.xml</literal> file. Here is an example: </para>
- <programlisting><jboss-web>
- <replication-config>
- <replication-trigger>SET_AND_NON_PRIMITIVE_GET</replication-trigger>
- <replication-granularity>SESSION</replication-granularity>
- <replication-field-batch-mode>true</replication-field-batch-mode>
- </replication-config>
-</jboss-web></programlisting>
- <para>The <literal>replication-trigger</literal> element determines what triggers a session replication
- (i.e. when is a session is considered <literal>dirty</literal> and in need of replication). It has 4 options:</para>
+ element in the <literal>jboss-web.xml</literal> file. However,
+ the <literal>replication-config</literal> element only needs to be set
+ if one or more of the default values described below is unacceptable.
+ Here is an example: </para>
+ <programlisting><![CDATA[<!DOCTYPE jboss-web PUBLIC
+ -//JBoss//DTD Web Application 5.0//EN
+ http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd>
+
+<jboss-web>
+
+ <replication-config>
+ <cache-name>custom-session-cache</cache-name>
+ <replication-trigger>SET</replication-trigger>
+ <replication-granularity>ATTRIBUTE</replication-granularity>
+ <replication-field-batch-mode>true</replication-field-batch-mode>
+ <use-jk>false</use-jk>
+ <max-unreplicated-interval>30</max-unreplicated-interval>
+ <snapshot-mode>instant</snapshot-mode>
+ <snapshot-interval>1000</snapshot-interval>
+ <session-notification-policy>com.example.CustomSessionNotificationPolicy</session-notification-policy>
+ </replication-config>
+
+</jboss-web>]]></programlisting>
+
+ <para>All of the above configuration elements are optional and can be ommitted
+ if the default value is acceptable. A couple are commonly used; the rest
+ are very infrequently changed from the defaults. We'll cover the commonly used ones first.</para>
+
+ <para>The <emphasis role="bold"><literal>replication-trigger</literal></emphasis> element determines when
+ the container should consider that session data must be replicated across
+ the cluster. The rationale for this setting is that after a mutable object
+ stored as a session attribute is accessed from the session, in the absence
+ of a <literal>setAttribute</literal> call the container has no clear way
+ to know if the object (and hence the session state) has been modified
+ and needs to be replicated. This element has 3 valid values:</para>
<itemizedlist>
<listitem>
- <para><emphasis role="bold">SET</emphasis>: With this policy, the session is considered dirty only when an attribute is set in the session (i.e., HttpSession.setAttribute() is invoked.) If your application always writes changed values back into the session, this option will be most optimal in terms of performance. The downside of SET is that if an object is retrieved from the session and modified without being written back into the session, the session manager will not know the attribute is dirty and the change to that object may not be replicated.</para>
+ <para><emphasis role="bold">SET_AND_GET</emphasis> is conservative but not optimal (performance-wise): it will always replicate session data even if its content has not been modified but simply accessed. This setting made (a little) sense in AS 4 since using it was a way to ensure that every request triggered replication of the session's timestamp. Since setting <literal>max_unreplicated_interval</literal> to 0 accomplishes the same thing at much lower cost, using <literal>SET_AND_GET</literal> makes no sense with AS 5.</para>
</listitem>
<listitem>
- <para><emphasis role="bold">SET_AND_GET</emphasis>: With this policy, any attribute that is get or set will be marked as dirty. If an object is retrieved from the session and modified without being written back into the session, the change to that object will be replicated. The downside of SET_AND_GET is that it can have significant performance implications, since even reading immutable objects from the session (e.g., strings, numbers) will mark the read attributes as needing to be replicated.</para>
+ <para><emphasis role="bold">SET_AND_NON_PRIMITIVE_GET</emphasis> is conservative but will only replicate if an object of a non-primitive type has been accessed (i.e. the object is not of a well-known immutable JDK type such as <literal>Integer</literal>, <literal>Long</literal>, <literal>String</literal>, etc.) This is the default value.</para>
</listitem>
<listitem>
- <para><emphasis role="bold">SET_AND_NON_PRIMITIVE_GET</emphasis>: This policy is similar to the SET_AND_GET policy except that get operationsthat return attribute values with primitive types do not mark the attribute as dirty. Primitive system types (i.e., String, Integer, Long, etc.) are immutable, so there is no reason to mark an attribute with such a type as dirty just because it has been read. If a get operation returns a value of a non-primitive type, the session manager has no simple way to know whether the object is mutable, so it assumes it is an marks the attribute as dirty. This setting avoids the downside of SET while reducing the performance impact of SET_AND_GET. It is the default setting.</para>
+ <para><emphasis role="bold">SET</emphasis> assumes that the developer will explicitly call <literal>setAttribute</literal> on the session if the data needs to be replicated. This setting prevents unnecessary replication and can have a major beneficial impact on performance, but requires very good coding practices to ensure <literal>setAttribute</literal> is always called whenever a mutable object stored in the session is modified.</para>
</listitem>
- <listitem>
- <para><emphasis role="bold">ACCESS</emphasis>: This option causes the session to be marked as dirty whenever it is accessed. Since a the session is accessed during each HTTP request, it will be replicated with each request. The purpose of ACCESS is to ensure session last-access timestamps are kept in sync around the cluster.. Since with the other replication-trigger options the time stamp may not be updated in other clustering nodes because of no replication, the session in other nodes may expire before the active node if the HTTP request does not retrieve or modify any session attributes. 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 use it with caution. With the other replication-trigger options, if a session has gone 80% of its expiration interval without being replicated, as a safeguard its timestamp will be replicated no matter what. So, A!
CCESS is only useful in special circumstances where the above safeguard is considered inadequate.</para>
- </listitem>
</itemizedlist>
- <para>The <literal>replication-granularity</literal> element controls the size of the replication units.
- The supported values are: </para>
+ <para>In all cases, calling <literal>setAttribute</literal> marks the session as needing replication.</para>
+ <para>The <emphasis role="bold"><literal>replication-granularity</literal></emphasis> element determines the granularity of what gets replicated if the container determines session replication is needed. The supported values are: </para>
<itemizedlist>
-
+ <listitem>
+ <para><emphasis role="bold">SESSION</emphasis> indicates that the entire session attribute map should be replicated when any attribute is considered modified. Replication occurs at request end. This option replicates the most data and thus incurs the highest replication cost, but since all attributes values are always replicated together it ensures that any references between attribute values will not be broken when the session is deserialized. For this reason it is the default setting.</para>
+ </listitem>
<listitem>
- <para><emphasis role="bold">ATTRIBUTE</emphasis>: Replication is only for the dirty attributes in the session plus some session data, like the last-accessed timestamp. For sessions that carry large amounts of data, this option can increase replication performance. However, attributes will be separately serialized, so if there are any shared references between objects stored in the attributes, those shared references may be broken on remote nodes. For example, say a Person object stored under key “husband” has a reference to an Address, while another Person object stored under key “wife” has a reference to that same Address object. When the “husband” and “wife” attributes are separately deserialized on the remote nodes, each Person object will now have a reference to its own Address object; the Address object will no longer be shared.</para>
+ <para><emphasis role="bold">ATTRIBUTE</emphasis> indicates that only attributes that the session considers to be potentially modified are replicated. Replication occurs at request end. For sessions carrying large amounts of data, parts of which are infrequently updated, this option can significantly increase replication performance. However, it is not suitable for applications that store objects in different attributes that share references with each other (e.g. a <literal>Person</literal> object in the "husband" attribute sharing with another <literal>Person</literal> in the "wife" attribute a reference to an <literal>Address</literal> object). This is because if the attributes are separately replicated, when the session is deserialized on remote nodes the shared references will be broken.</para>
</listitem>
- <listitem>
- <para><emphasis role="bold">SESSION</emphasis>: The entire session object is replicated if any attribute is dirty. The entire session is serialized in one unit, so shared object references are maintained on remote nodes. This is the default setting.</para>
- </listitem>
-
<listitem>
- <para><emphasis role="bold">FIELD</emphasis>: Replication is only for individual changed data fields inside session attribute objects. Shared object references will be preserved across the cluster. Potentially most performant, but requires changes to your application (this will be discussed later).</para>
+ <para><emphasis role="bold">FIELD</emphasis> is useful if the classes stored in the session have been bytecode enhanced for use by POJO Cache. If they have been, the session management layer will detect field level changes within objects stored to the session, and will replicate only those changes. This is the most performant setting. Replication is only for individual changed data fields inside session attribute objects. Shared object references will be preserved across the cluster. Potentially most performant, but requires changes to your application (this will be discussed later).</para>
</listitem>
</itemizedlist>
- <para>The <literal>replication-field-batch-mode</literal> element indicates whether you want all replication messages associated with a request to be batched into one message. Only applicable if replication-granularity is FIELD. Default is <literal>true</literal>.</para>
- <para>If your sessions are generally small, SESSION is the better policy. If your session is larger and
- some parts are infrequently accessed, ATTRIBUTE replication will be more effective. If your
- application has very big data objects in session attributes and only fields in those objects are
- frequently modified, the FIELD policy would be the best. In the next section, we will discuss exactly
- how the FIELD level replication works.</para>
- </section>
+ <para>The other elements under the <literal>replication-config</literal> element are much less frequently used.</para>
+ <para>The <literal>cacheName</literal> element indicates the name of the
+ JBoss Cache configuration that should be used for storing distributable
+ sessions and replicating them around the cluster. This element lets web applications that require
+ different caching characteristics specify the use of separate, differently
+ configured, JBoss Cache instances. In JBoss AS 4 the cache to use was a server-wide
+ configuration that could not be changed per web application. The default value is <literal>standard-session-cache</literal>
+ if the <literal>replication-granularity</literal> is not <literal>FIELD</literal>,
+ <literal>field-granularity-session-cache</literal> if it is. See <xref linkend="clustering-http-state-cacheconfig"/>
+ for more details on JBoss Cache configuration for web tier clustering.</para>
+ <para>The <literal>replication-field-batch-mode</literal> element indicates
+ whether all replication messages associated with a request will be
+ batched into one message. This is applicable only if <literal>replication-granularity</literal>
+ is <literal>FIELD</literal>. If <literal>replication-field-batch-mode</literal> is set to <literal>true</literal>,
+ fine-grained changes made to objects stored in the session
+ attribute map will replicate only when the HTTP request is finished; otherwise
+ they replicate as they occur. Setting this to <literal>false</literal> is not
+ advised. Default is <literal>true</literal>.</para>
+ <para>The <literal>useJK</literal> element indicates whether the container
+ should assume that a JK-based software load balancer (e.g. mod_jk, mod_proxy,
+ mod_cluster) is being used for load balancing for this web application. If set to <literal>true</literal>,
+ the container will examine the session ID associated with every request and
+ replace the <literal>jvmRoute</literal> portion of the session ID if it detects a failover.</para>
+
+ <para>The default value is <literal>null</literal> (i.e. unspecified). In
+ this case the session manager will use the presence or absence of a <literal>jvmRoute</literal>
+ configuration on its enclosing JBoss Web <literal>Engine</literal>
+ (see <xref linkend="clustering-http-jboss"/>) to determine whether JK is used.</para>
+
+ <para>
+ You need only set this to <literal>false</literal> for web applications whose
+ URL cannot be handled by the JK load balancer.
+ </para>
+ <para>The <literal>max-unreplicated-interval</literal> element configures the
+ maximum interval between requests, in seconds, after which a request will
+ trigger replication of the session's timestamp regardless of whether the
+ request has otherwise made the session dirty. Such replication ensures that
+ other nodes in the cluster are aware of the most recent value for the session's
+ timestamp and won't incorrectly expire an unreplicated session upon failover.
+ It also results in correct values for <literal>HttpSession.getLastAccessedTime()</literal> calls
+ following failover.</para>
+ <para>A value of <literal>0</literal> means the timestamp will be replicated
+ whenever the session is accessed. A value of <literal>-1</literal> means the
+ timestamp will be replicated only if some other activity during the request
+ (e.g. modifying an attribute) has resulted in other replication work involving
+ the session. A positive value greater than the
+ <literal>HttpSession.getMaxInactiveInterval()</literal> value will be treated
+ as probable misconfiguration and converted to <literal>0</literal>; i.e. replicate
+ the metadata on every request. Default value is <literal>60</literal>.</para>
+ <para>The <literal>snapshot-mode</literal> element configures when sessions
+ are replicated to the other nodes. Possible values are <literal>instant</literal>
+ (the default) and <literal>interval</literal>.</para>
+
+ <para>The typical value, <literal>instant</literal>, replicates changes to the
+ other nodes at the end of requests, using the request processing thread to
+ perform the replication. In this case, the <literal>snapshot-interval</literal>
+ property is ignored.</para>
+
+ <para>With <literal>interval</literal> mode, a background task is created that
+ runs every <literal>snapshot-interval</literal> milliseconds, checking for
+ modified sessions and replicating them.</para>
+
+ <para>Note that this property has no effect if <literal>replication-granularity</literal>
+ is set to <literal>FIELD</literal>. If it is <literal>FIELD</literal>,
+ <literal>instant</literal> mode will be used.</para>
+
+ <para>The <literal>snapshot-interval</literal> element defines how often
+ (in milliseconds) the background task that replicates modified sessions
+ should be started for this web application. Only meaningful if <literal>snapshot-mode</literal>
+ is set to <literal>interval</literal>.</para>
+
+ <para>The <literal>session-notification-policy</literal> element specifies the
+ fully qualified class name of the implementation of the
+ <literal>ClusteredSessionNotificationPolicy</literal> interface that should be
+ used to govern whether servlet specification notifications should be emitted
+ to any registered <literal>HttpSessionListener</literal>, <literal>HttpSessionAttributeListener</literal>
+ and/or <literal>HttpSessionBindingListener</literal>.</para>
+
+ <para>Event notifications that may make sense in a non-clustered environment
+ may or may not make sense in a clustered environment; see
+ <link linkend="https://jira.jboss.org/jira/browse/JBAS-5778">https://jira.jboss.org/jira/browse/JBAS-5778</link>
+ for an example of why a notification may not be desired. Configuring an appropriate
+ <literal>ClusteredSessionNotificationPolicy</literal> gives the application
+ author fine-grained control over what notifications are issued.</para>
+
+ <para>In JBoss AS 5.0.0.GA the default value if not explicitly set is the
+ <literal>LegacyClusteredSessionNotificationPolicy</literal>, which implements
+ the behavior in previous JBoss versions. In JBoss AS 5.1.0, this was
+ changed to <literal>IgnoreUndeployLegacyClusteredSessionNotificationPolicy</literal>,
+ which implements the same behavior except during undeployment,
+ during which no <literal>HttpSessionListener</literal> and
+ <literal>HttpSessionAttributeListener</literal> notifications are sent.</para>
+
+ </section>
+
+ <section id="clustering-http-passivation">
+ <title>HttpSession Passivation and Activation</title>
+ <para>Passivation is the process of controlling memory usage by removing
+ relatively unused sessions from memory while storing them in persistent
+ storage. If a passivated session is requested by a client, it can be
+ "activated" back into memory and removed from the persistent store.
+ JBoss AS 5 supports passivation of HttpSessions from web applications whose
+ <literal>web.xml</literal> includes the <literal>distributable</literal>
+ tag (i.e. clustered web applications).</para>
+
+ <para>Passivation occurs at three points during the lifecycle of a web application:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>When the container requests the creation of a new session.
+ If the number of currently active sessions exceeds a configurable limit,
+ an attempt is made to passivate sessions to make room in memory.</para>
+ </listitem>
+ <listitem>
+ <para>Periodically (by default every ten seconds) as the JBoss Web
+ background task thread runs.</para>
+ </listitem>
+ <listitem>
+ <para>When the web application is deployed and a backup copy of sessions
+ active on other servers is acquired by the newly deploying web application's
+ session manager.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>A session will be passivated if one of the following holds true:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The session has not been in use for longer than a configurable maximum idle time.</para>
+ </listitem>
+ <listitem>
+ <para>The number of active sessions exceeds a configurable maximum and the
+ session has not been in use for longer than a configurable minimum idle time.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In both cases, sessions are passivated on a Least Recently Used (LRU) basis.</para>
+
+ <section id="clustering-http-passivation-config">
+ <title>Configuring HttpSession Passivation</title>
+
+ <para>Session passivation behavior is configured via the
+ <literal>jboss-web.xml</literal> deployment descriptor in your web application's
+ <literal>WEB-INF</literal> directory.</para>
+
+ <programlisting><![CDATA[
+<!DOCTYPE jboss-web PUBLIC
+ -//JBoss//DTD Web Application 5.0//EN
+ http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd>
+
+<jboss-web>
+
+ <max-active-sessions>20</max-active-sessions>
+ <passivation-config>
+ <use-session-passivation>true</use-session-passivation>
+ <passivation-min-idle-time>60</passivation-min-idle-time>
+ <passivation-max-idle-time>600</passivation-max-idle-time>
+ </passivation-config>
+
+
+</jboss-web>]]></programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">max-active-session</emphasis></para>
+ <para>Determines the maximum number of active sessions allowed. If the
+ number of sessions managed by the the session manager exceeds this value
+ and passivation is enabled, the excess will be passivated based on the
+ configured <literal>passivation-min-idle-time</literal>. If after
+ passivation is completed (or if passivation is disabled), the number of
+ active sessions still exceeds this limit, attempts to create new sessions
+ will be rejected. If set to <literal>-1</literal> (the default), there is no limit.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">use-session-passivation</emphasis></para>
+ <para>Determines whether session passivation will be enabled for the web
+ application. Default is <literal>false</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">passivation-min-idle-time</emphasis></para>
+ <para>Determines the minimum time (in seconds) that a session must have been
+ inactive before the container will consider passivating it in order to
+ reduce the active session count to obey the value defined by <literal>max-active-sessions</literal>.
+ A value of <literal>-1</literal> (the default) disables passivating sessions
+ before <literal>passivation-max-idle-time</literal>. Neither a value of <literal>-1</literal>
+ nor a high value are recommended if <literal>max-active-sessions</literal>
+ is set.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">passivation-max-idle-time</emphasis></para>
+ <para>Determines the maximum time (in seconds) that a session can be inactive
+ before the container should attempt to passivate it to save memory.
+ Passivation of such sessions will take place regardless of whether the
+ active session count exceeds <literal>max-active-sessions</literal>. Should
+ be less than the <filename>web.xml</filename> <literal>session-timeout</literal> setting. A value
+ of <literal>-1</literal> (the default) disables passivation based on maximum
+ inactivity.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The total number of sessions in memory includes sessions replicated from other cluster nodes
+ that are not being accessed on this node. Take this into account when setting
+ <literal>max-active-sessions</literal>. The number of sessions replicated from other nodes
+ will also depend on whether <emphasis>buddy replication</emphasis> is enabled.
+ </para>
+
+ <para>
+ Say, for example, that you have an eight node cluster, and each node handles requests
+ from 100 users. With <emphasis>total replication</emphasis>, each node would store
+ 800 sessions in memory. With <emphasis>buddy replication</emphasis> enabled, and the
+ default <literal>numBuddies</literal> setting (<literal>1</literal>), each node will
+ store 200 sessions in memory.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="clustering-http-state-cacheconfig">
+
+ <title>Configuring the JBoss Cache instance used for session state replication</title>
+ <para>The container for a distributable web application makes use of JBoss Cache to
+ provide HTTP session replication services around the cluster. The container
+ integrates with the CacheManager service to obtain a reference to a JBoss Cache instance
+ (see <xref linkend="clustering-blocks-jbc-cachemanager"/>).</para>
+
+ <para>The name of the JBoss Cache configuration to use is controlled by the
+ <literal>cacheName</literal> element in the application's
+ <literal>jboss-web.xml</literal> (see <xref linkend="clustering-http-app"/>).
+ In most cases, though, this does not need to be set as the default values of
+ <literal>standard-session-cache</literal> and
+ <literal>field-granularity-session-cache</literal> (for applications
+ configured for FIELD granularity) are appropriate.</para>
+
+ <para>The JBoss Cache configurations in the <classname>CacheManager</classname> service expose
+ a number of options. See <xref linkend="jbosscache.chapt"/> and
+ the JBoss Cache documentation for a more complete discussion.
+ The <literal>standard-session-cache</literal> and
+ <literal>field-granularity-session-cache</literal> configurations are
+ already optimized for the web session replication use case, and most of the
+ settings should not be altered. Administrators may be interested in altering
+ the following settings:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">cacheMode</emphasis></para>
+ <para>
+ The default is <literal>REPL_ASYNC</literal>, which specifies that a session replication
+ message sent to the cluster does not wait for responses from other cluster nodes
+ confirming that the message has been received and processed. The alternative mode,
+ <literal>REPL_SYNC</literal>, offers a greater degree of confirmation that session state
+ has been received, but reduces performance significantly.
+ See <xref linkend="jbosscache-configuration-cachemode"/> for further details.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">enabled</emphasis> property in the <emphasis role="bold">buddyReplicationConfig</emphasis> section</para>
+ <para>Set to <literal>true</literal> to enable buddy replication. See <xref linkend="jbosscache-configuration-buddyrepl"/>.
+ Default is <literal>false</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">numBuddies</emphasis> property in the <emphasis role="bold">buddyReplicationConfig</emphasis> section</para>
+ <para>Set to a value greater than the default (<literal>1</literal>) to increase the number of backup nodes onto
+ which sessions are replicated. Only relevant if buddy replication is enabled. See <xref linkend="jbosscache-configuration-buddyrepl"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">buddyPoolName</emphasis> property in the <emphasis role="bold">buddyReplicationConfig</emphasis> section</para>
+ <para>A way to specify a preferred replication group when buddy replication is enabled.
+ JBoss Cache tries to pick a buddy who shares the same pool name (falling back to other
+ buddies if not available). Only relevant if buddy replication is enabled. See <xref linkend="jbosscache-configuration-buddyrepl"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">multiplexerStack</emphasis></para>
+ <para>Name of the JGroups protocol stack the cache should use. See <xref linkend="clustering-blocks-jgroups-channelfactory"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">clusterName</emphasis></para>
+ <para>Identifying name JGroups will use for this cache's channel. Only
+ change this if you create a new cache configuration, in which case this
+ property should have a different value from all other cache configurations.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>If you wish to use a completely new JBoss Cache configuration rather
+ than editing one of the existing ones, please see <xref linkend="jbosscache-custom-deployment-cachemgr"/>.</para>
+ </section>
+
+ </section>
+
<section id="clustering-http-field">
<title>Using FIELD level replication</title>
- <para>FIELD-level replication only replicates modified data fields inside objects stored in the session. Its use could potentially drastically reduce the data traffic between clustered nodes, and hence improve the performance of the whole cluster. To use FIELD-level replication, you have to first prepare (i.e., bytecode enhance) your Java class to allow the session cache to detect when fields in cached objects have been changed and need to be replicated.
+ <para>FIELD-level replication only replicates modified data fields inside objects stored in the session. It can reduce the data traffic between clustered nodes, and hence improve the performance of the whole cluster. To use FIELD-level replication, you must first prepare (that is, bytecode enhance) your Java class to allow the session cache to detect when fields in cached objects have been changed and need to be replicated.
</para>
<para>
- The first step in doing this is to identify the classes that need to be prepared. This is done via annotations. For example:
+ First, you need to identify the classes that you need to prepare. You can identify these classes by using annotations, like so:
</para>
<programlisting><![CDATA[
- at org.jboss.cache.aop.AopMarker
+@@org.jboss.cache.pojo.annotation.Replicable
public class Address
{
...
@@ -438,7 +746,7 @@
</programlisting>
<para>
-If you annotate a class with InstanceAopMarker instead, then all of its subclasses will be automatically annotated as well. Similarly, you can annotate an interface with InstanceofAopMarker and all of its implementing classes will be annotated. For example:
+If you annotate a class with <literal>@Replicable</literal>, then all of its subclasses will be automatically annotated as well. Similarly, you can annotate an interface with <literal>@Replicable</literal> and all of its implementing classes will be annotated. For example:
</para>
<programlisting><![CDATA[
@org.jboss.cache.aop.InstanceOfAopMarker
@@ -446,47 +754,31 @@
{
...
}
-then when you have a sub-class like
+
public class Student extends Person
{
...
}
]]></programlisting>
-<para>There will be no need to annotate <literal>Student</literal>. It will be annotated automatically because it is a sub-class of <literal>Person</literal>.
- Jboss Enterprise Application Platform 4.2 requires JDK 5 at runtime, but some users may still need to build their projects using JDK 1.4. In this case, annotating classes can be done via JDK 1.4 style annotations embedded in JavaDocs. For example:
+<para>There is no need to annotate <literal>Student</literal>. POJO Cache will recognize it as @Replicable because it is a sub-class of <literal>Person</literal>.</para>
+<para>JBoss AS 5 requires JDK 5 at runtime, but some users may still need to build their projects using JDK 1.4. In this case, annotating classes can be done via JDK 1.4 style annotations embedded in JavaDocs. For example:
</para>
<programlisting>
-/*
- * My usual comments here first.
- * @@org.jboss.web.tomcat.tc5.session.AopMarker
+<programlisting>/**
+ * Represents a street address.
+ * @@org.jboss.cache.pojo.annotation.Replicable
*/
-public class Address
+ public class Address
{
...
}
</programlisting>
-
-<para>The anologue for <literal>@InstanceAopMarker</literal> is:</para>
-
-<programlisting>
-/*
- *
- * @@org.jboss.web.tomcat.tc5.session.InstanceOfAopMarker
- */
-public class Person
-{
-...
-}
-</programlisting>
-
-
-
<para>
- Once you have annotated your classes, you will need to perform a pre-processing step to bytecode enhance your classes for use by TreeCacheAop. You need to use the JBoss AOP pre-compiler <literal>annotationc</literal> and post-compiler <literal>aopc</literal> to process the above source code before and after they are compiled by the Java compiler. The annotationc step is only need if the JDK 1.4 style annotations are used; if JDK 5 annotations are used it is not necessary. Here is an example on how to invoke those commands from command line.
+ Once you have annotated your classes, you will need to perform a pre-processing step to bytecode enhance your classes for use by POJO Cache. You need to use the JBoss AOP pre-compiler <literal>annotationc</literal> and post-compiler <literal>aopc</literal> to process the above source code before and after they are compiled by the Java compiler. The <literal>annotationc</literal> step is only need if the JDK 1.4 style annotations are used; if JDK 5 annotations are used it is not necessary. Here is an example of how to invoke those commands from command line.
</para>
<programlisting>
@@ -500,72 +792,37 @@
</para>
<note>
<para>
- You can see a complete example on how to build, deploy, and validate a FIELD-level replicated web application from this page: <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=Http_session_field_level_example"/>. The example bundles the pre- and post-compile tools so you do not need to download JBoss AOP separately.
+ You can see a complete example of how to build, deploy, and validate a FIELD-level replicated web application from this page: <ulink url="http://www.jboss.org/community/wiki/httpsessionfieldlevelexample"/>. The example bundles the pre- and post-compile tools so you do not need to download JBoss AOP separately.
</para>
</note>
- <para>When you deploy the web application into JBoss Enterprise Application Platform, make sure that the following configurations are
- correct:</para>
- <itemizedlist>
- <listitem>
- <para>In the server's <literal>deploy/jboss-web-cluster.sar/META-INF/jboss-service.xml</literal> file,
- the <literal>inactiveOnStartup</literal> and <literal>useMarshalling</literal> attributes
- must both be <literal>true</literal>.</para>
- </listitem>
- <listitem>
- <para>In the application's <literal>jboss-web.xml</literal> file, the
- <literal>replication-granularity</literal> attribute must be
- <literal>FIELD</literal>.</para>
- </listitem>
- </itemizedlist>
- <para>Finally, let's see an example on how to use FIELD-level replication on those data classes. Notice
- that there is no need to call <literal>session.setAttribute()</literal> after you make changes to
- the data object, and all changes to the fields are automatically replicated across the cluster.</para>
+ <para>Finally, let's see an example on how to use FIELD-level replication on those data classes. First, we see some servlet code that reads some data from the request parameters, creates a couple of objects and stores them in the session:</para>
+
<programlisting>
-// Do this only once. So this can be in init(), e.g.
-if(firstTime)
-{
- Person joe = new Person("Joe", 40);
- Person mary = new Person("Mary", 30);
- Address addr = new Address();
- addr.setZip(94086);
+Person husband = new Person(getHusbandName(request), getHusbandAge(request));
+Person wife = new Person(getWifeName(request), getWifeAge(request));
+Address addr = new Address();
+addr.setPostalCode(getPostalCode(request));
- joe.setAddress(addr);
- mary.setAddress(addr); // joe and mary share the same address!
+husband.setAddress(addr);
+wife.setAddress(addr); // husband and wife share the same address!
- session.setAttribute("joe", joe); // that's it.
- session.setAttribute("mary", mary); // that's it.
-}
+session.setAttribute("husband", husband); // that's it.
+session.setAttribute("wife", wife); // that's it.
+ </programlisting>
+
+ <para>Later, a different servlet could update the family's postal code:</para>
+ <programlisting>
+Person wife = (Person)session.getAttribute("wife");
+wife.getAddress().setPostalCode(getPostalCode(request)); // this will update and replicate the postal code.
+ </programlisting>
+
+ <para>Notice that in there is no need to call <literal>session.setAttribute()</literal> after you make changes to
+ the data object, and all changes to the fields are automatically replicated across the cluster.</para>
-Person mary = (Person)session.getAttribute("mary");
-mary.getAddress().setZip(95123); // this will update and replicate the zip code.
- </programlisting>
<para>Besides plain objects, you can also use regular Java collections of those objects as session
- attributes. JBoss cache automatically figures out how to handle those collections and replicate
+ attributes. POJO Cache automatically figures out how to handle those collections and replicate
field changes in their member objects.</para>
- </section>
- </section>
- <section id="clustering-http-monitor">
- <title>Monitoring session replication</title>
- <para> If you have deployed and accessed your application, go to the
- <literal>jboss.cache:service=TomcatClusteringCache</literal> MBean and invoke the
- <literal>printDetails</literal> operation. You should see output resembling the following.</para>
- <programlisting>/JSESSION
-/localhost
-
-/quote
-
-/FB04767C454BAB3B2E462A27CB571330
-VERSION: 6
-FB04767C454BAB3B2E462A27CB571330: org.jboss.invocation.MarshalledValue at 1f13a81c
-
-/AxCI8Ovt5VQTfNyYy9Bomw**
-VERSION: 4
-AxCI8Ovt5VQTfNyYy9Bomw**: org.jboss.invocation.MarshalledValue at e076e4c8</programlisting>
-
-<para>
- This output shows two separate web sessions, in one application named <emphasis>quote</emphasis>, that are being shared via JBossCache. This example uses a <literal>replication-granularity</literal> of <literal>session</literal>. Had <literal>ATTRIBUTE</literal> level replication been used, there would be additional entries showing each replicated session attribute. In either case, the replicated values are stored in an opaque <literal>MarshelledValue</literal> container. There aren't currently any tools that allow you to inspect the contents of the replicated session values. If you do not see any output, either the application was not correctly marked as <literal>distributable</literal> or you haven't accessed a part of application that places values in the HTTP session. The <literal>org.jboss.cache</literal> and <literal>org.jboss.web</literal> logging categories provide additional insight into session replication useful for debugging purposes.
-</para>
</section>
@@ -608,15 +865,14 @@
</listitem>
<listitem>
<para><emphasis role="bold">cacheConfig</emphasis> is the name of the
- cache configuration (see the Editing the CacheManager Configuration section <!-- <xref linkend="jbosscache-cachemanager"/>-->) to use
+ cache configuration (see <xref linkend="clustering-blocks-jbc-cachemanager"/>) to use
for the clustered SSO cache. Default is <literal>clustered-sso</literal>.</para>
</listitem>
<listitem>
<para><emphasis role="bold">treeCacheName</emphasis> is deprecated; use <literal>cacheConfig</literal>.
Specifies a JMX ObjectName of the JBoss Cache MBean to use
for the clustered SSO cache. If no cache can be located from the
- CacheManager service using the value of <literal>cacheConfig</literal>
- (see see the Editing the CacheManager Configuration section <!--<xref linkend="jbosscache-cachemanager"/>-->),
+ CacheManager service using the value of <literal>cacheConfig</literal>,
an attempt to locate an mbean registered in JMX under this ObjectName
will be made. Default value is <literal>jboss.cache:service=TomcatClusteringCache</literal>.</para>
</listitem>
More information about the jboss-cvs-commits
mailing list