[jboss-cvs] JBossAS SVN: r82620 - projects/docs/community/5/Clustering_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Jan 5 22:19:19 EST 2009
Author: bstansberry at jboss.com
Date: 2009-01-05 22:19:19 -0500 (Mon, 05 Jan 2009)
New Revision: 82620
Modified:
projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_HTTP.xml
projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Introduction.xml
projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_JGroups.xml
Log:
[JBAS-6358] Open with a quick start.
Modified: projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_HTTP.xml
===================================================================
--- projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_HTTP.xml 2009-01-06 02:32:46 UTC (rev 82619)
+++ projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_HTTP.xml 2009-01-06 03:19:19 UTC (rev 82620)
@@ -48,7 +48,9 @@
is not acceptable and, in this case, session state replication is the
price one has to pay.</para>
</note>
- <section><title>Configuring load balancing using Apache and mod_jk</title>
+
+ <section id="clustering-http-modjk">
+ <title>Configuring load balancing using Apache and mod_jk</title>
<para>Apache is a well-known web server which can be extended by plugging in modules. One of these modules, mod_jk has been specifically designed to allow the forwarding of requests from Apache to a Servlet container. Furthermore, it is also able to load-balance HTTP calls to a set of Servlet containers while maintaining sticky sessions, which is what is most interesting for us in this section.</para>
@@ -67,7 +69,7 @@
downloaded file to <literal>mod_jk.so</literal> and copy it under
<literal>APACHE_HOME/modules/</literal>.</para>
</section>
- <section id="clustering-http-modjk">
+ <section>
<title>Configure Apache to load mod_jk</title>
<para>Modify APACHE_HOME/conf/httpd.conf and add a single line at the end of the file:</para>
<programlisting>
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-01-06 02:32:46 UTC (rev 82619)
+++ projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Introduction.xml 2009-01-06 03:19:19 UTC (rev 82620)
@@ -2,24 +2,489 @@
<!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>Clustering Concepts</title>
+ <title>JBoss Application Server Clustering Basics</title>
<subtitle>High Availability Enterprise Services via JBoss Clusters</subtitle>
- <section id="clustering-intro">
+ <section id="clustering-intro">
<title>Introduction</title>
+
<para>
- Clustering allows us to run an application on several parallel servers (a.k.a cluster nodes) while providing a single view to application clients. Load is distributed across different servers, and even if one or more of the servers fails, the application is still accessible via the surviving cluster nodes. Clustering is crucial for scalable enterprise applications, as you can improve performance by simply adding more nodes to the cluster. Clustering is crucial for highly available enterprise applications, as it is the clustering infrastructure that supports the redundancy needed for high availability.
+ Clustering allows you to run an application on several parallel servers
+ (a.k.a cluster nodes) while providing a single view to application
+ clients. Load is distributed across different servers, and even if
+ one or more of the servers fails, the application is still accessible
+ via the surviving cluster nodes. Clustering is crucial for scalable
+ enterprise applications, as you can improve performance by adding more
+ nodes to the cluster. Clustering is crucial for highly available
+ enterprise applications, as it is the clustering infrastructure
+ that supports the redundancy needed for high availability.
</para>
<para>
- The JBoss Application Server (AS) comes with clustering support out of the box. The simplest way to start a JBoss server cluster is to start several JBoss instances on the same local network, using the <literal>run -c all</literal> command for each instance. Those server instances, all started in the <literal>all</literal> configuration, detect each other and automatically form a cluster.
+ The JBoss Application Server (AS) comes with clustering support out of
+ the box, as part of the <literal>all</literal> configuration. The
+ <literal>all</literal> configuration includes support for the following:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>A scalable, fault-tolerant JNDI implementation (HA-JNDI).</para>
+ </listitem>
+
+ <listitem>
+ <para>Web tier clustering, including:</para>
+ <itemizedlist>
+ <listitem>
+ <para>High availability for web session state via state
+ replication.</para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem><para>Ability to integrate with hardware and software
+ load balancers, including special integration with mod_jk and
+ other JK-based software load balancers.</para></listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem><para>Single Sign-on support across a cluster.</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>EJB session bean clustering, for both stateful and stateless
+ beans, and for both EJB3 and EJB2.</para>
+ </listitem>
+
+ <listitem>
+ <para>A distributed cache for JPA/Hibernate entities.</para>
+ </listitem>
+
+ <listitem>
+ <para>A framework for keeping local EJB2 entity caches consistent
+ across a cluster by invalidating cache entries across the cluster
+ when a bean is changed on any node.</para>
+ </listitem>
+
+ <listitem>
+ <para>Distributed JMS queues and topics via JBoss Messaging.</para>
+ </listitem>
+
+ <listitem>
+ <para>Deploying a service or application on multiple nodes in the
+ cluster but having it active on only one (but at least one)
+ node, a.k.a. an "HA Singleton".</para>
+ </listitem>
+
+ </itemizedlist>
</para>
+
<para>
- In the first section of this chapter, we discuss basic concepts behind JBoss's clustering services. It is important that you understand these concepts before reading the rest of the chapter. Clustering configurations for specific types of applications are covered after this section.
+ In this <emphasis>Clustering Guide</emphasis> we aim to provide you with
+ an in depth understanding of how to use JBoss AS's clustering features.
+ In this first chapter, the goal is to provide some basic "Quick Start"
+ steps to encourage you to start experimenting with JBoss AS Clustering,
+ and then to provide some background information that will allow you to
+ understand how JBoss AS Clustering works. The later chapters in the
+ <emphasis>Clustering Guide</emphasis> then explain how to use features
+ listed above. Finally, we provide some more details about advanced
+ configuration of JGroups, the core technology that underlies JBoss AS
+ Clustering.
</para>
-</section>
+ </section>
+ <section id="clustering-quickstart">
+ <title>Quick Start Guide</title>
+ <para>
+ The goal of this section is to give you the minimum information
+ needed to let you get started experimenting with JBoss AS Clustering.
+ Each of the areas touched on in this section is covered in much greater
+ detail later in this guide.
+ </para>
+
+ <section id="clustering-quickstart-setup">
+ <title>Initial Preparation</title>
+
+ <para>Preparing a set of servers to act as a JBoss AS cluster
+ involves a few simple steps:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">Install JBoss AS on all your servers.</emphasis>
+ In its simplest form, this is just a matter of unzipping the JBoss
+ download onto the filesystem on each server. See the
+ "Administration and Configuration Guide" for full details.</para>
+
+ <para id="clustering-prep-dualconfig">If you want to run multiple
+ JBoss AS instances on a single server, you can either install the
+ full JBoss distribution onto multiple locations on your filesystem,
+ or you can simply make copies of the <literal>all</literal>
+ configuration. For example, assuming the root of the JBoss distribution
+ was unzipped to <literal>/home/userA/jboss</literal>, you would:</para>
+
+ <programlisting>
+$ cd /home/userA/jboss/server
+$ cp -r all node1
+$ cp -r all node2</programlisting>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">For each node, determine the address
+ to bind sockets to.</emphasis> When you start JBoss, whether
+ clustered or not, you need to tell JBoss on what address its
+ sockets should listen for traffic. (The default is <literal>localhost</literal>
+ which is secure but isn't very useful, particularly in a cluster.)
+ So, you need to decide what those addresses will be.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Ensure multicast is working.</emphasis>
+ By default JBoss AS uses UDP multicast for most intra-cluster
+ communications. Make sure each server's networking configuration
+ supports multicast and that multicast support is enabled for any
+ switches or routers between your servers. If you are planning to
+ run more than one node on a server, make sure the server's routing
+ table includes a multicast route. See the JGroups documentation
+ at http://www.jgroups.org
+ for more on this general area, including information on how to use
+ JGroups' diagnostic tools to confirm that multicast is working.
+ </para>
+
+ <note>
+ <para>JBoss AS clustering does not require the use of UDP multicast;
+ the AS can also be reconfigured to use TCP unicast for intra-cluster
+ communication.</para>
+ </note>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Determine a unique integer "ServerPeerID" for each
+ node.</emphasis> This is needed for JBoss Messaging clustering,
+ and can be skipped if you will not be running JBoss Messaging.
+ JBM requires that each node in a cluster have a unique integer
+ id, known as a "ServerPeerID", that should remain consistent
+ across server restarts. A simple 1, 2, 3, ..., x naming scheme is
+ fine. We'll cover how to use these integer ids in the next section.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Beyond the above steps, the following two steps are
+ recommended to help ensure that your cluster is properly isolated
+ from other JBoss AS clusters that may be running on your network:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para id="clustering-prep-clustername">
+ <emphasis role="bold">Pick a unique name for your cluster.</emphasis>
+ The default name for a JBoss AS cluster is "DefaultPartition". Come
+ up with a different name for each cluster in your environment, e.g.
+ "QAPartition" or "BobsDevPartition". The use of "Partition" is not
+ required; it's just a semi-convention. As a small aid to performance
+ try to keep the name short. We'll cover how to use the name you
+ pick in the next section.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="clustering-prep-mcastaddr">
+ <emphasis role="bold">Pick a unique multicast address for your cluster.</emphasis>
+ By default JBoss AS uses UDP multicast for most intra-cluster
+ communication. Pick a different multicast address for each cluster
+ you run. Generally a good multicast address is of the form
+ <literal>239.255.x.y</literal>. See
+ http://www.29west.com/docs/THPM/multicast-address-assignment.html
+ for a good discussion on multicast address assignment. We'll cover
+ how to use the address you pick in the next section.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>See <xref linkend="clustering-jgroups-isolation"/> for more on isolating clusters.</para>
+ </section>
+
+ <section id="clustering-quickstart-launching">
+ <title>Launching a JBoss AS Cluster</title>
+ <para>The simplest way to start a JBoss server cluster is to start
+ several JBoss instances on the same local network, using the
+ <literal>-c all</literal> command line option for each instance. Those
+ server instances will detect each other and automatically form a cluster.
+ </para>
+
+ <para>Let's look at a few different scenarios for doing this. In each
+ scenario we'll be creating a two node cluster, where the ServerPeerID
+ for the first node is <literal>1</literal> and for the second node is
+ <literal>2</literal>. We've decided to call our cluster "DocsPartition"
+ and to use <literal>239.255.100.100</literal> as our multicast address.
+ These scenarios are meant to be illustrative; the use of a two node
+ cluster shouldn't be taken to mean that is the best size for a cluster;
+ it's just that's the simplest way to do the examples.</para>
+
+ <itemizedlist>
+ <listitem><para><emphasis role="bold">Scenario 1: Nodes on Separate Machines</emphasis></para>
+ <para>This is the most common production scenario. Assume the
+ machines are named "node1" and "node2" and node1 has an IP address
+ of <literal>192.168.0.101</literal> and node2 has an address of
+ <literal>192.168.0.102</literal>. Assume the "ServerPeerID" for
+ node1 is <literal>1</literal> and for node2 it's <literal>1</literal>.
+ Assume on each machine JBoss is installed in <literal>/var/jboss</literal>.</para>
+
+ <para>On node1, to launch JBoss:</para>
+ <programlisting>
+$ cd /var/jboss/bin
+$ ./run.sh -c all -g DocsPartition -u 239.255.100.100 -b 192.168.0.101 -Djboss.messaging.ServerPeerID=1</programlisting>
+
+ <para>On node2, it's the same except for a different -b value and ServerPeerID:</para>
+
+ <programlisting>
+$ cd /var/jboss/bin
+$ ./run.sh -c all -g DocsPartition -u 239.255.100.100 -b 192.168.0.102 -Djboss.messaging.ServerPeerID=2</programlisting>
+
+ <para>The <literal>-c</literal> switch says to use the <literal>all</literal>
+ config, which includes clustering support. The <literal>-g</literal> switch
+ sets the cluster name. The <literal>-u</literal> switch sets the multicast
+ address that will be used for intra-cluster communication. The
+ <literal>-b</literal> switch sets the address on which sockets
+ will be bound. The <literal>-D</literal> switch sets system
+ property <literal>jboss.messaging.ServerPeerId</literal>, from which
+ JBoss Messaging gets its unique id.</para>
+ </listitem>
+ <listitem><para><emphasis role="bold">Scenario 2: Two Nodes on a Single, Multihomed, Server</emphasis></para>
+ <para>Running multiple nodes on the same machine is a common scenario
+ in a development environment, and is also used in production in
+ combination with Scenario 1. (Running all the nodes in a production
+ cluster on a single machine is generally not recommended, since the
+ machine itself becomes a single point of failure.) In this version
+ of the scenario, the machine is multihomed, i.e. has more than one IP
+ address. This allows the binding of each JBoss instance to a different
+ address, preventing port conflicts when the nodes open sockets.
+ </para>
+
+ <para>Assume that single machine has the <literal>192.168.0.101</literal> and
+ <literal>192.168.0.102</literal> addresses assigned, and that the two
+ JBoss instances use the same addresses and ServerPeerIDs as in
+ Scenario 1. The difference from Scenario 1 is we need to be sure
+ each AS instance has its own work area. So, instead of using
+ the <literal>all</literal> config, we are going to use the
+ <literal>node1</literal> and <literal>node2</literal> configs we
+ copied from <literal>all</literal> in
+ <link linkend="clustering-prep-dualconfig">the previous section</link>.</para>
+
+ <para>To launch the first instance, open a console window and:</para>
+ <programlisting>
+$ cd /var/jboss/bin
+$ ./run.sh -c node1 -g DocsPartition -u 239.255.100.100 -b 192.168.0.101 -Djboss.messaging.ServerPeerID=1</programlisting>
+
+ <para>For the second instance, it's the same except for different -b and -c values and a different ServerPeerID:</para>
+
+ <programlisting>
+$ cd /var/jboss/bin
+$ ./run.sh -c node2 -g DocsPartition -u 239.255.100.100 -b 192.168.0.102 -Djboss.messaging.ServerPeerID=2</programlisting>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Scenario 3: Two Nodes on a Single, Non-Multihomed, Server</emphasis></para>
+ <para>This scenario is similar to Scenario 2, but here the machine
+ only has one IP address available. Two processes can't bind sockets
+ to the same address and port, so we'll have to tell JBoss to
+ a different ports for the two instances. This can be done by
+ configuring the ServiceBindingManager service by setting the
+ <literal>jboss.service.binding.set</literal> system property.</para>
+
+ <para>To launch the first instance, open a console window and:</para>
+ <programlisting>
+$ cd /var/jboss/bin
+$ ./run.sh -c node1 -g DocsPartition -u 239.255.100.100 -b 192.168.0.101 -Djboss.messaging.ServerPeerID=1 -Djboss.service.binding.set=ports-default</programlisting>
+
+ <para>For the second instance:</para>
+
+ <programlisting>
+$ cd /var/jboss/bin
+$ ./run.sh -c node2 -g DocsPartition -u 239.255.100.100 -b 192.168.0.101 -Djboss.messaging.ServerPeerID=2 -Djboss.service.binding.set=ports-01</programlisting>
+
+ <para>This tells the ServiceBindingManager on the first node to use
+ the standard set of ports (e.g. JNDI on 1099). The second node uses
+ the "ports-01" binding set, which by default for each port has an
+ offset of 100 from the standard port number (e.g. JNDI on 1199).
+ See the <literal>conf/bootstrap/bindings.xml</literal> file for the
+ full ServiceBindingManager configuration.</para>
+
+ <para>Note that this setup is not advised for production use,
+ due to the increased management complexity that comes with using
+ different ports. But it is a fairly common scenario in development
+ environments where developers want to use clustering but cannot
+ multihome their workstations.</para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ <para></para>
+ </section>
+
+ <section id="clustering-quickstart-http">
+ <title>Web Application Clustering Quick Start</title>
+ <para>JBoss AS supports clustered web sessions, where a backup
+ copy of each user's <literal>HttpSession</literal> state is stored
+ on one or more nodes in the cluster. In case the primary node
+ handling the session fails or is shut down, any other node in the
+ cluster can handle subsequent requests for the session by accessing
+ the backup copy. Web tier clustering is discussed in detail in
+ <xref linkend="clustering-http"/>.</para>
+
+ <para>There are two aspects to setting up web tier clustering:
+
+ <itemizedlist>
+ <listitem><para><emphasis role="bold">Configuring an External
+ Load Balancer</emphasis>. Web applications require an external
+ load balancer to balance HTTP requests across the cluster of JBoss AS
+ instances (see <xref linkend="clustering-concepts-arch-balancer"/>
+ for more on why that is). JBoss AS itself doesn't act as an HTTP load
+ balancer. So, you will need to set up a hardware or software
+ load balancer. There are many possible load balancer choices,
+ so how to configure one is really beyond the scope of a Quick Start.
+ But see <xref linkend="clustering-http-modjk"/> for details on
+ how to set up the popular mod_jk software load balancer.</para>
+ </listitem>
+ <listitem><para><emphasis role="bold">Configuring Your Web
+ Application for Clustering</emphasis>. This aspect involves
+ telling JBoss you want clustering behavior for a particular
+ web app, and it couldn't be simpler. Just add an empty
+ <literal>distributable</literal> element to your application's
+ <literal>web.xml</literal> file:</para>
+ <programlisting><?xml version="1.0"?>
+<web-app xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
+ http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
+ version="2.5">
+
+ <distributable/>
+
+</web-app></programlisting>
+
+ <para>Simply doing that is enough to get the default JBoss AS
+ web session clustering behavior, which is appropriate for most
+ applications. See <xref linkend="clustering-http-state"/> for
+ more advanced configuration options.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id="clustering-quickstart-ejbsessions">
+ <title>EJB Session Bean Clustering Quick Start</title>
+ <para>JBoss AS supports clustered EJB session beans, whereby
+ requests for a bean are balanced across the cluster, and, for
+ stateful beans, a backup copy of bean state is maintained on one
+ or more cluster nodes, providing high availability in case the
+ node handling a particular session fails or is shut down. Clustering
+ of both EJB2 and EJB3 beans is supported.
+ </para>
+
+ <para>For EJB3 session beans, simply add the <literal>org.jboss.ejb3.annotation.Clustered</literal>
+ annotation to the bean class for your stateful or stateless bean:</para>
+
+ <programlisting>
+ at javax.ejb.Stateless
+ at org.jboss.ejb3.annotation.Clustered
+public class MyBean implements MySessionInt {
+
+ public void test() {
+ // Do something cool
+ }
+}</programlisting>
+
+ <para>For EJB2 session beans, or for EJB3 beans where you prefer
+ XML configuration over annotations, simply add a <literal>clustered</literal>
+ element to the bean's section in the JBoss-specific deployment
+ descriptor, <literal>jboss.xml</literal>:</para>
+
+ <programlisting>
+<jboss>
+ <enterprise-beans>
+ <session>
+ <ejb-name>example.StatelessSession</ejb-name>
+ <jndi-name>example.StatelessSession</jndi-name>
+ <clustered>true</clustered>
+ </session>
+ </enterprise-beans>
+</jboss> </programlisting>
+
+ <para>See <xref linkend="clustering-session"/>for more advanced
+ configuration options.</para>
+ </section>
+
+ <section id="clustering-quickstart-ejb3entities">
+ <title>JPA Entity Clustering Quick Start</title>
+ <para>One of the big improvements in the clustering area in JBoss AS 5
+ is the use of the new Hibernate/JBoss Cache integration for second
+ level caching that was introduced in Hibernate 3.3. In the JPA/Hibernate
+ context, a second level cache refers to a cache whose contents are
+ retained beyond the scope of a transaction. A second level cache
+ <emphasis>may</emphasis> improve performance by reducing the number
+ of database reads. You should always load test your application
+ with second level caching enabled and disabled to see whether
+ it has a beneficial impact on your particular application.</para>
+ <para>If you use more than one JBoss AS instance to run your
+ JPA/Hibernate application and you use second level caching, you must
+ use a cluster-aware cache. Otherwise a cache on server A will still
+ hold out-of-date data after activity on server B updates some entities.</para>
+ <para>JBoss AS provides a cluster-aware second level cache based on JBoss Cache.
+ To tell JBoss AS's standard Hibernate-based JPA provider to enable
+ second level caching with JBoss Cache, configure your
+ <literal>persistence.xml</literal> as follows:</para>
+
+ <programlisting><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<persistence xmlns="http://java.sun.com/xml/ns/persistence"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
+ http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
+ version="1.0">
+ <persistence-unit name="somename" transaction-type="JTA">
+ <jta-data-source>java:/SomeDS</jta-data-source>
+ <properties>
+ <property name="hibernate.cache.use_second_level_cache" value="true"/>
+ <property name="hibernate.cache.region.factory_class" value="org.hibernate.cache.jbc2.JndiMultiplexedJBossCacheRegionFactory"/>
+ <property name="hibernate.cache.region.jbc2.cachefactory" value="java:CacheManager"/>
+ <!-- Other configuration options ... -->
+ </properties>
+ </persistence-unit>
+</persistence>]]>
+ </programlisting>
+
+ <para>That tells Hibernate to use the JBoss Cache-based second level
+ cache, but it doesn't tell it what entities to cache. That can
+ be done by adding the <literal>org.hibernate.annotations.Cache</literal>
+ annotation to your entity class:</para>
+
+ <programlisting><![CDATA[
+package org.example.entities;
+
+import java.io.Serializable;
+
+import javax.persistence.Entity;
+
+import org.hibernate.annotations.Cache;
+import org.hibernate.annotations.CacheConcurrencyStrategy;
+
+ at Entity
+ at Cache (usage=CacheConcurrencyStrategy.TRANSACTIONAL)
+public class Account implements Serializable]]>
+ </programlisting>
+
+ <para>See <xref linkend="clustering-entity"/>for more advanced
+ configuration options and details on how to configure the same
+ thing for a non-JPA Hibernate application.</para>
+ </section>
+
+ </section>
- <section id="clustering-intro-def">
+ <section id="clustering-concepts">
+ <title>Clustering Concepts</title>
+ <para>
+ In the next section, we discuss basic concepts behind JBoss's clustering services. It is important that you understand these concepts before reading the rest of the chapter. Clustering configurations for specific types of applications are covered after this section.
+ </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 na!
me that matches the other cluster members.
@@ -47,96 +512,15 @@
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-hapartition"> <title>HAPartition</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.
- </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=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>
-
-<section><title>JBoss Cache channels</title>
-<para>
- JBoss Cache is a fully featured distributed cache framework that can be used in any application server environment or standalone. JBoss AS integrates JBoss Cache to provide cache services for HTTP sessions, EJB 3.0 session beans, and EJB 3.0 entity beans. Each of these cache services is defined in a separate Mbean, and each cache creates its own JGroups Channel. We will cover those MBeans when we discuss specific services in the next several sections.
-</para>
-</section>
-
-<section id="clustering-intro-arch">
+<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-intro-arch-proxy">
+ <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 stub (or proxy) object. The stub object is generated by the server and it implements the business interface of the service. The client then makes local method calls against the stub object. The stub automatically routes the call across the network and where it is invoked against service objects managed in the server. In a clustering environment, the server-generated stub object includes an interceptor that understands how to route calls to multiple nodes in the cluster. The stub 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.
@@ -158,8 +542,8 @@
to handle the entire cluster restart.</para>
</note>
</section>
- <section id="clustering-intro-arch-balancer">
- <title>Load balancer</title>
+ <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 according 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 about 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 unde!
rstanding 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>
@@ -178,12 +562,12 @@
</section>
-<section id="clustering-intro-balancepolicy">
+<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-intro-balancepolicy-30">
+ <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.
@@ -227,7 +611,116 @@
</section>
</section>
+ </section>
+ <section id="clustering-blocks">
+ <title>Clustering Building Blocks</title>
+ <para></para>
+
+ <section id="clustering-blocks-jgroups">
+ <title>Group Communication with JGroups</title>
+ <para></para>
+
+ </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.
+ </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=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>
+
+ <section><title>JBoss Cache channels</title>
+ <para>
+ JBoss Cache is a fully featured distributed cache framework that can be
+ used in any application server environment or standalone. JBoss AS
+ integrates JBoss Cache to provide cache services for HTTP sessions,
+ EJB 3.0 session beans, and EJB 3.0 entity beans. Each of these cache
+ services is defined in a separate Mbean, and each cache creates its own
+ JGroups Channel. We will cover those MBeans when we discuss specific
+ services in the next several sections.
+ </para>
+</section>
+ </section>
<section id="clustering-intro-farm">
<title>Farming Deployment</title>
Modified: projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_JGroups.xml
===================================================================
--- projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_JGroups.xml 2009-01-06 02:32:46 UTC (rev 82619)
+++ projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_JGroups.xml 2009-01-06 03:19:19 UTC (rev 82620)
@@ -1100,7 +1100,7 @@
</para>
</section>
- <section><title>Isolating JGroups Channels</title>
+ <section id="clustering-jgroups-isolation"><title>Isolating JGroups Channels</title>
<para>
Within JBoss AS, there are a number of services that independently create JGroups channels -- 3 different JBoss Cache services (used for HttpSession replication, EJB3 SFSB replication and EJB3 entity replication) along with the general purpose clustering service called HAPartition that underlies most other JBossHA services.
</para>
More information about the jboss-cvs-commits
mailing list