[jboss-cvs] JBossAS SVN: r84565 - projects/docs/community/5/Clustering_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri Feb 20 13:51:00 EST 2009
Author: bstansberry at jboss.com
Date: 2009-02-20 13:51:00 -0500 (Fri, 20 Feb 2009)
New Revision: 84565
Added:
projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Building_Blocks.xml
projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Concepts.xml
projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Deployment.xml
Modified:
projects/docs/community/5/Clustering_Guide/en-US/Book_Info.xml
projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide.xml
projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Introduction.xml
Log:
Reorg into parts; combine farming with HASingleton
Modified: projects/docs/community/5/Clustering_Guide/en-US/Book_Info.xml
===================================================================
--- projects/docs/community/5/Clustering_Guide/en-US/Book_Info.xml 2009-02-20 18:21:08 UTC (rev 84564)
+++ projects/docs/community/5/Clustering_Guide/en-US/Book_Info.xml 2009-02-20 18:51:00 UTC (rev 84565)
@@ -2,8 +2,8 @@
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
<bookinfo>
-<title>JBoss Application Server 5</title>
- <subtitle>Clustering Guide</subtitle>
+<title>JBoss AS 5.0 Clustering Guide</title>
+ <subtitle>High Availability Enterprise Services with JBoss Application Server Clusters</subtitle>
<edition>2</edition>
<issuenum>2</issuenum>
<pubsnumber>2</pubsnumber>
@@ -15,6 +15,6 @@
This book is the JBoss Application Server 5 Clustering Guide.
</para>
</abstract>
- <subtitle>Authors</subtitle>
+ <!-- <subtitle>Authors</subtitle>-->
<xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</bookinfo>
Modified: projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide.xml
===================================================================
--- projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide.xml 2009-02-20 18:21:08 UTC (rev 84564)
+++ projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide.xml 2009-02-20 18:51:00 UTC (rev 84565)
@@ -3,13 +3,32 @@
<book>
<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_HTTP.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-<xi:include href="Clustering_Guide_HASingleton.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_JGroups.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-<xi:include href="Clustering_Guide_JBoss_Cache.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+
+<part id="Core_Services">
+ <title>Introduction and Core Services</title>
+ <xi:include href="Clustering_Guide_Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Clustering_Guide_Concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Clustering_Guide_Building_Blocks.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Clustering_Guide_Deployment.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</part>
+
+<part id="Clustered_JEE">
+ <title>Clustered Java EE</title>
+ <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_HTTP.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <!--
+ <xi:include href="Clustering_Guide_HASingleton.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+-->
+ <xi:include href="Clustering_Guide_JMS.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</part>
+
+<part id="JGroups_JBC">
+ <title>JGroups and JBoss Cache</title>
+ <xi:include href="Clustering_Guide_JGroups.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Clustering_Guide_JBoss_Cache.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</part>
+
</book>
Added: projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Building_Blocks.xml
===================================================================
--- projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Building_Blocks.xml (rev 0)
+++ projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Building_Blocks.xml 2009-02-20 18:51:00 UTC (rev 84565)
@@ -0,0 +1,489 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+ <chapter id="clustering-blocks.chapt">
+ <title>Clustering Building Blocks</title>
+
+ <para>The clustering features in JBoss AS 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:
+ </para>
+
+ <figure id="clustering-as-arch.fig">
+ <title>The JBoss AS clustering architecture</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/clustering-as-arch.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para><emphasis role="bold">JGroups</emphasis> 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 AS cluster.
+ See <xref linkend="clustering-blocks-jgroups"/> for more on how JBoss AS
+ uses JGroups.</para>
+
+ <para><emphasis role="bold">JBoss Cache</emphasis> is a highly flexible
+ clustered transactional caching library. Many AS clustering services
+ need to cache some state in memory while 1) ensuring for high availability
+ purposes that a backup copy of that state is available on another node
+ if it can't otherwise be recreated (e.g. the contents of a web session)
+ and 2) ensuring that the data cached on each node in the cluster is consistent.
+ JBoss Cache handles these concerns for most JBoss AS clustered services.
+ JBoss Cache uses JGroups to handle its group communication requirements.
+ <emphasis role="bold">POJO Cache</emphasis> is an extension of the
+ core JBoss Cache that JBoss AS uses to support fine-grained replication
+ of clustered web session state. See <xref linkend="clustering-blocks-jbc"/>
+ for more on how JBoss AS uses JBoss Cache and POJO Cache.</para>
+
+ <para><emphasis role="bold">HAPartition</emphasis> is an adapter on top
+ of a JGroups channel that allows multiple services to use the channel.
+ HAPartition also supports a distributed registry of which HAPartition-based
+ services are running on which cluster members. It provides notifications to
+ interested listeners when the cluster membership changes or the clustered
+ service registry changes. See <xref linkend="clustering-hapartition"/> for
+ more details on HAPartition.</para>
+
+ <para>The other higher level clustering services make use of JBoss Cache
+ or HAPartition, or, in the case of HA-JNDI, both. The exception to this
+ is JBoss Messaging's clustering features, which interact with JGroups
+ directly.</para>
+
+ <section id="clustering-blocks-jgroups">
+ <title>Group Communication with JGroups</title>
+ <para></para>
+
+ <section id="clustering-blocks-jgroups-sharedtransport">
+ <title>The JGroups Shared Transport</title>
+ <para></para>
+ </section>
+
+ <section id="clustering-blocks-jgroups-channelfactory">
+ <title>The Channel Factory Service</title>
+ <para></para>
+ </section>
+ </section>
+
+ <section id="clustering-hapartition">
+ <title>The HAPartition Service</title>
+ <para>
+ HAPartition is a general purpose service used for a variety of tasks
+ in AS clustering. At its core, it is an abstraction built on top of
+ a JGroups Channel that provides support for making/receiving RPC
+ invocations on/from one or more cluster members. HAPartition also
+ supports a distributed registry of which clustering services are
+ running on which cluster members. It provides notifications to
+ interested listeners when the cluster membership changes or the
+ clustered service registry changes. HAPartition 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, EJB 2 SFSB
+ replication and entity cache management, farming, HA-JNDI and HA singletons.
+ Custom services can also make use of HAPartition.
+ </para>
+
+
+
+ <para>The following example shows the <literal>HAPartition</literal> MBean definition packaged with the standard JBoss AS distribution.
+ So, if you simply start JBoss servers with their default clustering settings on a local network, you
+ would get a default cluster named <literal>DefaultPartition</literal> that includes all server
+ instances as its nodes.</para>
+ <programlisting>
+<mbean code="org.jboss.ha.framework.server.ClusterPartition"
+ name="jboss:service=DefaultPartition">
+
+ <! -- Name of the partition being built -->
+ <attribute name="PartitionName">
+ ${jboss.partition.name:DefaultPartition}
+ </attribute>
+
+ <! -- The address used to determine the node name -->
+ <attribute name="NodeAddress">${jboss.bind.address}</attribute>
+
+ <! -- Determine if deadlock detection is enabled -->
+ <attribute name="DeadlockDetection">False</attribute>
+
+ <! -- Max time (in ms) to wait for state transfer to complete.
+ Increase for large states -->
+ <attribute name="StateTransferTimeout">30000</attribute>
+
+ <! -- The JGroups protocol configuration -->
+ <attribute name="PartitionConfig">
+ ... ...
+ </attribute>
+</mbean>
+ </programlisting>
+ <para>Here, we omitted the detailed JGroups protocol configuration for this channel. JGroups handles the
+ underlying peer-to-peer communication between nodes, and its configuration is discussed in <xref linkend="jgroups.chapt"/>. The following list shows the available configuration attributes
+ in the <literal>HAPartition</literal> MBean.</para>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">PartitionName</emphasis> is an optional attribute to specify the
+ name of the cluster. Its default value is <literal>DefaultPartition</literal>. Use the <literal>-g </literal> (a.k.a. --partition) command line switch to set this value at JBoss startup.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">NodeAddress</emphasis> is an optional attribute used to help generate a unique name for this node.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">DeadlockDetection</emphasis> is an optional boolean attribute that
+ tells JGroups to run message deadlock detection algorithms with every request. Its default
+ value is <literal>false</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">StateTransferTimeout</emphasis> is an optional attribute to specify the timeout for state replication across the cluster (in milliseconds). State replication refers to the process of obtaining initial application state from other already-running cluster members at service startup. Its default value is <literal>30000</literal>. </para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">PartitionConfig</emphasis> is an element to specify JGroup
+ configuration options for this cluster (see <xref linkend="jgroups-configuration"/>).</para>
+ </listitem>
+ </itemizedlist>
+ <para>In order for nodes to form a cluster, they must have the exact same <literal>PartitionName</literal> and the <literal>ParitionConfig</literal> elements. Changes in either element on some but not all nodes would cause the cluster to split.
+ </para>
+
+ <para>You can view the current cluster information by pointing your browser to the JMX console of any
+ JBoss instance in the cluster (i.e., <literal>http://hostname:8080/jmx-console/</literal>) and then
+ clicking on the <literal>jboss:service=HAPartition,partition=DefaultPartition</literal> MBean (change the MBean name to reflect your partitionr name if you use the -g startup switch). A list of IP addresses for the current cluster members is shown in the CurrentView field.</para>
+
+ <note><title>Note</title>
+ <para>
+ While it is technically possible to put a JBoss server instance into multiple HAPartitions at the same time, this practice is generally not recommended, as it increases management complexity.
+ </para>
+ </note>
+
+ <section id="clustering-hapartition-drm">
+ <title>DistributedReplicantManager Service</title>
+ <para>
+ The <literal>DistributedReplicantManager</literal> (DRM) service is a component
+ of the HAPartition service made available to HAPartition
+ users via the <literal>HAPartition.getDistributedReplicantManager()</literal>
+ method. Generally speaking, JBoss AS users will not directly make
+ use of the DRM; we discuss it here as an aid to those who want a
+ deeper understanding of how AS clustering internals work.</para>
+ <para>
+ The DRM is a distributed registry that allows HAPartition users to
+ register objects under a given key, making available to callersthe
+ set of objects registered under that key by the various members of t
+ he cluster. The DRM also provides a notification mechanism so interested
+ listeners can be notified when the contents of the registry changes.
+ </para>
+ <para>There are two main usages for the DRM in JBoss AS:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">Clustered Smart Proxies</emphasis></para>
+ <para>Here the keys are the names of the various services that need a
+ clustered smart proxy (see <xref linkend="clustering-concepts-arch-proxy"/>,
+ e.g. the name of a clustered EJB. The value object each node stores in
+ the DRM is known as a "target". It's something a smart proxy's transport
+ layer can use to contact the node (e.g. an RMI stub, an HTTP URL or a JBoss Remoting
+ <literal>InvokerLocator</literal>). The factory that builds clustered smart
+ proxies accesses the DRM to get the set of "targets" that should be
+ injected into the proxy to allow it to communicate with all the
+ nodes in a cluster.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">HASingleton</emphasis></para>
+ <para>Here the keys are the names of the various services that need to
+ function as High Availablity Singletons (see <xref linkend="clustering-hasingleton"/>).
+ The value object each node stores in the DRM is simply a String that
+ acts as a token to indicate that the node has the service deployed, and
+ thus is a candidate to become the "master" node for the HA singleton
+ service.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In both cases, the key under which objects are registered identifies
+ a particular clustered service. It is useful to understand that every
+ node in a cluster doesn't have to register an object under every key.
+ Only services that are deployed on a particular node will register
+ something under that service's key, and services don't have to be
+ deployed homogeneously across the cluster. The DRM is thus useful as a
+ mechanism for understanding a service's "topology" around the cluster
+ -- which nodes have the service deployed.</para>
+ </section>
+
+ <section id="clustering-hapartition-distributedstate">
+ <title>DistributedState Service</title>
+ <para>
+ The <literal>DistributedState</literal> service is a legacy component
+ of the HAPartition service made available to HAPartition
+ users via the <literal>HAPartition.getDistributedState()</literal>
+ method. This service provides coordinated management of arbitary
+ application state around the cluster. It is supported for backwards
+ compatibility reasons, but new applications should not use it; they
+ should use the much more sophisticated JBoss Cache instead.
+ </para>
+ <para>In JBoss 5 the <literal>DistributedState</literal> service actually
+ delegates to an underlying JBoss Cache instance.</para>
+ </section>
+
+ <section id="clustering-hapartition-customsvcs">
+ <title>Custom Use of HAPartition</title>
+
+ <para>Custom services can also use make use of HAPartition to handle
+ interactions with the cluster. Generally the easiest way to do this
+ is to extend the <literal>org.jboss.ha.framework.server.HAServiceImpl</literal>
+ base class, or the <literal>org.jboss.ha.jxm.HAServiceMBeanSupport</literal>
+ class if JMX registration and notification support are desired.
+ </para>
+
+ </section>
+
+</section>
+
+ <section id="clustering-blocks-jbc">
+ <title>Distributed Caching with JBoss Cache</title>
+ <para>
+ JBoss Cache is a fully featured distributed cache framework that can be
+ used in any application server environment or standalone. JBoss Cache
+ provides the underlying distributed caching support used by many of the
+ standard clustered services in a JBoss AS cluster, including:
+ <itemizedlist>
+ <listitem><para>Replication of clustered webapp sessions.</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>
+ <listitem><para>DistributedStateService</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>Users can also create their own JBoss Cache and POJO Cache
+ instances for custom use by their applications, see
+ <xref linkend="jbosscache.chapt"/> for more on this.</para>
+
+ <section id="clustering-blocks-jbc-cachemanager">
+ <title>The JBoss AS CacheManager Service</title>
+ <para>Many of the standard clustered services in JBoss AS use JBoss
+ Cache to maintain consistent state across the cluster. Different
+ services (e.g. web session clustering or second level caching of
+ JPA/Hibernate entities) use different JBoss Cache instances, with
+ each cache configured to meet the needs of the service that uses it.
+ In AS 4, each of these caches was independently deployed in the
+ <literal>deploy/</literal> directory, which had a number of disadvantages:
+ <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>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.
+ Using JMX for purposes other exposing management interfaces is just
+ not the JBoss 5 way.</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>In JBoss 5, the scattered cache deployments have been replaced
+ with a new <emphasis role="bold">CacheManager</emphasis> service,
+ deployed via the <literal>JBOSS_HOME/server/all/deploy/cluster/jboss-cache-manager.sar</literal>.
+ The CacheManager is a factory and registry for JBoss Cache instances.
+ It is configured with a set of named JBoss Cache configurations.
+ Services that need a cache ask the cache manager for the cache by
+ name; the cache manager creates the cache (if not already created)
+ and returns it. The cache manager keeps a reference to each cache
+ it has created, so all services that request the same cache configuration
+ name will share the same cache. When a service is done with the cache,
+ it releases it to the cache manager. The cache manager keeps track
+ of how many services are using each cache, and will stop and destroy
+ the cache when all services have released it.</para>
+
+ <section id="clustering-blocks-jbc-cachemanager-stdconfigs">
+ <title>Standard Cache Configurations</title>
+ <para>The following standard JBoss Cache configurations ship with JBoss AS 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 <literal>deploy/cluster/jboss-cache-manager.sar/META-INF/jboss-cache-manager-jboss-beans.xml</literal>
+ 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
+ in the documentation chapters for each service in this guide,
+ it is not advisable to change them.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">standard-session-cache</emphasis></para>
+ <para>Standard cache used for web sessions.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">field-granularity-session-cache</emphasis></para>
+ <para>Standard cache used for FIELD granularity web sessions.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">sfsb-cache</emphasis></para>
+ <para>Standard cache used for EJB3 SFSB caching.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">ha-partition</emphasis></para>
+ <para>Used by web tier Clustered Single Sign-On,
+ HA-JNDI, Distributed State.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">mvcc-entity</emphasis></para>
+ <para>A config appropriate for JPA/Hibernate entity/collection
+ caching that uses JBC's MVCC locking (see notes below).</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">optimistic-entity</emphasis></para>
+ <para>A config appropriate for JPA/Hibernate entity/collection
+ caching that uses JBC's optimistic locking (see notes below).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">pessimistic-entity</emphasis></para>
+ <para>A config appropriate for JPA/Hibernate entity/collection
+ caching that uses JBC's pessimistic locking (see notes below).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">mvcc-entity-repeatable</emphasis></para>
+ <para>Same as "mvcc-entity" but uses JBC's REPEATABLE_READ
+ isolation level instead of READ_COMMITTED (see notes below).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">pessimistic-entity-repeatable</emphasis></para>
+ <para>Same as "pessimistic-entity" but uses JBC's REPEATABLE_READ
+ isolation level instead of READ_COMMITTED (see notes below).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">local-query</emphasis></para>
+ <para>A config appropriate for JPA/Hibernate query result caching.
+ Does not replicate query results. DO NOT store the timestamp data
+ Hibernate uses to verify validity of query results in this cache.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">replicated-query</emphasis></para>
+ <para>A config appropriate for JPA/Hibernate query result caching.
+ Replicates query results. DO NOT store the timestamp data
+ Hibernate uses to verify validity of query result in this cache.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">timestamps-cache</emphasis></para>
+ <para>A config appropriate for the timestamp data cached as part
+ of JPA/Hibernate query result caching. A replicated timestamp cache
+ is required if query result caching is used, even if the query results
+ themselves use a non-replicating cache like <literal>local-query</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">mvcc-shared</emphasis></para>
+ <para>A config appropriate for a cache that's shared for JPA/Hibernate
+ entity, collection, query result and timestamp caching. Not an
+ advised configuration, since it requires cache mode REPL_SYNC,
+ which is the least efficient mode. Also requires a full state
+ transfer at startup, which can be expensive. Maintained for
+ backwards compatibility reasons, as a shared cache was the only
+ option in JBoss 4. Uses JBC's MVCC locking.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">optimistic-shared</emphasis></para>
+ <para>A config appropriate for a cache that's shared for JPA/Hibernate
+ entity, collection, query result and timestamp caching. Not an
+ advised configuration, since it requires cache mode REPL_SYNC,
+ which is the least efficient mode. Also requires a full state
+ transfer at startup, which can be expensive. Maintained for
+ backwards compatibility reasons, as a shared cache was the only
+ option in JBoss 4. Uses JBC's optimistic locking.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">pessimistic-shared</emphasis></para>
+ <para>A config appropriate for a cache that's shared for JPA/Hibernate
+ entity, collection, query result and timestamp caching. Not an
+ advised configuration, since it requires cache mode REPL_SYNC,
+ which is the least efficient mode. Also requires a full state
+ transfer at startup, which can be expensive. Maintained for
+ backwards compatibility reasons, as a shared cache was the only
+ option in JBoss 4. Uses JBC's pessimistic locking.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">mvcc-shared-repeatable</emphasis></para>
+ <para>Same as "mvcc-shared" but uses JBC's REPEATABLE_READ
+ isolation level instead of READ_COMMITTED (see notes below).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">pessimistic-shared-repeatable</emphasis></para>
+ <para>Same as "pessimistic-shared" but uses JBC's REPEATABLE_READ
+ isolation level instead of READ_COMMITTED. (see notes below).
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <note><para>For more on JBoss Cache's locking schemes, see
+ <xref linkend="jbosscache-configuration-concurrency"/>)</para></note>
+
+ <note><para>For JPA/Hibernate second level caching, REPEATABLE_READ is
+ only useful if the application evicts/clears entities from the
+ EntityManager/Hibernate Session and then expects to repeatably
+ re-read them in the same transaction. Otherwise, the Session's
+ internal cache provides a repeatable-read semantic.</para></note>
+
+ </section>
+
+ <section>
+ <title>Cache Configuration Aliases</title>
+ <para>The CacheManager also supports aliasing of caches; i.e.
+ 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 config
+ names. It's also useful for supporting legacy EJB3 application
+ configurations ported over from AS 4.</para>
+ <para>Aliases can be configured by editing the "CacheManager"
+ bean in the <literal>jboss-cache-manager-jboss-beans.xml</literal>
+ file. The following redacted config shows the standard aliases in
+ AS 5.0.0.GA:</para>
+
+ <programlisting><![CDATA[
+<bean name="CacheManager" class="org.jboss.ha.cachemanager.CacheManager">
+
+ . . .
+
+ <!-- Aliases for cache names. Allows caches to be shared across
+ services that may expect different cache config names. -->
+ <property name="configAliases">
+ <map keyClass="java.lang.String" valueClass="java.lang.String">
+ <!-- Use the HAPartition cache for ClusteredSSO caching -->
+ <entry>
+ <key>clustered-sso</key>
+ <value>ha-partition</value>
+ </entry>
+ <!-- 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 -->
+ <entry>
+ <key>jboss.cache:service=EJB3EntityTreeCache</key>
+ <value>mvcc-shared</value>
+ </entry>
+ </map>
+ </property>
+
+ . . .
+
+</bean>]]></programlisting>
+ </section>
+ </section>
+ </section>
+
+ </chapter>
+
Property changes on: projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Building_Blocks.xml
___________________________________________________________________
Name: svn:executable
+ *
Name: svn:keywords
+
Added: projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Concepts.xml
===================================================================
--- projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Concepts.xml (rev 0)
+++ projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Concepts.xml 2009-02-20 18:51:00 UTC (rev 84565)
@@ -0,0 +1,224 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+ <chapter id="cluster.concepts.chapt">
+ <title>Clustering Concepts</title>
+
+ <para>
+ In the next section, we discuss basic concepts behind JBoss's clustering
+ services. It is helpful that you understand these concepts before reading
+ the rest of the Clustering Guide. Clustering configurations for specific
+ types of applications are covered beginning with the next chapter.
+ </para>
+
+ <section id="clustering-concepts-def">
+ <title>Cluster Definition</title>
+ <para>
+ A cluster is a set of nodes that communicate with each other and work
+ toward a common goal. In a JBoss Application Server cluster (also known
+ as a “partition”), a node is an JBoss Application Server instance.
+ Communication between the nodes is handled by the JGroups group communication
+ library, with a JGroups Channel providing the core functionality of tracking
+ who is in the cluster and reliably exchanging messages between the cluster
+ members. JGroups channels with the same configuration and name have the
+ ability to dynamically discover each other and form a group. This is why
+ simply executing “run -c all” on two AS instances on the same network is
+ enough for them to form a cluster – each AS starts a Channel (actually,
+ several) with the same default configuration, so they dynamically discover
+ each other and form a cluster. Nodes can be dynamically added to or removed
+ from clusters at any time, simply by starting or stopping a Channel with a
+ configuration and name that matches the other cluster members.
+
+ In summary, a JBoss cluster is a set of AS server instances each of which
+ is running an identically configured and named JGroups Channel.
+ </para>
+ <para>
+ On the same AS instance, different services can create their own Channel.
+ In a default 5.0.x AS, four different services create channels – the web
+ session replication service, the EJB3 SFSB replication service, the EJB3
+ entity caching service, and a core general purpose clustering service known
+ as HAPartition. In order to differentiate these channels, each must have a
+ unique name, and its configuration must match its peers yet differ from the
+ other channels.
+ </para>
+ <para>
+ So, if you go to two AS 5.0.x instances and execute <literal>run -c all</literal>,
+ 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
+ cluster, but it's important to understand that you really have 4 channels,
+ and hence 4 two node clusters.
+ </para>
+
+ <para>On the same network, even for the same service, we may have different clusters.
+ <xref linkend="clustering-Partition.fig"/> shows an example network of JBoss
+ server instances divided into three clusters, with the third cluster only
+ having one node. This sort of topology can be set up simply by configuring
+ the AS instances such that within a set of nodes meant to form a cluster the
+ Channel configurations and names match while they differ from any other
+ channels on the same network. </para>
+ <figure id="clustering-Partition.fig">
+ <title>Clusters and server nodes</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/clustering-Partition.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>
+ The section on “JGroups Configuration” and on “Isolating JGroups Channels”
+ covers in detail how to configure Channels such that desired peers find
+ each other and unwanted peers do not. As mentioned above, by default JBoss
+ AS uses four separate JGroups Channels. These can be divided into two
+ broad categories: the Channel used by the general purpose HAPartition
+ service, and three Channels created by JBoss Cache for special purpose
+ caching and cluster wide state replication.
+ </para>
+</section>
+
+<section id="clustering-concepts-arch">
+ <title>Service Architectures</title>
+ <para>The clustering topography defined by the <literal>HAPartition</literal>
+ MBean on each node is of great importance to system administrators. But for
+ most application developers, you are probably more concerned about the cluster
+ architecture from a client application's point of view. Two basic clustering
+ architectures are used with JBoss AS: client-side interceptors (a.k.a smart
+ proxies or stubs) and external load balancers. Which architecture your
+ application will use will depend on what type of client you have.
+ </para>
+
+
+ <section id="clustering-concepts-arch-proxy">
+ <title>Client-side interceptor architecture</title>
+<para>
+ Most remote services provided by the JBoss application server, including
+ JNDI, EJB, JMS, RMI and JBoss Remoting, require the client to obtain
+ (e.g., 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
+ object. The proxy automatically routes the call across the network where
+ it is invoked against service objects managed in the server. The proxy
+ object figures out how to find the appropriate server node, marshal call
+ parameters, un-marshall call results, and return the result to the caller
+ client. In a clustered environment, the server-generated proxy object includes an
+ interceptor that understands how to route calls to multiple nodes in the
+ cluster.
+</para>
+
+
+<para>The proxy's clustering logic maintains up-to-date knowledge about
+ the cluster. For instance, it knows the IP addresses of all available
+ server nodes, the algorithm to distribute load across nodes (see next section),
+ and how to failover the request if the target node not available.
+ As part of handling each service request, if the cluster topology has
+ changed the server node updates the proxy with the latest changes
+ in the cluster. For instance, if a node drops out of the cluster, each
+ proxy is updated with the new topology the next time it connects to any
+ active node in the cluster. All the manipulations done by the proxy's
+ clustering logic are transparent to the client application. The client-side
+ interceptor clustering architecture is illustrated in <xref linkend="clustering-InterceptorArch.fig"/>.
+</para>
+ <figure id="clustering-InterceptorArch.fig">
+ <title>The client-side interceptor (proxy) architecture for clustering</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/clustering-InterceptorArch.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <note>
+ <para><xref linkend="clustering-session-slsb21"/> describes how to enable the client proxy
+ to handle the entire cluster restart.</para>
+ </note>
+ </section>
+ <section id="clustering-concepts-arch-balancer">
+ <title>External Load Balancer Architecture</title>
+ <para>
+ Other JBoss services, in particular the HTTP-based services, do not
+ require the client to download anything. The client (e.g., a web browser)
+ sends in requests and receives responses directly over the wire using
+ to certain communication protocols (e.g., the HTTP protocol). In this
+ case, an external load balancer is required to process all requests and
+ dispatch them to server nodes in the cluster. The client only needs to know
+ how to contact the load balancer; it has no knowledge of the JBoss AS
+ instances behind the load balancer. The load balancer is logically part
+ of the cluster, but we refer to it as “external” because it is not running
+ in the same process as either the client or any of the JBoss AS instances.
+ It can be implemented either in software or hardware. There are many
+ vendors of hardware load balancers; the mod_jk Apache module is an excellent
+ example of a software load balancer. An external load balancer implements
+ its own mechanism for understanding the cluster configuration and provides
+ its own load balancing and failover policies. The external load balancer
+ clustering architecture is illustrated in <xref linkend="clustering-BalancerArch.fig"/>.
+ </para>
+ <figure id="clustering-BalancerArch.fig">
+ <title>The external load balancer architecture for clustering</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/clustering-BalancerArch.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ A potential problem with an external load balancer architecture is that
+ the load balancer itself may be a single point of failure. It needs to be
+ monitored closely to ensure high availability of the entire cluster's services.
+ </para>
+ </section>
+
+</section>
+
+<section id="clustering-concepts-balancepolicy">
+ <title>Load-Balancing Policies</title>
+ <para>
+ Both the JBoss client-side interceptor (stub) and load balancer use load balancing policies to determine which server node to which node a new request should be sent. In this section, let's go over the load balancing policies available in JBoss AS.
+ </para>
+ <section id="clustering-concepts-balancepolicy-30">
+ <title>Client-side interceptor architecture</title>
+ <para>
+ In JBoss 5.0.0, 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.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Round-Robin (<literal>org.jboss.ha.framework.interfaces.RoundRobin</literal>): 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Random-Robin (<literal>org.jboss.ha.framework.interfaces.RandomRobin</literal>): for each call the target node is randomly selected from the list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ First Available (<literal>org.jboss.ha.framework.interfaces.FirstAvailable</literal>): 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 stub elects its own target node independently of the other stubs, so if a particular client downloads two stubs for the same target service (e.g., an EJB), each stub will independently pick its target. This is an example of a policy that provides “session affinity” or “sticky sessions”, since the target node does not change once established.
+ </para>
+ </listitem>
+
+
+ <listitem>
+ <para>
+ First Available Identical All Proxies (<literal>org.jboss.ha.framework.interfaces.FirstAvailableIdenticalAllProxies</literal>): has the same behaviour as the "First Available" policy but the elected target node is shared by all stubs in the same client-side VM that are associated with the same target service. So if a particular client downloads two stubs for the same target service (e.g. an EJB), each stub will use the same target.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ <para>
+ Each of the above is an implementation of the org.jboss.ha.framework.interfaces.LoadBalancePolicy interface; users are free to write their own implementation of this simple interface if they need some special behavior. In later sections we'll see how to configure the load balance policies used by different services.
+ </para>
+</section>
+ <section><title>External load balancer architecture</title>
+
+<para>
+As noted above, an external load balancer provides its own load balancing capabilities. What capabilities are supported depends on the provider of the load balancer. The only JBoss requirement is that the load balancer support “session affinity” (a.k.a. “sticky sessions”). With session affinitiy enabled, once the load balancer routes a request from a client to node A and the server initiates a session, all future requests associated with that session must be routed to node A, so long as node A is available.
+ </para>
+
+
+ </section>
+</section>
+
+
+
+ </chapter>
+
Property changes on: projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Concepts.xml
___________________________________________________________________
Name: svn:executable
+ *
Name: svn:keywords
+
Added: projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Deployment.xml
===================================================================
--- projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Deployment.xml (rev 0)
+++ projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Deployment.xml 2009-02-20 18:51:00 UTC (rev 84565)
@@ -0,0 +1,480 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+ <chapter id="deployment.chapt">
+ <title>Clustered Deployment Options</title>
+
+ <section>
+ <title>Clustered Singleton Services</title>
+ <para>
+ A clustered singleton service (also known as an HA singleton)
+ is a service that is deployed on multiple nodes in a cluster, but
+ is providing its service on only one of the nodes. The node
+ running the singleton service is typically called the master node.
+ When the master fails or is shut down, another master is selected
+ from the remaining nodes and the service is restarted on the new
+ master. Thus, other than a brief interval when one master has
+ stopped and another has yet to take over, the service is always
+ being provided by one but only one node.
+ </para>
+ <figure id="master_node_fail.fig">
+ <title>Topology after the Master Node fails</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/master_node_fail.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <section>
+ <title>HASingleton Deployment Options</title>
+ <para>
+ The JBoss Application Server (AS) provides support for a number of
+ strategies for helping you deploy clustered singleton services. In
+ this section we will explore the different strategies. All of the
+ strategies are built on top of the HAPartition service described
+ in the introduction. They rely on the <literal>HAPartition</literal>
+ to provide notifications when different nodes in the cluster start
+ and stop; based on those notifications each node in the cluster
+ can independently (but consistently) determine if it is now the
+ master node and needs to begin providing a service.
+ </para>
+
+
+ <section>
+ <title>HASingletonDeployer service</title>
+ <para>
+ 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 deploy) and deploy it in the
+ <literal>$JBOSS_HOME/server/all/deploy-hasingleton</literal>
+ directory instead of in <literal>deploy</literal>. The
+ <literal>deploy-hasingleton</literal> directory does not lie under
+ deploy or farm, so its contents are not automatically deployed
+ when an AS instance starts. Instead, deploying the contents of this
+ directory is the responsibility of a special service, the
+ <literal>jboss.ha:service=HASingletonDeployer</literal>
+ MBean (which itself is deployed via the
+ deploy/deploy-hasingleton-service.xml file.) The
+ HASingletonDeployer service is itself an HA Singleton, one whose
+ provided service when it becomes master is to deploy the
+ contents of deploy-hasingleton and whose service when it stops
+ being the master (typically at server shutdown) is to undeploy
+ the contents of <literal>deploy-hasingleton</literal>.
+ </para>
+ <para>
+ So, by placing your deployments in <literal>deploy-hasingleton</literal>
+ you know that they will be deployed only on the master node in
+ the cluster. If the master node cleanly shuts down, they will be
+ cleanly undeployed as part of shutdown. If the master node fails
+ or is shut down, they will be deployed on whatever node takes
+ over as master.
+ </para>
+ <para>
+ Using deploy-hasingleton is very simple, but it does
+ have two drawbacks:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ There is no hot-deployment feature for services in
+ <literal>deploy-hasingleton</literal>
+ . Redeploying a service that has been deployed to
+ <literal>deploy-hasingleton</literal>
+ requires a server restart.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the master node fails and another node takes over
+ as master, your singleton service needs to go through the
+ entire deployment process before it will be providing
+ services. Depending on how complex the deployment of your
+ service is and what sorts of startup activities it engages
+ in, this could take a while, during which time the service
+ is not being provided.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Mbean deployments using HASingletonController</title>
+ <para>
+ If your service is an Mbean (i.e., not a J2EE deployment like an ear
+ or war or jar), you can deploy it along with a service called an
+ HASingletonController in order to turn it into an HA singleton.
+ It is the job of the HASingletonController to work with the
+ HAPartition service to monitor the cluster and determine if it
+ is now the master node for its service. If it determines it has
+ become the master node, it invokes a method on your service
+ telling it to begin providing service. If it determines it is no
+ longer the master node, it invokes a method on your service
+ telling it to stop providing service. Let's walk through an
+ illustration.
+ </para>
+ <para>
+ First, we have an MBean service that we want to make
+ an HA singleton. The only thing special about it is it needs to
+ expose in its MBean interface a method that can be called when
+ it should begin providing service, and another that can be
+ called when it should stop providing service:
+ </para>
+
+ <programlisting><![CDATA[
+public class HASingletonExample implements HASingletonExampleMBean
+{
+ private boolean isMasterNode = false;
+
+ public void startSingleton()
+ {
+ isMasterNode = true;
+ }
+
+ public boolean isMasterNode()
+ {
+ return isMasterNode;
+ }
+
+ public void stopSingleton()
+ {
+ isMasterNode = false;
+ }
+}
+]]></programlisting>
+
+ <para>
+ We used <literal>startSingleton</literal> and <literal>stopSingleton</literal>
+ in the above example, but you could name the methods anything.
+ </para>
+ <para>
+ Next, we deploy our service, along with an HASingletonController
+ to control it, most likely packaged in a .sar file, with the
+ following <literal>META-INF/jboss-service.xml</literal>:
+ </para>
+ <programlisting><![CDATA[
+<server>
+ <!-- This MBean is an example of a clustered singleton -->
+ <mbean code="org.jboss.ha.examples.HASingletonExample"
+ name=“jboss:service=HASingletonExample"/>
+
+ <!-- This HASingletonController manages the cluster Singleton -->
+ <mbean code="org.jboss.ha.singleton.HASingletonController"
+ name="jboss:service=ExampleHASingletonController">
+
+ <!-- Inject a ref to the HAPartition -->
+ <depends optional-attribute-name="ClusterPartition" proxy-type="attribute">
+ jboss:service=${jboss.partition.name:DefaultPartition}
+ </depends>
+ <!-- Inject a ref to the service being controlled -->
+ <depends optional-attribute-name="TargetName">jboss:service=HASingletonExample</depends>
+
+ <!-- Methods to invoke when become master / stop being master -->
+ <attribute name="TargetStartMethod">startSingleton</attribute>
+ <attribute name="TargetStopMethod">stopSingleton</attribute>
+ </mbean>
+</server>
+]]></programlisting>
+
+ <para>Voila! A clustered singleton service.</para>
+ <para>
+ The obvious downside to this approach is it only works for
+ MBeans. Upsides are that the above example can be placed in
+ <literal>deploy</literal> or <literal>farm</literal>
+ and thus can be hot deployed and farmed deployed. Also, if our
+ example service had complex, time-consuming startup
+ requirements, those could potentially be implemented in create()
+ or start() methods. JBoss will invoke create() and start() as
+ soon as the service is deployed; it doesn't wait until the node
+ becomes the master node. So, the service could be primed and
+ ready to go, just waiting for the controller to implement
+ startSingleton() at which point it can immediately provide
+ service.
+ </para>
+ <para>
+ The jboss.ha:service=HASingletonDeployer service discussed above
+ is itself an interesting example of using an
+ HASingletonController. Here is its deployment descriptor
+ (extracted from the <literal>deploy/deploy-hasingleton-service.xml</literal>
+ file):
+ </para>
+ <programlisting><![CDATA[
+<mbean code="org.jboss.ha.singleton.HASingletonController"
+ name="jboss.ha:service=HASingletonDeployer">
+ <depends optional-attribute-name="ClusterPartition" proxy-type="attribute">
+ jboss:service=${jboss.partition.name:DefaultPartition}
+ </depends>
+ <depends optional-attributeame="TargetName">
+ jboss.system:service=MainDeployer
+ </depends>
+ <attribute name="TargetStartMethod">deploy</attribute>
+ <attribute name="TargetStartMethodArgument">
+ ${jboss.server.home.url}/deploy-hasingleton
+ </attribute>
+ <attribute name="TargetStopMethod">undeploy</attribute>
+ <attribute name="TargetStopMethodArgument">
+ ${jboss.server.home.url}/deploy-hasingleton
+ </attribute>
+</mbean>
+]]></programlisting>
+
+ <para>
+ A few interesting things here. First the service being
+ controlled is the <literal>MainDeployer</literal>
+ service, which is the core deployment service in JBoss. That is,
+ it's a service that wasn't written with an intent that it be
+ controlled by an <literal>HASingletonController</literal>.
+ But it still works! Second, the target start and stop methods
+ are <literal>deploy</literal> and <literal>undeploy</literal>.
+ No requirement that they have particular names, or even that they
+ logically have <emphasis>start</emphasis> and <emphasis>stop</emphasis>
+ functionality. Here the functionality of the invoked methods is more like
+ <emphasis>do</emphasis> and <emphasis>undo</emphasis>. Finally, note the
+ <literal>TargetStart(Stop)MethodArgument</literal> attributes.
+ Your singleton service's start/stop methods can take an argument,
+ in this case the location of the directory the <literal>MainDeployer</literal>
+ should deploy/undeploy.
+ </para>
+ </section>
+
+ <section>
+ <title>HASingleton deployments using a Barrier</title>
+ <para>
+ Services deployed normally inside deploy or farm
+ that want to be started/stopped whenever the content of
+ deploy-hasingleton gets deployed/undeployed, (i.e., whenever the
+ current node becomes the master), need only specify a dependency
+ on the Barrier mbean:
+ </para>
+ <programlisting><![CDATA[
+<depends>jboss.ha:service=HASingletonDeployer,type=Barrier</depends>
+]]></programlisting>
+
+ <para>
+ The way it works is that a BarrierController is deployed along with the
+ jboss.ha:service=HASingletonDeployer MBean and listens for JMX
+ notifications from it. A BarrierController is a relatively
+ simple Mbean that can subscribe to receive any JMX notification
+ in the system. It uses the received notifications to control the
+ lifecycle of a dynamically created Mbean called the Barrier.The
+ Barrier is instantiated, registered and brought to the CREATE
+ state when the BarrierController is deployed. After that, the
+ BarrierController starts and stops the Barrier when matching JMX
+ notifications are received. Thus, other services need only
+ depend on the Barrier MBean using the usual <depends> tag, and
+ they will be started and stopped in tandem with the Barrier.
+ When the BarrierController is undeployed the Barrier is destroyed too.
+ </para>
+ <para>
+ This provides an alternative to the deploy-hasingleton approach in that we can use
+ farming to distribute the service, while content in deploy-hasingleton must be copied
+ manually on all nodes.
+ </para>
+ <para>
+ On the other hand, the barrier-dependent service will be instantiated/created (i.e., any create() method invoked) on all nodes, but only started on the master node. This is different with the deploy-hasingleton approach that will only deploy (instantiate/create/start) the contents of the deploy-hasingleton directory on one of the nodes.
+ </para>
+ <para>
+ So services depending on the barrier will need to make sure they do minimal or no work inside their create() step, rather they should use start() to do the work.
+ </para>
+ <note>
+ <title>Note</title>
+ <para>
+ The Barrier controls the start/stop of dependent services, but not their destruction,
+ which happens only when the <literal>BarrierController</literal> is itself destroyed/undeployed.
+ Thus using the <literal>Barrier</literal> to control services that need to be "destroyed" as part of their normal “undeploy” operation (like, for example, an <literal>EJBContainer</literal>) will not have the desired effect.
+ </para>
+ </note>
+ </section>
+</section>
+
+ <section>
+ <title>Determining the master node</title>
+ <para>
+ The various clustered singleton management strategies all depend on the fact that each node in the cluster can independently react to changes in cluster membership and correctly decide whether it is now the “master node”. How is this done?
+ </para>
+ <para>
+ Prior to JBoss AS 4.2.0, the methodology for this was fixed and simple.
+ For each member of the cluster, the HAPartition mbean maintains an attribute called the CurrentView, which is basically an ordered list of the current members of the cluster.
+ As nodes join and leave the cluster, JGroups ensures that each surviving member of the cluster gets an updated view.
+ You can see the current view by going into the JMX console, and looking at the CurrentView attribute in the <literal>jboss:service=DefaultPartition</literal> mbean.
+ Every member of the cluster will have the same view, with the members in the same order.
+ </para>
+ <para>
+ Let's say, for example, that we have a 4 node cluster, nodes A through D, and the current view can be expressed as {A, B, C, D}.
+ Generally speaking, the order of nodes in the view will reflect the order in which they joined the cluster (although this is not always the case, and should not be assumed to be the case).
+ </para>
+ <para>
+ To further our example, let's say there is a singleton service (i.e. an <literal>HASingletonController</literal>) named Foo that's deployed around the cluster, except, for whatever reason, on B.
+ The <literal>HAPartition</literal> service maintains across the cluster a registry of what services are deployed where, in view order.
+ So, on every node in the cluster, the <literal>HAPartition</literal> service knows that the view with respect to the Foo service is {A, C, D} (no B).
+ </para>
+ <para>
+ Whenever there is a change in the cluster topology of the Foo service, the <literal>HAPartition</literal> service invokes a callback on Foo notifying it of the new topology.
+ So, for example, when Foo started on D, the Foo service running on A, C and D all got callbacks telling them the new view for Foo was {A, C, D}.
+ That callback gives each node enough information to independently decide if it is now the master.
+ The Foo service on each node does this by checking if they are the first member of the view – if they are, they are the master; if not, they're not.
+ Simple as that.
+ </para>
+ <para>
+ If A were to fail or shutdown, Foo on C and D would get a callback with a new view for Foo of {C, D}.
+ C would then become the master.
+ If A restarted, A, C and D would get a callback with a new view for Foo of {C, D, A}.
+ C would remain the master – there's nothing magic about A that would cause it to become the master again just because it was before.
+ </para>
+
+ <section>
+ <title>HA singleton election policy</title>
+ <para>
+ The <literal>HASingletonElectionPolicy</literal> object is responsible for electing a master node from a list of available nodes, on behalf of an HA singleton, following a change in cluster topology.
+ </para>
+ <programlisting><![CDATA[
+public interface HASingletonElectionPolicy
+{
+ ClusterNode elect(List<ClusterNode> nodes);
+}
+]]></programlisting>
+ <para>
+ JBoss ships with 2 election policies:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>HASingletonElectionPolicySimple</literal></term>
+ <listitem>
+ <para>
+ This policy selects a master node based relative age.
+ The desired age is configured via the <literal>position</literal> property, which corresponds to the index in the list of available nodes.
+ <literal>position = 0</literal>, the default, refers to the oldest node; <literal>position = 1</literal>, refers to the 2nd oldest; etc.
+ <literal>position</literal> can also be negative to indicate youngness; imagine the list of available nodes as a circular linked list.
+ <literal>position = -1</literal>, refers to the youngest node; <literal>position = -2</literal>, refers to the 2nd youngest node; etc.
+ </para>
+ <programlisting><![CDATA[
+<bean class="org.jboss.ha.singleton.HASingletonElectionPolicySimple">
+ <property name="position">-1</property>
+</bean>
+]]></programlisting>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>PreferredMasterElectionPolicy</literal></term>
+ <listitem>
+ <para>
+ This policy extends <literal>HASingletonElectionPolicySimple</literal>, allowing the configuration of a preferred node.
+ The <literal>preferredMaster</literal> property, specified as <emphasis>host:port</emphasis> or <emphasis>address:port</emphasis>, identifies a specific node that should become master, if available.
+ If the preferred node is not available, the election policy will behave as described above.
+ </para>
+ <programlisting><![CDATA[
+<bean class="org.jboss.ha.singleton.PreferredMasterElectionPolicy">
+ <property name="preferredMaster">server1:12345</property>
+</bean>
+]]></programlisting>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ </section>
+
+ </section>
+
+ <section id="clustering-intro-farm">
+ <title>Farming Deployment</title>
+
+ <para>The Farm Service previously available in JBoss 4.x is not available
+ in JBoss 5.0 as it was incompatible with the new Profile Service at
+ the core of the AS. A new Profile Service-based replacement for the
+ Farm Service will be added in a future release.</para>
+<!--
+ <para>The easiest way to deploy an application into the cluster is to use the farming service. That is
+ to hot-deploy the application archive file (e.g., the EAR, WAR or SAR file) in the
+ <code>all/farm/</code> directory of any of the cluster members and the application will be automatically
+ duplicated across all nodes in the same cluster. If node joins the cluster later, it will pull in
+ all farm deployed applications in the cluster and deploy them locally at start-up time. If you
+ delete the application from one of the running cluster server node's <literal>farm/</literal>
+ folder, the application will be undeployed locally and then removed from all other cluster server
+ nodes farm folder (triggers undeployment.) You should manually delete the application from the farm
+ folder of any server node not currently connected to the cluster.</para>
+ <note>
+ <para>Currently, due to an implementation weakness, the farm deployment service only works for 1) archives located in the farm/ directory of the first node to join the cluster or 2) hot-deployed archives. If you first put a new application in the farm/ directory and then start the server to have it join an already running cluster, the application will not be pushed across the cluster or deployed. This is because the farm service does not know whether the application really represents a new deployment or represents an old deployment that was removed from the rest of the cluster while the newly starting node was off-line. We are working to resolve this issue.</para>
+ </note>
+ <note>
+ <para>You can only put zipped archive files, not exploded directories, in the farm directory. If exploded directories are placed in farm the directory contents will be replicated around the cluster piecemeal, and it is very likely that remote nodes will begin trying to deploy things before all the pieces have arrived, leading to deployment failure. </para>
+ </note>
+ <note>
+ <para>Farmed deployment is not atomic. A problem deploying, undeploying or redeploying an application on one node in the cluster will not prevent the deployment, undeployment or redeployment being done on the other nodes. There is no rollback capability. Deployment is also not staggered; it is quite likely, for example, that a redeployment will happen on all nodes in the cluster simultaneously, briefly leaving no nodes in the cluster providing service.
+ </para>
+ </note>
+
+ <para>Farming is enabled by default in the <literal>all</literal> configuration in JBoss AS
+ distributions, so you will not have to set it up yourself. The <literal>farm-service.xml</literal> configuration file is located in the deploy/deploy.last directory. If you want to enable farming in a custom configuration, simply copy the farm-service.xml file and copy it to the JBoss deploy directory <literal>$JBOSS_HOME/server/your_own_config/deploy/deploy.last</literal>. Make sure that your custom configuration has clustering enabled.</para>
+ <para>
+ After deploying farm-service.xml you are ready to rumble. The required FarmMemberService MBean attributes for configuring a farm are listed below.
+</para>
+ <programlisting>
+<?xml version="1.0" encoding="UTF-8"?>
+<server>
+
+ <mbean code="org.jboss.ha.framework.server.FarmMemberService"
+ name="jboss:service=FarmMember,partition=DefaultPartition">
+ ...
+
+ <depends optional-attribute-name="ClusterPartition"
+ proxy-type="attribute">
+ jboss:service=${jboss.partition.name:DefaultPartition}
+ </depends>
+ <attribute name="ScanPeriod">5000</attribute>
+ <attribute name="URLs">farm/</attribute>
+ ...
+ </mbean>
+</server>
+ </programlisting>
+
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">ClusterPartition</emphasis> is a required attribute to inject the HAPartition service that the farm service uses for intra-cluster communication.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">URLs</emphasis> points to the directory where deployer watches for
+ files to be deployed. This MBean will create this directory is if does not already exist.
+ If a full URL is not provided, it is assumed that the value is a filesytem path relative to the configuration directory (e.g. <literal>$JBOSS_HOME/server/all/</literal>).</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">ScanPeriod</emphasis> specifies the interval at which the folder
+ must be scanned for changes.. Its default value is <literal>5000</literal>.</para>
+ </listitem>
+ </itemizedlist>
+ <para>The farming service is an extension of the <literal>URLDeploymentScanner</literal>, which scans for hot deployments in the <literal>deploy/</literal> directory. So, you can use all the attributes
+ defined in the <literal>URLDeploymentScanner</literal> MBean in the
+ <literal>FarmMemberService</literal> MBean. In fact, the <literal>URLs</literal> and
+ <literal>ScanPeriod</literal> attributes listed above are inherited from the
+ <literal>URLDeploymentScanner</literal> MBean.</para>
+-->
+ </section>
+
+ <!--
+ <section id="clustering-intro-state">
+ <title>Distributed state replication services</title>
+ <para>In a clustered server environment, distributed state management is a key service the cluster must
+ provide. For instance, in a stateful session bean application, the session state must be
+ synchronized among all bean instances across all nodes, so that the client application reaches the
+ same session state no matter which node serves the request. In an entity bean application, the bean
+ object sometimes needs to be cached across the cluster to reduce the database load. Currently, the state replication and distributed cache services in JBoss AS are provided via three ways: the <literal>HASessionState</literal> Mbean, the <literal>DistributedState</literal> MBean and the JBoss Cache framework.</para>
+ <itemizedlist>
+ <listitem>
+ <para>The <literal>HASessionState</literal> MBean is a legacy service that provides session replication and distributed cache services for EJB 2.x stateful session beans. The MBean is defined in the <literal>all/deploy/cluster-service.xml</literal> file. We will show its configuration options in the EJB 2.x stateful session bean section later.</para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>DistributedState</literal> Mbean is a legacy service built on the HAPartition service. It is supported for backwards compatibility reasons, but new applications should not use it; they should use the much more sophisticated JBoss Cache instead.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ As mentioned above JBoss Cache is used to provide cache services for HTTP sessions, EJB 3.0 session beans and EJB 3.0 entity beans. It is the primary distributed state management tool in JBoss AS, and is an excellent choice for any custom caching requirements your applications may have. We will cover JBoss Cache in more detail when we discuss specific services in the next several sections..</para>
+ </listitem>
+ </itemizedlist>
+
+ </section>
+ -->
+ </chapter>
+
Property changes on: projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Deployment.xml
___________________________________________________________________
Name: svn:executable
+ *
Name: svn:keywords
+
Modified: projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Introduction.xml
===================================================================
--- projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Introduction.xml 2009-02-20 18:21:08 UTC (rev 84564)
+++ projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Introduction.xml 2009-02-20 18:51:00 UTC (rev 84565)
@@ -1,13 +1,9 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
- <chapter id="cluster.chapt">
- <title>JBoss Application Server Clustering Basics</title>
- <subtitle>High Availability Enterprise Services via JBoss Clusters</subtitle>
+ <chapter id="clustering-intro.chapt">
+ <title>Introduction and Quick Start</title>
- <section id="clustering-intro">
- <title>Introduction</title>
-
<para>
Clustering allows you to run an application on several parallel servers
(a.k.a cluster nodes) while providing a single view to application
@@ -89,7 +85,7 @@
configuration of JGroups, the core technology that underlies JBoss AS
Clustering.
</para>
- </section>
+
<section id="clustering-quickstart">
<title>Quick Start Guide</title>
<para>
@@ -478,784 +474,8 @@
</section>
- <section id="clustering-concepts">
- <title>Clustering Concepts</title>
- <para>
- In the next section, we discuss basic concepts behind JBoss's clustering
- services. It is helpful that you understand these concepts before reading
- the rest of the Clustering Guide. Clustering configurations for specific
- types of applications are covered beginning with the next chapter.
- </para>
- <section id="clustering-concepts-def">
- <title>Cluster Definition</title>
- <para>
- A cluster is a set of nodes that communicate with each other and work
- toward a common goal. In a JBoss Application Server cluster (also known
- as a “partition”), a node is an JBoss Application Server instance.
- Communication between the nodes is handled by the JGroups group communication
- library, with a JGroups Channel providing the core functionality of tracking
- who is in the cluster and reliably exchanging messages between the cluster
- members. JGroups channels with the same configuration and name have the
- ability to dynamically discover each other and form a group. This is why
- simply executing “run -c all” on two AS instances on the same network is
- enough for them to form a cluster – each AS starts a Channel (actually,
- several) with the same default configuration, so they dynamically discover
- each other and form a cluster. Nodes can be dynamically added to or removed
- from clusters at any time, simply by starting or stopping a Channel with a
- configuration and name that matches the other cluster members.
-
- In summary, a JBoss cluster is a set of AS server instances each of which
- is running an identically configured and named JGroups Channel.
- </para>
- <para>
- On the same AS instance, different services can create their own Channel.
- In a default 5.0.x AS, four different services create channels – the web
- session replication service, the EJB3 SFSB replication service, the EJB3
- entity caching service, and a core general purpose clustering service known
- as HAPartition. In order to differentiate these channels, each must have a
- unique name, and its configuration must match its peers yet differ from the
- other channels.
- </para>
- <para>
- So, if you go to two AS 5.0.x instances and execute <literal>run -c all</literal>,
- 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
- cluster, but it's important to understand that you really have 4 channels,
- and hence 4 two node clusters.
- </para>
-
- <para>On the same network, even for the same service, we may have different clusters.
- <xref linkend="clustering-Partition.fig"/> shows an example network of JBoss
- server instances divided into three clusters, with the third cluster only
- having one node. This sort of topology can be set up simply by configuring
- the AS instances such that within a set of nodes meant to form a cluster the
- Channel configurations and names match while they differ from any other
- channels on the same network. </para>
- <figure id="clustering-Partition.fig">
- <title>Clusters and server nodes</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/clustering-Partition.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>
- The section on “JGroups Configuration” and on “Isolating JGroups Channels”
- covers in detail how to configure Channels such that desired peers find
- each other and unwanted peers do not. As mentioned above, by default JBoss
- AS uses four separate JGroups Channels. These can be divided into two
- broad categories: the Channel used by the general purpose HAPartition
- service, and three Channels created by JBoss Cache for special purpose
- caching and cluster wide state replication.
- </para>
-</section>
-
-<section id="clustering-concepts-arch">
- <title>Service Architectures</title>
- <para>The clustering topography defined by the <literal>HAPartition</literal>
- MBean on each node is of great importance to system administrators. But for
- most application developers, you are probably more concerned about the cluster
- architecture from a client application's point of view. Two basic clustering
- architectures are used with JBoss AS: client-side interceptors (a.k.a smart
- proxies or stubs) and external load balancers. Which architecture your
- application will use will depend on what type of client you have.
- </para>
-
-
- <section id="clustering-concepts-arch-proxy">
- <title>Client-side interceptor architecture</title>
-<para>
- Most remote services provided by the JBoss application server, including
- JNDI, EJB, JMS, RMI and JBoss Remoting, require the client to obtain
- (e.g., 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
- object. The proxy automatically routes the call across the network where
- it is invoked against service objects managed in the server. The proxy
- object figures out how to find the appropriate server node, marshal call
- parameters, un-marshall call results, and return the result to the caller
- client. In a clustered environment, the server-generated proxy object includes an
- interceptor that understands how to route calls to multiple nodes in the
- cluster.
-</para>
-
-
-<para>The proxy's clustering logic maintains up-to-date knowledge about
- the cluster. For instance, it knows the IP addresses of all available
- server nodes, the algorithm to distribute load across nodes (see next section),
- and how to failover the request if the target node not available.
- As part of handling each service request, if the cluster topology has
- changed the server node updates the proxy with the latest changes
- in the cluster. For instance, if a node drops out of the cluster, each
- proxy is updated with the new topology the next time it connects to any
- active node in the cluster. All the manipulations done by the proxy's
- clustering logic are transparent to the client application. The client-side
- interceptor clustering architecture is illustrated in <xref linkend="clustering-InterceptorArch.fig"/>.
-</para>
- <figure id="clustering-InterceptorArch.fig">
- <title>The client-side interceptor (proxy) architecture for clustering</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/clustering-InterceptorArch.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <note>
- <para><xref linkend="clustering-session-slsb21"/> describes how to enable the client proxy
- to handle the entire cluster restart.</para>
- </note>
- </section>
- <section id="clustering-concepts-arch-balancer">
- <title>External Load Balancer Architecture</title>
- <para>
- Other JBoss services, in particular the HTTP-based services, do not
- require the client to download anything. The client (e.g., a web browser)
- sends in requests and receives responses directly over the wire using
- to certain communication protocols (e.g., the HTTP protocol). In this
- case, an external load balancer is required to process all requests and
- dispatch them to server nodes in the cluster. The client only needs to know
- how to contact the load balancer; it has no knowledge of the JBoss AS
- instances behind the load balancer. The load balancer is logically part
- of the cluster, but we refer to it as “external” because it is not running
- in the same process as either the client or any of the JBoss AS instances.
- It can be implemented either in software or hardware. There are many
- vendors of hardware load balancers; the mod_jk Apache module is an excellent
- example of a software load balancer. An external load balancer implements
- its own mechanism for understanding the cluster configuration and provides
- its own load balancing and failover policies. The external load balancer
- clustering architecture is illustrated in <xref linkend="clustering-BalancerArch.fig"/>.
- </para>
- <figure id="clustering-BalancerArch.fig">
- <title>The external load balancer architecture for clustering</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/clustering-BalancerArch.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>
- A potential problem with an external load balancer architecture is that
- the load balancer itself may be a single point of failure. It needs to be
- monitored closely to ensure high availability of the entire cluster's services.
- </para>
- </section>
-
-</section>
-
-<section id="clustering-concepts-balancepolicy">
- <title>Load-Balancing Policies</title>
- <para>
- Both the JBoss client-side interceptor (stub) and load balancer use load balancing policies to determine which server node to which node a new request should be sent. In this section, let's go over the load balancing policies available in JBoss AS.
- </para>
- <section id="clustering-concepts-balancepolicy-30">
- <title>Client-side interceptor architecture</title>
- <para>
- In JBoss 5.0.0, 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.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Round-Robin (<literal>org.jboss.ha.framework.interfaces.RoundRobin</literal>): 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.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Random-Robin (<literal>org.jboss.ha.framework.interfaces.RandomRobin</literal>): for each call the target node is randomly selected from the list.
- </para>
- </listitem>
- <listitem>
- <para>
- First Available (<literal>org.jboss.ha.framework.interfaces.FirstAvailable</literal>): 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 stub elects its own target node independently of the other stubs, so if a particular client downloads two stubs for the same target service (e.g., an EJB), each stub will independently pick its target. This is an example of a policy that provides “session affinity” or “sticky sessions”, since the target node does not change once established.
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- First Available Identical All Proxies (<literal>org.jboss.ha.framework.interfaces.FirstAvailableIdenticalAllProxies</literal>): has the same behaviour as the "First Available" policy but the elected target node is shared by all stubs in the same client-side VM that are associated with the same target service. So if a particular client downloads two stubs for the same target service (e.g. an EJB), each stub will use the same target.
- </para>
- </listitem>
-
- </itemizedlist>
- <para>
- Each of the above is an implementation of the org.jboss.ha.framework.interfaces.LoadBalancePolicy interface; users are free to write their own implementation of this simple interface if they need some special behavior. In later sections we'll see how to configure the load balance policies used by different services.
- </para>
-</section>
- <section><title>External load balancer architecture</title>
-
-<para>
-As noted above, an external load balancer provides its own load balancing capabilities. What capabilities are supported depends on the provider of the load balancer. The only JBoss requirement is that the load balancer support “session affinity” (a.k.a. “sticky sessions”). With session affinitiy enabled, once the load balancer routes a request from a client to node A and the server initiates a session, all future requests associated with that session must be routed to node A, so long as node A is available.
- </para>
-
-
- </section>
-</section>
- </section>
-
- <section id="clustering-blocks">
- <title>Clustering Building Blocks</title>
-
- <para>The clustering features in JBoss AS 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:
- </para>
-
- <figure id="clustering-as-arch.fig">
- <title>The JBoss AS clustering architecture</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/clustering-as-arch.png" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para><emphasis role="bold">JGroups</emphasis> 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 AS cluster.
- See <xref linkend="clustering-blocks-jgroups"/> for more on how JBoss AS
- uses JGroups.</para>
-
- <para><emphasis role="bold">JBoss Cache</emphasis> is a highly flexible
- clustered transactional caching library. Many AS clustering services
- need to cache some state in memory while 1) ensuring for high availability
- purposes that a backup copy of that state is available on another node
- if it can't otherwise be recreated (e.g. the contents of a web session)
- and 2) ensuring that the data cached on each node in the cluster is consistent.
- JBoss Cache handles these concerns for most JBoss AS clustered services.
- JBoss Cache uses JGroups to handle its group communication requirements.
- <emphasis role="bold">POJO Cache</emphasis> is an extension of the
- core JBoss Cache that JBoss AS uses to support fine-grained replication
- of clustered web session state. See <xref linkend="clustering-blocks-jbc"/>
- for more on how JBoss AS uses JBoss Cache and POJO Cache.</para>
-
- <para><emphasis role="bold">HAPartition</emphasis> is an adapter on top
- of a JGroups channel that allows multiple services to use the channel.
- HAPartition also supports a distributed registry of which HAPartition-based
- services are running on which cluster members. It provides notifications to
- interested listeners when the cluster membership changes or the clustered
- service registry changes. See <xref linkend="clustering-hapartition"/> for
- more details on HAPartition.</para>
-
- <para>The other higher level clustering services make use of JBoss Cache
- or HAPartition, or, in the case of HA-JNDI, both. The exception to this
- is JBoss Messaging's clustering features, which interact with JGroups
- directly.</para>
-
- <section id="clustering-blocks-jgroups">
- <title>Group Communication with JGroups</title>
- <para></para>
-
- <section id="clustering-blocks-jgroups-sharedtransport">
- <title>The JGroups Shared Transport</title>
- <para></para>
- </section>
-
- <section id="clustering-blocks-jgroups-channelfactory">
- <title>The Channel Factory Service</title>
- <para></para>
- </section>
- </section>
-
- <section id="clustering-hapartition">
- <title>The HAPartition Service</title>
- <para>
- HAPartition is a general purpose service used for a variety of tasks
- in AS clustering. At its core, it is an abstraction built on top of
- a JGroups Channel that provides support for making/receiving RPC
- invocations on/from one or more cluster members. HAPartition also
- supports a distributed registry of which clustering services are
- running on which cluster members. It provides notifications to
- interested listeners when the cluster membership changes or the
- clustered service registry changes. HAPartition 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, EJB 2 SFSB
- replication and entity cache management, farming, HA-JNDI and HA singletons.
- Custom services can also make use of HAPartition.
- </para>
-
-
-
- <para>The following example shows the <literal>HAPartition</literal> MBean definition packaged with the standard JBoss AS distribution.
- So, if you simply start JBoss servers with their default clustering settings on a local network, you
- would get a default cluster named <literal>DefaultPartition</literal> that includes all server
- instances as its nodes.</para>
- <programlisting>
-<mbean code="org.jboss.ha.framework.server.ClusterPartition"
- name="jboss:service=DefaultPartition">
-
- <! -- Name of the partition being built -->
- <attribute name="PartitionName">
- ${jboss.partition.name:DefaultPartition}
- </attribute>
-
- <! -- The address used to determine the node name -->
- <attribute name="NodeAddress">${jboss.bind.address}</attribute>
-
- <! -- Determine if deadlock detection is enabled -->
- <attribute name="DeadlockDetection">False</attribute>
-
- <! -- Max time (in ms) to wait for state transfer to complete.
- Increase for large states -->
- <attribute name="StateTransferTimeout">30000</attribute>
-
- <! -- The JGroups protocol configuration -->
- <attribute name="PartitionConfig">
- ... ...
- </attribute>
-</mbean>
- </programlisting>
- <para>Here, we omitted the detailed JGroups protocol configuration for this channel. JGroups handles the
- underlying peer-to-peer communication between nodes, and its configuration is discussed in <xref linkend="jgroups.chapt"/>. The following list shows the available configuration attributes
- in the <literal>HAPartition</literal> MBean.</para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">PartitionName</emphasis> is an optional attribute to specify the
- name of the cluster. Its default value is <literal>DefaultPartition</literal>. Use the <literal>-g </literal> (a.k.a. --partition) command line switch to set this value at JBoss startup.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">NodeAddress</emphasis> is an optional attribute used to help generate a unique name for this node.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">DeadlockDetection</emphasis> is an optional boolean attribute that
- tells JGroups to run message deadlock detection algorithms with every request. Its default
- value is <literal>false</literal>.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">StateTransferTimeout</emphasis> is an optional attribute to specify the timeout for state replication across the cluster (in milliseconds). State replication refers to the process of obtaining initial application state from other already-running cluster members at service startup. Its default value is <literal>30000</literal>. </para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">PartitionConfig</emphasis> is an element to specify JGroup
- configuration options for this cluster (see <xref linkend="jgroups-configuration"/>).</para>
- </listitem>
- </itemizedlist>
- <para>In order for nodes to form a cluster, they must have the exact same <literal>PartitionName</literal> and the <literal>ParitionConfig</literal> elements. Changes in either element on some but not all nodes would cause the cluster to split.
- </para>
-
- <para>You can view the current cluster information by pointing your browser to the JMX console of any
- JBoss instance in the cluster (i.e., <literal>http://hostname:8080/jmx-console/</literal>) and then
- clicking on the <literal>jboss:service=HAPartition,partition=DefaultPartition</literal> MBean (change the MBean name to reflect your partitionr name if you use the -g startup switch). A list of IP addresses for the current cluster members is shown in the CurrentView field.</para>
-
- <note><title>Note</title>
- <para>
- While it is technically possible to put a JBoss server instance into multiple HAPartitions at the same time, this practice is generally not recommended, as it increases management complexity.
- </para>
- </note>
-
- <section id="clustering-hapartition-drm">
- <title>DistributedReplicantManager Service</title>
- <para>
- The <literal>DistributedReplicantManager</literal> (DRM) service is a component
- of the HAPartition service made available to HAPartition
- users via the <literal>HAPartition.getDistributedReplicantManager()</literal>
- method. Generally speaking, JBoss AS users will not directly make
- use of the DRM; we discuss it here as an aid to those who want a
- deeper understanding of how AS clustering internals work.</para>
- <para>
- The DRM is a distributed registry that allows HAPartition users to
- register objects under a given key, making available to callersthe
- set of objects registered under that key by the various members of t
- he cluster. The DRM also provides a notification mechanism so interested
- listeners can be notified when the contents of the registry changes.
- </para>
- <para>There are two main usages for the DRM in JBoss AS:</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">Clustered Smart Proxies</emphasis></para>
- <para>Here the keys are the names of the various services that need a
- clustered smart proxy (see <xref linkend="clustering-concepts-arch-proxy"/>,
- e.g. the name of a clustered EJB. The value object each node stores in
- the DRM is known as a "target". It's something a smart proxy's transport
- layer can use to contact the node (e.g. an RMI stub, an HTTP URL or a JBoss Remoting
- <literal>InvokerLocator</literal>). The factory that builds clustered smart
- proxies accesses the DRM to get the set of "targets" that should be
- injected into the proxy to allow it to communicate with all the
- nodes in a cluster.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">HASingleton</emphasis></para>
- <para>Here the keys are the names of the various services that need to
- function as High Availablity Singletons (see <xref linkend="clustering-hasingleton"/>).
- The value object each node stores in the DRM is simply a String that
- acts as a token to indicate that the node has the service deployed, and
- thus is a candidate to become the "master" node for the HA singleton
- service.</para>
- </listitem>
- </itemizedlist>
-
- <para>In both cases, the key under which objects are registered identifies
- a particular clustered service. It is useful to understand that every
- node in a cluster doesn't have to register an object under every key.
- Only services that are deployed on a particular node will register
- something under that service's key, and services don't have to be
- deployed homogeneously across the cluster. The DRM is thus useful as a
- mechanism for understanding a service's "topology" around the cluster
- -- which nodes have the service deployed.</para>
- </section>
-
- <section id="clustering-hapartition-distributedstate">
- <title>DistributedState Service</title>
- <para>
- The <literal>DistributedState</literal> service is a legacy component
- of the HAPartition service made available to HAPartition
- users via the <literal>HAPartition.getDistributedState()</literal>
- method. This service provides coordinated management of arbitary
- application state around the cluster. It is supported for backwards
- compatibility reasons, but new applications should not use it; they
- should use the much more sophisticated JBoss Cache instead.
- </para>
- <para>In JBoss 5 the <literal>DistributedState</literal> service actually
- delegates to an underlying JBoss Cache instance.</para>
- </section>
-
- <section id="clustering-hapartition-customsvcs">
- <title>Custom Use of HAPartition</title>
-
- <para>Custom services can also use make use of HAPartition to handle
- interactions with the cluster. Generally the easiest way to do this
- is to extend the <literal>org.jboss.ha.framework.server.HAServiceImpl</literal>
- base class, or the <literal>org.jboss.ha.jxm.HAServiceMBeanSupport</literal>
- class if JMX registration and notification support are desired.
- </para>
-
- </section>
-
-</section>
-
- <section id="clustering-blocks-jbc">
- <title>Distributed Caching with JBoss Cache</title>
- <para>
- JBoss Cache is a fully featured distributed cache framework that can be
- used in any application server environment or standalone. JBoss Cache
- provides the underlying distributed caching support used by many of the
- standard clustered services in a JBoss AS cluster, including:
- <itemizedlist>
- <listitem><para>Replication of clustered webapp sessions.</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>
- <listitem><para>DistributedStateService</para></listitem>
- </itemizedlist>
- </para>
-
- <para>Users can also create their own JBoss Cache and POJO Cache
- instances for custom use by their applications, see
- <xref linkend="jbosscache.chapt"/> for more on this.</para>
-
- <section id="clustering-blocks-jbc-cachemanager">
- <title>The JBoss AS CacheManager Service</title>
- <para>Many of the standard clustered services in JBoss AS use JBoss
- Cache to maintain consistent state across the cluster. Different
- services (e.g. web session clustering or second level caching of
- JPA/Hibernate entities) use different JBoss Cache instances, with
- each cache configured to meet the needs of the service that uses it.
- In AS 4, each of these caches was independently deployed in the
- <literal>deploy/</literal> directory, which had a number of disadvantages:
- <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>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.
- Using JMX for purposes other exposing management interfaces is just
- not the JBoss 5 way.</para></listitem>
- </itemizedlist>
- </para>
-
- <para>In JBoss 5, the scattered cache deployments have been replaced
- with a new <emphasis role="bold">CacheManager</emphasis> service,
- deployed via the <literal>JBOSS_HOME/server/all/deploy/cluster/jboss-cache-manager.sar</literal>.
- The CacheManager is a factory and registry for JBoss Cache instances.
- It is configured with a set of named JBoss Cache configurations.
- Services that need a cache ask the cache manager for the cache by
- name; the cache manager creates the cache (if not already created)
- and returns it. The cache manager keeps a reference to each cache
- it has created, so all services that request the same cache configuration
- name will share the same cache. When a service is done with the cache,
- it releases it to the cache manager. The cache manager keeps track
- of how many services are using each cache, and will stop and destroy
- the cache when all services have released it.</para>
-
- <section id="clustering-blocks-jbc-cachemanager-stdconfigs">
- <title>Standard Cache Configurations</title>
- <para>The following standard JBoss Cache configurations ship with JBoss AS 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 <literal>deploy/cluster/jboss-cache-manager.sar/META-INF/jboss-cache-manager-jboss-beans.xml</literal>
- 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
- in the documentation chapters for each service in this guide,
- it is not advisable to change them.</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">standard-session-cache</emphasis></para>
- <para>Standard cache used for web sessions.</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">field-granularity-session-cache</emphasis></para>
- <para>Standard cache used for FIELD granularity web sessions.</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">sfsb-cache</emphasis></para>
- <para>Standard cache used for EJB3 SFSB caching.</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">ha-partition</emphasis></para>
- <para>Used by web tier Clustered Single Sign-On,
- HA-JNDI, Distributed State.</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">mvcc-entity</emphasis></para>
- <para>A config appropriate for JPA/Hibernate entity/collection
- caching that uses JBC's MVCC locking (see notes below).</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">optimistic-entity</emphasis></para>
- <para>A config appropriate for JPA/Hibernate entity/collection
- caching that uses JBC's optimistic locking (see notes below).
- </para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">pessimistic-entity</emphasis></para>
- <para>A config appropriate for JPA/Hibernate entity/collection
- caching that uses JBC's pessimistic locking (see notes below).
- </para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">mvcc-entity-repeatable</emphasis></para>
- <para>Same as "mvcc-entity" but uses JBC's REPEATABLE_READ
- isolation level instead of READ_COMMITTED (see notes below).
- </para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">pessimistic-entity-repeatable</emphasis></para>
- <para>Same as "pessimistic-entity" but uses JBC's REPEATABLE_READ
- isolation level instead of READ_COMMITTED (see notes below).
- </para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">local-query</emphasis></para>
- <para>A config appropriate for JPA/Hibernate query result caching.
- Does not replicate query results. DO NOT store the timestamp data
- Hibernate uses to verify validity of query results in this cache.</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">replicated-query</emphasis></para>
- <para>A config appropriate for JPA/Hibernate query result caching.
- Replicates query results. DO NOT store the timestamp data
- Hibernate uses to verify validity of query result in this cache.</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">timestamps-cache</emphasis></para>
- <para>A config appropriate for the timestamp data cached as part
- of JPA/Hibernate query result caching. A replicated timestamp cache
- is required if query result caching is used, even if the query results
- themselves use a non-replicating cache like <literal>local-query</literal>.</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">mvcc-shared</emphasis></para>
- <para>A config appropriate for a cache that's shared for JPA/Hibernate
- entity, collection, query result and timestamp caching. Not an
- advised configuration, since it requires cache mode REPL_SYNC,
- which is the least efficient mode. Also requires a full state
- transfer at startup, which can be expensive. Maintained for
- backwards compatibility reasons, as a shared cache was the only
- option in JBoss 4. Uses JBC's MVCC locking.</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">optimistic-shared</emphasis></para>
- <para>A config appropriate for a cache that's shared for JPA/Hibernate
- entity, collection, query result and timestamp caching. Not an
- advised configuration, since it requires cache mode REPL_SYNC,
- which is the least efficient mode. Also requires a full state
- transfer at startup, which can be expensive. Maintained for
- backwards compatibility reasons, as a shared cache was the only
- option in JBoss 4. Uses JBC's optimistic locking.</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">pessimistic-shared</emphasis></para>
- <para>A config appropriate for a cache that's shared for JPA/Hibernate
- entity, collection, query result and timestamp caching. Not an
- advised configuration, since it requires cache mode REPL_SYNC,
- which is the least efficient mode. Also requires a full state
- transfer at startup, which can be expensive. Maintained for
- backwards compatibility reasons, as a shared cache was the only
- option in JBoss 4. Uses JBC's pessimistic locking.</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">mvcc-shared-repeatable</emphasis></para>
- <para>Same as "mvcc-shared" but uses JBC's REPEATABLE_READ
- isolation level instead of READ_COMMITTED (see notes below).
- </para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">pessimistic-shared-repeatable</emphasis></para>
- <para>Same as "pessimistic-shared" but uses JBC's REPEATABLE_READ
- isolation level instead of READ_COMMITTED. (see notes below).
- </para>
- </listitem>
-
- </itemizedlist>
-
- <note><para>For more on JBoss Cache's locking schemes, see
- <xref linkend="jbosscache-configuration-concurrency"/>)</para></note>
-
- <note><para>For JPA/Hibernate second level caching, REPEATABLE_READ is
- only useful if the application evicts/clears entities from the
- EntityManager/Hibernate Session and then expects to repeatably
- re-read them in the same transaction. Otherwise, the Session's
- internal cache provides a repeatable-read semantic.</para></note>
-
- </section>
-
- <section>
- <title>Cache Configuration Aliases</title>
- <para>The CacheManager also supports aliasing of caches; i.e.
- 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 config
- names. It's also useful for supporting legacy EJB3 application
- configurations ported over from AS 4.</para>
- <para>Aliases can be configured by editing the "CacheManager"
- bean in the <literal>jboss-cache-manager-jboss-beans.xml</literal>
- file. The following redacted config shows the standard aliases in
- AS 5.0.0.GA:</para>
-
- <programlisting><![CDATA[
-<bean name="CacheManager" class="org.jboss.ha.cachemanager.CacheManager">
-
- . . .
-
- <!-- Aliases for cache names. Allows caches to be shared across
- services that may expect different cache config names. -->
- <property name="configAliases">
- <map keyClass="java.lang.String" valueClass="java.lang.String">
- <!-- Use the HAPartition cache for ClusteredSSO caching -->
- <entry>
- <key>clustered-sso</key>
- <value>ha-partition</value>
- </entry>
- <!-- 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 -->
- <entry>
- <key>jboss.cache:service=EJB3EntityTreeCache</key>
- <value>mvcc-shared</value>
- </entry>
- </map>
- </property>
-
- . . .
-
-</bean>]]></programlisting>
- </section>
- </section>
- </section>
-
- </section>
-
- <section id="clustering-intro-farm">
- <title>Farming Deployment</title>
-
- <para>The Farm Service previously available in JBoss 4.x is not available
- in JBoss 5.0 as it was incompatible with the new Profile Service at
- the core of the AS. A new Profile Service-based replacement for the
- Farm Service will be added in a future release.</para>
-<!--
- <para>The easiest way to deploy an application into the cluster is to use the farming service. That is
- to hot-deploy the application archive file (e.g., the EAR, WAR or SAR file) in the
- <code>all/farm/</code> directory of any of the cluster members and the application will be automatically
- duplicated across all nodes in the same cluster. If node joins the cluster later, it will pull in
- all farm deployed applications in the cluster and deploy them locally at start-up time. If you
- delete the application from one of the running cluster server node's <literal>farm/</literal>
- folder, the application will be undeployed locally and then removed from all other cluster server
- nodes farm folder (triggers undeployment.) You should manually delete the application from the farm
- folder of any server node not currently connected to the cluster.</para>
- <note>
- <para>Currently, due to an implementation weakness, the farm deployment service only works for 1) archives located in the farm/ directory of the first node to join the cluster or 2) hot-deployed archives. If you first put a new application in the farm/ directory and then start the server to have it join an already running cluster, the application will not be pushed across the cluster or deployed. This is because the farm service does not know whether the application really represents a new deployment or represents an old deployment that was removed from the rest of the cluster while the newly starting node was off-line. We are working to resolve this issue.</para>
- </note>
- <note>
- <para>You can only put zipped archive files, not exploded directories, in the farm directory. If exploded directories are placed in farm the directory contents will be replicated around the cluster piecemeal, and it is very likely that remote nodes will begin trying to deploy things before all the pieces have arrived, leading to deployment failure. </para>
- </note>
- <note>
- <para>Farmed deployment is not atomic. A problem deploying, undeploying or redeploying an application on one node in the cluster will not prevent the deployment, undeployment or redeployment being done on the other nodes. There is no rollback capability. Deployment is also not staggered; it is quite likely, for example, that a redeployment will happen on all nodes in the cluster simultaneously, briefly leaving no nodes in the cluster providing service.
- </para>
- </note>
-
- <para>Farming is enabled by default in the <literal>all</literal> configuration in JBoss AS
- distributions, so you will not have to set it up yourself. The <literal>farm-service.xml</literal> configuration file is located in the deploy/deploy.last directory. If you want to enable farming in a custom configuration, simply copy the farm-service.xml file and copy it to the JBoss deploy directory <literal>$JBOSS_HOME/server/your_own_config/deploy/deploy.last</literal>. Make sure that your custom configuration has clustering enabled.</para>
- <para>
- After deploying farm-service.xml you are ready to rumble. The required FarmMemberService MBean attributes for configuring a farm are listed below.
-</para>
- <programlisting>
-<?xml version="1.0" encoding="UTF-8"?>
-<server>
-
- <mbean code="org.jboss.ha.framework.server.FarmMemberService"
- name="jboss:service=FarmMember,partition=DefaultPartition">
- ...
-
- <depends optional-attribute-name="ClusterPartition"
- proxy-type="attribute">
- jboss:service=${jboss.partition.name:DefaultPartition}
- </depends>
- <attribute name="ScanPeriod">5000</attribute>
- <attribute name="URLs">farm/</attribute>
- ...
- </mbean>
-</server>
- </programlisting>
-
-
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">ClusterPartition</emphasis> is a required attribute to inject the HAPartition service that the farm service uses for intra-cluster communication.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">URLs</emphasis> points to the directory where deployer watches for
- files to be deployed. This MBean will create this directory is if does not already exist.
- If a full URL is not provided, it is assumed that the value is a filesytem path relative to the configuration directory (e.g. <literal>$JBOSS_HOME/server/all/</literal>).</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">ScanPeriod</emphasis> specifies the interval at which the folder
- must be scanned for changes.. Its default value is <literal>5000</literal>.</para>
- </listitem>
- </itemizedlist>
- <para>The farming service is an extension of the <literal>URLDeploymentScanner</literal>, which scans for hot deployments in the <literal>deploy/</literal> directory. So, you can use all the attributes
- defined in the <literal>URLDeploymentScanner</literal> MBean in the
- <literal>FarmMemberService</literal> MBean. In fact, the <literal>URLs</literal> and
- <literal>ScanPeriod</literal> attributes listed above are inherited from the
- <literal>URLDeploymentScanner</literal> MBean.</para>
--->
- </section>
-
+
<!--
<section id="clustering-intro-state">
<title>Distributed state replication services</title>
More information about the jboss-cvs-commits
mailing list