[jboss-cvs] JBossAS SVN: r82584 - projects/docs/community/5/Clustering_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Jan 1 23:41:10 EST 2009
Author: bstansberry at jboss.com
Date: 2009-01-01 23:41:10 -0500 (Thu, 01 Jan 2009)
New Revision: 82584
Modified:
projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Introduction.xml
projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_JNDI.xml
Log:
[JBAS-6357] Update the HA-JNDI Chapter
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-01 23:48:34 UTC (rev 82583)
+++ projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Introduction.xml 2009-01-02 04:41:10 UTC (rev 82584)
@@ -47,7 +47,7 @@
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> <title>HAPartition</title>
+<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.
Modified: projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_JNDI.xml
===================================================================
--- projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_JNDI.xml 2009-01-01 23:48:34 UTC (rev 82583)
+++ projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_JNDI.xml 2009-01-02 04:41:10 UTC (rev 82584)
@@ -4,17 +4,24 @@
<chapter id="clustering-jndi">
<title>Clustered JNDI Services</title>
<para>
- JNDI is one of the most important services provided by the application server. The JBoss HA-JNDI (High Availability JNDI) service brings the following features to JNDI:</para>
+ JNDI is one of the most important services provided by the application
+ server. The JBoss HA-JNDI (High Availability JNDI) service brings the
+ following features to JNDI:</para>
<itemizedlist>
<listitem>
<para>
- Transparent failover of naming operations. If an HA-JNDI naming Context is connected to the HA-JNDI service on a particular JBoss AS instance, and that service fails or is shut down, the HA-JNDI client can transparently fail over to another AS instance.
+ Transparent failover of naming operations. If an HA-JNDI naming
+ Context is connected to the HA-JNDI service on a particular JBoss AS
+ instance, and that service fails or is shut down, the HA-JNDI client
+ can transparently fail over to another AS instance.
</para>
</listitem>
<listitem>
<para>
- Load balancing of naming operations. An HA-JNDI naming Context will automatically load balance its requests across all the HA-JNDI servers in the cluster.
- </para>
+ Load balancing of naming operations. An HA-JNDI naming Context will
+ automatically load balance its requests across all the HA-JNDI
+ servers in the cluster.
+ </para>
</listitem>
<listitem>
<para>
@@ -22,39 +29,53 @@
</para>
</listitem>
<listitem>
- <para>
- Unified view of JNDI trees cluster-wide. Client can connect to the HA-JNDI service running on any node in the cluster and find objects bound in JNDI on any other node. This is accomplished via two mechanisms:
- </para>
-</listitem>
-</itemizedlist>
+ <para>
+ Unified view of JNDI trees cluster-wide. A client can connect to the
+ HA-JNDI service running on any node in the cluster and find objects bound
+ in JNDI on any other node. This is accomplished via two mechanisms:
+ <itemizedlist>
+ <listitem>
+ <para>Cross-cluster lookups. A client can perform a lookup and the
+ server side HA-JNDI service has the ability to find things bound
+ in regular JNDI on any node in the cluster.
+ </para>
+ </listitem>
+ <listitem>
+ <para>A replicated cluster-wide context tree. An object bound into
+ the HA-JNDI service will be replicated around the cluster, and a
+ copy of that object will be available in-VM on each node in the cluster.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+
+</itemizedlist>
- <itemizedlist>
- <listitem>
- <para>Cross-cluster lookups. A client can perform a lookup and the server side HA-JNDI service has the ability to find things bound in regular JNDI on any node in the cluster.
- </para>
- </listitem>
- <listitem>
- <para>A replicated cluster-wide context tree. An object bound into the HA-JNDI service will be replicated around the cluster, and a copy of that object will be available in-VM on each node in the cluster.
- </para>
- </listitem>
- </itemizedlist>
-
-
-
-
<para>
- JNDI is a key component for many other interceptor-based clustering services: those services register themselves with the JNDI so that the client can lookup their proxies and make use of their services. HA-JNDI completes the picture by ensuring that clients have a highly-available means to look up those proxies. However, it is important to understand that using HA-JNDI (or not) has no effect whatsoever on the clustering behavior of the objects that are looked up. To illustrate:
+ JNDI is a key component for many other interceptor-based clustering services:
+ those services register themselves with JNDI so the client can look up their
+ proxies and make use of their services. HA-JNDI completes the picture by
+ ensuring that clients have a highly-available means to look up those proxies.
+ However, it is important to understand that using HA-JNDI (or not) has no
+ effect whatsoever on the clustering behavior of the objects that are
+ looked up. To illustrate:
</para>
<itemizedlist>
<listitem>
<para>
- If an EJB is not configured as clustered, looking up the EJB via HA-JNDI does not somehow result in the addition of clustering capabilities (load balancing of EJB calls, transparent failover, state replication) to the EJB.
+ If an EJB is not configured as clustered, looking up the EJB
+ via HA-JNDI does not somehow result in the addition of clustering
+ capabilities (load balancing of EJB calls, transparent failover,
+ state replication) to the EJB.
</para>
</listitem>
<listitem>
<para>
- If an EJB is configured as clustered, looking up the EJB via regular JNDI instead of HA-JNDI does not somehow result in the removal of the bean proxy's clustering capabilities.
+ If an EJB is configured as clustered, looking up the EJB via
+ regular JNDI instead of HA-JNDI does not somehow result in the
+ removal of the bean proxy's clustering capabilities.
</para>
</listitem>
</itemizedlist>
@@ -65,158 +86,211 @@
<section id="clustering-jndi-how">
<title>How it works</title>
<para>
- The JBoss client-side HA-JNDI naming Context is based on the client-side interceptor architecture. The client obtains an HA-JNDI proxy object (via the InitialContext object) and invokes JNDI lookup services on the remote server through the proxy. The client specifies that it wants an HA-JNDI proxy by configuring the naming properties used by the InitialContext object. This is covered in detail in the “Client Configuration” section. Other than the need to ensure the appropriate naming properties are provided to the InitialContext, the fact that the naming Context is using HA-JNDI is completely transparent to the client.
+ The JBoss client-side HA-JNDI naming Context is based on the client-side
+ interceptor architecture (see <xref linkend="clustering-intro-arch-proxy"/>).
+ The client obtains an HA-JNDI proxy object (via the <literal>InitialContext</literal>
+ object) and invokes JNDI lookup services on the remote server through the proxy.
+ The client specifies that it wants an HA-JNDI proxy by configuring the
+ naming properties used by the <literal>InitialContext</literal> object.
+ This is covered in detail in <xref linkend="clustering-jndi-client"/>.
+ Other than the need to ensure the appropriate naming properties are provided
+ to the <literal>InitialContext</literal>, the fact that the naming
+ Context is using HA-JNDI is completely transparent to the client.
</para>
<para>
- On the server side, he the HA-JNDI service maintains a cluster-wide context tree. The cluster wide tree is always available as long as there is one node left in the cluster. Each node in the cluster also maintains its own local JNDI context tree. The HA-JNDI service on that node is able to find objects bound into the local JNDI context tree. An application can bind its objects to either tree. The design rationale for this architecture is as follows:
+ On the server side, the HA-JNDI service maintains a cluster-wide context
+ tree. The cluster wide tree is always available as long as there is one
+ node left in the cluster. Each node in the cluster also maintains its own
+ local JNDI context tree. The HA-JNDI service on each node is able to find
+ objects bound into the local JNDI context tree, and is also able to make
+ a cluster-wide RPC to find objects bound in the local tree on any other
+ node. An application can bind its objects to either tree, although in
+ practice most objects are bound into the local JNDI context tree. The design
+ rationale for this architecture is as follows:
</para>
<itemizedlist>
<listitem>
<para>
- It avoids migration issues with applications that assume that their JNDI implementation is local. This allows clustering to work out-of-the-box with just a few tweaks of configuration files.
+ It avoids migration issues with applications that assume that their
+ JNDI implementation is local. This allows clustering to work out-of-the-box
+ with just a few tweaks of configuration files.
</para>
- </listitem>
-
+ </listitem>
<listitem>
<para>
- In a homogeneous cluster, this configuration actually cuts down on the amount of network traffic. A homogenous cluster is one where the same types of objects are bound under the same names on each node.
+ In a homogeneous cluster, this configuration actually cuts down on
+ the amount of network traffic. A homogenous cluster is one where the
+ same types of objects are bound under the same names on each node.
</para>
</listitem>
<listitem>
<para>
- Designing it in this way makes the HA-JNDI service an optional service since all underlying cluster code uses a straight new <literal>InitialContext()</literal> to lookup or create bindings.
+ Designing it in this way makes the HA-JNDI service an optional service
+ since all underlying cluster code uses a straight new <literal>InitialContext</literal>
+ to lookup or create bindings.
</para>
</listitem>
</itemizedlist>
<para>
- On the server side, a naming <literal>Context</literal> obtained via a call to new <literal>InitialContext()</literal> will be bound to the local-only, non-cluster-wide JNDI Context (this is actually basic JNDI). So, all EJB homes and such will not be bound to the cluster-wide JNDI Context, but rather, each home will be bound into the local JNDI.
+ On the server side, a naming Context obtained via a call
+ to <literal>new InitialContext()</literal> will be bound to the local-only,
+ non-cluster-wide JNDI Context. So, all EJB homes and such will not be bound
+ to the cluster-wide JNDI Context, but rather, each home will be bound into
+ the local JNDI.
</para>
<para>
- When a remote client does a lookup through HA-JNDI, HA-JNDI will delegate to the local JNDI Context when it cannot find the object within the global cluster-wide Context. The detailed lookup rule is as follows.
+ When a remote client does a lookup through HA-JNDI, HA-JNDI will delegate
+ to the local JNDI service when it cannot find the object within the global
+ cluster-wide Context. The detailed lookup rule is as follows.
</para>
<itemizedlist>
<listitem>
<para>If the binding is available in the cluster-wide JNDI tree, return it.</para>
</listitem>
<listitem>
- <para>If the binding is not in the cluster-wide tree, delegate the lookup query to the local JNDI service and return the received answer if available.</para>
+ <para>If the binding is not in the cluster-wide tree, delegate the lookup
+ query to the local JNDI service and return the received answer if available.</para>
</listitem>
<listitem>
- <para>If not available, the HA-JNDI services asks all other nodes in the cluster if their local JNDI service owns such a binding and returns the answer from the set it receives.</para>
+ <para>If not available, the HA-JNDI service asks all other nodes in
+ the cluster if their local JNDI service owns such a binding and
+ returns the answer from the set it receives.</para>
</listitem>
<listitem>
- <para>If no local JNDI service owns such a binding, a <literal>NameNotFoundException</literal> is finally raised.</para>
+ <para>If no local JNDI service owns such a binding, a
+ <literal>NameNotFoundException</literal> is finally raised.</para>
</listitem>
</itemizedlist>
<para>
- In practice, objects are rarely bound in the cluster-wide JNDI tree; rather they are bound in the local JNDI tree. For example, when EJBs are deployed, their proxies are always bound in local JNDI, not HA-JNDI. So, an EJB home lookup done through HA-JNDI will always be delegated to the local JNDI instance.
+ In practice, objects are rarely bound in the cluster-wide JNDI tree;
+ rather they are bound in the local JNDI tree. For example, when EJBs are
+ deployed, their proxies are always bound in local JNDI, not HA-JNDI.
+ So, an EJB home lookup done through HA-JNDI will always be delegated to
+ the local JNDI instance.
</para>
<note><title>Note</title>
<para>
- If different beans (even of the same type, but participating in different clusters) use the same JNDI name, this means that each JNDI server will have a logically different "target" bound (JNDI on node 1 will have a binding for bean A and JNDI on node 2 will have a binding, under the same name, for bean B). Consequently, if a client performs a HA-JNDI query for this name, the query will be invoked on any JNDI server of the cluster and will return the locally bound stub. Nevertheless, it may not be the correct stub that the client is expecting to receive! So, it is always best practice to ensure that across the cluster different names are used for logically different bindings.
+ If different beans (even of the same type, but participating in
+ different clusters) use the same JNDI name, this means that each JNDI
+ server will have a logically different "target" bound under the same
+ name. (JNDI on node 1 will have a binding for bean A and JNDI on node
+ 2 will have a binding, under the same name, for bean B). Consequently,
+ if a client performs a HA-JNDI query for this name, the query will be
+ invoked on any JNDI server of the cluster and will return the locally
+ bound stub. Nevertheless, it may not be the correct stub that the client
+ is expecting to receive! So, it is always best practice to ensure that
+ across the cluster different names are used for logically different bindings.
</para>
</note>
+
+ <note><title>Note</title>
+ <para>
+ If a binding is only made available on a few nodes in the cluster (for
+ example because a bean is only deployed on a small subset of nodes in
+ the cluster), the probability is higher that a lookup will hit a
+ HA-JNDI server that does not own this binding and thus the lookup will need
+ to be forwarded to all nodes in the cluster. Consequently, the query
+ time will be longer than if the binding would have been available locally.
+ Moral of the story: as much as possible, cache the result of your JNDI
+ queries in your client.
+ </para>
+ </note>
-
<note><title>Note</title>
<para>
- You cannot currently use a non-JNP JNDI implementation (i.e. LDAP) for your local JNDI implementation if you want to use HA-JNDI. However, you can use JNDI federation using the ExternalContext MBean to bind non-JBoss JNDI trees into the JBoss JNDI namespace. Furthermore, nothing prevents you using one centralized JNDI server for your whole cluster and scrapping HA-JNDI and JNP.
+ You cannot currently use a non-JNP JNDI implementation (i.e. LDAP) for
+ your local JNDI implementation if you want to use HA-JNDI. However, you
+ can use JNDI federation using the <literal>ExternalContext</literal>
+ MBean to bind non-JBoss JNDI trees into the JBoss JNDI namespace.
+ Furthermore, nothing prevents you using one centralized JNDI server
+ for your whole cluster and scrapping HA-JNDI and JNP.
</para>
- </note>
-
- <note><title>Note</title>
- <para>
- If a binding is only made available on a few nodes in the cluster (for example because a bean is only deployed on a small subset of nodes in the cluster), the probability that a lookup will hit a HA-JNDI server that does not own this binding is higher and thus the lookup will need to be forwarded to all nodes in the cluster. Consequently, the query time will be longer than if the binding would have been available locally. Moral of the story: as much as possible, cache the result of your JNDI queries in your client.
- </para>
</note>
-
-
-
-
- <para>So, an EJB home lookup through HA-JNDI, will always be delegated to the local JNDI instance. If
- different beans (even of the same type, but participating in different clusters) use the same JNDI
- name, it means that each JNDI server will have a different "target" bound (JNDI on node 1 will have
- a binding for bean A and JNDI on node 2 will have a binding, under the same name, for bean B).
- Consequently, if a client performs a HA-JNDI query for this name, the query will be invoked on any
- JNDI server of the cluster and will return the locally bound stub. Nevertheless, it may not be the
- correct stub that the client is expecting to receive!</para>
- <note>
- <para>You cannot currently use a non-JNP JNDI implementation (i.e. LDAP) for your local JNDI
- implementation if you want to use HA-JNDI. However, you can use JNDI federation using the
- <literal>ExternalContext</literal> MBean to bind non-JBoss JNDI trees into the JBoss JNDI
- namespace. Furthermore, nothing prevents you though of using one centralized JNDI server for
- your whole cluster and scrapping HA-JNDI and JNP.</para>
- </note>
- <note>
- <para>If a binding is only made available on a few nodes in the cluster (for example because a bean
- is only deployed on a small subset of nodes in the cluster), the probability to lookup a HA-JNDI
- server that does not own this binding is higher and the lookup will need to be forwarded to all
- nodes in the cluster. Consequently, the query time will be longer than if the binding would have
- been available locally. Moral of the story: as much as possible, cache the result of your JNDI
- queries in your client.</para>
- </note>
</section>
<section id="clustering-jndi-client">
<title>Client configuration</title>
+
+ <para>Configuring a client to use HA-JNDI is a matter of ensuring the
+ correct set of naming environment properties are available when a new
+ <literal>InitialContext</literal> is created. How this is done varies
+ depending on whether the client is running inside JBoss AS itself or
+ is in another VM.</para>
+
<section><title>For clients running inside the application server</title>
<para>
- If you want to access HA-JNDI from inside the application server, you must explicitly get an InitialContext by passing in JNDI properties. The following code shows how to create a naming Context bound to HA-JNDI:
+ If you want to access HA-JNDI from inside the application server, you
+ must explicitly configure your <literal>InitialContext</literal> by
+ passing in JNDI properties to the constructor. The following code shows
+ how to create a naming Context bound to HA-JNDI:
</para>
<programlisting role="JAVA">Properties p = new Properties();
-p.put(Context.INITIAL_CONTEXT_FACTORY,
-"org.jnp.interfaces.NamingContextFactory");
-p.put(Context.URL_PKG_PREFIXES, "jboss.naming:org.jnp.interfaces");
-p.put(Context.PROVIDER_URL, "localhost:1100"); // HA-JNDI port.
+p.put(Context.INITIAL_CONTEXT_FACTORY, "org.jnp.interfaces.NamingContextFactory");
+p.put(Context.URL_PKG_PREFIXES, "jboss.naming:org.jnp.interfaces");
+// HA-JNDI is listening on the address passed to JBoss via -b
+String bindAddress = System.getProperty("jboss.bind.address", "localhost");
+p.put(Context.PROVIDER_URL, bindAddress + ":1100"); // HA-JNDI address and port.
return new InitialContext(p);</programlisting>
<para>
-The Context.PROVIDER_URL property points to the HA-JNDI service configured in the HANamingService MBean (see the section called “JBoss configuration”).
+The Context.PROVIDER_URL property points to the HA-JNDI service configured in the
+<literal>deploy/cluster/hajndi-jboss-beans.xml</literal> file (see <xref linkend="clustering-jndi-jboss"/>).
+By default this service listens on the interface named via the
+<literal>jboss.bind.address</literal> system property, which itself is set to
+whatever value you assign to the <literal>-b</literal> command line option when
+you start JBoss AS (or <literal>localhost</literal> if not specified). The above
+code shows an example of accessing this property.
</para>
<para>
- However, this does not work in all cases, especially when running a multihomed cluster (several JBoss instances on one machine bound to different IPs). A safer method is not to specify the Context.PROVIDER_URL (which does not work in all scenarios) but the partition name property:
+ However, this does not work in all cases, especially when running several
+ JBoss AS instances on the same machine and bound to the same IP address, but
+ configured to use different ports. A safer method is to not specify the
+ Context.PROVIDER_URL but instead allow the <literal>InitialContext</literal>
+ to statically find the in-VM HA-JNDI by specifying the <literal>jnp.partitionName</literal>
+ property:
</para>
<programlisting role="JAVA">Properties p = new Properties();
p.put(Context.INITIAL_CONTEXT_FACTORY, "org.jnp.interfaces.NamingContextFactory");
p.put(Context.URL_PKG_PREFIXES, "jboss.naming:org.jnp.interfaces");
-p.put("jnp.partitionName", "DefaultPartition"); // partition name.
+// HA-JNDI is registered under the partition name passed to JBoss via -g
+String partitionName = System.getProperty("jboss.partition.name", "DefaultPartition");
+p.put("jnp.partitionName", partitionName);
return new InitialContext(p);</programlisting>
+<para>This example uses the <literal>jboss.partition.name</literal> system
+property to identify the partition with which the HA-JNDI service works. This
+system property is set to whatever value you assign to the <literal>-g</literal>
+command line option when you start JBoss AS (or <literal>DefaultPartition</literal>
+if not specified).
+</para>
+
<para>
- Do not attempt to simplify things by placing a jndi.properties file in your deployment or by editing the AS's conf/jndi.properties file. Doing either will almost certainly break things for your application and quite possibly across the application server. If you want to externalize your client configuration, one approach is to deploy a properties file not named jndi.properties, and then programatically create a Properties object that loads that file's contents.
+ Do not attempt to simplify things by placing a <literal>jndi.properties</literal>
+ file in your deployment or by editing the AS's <literal>conf/jndi.properties</literal>
+ file. Doing either will almost certainly break things for your application
+ and quite possibly across the application server. If you want to externalize
+ your client configuration, one approach is to deploy a properties file not
+ named <literal>jndi.properties</literal>, and then programatically create a
+ <literal>Properties</literal> object that loads that file's contents.
</para>
-<note><title>Note</title>
- <para>
- Previously, HANamingServiceMBean.bindAddress served two functions:
-
- From <filename>trunk/cluster/src/etc/hajndi-service.xml</filename>:
- <programlisting><!-- Bind address of bootstrap and HA-JNDI RMI endpoints -->
- <attribute name="BindAddress">${jboss.bind.address}</attribute></programlisting>
-
- The bootstrap and HA-JNDI RMI endpoints are now defined separately:
- <programlisting>
- <!-- Bind address of bootstrap endpoint -->
- <attribute name="BindAddress">${jboss.bind.address}</attribute>
- <!-- Bind address of the HA-JNDI RMI endpoint -->
- <attribute name="RmiBindAddress">${jboss.bind.address}</attribute>
- </programlisting>
- They each default to the same value.
- Users may want to override the RMI bind address if deployed on a multi-homed machine, and want to use an specific network interface for HA-JNDI RMI calls.
- This ability already exists in the standard NamingService.
- </para>
-</note>
-
-
<section><title>Accessing HA-JNDI Resources from EJBs and WARs -- Environment Naming Context</title>
- <para>If your HA-JNDI client is an EJB or servlet, the least intrusive way to configure the lookup of resources is to bind the resources to the environment naming context of the bean or webapp performing the lookup. The binding can then be configured to use HA-JNDI instead of a local mapping. Following is an example of doing this for a JMS connection factory and queue (the most common use case for this kind of thing.</para>
- <para>Within the bean definition in the ejb-jar.xml or in the war's web.xml you will need to define two resource-ref mappings, one for the connection factory and one for the destination.</para>
+ <para>If your HA-JNDI client is an EJB or servlet, the least intrusive way
+ to configure the lookup of resources is to bind the resources to the
+ environment naming context of the bean or webapp performing the lookup. The
+ binding can then be configured to use HA-JNDI instead of a local mapping.
+ Following is an example of doing this for a JMS connection factory and
+ queue (the most common use case for this kind of thing).</para>
+
+ <para>Within the bean definition in the ejb-jar.xml or in the war's web.xml
+ you will need to define two resource-ref mappings, one for the connection
+ factory and one for the destination.</para>
<programlisting role="XML"><resource-ref>
<res-ref-name>jms/ConnectionFactory</res-ref-name>
<res-type>javax.jms.QueueConnectionFactory</res-type>
@@ -230,22 +304,32 @@
</resource-ref></programlisting>
<para>
- Using these examples the bean performing the lookup can obtain the connection factory by looking up 'java:comp/env/jms/ConnectionFactory' and can obtain the queue by looking up 'java:comp/env/jms/Queue'.
+ Using these examples the bean performing the lookup can obtain the connection
+ factory by looking up 'java:comp/env/jms/ConnectionFactory' and can obtain the
+ queue by looking up 'java:comp/env/jms/Queue'.
</para>
<para>
-Within the JBoss-specific deployment descriptor (jboss.xml for EJBs, jboss-web.xml for a WAR) these references need to mapped to a URL that makes use of HA-JNDI.
+Within the JBoss-specific deployment descriptor (jboss.xml for EJBs, jboss-web.xml
+for a WAR) these references need to be mapped to a URL that makes use of HA-JNDI.
</para>
<programlisting role="XML"><resource-ref>
<res-ref-name>jms/ConnectionFactory</res-ref-name>
- <jndi-name>jnp://localhost:1100/ConnectionFactory</jndi-name>
+ <jndi-name>jnp://${jboss.bind.address}:1100/ConnectionFactory</jndi-name>
</resource-ref>
<resource-ref>
<res-ref-name>jms/Queue</res-ref-name>
- <jndi-name>jnp://localhost:1100/queue/A</jndi-name>
+ <jndi-name>jnp://${jboss.bind.address}:1100/queue/A</jndi-name>
</resource-ref></programlisting>
-<para>The URL should be the URL to the HA-JNDI server running on the same node as the bean; if the bean is available the local HA-JNDI server should also be available. The lookup will then automatically query all of the nodes in the cluster to identify which node has the JMS resources available.
+<para>The URL should be the URL to the HA-JNDI server running on the same node
+ as the bean; if the bean is available the local HA-JNDI server should also be
+ available. The lookup will then automatically query all of the nodes in the
+ cluster to identify which node has the JMS resources available.</para>
+<para>The <literal>${jboss.bind.address}</literal> syntax used above tells JBoss
+ to use the value of the <literal>jboss.bind.address</literal> system property
+ when determining the URL. That system property is itself set to whatever value
+ you assign to the <literal>-b</literal> command line option when you start JBoss AS.
</para>
</section>
@@ -271,53 +355,103 @@
<section><title>For clients running outside the application server</title>
- <para>The JNDI client needs to be aware of the HA-JNDI cluster. You can pass a list of JNDI servers (i.e., the nodes in the HA-JNDI cluster) to the <literal>java.naming.provider.url</literal> JNDI setting in the <literal>jndi.properties</literal> file. Each server node is identified by its IP address and the JNDI port number. The server nodes are separated by commas (see <xref linkend="clustering-jndi-jboss"/> for how to configure the servers and ports).</para>
+ <para>The JNDI client needs to be aware of the HA-JNDI cluster. You can
+ pass a list of JNDI servers (i.e., the nodes in the HA-JNDI cluster) to the
+ <literal>java.naming.provider.url</literal> JNDI setting in the
+ <literal>jndi.properties</literal> file. Each server node is identified
+ by its IP address and the JNDI port number. The server nodes are separated
+ by commas (see <xref linkend="clustering-jndi-jboss"/> for how to configure
+ the servers and ports).</para>
-<programlisting>java.naming.provier.url=server1:1100,server2:1100,server3:1100,server4:1100</programlisting>
- <para>When initialising, the JNP client code will try to get in touch with each server node from the
- list, one after the other, stopping as soon as one server has been reached. It will then download
- the HA-JNDI stub from this node.</para>
+<programlisting>java.naming.provider.url=server1:1100,server2:1100,server3:1100,server4:1100</programlisting>
+ <para>When initialising, the JNP client code will try to get in touch
+ with each server node from the list, one after the other, stopping as
+ soon as one server has been reached. It will then download the HA-JNDI
+ stub from this node.</para>
<note>
- <para>There is no load balancing behavior in the JNP client lookup process itself. It just goes through the provider lists and uses the first available server to obtain the stub. The HA-JNDI provider list only needs to contain a subset of HA-JNDI nodes in the cluster.</para>
+ <para>There is no load balancing behavior in the JNP client lookup process
+ itself. It just goes through the provider lists and uses the first
+ available server to obtain the stub. The HA-JNDI provider list only
+ needs to contain a subset of HA-JNDI nodes in the cluster; once the
+ HA-JNDI stub is downloaded, the stub will include information on
+ all the available servers. A good practice is to include a set of servers
+ such that you are certain that at least one of those in the list
+ will be available.</para>
</note>
<para>
- The downloaded smart proxy contains the list of currently running nodes and the logic to load balance naming requests and to fail-over to another node if necessary. Furthermore, each time a JNDI invocation is made to the server, the list of targets in the proxy interceptor is updated (only if the list has changed since the last call).
+ The downloaded smart proxy contains the list of currently running nodes and
+ the logic to load balance naming requests and to fail-over to another node
+ if necessary. Furthermore, each time a JNDI invocation is made to the server,
+ the list of targets in the proxy interceptor is updated (only if the list
+ has changed since the last call).
</para>
<para>
- If the property string java.naming.provider.url is empty or if all servers it mentions are not reachable, the JNP client will try to discover a HA-JNDI server through a multicast call on the network (auto-discovery). See the section called “JBoss configuration” on how to configure auto-discovery on the JNDI server nodes. Through auto-discovery, the client might be able to get a valid HA-JNDI server node without any configuration. Of course, for auto-discovery to work, the network segment(s) between the client and the server cluster must be configured to propagate such multicast datagrams.
+ If the property string <literal>java.naming.provider.url</literal> is empty
+ or if all servers it mentions are not reachable, the JNP client will try
+ to discover a HA-JNDI server through a multicast call on the network (auto-discovery).
+ See <xref linkend="clustering-jndi-jboss"/> for how to configure auto-discovery
+ on the JNDI server nodes. Through auto-discovery, the client might be able
+ to get a valid HA-JNDI server node without any configuration. Of course,
+ for auto-discovery to work, the network segment(s) between the client and
+ the server cluster must be configured to propagate such multicast datagrams.
</para>
<note>
- <para>By default the auto-discovery feature uses multicast group address 230.0.0.4 and port1102.</para>
+ <para>By default the auto-discovery feature uses multicast group address 230.0.0.4 and port 1102.</para>
</note>
- <para>In addition to the <literal>java.naming.provider.url</literal> property, you can specify a set of other properties. The following list shows all clustering-related client side properties you can specify when creating a new InitialContext. (All of the standard, non-clustering-related environment properties used with regular JNDI are also available.)</para>
+ <para>In addition to the <literal>java.naming.provider.url</literal> property,
+ you can specify a set of other properties. The following list shows all
+ clustering-related client side properties you can specify when creating a
+ new <literal>InitialContext</literal>. (All of the standard, non-clustering-related
+ environment properties used with regular JNDI are also available.)</para>
<itemizedlist>
<listitem>
- <para><literal>java.naming.provider.url</literal>: Provides a list of IP addresses and port
- numbers for HA-JNDI provider nodes in the cluster. The client tries those providers one by
- one and uses the first one that responds.</para>
+ <para><literal>java.naming.provider.url</literal>: Provides a list
+ of IP addresses and port numbers for HA-JNDI provider nodes in the
+ cluster. The client tries those providers one by one and uses the
+ first one that responds.</para>
</listitem>
<listitem>
- <para><literal>jnp.disableDiscovery</literal>: When set to <literal>true</literal>, this
- property disables the automatic discovery feature. Default is
- <literal>false</literal>.</para>
+ <para><literal>jnp.disableDiscovery</literal>: When set to <literal>true</literal>,
+ this property disables the automatic discovery feature. Default is
+ <literal>false</literal>.</para>
</listitem>
<listitem>
- <para><literal>jnp.partitionName</literal>: In an environment where multiple HA-JNDI services bound to distinct clusters (a.k.a. partitions), are running, this property allows you to ensure that your client only accepts automatic-discovery responses from servers in the desired partition. If you do not use the automatic discovery feature (i.e. jnp.disableDiscovery is true), this property is not used. By default, this property is not set and the automatic discovery select the first HA-JNDI server that responds, irregardless of the cluster partition name.</para>
+ <para><literal>jnp.partitionName</literal>: In an environment where
+ multiple HA-JNDI services bound to distinct clusters (a.k.a. partitions),
+ are running, this property allows you to ensure that your client only
+ accepts automatic-discovery responses from servers in the desired partition.
+ If you do not use the automatic discovery feature (i.e. jnp.disableDiscovery
+ is true), this property is not used. By default, this property is not set
+ and the automatic discovery selects the first HA-JNDI server that responds,
+ regardless of the cluster partition name.</para>
</listitem>
<listitem>
- <para><literal>jnp.discoveryTimeout</literal>: Determines how much time the context will wait
- for a response to its automatic discovery packet. Default is 5000 ms.</para>
+ <para><literal>jnp.discoveryTimeout</literal>: Determines how many
+ milliseconds the context will wait for a response to its automatic
+ discovery packet. Default is 5000 ms.</para>
</listitem>
<listitem>
- <para><literal>jnp.discoveryGroup</literal>: Determines which multicast group address is used for the automatic discovery. Default is 230.0.0.4. Must match the value of the AutoDiscoveryAddress configured on the server side HA-JNDI service.</para>
+ <para><literal>jnp.discoveryGroup</literal>: Determines which multicast
+ group address is used for the automatic discovery. Default is 230.0.0.4.
+ Must match the value of the AutoDiscoveryAddress configured on the server
+ side HA-JNDI service. Note that the server side HA-JNDI service by
+ default listens on the address specified via the <literal>-u</literal>
+ startup switch, so if <literal>-u</literal> is used on the server side
+ (as is recommended), jnp.discoveryGroup will need to be configured on
+ the client side.</para>
</listitem>
<listitem>
- <para><literal>jnp.discoveryPort</literal>: Determines which multicast group port is used for the automatic discovery. Default is 1102. Must match the value of the AutoDiscoveryPort configured on the server side HA-JNDI service.</para>
+ <para><literal>jnp.discoveryPort</literal>: Determines which multicast
+ port is used for the automatic discovery. Default is 1102. Must match the
+ value of the AutoDiscoveryPort configured on the server side HA-JNDI service.</para>
</listitem>
<listitem>
- <para><literal>jnp.discoveryTTL</literal>: specifies the TTL (time-to-live) for autodiscovery IP multicast packets. This value represents the number of network hops a multicast packet can be allowed to propagate before networking equipment should drop the packet. Despite its name, it does not represent a unit of time.
+ <para><literal>jnp.discoveryTTL</literal>: specifies the TTL (time-to-live) f
+ or autodiscovery IP multicast packets. This value represents the number of
+ network hops a multicast packet can be allowed to propagate before networking
+ equipment should drop the packet. Despite its name, it does not represent a unit of time.
</para>
</listitem>
@@ -325,130 +459,268 @@
</section>
+ </section>
-
<section id="clustering-jndi-jboss">
<title>JBoss configuration</title>
- <para>The <literal>cluster-service.xml</literal> file in the <literal>all/deploy</literal> directory
- includes the following MBean to enable HA-JNDI services.</para>
-<programlisting role="XML"><mbean code="org.jboss.ha.jndi.HANamingService"
-name="jboss:service=HAJNDI">
-<depends optional-attribute-name="ClusterPartition"
-proxy-type="attribute">jboss:service=${jboss.partition.name:DefaultPartition}</depends>
-
-<mbean></programlisting>
+ <para>The <literal>hajndi-jboss-beans.xml</literal> file in the
+ <literal>JBOSS_HOME/server/all/deploy/cluster</literal> directory
+ includes the following bean to enable HA-JNDI services.</para>
- <para>You can see that this MBean depends on the <literal>DefaultPartition</literal> MBean defined above it (discussed earlier in this chapter). In other configurations, you can put that
- element in the <literal>jboss-service.xml</literal> file or any other JBoss configuration files in
- the <literal>/deploy</literal> directory to enable HA-JNDI services. The available attributes for
- this MBean are listed below.</para>
+<programlisting><bean name="HAJNDI" class="org.jboss.ha.jndi.HANamingService">
+
+ <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss:service=HAJNDI",
+ exposedInterface=org.jboss.ha.jndi.HANamingServiceMBean.class)</annotation>
+
+ <!-- The partition used for group RPCs to find locally bound objects on other nodes -->
+ <property name="HAPartition"><inject bean="HAPartition"/></property>
+
+ <!-- Handler for the replicated tree -->
+ <property name="distributedTreeManager">
+ <bean class="org.jboss.ha.jndi.impl.jbc.JBossCacheDistributedTreeManager">
+ <property name="cacheHandler"><inject bean="HAPartitionCacheHandler"/></property>
+ </bean>
+ </property>
+
+ <property name="localNamingInstance">
+ <inject bean="jboss:service=NamingBeanImpl" property="namingInstance"/>
+ </property>
+
+ <!-- The thread pool used to control the bootstrap and auto discovery lookups -->
+ <property name="lookupPool"><inject bean="jboss.system:service=ThreadPool"/></property>
+
+ <!-- Bind address of bootstrap endpoint -->
+ <property name="bindAddress">${jboss.bind.address}</property>
+ <!-- Port on which the HA-JNDI stub is made available -->
+ <property name="port">
+ <!-- Get the port from the ServiceBindingManager -->
+ <value-factory bean="ServiceBindingManager" method="getIntBinding">
+ <parameter>jboss:service=HAJNDI</parameter>
+ <parameter>Port</parameter>
+ </value-factory>
+ </property>
+
+ <!-- Bind address of the HA-JNDI RMI endpoint -->
+ <property name="rmiBindAddress">${jboss.bind.address}</property>
+
+ <!-- RmiPort to be used by the HA-JNDI service once bound. 0 = ephemeral. -->
+ <property name="rmiPort">
+ <!-- Get the port from the ServiceBindingManager -->
+ <value-factory bean="ServiceBindingManager" method="getIntBinding">
+ <parameter>jboss:service=HAJNDI</parameter>
+ <parameter>RmiPort</parameter>
+ </value-factory>
+ </property>
+
+ <!-- Accept backlog of the bootstrap socket -->
+ <property name="backlog">50</property>
+
+ <!-- A flag to disable the auto discovery via multicast -->
+ <property name="discoveryDisabled">false</property>
+ <!-- Set the auto-discovery bootstrap multicast bind address. If not
+ specified and a BindAddress is specified, the BindAddress will be used. -->
+ <property name="autoDiscoveryBindAddress">${jboss.bind.address}</property>
+ <!-- Multicast Address and group port used for auto-discovery -->
+ <property name="autoDiscoveryAddress">${jboss.partition.udpGroup:230.0.0.4}</property>
+ <property name="autoDiscoveryGroup">1102</property>
+ <!-- The TTL (time-to-live) for autodiscovery IP multicast packets -->
+ <property name="autoDiscoveryTTL">16</property>
+
+ <!-- The load balancing policy for HA-JNDI -->
+ <property name="loadBalancePolicy">org.jboss.ha.framework.interfaces.RoundRobin</property>
+
+ <!-- Client socket factory to be used for client-server
+ RMI invocations during JNDI queries
+ <property name="clientSocketFactory">custom</property>
+ -->
+ <!-- Server socket factory to be used for client-server
+ RMI invocations during JNDI queries
+ <property name="serverSocketFactory">custom</property>
+ -->
+ </bean></programlisting>
+
+ <para>You can see that this bean has a number of other services injected
+ into different properties:
+
<itemizedlist>
+ <listitem><para><emphasis role="bold">HAPartition</emphasis> accepts the
+ core clustering service used manage HA-JNDI's clustered proxies and to
+ make the group RPCs that find locally bound objects on other nodes.
+ See <xref linkend="clustering-hapartition"/> for more.</para>
+ </listitem>
+
+ <listitem><para><emphasis role="bold">distributedTreeManager</emphasis>
+ accepts a handler for the replicated tree. The standard handler uses
+ JBoss Cache to manage the replicated tree. The JBoss Cache instance
+ is retrieved using the injected <literal>HAPartitionCacheHandler</literal>
+ bean. See <xref linkend="clustering-hapartition"/> for more details.</para></listitem>
+
+ <listitem><para><emphasis role="bold">localNamingInstance</emphasis> accepts
+ the reference to the local JNDI service.</para></listitem>
+
+ <listitem><para><emphasis role="bold">lookupPool</emphasis> accepts the
+ thread pool used to provide threads to handle the bootstrap and auto
+ discovery lookups.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Besides the above dependency injected services, the available configuration
+ attributes for the HAJNDI bean are as follows:</para>
+
+ <itemizedlist>
<listitem>
- <para><emphasis role="bold">Cluster Partition</emphasis> is a required attribute to inject the HAPartition service that HA-JNDI uses for intra-cluster communication.</para>
+ <para><emphasis role="bold">bindAddress</emphasis> specifies the address
+ to which the HA-JNDI server will bind to listen for naming proxy download
+ requests from JNP clients. The default value is the value of the
+ <literal>jboss.bind.address</literal> system property, or
+ <literal>localhost</literal> if that property is not set.
+ The <literal>jboss.bind.address</literal> system property is set if the
+ <literal>-b</literal> command line switch is used when JBoss is started.</para>
</listitem>
+
<listitem>
- <para><emphasis role="bold">BindAddress</emphasis> is an optional attribute to specify the address to which the HA-JNDI server will bind waiting for JNP clients. Only useful for multi-homed computers. The default value is the value of the jboss.bind.address system property, or the host's default addresss if that property is not set. The jboss.bind.address system property is set if the -b command line switch is used when JBoss is started.</para>
+ <para><emphasis role="bold">port</emphasis> specifies the port to
+ which the HA-JNDI server will bind to listen for naming proxy download
+ requests from JNP clients. The value is obtained from the
+ ServiceBindingManager bean configured in <literal>conf/bootstrap/bindings.xml</literal>.
+ The default value is <literal>1100</literal>.</para>
</listitem>
<listitem>
- <para><emphasis role="bold">Port</emphasis> is an optional attribute to specify the port to
- which the HA-JNDI server will bind waiting for JNP clients. The default value is
- <literal>1100</literal>.</para>
+ <para><emphasis role="bold">Backlog</emphasis> specifies the maximum
+ queue length for incoming connection indications for the TCP server
+ socket on which the service listens for naming proxy download
+ requests from JNP clients. The default value is <literal>50</literal>.</para>
</listitem>
<listitem>
- <para><emphasis role="bold">Backlog</emphasis> is an optional attribute to specify the backlog
- value used for the TCP server socket waiting for JNP clients. The default value is
- <literal>50</literal>.</para>
+ <para><emphasis role="bold">rmiBindAddress</emphasis> specifies the address
+ to which the HA-JNDI server will bind to listen for RMI requests (e.g.
+ for JNDI lookups) from naming proxies. The default value is the value of the
+ <literal>jboss.bind.address</literal> system property, or
+ <literal>localhost</literal> if that property is not set.
+ The <literal>jboss.bind.address</literal> system property is set if the
+ <literal>-b</literal> command line switch is used when JBoss is started.</para>
</listitem>
<listitem>
- <para><emphasis role="bold">RmiPort</emphasis> determines which port the server should use to communicate with the downloaded stub. This attribute is optional. The default value is 1101. If no value is set, the server automatically assigns a RMI port.</para>
+ <para><emphasis role="bold">rmiPort</emphasis> specifies the port to which
+ the server will bind to communicate with the downloaded stub. The value
+ is obtained from the ServiceBindingManager bean configured in
+ <literal>conf/bootstrap/bindings.xml</literal>. The default value is
+ <literal>1101</literal>. If no value is set, the operating system
+ automatically assigns a port.</para>
</listitem>
- <listitem>
- <para>
- <literal>DiscoveryDisabled</literal> is a boolean flag that disables configuration of the auto discovery multicast listener.
+ <listitem>
+ <para><emphasis role="bold">discoveryDisabled</emphasis> is a boolean flag
+ that disables configuration of the auto discovery multicast listener.
+ The default is <literal>false</literal>.
</para>
</listitem>
<listitem>
- <para><emphasis role="bold">AutoDiscoveryAddress</emphasis> is an optional attribute to specify the multicast address to listen to for JNDI automatic discovery. The default value is the value of the jboss.partition.udpGroup system property, or 230.0.0.4 if that is not set. The jboss.partition.udpGroup system property is set if the -u command line switch is used when JBoss is started.</para>
+ <para><emphasis role="bold">autoDiscoveryAddress</emphasis> specifies the
+ multicast address to listen to for JNDI automatic discovery. The default
+ value is the value of the <literal>jboss.partition.udpGroup</literal>
+ system property, or 230.0.0.4 if that is not set. The
+ <literal>jboss.partition.udpGroup</literal> system property is set if
+ the <literal>-u</literal> command line switch is used when JBoss is started.</para>
</listitem>
<listitem>
- <para><emphasis role="bold">AutoDiscoveryGroup</emphasis> is an optional attribute to specify
- the multicast group to listen to for JNDI automatic discovery.. The default value is
- <literal>1102</literal>.</para>
+ <para><emphasis role="bold">autoDiscoveryGroup</emphasis> specifies
+ the port to listen on for multicast JNDI automatic discovery packets.
+ The default value is <literal>1102</literal>.</para>
</listitem>
<listitem>
- <para><emphasis role="bold">AutoDiscoveryBindAddress</emphasis> sets the interface on which HA-JNDI should listen for auto-discovery request packets. If this attribute is not specified and a <literal>BindAddress</literal> is specified, the <literal>BindAddress</literal> will be used..</para>
+ <para><emphasis role="bold">autoDiscoveryBindAddress</emphasis> sets the
+ interface on which HA-JNDI should listen for auto-discovery request packets.
+ If this attribute is not specified and a <literal>bindAddress</literal> is
+ specified, the <literal>bindAddress</literal> will be used.</para>
</listitem>
<listitem>
- <para><emphasis role="bold">AutoDiscoveryTTL</emphasis> specifies the TTL (time-to-live) for autodiscovery IP multicast packets. This value represents the number of network hops a multicast packet can be allowed to propagate before networking equipment should drop the packet. Despite its name, it does not represent a unit of time.</para>
+ <para><emphasis role="bold">autoDiscoveryTTL</emphasis> specifies the
+ TTL (time-to-live) for autodiscovery IP multicast packets. This value
+ represents the number of network hops a multicast packet can be allowed
+ to propagate before networking equipment should drop the packet. Despite
+ its name, it does not represent a unit of time.</para>
</listitem>
- <listitem>
- <para><emphasis role="bold">LoadBalancePolicy</emphasis> specifies the class name of the LoadBalancePolicyimplementation that should be included in the client proxy. See the earlier section on “Load-Balancing Policies” for details.
- </para>
- </listitem>
- <listitem>
-
- <para><emphasis role="bold">LookupPool</emphasis> specifies the thread pool service used to control the bootstrap and auto discovery lookups.
- </para>
- </listitem>
+ <listitem>
+ <para><emphasis role="bold">loadBalancePolicy</emphasis> specifies the
+ class name of the LoadBalancePolicyimplementation that should be included
+ in the client proxy. See <xref linkend="clustering-intro-balancepolicy"/>
+ for details.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">clientSocketFactory</emphasis> is an optional
+ attribute that specifies the fully qualified classname of the
+ <literal>java.rmi.server.RMIClientSocketFactory</literal> that should be used
+ to create client sockets. The default is <literal>null</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">serverSocketFactory</emphasis> is an optional
+ attribute that specifies the fully qualified classname of the
+ <literal>java.rmi.server.RMIServerSocketFactory</literal> that should be used
+ to create server sockets. The default is <literal>null</literal>.</para>
+ </listitem>
</itemizedlist>
- <para>The full default configuration of the <literal>HANamingService</literal> MBean is as follows.</para>
-<programlisting><![CDATA[
- <mbean code="org.jboss.ha.jndi.HANamingService"
- name="jboss:service=HAJNDI">
- <!-- 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>
- <!-- Bind address of bootstrap and HA-JNDI RMI endpoints -->
- <attribute name="BindAddress">${jboss.bind.address}</attribute>
- <!-- Port on which the HA-JNDI stub is made available -->
- <attribute name="Port">1100</attribute>
- <!-- RmiPort to be used by the HA-JNDI service once bound. 0 => auto. -->
- <attribute name="RmiPort">1101</attribute>
- <!-- Accept backlog of the bootstrap socket -->
- <attribute name="Backlog">50</attribute>
- <!-- The thread pool service used to control the bootstrap and auto discovery lookups -->
- <depends optional-attribute-name="LookupPool"
- proxy-type="attribute">jboss.system:service=ThreadPool</depends>
- <!-- A flag to disable the auto discovery via multicast -->
- <attribute name="DiscoveryDisabled">false</attribute>
- <!-- Set the auto-discovery bootstrap multicast bind address. If not
- specified and a BindAddress is specified, the BindAddress will be used. -->
- <attribute name="AutoDiscoveryBindAddress">${jboss.bind.address}</attribute>
- <!-- Multicast Address and group port used for auto-discovery -->
- <attribute name="AutoDiscoveryAddress">${jboss.partition.udpGroup:230.0.0.4}</attribute>
- <attribute name="AutoDiscoveryGroup">1102</attribute>
- <!-- The TTL (time-to-live) for autodiscovery IP multicast packets -->
- <attribute name="AutoDiscoveryTTL">16</attribute>
- <!-- The load balancing policy for HA-JNDI -->
- <attribute name="LoadBalancePolicy">org.jboss.ha.framework.interfaces.RoundRobin</attribute>
-
- <!-- Client socket factory to be used for client-server
- RMI invocations during JNDI queries
- <attribute name="ClientSocketFactory">custom</attribute>
- -->
- <!-- Server socket factory to be used for client-server
- RMI invocations during JNDI queries
- <attribute name="ServerSocketFactory">custom</attribute>
- -->
- </mbean>]]>
-</programlisting>
+
+ <section><title>Adding a Second HA-JNDI Service</title>
<para>
- It is possible to start several HA-JNDI services that use different clusters. This can be used, for example, if a node is part of many clusters. In this case, make sure that you set a different port or IP address for eachservices. For instance, if you wanted to hook up HA-JNDI to the example cluster you set up and change the binding port, the Mbean descriptor would look as follows.
+ It is possible to start several HA-JNDI services that use different HAPartitions.
+ This can be used, for example, if a node is part of many logical clusters. In this case,
+ make sure that you set a different port or IP address for each service. For
+ instance, if you wanted to hook up HA-JNDI to the example cluster you set up
+ and change the binding port, the bean descriptor would look as follows (properties
+ that do not vary from the standard deployments are omitted):
</para>
-<programlisting><![CDATA[
-<mbean code="org.jboss.ha.jndi.HANamingService"
- name="jboss:service=HAJNDI">
- <depends optional-attribute-name="ClusterPartition"
- proxy-type="attribute">jboss:service=MySpecialPartition</depends>
- <attribute name="Port">56789</attribute>
-</mbean> ]]>
-</programlisting>
+<programlisting>
+ <-- Cache Handler for secondary HAPartition -->
+ <bean name="SecondaryHAPartitionCacheHandler"
+ class="org.jboss.ha.framework.server.HAPartitionCacheHandlerImpl">
+ <property name="cacheManager"><inject bean="CacheManager"/></property>
+ <property name="cacheConfigName">secondary-ha-partition</property>
+ </bean>
+
+ <-- The secondary HAPartition -->
+ <bean name="SecondaryHAPartition" class="org.jboss.ha.framework.server.ClusterPartition">
+
+ <depends>jboss:service=Naming</depends>
+
+ <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss:service=HAPartition,partition=SecondaryPartition",
+ exposedInterface=org.jboss.ha.framework.server.ClusterPartitionMBean.class, registerDirectly=true)</annotation>
+
+ <property name="cacheHandler"><inject bean="SecondaryHAPartitionCacheHandler"/></property>
+
+ <property name="partitionName">SecondaryPartition</property>
+
+ ....
+ </bean>
+
+ <bean name="MySpecialPartitionHAJNDI" class="org.jboss.ha.jndi.HANamingService">
+
+ <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss:service=HAJNDI,partitionName=SecondaryPartition",
+ exposedInterface=org.jboss.ha.jndi.HANamingServiceMBean.class)</annotation>
+
+ <property name="HAPartition"><inject bean="SecondaryHAPartition"/></property>
+
+ <property name="distributedTreeManager">
+ <bean class="org.jboss.ha.jndi.impl.jbc.JBossCacheDistributedTreeManager">
+ <property name="cacheHandler"><inject bean="SecondaryHAPartitionPartitionCacheHandler"/></property>
+ </bean>
+ </property>
+
+ <property name="port">56789</property>
+
+ <property name="rmiPort">56790</property>
+
+ <property name="autoDiscoveryGroup">56791</property>
+
+ .....
+ </bean></programlisting>
</section>
-</section>
+
+ </section>
</chapter>
More information about the jboss-cvs-commits
mailing list