[jboss-cvs] JBossAS SVN: r93162 - projects/docs/community/5/Clustering_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Sep 3 09:50:59 EDT 2009
Author: pferraro
Date: 2009-09-03 09:50:58 -0400 (Thu, 03 Sep 2009)
New Revision: 93162
Modified:
projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_EJBs.xml
Log:
Updated config references. More detail for EJB3 annotations.
Modified: projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_EJBs.xml
===================================================================
--- projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_EJBs.xml 2009-09-03 12:41:03 UTC (rev 93161)
+++ projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_EJBs.xml 2009-09-03 13:50:58 UTC (rev 93162)
@@ -14,21 +14,65 @@
<section id="clustering-session-slsb30">
<title>Stateless Session Bean in EJB 3.0</title>
<para>
- Clustering stateless session beans is most probably the easiest case: as no state is involved, calls can be load-balanced on any participating node (i.e. any node that has this specific bean deployed) of the cluster.
+ Clustering stateless session beans is probably the easiest case since no state is involved.
+ 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
@@ -42,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>
@@ -61,32 +105,14 @@
<note>
<para>
- The <literal><clustered>true</clustered></literal> element is really just an alias for the <literal><configuration-name>Clustered Stateless SessionBean</configuration-name></literal> element in the conf/standard-jboss.xml file.
+ The <literal><clustered>true</clustered></literal> element is really just an alias for the <literal><container-name>Clustered Stateless SessionBean</container-name></literal> element in the conf/standardjboss.xml file.
</para>
</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>
@@ -100,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
{
@@ -116,7 +146,7 @@
]]></programlisting>
<itemizedlist>
- <listitem><para><literal>name</literal> specifies the name of a cache configuration registered with the <literal>CacheManager</literal> service discussed in <xref linkend="clustering-blocks-jbc-cachemanager"/>. By default, the <literal>sfsb-cache</literal> configuration will be used.</para></listitem>
+ <listitem><para><literal>name</literal> specifies the name of a cache configuration registered with the <literal>CacheManager</literal> service discussed in <xref linkend="sfsb-jbc-cachemanager"/>. By default, the <literal>sfsb-cache</literal> configuration will be used.</para></listitem>
<listitem><para><literal>maxSize</literal> specifies the maximum number of beans that can cached before the cache should start passivating beans, using an LRU algorithm.</para></listitem>
<listitem><para><literal>idleTimeoutSeconds</literal> specifies the max period of time a bean can go unused before the cache should passivate it (irregardless of whether maxSize beans are cached.)</para></listitem>
<listitem><para><literal>removalTimeoutSeconds</literal> specifies the max period of time a bean can go unused before the cache should remove it altogether.</para></listitem>
@@ -177,7 +207,7 @@
</para>
</section>
- <section>
+ <section id="sfsb-jbc-cachemanager">
<title>CacheManager service configuration</title>
<para>
JBoss Cache provides the session state replication service for EJB 3.0 stateful session beans.
@@ -200,6 +230,7 @@
<property name="nodeLockingScheme">PESSIMISTIC</property>
<property name="isolationLevel">REPEATABLE_READ</property>
+ <property name="useLockStriping">false</property>
<property name="cacheMode">REPL_ASYNC</property>
<!--
@@ -408,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 AS
- 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>
@@ -443,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.
@@ -471,53 +502,51 @@
</para>
</section>
<section>
- <title>The HASessionState service configuration</title>
+ <title>The HASessionStateService configuration</title>
<para>
- The <literal>HASessionState</literal> service MBean is defined in the
- <code>all/deploy/cluster-service.xml</code> file.</para>
+ The <literal>HASessionStateService</literal> bean is defined in the
+ <code>all/deploy/cluster/ha-legacy-jboss-beans.xml</code> file.</para>
<programlisting><![CDATA[
-<mbean code="org.jboss.ha.hasessionstate.server.HASessionStateService" name="jboss:service=HASessionState">
- <depends>jboss:service=Naming</depends>
- <!--
- We now inject the partition into the HAJNDI service instead
- of requiring that the partition name be passed
- -->
- <depends optional-attribute-name="ClusterPartition" proxy-type="attribute">
- jboss:service=${jboss.partition.name:DefaultPartition}
- </depends>
+<bean name="HASessionStateService"
+ class="org.jboss.ha.hasessionstate.server.HASessionStateService">
+
+ <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss:service=HASessionState", exposedInterface=org.jboss.ha.hasessionstate.server.HASessionStateServiceMBean.class, registerDirectly=true)</annotation>
+
+ <!-- Partition used for group RPCs -->
+ <property name="HAPartition"><inject bean="HAPartition"/></property>
+
<!-- JNDI name under which the service is bound -->
- <attribute name="JndiName">/HASessionState/Default</attribute>
- <!--
- Max delay before cleaning unreclaimed state.
- Defaults to 30*60*1000 => 30 minutes
- -->
- <attribute name="BeanCleaningDelay">0</attribute>
-</mbean>
+ <property name="jndiName">/HASessionState/Default</property>
+ <!-- Max delay before cleaning unreclaimed state.
+ Defaults to 30*60*1000 => 30 minutes -->
+ <property name="beanCleaningDelay">0</property>
+
+</bean>
]]></programlisting>
- <para>The configuration attributes in the <literal>HASessionState</literal> MBean are listed below.</para>
+ <para>The configuration attributes in the <literal>HASessionStateService</literal> bean are listed below.</para>
<itemizedlist>
<listitem>
<para>
- <emphasis role="bold">ClusterPartition</emphasis> is a required attribute to inject the HAPartition service that HA-JNDI uses for intra-cluster communication.
+ <emphasis role="bold">HAPartition</emphasis> is a required attribute to inject the HAPartition service that HA-JNDI uses for intra-cluster communication.
</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">JndiName</emphasis> is an optional attribute to specify the JNDI
- name under which this <literal>HASessionState</literal> service is bound. The default
+ <emphasis role="bold">jndiName</emphasis> is an optional attribute to specify the JNDI
+ name under which this <literal>HASessionStateService</literal> bean is bound. The default
value is <literal>/HAPartition/Default</literal>.
</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">BeanCleaningDelay</emphasis> is an optional attribute to specify
- the number of miliseconds after which the <literal>HASessionState</literal> service can
+ <emphasis role="bold">beanCleaningDelay</emphasis> is an optional attribute to specify
+ 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>HASessionState</literal> service 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