[jboss-cvs] JBossAS SVN: r93163 - projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Sep 3 09:51:41 EDT 2009
Author: pferraro
Date: 2009-09-03 09:51:41 -0400 (Thu, 03 Sep 2009)
New Revision: 93163
Modified:
projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_EJBs.xml
Log:
Sync with updates from community documentation.
Modified: projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_EJBs.xml
===================================================================
--- projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_EJBs.xml 2009-09-03 13:50:58 UTC (rev 93162)
+++ projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_EJBs.xml 2009-09-03 13:51:41 UTC (rev 93163)
@@ -18,18 +18,61 @@
Calls can be load balanced to any participating node (i.e. any node that has this specific bean deployed) of the cluster.
</para>
<para>
- To cluster a stateless session bean in EJB 3.0, all you need to do is to annotate the bean class with the <literal>@Clustered</literal> annotation.
- You can pass in the load balance policy and cluster partition as parameters to the annotation.
- The default load balance policy is <literal>org.jboss.ha.framework.interfaces.RandomRobin</literal> and the default cluster is <literal>DefaultPartition</literal>.
- Below is the definition of the <literal>@Cluster</literal> annotation.
+ To cluster a stateless session bean in EJB 3.0, simply annotate the bean class with the <literal>@Clustered</literal> annotation.
+ This annotation contains optional parameters for overriding both the load balance policy and partition to use.
</para>
-<programlisting><![CDATA[
+<programlisting id="clustered-annoation"><![CDATA[
public @interface Clustered
{
- Class loadBalancePolicy() default LoadBalancePolicy.class;
String partition() default "${jboss.partition.name:DefaultPartition}";
+ String loadBalancePolicy() default "LoadBalancePolicy";
}
]]></programlisting>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">partition</emphasis> specifies the name of the cluster the bean participates in.
+ While the <literal>@Clustered</literal> annotation lets you override the default partition, <literal>DefaultPartition</literal>, for an individual bean, you can override this for all beans using the <literal>jboss.partition.name</literal> system property.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">loadBalancePolicy</emphasis> defines the name of a class implementing <literal>org.jboss.ha.client.loadbalance.LoadBalancePolicy</literal>, indicating how the bean stub should balance calls made on the nodes of the cluster.
+ The default value, <literal>LoadBalancePolicy</literal> is a special token indicating the default policy for the session bean type.
+ For stateless session beans, the default policy is <literal>org.jboss.ha.client.loadbalance.RoundRobin</literal>.
+ You can override the default value using your own implementation, or choose one from the list of available policies:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.ha.client.loadbalance.RoundRobin</literal></term>
+ <listitem><para>Starting with a random target, always favors the next available target in the list, ensuring maximum load balancing always occurs.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.ha.client.loadbalance.RandomRobin</literal></term>
+ <listitem><para>Randomly selects its target without any consideration to previously selected targets.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.ha.client.loadbalance.aop.FirstAvailable</literal></term>
+ <listitem>
+ <para>
+ Once a target is chosen, always favors that same target; i.e. no further load balancing occurs.
+ Useful in cases where "sticky session" behavior is desired, e.g. stateful session beans.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.ha.client.loadbalance.aop.FirstAvailableIdenticalAllProxies</literal></term>
+ <listitem><para>Similar to <literal>FirstAvailable</literal>, except that the favored target is shared across all proxies.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </itemizedlist>
<para>Here is an example of a clustered EJB 3.0 stateless session bean implementation.</para>
<programlisting><![CDATA[
@Stateless
@@ -43,7 +86,7 @@
}
]]></programlisting>
<para>
- The <literal>@Clustered</literal> annotation can also be omitted and the clustering configuration applied in jboss.xml:
+ Rather than using the <literal>@Clustered</literal> annotation, you can also enable clustering for a session bean in jboss.xml:
</para>
<programlisting><![CDATA[
<jboss>
@@ -67,27 +110,9 @@
</note>
<para>
- In the bean configuration, only the <clustered> element is mandatory.
- It indicates that the bean needs to support clustering features.
- The <cluster-config> element is optional and the default values of its attributes are indicated in the sample configuration above.
- Below is a description of the attributes in the <cluster-config> element.
+ In the bean configuration, only the <clustered> element is necessary to indicate that the bean needs to support clustering features.
+ The default values for the optional <cluster-config> elements match those of the corresponding properties from the <literal>@Clustered</literal> annotation.
</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">partition-name</emphasis> specifies the name of the cluster the bean participates in.
- The default value is <literal>DefaultPartition</literal>.
- The default partition name can also be set system-wide using the <literal>jboss.partition.name</literal> system property.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">load-balance-policy</emphasis> Indicates the class to be used by the bean stub to balance calls made on the nodes of the cluster.
- By default, the proxy will load-balance calls in a <literal>RoundRobin</literal> fashion.
- You can also implement your own load-balance policy class or use the class <literal>FirstAvailable</literal> that persists to use the first node available that it meets until it fails.
- </para>
- </listitem>
- </itemizedlist>
</section>
@@ -101,10 +126,14 @@
<section>
<title>The EJB application configuration</title>
<para>
- To cluster stateful session beans in EJB 3.0, you need to tag the bean implementation class with the <literal>@Cluster</literal> annotation, just as we did with the EJB 3.0 stateless session bean earlier.
- The @org.jboss.ejb3.annotation.CacheConfig annotation can also be applied to the bean to specify caching behavior.
- Below is the definition of the @CacheConfig annotation:
+ To cluster stateful session beans in EJB 3.0, you need to tag the bean implementation class with the <literal>@Clustered</literal> annotation, just as we did with the EJB 3.0 stateless session bean earlier.
+ In contrast to stateless session beans, stateful session bean method invocations are load balanced using <literal>org.jboss.ha.client.loadbalance.aop.FirstAvailable</literal> policy, by default.
+ Using this policy, methods invocations will stick to a randomly chosen node.
</para>
+ <para>
+ The <literal>@org.jboss.ejb3.annotation.CacheConfig</literal> annotation can also be applied to the bean to override the default caching behavior.
+ Below is the definition of the <literal>@CacheConfig</literal> annotation:
+ </para>
<programlisting><![CDATA[
public @interface CacheConfig
{
@@ -410,9 +439,9 @@
Clustering stateful session beans is more complex than clustering their stateless counterparts
since JBoss needs to manage the state information. The state of all stateful session beans are
replicated and synchronized across the cluster each time the state of a bean changes. The JBoss Enterprise Application Platform
- uses the <literal>HASessionState</literal> MBean to manage distributed session states for clustered
+ uses the <literal>HASessionStateService</literal> bean to manage distributed session states for clustered
EJB 2.x stateful session beans. In this section, we cover both the session bean configuration and
- the <literal>HASessionState</literal> MBean configuration.
+ the <literal>HASessionStateService</literal> bean configuration.
</para>
<section>
@@ -445,7 +474,7 @@
</para>
<para>
The <literal><session-state-manager-jndi-name></literal> tag is used to give the JNDI
- name of the <literal>HASessionState</literal> service to be used by this bean.
+ name of the <literal>HASessionStateService</literal> to be used by this bean.
</para>
<para>
The description of the remaining tags is identical to the one for stateless session bean.
@@ -473,7 +502,7 @@
</para>
</section>
<section>
- <title>The HASessionState service configuration</title>
+ <title>The HASessionStateService configuration</title>
<para>
The <literal>HASessionStateService</literal> bean is defined in the
<code>all/deploy/cluster/ha-legacy-jboss-beans.xml</code> file.</para>
@@ -512,12 +541,12 @@
<listitem>
<para>
<emphasis role="bold">beanCleaningDelay</emphasis> is an optional attribute to specify
- the number of miliseconds after which the <literal>HASessionStateService</literal> bean can
+ the number of miliseconds after which the <literal>HASessionStateService</literal> can
clean a state that has not been modified. If a node, owning a bean, crashes, its brother
node will take ownership of this bean. Nevertheless, the container cache of the brother
node will not know about it (because it has never seen it before) and will never delete
according to the cleaning settings of the bean. That is why the
- <literal>HASessionStateService</literal> bean needs to do this cleanup sometimes. The
+ <literal>HASessionStateService</literal> needs to do this cleanup sometimes. The
default value is <literal>30*60*1000</literal> milliseconds (i.e., 30 minutes).
</para>
</listitem>
More information about the jboss-cvs-commits
mailing list