Red Hat Training

A Red Hat training course is available for JBoss Enterprise Application Platform Common Criteria Certification

18.3. The HAPartition Service

HAPartition is a general purpose service used for a variety of tasks in Enterprise Application Platform 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 Enterprise Application Platform distribution. This configuration can be found in the server/all/deploy/cluster/hapartition-jboss-beans.xml file. 
<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>
Much of the above is generic; 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 is an optional attribute to specify 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 server 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 Section 18.2.1, “The JBoss Enterprise Application Platform CacheManager Service”). HAPartition exposes a child service called DistributedState (see Section 18.3.2, “DistributedState Service”) 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 Section 26.1.5, “JGroups Integration” 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.

18.3.1. 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 Enterprise Application Platform 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 Enterprise Application Platform 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 Enterprise Application Platform:
  • Clustered Smart Proxies
    Here the keys are the names of the various services that need a clustered smart proxy (see Section 17.2.1, “Client-side interceptor architecture”, 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 HASingleton chapter). 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.