[jboss-cvs] JBossAS SVN: r92817 - projects/docs/community/5/Clustering_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Aug 25 19:09:39 EDT 2009
Author: bstansberry at jboss.com
Date: 2009-08-25 19:09:39 -0400 (Tue, 25 Aug 2009)
New Revision: 92817
Modified:
projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Building_Blocks.xml
Log:
[JBAS-6358] Move HAPartition after JBC
Modified: 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 2009-08-25 23:04:52 UTC (rev 92816)
+++ projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Building_Blocks.xml 2009-08-25 23:09:39 UTC (rev 92817)
@@ -253,211 +253,7 @@
the stack name to the string "unnamed_", e.g. unnamed_customStack.</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 <literal>Channel</literal> that provides support for making/receiving RPC
- invocations on/from one or more cluster members. HAPartition allows
- services that use it to share a single <literal>Channel</literal> and
- multiplex RPC invocations over it, eliminating the configuration complexity
- and runtime overhead of having each service create its own <literal>Channel</literal>.
- 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 snippet shows the <literal>HAPartition</literal> service definition packaged with the standard JBoss AS distribution.
- This configuration can be found in the <literal>server/all/deploy/cluster/hapartition-jboss-beans.xml</literal> file.
- </para>
- <programlisting><![CDATA[
- <bean name="HAPartitionCacheHandler"
- class="org.jboss.ha.framework.server.HAPartitionCacheHandlerImpl">
- <property name="cacheManager"><inject bean="CacheManager"/></property>
- <property name="cacheConfigName">ha-partition</property>
- </bean>
-
- <bean name="HAPartition"
- class="org.jboss.ha.framework.server.ClusterPartition">
- <depends>jboss:service=Naming</depends>
-
- <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss:service=HAPartition,partition=${jboss.partition.name:DefaultPartition}", exposedInterface=org.jboss.ha.framework.server.ClusterPartitionMBean.class, registerDirectly=true)</annotation>
-
- <!-- ClusterPartition requires a Cache for state management -->
- <property name="cacheHandler"><inject bean="HAPartitionCacheHandler"/></property>
-
- <!-- Name of the partition being built -->
- <property name="partitionName">${jboss.partition.name:DefaultPartition}</property>
-
- <!-- The address used to determine the node name -->
- <property name="nodeAddress">${jboss.bind.address}</property>
-
- <!-- Max time (in ms) to wait for state transfer to complete. Increase for large states -->
- <property name="stateTransferTimeout">30000</property>
-
- <!-- Max time (in ms) to wait for RPC calls to complete. -->
- <property name="methodCallTimeout">60000</property>
-
- <!-- Optionally provide a thread source to allow async connect of our channel -->
- <property name="threadPool"><inject bean="jboss.system:service=ThreadPool"/></property>
-
- <property name="distributedStateImpl">
- <bean name="DistributedState"
- class="org.jboss.ha.framework.server.DistributedStateImpl">
- <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss:service=DistributedState,partitionName=${jboss.partition.name:DefaultPartition}", exposedInterface=org.jboss.ha.framework.server.DistributedStateImplMBean.class, registerDirectly=true)</annotation>
- <property name="cacheHandler"><inject bean="HAPartitionCacheHandler"/></property>
- </bean>
- </property>
-
- </bean>]]></programlisting>
- <para>Much of the above is boilerplate; below we'll touch on the key points
- relevant to end users. There are two beans defined above, the
- <literal>HAPartitionCacheHandler</literal> and the <literal>HAPartition</literal> itself.</para>
-
- <para>The <literal>HAPartition</literal> bean itself exposes the following
- configuration properties:</para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">partitionName</emphasis> specifies 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 unused and can be ignored.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">stateTransferTimeout</emphasis> specifies the timeout (in milliseconds) for initial application state transfer. State transfer refers to the process of obtaining a serialized copy of 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">methodCallTimeout</emphasis> specifies the timeout (in milliseconds) for obtaining responses to group RPCs from the other cluster members. Its default value is <literal>60000</literal>. </para>
- </listitem>
- </itemizedlist>
-
- <para>The <literal>HAPartitionCacheHandler</literal> is a small utility service that
- helps the HAPartition integrate with JBoss Cache
- (see <xref linkend="clustering-blocks-jbc-cachemanager"/>). HAPartition exposes
- a child service called DistributedState (see <xref linkend="clustering-hapartition-distributedstate"/>)
- that uses JBoss Cache; the <literal>HAPartitionCacheHandler</literal> helps ensure
- consistent configuration between the JGroups <literal>Channel</literal> used by
- Distributed State's cache and the one used directly by HAPartition.</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">cacheConfigName</emphasis> the name of the
- JBoss Cache configuration to use for the HAPartition-related cache.
- Indirectly, this also specifies the name of the JGroups protocol
- stack configuration HAPartition should use. See
- <xref linkend="jbosscache-configuration-jgroups"/> for more on
- how the JGroups protocol stack is configured.</para>
- </listitem>
- </itemizedlist>
-
- <para>In order for nodes to form a cluster, they must have the exact same <literal>partitionName</literal>
- and the <literal>HAPartitionCacheHandler</literal>'s <literal>cacheConfigName</literal>
- must specify an identical JBoss Cache configuration. Changes in either
- element on some but not all nodes would prevent proper clustering behavior.
- </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>
@@ -711,6 +507,210 @@
</section>
</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 <literal>Channel</literal> that provides support for making/receiving RPC
+ invocations on/from one or more cluster members. HAPartition allows
+ services that use it to share a single <literal>Channel</literal> and
+ multiplex RPC invocations over it, eliminating the configuration complexity
+ and runtime overhead of having each service create its own <literal>Channel</literal>.
+ 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 snippet shows the <literal>HAPartition</literal> service definition packaged with the standard JBoss AS distribution.
+ This configuration can be found in the <literal>server/all/deploy/cluster/hapartition-jboss-beans.xml</literal> file.
+ </para>
+ <programlisting><![CDATA[
+ <bean name="HAPartitionCacheHandler"
+ class="org.jboss.ha.framework.server.HAPartitionCacheHandlerImpl">
+ <property name="cacheManager"><inject bean="CacheManager"/></property>
+ <property name="cacheConfigName">ha-partition</property>
+ </bean>
+
+ <bean name="HAPartition"
+ class="org.jboss.ha.framework.server.ClusterPartition">
+
+ <depends>jboss:service=Naming</depends>
+
+ <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss:service=HAPartition,partition=${jboss.partition.name:DefaultPartition}", exposedInterface=org.jboss.ha.framework.server.ClusterPartitionMBean.class, registerDirectly=true)</annotation>
+
+ <!-- ClusterPartition requires a Cache for state management -->
+ <property name="cacheHandler"><inject bean="HAPartitionCacheHandler"/></property>
+
+ <!-- Name of the partition being built -->
+ <property name="partitionName">${jboss.partition.name:DefaultPartition}</property>
+
+ <!-- The address used to determine the node name -->
+ <property name="nodeAddress">${jboss.bind.address}</property>
+
+ <!-- Max time (in ms) to wait for state transfer to complete. Increase for large states -->
+ <property name="stateTransferTimeout">30000</property>
+
+ <!-- Max time (in ms) to wait for RPC calls to complete. -->
+ <property name="methodCallTimeout">60000</property>
+
+ <!-- Optionally provide a thread source to allow async connect of our channel -->
+ <property name="threadPool"><inject bean="jboss.system:service=ThreadPool"/></property>
+
+ <property name="distributedStateImpl">
+ <bean name="DistributedState"
+ class="org.jboss.ha.framework.server.DistributedStateImpl">
+ <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss:service=DistributedState,partitionName=${jboss.partition.name:DefaultPartition}", exposedInterface=org.jboss.ha.framework.server.DistributedStateImplMBean.class, registerDirectly=true)</annotation>
+ <property name="cacheHandler"><inject bean="HAPartitionCacheHandler"/></property>
+ </bean>
+ </property>
+
+ </bean>]]></programlisting>
+ <para>Much of the above is boilerplate; below we'll touch on the key points
+ relevant to end users. There are two beans defined above, the
+ <literal>HAPartitionCacheHandler</literal> and the <literal>HAPartition</literal> itself.</para>
+
+ <para>The <literal>HAPartition</literal> bean itself exposes the following
+ configuration properties:</para>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">partitionName</emphasis> specifies 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 unused and can be ignored.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">stateTransferTimeout</emphasis> specifies the timeout (in milliseconds) for initial application state transfer. State transfer refers to the process of obtaining a serialized copy of 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">methodCallTimeout</emphasis> specifies the timeout (in milliseconds) for obtaining responses to group RPCs from the other cluster members. Its default value is <literal>60000</literal>. </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The <literal>HAPartitionCacheHandler</literal> is a small utility service that
+ helps the HAPartition integrate with JBoss Cache
+ (see <xref linkend="clustering-blocks-jbc-cachemanager"/>). HAPartition exposes
+ a child service called DistributedState (see <xref linkend="clustering-hapartition-distributedstate"/>)
+ that uses JBoss Cache; the <literal>HAPartitionCacheHandler</literal> helps ensure
+ consistent configuration between the JGroups <literal>Channel</literal> used by
+ Distributed State's cache and the one used directly by HAPartition.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">cacheConfigName</emphasis> the name of the
+ JBoss Cache configuration to use for the HAPartition-related cache.
+ Indirectly, this also specifies the name of the JGroups protocol
+ stack configuration HAPartition should use. See
+ <xref linkend="jbosscache-configuration-jgroups"/> for more on
+ how the JGroups protocol stack is configured.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In order for nodes to form a cluster, they must have the exact same <literal>partitionName</literal>
+ and the <literal>HAPartitionCacheHandler</literal>'s <literal>cacheConfigName</literal>
+ must specify an identical JBoss Cache configuration. Changes in either
+ element on some but not all nodes would prevent proper clustering behavior.
+ </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>
+
</chapter>
More information about the jboss-cvs-commits
mailing list