### Eclipse Workspace Patch 1.0
#P docs-cluster_guide
Index: en-US/Clustering_Guide_Building_Blocks.xml
===================================================================
--- en-US/Clustering_Guide_Building_Blocks.xml (revision 92816)
+++ en-US/Clustering_Guide_Building_Blocks.xml (working copy)
@@ -253,210 +253,6 @@
the stack name to the string "unnamed_", e.g. unnamed_customStack.
-
-
- The HAPartition Service
-
- 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 allows
- services that use it to share a single Channel and
- multiplex RPC invocations over it, eliminating the configuration complexity
- and runtime overhead of having each service create its own Channel.
- 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.
-
-
-
-
- The following snippet shows the HAPartition service definition packaged with the standard JBoss AS distribution.
- This configuration can be found in the server/all/deploy/cluster/hapartition-jboss-beans.xml file.
-
-
-
- ha-partition
-
-
-
-
- jboss:service=Naming
-
- @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)
-
-
-
-
-
- ${jboss.partition.name:DefaultPartition}
-
-
- ${jboss.bind.address}
-
-
- 30000
-
-
- 60000
-
-
-
-
-
-
- @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)
-
-
-
-
- ]]>
- 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
- HAPartitionCacheHandler and the HAPartition itself.
-
- The HAPartition bean itself exposes the following
- configuration properties:
-
-
- partitionName specifies the
- name of the cluster. Its default value is DefaultPartition. Use the -g (a.k.a. --partition) command line switch to set this value at JBoss startup.
-
-
- nodeAddress is unused and can be ignored.
-
-
- stateTransferTimeout 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 30000.
-
-
- methodCallTimeout specifies the timeout (in milliseconds) for obtaining responses to group RPCs from the other cluster members. Its default value is 60000.
-
-
-
- The HAPartitionCacheHandler is a small utility service that
- helps the HAPartition integrate with JBoss Cache
- (see ). HAPartition exposes
- a child service called DistributedState (see )
- that uses JBoss Cache; the HAPartitionCacheHandler helps ensure
- consistent configuration between the JGroups Channel used by
- Distributed State's cache and the one used directly by HAPartition.
-
-
-
- cacheConfigName 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
- for more on
- how the JGroups protocol stack is configured.
-
-
-
- In order for nodes to form a cluster, they must have the exact same partitionName
- and the HAPartitionCacheHandler's cacheConfigName
- must specify an identical JBoss Cache configuration. Changes in either
- element on some but not all nodes would prevent proper clustering behavior.
-
-
- You can view the current cluster information by pointing your browser to the JMX console of any
- JBoss instance in the cluster (i.e., http://hostname:8080/jmx-console/) and then
- clicking on the jboss:service=HAPartition,partition=DefaultPartition 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.
-
- Note
-
- 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.
-
-
-
-
- DistributedReplicantManager Service
-
- The DistributedReplicantManager (DRM) service is a component
- of the HAPartition service made available to HAPartition
- users via the HAPartition.getDistributedReplicantManager()
- 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.
-
- 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.
-
- There are two main usages for the DRM in JBoss AS:
-
-
-
- Clustered Smart Proxies
- Here the keys are the names of the various services that need a
- clustered smart proxy (see ,
- 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
- InvokerLocator). 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.
-
-
- HASingleton
- Here the keys are the names of the various services that need to
- function as High Availablity Singletons (see ).
- 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.
-
-
-
- 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.
-
-
-
- DistributedState Service
-
- The DistributedState service is a legacy component
- of the HAPartition service made available to HAPartition
- users via the HAPartition.getDistributedState()
- 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.
-
- In JBoss 5 the DistributedState service actually
- delegates to an underlying JBoss Cache instance.
-
-
-
- Custom Use of HAPartition
-
- 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 org.jboss.ha.framework.server.HAServiceImpl
- base class, or the org.jboss.ha.jxm.HAServiceMBeanSupport
- class if JMX registration and notification support are desired.
-
-
-
-
-
Distributed Caching with JBoss Cache
@@ -711,6 +507,210 @@
+
+
+ The HAPartition Service
+
+ 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 allows
+ services that use it to share a single Channel and
+ multiplex RPC invocations over it, eliminating the configuration complexity
+ and runtime overhead of having each service create its own Channel.
+ 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.
+
+
+
+
+ The following snippet shows the HAPartition service definition packaged with the standard JBoss AS distribution.
+ This configuration can be found in the server/all/deploy/cluster/hapartition-jboss-beans.xml file.
+
+
+
+ ha-partition
+
+
+
+
+ jboss:service=Naming
+
+ @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)
+
+
+
+
+
+ ${jboss.partition.name:DefaultPartition}
+
+
+ ${jboss.bind.address}
+
+
+ 30000
+
+
+ 60000
+
+
+
+
+
+
+ @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)
+
+
+
+
+ ]]>
+ 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
+ HAPartitionCacheHandler and the HAPartition itself.
+
+ The HAPartition bean itself exposes the following
+ configuration properties:
+
+
+ partitionName specifies the
+ name of the cluster. Its default value is DefaultPartition. Use the -g (a.k.a. --partition) command line switch to set this value at JBoss startup.
+
+
+ nodeAddress is unused and can be ignored.
+
+
+ stateTransferTimeout 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 30000.
+
+
+ methodCallTimeout specifies the timeout (in milliseconds) for obtaining responses to group RPCs from the other cluster members. Its default value is 60000.
+
+
+
+ The HAPartitionCacheHandler is a small utility service that
+ helps the HAPartition integrate with JBoss Cache
+ (see ). HAPartition exposes
+ a child service called DistributedState (see )
+ that uses JBoss Cache; the HAPartitionCacheHandler helps ensure
+ consistent configuration between the JGroups Channel used by
+ Distributed State's cache and the one used directly by HAPartition.
+
+
+
+ cacheConfigName 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
+ for more on
+ how the JGroups protocol stack is configured.
+
+
+
+ In order for nodes to form a cluster, they must have the exact same partitionName
+ and the HAPartitionCacheHandler's cacheConfigName
+ must specify an identical JBoss Cache configuration. Changes in either
+ element on some but not all nodes would prevent proper clustering behavior.
+
+
+ You can view the current cluster information by pointing your browser to the JMX console of any
+ JBoss instance in the cluster (i.e., http://hostname:8080/jmx-console/) and then
+ clicking on the jboss:service=HAPartition,partition=DefaultPartition 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.
+
+ Note
+
+ 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.
+
+
+
+
+ DistributedReplicantManager Service
+
+ The DistributedReplicantManager (DRM) service is a component
+ of the HAPartition service made available to HAPartition
+ users via the HAPartition.getDistributedReplicantManager()
+ 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.
+
+ 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.
+
+ There are two main usages for the DRM in JBoss AS:
+
+
+
+ Clustered Smart Proxies
+ Here the keys are the names of the various services that need a
+ clustered smart proxy (see ,
+ 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
+ InvokerLocator). 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.
+
+
+ HASingleton
+ Here the keys are the names of the various services that need to
+ function as High Availablity Singletons (see ).
+ 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.
+
+
+
+ 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.
+
+
+ DistributedState Service
+
+ The DistributedState service is a legacy component
+ of the HAPartition service made available to HAPartition
+ users via the HAPartition.getDistributedState()
+ 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.
+
+ In JBoss 5 the DistributedState service actually
+ delegates to an underlying JBoss Cache instance.
+
+
+
+ Custom Use of HAPartition
+
+ 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 org.jboss.ha.framework.server.HAServiceImpl
+ base class, or the org.jboss.ha.jxm.HAServiceMBeanSupport
+ class if JMX registration and notification support are desired.
+
+
+
+
+
+