[jboss-cvs] JBossAS SVN: r99193 - projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Jan 11 02:30:15 EST 2010
Author: laubai
Date: 2010-01-11 02:30:13 -0500 (Mon, 11 Jan 2010)
New Revision: 99193
Modified:
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/AOP.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Architecture.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Author_Group.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Example_Installation.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Info.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_Building_Blocks.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_Concepts.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_Deployment.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_HTTP.xml
Log:
Edited Clustering Guide HTTP.xml
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/AOP.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/AOP.xml 2010-01-11 06:50:04 UTC (rev 99192)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/AOP.xml 2010-01-11 07:30:13 UTC (rev 99193)
@@ -7,7 +7,7 @@
<para>
<indexterm><primary>JBoss AOP</primary><secondary>aspect oriented framework</secondary></indexterm>
<indexterm><primary>AOP</primary><see>JBoss AOP</see></indexterm>
- JBoss AOP is a 100% Pure Java Aspected Oriented Framework usable in any programming environment or tightly integrated with our application server. Aspects allow you to more easily modularize your code base when regular object oriented programming just doesn't fit the bill. It can provide a cleaner separation from application logic and system code. It provides a great way to expose integration points into your software. Combined with JDK 1.5 Annotations, it also is a great way to expand the Java language in a clean pluggable way rather than using annotations solely for code generation. </para>
+ JBoss AOP is a 100% Pure Java Aspect Oriented Framework usable in any programming environment or tightly integrated with our application server. Aspects allow you to more easily modularize your code base when regular object oriented programming just doesn't fit the bill. It can provide a cleaner separation from application logic and system code. It provides a great way to expose integration points into your software. Combined with JDK 1.5 Annotations, it also is a great way to expand the Java language in a clean pluggable way rather than using annotations solely for code generation. </para>
<para>JBoss AOP is not only a framework, but also a prepackaged set of aspects that are applied via annotations, pointcut expressions, or dynamically at runtime. Some of these include caching, asynchronous communication, transactions, security, remoting, and many many more. </para>
@@ -223,7 +223,7 @@
The <classname>AspectManager</classname> Service can be managed at runtime using the JMX console, which is found at <filename>http://localhost:8080/jmx-console</filename>. It is registered under the ObjectName <literal>jboss.aop:service=AspectManager</literal>. If you want to configure it on startup you need to edit some configuration files.
</para>
<para>
- In JBoss Enterprise Web Platform 5 the <classname>AspectManager</classname> Service is configured using a JBoss Microcontainer bean. The configuration file is <filename>jboss-as/server/xxx/conf/bootstrap/aop.xml</filename>. The <classname>AspectManager</classname> Service is deployed with the following XML:
+ In JBoss Enterprise Web Platform 5 the <classname>AspectManager</classname> Service is configured using a JBoss Microcontainer bean. The configuration file is <filename>jboss-as/server/$PROFILE/conf/bootstrap/aop.xml</filename>. The <classname>AspectManager</classname> Service is deployed with the following XML:
</para>
<programlisting><![CDATA[
<bean name="AspectManager" class="org.jboss.aop.deployers.AspectManagerJDK5">
@@ -340,7 +340,7 @@
<section>
<title>Improving Loadtime Performance in the JBoss Enterprise Web Platform Environment</title>
<para>
- The same rules apply to the JBoss Enterprise Web Platform for tuning loadtime weaving performance as standalone Java. Switches such as pruning, optimized, include and exclude are configured through the <filename>jboss-5.x.x.GA/server/xxx/conf/aop.xml</filename> file talked about earlier in this chapter.
+ The same rules apply to the JBoss Enterprise Web Platform for tuning loadtime weaving performance as standalone Java. Switches such as <varname>prune</varname>, <varname>optimized</varname>, <varname>include</varname> and <varname>exclude</varname> are configured through the <filename>jboss-as/server/$PROFILE/conf/bootstrap/aop.xml</filename> file talked about earlier in this chapter.
</para>
</section>
<section>
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml 2010-01-11 06:50:04 UTC (rev 99192)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml 2010-01-11 07:30:13 UTC (rev 99193)
@@ -8,12 +8,27 @@
<title>How to Use Alternative Databases</title>
<para>
<indexterm><primary>Configuration</primary><secondary>databases</secondary></indexterm>
-JBoss utilizes the Hypersonic database as its default database. While this is good for development and prototyping, you or your company will probably require another database to be used for production. This chapter covers configuring JBoss Enterprise Web Platform to use alternative databases. We cover the procedures for all officially supported databases on the JBoss Enterprise Web Platform. They include: MySQL 5.0, MySQL 5.1, PostgreSQL 8.2.4, PostgreSQL 8.3.5, Oracle 10g, Oracle 11g R2, Oracle 11g R2 RAC, DB2 9.7, Sybase ASE 15.0, and MS SQL 2005 and 2008.
+ JBoss utilizes the Hypersonic database as its default database. While this is good for
+ development and prototyping, you or your company will probably require another database
+ to be used for production. This chapter covers configuring JBoss Enterprise Web Platform
+ to use alternative databases. We cover the procedures for all officially supported
+ databases on the JBoss Enterprise Web Platform. They include: MySQL 5.0, MySQL 5.1,
+ PostgreSQL 8.2.4, PostgreSQL 8.3.5, Oracle 10g, Oracle 11g R2, Oracle 11g R2 RAC, DB2 9.7,
+ Sybase ASE 15.0, and MS SQL 2005 and 2008.
</para>
- <para>Please note that in this chapter, we explain how to use alternative databases to support all services in JBoss Enterprise Web Platform. This includes all the system level services such as EJB and JMS. For individual applications (e.g., WAR or EAR) deployed in JBoss Enterprise Web Platform, you can still use any backend database by setting up the appropriate data source connection. </para>
+ <para>
+ Please note that in this chapter, we explain how to use alternative databases to support all
+ services in JBoss Enterprise Web Platform. This includes all the system level services such
+ as EJB and JMS. For individual applications (e.g., WAR or EAR) deployed in
+ JBoss Enterprise Web Platform, you can still use any backend database by setting up the
+ appropriate data source connection. </para>
- <para>We assume that you have already installed the external database server, and have it running. You should create an empty database named <literal>jboss</literal>, accessible via the username / password pair <literal>jbossuser / jbosspass</literal>. The <literal>jboss</literal> database is used to store JBoss Enterprise Web Platform internal data — JBoss Enterprise Web Platform will automatically create tables and data in it.</para>
+ <para>We assume that you have already installed the external database server, and have it
+ running. You should create an empty database named <literal>jboss</literal>, accessible via
+ the username / password pair <literal>jbossuser / jbosspass</literal>. The
+ <literal>jboss</literal> database is used to store JBoss Enterprise Web Platform internal
+ data — JBoss Enterprise Web Platform will automatically create tables and data in it.</para>
</section>
@@ -413,7 +428,7 @@
<variablelist>
<varlistentry><term><literal>track-connection-by-tx</literal></term><listitem>
<para>
- Specifying a true value for this element makes the connection manager keep an <literal>xid</literal> to connection map and only return the connection to the pool when the transaction completes and all the connection handles are closed or disassociated (by the method calls returning). As a side effect, we never suspend and resume the <literal>xid</literal> on the connection's <classname>XAResource</classname>. This is the same connection tracking behavior used for local transactions.
+ Specifying a <literal>true</literal> value for this element makes the connection manager keep an <literal>xid</literal> to connection map and only return the connection to the pool when the transaction completes and all the connection handles are closed or disassociated (by the method calls returning). As a side effect, we never suspend and resume the <literal>xid</literal> on the connection's <classname>XAResource</classname>. This is the same connection tracking behavior used for local transactions.
</para>
<para>
The XA specification implies that any connection may be enrolled in any transaction using any <literal>xid</literal> for that transaction at any time from any thread (suspending other transactions if necessary). The original JCA implementation assumed this and aggressively delisted connections and returned them to the pool as soon as control left the EJB they were used in or handles were closed. Since some other transaction could be using the connection the next time work needed to be done on the original transaction, there was no way to get the original connection back. It turns out that most <classname>XADataSource</classname> driver vendors do not support this, and require that all work done under a particular <literal>xid</literal> go through the same connection.
@@ -843,6 +858,10 @@
<para>Changing the external datasource to <literal>DefaultDS</literal> is convenient. But if you have applications that assume the <literal>DefaultDS</literal> always points to the factory-default HSQL DB, that approach could break your application. Also, changing <literal>DefaultDS</literal> destination forces all JBoss services to use the external database. What if you want to use the external database only on some services?</para>
<para>A safer and more flexible way to hook up JBoss Enterprise Web Platform services with the external DataSource is to manually change the <literal>DefaultDS</literal> in all standard JBoss services to the DataSource JNDI name defined in your <filename>*-ds.xml</filename> file (e.g., the <literal>MySqlDS</literal> in <filename>mysql-ds.xml</filename> etc.). Below is a complete list of files that contain <literal>DefaultDS</literal>. You can update them all to use the external database on all JBoss services or update some of them to use different combination of DataSources for different services.</para>
+
+ <note>
+ <para>Not all files will be present in all server profiles.</para>
+ </note>
<itemizedlist>
<listitem><para><filename>$JBOSS_HOME/server/$PROFILE/conf/login-config.xml</filename>: This file is used in Java EE container managed security services.</para></listitem>
@@ -1078,7 +1097,7 @@
<term><varname><![CDATA[<transaction-isolation>]]></varname></term>
<listitem>
<para>
- The default transaction isolation of the connection (unspecified means use the default provided by the database):
+ The default transaction isolation of the connection. Leaving this unspecified means that the default provided by the database will be used. The options are:
</para>
<itemizedlist spacing="compact">
<listitem>
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Architecture.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Architecture.xml 2010-01-11 06:50:04 UTC (rev 99192)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Architecture.xml 2010-01-11 07:30:13 UTC (rev 99193)
@@ -53,7 +53,7 @@
The <classname>org.jboss.Main</classname> entry point in JBoss Enterprise Web Platform 5 loads an <classname>org.jboss.system.server.Server</classname> implementation. This is a JBoss Microcontainer.
</para>
<indexterm><primary>JBoss Enterprise Web Platform</primary><secondary>Server interface implementation</secondary></indexterm>
- <para>The default JBoss Enterprise Web Platform 5 <classname>org.jboss.system.server.Server implementation</classname> is <classname>org.jboss.bootstrap.microcontainer.ServerImpl</classname>. This implementation is an extension of the kernel basic bootstrap that boots the MC from the bootstrap beans declared in <filename><![CDATA[<jboss.server.config.url>/bootstrap.xml]]></filename> descriptors using a <classname>BasicXMLDeployer</classname>. In addition, the <classname>ServerImpl</classname> registers install callbacks for any beans that implement the <classname>org.jboss.bootstrap.spi.Bootstrap</classname> interface. The <filename>bootstrap/profile*.xml</filename> configurations include a <classname>ProfileServiceBootstrap</classname> bean that implements the <classname>Bootstrap</classname> interface.
+ <para>The default JBoss Enterprise Web Platform 5 <classname>org.jboss.system.server.Server</classname> implementation is <classname>org.jboss.bootstrap.microcontainer.ServerImpl</classname>. This implementation is an extension of the kernel basic bootstrap that boots the MC from the bootstrap beans declared in <filename><![CDATA[<jboss.server.config.url>/bootstrap.xml]]></filename> descriptors using a <classname>BasicXMLDeployer</classname>. In addition, the <classname>ServerImpl</classname> registers install callbacks for any beans that implement the <classname>org.jboss.bootstrap.spi.Bootstrap</classname> interface. The <filename>bootstrap/profile*.xml</filename> configurations include a <classname>ProfileServiceBootstrap</classname> bean that implements the <classname>Bootstrap</classname> interface.
</para>
<indexterm><primary>ProfileService</primary><secondary>bootstrap</secondary></indexterm>
<para>The <classname>org.jboss.system.server.profileservice.ProfileServiceBootstrap</classname> is an implementation of the <classname>org.jboss.bootstrap.spi.Bootstrap</classname> interface that loads the deployments associated with the current profile. The <literal>$PROFILE</literal> is the name of the server configuration profile being loaded and corresponds to the <code>server -c</code> command line argument. The default <literal>$PROFILE</literal> is <literal>default</literal>.</para>
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Author_Group.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Author_Group.xml 2010-01-11 06:50:04 UTC (rev 99192)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Author_Group.xml 2010-01-11 07:30:13 UTC (rev 99193)
@@ -16,4 +16,8 @@
<firstname>Isaac</firstname>
<surname>Rooskov</surname>
</editor>
+ <editor>
+ <firstname>Laura</firstname>
+ <surname>Bailey</surname>
+ </editor>
</authorgroup>
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Example_Installation.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Example_Installation.xml 2010-01-11 06:50:04 UTC (rev 99192)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Example_Installation.xml 2010-01-11 07:30:13 UTC (rev 99193)
@@ -35,4 +35,4 @@
[java] SpecificationVersion: $VERSION
[java] JBoss version is: $VERSION
</programlisting>
-</appendix>
\ No newline at end of file
+</appendix>
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Info.xml 2010-01-11 06:50:04 UTC (rev 99192)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Info.xml 2010-01-11 07:30:13 UTC (rev 99193)
@@ -7,7 +7,7 @@
<subtitle>for JBoss Enterprise Web Platform 5.0</subtitle>
<edition>1</edition>
<issuenum>1</issuenum>
- <pubsnumber>0.1</pubsnumber>
+ <pubsnumber>0.2</pubsnumber>
<productname>JBoss Enterprise Web Platform</productname>
<productnumber>5.0</productnumber>
<!-- <pubdate>, 2009</pubdate> -->
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide.xml 2010-01-11 06:50:04 UTC (rev 99192)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide.xml 2010-01-11 07:30:13 UTC (rev 99193)
@@ -5,8 +5,8 @@
<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Clustering_Guide_Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Clustering_Guide_JNDI.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-<xi:include href="Clustering_Guide_EJBs.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-<xi:include href="Clustering_Guide_Entity_EJBs.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<!--<xi:include href="Clustering_Guide_EJBs.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<xi:include href="Clustering_Guide_Entity_EJBs.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />-->
<xi:include href="Clustering_Guide_HTTP.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Clustering_Guide_JMS.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Clustering_Guide_JBoss_Cache_JGroups.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_Building_Blocks.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_Building_Blocks.xml 2010-01-11 06:50:04 UTC (rev 99192)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_Building_Blocks.xml 2010-01-11 07:30:13 UTC (rev 99193)
@@ -4,19 +4,32 @@
<chapter id="clustering-blocks.chapt">
<title>Clustering Building Blocks</title>
<para>The clustering features in JBoss Enterprise Web Platform are built on top of lower level
- libraries that provide much of the core functionality. <xref linkend="clustering-as-arch.fig"/>
- shows the main pieces:
+ libraries that provide much of the core functionality. <!--<xref linkend="clustering-as-arch.fig"/>
+ shows the main pieces:-->
</para>
+
+<!--replace with https://engineering.redhat.com/rt3/Ticket/Display.html?id=55884-->
+ <screen>
+JGroups
+ |-- JBoss Cache
+ | |-- HTTP Session
+ | |-- Hibernate
+ |
+ |-- HAPartition
+ |-- HA-JNDI
+ |-- HA Singleton
+ |-- Client Proxies
+ </screen>
- <figure id="clustering-as-arch.fig">
+ <!--<figure id="clustering-as-arch.fig">
<title>The JBoss Enterprise Web Platform clustering architecture</title>
<mediaobject>
- <imageobject><!--replace with https://engineering.redhat.com/rt3/Ticket/Display.html?id=55884-->
+ <imageobject>
<imagedata align="center" fileref="images/clustering-as-arch.png" />
</imageobject>
</mediaobject>
- </figure>
-
+ </figure>-->
+
<para><application>JGroups</application> is a toolkit for reliable
point-to-point and point-to-multipoint communication. JGroups is used for
all clustering-related communications between nodes in a JBoss Enterprise Web Platform cluster.
@@ -49,8 +62,14 @@
<section id="clustering-blocks-jgroups">
<title>Group Communication with JGroups</title>
- <para>
- JGroups provides the underlying group communication support for JBoss Enterprise Web Platform clusters. Services deployed on JBoss Enterprise Web Platform which need group communication with their peers will obtain a JGroups <classname>Channel</classname> and use it to communicate. The <classname>Channel</classname> handles such tasks as managing which nodes are members of the group, detecting node failures, ensuring lossless, first-in-first-out delivery of messages to all group members, and providing flow control to ensure fast message senders cannot overwhelm slow message receivers.
+ <para>
+ JGroups provides the underlying group communication support for
+ JBoss Enterprise Web Platform clusters. Services deployed on JBoss Enterprise Web Platform
+ which need group communication with their peers will obtain a JGroups
+ <classname>Channel</classname> and use it to communicate. The <classname>Channel</classname>
+ handles such tasks as managing which nodes are members of the group, detecting node failures,
+ ensuring lossless, first-in-first-out delivery of messages to all group members, and providing
+ flow control to ensure fast message senders cannot overwhelm slow message receivers.
</para>
<para>
@@ -68,7 +87,7 @@
</para>
<para>
- The <classname>ChannelFactory</classname> service is deployed in the <filename>server/$PROFILE/deploy/cluster/jgroups-channelfactory.sar</filename>. On startup the ChannelFactory service parses the <filename>server/$PROFILE/deploy/cluster/jgroups-channelfactory.sar/META-INF/jgroups-channelfactory-stacks.xml</filename> file, which includes various standard JGroups configurations identified by name (for example, UDP or TCP). Services that require a channel access the channel factory and request a channel with a particular named configuration.
+ The <classname>ChannelFactory</classname> service is deployed in the <filename>server/production/deploy/cluster/jgroups-channelfactory.sar</filename>. On startup the ChannelFactory service parses the <filename>server/production/deploy/cluster/jgroups-channelfactory.sar/META-INF/jgroups-channelfactory-stacks.xml</filename> file, which includes various standard JGroups configurations identified by name (for example, UDP or TCP). Services that require a channel access the channel factory and request a channel with a particular named configuration.
</para>
<note>
<para>
@@ -79,7 +98,7 @@
<section id="clustering-blocks-jgroups-stdconfigs">
<title>Standard Protocol Stack Configurations</title>
<para>
- The standard protocol stack configurations that ship with Enterprise Web Platform 5 are described below. Note that not all of these are actually used; many are included as a convenience to users who may wish to alter the default server configuration profile. The configurations used in a stock Enterprise Web Platform 5 <literal>all</literal> configuration are <literal>udp</literal>, <literal>jbm-control</literal> and <literal>jbm-data</literal>, with all clustering services other than JBoss Messaging using <literal>udp</literal>.
+ The standard protocol stack configurations that ship with Enterprise Web Platform 5 are described below. Note that not all of these are actually used; many are included as a convenience to users who may wish to alter the default server configuration profile. The configurations used in a pristine Enterprise Web Platform 5 <literal>all</literal> configuration are <literal>udp</literal>, <literal>jbm-control</literal> and <literal>jbm-data</literal>, with all clustering services other than JBoss Messaging using <literal>udp</literal>.
</para>
<para>
You can add a new stack configuration by adding a new <literal>stack</literal> element to the <filename>server/all/deploy/cluster/jgroups-channelfactory.sar/META-INF/jgroups-channelfactory-stacks.xml</filename> file. You can alter the behavior of an existing configuration by editing this file. Before doing this though, see the other standard configurations shipped with the Enterprise Web Platform to determine whether they will meet your requirements.
@@ -131,7 +150,7 @@
</para>
</listitem>
</varlistentry>
- <varlistentry>
+ <!--<varlistentry>
<term><literal>jbm-control</literal></term>
<listitem>
<para>
@@ -146,7 +165,7 @@
TCP-based stack optimized for the JBoss Messaging Data Channel.
</para>
</listitem>
- </varlistentry>
+ </varlistentry>-->
</variablelist>
</section>
</section>
@@ -211,7 +230,7 @@
standard clustered services in a JBoss Enterprise Web Platform cluster, including:
<itemizedlist>
<listitem><para>replication of clustered web application sessions</para></listitem>
- <listitem><para>replication of clustered EJB3 Stateful Session beans</para></listitem>
+<!-- <listitem><para>replication of clustered EJB3 Stateful Session beans</para></listitem>-->
<listitem><para>clustered caching of JPA and Hibernate entities</para></listitem>
<listitem><para>clustered Single Sign-On</para></listitem>
<listitem><para>the HA-JNDI replicated tree</para></listitem>
@@ -234,10 +253,9 @@
directory, which had a number of disadvantages:
</para>
<itemizedlist>
- <listitem><para>Caches that end user applications
- didn't need were deployed anyway, with each creating an expensive
- JGroups channel. For example, even if there were no clustered EJB3
- SFSBs, a cache to store them was started.</para></listitem>
+ <listitem><para>Different cache types were created regardless of whether they
+ were required by a particular application, and used a resource-expensive
+ JGroups channel in the process.</para></listitem>
<listitem><para>Caches are internal details of the services that
use them. They shouldn't be first-class deployments.</para></listitem>
<listitem><para>Services would find their cache via JMX lookups. This
@@ -245,8 +263,8 @@
</itemizedlist>
<para>In JBoss Enterprise Web Platform 5, the scattered cache deployments have been replaced
- with a new <classname>CacheManager</classname> service,
- deployed via the <filename>$JBOSS_HOME/server/$PROFILE/deploy/cluster/jboss-cache-manager.sar</filename>.
+ with a new <classname>CacheManager</classname> service, deployed via the
+ <filename>$JBOSS_HOME/server/$PROFILE/deploy/cluster/jboss-cache-manager.sar</filename>.
The <classname>CacheManager</classname> is a factory and registry for JBoss Cache instances.
It is configured with a set of named JBoss Cache configurations.
Services that require a cache request it by name from the cache manager.
@@ -262,8 +280,8 @@
<title>Standard Cache Configurations</title>
<para>The following standard JBoss Cache configurations ship with JBoss Enterprise Web Platform 5.
You can add others to suit your needs, or edit these configurations
- to adjust cache behavior. Additions or changes are done by editing
- the <filename>deploy/cluster/jboss-cache-manager.sar/META-INF/jboss-cache-manager-jboss-beans.xml</filename>
+ to adjust cache behavior. Additions or changes are done by editing the
+ <filename>deploy/cluster/jboss-cache-manager.sar/META-INF/jboss-cache-manager-jboss-beans.xml</filename>
file (see <xref linkend="jbosscache-custom-deployment-cachemgr"/>
for details). Note however that these configurations are specifically
optimized for their intended use, and except as specifically noted
@@ -288,14 +306,14 @@
</para>
</listitem>
</varlistentry>
- <varlistentry>
+ <!--<varlistentry>
<term><literal>sfsb-cache</literal></term>
<listitem>
<para>
Standard cache used for EJB3 SFSB caching.
</para>
</listitem>
- </varlistentry>
+ </varlistentry>-->
<varlistentry>
<term><literal>ha-partition</literal></term>
<listitem>
@@ -460,8 +478,8 @@
allowing caches registered under one name to be looked up under a
different name. Aliasing is useful for sharing caches between
services whose configuration may specify different cache configuration
- names. It's also useful for supporting legacy EJB3 application
- configurations.</para>
+ names. <!--It's also useful for supporting legacy EJB3 application
+ configurations.--></para>
<para>Aliases can be configured by editing the <literal>CacheManager</literal>
bean in the <filename>jboss-cache-manager-jboss-beans.xml</filename>
file. The following redacted configuration shows the standard aliases in
@@ -481,22 +499,27 @@
<key>clustered-sso</key>
<value>ha-partition</value>
</entry>
- <!-- Handle the legacy name for the EJB3 SFSB cache -->
+ </map>
+ </property>
+
+ . . .
+
+</bean>]]></programlisting>
+
+<!-- Removed from after </entry> after ha-partition:
+ # Handle the legacy name for the EJB3 SFSB cache
<entry>
<key>jboss.cache:service=EJB3SFSBClusteredCache</key>
<value>sfsb-cache</value>
</entry>
- <!-- Handle the legacy name for the EJB3 Entity cache -->
+ # Handle the legacy name for the EJB3 Entity cache
<entry>
<key>jboss.cache:service=EJB3EntityTreeCache</key>
<value>mvcc-shared</value>
</entry>
- </map>
- </property>
-
- . . .
-
-</bean>]]></programlisting>
+-->
+
+
</section>
</section>
</section>
@@ -515,13 +538,15 @@
interested listeners when the cluster membership changes or the
clustered service registry changes. <classname>HAPartition</classname> forms the core of many
of the clustering services we'll be discussing in the rest of this
- guide, including smart client-side clustered proxies, EJB2 stateful session bean
- replication and entity cache management, farming, HA-JNDI and HA singletons.
+ guide, including smart client-side clustered proxies,<!-- EJB2 stateful session bean
+ replication and entity cache management,--> farming, HA-JNDI and HA singletons.
Custom services can also make use of <classname>HAPartition</classname>.
</para>
- <para>The following snippet shows the <classname>HAPartition</classname> service definition packaged with the standard JBoss Enterprise Web Platform distribution.
- This configuration can be found in the <filename>server/$PROFILE/deploy/cluster/hapartition-jboss-beans.xml</filename> file.
+ <para>The following snippet shows the <classname>HAPartition</classname> service
+ definition packaged with the standard JBoss Enterprise Web Platform distribution.
+ This configuration can be found in the
+ <filename>server/$PROFILE/deploy/cluster/hapartition-jboss-beans.xml</filename> file.
</para>
<programlisting><![CDATA[
<bean name="HAPartitionCacheHandler" class="org.jboss.ha.framework.server.HAPartitionCacheHandlerImpl">
@@ -682,8 +707,8 @@
<term><literal>Clustered Smart Proxies</literal></term>
<listitem>
<para>Here the keys are the names of the various services that need a
- clustered smart proxy (see <xref linkend="clustering-concepts-arch-proxy"/>,
- for example, the name of a clustered EJB. The value object each node stores in
+ clustered smart proxy (see <xref linkend="clustering-concepts-arch-proxy"/>.
+ <!--for example, the name of a clustered EJB.--> The value object each node stores in
the DRM is known as a <emphasis>target</emphasis>. This is used by the smart proxy's transport
layer to contact the node (for example, an RMI stub, an HTTP URL or a JBoss Remoting
<classname>InvokerLocator</classname>). The factory that builds clustered smart
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_Concepts.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_Concepts.xml 2010-01-11 06:50:04 UTC (rev 99192)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_Concepts.xml 2010-01-11 07:30:13 UTC (rev 99193)
@@ -34,8 +34,8 @@
of the Enterprise Web Platform 5 <literal>all</literal> configuration,
two different services create a total of four different channels —
JBoss Messaging creates two, and a core general purpose clustering service
- known as <classname>HAPartition</classname> creates two more. If you deploy clustered web applications,
- clustered EJB3 SFSBs or a clustered JPA/Hibernate entity cache, additional
+ known as <classname>HAPartition</classname> creates two more. If you deploy clustered web applications
+ <!--clustered EJB3 SFSBs--> or a clustered JPA/Hibernate entity cache, additional
channels will be created. The channels the Enterprise Web Platform connects
can be divided into three broad categories: a general purpose channel used
by the <classname>HAPartition</classname> service, channels created by JBoss Cache for special
@@ -44,7 +44,7 @@
<para>
So, if you go to two Enterprise Web Platform 5 instances and execute <code>run -c all</code>,
the channels will discover each other and you'll have a conceptual
- <literal>cluster</literal>. It's easy to think of this as a two node
+ <literal>cluster</literal>. It is easy to think of this as a two node
cluster, but it's important to understand that you really have multiple channels,
and hence multiple two node clusters.
</para>
@@ -54,7 +54,7 @@
server instances divided into three sets, with the third set only
having one node. This sort of topology can be set up simply by configuring
the Enterprise Web Platform instances such that within a set of nodes meant to form a cluster the
- <classname>Channel</classname> configurations and names match while they differ from any other channel configurations and names match while they differ from any other channels on the same network. The Enterprise Web Platform tries to make this as easy as possible, such that servers that are meant to cluster only need to have the same values passed on the command line to the <code>-g</code> (partition name) and <code>-u</code> (multicast address) startup switches. Different calues should be chosen for each set of servers. <xref linkend="jgroups-configuration"/> and <xref linkend="clustering-jgroups-isolation"/> cover in detail how to configure the Enterprise Web Platform such that desired peers find each other and unwanted peers do not.</para>
+ <classname>Channel</classname> configurations and names match while they differ from any other channel configurations and names match while they differ from any other channels on the same network. The Enterprise Web Platform tries to make this as easy as possible, such that servers that are meant to cluster only need to have the same values passed on the command line to the <code>-g</code> (partition name) and <code>-u</code> (multicast address) startup switches. Different values should be chosen for each set of servers. <xref linkend="jgroups-configuration"/> and <xref linkend="clustering-jgroups-isolation"/> cover in detail how to configure the Enterprise Web Platform such that desired peers find each other and unwanted peers do not.</para>
<figure id="clustering-Partition.fig">
<title>Clusters and server nodes</title>
<mediaobject>
@@ -84,7 +84,7 @@
<title>Client-side interceptor architecture</title>
<para>
Most remote services provided by the JBoss Enterprise Web Platform, including
- JNDI, EJB, JMS, RMI and JBoss Remoting, require the client to obtain
+ JNDI, <!--EJB,-->JMS, RMI and JBoss Remoting, require the client to obtain
(that is, to look up and download) a remote proxy object. The proxy object
is generated by the server and it implements the business interface of
the service. The client then makes local method calls against the proxy
@@ -169,14 +169,14 @@
<section id="clustering-concepts-balancepolicy-30">
<title>Client-side interceptor architecture</title>
<para>
- In JBoss Enterprise Web Platform 5, the following load balancing options are available when the client-side interceptor architecture is used. The client-side stub maintains a list of all nodes providing the target service; the job of the load balance policy is to pick a node from this list for each request. Each policy has two implementation classes, one meant for use by legacy services like EJB2 that use the legacy detached invoker architecture, and the other meant for services like EJB3 that use AOP-based invocations.
+ In JBoss Enterprise Web Platform 5, the following load balancing options are available when the client-side interceptor architecture is used. The client-side stub maintains a list of all nodes providing the target service; the job of the load balance policy is to pick a node from this list for each request. Each policy has two implementation classes, one meant for use by legacy services <!--like EJB2--> that use the legacy detached invoker architecture, and the other meant for services <!--like EJB3--> that use AOP-based invocations.
</para>
<variablelist>
<varlistentry>
<term>Round-Robin</term>
<listitem>
<para>
- Each call is dispatched to a new node, proceeding sequentially through the list of nodes. The first target node is randomly selected from the list. Implemented by <classname>org.jboss.ha.framework.interfaces.RoundRobin</classname> (legacy) and <classname>org.jboss.ha.client.loadbalance.RoundRobin</classname> (EJB3).
+ Each call is dispatched to a new node, proceeding sequentially through the list of nodes. The first target node is randomly selected from the list. Implemented by <classname>org.jboss.ha.framework.interfaces.RoundRobin</classname> (legacy) and <classname>org.jboss.ha.client.loadbalance.RoundRobin</classname> (AOP).
</para>
</listitem>
</varlistentry>
@@ -184,7 +184,7 @@
<term>Random-Robin</term>
<listitem>
<para>
- For each call the target node is randomly selected from the list. Implemented by <classname>org.jboss.ha.framework.interfaces.RandomRobin </classname> (legacy) and <classname>org.jboss.ha.client.loadbalance.RandomRobin </classname> (EJB3).
+ For each call the target node is randomly selected from the list. Implemented by <classname>org.jboss.ha.framework.interfaces.RandomRobin </classname> (legacy) and <classname>org.jboss.ha.client.loadbalance.RandomRobin </classname> (AOP).
</para>
</listitem>
</varlistentry>
@@ -192,7 +192,7 @@
<term>First Available</term>
<listitem>
<para>
- One of the available target nodes is elected as the main target and is thereafter used for every call. This elected member is randomly chosen from the list of members in the cluster. When the list of target nodes changes (because a node starts or dies), the policy will choose a new target node unless the currently elected node is still available. Each client-side proxy elects its own target node independently of the other proxies, so if a particular client downloads two proxies for the same target service (for example, an EJB), each proxy will independently pick its target. This is an example of a policy that provides <emphasis>session affinity</emphasis> or <emphasis>sticky sessions</emphasis>, since the target node does not change once established. Implemented by <classname>org.jboss.ha.framework.interfaces.FirstAvailable</classname> (legacy) and <classname>org.jboss.ha.client.loadbalance.aop.FirstAvailable</classname> (EJB3).
+ One of the available target nodes is elected as the main target and is thereafter used for every call. This elected member is randomly chosen from the list of members in the cluster. When the list of target nodes changes (because a node starts or dies), the policy will choose a new target node unless the currently elected node is still available. Each client-side proxy elects its own target node independently of the other proxies, so if a particular client downloads two proxies for the same target service, each proxy will independently pick its target. This is an example of a policy that provides <emphasis>session affinity</emphasis> or <emphasis>sticky sessions</emphasis>, since the target node does not change once established. Implemented by <classname>org.jboss.ha.framework.interfaces.FirstAvailable</classname> (legacy) and <classname>org.jboss.ha.client.loadbalance.aop.FirstAvailable</classname> (AOP).
</para>
</listitem>
</varlistentry>
@@ -200,7 +200,7 @@
<term>First Available Identical All Proxies</term>
<listitem>
<para>
- Has the same behavior as the "First Available" policy but the elected target node is shared by all proxies in the same client-side VM that are associated with the same target service. So if a particular client downloads two proxies for the same target service (for example, an EJB), each proxy will use the same target. Implemented by <classname>org.jboss.ha.framework.interfaces.FirstAvailableIdenticalAllProxies</classname> (legacy) and <classname>org.jboss.ha.client.loadbalance.aop.FirstAvailableIdenticalAllProxies</classname> (EJB3).
+ Has the same behavior as the "First Available" policy but the elected target node is shared by all proxies in the same client-side VM that are associated with the same target service. So if a particular client downloads two proxies for the same target service, each proxy will use the same target. Implemented by <classname>org.jboss.ha.framework.interfaces.FirstAvailableIdenticalAllProxies</classname> (legacy) and <classname>org.jboss.ha.client.loadbalance.aop.FirstAvailableIdenticalAllProxies</classname> (AOP).
</para>
</listitem>
</varlistentry>
@@ -213,7 +213,7 @@
<section><title>External load balancer architecture</title>
<para>
- New in JBoss Enterprise Web Platform 5 are a set of <literal>TransactionSticky</literal> load balance policies. These extend the standard policies above to add behavior such that all invocations that occur within the scope of a transaction are routed to the same node (if that node still exists). These are based on the legacy detached invoker architecture, so they are not available for AOP-based services like EJB3.
+ New in JBoss Enterprise Web Platform 5 are a set of <literal>TransactionSticky</literal> load balance policies. These extend the standard policies above to add behavior such that all invocations that occur within the scope of a transaction are routed to the same node (if that node still exists). These are based on the legacy detached invoker architecture, so they are not available for AOP-based services.
</para>
<variablelist>
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_Deployment.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_Deployment.xml 2010-01-11 06:50:04 UTC (rev 99192)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_Deployment.xml 2010-01-11 07:30:13 UTC (rev 99193)
@@ -56,7 +56,7 @@
The simplest and most commonly used strategy for deploying an HA
singleton is to take an ordinary deployment (WAR, EAR, JAR,
whatever you would normally put in <filename>deploy</filename>) and deploy it in the
- <filename>$JBOSS_HOME/server/$PROFILE/deploy-hasingleton</filename>
+ <filename>$JBOSS_HOME/server/production/deploy-hasingleton</filename>
directory instead of in <filename>deploy</filename>. The
<filename>deploy-hasingleton</filename> directory does not lie under
<filename>deploy</filename> or <filename>farm</filename> directories,
@@ -259,7 +259,7 @@
but not their destruction, which happens only when the <literal>BarrierController</literal>
is itself destroyed and undeployed. Thus using the <literal>Barrier</literal> to control services
that need to be <emphasis>destroyed</emphasis> as part of their normal <emphasis>undeploy</emphasis>
- operation (like, for example, an <classname>EJBContainer</classname>) will not have the desired effect.
+ operation will not have the desired effect.
</para>
</note>
</section>
@@ -379,7 +379,7 @@
<para>
The easiest way to deploy an application into the cluster is to use the farming service.
Using the farming service, you can deploy an application (EAR, WAR, or SAR; either an
- archive file or in exploded form) to the <classname>$PROFILE/farm/</classname> directory
+ archive file or in exploded form) to the <classname>production/farm/</classname> directory
of any cluster member and the application will be automatically duplicated across all
nodes in the same cluster. If a node joins the cluster later, it will pull in all farm
deployed applications in the cluster and deploy them locally at start-up time.
@@ -444,8 +444,7 @@
<para>
Indicates whether this handler allows a node to push content changes to
the cluster. A value of <literal>true</literal> is equivalent to setting
- <varname>synchronizationPolicy</varname> to
- <literal>org.jboss.system.server.profileservice.repository.clustered.sync.ImmutableSynchronizationPolicy</literal>.
+ <varname>synchronizationPolicy</varname> to <literal>org.jboss.system.server.profileservice.repository.clustered.sync.ImmutableSynchronizationPolicy</literal>.
</para>
</listitem>
</varlistentry>
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_HTTP.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_HTTP.xml 2010-01-11 06:50:04 UTC (rev 99192)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_HTTP.xml 2010-01-11 07:30:13 UTC (rev 99193)
@@ -52,29 +52,41 @@
<section id="clustering-http-modjk">
<title>Configuring load balancing using Apache and mod_jk</title>
- <para>Apache is a well-known web server which can be extended by plugging in modules. One of these modules, mod_jk has been specifically designed to allow the forwarding of requests from Apache to a Servlet container. Furthermore, it is also able to load-balance HTTP calls to a set of Servlet containers while maintaining sticky sessions, which is what is most interesting for us in this section.</para>
+ <para>Apache is a well-known web server which can be extended by plugging
+ in modules. One of these modules, <application>mod_jk</application> has been
+ specifically designed to allow the forwarding of requests from Apache to a
+ Servlet container. Furthermore, it is also able to load-balance HTTP calls
+ to a set of Servlet containers while maintaining sticky sessions, which is
+ what is most interesting for us in this section.</para>
<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 <ulink url="http://httpd.apache.org/">http://httpd.apache.org/</ulink>. Its installation is pretty
- straightforward and requires no specific configuration. As several versions of Apache exist, we
- advise you to use the latest stable 2.2.x version. We will assume, 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 the use of mod_jk 1.2.x, as both earlier versions of mod_jk, and mod_jk2, are deprecated, unsupported and no further
- development is going on in the community. The mod_jk 1.2.x binary can be downloaded from <ulink url="http://www.apache.org/dist/jakarta/tomcat-connectors/jk/binaries/">http://www.apache.org/dist/jakarta/tomcat-connectors/jk/binaries/</ulink>. Rename the
- downloaded file to <literal>mod_jk.so</literal> and copy it under
- <literal>APACHE_HOME/modules/</literal>.</para>
+ <para>First of all, make sure that you have Apache installed. You can
+ download Apache directly from the Apache web site at
+ <ulink url="http://httpd.apache.org/">http://httpd.apache.org/</ulink>.
+ Its installation is straightforward and requires no specific configuration.
+ We advise you to use the latest stable version of Apache, which is version
+ 2.2.x. We will assume, for the next sections, that you have installed
+ Apache in the <filename>$APACHE_HOME</filename> directory.</para>
+
+ <para>Next, download <application>mod_jk</application> binaries. Several
+ versions of mod_jk exist as well. We strongly advise the use of mod_jk 1.2.x,
+ as both earlier versions of mod_jk, and mod_jk2, are deprecated, unsupported
+ and no further development is going on in the community. The mod_jk 1.2.x
+ binary can be downloaded from <ulink url="http://www.apache.org/dist/jakarta/tomcat-connectors/jk/binaries/">http://www.apache.org/dist/jakarta/tomcat-connectors/jk/binaries/</ulink>.
+ Rename the downloaded file to <literal>mod_jk.so</literal> and copy it under
+ <filename>$APACHE_HOME/modules/</filename>.</para>
</section>
<section>
<title>Configure Apache to load mod_jk</title>
- <para>Modify APACHE_HOME/conf/httpd.conf and add a single line at the end of the file:</para>
+ <para>Modify <filename>$APACHE_HOME/conf/httpd.conf</filename> and add a single
+ line at the end of the file:</para>
<programlisting>
# Include mod_jk's specific configuration file
Include conf/mod-jk.conf
</programlisting>
- <para>Next, create a new file named <literal>APACHE_HOME/conf/mod-jk.conf</literal>:</para>
+ <para>Next, create a new file named <filename>$APACHE_HOME/conf/mod-jk.conf</filename>:</para>
<programlisting>
# Load mod_jk module
# Specify the filename of the mod_jk lib
@@ -124,25 +136,28 @@
<para>Please note that two settings are very important:</para>
<itemizedlist>
<listitem>
- <para>The <literal>LoadModule</literal> directive must reference the mod_jk library you have
- downloaded in the previous section. You must indicate the exact same name with the "modules"
- file path prefix.</para>
+ <para>The <literal>LoadModule</literal> directive must reference the
+ mod_jk library you downloaded and placed in
+ <filename>$APACHE_HOME/modules/</filename>. You must indicate the
+ same name, including the <literal>modules</literal> file path prefix.</para>
</listitem>
<listitem>
- <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 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>
+ <para>The <literal>JkMount</literal> directive tells Apache which URLs it
+ should forward to the <application>mod_jk</application> module (and, in
+ turn, to the Servlet containers). In the above file, all requests with URL
+ path <filename>/application/*</filename> are sent to the mod_jk load-balancer.
+ This way, you can configure Apache to serve static contents (or PHP contents)
+ directly and only use the load balancer for Java applications. If you only
+ use <application>mod_jk</application> as a load balancer, you can also forward all URLs (that is, <filename>/*</filename>) to mod_jk.</para>
</listitem>
</itemizedlist>
- <para>In addition to the <literal>JkMount</literal> directive, you can also use the
- <literal>JkMountFile</literal> directive to specify a mount points configuration file, which
- contains multiple Tomcat forwarding URL mappings. You just need to create a
- <literal>uriworkermap.properties</literal> file in the <literal>APACHE_HOME/conf</literal>
- directory. The format of the file is <literal>/url=worker_name</literal>. To get things started,
- paste the following example into the file you created:</para>
+ <para>In addition to the <literal>JkMount</literal> directive, you can also use
+ the <literal>JkMountFile</literal> directive to specify a mount points
+ configuration file, which contains multiple Tomcat forwarding URL mappings.
+ You just need to create a <literal>uriworkermap.properties</literal> file in the
+ <filename>$APACHE_HOME/conf</filename> directory. The format of the file is
+ <literal>/url=worker_name</literal>. To get things started, paste the following
+ example code into the file you created:</para>
<programlisting>
# Simple worker configuration file
@@ -152,17 +167,21 @@
/web-console=loadbalancer
/web-console/*=loadbalancer
</programlisting>
- <para>This will configure mod_jk to forward requests to <literal>/jmx-console</literal> and
- <literal>/web-console</literal> to Tomcat.</para>
- <para>You will most probably not change the other settings in <literal>mod_jk.conf</literal>. They are
- used to tell mod_jk where to put its logging file, which logging level to use and so on.</para>
+ <para>This will configure <application>mod_jk</application> to forward requests
+ made to <literal>/jmx-console</literal> and <literal>/web-console</literal>
+ to Tomcat.</para>
+ <para>You will most probably not change the other settings in
+ <filename>mod_jk.conf</filename>. They are used to tell mod_jk where to put its
+ logging file, which logging level to use and so on.</para>
</section>
<section id="clustering-http-nodes">
<title>Configure worker nodes in mod_jk</title>
- <para>Next, you need to configure mod_jk workers file <literal>conf/workers.properties</literal>. This
- file specifies where the different Servlet containers are located and how calls should be
- load-balanced across them. The configuration file contains one section for each target servlet
- container and one global section. For a two nodes setup, the file could look like this:</para>
+ <para>Next, you need to configure the mod_jk file
+ <filename>conf/workers.properties</filename> file. This file specifies where the
+ different <classname>Servlet</classname> containers are located and how calls
+ should be load-balanced across them. The configuration file contains one section
+ for each target servlet container and one global section. For a two node setup,
+ the file might look like this:</para>
<!-- The local worker comment is from here: http://jira.jboss.com/jira/browse/JBDOCS-102 -->
<programlisting>
# Define list of workers that will be used
@@ -194,50 +213,67 @@
# Status worker for managing load balancer
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 (that is, JBoss Enterprise Web Platform instances) node1 and node2 listening on port
- 8009.</para>
- <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>
+ <para>The above file configures mod_jk to perform weighted round-robin
+ load balancing with sticky sessions between two servlet containers
+ (that is, JBoss Enterprise Web Platform instances) <classname>node1</classname>
+ and <classname>node2</classname> listening on port <literal>8009</literal>.</para>
+ <para>In the <filename>workers.properties</filename> 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>
-
- <para>The <literal>lbfactor</literal> attribute is the load-balancing factor for this specific worker.
- It is used to define the priority (or weight) a node should have over other nodes. The higher this number is for a given worker relative to the other workers, the more HTTP requests the worker will receive. This setting can be used to differentiate servers with different processing power.</para>
- <para>The <literal>cachesize</literal> attribute defines the size of the thread pools associated to the
- Servlet container (i.e. the number of concurrent requests it will forward to the Servlet container).
- Make sure this number does not outnumber the number of threads configured on the AJP13 connector of
- the Servlet container. Please review
- <ulink url="http://tomcat.apache.org/connectors-doc/reference/workers.html">>http://tomcat.apache.org/connectors-doc/reference/workers.html</ulink> for
- comments on <literal>cachesize</literal> for Apache 1.3.x.</para>
- <para>The last part of the <literal>conf/workers.properties</literal> file defines the loadbalancer
- worker. The only thing you must change is the
- <literal>worker.loadbalancer.balanced_workers</literal> line: it must list all workers previously
- defined in the same file. Load-balancing will happen over these workers.</para>
- <para>The <literal>sticky_session</literal> property specifies the cluster behavior for HTTP sessions.
- If you specify <literal>worker.loadbalancer.sticky_session=0</literal>, each request will be load
- balanced between node1 and node2; i.e., different requests for the same session will go to different servers. But when a user opens a session on one server, it is always necessary to always forward this user's requests to the same server, as long as that server is available. This is called a "sticky session", as the client is always using the same server he reached on his first request. To enable session stickiness, you need to set
- <literal>worker.loadbalancer.sticky_session</literal> to 1.</para>
+ <para>The <varname>lbfactor</varname> attribute is the load-balancing factor for
+ this specific worker. It is used to define the priority (or weight) a node should
+ have over other nodes. The higher this number is for a given worker relative to
+ the other workers, the more HTTP requests the worker will receive. This setting
+ can be used to differentiate servers with different processing power.</para>
+
+ <para>The <varname>cachesize</varname> attribute defines the size of the thread
+ pools associated to the servlet container (that is, the number of concurrent requests
+ it will forward to the Servlet container). Make sure this number is not greater than
+ the number of threads configured on the AJP13 connector of the Servlet container.
+ See <ulink url="http://tomcat.apache.org/connectors-doc/reference/workers.html">>http://tomcat.apache.org/connectors-doc/reference/workers.html</ulink> for comments on
+ <varname>cachesize</varname> for Apache 1.3.x.</para>
+
+ <para>The last part of the <filename>conf/workers.properties</filename> file defines
+ the load balancer worker. The only thing you must change is the
+ <varname>worker.loadbalancer.balanced_workers</varname> line: it must list all workers
+ previously defined in the same file. Load balancing will happen over these workers.</para>
+
+ <para>The <varname>sticky_session</varname> property specifies the cluster
+ behavior for HTTP sessions. If you specify
+ <code>worker.loadbalancer.sticky_session=0</code>, each request will be load
+ balanced between <classname>node1</classname> and <classname>node2</classname>;
+ that is, different requests for the same session will go to different servers.
+ But when a user opens a session on one server, it is always necessary to always
+ forward this user's requests to the same server, as long as that server is
+ available. This is called a <emphasis>sticky session</emphasis>, as the client
+ is always using the same server he reached on his first request. To enable
+ session stickiness, you need to set
+ <varname>worker.loadbalancer.sticky_session</varname> to <literal>1</literal>.</para>
<note>
- <para>A non-loadbalanced setup with a single node requires a <literal>worker.list=node1</literal>
- entry.</para>
+ <para>A non-loadbalanced setup with a single node requires a
+ <code>worker.list=node1</code> entry.</para>
</note>
</section>
<section id="clustering-http-jboss">
<title>Configuring JBoss to work with mod_jk</title>
- <para>Finally, we must configure the JBoss Enterprise Web Platform 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/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>
-<Engine name="jboss.web" defaultHost="localhost" jvmRoute="node1">
-...
-</Engine>
- </programlisting>
- <para>You also need to be sure the AJP connector in server.xml is enabled (i.e., uncommented). It is enabled by default.
+ <para>Finally, we must configure the JBoss Enterprise Web Platform instances
+ on all clustered nodes so that they can expect requests forwarded from the
+ mod_jk load balancer.</para>
+ <para>On each clustered JBoss node, we have to name the node according to the
+ name specified in <filename>workers.properties</filename>. For instance, on
+ JBoss instance <classname>node1</classname>, edit the
+ <filename>JBOSS_HOME/server/$PROFILE/deploy/jbossweb.sar/server.xml</filename> file.
+ Locate the <literal><![CDATA[<Engine>]]></literal> element and add an attribute
+ <varname>jvmRoute</varname>:</para>
+ <programlisting><![CDATA[
+<Engine name="jboss.web" defaultHost="localhost" jvmRoute="node1">
+</Engine>
+]]> </programlisting>
+ <para>You also need to ensure that the AJP connector in <filename>server.xml</filename>
+ is enabled (that is, uncommented). It is enabled by default.
</para>
<programlisting><![CDATA[
<!-- Define an AJP 1.3 Connector on port 8009 -->
@@ -253,23 +289,30 @@
<programlisting>
<attribute name="UseJK">true</attribute>
</programlisting>-->
- <para>At this point, you have a fully working Apache with 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>
+ <para>At this point, you have a fully working Apache with 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 AS, please refer to the JBoss
- wiki page at
- <literal>http://www.jboss.org/community/wiki/UsingModjk12WithJBoss</literal>.</para>
+ <para>For more updated information on using mod_jk 1.2 with JBoss Application Server,
+ refer to the JBoss wiki page at <ulink url="http://www.jboss.org/community/wiki/UsingModjk12WithJBoss">http://www.jboss.org/community/wiki/UsingModjk12WithJBoss</ulink>.</para>
</note>
</section>
</section>
<section id="clustering-http-state">
<title>Configuring HTTP session state replication</title>
- <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 Web Platform applies no matter what load balancer is used.
+ <para>The preceding discussion has been focused on using mod_jk as a load balancer.
+ The following information about clustering HTTP services in
+ JBoss Enterprise Web Platform applies regardless of the load balancer 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, 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>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 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
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>
@@ -355,177 +398,266 @@
<section id="clustering-http-app">
<title>Enabling session replication in your application</title>
- <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"
+ <para>To enable replication of your web application you must tag the
+ application as distributable in the <filename>web.xml</filename> descriptor.
+ Here's an example:</para>
+ <programlisting><![CDATA[
+<?xml version="1.0"?>
+<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
- version="2.4">
+ version="2.4">
- <emphasis role="bold"><distributable/></emphasis>
+ <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. 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
+</web-app>
+]]></programlisting>
+ <para> You can futher configure session replication using the
+ <literal>replication-config</literal> element in the <filename>jboss-web.xml</filename>
+ 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>
+ http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd>
-<jboss-web>
+<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>
+ <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>
+</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>
+ 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
+ <para>The <varname>replication-trigger</varname> 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
+ of a <methodname>setAttribute</methodname> 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>
+ and needs to be replicated. This element has three valid values:</para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>SET_AND_GET</literal></term>
+ <listitem>
+ <para>Always replicates session data,
+ even if its content has not been modified but simply accessed. This
+ previously ensured that every request triggered a timestamp.
+ Since setting <varname>max_unreplicated_interval</varname> to <literal>0</literal>
+ accomplishes the same thing at much lower cost, using <literal>SET_AND_GET</literal>
+ is not sensible with Enterprise Web Platform 5.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>SET_AND_NON_PRIMITIVE_GET</literal></term>
+ <listitem>
+ <para>Only replicates if an object of a non-primitive type has been
+ accessed (that is, 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>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>SET</literal></term>
+ <listitem>
+ <para>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
+ major performance benefits, but requires very good coding practices to
+ ensure that <methodname>setAttribute</methodname> is always called
+ whenever a mutable object stored in the session is modified.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>In all cases, calling <methodname>setAttribute</methodname> marks the
+ session as needing replication.</para>
+
+ <para>The <varname>replication-granularity</varname> element determines the granularity of what gets replicated if the container determines session replication is needed. The supported values are: </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>SESSION</literal></term>
+ <listitem>
+ <para>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>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ATTRIBUTE</literal></term>
+ <listitem>
+ <para>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
+ (for example, a <literal>Person</literal> object in the
+ <varname>husband<varname> attribute sharing a reference to an
+ <literal>Address</literal> object with another <literal>Person</literal>
+ in the <varname>wife</varname> attribute). 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>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>FIELD</literal></term>
+ <listitem>
+ <para>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>
+ </varlistentry>
+ </variablelist>
+
+ <para>The other elements under the <literal>replication-config</literal> element are much less frequently used.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>cacheName</varname></term>
<listitem>
- <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 Enterprise Web Platform 5.</para>
+ <para>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. The default value is
+ <literal>standard-session-cache</literal> if the
+ <varname>replication-granularity</varname> is not <literal>FIELD</literal>,
+ and <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>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>replication-field-batch-mode</varname></term>
<listitem>
- <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>
+ <para>Indicates whether all replication messages associated with a request
+ will be batched into one message. This is applicable only if
+ <varname>replication-granularity</varname> is <literal>FIELD</literal>.
+ If <varname>replication-field-batch-mode</varname> 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. The default value is <literal>true</literal>.</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>useJK</varname></term>
<listitem>
- <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>
+ <para>Indicates whether the container
+ should assume that a JK-based software load balancer (for example, 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> (that is, 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. <varname>useJK</varname> need only be set to
+ <literal>false</literal> for web applications whose URL cannot be handled by
+ the JK load balancer.
+ </para>
</listitem>
- </itemizedlist>
- <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>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>max-unreplicated-interval</varname></term>
<listitem>
- <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>
+ <para>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
+ <methodname>HttpSession.getLastAccessedTime()</methodname> 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
+ (for example, modifying an attribute) has resulted in other replication work
+ involving the session. A positive value greater than the
+ <methodname>HttpSession.getMaxInactiveInterval()</methodname> value will be treated
+ as a probable misconfiguration and converted to <literal>0</literal>; that is,
+ metadata will be replicated on every request. The default value is
+ <literal>60</literal>.</para>
</listitem>
-
- <listitem>
- <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 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 Enterprise Web Platform 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>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>snapshot-mode</varname></term>
+ <listitem>
+ <para>Configures when sessions are replicated to the other nodes. Possible
+ values are <literal>instant</literal> (the default) and <literal>interval</literal>.</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>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>
- 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>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>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>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>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>snapshot-interval</varname></term>
+ <listitem>
+ <para>Defines how often (in milliseconds) the background task that replicates
+ modified sessions should be started for this web application. Only meaningful
+ if <varname>snapshot-mode</varname> is set to <literal>interval</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>session-notification-policy</varname></term>
+ <listitem>
+ <para>Specifies the fully qualified class name of the implementation of the
+ <classname>ClusteredSessionNotificationPolicy</classname> interface that should be
+ used to govern whether servlet specification notifications should be emitted
+ to any registered <classname>HttpSessionListener</classname>,
+ <classname>HttpSessionAttributeListener</classname>
+ or <classname>HttpSessionBindingListener</classname>.</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>Sensible event notifications for a non-clustered environment may not
+ remain sensible in a clustered environment. (See
+ <ulink url="https://jira.jboss.org/jira/browse/JBAS-5778">https://jira.jboss.org/jira/browse/JBAS-5778</ulink>
+ for an example of why a notification may not be desired.) Configuring an appropriate
+ <classname>ClusteredSessionNotificationPolicy</classname> gives the application
+ author fine-grained control over what notifications are issued.</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
- <ulink url="https://jira.jboss.org/jira/browse/JBAS-5778">https://jira.jboss.org/jira/browse/JBAS-5778</ulink>
- 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 previous releases, the default value if not explicitly set is the
- <literal>LegacyClusteredSessionNotificationPolicy</literal>, which implements
- the behavior in previous JBoss versions. In JBoss Enterprise Web Platform 5, 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>
-
+ <para>If no value is explicitly set, the default behavior is
+ <classname>IgnoreUndeployLegacyClusteredSessionNotificationPolicy</classname>,
+ which implements the same behavior except during undeployment,
+ during which no <literal>HttpSessionListener</literal> and
+ <literal>HttpSessionAttributeListener</literal> notifications are sent.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
<section id="clustering-http-passivation">
@@ -535,8 +667,8 @@
storage. If a passivated session is requested by a client, it can be
"activated" back into memory and removed from the persistent store.
JBoss Enterprise Web Platform 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>
+ <filename>web.xml</filename> includes the <literal>distributable</literal>
+ tag (that is, clustered web applications).</para>
<para>Passivation occurs at three points during the lifecycle of a web application:</para>
@@ -575,8 +707,8 @@
<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>
+ <filename>jboss-web.xml</filename> deployment descriptor in your web application's
+ <filename>WEB-INF</filename> directory.</para>
<programlisting><![CDATA[
<!DOCTYPE jboss-web PUBLIC
@@ -595,48 +727,56 @@
</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>
+ <variablelist>
+ <varlistentry>
+ <term><varname>max-active-session</varname></term>
+ <listitem>
+ <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 <varname>passivation-min-idle-time</varname>. 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>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>use-session-passivation</varname></term>
+ <listitem>
+ <para>Determines whether session passivation will be enabled for the web
+ application. Default is <literal>false</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>passivation-min-idle-time</varname></term>
+ <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
+ <varname>max-active-sessions</varname>.
+ A value of <literal>-1</literal> (the default) disables passivating sessions
+ before <varname>passivation-max-idle-time</varname>. Neither a value of <literal>-1</literal>
+ nor a high value are recommended if <varname>max-active-sessions</varname>
+ is set.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>passivation-max-idle-time</varname></term>
+ <listitem>
+ <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 <varname>max-active-sessions</varname>. 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>
+ </varlistentry>
+ </variablelist>
<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
+ <varname>max-active-sessions</varname>. The number of sessions replicated from other nodes
will also depend on whether <emphasis>buddy replication</emphasis> is enabled.
</para>
@@ -644,95 +784,109 @@
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
+ default <varname>numBuddies</varname> setting (<literal>1</literal>), each node will
store 200 sessions in memory.
</para>
- </section>
+ </section>
+ </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>
+ integrates with the <classname>CacheManager</classname> 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"/>).
+ <filename>jboss-web.xml</filename> (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>
+ <varname>standard-session-cache</varname> and <varname>field-granularity-session-cache</varname>
+ (for applications configured for <literal>FIELD</literal> 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
+ The <varname>standard-session-cache</varname> and
+ <varname>field-granularity-session-cache</varname> 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>
+ <variablelist>
+ <varlistentry>
+ <term><varname>cacheMode</varname></term>
+ <listitem>
+ <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>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>enabled</varname> (in <varname>buddyReplicationConfig</varname>)</term>
+ <listitem>
+ <para>Set to <literal>true</literal> to enable buddy replication. See
+ <xref linkend="jbosscache-configuration-buddyrepl"/>.
+ Default is <literal>false</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>numBuddies</varname> (in <varname>buddyReplicationConfig</varname>)</term>
+ <listitem>
+ <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>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>buddyPoolName</varname> (in <varname>buddyReplicationConfig</varname>)</term>
+ <listitem>
+ <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>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>multiplexerStack</varname></term>
+ <listitem>
+ <para>Name of the JGroups protocol stack the cache should use.
+ See <xref linkend="clustering-blocks-jgroups-channelfactory"/>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>clusterName</varname></term>
+ <listitem>
+ <para>Specifies the 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>
+ </variablelist>
- <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>
+ 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. 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>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>
- First, you need to identify the classes that you need to prepare. You can identify these classes by using annotations, like so:
+ 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[
@@ -744,7 +898,10 @@
</programlisting>
<para>
-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:
+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
@@ -760,11 +917,9 @@
]]></programlisting>
<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 Enterprise Web Platform 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>JBoss Enterprise Web Platform 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>/**
* Represents a street address.
* @org.jboss.cache.pojo.annotation.Replicable
@@ -776,7 +931,14 @@
</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 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.
+ 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>
@@ -786,14 +948,22 @@
</programlisting>
<para>
- Please see the JBoss AOP documentation for the usage of the pre- and post-compiler. The JBoss AOP project also provides easy to use ANT tasks to help integrate those steps into your application build process.
+ See the JBoss AOP documentation for the usage of the pre- and post-compiler.
+ The JBoss AOP project also provides easy to use ANT tasks to help integrate those
+ steps into your application build process.
</para>
<note>
<para>
- 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.
+ 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>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>
+ <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>
Person husband = new Person(getHusbandName(request), getHusbandAge(request));
@@ -814,12 +984,15 @@
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>
+ <para>Notice that in there is no need to call
+ <methodname>session.setAttribute()</methodname> after you make changes to
+ the data object, and all changes to the fields are automatically replicated
+ across the cluster.</para>
- <para>Besides plain objects, you can also use regular Java collections of those objects as session
- attributes. POJO Cache automatically figures out how to handle those collections and replicate
- field changes in their member objects.</para>
+ <para>
+ Besides plain objects, you can also use regular Java collections of those
+ objects as session attributes. POJO Cache automatically figures out how
+ to handle those collections and replicate field changes in their member objects.</para>
</section>
@@ -833,88 +1006,107 @@
are deployed on that same machine or on another node in the cluster.
Authentication replication is handled by JBoss Cache. Clustered single sign-on
support is a JBoss-specific extension of the non-clustered
- <literal>org.apache.catalina.authenticator.SingleSignOn</literal>
+ <classname>org.apache.catalina.authenticator.SingleSignOn</classname>
valve that is a standard part of Tomcat and JBoss Web. Both the non-clustered
and clustered versions allow users to sign on to any one of the web apps
associated with a virtual host and have their identity recognized by all
- other web apps on the same virtual host. The clustered version brings the
+ other web applications on the same virtual host. The clustered version brings the
added benefits of enabling SSO failover and allowing a load balancer to direct
- requests for different webapps to different servers, while maintaining the SSO.
+ requests for different web applications to different servers, while maintaining the SSO.
</para>
<section id="clustering-sso-configuration">
<title>Configuration</title>
<para>
- To enable clustered single sign-on, you must add the <literal>ClusteredSingleSignOn</literal>
+ To enable clustered single sign-on, you must add the <classname>ClusteredSingleSignOn</classname>
valve to the appropriate <literal>Host</literal> elements of the
<literal>JBOSS_HOME/server/all/deploy/jbossweb.sar/server.xml</literal> file.
The valve element is already included in the standard file; you just need
to uncomment it. The valve configuration is shown here:
</para>
- <programlisting><Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" /></programlisting>
+ <programlisting><![CDATA[<Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" />]]></programlisting>
<para>The element supports the following attributes:</para>
-
- <itemizedlist>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>className</varname></term>
<listitem>
- <para><emphasis role="bold">className</emphasis> is a required attribute
- to set the Java class name of the valve implementation to use. This must
+ <para>Required. Sets the Java class name of the valve implementation to use. This must
be set to <literal>org.jboss.web.tomcat.service.sso.ClusteredSingleSign</literal>.</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>cacheConfig</varname></term>
<listitem>
- <para><emphasis role="bold">cacheConfig</emphasis> is the name of the
+ <para>Specifies the name of the
cache configuration (see <xref linkend="clustering-blocks-jbc-cachemanager"/>) to use
for the clustered SSO cache. Default is <literal>clustered-sso</literal>.</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>treeCacheName</varname></term>
<listitem>
- <para><emphasis role="bold">treeCacheName</emphasis> is deprecated; use <literal>cacheConfig</literal>.
+ <para>Deprecated; use <varname>cacheConfig</varname>.
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>,
+ CacheManager service using the value of <varname>cacheConfig</varname>,
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>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>cookieDomain</varname></term>
<listitem>
- <para><emphasis role="bold">cookieDomain</emphasis> is used to set the host domain
- to be used for sso cookies. See <xref linkend="clustering-sso-cookie-domain"/> for more.
+ <para>Sets the host domain to be used for SSO cookies. See
+ <xref linkend="clustering-sso-cookie-domain"/> for more.
Default is <literal>"/"</literal>.</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>maxEmptyLife</varname></term>
<listitem>
- <para><emphasis role="bold">maxEmptyLife</emphasis> is the maximum number of seconds
+ <para>The maximum number of seconds
an SSO with no active sessions will be usable by a request. The clustered
SSO valve tracks what cluster nodes are managing sessions related to an
SSO. A positive value for this attribute allows proper handling of
shutdown of a node that is the only one that had handled any of the sessions
associated with an SSO. The shutdown invalidates the local copy of the
- sessions, eliminating all sessions from the SSO. If maxEmptyLife were
+ sessions, eliminating all sessions from the SSO. If <varname>maxEmptyLife</varname> were
zero, the SSO would terminate along with the local session copies.
But, backup copies of the sessions (if they are from clustered
webapps) are available on other cluster nodes. Allowing the SSO to live
beyond the life of its managed sessions gives the user time to make
another request which can fail over to a different cluster node, where
it activates the the backup copy of the session. Default is
- <literal>1800</literal>, i.e. 30 minutes.</para>
+ <literal>1800</literal> (30 minutes).</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>processExpiresInterval</varname></term>
<listitem>
- <para><emphasis role="bold">processExpiresInterval</emphasis> is the minimum number
- of seconds between efforts by the valve to find and invalidate SSO's
- that have exceeded their 'maxEmptyLife'. Does not imply effort will be
- spent on such cleanup every 'processExpiresInterval', just that it
- won't occur more frequently than that. Default is <literal>60</literal>.</para>
+ <para>The minimum number of seconds between efforts by the valve to find and
+ invalidate SSO's that have exceeded their <varname>maxEmptyLife</varname>. Does
+ not imply effort will be spent on such cleanup every <varname>processExpiresInterval</varname>,
+ just that it won't occur more frequently than that. Default is <literal>60</literal>.</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>requireReauthentication</varname></term>
<listitem>
- <para><emphasis role="bold">requireReauthentication</emphasis> is a flag to determine
- whether each request needs to be reauthenticated to the security <emphasis>Realm</emphasis>.
- If "true", this Valve uses cached security credentials (username and password)
+ <para>A flag to determine whether each request needs to be reauthenticated to
+ the security <emphasis>Realm</emphasis>. If <literal>true</literal>, this
+ valve uses cached security credentials (username and password)
to reauthenticate to the JBoss Web security <emphasis>Realm</emphasis>
each request associated with an SSO session. If <literal>false</literal>,
the valve can itself authenticate requests based on the presence of a
valid SSO cookie, without rechecking with the <emphasis>Realm</emphasis>.
Setting to <literal>true</literal> can allow web applications with
- different <literal>security-domain</literal> configurations to share an
+ different <varname>security-domain</varname> configurations to share an
SSO. Default is <literal>false</literal>.</para>
</listitem>
- </itemizedlist>
+ </varlistentry>
+ </variablelist>
</section>
@@ -923,8 +1115,8 @@
<para>The user will not be challenged as long as they access only
unprotected resources in any of the web applications on the virtual host.</para>
- <para>Upon access to a protected resource in any web app, the user will
- be challenged to authenticate, using the login method defined for the web app.</para>
+ <para>Upon access to a protected resource in any web application, the user will
+ be challenged to authenticate, using the login method defined for the web application.</para>
<para>Once authenticated, the roles associated with this user will be
utilized for access control decisions across all of the associated web
@@ -932,7 +1124,7 @@
each application individually.</para>
<para>If the web application invalidates a session (by invoking the
- <literal>javax.servlet.http.HttpSession.invalidate()</literal> method),
+ <methodname>javax.servlet.http.HttpSession.invalidate()</methodname> method),
the user's sessions in all web applications will be invalidated.</para>
<para>A session timeout does not invalidate the SSO if other sessions
@@ -942,60 +1134,60 @@
<section id="clustering-sso-limitations">
<title>Limitations</title>
<para>There are a number of known limitations to this Tomcat valve-based
- SSO implementation:
+ SSO implementation:</para>
<itemizedlist>
- <listitem><para>Only useful within a cluster of JBoss servers;
+ <listitem><para>It is only useful within a cluster of JBoss servers;
SSO does not propagate to other resources.</para></listitem>
- <listitem><para>Requires use of container managed authentication
- (via <literal><login-config></literal> element in <literal>web.xml</literal>)</para></listitem>
+ <listitem><para>It requires the use of container managed authentication
+ (via the <literal><![CDATA[login-config>]]></literal> element in
+ <filename>web.xml</filename>)</para></listitem>
<listitem><para>Requires cookies. SSO is maintained via a cookie and URL rewriting is not supported.</para></listitem>
- <listitem><para>Unless <literal>requireReauthentication</literal> is set
+ <listitem><para>Unless <varname>requireReauthentication</varname> is set
to <literal>true</literal>, all web applications configured for the same
SSO valve must share the same JBoss Web <literal>Realm</literal> and
- JBoss Security <literal>security-domain</literal>. This means:
+ JBoss Security <varname>security-domain</varname>. This means:
<itemizedlist>
- <listitem><para>In <literal>server.xml</literal> you can nest the
+ <listitem><para>In <filename>server.xml</filename> you can nest the
<literal>Realm</literal> element inside the <literal>Host</literal>
element (or the surrounding <literal>Engine</literal> element), but not
- inside a <literal>context.xml</literal> packaged with one of the involved web applications.</para></listitem>
- <listitem><para>The <literal>security-domain</literal> configured in
- <literal>jboss-web.xml</literal> or <literal>jboss-app.xml</literal>
+ inside a <filename>context.xml</filename> packaged with one of the
+ involved web applications.</para></listitem>
+ <listitem><para>The <varname>security-domain</varname> configured in
+ <filename>jboss-web.xml</filename> or <filename>jboss-app.xml</filename>
must be consistent for all of the web applications.</para></listitem>
- <listitem><para>Even if you set <literal>requireReauthentication</literal>
- to <literal>true</literal> and use a different <literal>security-domain</literal>
- (or, less likely, a different <literal>Realm</literal>) for different webapps,
+ <listitem><para>Even if you set <varname>requireReauthentication</varname>
+ to <literal>true</literal> and use a different <varname>security-domain</varname>
+ (or, less likely, a different <literal>Realm</literal>) for different web applications,
the varying security integrations must all accept the same credentials
(e.g. username and password).</para></listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
- </para>
</section>
<section id="clustering-sso-cookie-domain">
<title>Configuring the Cookie Domain</title>
- <para>As noted above the SSO valve supports a <literal>cookieDomain</literal>
+ <para>As noted above the SSO valve supports a <varname>cookieDomain</varname>
configuration attribute. This attribute allows configuration of the SSO cookie's domain
- (i.e. the set of hosts to which the browser will present the cookie).
+ (that is, the set of hosts to which the browser will present the cookie).
By default the domain is <literal>"/"</literal>, meaning the browser
will only present the cookie to the host that issued it. The
- <literal>cookieDomain</literal> attribute allows the cookie to be
+ <varname>cookieDomain</varname> attribute allows the cookie to be
scoped to a wider domain.</para>
<para>For example, suppose we have a case where two apps, with URLs
- <literal>http://app1.xyz.com</literal> and <literal>http://app2.xyz.com</literal>,
- that wish to share an SSO context. These apps could be running on different
+ <filename>http://app1.xyz.com</filename> and <filename>http://app2.xyz.com</filename>,
+ that wish to share an SSO context. These applications could be running on different
servers in a cluster or the virtual host with which they are associated
could have multiple aliases. This can be supported with the following configuration:
- <programlisting><Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn"
- cookieDomain="xyz.com" /></programlisting>
+ <programlisting><![CDATA[<Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn"
+ cookieDomain="xyz.com" />]]></programlisting>
</para>
</section>
</section>
</chapter>
-
More information about the jboss-cvs-commits
mailing list