[jboss-cvs] JBossAS SVN: r99093 - projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Jan 7 00:30:59 EST 2010
Author: laubai
Date: 2010-01-07 00:30:57 -0500 (Thu, 07 Jan 2010)
New Revision: 99093
Modified:
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/AOP.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Administration_And_Configuration_Guide.ent
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_EJBs.xml
Log:
Corrected Clustering Session EJBs.
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/AOP.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/AOP.xml 2010-01-07 05:27:01 UTC (rev 99092)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/AOP.xml 2010-01-07 05:30:57 UTC (rev 99093)
@@ -51,7 +51,7 @@
<para>For example, let's say you wanted to add code to an application to measure the amount of time it would take to invoke a particular method. In plain Java, the code would look something like the following. </para>
-<programlisting id="aop.code1" role="JAVA">public class BankAccountDAO
+<programlisting role="JAVA">public class BankAccountDAO
{
public void withdraw(double amount)
{
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Administration_And_Configuration_Guide.ent
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Administration_And_Configuration_Guide.ent 2010-01-07 05:27:01 UTC (rev 99092)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Administration_And_Configuration_Guide.ent 2010-01-07 05:30:57 UTC (rev 99093)
@@ -1,4 +1,4 @@
<!ENTITY HOLDER "Red Hat, Inc">
-<!ENTITY YEAR "2009">
-<!ENTITY JBPAPP "JBoss Enterprise Application Platform">
-<!ENTITY VER "5.0">
+<!ENTITY YEAR "2010">
+<!ENTITY JBPAPP "JBoss Enterprise Web Platform">
+<!ENTITY VERSION "5.0">
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_EJBs.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_EJBs.xml 2010-01-07 05:27:01 UTC (rev 99092)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_EJBs.xml 2010-01-07 05:30:57 UTC (rev 99093)
@@ -4,57 +4,72 @@
<chapter id="clustering-session">
<title>Clustered Session EJBs</title>
<para>
- Session EJBs provide remote invocation services.
- They are clustered based on the client-side interceptor architecture.
- The client application for a clustered session bean is the same as the client for the non-clustered version of the session bean, except for some minor changes.
- No code change or re-compilation is needed on the client side.
- Now, let's check out how to configure clustered session beans in EJB 3.0 and EJB 2.x server applications respectively.
+ Session EJBs provide remote invocation services. They are clustered based
+ on the client-side interceptor architecture. The client application for a
+ clustered session bean is the same as the client for the non-clustered
+ version of the session bean, except for some minor changes. No code change
+ or re-compilation is needed on the client side. This chapter shows you how
+ to configure clustered session beans in EJB 3.0 and EJB 2.x server
+ applications respectively.
</para>
<section id="clustering-session-slsb30">
<title>Stateless Session Bean in EJB 3.0</title>
<para>
- 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.
+ Clustering stateless session beans is the simplest case since no state is
+ involved. Calls can be load balanced to any participating node (that is,
+ any node that has this specific bean deployed) of the cluster.
</para>
<para>
- 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.
+ 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 id="clustered-annotation"><![CDATA[
+<programlisting><![CDATA[
public @interface Clustered
{
String partition() default "${jboss.partition.name:DefaultPartition}";
String loadBalancePolicy() default "LoadBalancePolicy";
}
]]></programlisting>
- <itemizedlist>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>partition</varname></term>
<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.
+ 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
+ <varname>jboss.partition.name</varname> system property.
</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>loadBalancePolicy</varname></term>
<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:
+ Defines the name of a class implementing
+ <classname>org.jboss.ha.client.loadbalance.LoadBalancePolicy</classname>,
+ 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>
@@ -64,16 +79,17 @@
</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>
+ </varlistentry>
+ </variablelist>
+ <para>
+ The following is an example of a clustered EJB 3.0 stateless session bean implementation:
+ </para>
<programlisting><![CDATA[
@Stateless
@Clustered
@@ -86,7 +102,8 @@
}
]]></programlisting>
<para>
- Rather than using the <literal>@Clustered</literal> annotation, you can also enable clustering for a session bean in jboss.xml:
+ Rather than using the <literal>@Clustered</literal> annotation, you can also enable
+ clustering for a session bean in <filename>jboss.xml</filename>:
</para>
<programlisting><![CDATA[
<jboss>
@@ -105,13 +122,19 @@
<note>
<para>
- 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.
+ The <literal><![CDATA[<clustered>true</clustered>]]></literal> element is
+ an alias for the
+ <literal><![CDATA[<container-name>Clustered Stateless SessionBean</container-name>]]></literal>
+ element in the <filename>conf/standardjboss.xml</filename> file.
</para>
</note>
<para>
- 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.
+ In the bean configuration, only the <literal><![CDATA[<clustered>]]></literal>
+ element is necessary to indicate that the bean needs to support clustering
+ features. The default values for the optional
+ <literal><![CDATA[<cluster-config>]]></literal> elements match those of the
+ corresponding properties from the <literal>@Clustered</literal> annotation.
</para>
</section>
@@ -119,20 +142,28 @@
<section id="clustering-session-sfsb30">
<title>Stateful Session Beans in EJB 3.0</title>
<para>
- 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.
+ 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 is replicated and synchronized
+ across the cluster each time the state of a bean changes.
</para>
<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>@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.
+ 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
+ <classname>org.jboss.ha.client.loadbalance.aop.FirstAvailable</classname>
+ 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:
+ The <literal>@org.jboss.ejb3.annotation.CacheConfig</literal> annotation
+ can also be applied to the bean to override the default caching behavior.
+ The definition of the <literal>@CacheConfig</literal> annotation is:
</para>
<programlisting><![CDATA[
public @interface CacheConfig
@@ -145,15 +176,38 @@
}
]]></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="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 (regardless 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>
- <listitem><para><literal>replicationIsPassivation</literal> specifies whether the cache should consider a replication as being equivalent to a passivation, and invoke any @PrePassivate and @PostActivate callbacks on the bean. By default true, since replication involves serializing the bean, and preparing for and recovering from serialization is a common reason for implementing the callback methods.</para></listitem>
- </itemizedlist>
+ <variablelist>
+ <varlistentry><term><varname>name</varname></term>
+ <listitem><para>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>
+ </varlistentry>
+ <varlistentry><term><varname>maxSize</varname></term>
+ <listitem><para>Specifies the maximum number of beans that can cached before the
+ cache should start passivating beans, using an LRU algorithm.</para></listitem>
+ </varlistentry>
+ <varlistentry><term><varname>idleTimeoutSeconds</varname></term>
+ <listitem><para>Specifies the maximum period of time a bean can go unused
+ before the cache should passivate it (regardless of whether
+ <varname>maxSize</varname> beans are cached).</para></listitem>
+ </varlistentry>
+ <varlistentry><term><varname>removalTimeoutSeconds</varname></term>
+ <listitem><para>Specifies the maximum period of time a bean can go unused
+ before the cache should remove it altogether.</para></listitem>
+ </varlistentry>
+ <varlistentry><term><varname>replicationIsPassivation</varname></term>
+ <listitem><para>Specifies whether the cache should consider a replication as
+ being equivalent to a passivation, and invoke any <literal>@PrePassivate</literal>
+ and <literal>@PostActivate</literal> callbacks on the bean. By default this is
+ set to <literal>true</literal>, since replication involves serializing the bean,
+ and preparing for and recovering from serialization is a common reason for
+ implementing the callback methods.</para></listitem>
+ </varlistentry>
+ </variablelist>
- <para>Here is an example of a clustered EJB 3.0 stateful session bean implementation.</para>
+ <para>The following is an example of a clustered EJB 3.0 stateful
+ session bean implementation.</para>
<programlisting><![CDATA[
@Stateful
@Clustered
@@ -170,7 +224,9 @@
]]></programlisting>
<para>
- As with stateless beans, the @Clustered annotation can alternatively be omitted and the clustering configuration instead applied to jboss.xml:
+ As with stateless beans, the <literal>@Clustered</literal> annotation
+ can alternatively be omitted and the clustering configuration instead
+ applied to <filename>jboss.xml</filename> like so:
</para>
<programlisting><![CDATA[
<jboss>
@@ -191,8 +247,9 @@
<section>
<title>Optimize state replication</title>
<para>
- As the replication process is a costly operation, you can optimise this behaviour by
- optionally implementing the org.jboss.ejb3.cache.Optimized interface in your bean class:
+ As the replication process is a costly operation, you can optimise
+ this behaviour by optionally implementing the
+ <classname>org.jboss.ejb3.cache.Optimized</classname> interface in your bean class:
</para>
<programlisting><![CDATA[
public interface Optimized
@@ -201,18 +258,25 @@
}
]]></programlisting>
<para>
- Before replicating your bean, the container will check if your bean implements the <literal>Optimized</literal> interface.
- If this is the case, the container calls the <literal>isModified()</literal> method and will only replicate the bean when the method returns <literal>true</literal>.
- If the bean has not been modified (or not enough to require replication, depending on your own preferences), you can return <literal>false</literal> and the replication would not occur.
+ Before replicating your bean, the container will check whether your bean
+ implements the <literal>Optimized</literal> interface. If this is the case,
+ the container calls the <methodname>isModified()</methodname> method and will
+ only replicate the bean when the method returns <literal>true</literal>.
+ If the bean has not been modified (or not enough to require replication,
+ depending on your own preferences), you can return <literal>false</literal>
+ and replication would not occur.
</para>
</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.
- The <literal>CacheManager</literal> service, described in <xref linkend="clustering-blocks-jbc-cachemanager"/> is both a factory and registry of JBoss Cache instances.
- By default, stateful session beans use the <literal>sfsb-cache</literal> configuration from the <literal>CacheManager</literal>, defined as follows:
+ JBoss Cache provides the session state replication service for EJB 3.0
+ stateful session beans. The <classname>CacheManager</classname> service,
+ described in <xref linkend="clustering-blocks-jbc-cachemanager"/> is both
+ a factory and registry of JBoss Cache instances. By default, stateful
+ session beans use the <literal>sfsb-cache</literal> configuration from
+ the <classname>CacheManager</classname>, defined as follows:
</para>
<programlisting><![CDATA[
<bean name="StandardSFSBCacheConfig" class="org.jboss.cache.config.Configuration">
@@ -338,43 +402,52 @@
<formalpara>
<title>Eviction</title>
<para>
- The default SFSB cache is configured to support eviction.
- The EJB3 SFSB container uses the JBoss Cache eviction mechanism to manage SFSB passivation.
- When beans are deployed, the EJB container will programatically add eviction regions to the cache, one region per bean type.
+ The default SFSB cache is configured to support eviction. The EJB3 SFSB
+ container uses the JBoss Cache eviction mechanism to manage SFSB passivation.
+ When beans are deployed, the EJB container will programatically add eviction
+ regions to the cache, one region per bean type.
</para>
</formalpara>
<formalpara>
<title>CacheLoader</title>
<para>
- A JBoss Cache CacheLoader is also configured; again to support SFSB passivation.
- When beans are evicted from the cache, the cache loader passivates them to a persistent store;
- in this case to the filesystem in the $JBOSS_HOME/server/all/data/sfsb directory.
- JBoss Cache supports a variety of different CacheLoader implementations that know how to store
- data to different persistent store types; see the JBoss Cache documentation for details.
- However, if you change the CacheLoaderConfiguration, be sure that you do not use a shared store, e.g. a single schema in a shared database.
- Each node in the cluster must have its own persistent store, otherwise as nodes independently passivate and activate clustered beans, they will corrupt each other's data.
+ A JBoss Cache <classname>CacheLoader</classname> is also configured; again to
+ support SFSB passivation. When beans are evicted from the cache, the cache loader
+ passivates them to a persistent store; in this case to the filesystem in the
+ <filename>$JBOSS_HOME/server/all/data/sfsb</filename> directory.
+ JBoss Cache supports a variety of different <classname>CacheLoader</classname>
+ implementations that know how to store data to different persistent store types;
+ see the JBoss Cache documentation for details. However, if you change the
+ <varname>CacheLoaderConfig</varname>, be sure that you do not use a shared
+ store, for example, a single schema in a shared database. Each node in the cluster
+ must have its own persistent store, otherwise as nodes independently passivate
+ and activate clustered beans, they will corrupt each other's data.
</para>
</formalpara>
<formalpara>
<title>Buddy Replication</title>
<para>
- Using buddy replication, state is replicated to a configurable number of backup servers in the cluster (a.k.a.buddies), rather than to all servers in the cluster.
- To enable buddy replication, adjust the following properties in the <literal>buddyReplicationConfig</literal> property bean:
+ Using buddy replication, state is replicated to a configurable number of backup
+ servers in the cluster (also known as <emphasis>buddies</emphasis>), rather than to
+ all servers in the cluster. To enable buddy replication, adjust the following
+ properties in the <classname>buddyReplicationConfig</classname> property bean:
<itemizedlist>
<listitem>
<para>
- Set <literal>enabled</literal> to <literal>true</literal>.
+ Set <varname>enabled</varname> to <literal>true</literal>.
</para>
</listitem>
<listitem>
<para>
- Use the <literal>buddyPoolName</literal> to form logical subgroups of nodes within the cluster.
- If possible, buddies will be chosen from nodes in the same buddy pool.
+ Use the <varname>buddyPoolName</varname> to form logical subgroups of nodes
+ within the cluster. If possible, buddies will be chosen from nodes in the
+ same buddy pool.
</para>
</listitem>
<listitem>
<para>
- Adjust the <literal>buddyLocatorConfig.numBuddies</literal> property to reflect the number of backup nodes to which each node should replicate its state.
+ Adjust the <varname>buddyLocatorConfig.numBuddies</varname> property to reflect
+ the number of backup nodes to which each node should replicate its state.
</para>
</listitem>
</itemizedlist>
@@ -387,8 +460,8 @@
<section id="clustering-session-slsb21">
<title>Stateless Session Bean in EJB 2.x</title>
<para>
- To make an EJB 2.x bean clustered, you need to modify its <literal>jboss.xml</literal>
- descriptor to contain a <literal><clustered></literal> tag.
+ To make an EJB 2.x bean clustered, you need to modify its <filename>jboss.xml</filename>
+ descriptor to contain a <literal><![CDATA[<clustered>]]></literal> tag.
</para>
<programlisting><![CDATA[
<jboss>
@@ -407,30 +480,39 @@
</jboss>
]]></programlisting>
- <itemizedlist>
+ <variablelist>
+ <varlistentry>
+ <term><varname>partition-name</varname></term>
<listitem>
<para>
- <emphasis role="bold">partition-name</emphasis> specifies the name of the cluster the bean
+ 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>
+ </varlistentry>
+ <varlistentry><term><varname>home-load-balance-policy</varname></term>
<listitem>
<para>
- <emphasis role="bold">home-load-balance-policy</emphasis> indicates the class to be used
- by the home 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.
+ Indicates the class to be used
+ by the home 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.
</para>
</listitem>
+ </varlistentry>
+ <varlistentry><term><varname>bean-load-balance-policy</varname></term>
<listitem>
<para>
- <emphasis role="bold">bean-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.
+ 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.
</para>
</listitem>
- </itemizedlist>
+ </varlistentry>
+ </variablelist>
</section>
<section id="clustering-session-sfsb21">
@@ -438,17 +520,18 @@
<para>
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 Web Platform
- 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>HASessionStateService</literal> bean configuration.
+ replicated and synchronized across the cluster each time the state of a bean changes. The
+ JBoss Enterprise Web Platform uses the <classname>HASessionStateService</classname> 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
+ <classname>HASessionStateService</classname> bean configuration.
</para>
<section>
<title>The EJB application configuration</title>
<para>
- In the EJB application, you need to modify the <literal>jboss.xml</literal> descriptor file
- for each stateful session bean and add the <literal><clustered></literal> tag.
+ In the EJB application, you need to modify the <filename>jboss.xml</filename> descriptor file
+ for each stateful session bean and add the <literal><![CDATA[<clustered>]]></literal> tag.
</para>
<programlisting><![CDATA[
<jboss>
@@ -468,19 +551,19 @@
</jboss>
]]></programlisting>
<para>
- In the bean configuration, only the <literal><clustered></literal> tag is mandatory to
- indicate that the bean works in a cluster. The <literal><cluster-config></literal>
+ In the bean configuration, only the <literal><![CDATA[<clustered>]]></literal> tag is mandatory to
+ indicate that the bean works in a cluster. The <literal><![CDATA[<cluster-config>]]></literal>
element is optional and its default attribute values are indicated in the sample configuration above.
</para>
<para>
- The <literal><session-state-manager-jndi-name></literal> tag is used to give the JNDI
- name of the <literal>HASessionStateService</literal> to be used by this bean.
+ The <literal><![CDATA[<session-state-manager-jndi-name>]]></literal> tag is used to give the JNDI
+ name of the <classname>HASessionStateService</classname> to be used by this bean.
</para>
<para>
The description of the remaining tags is identical to the one for stateless session bean.
- Actions on the clustered stateful session bean's home interface are by default load-balanced,
- round-robin. Once the bean's remote stub is available to the client, calls will not be
- load-balanced round-robin any more and will stay "sticky" to the first node in the list.
+ Actions on the clustered stateful session bean's home interface are by default
+ load-balanced round-robin. Once the bean's remote stub is available to the client, calls
+ will not be load-balanced round-robin any more and will "stick" to the first node in the list.
</para>
</section>
<section>
@@ -494,7 +577,7 @@
</programlisting>
<para>
Before replicating your bean, the container will detect if your bean implements this method.
- If your bean does, the container calls the <literal>isModified()</literal> method and it only
+ If your bean does, the container calls the <methodname>isModified()</methodname> method and it only
replicates the bean when the method returns <literal>true</literal>. If the bean has not been
modified (or not enough to require replication, depending on your own preferences), you can
return <literal>false</literal> and the replication would not occur.
@@ -503,8 +586,8 @@
<section>
<title>The HASessionStateService configuration</title>
<para>
- The <literal>HASessionStateService</literal> bean is defined in the
- <code><profile>/deploy/cluster/ha-legacy-jboss-beans.xml</code> file.</para>
+ The <classname>HASessionStateService</classname> bean is defined in the
+ <filename>$PROFILE/deploy/cluster/ha-legacy-jboss-beans.xml</filename> file.</para>
<programlisting><![CDATA[
<bean name="HASessionStateService"
class="org.jboss.ha.hasessionstate.server.HASessionStateService">
@@ -527,40 +610,55 @@
</bean>
]]></programlisting>
- <para>The configuration attributes in the <literal>HASessionStateService</literal> bean are listed below.</para>
- <itemizedlist>
+ <para>The configuration attributes in the <classname>HASessionStateService</classname>
+ bean are listed below.</para>
+ <variablelist>
+ <varlistentry><term><varname>HAPartition</varname></term>
<listitem>
<para>
- <emphasis role="bold">HAPartition</emphasis> is a required attribute to inject the HAPartition service that HA-JNDI uses for intra-cluster communication.
+ A required attribute to inject the <classname>HAPartition</classname> service
+ that HA-JNDI uses for intra-cluster communication.
</para>
</listitem>
+ </varlistentry>
+ <varlistentry><term><varname>jndiName</varname></term>
<listitem>
<para>
- <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
+ An optional attribute to specify the JNDI name under which this
+ <classname>HASessionStateService</classname> bean is bound. The default
value is <literal>/HAPartition/Default</literal>.
</para>
</listitem>
+ </varlistentry>
+ <varlistentry><term><varname>beanCleaningDelay</varname></term>
<listitem>
<para>
- <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>HASessionStateService</literal> needs to do this cleanup sometimes. The
- default value is <literal>30*60*1000</literal> milliseconds (i.e., 30 minutes).
+ An optional attribute to specify the number of miliseconds after which the
+ <classname>HASessionStateService</classname> 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, which is why
+ <classname>HASessionStateService</classname> must perform this cleanup. The
+ default value is <literal>30*60*1000</literal> milliseconds (that is, 30 minutes).
</para>
</listitem>
- </itemizedlist>
+ </varlistentry>
+ </variablelist>
</section>
<section><title>Handling Cluster Restart</title>
<para>
- We have covered the HA smart client architecture in <xref linkend="clustering-concepts-arch-proxy"/>. The default HA smart proxy client can only failover as long as one node in the cluster exists. If there is a complete cluster shutdown, the proxy becomes orphaned and loses knowledge of the available nodes in the cluster. There is no way for the proxy to recover from this. The proxy needs to look up a fresh set of targets out of JNDI/HA-JNDI when the nodes are restarted.
+ We have covered the HA smart client architecture in <xref linkend="clustering-concepts-arch-proxy"/>.
+ The default HA smart proxy client can only failover as long as one node in the cluster exists.
+ If there is a complete cluster shutdown, the proxy becomes orphaned and loses knowledge of the
+ available nodes in the cluster. There is no way for the proxy to recover from this. The proxy
+ needs to look up a fresh set of targets out of JNDI/HA-JNDI when the nodes are restarted.
</para>
<para>
- RetryInterceptor can be added to the proxy client side interceptor stack to allow for a transparent recovery from such a restart failure. To enable it for an EJB, setup an invoker-proxy-binding that includes the RetryInterceptor. Below is an example jboss.xml configuration.
+ <classname>RetryInterceptor</classname> can be added to the proxy client side interceptor stack
+ to allow for a transparent recovery from such a restart failure. To enable it for an EJB, setup
+ an invoker-proxy-binding that includes the <classname>RetryInterceptor</classname>. Below is an
+ example <filename>jboss.xml</filename> configuration.
</para>
<programlisting><![CDATA[
<jboss>
@@ -604,33 +702,43 @@
<section>
<title>JNDI Lookup Process</title>
<para>
- In order to recover the HA proxy, the RetryInterceptor does a lookup in JNDI.
- This means that internally it creates a new InitialContext and does a JNDI lookup.
- But, for that lookup to succeed, the InitialContext needs to be configured properly to find your naming server.
- The RetryInterceptor will go through the following steps in attempting to determine the proper naming environment properties:
+ In order to recover the HA proxy, the <classname>RetryInterceptor</classname> does a
+ lookup in JNDI. This means that internally it creates a new <classname>InitialContext</classname>
+ and does a JNDI lookup. For that lookup to succeed, the <classname>InitialContext</classname>
+ needs to be configured properly to find your naming server. The <classname>RetryInterceptor</classname>
+ will go through the following steps in attempting to determine the proper naming environment properties:
</para>
<orderedlist>
<listitem>
<para>
- It will check its own static retryEnv field.
- This field can be set by client code via a call to RetryInterceptor.setRetryEnv(Properties).
- This approach to configuration has two downsides:
- first, it reduces portability by introducing JBoss-specific calls to the client code;
- and second, since a static field is used only a single configuration per VM is possible.
+ It will check its own static <varname>retryEnv</varname> field. This field can be set
+ by client code via a call to <literal>RetryInterceptor.setRetryEnv(Properties)</literal>.
+ This approach to configuration has two downsides: first, it reduces portability by
+ introducing JBoss-specific calls to the client code; and second, since a static field
+ is used only a single configuration per VM is possible.
</para>
</listitem>
<listitem>
<para>
- If the retryEnv field is null, it will check for any environment properties bound to a ThreadLocal by the org.jboss.naming.NamingContextFactory class.
- To use this class as your naming context factory, in your jndi.properties set property java.naming.factory.initial=org.jboss.naming.NamingContextFactory.
- The advantage of this approach is use of org.jboss.naming.NamingContextFactory is simply a configuration option in your jndi.properties file, and thus your java code is unaffected.
- The downside is the naming properties are stored in a ThreadLocal and thus are only visible to the thread that originally created an InitialContext.
+ If the <varname>retryEnv</varname> field is null, it will check for any environment
+ properties bound to a <classname>ThreadLocal</classname> by the
+ <classname>org.jboss.naming.NamingContextFactory</classname> class.
+ To use this class as your naming context factory, set the
+ <varname>java.naming.factory.initial=org.jboss.naming.NamingContextFactory</varname>
+ property in your <filename>jndi.properties</filename>. The advantage of this approach
+ is use of <classname>org.jboss.naming.NamingContextFactory</classname> is simply a
+ configuration option in your <filename>jndi.properties</filename> file, and thus your
+ Java code is unaffected. The downside is the naming properties are stored in a
+ <classname>ThreadLocal</classname> and thus are only visible to the thread that
+ originally created an <classname>InitialContext</classname>.
</para>
</listitem>
<listitem>
<para>
- If neither of the above approaches yield a set of naming environment properties, a default InitialContext is used.
- If the attempt to contact a naming server is unsuccessful, by default the InitialContext will attempt to fall back on multicast discovery to find an HA-JNDI naming server.
+ If neither of the above approaches yield a set of naming environment properties,
+ a default <classname>InitialContext</classname> is used. If the attempt to contact
+ a naming server is unsuccessful, by default the <classname>InitialContext</classname>
+ will attempt to fall back on multicast discovery to find an HA-JNDI naming server.
See <xref linkend="clustering-jndi"/> for more on multicast discovery of HA-JNDI.
</para>
</listitem>
@@ -639,13 +747,25 @@
<section><title>SingleRetryInterceptor</title>
<para>
- The RetryInterceptor is useful in many use cases, but a disadvantage it has is that it will continue attempting to re-lookup the HA proxy in JNDI until it succeeds. If for some reason it cannot succeed, this process could go on forever, and thus the EJB call that triggered the RetryInterceptor will never return. For many client applications, this possibility is unacceptable. As a result, JBoss doesn't make the RetryInterceptor part of its default client interceptor stacks for clustered EJBs.
+ The <classname>RetryInterceptor</classname> is useful in many use cases, but a
+ disadvantage it has is that it will continue attempting to re-lookup the HA proxy in JNDI
+ until it succeeds. If for some reason it cannot succeed, this process could go on forever,
+ and thus the EJB call that triggered the <classname>RetryInterceptor</classname> will never
+ return. For many client applications, this possibility is unacceptable. As a result, JBoss
+ does not make the <classname>RetryInterceptor</classname> part of its default client
+ interceptor stacks for clustered EJBs.
</para>
<para>
- In a previous release, a new flavor of retry interceptor was introduced, the org.jboss.proxy.ejb.SingleRetryInterceptor. This version works like the RetryInterceptor, but only makes a single attempt to re-lookup the HA proxy in JNDI. If this attempt fails, the EJB call will fail just as if no retry interceptor was used. The SingleRetryInterceptor is now part of the default client interceptor stacks for clustered EJBs.
+ The <classname>org.jboss.proxy.ejb.SingleRetryInterceptor</classname> was introduced only
+ recently. This version works like the <classname>RetryInterceptor</classname>, but only
+ makes a single attempt to re-lookup the HA proxy in JNDI. If this attempt fails, the EJB call
+ will fail just as if no retry interceptor was used. The <classname>SingleRetryInterceptor</classname>
+ is now part of the default client interceptor stacks for clustered EJBs.
</para>
<para>
- The downside of the SingleRetryInterceptor is that if the retry attempt is made during a portion of a cluster restart where no servers are available, the retry will fail and no further attempts will be made.
+ The downside of the SingleRetryInterceptor is that if the retry attempt is made during a
+ portion of a cluster restart where no servers are available, the retry will fail and no
+ further attempts will be made.
</para>
</section>
</section>
More information about the jboss-cvs-commits
mailing list