[jboss-cvs] JBossAS SVN: r99877 - 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
Mon Jan 25 02:29:32 EST 2010
Author: laubai
Date: 2010-01-25 02:29:32 -0500 (Mon, 25 Jan 2010)
New Revision: 99877
Modified:
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JNDI.xml
Log:
Corrected Clustering_Guide_JNDI.xml.
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JNDI.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JNDI.xml 2010-01-25 07:18:25 UTC (rev 99876)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JNDI.xml 2010-01-25 07:29:32 UTC (rev 99877)
@@ -4,13 +4,14 @@
<chapter id="clustering-jndi">
<title>Clustered JNDI Services</title>
<para>
- JNDI is one of the most important services provided by the application
+ The Java Naming and Directory Interface (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
+ Transparent failover of naming operations. If a HA-JNDI naming
Context is connected to the HA-JNDI service on a particular JBoss Enterprise Web Platform
instance, and that service fails or is shut down, the HA-JNDI client
can transparently fail over to another Enterprise Web Platform instance.
@@ -32,7 +33,7 @@
<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:
+ in JNDI on any other node. This is accomplished via two mechanisms:</para>
<itemizedlist>
<listitem>
<para>Cross-cluster lookups. A client can perform a lookup and the
@@ -47,9 +48,7 @@
</para>
</listitem>
</itemizedlist>
- </para>
- </listitem>
-
+ </listitem>
</itemizedlist>
@@ -60,9 +59,9 @@
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:
+ looked up. <!--To illustrate:-->
</para>
- <itemizedlist>
+<!-- <itemizedlist>
<listitem>
<para>
If an EJB is not configured as clustered, looking up the EJB
@@ -78,16 +77,14 @@
removal of the bean proxy's clustering capabilities.
</para>
</listitem>
- </itemizedlist>
-
-
+ </itemizedlist>-->
<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 (see <xref linkend="clustering-intro.chapt"/> the Introduction and Quick Start chapter).
+ interceptor architecture (see <xref linkend="clustering-intro.chapt"/>).
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
@@ -134,8 +131,8 @@
<para>
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 <methodname>new InitialContext()</methodname> will be bound to the local-only,
+ non-cluster-wide JNDI Context. So, homes will not be bound
to the cluster-wide JNDI Context, but rather, each home will be bound into
the local JNDI.
</para>
@@ -159,16 +156,17 @@
</listitem>
<listitem>
<para>If no local JNDI service owns such a binding, a
- <literal>NameNotFoundException</literal> is finally raised.</para>
+ <exceptionname>NameNotFoundException</exceptionname> 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
+ In practice, objects are rarely bound in the cluster-wide JNDI tree. A lookup performed
+ through HA-JNDI will always be delegated to the local JNDI instance.
+<!-- 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.
+ the local JNDI instance.-->
</para>
<note><title>Note</title>
@@ -218,7 +216,7 @@
<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
+ <classname>InitialContext</classname> is created. How this is done varies
depending on whether the client is running inside JBoss Enterprise Web Platform itself or
is in another VM.</para>
@@ -226,7 +224,7 @@
<section><title>For clients running inside the Enterprise Web Platform</title>
<para>
If you want to access HA-JNDI from inside the Enterprise Web Platform, you
- must explicitly configure your <literal>InitialContext</literal> by
+ must explicitly configure your <classname>InitialContext</classname> by
passing in JNDI properties to the constructor. The following code shows
how to create a naming Context bound to HA-JNDI:
</para>
@@ -239,10 +237,10 @@
return new InitialContext(p);</programlisting>
<para>
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"/>).
+<filename>deploy/cluster/hajndi-jboss-beans.xml</filename> 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
+<varname>jboss.bind.address</varname> system property, which itself is set to
+whatever value you assign to the <code>-b</code> command line option when
you start JBoss Enterprise Web Platform (or <literal>localhost</literal> if not specified). The above
code shows an example of accessing this property.
</para>
@@ -251,8 +249,8 @@
However, this does not work in all cases, especially when running several
JBoss Enterprise Web Platform 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>
+ Context.PROVIDER_URL but instead allow the <classname>InitialContext</classname>
+ to statically find the in-VM HA-JNDI by specifying the <varname>jnp.partitionName</varname>
property:
</para>
<programlisting role="JAVA">Properties p = new Properties();
@@ -263,33 +261,34 @@
p.put("jnp.partitionName", partitionName);
return new InitialContext(p);</programlisting>
-<para>This example uses the <literal>jboss.partition.name</literal> system
+<para>This example uses the <varname>jboss.partition.name</varname> 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>
+system property is set to whatever value you assign to the <code>-g</code>
command line option when you start JBoss Enterprise Web Platform (or <literal>DefaultPartition</literal>
if not specified).
</para>
<para>
- Do not attempt to simplify things by placing a <literal>jndi.properties</literal>
- file in your deployment or by editing the Enterprise Web Platform's <literal>conf/jndi.properties</literal>
+ Do not attempt to simplify things by placing a <filename>jndi.properties</filename>
+ file in your deployment or by editing the Enterprise Web Platform's <filename>conf/jndi.properties</filename>
file. Doing either will almost certainly break things for your application
and quite possibly across the 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
+ named <varname>jndi.properties</varname>, and then programatically create a
<literal>Properties</literal> object that loads that file's contents.
</para>
-<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
+<section><title>Accessing HA-JNDI Resources from <!--EJBs and--> WARs -- Environment Naming Context</title>
+ <para>If your HA-JNDI client is <!--an EJB or--> a 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
+ <para>Within the bean definition in the <!--<filename>ejb-jar.xml</filename> or in the-->
+ WAR's <filename>web.xml</filename>,
+ you will need to define two <literal>resource-ref</literal> 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>
@@ -305,12 +304,13 @@
<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'.
+ factory by looking up <literal>java:comp/env/jms/ConnectionFactory</literal> and can obtain the
+ queue by looking up <literal>java:comp/env/jms/Queue</literal>.
</para>
<para>
-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.
+Within the JBoss-specific deployment descriptor (<!--jboss.xml for EJBs, -->
+<filename>jboss-web.xml</filename>) 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>
@@ -327,26 +327,37 @@
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
+ to use the value of the <varname>jboss.bind.address</varname> 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 Enterprise Web Platform.
+ you assign to the <code>-b</code> command line option when you start JBoss Enterprise Web Platform.
</para>
-</section>
-<section><title>Why do this programmatically and not just put this in a jndi.properties file?</title>
+<important><title>Why do this programmatically and not just put this in a jndi.properties file?</title>
<para>
- The JBoss Enterprise Web Platform's internal naming environment is controlled by the <filename>conf/jndi.properties</filename> file, which should not be edited.
+ The JBoss Enterprise Web Platform's internal naming environment is controlled by the
+ <filename>conf/jndi.properties</filename> file, which should not be edited.
</para>
<para>
- No other jndi.properties file should be deployed inside the Enterprise Web Platform because of the possibility of its being found on the classpath when it shouldn't and thus disrupting the internal operation of the server. For example, if an EJB deployment included a jndi.properties configured for HA-JNDI, when the server binds the EJB proxies into JNDI it will likely bind them into the replicated HA-JNDI tree and not into the local JNDI tree where they belong.
+ No other <filename>jndi.properties</filename> file should be deployed inside the
+ Enterprise Web Platform. If another <filename>jndi.properties</filename> file is
+ deployed, it may be found on the classpath when it is not intended for use and
+ disrupt the internal operation of the server.
+ <!--For example, if an EJB deployment included a jndi.properties configured for HA-JNDI,
+ when the server binds the EJB proxies into JNDI it will likely bind them into the
+ replicated HA-JNDI tree and not into the local JNDI tree where they belong.-->
</para>
+</important>
+
</section>
+
<section><title>How can I tell if things are being bound into HA-JNDI that shouldn't be?</title>
- <para>Go into the the jmx-console and execute the <literal>list</literal> operation on the <literal>jboss:service=JNDIView</literal> mbean. Towards the bottom of the results, the contents of the "HA-JNDI Namespace" are listed. Typically this will be empty; if any of your own deployments are shown there and you didn't explicitly bind them there, there's probably an improper jndi.properties file on the classpath. Please visit the following link for an example: <ulink url="http://www.jboss.com/index.html?module=bb&op=viewtopic&t=104715">Problem with removing a Node from Cluster</ulink>.</para>
+ <para>
+ Go into the the jmx-console and execute the <literal>list</literal> operation on the <literal>jboss:service=JNDIView</literal> mbean. Towards the bottom of the results, the contents of the "HA-JNDI Namespace" are listed. Typically this will be empty; if any of your own deployments are shown there and you didn't explicitly bind them there, there's probably an improper <filename>jndi.properties</filename> file on the classpath. <!--Please visit the following link for an example: <ulink url="http://www.jboss.com/index.html?module=bb&op=viewtopic&t=104715">Problem with removing a Node from Cluster</ulink>.-->
+ </para>
</section>
@@ -356,9 +367,9 @@
<section><title>For clients running outside the Enterprise Web Platform</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
+ pass a list of JNDI servers (that is, the nodes in the HA-JNDI cluster) to the
+ <varname>java.naming.provider.url</varname> JNDI setting in the
+ <filename>jndi.properties</filename> 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>
@@ -388,7 +399,7 @@
</para>
<para>
- If the property string <literal>java.naming.provider.url</literal> is empty
+ If the property string <varname>java.naming.provider.url</varname> 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
@@ -398,63 +409,90 @@
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 port 1102.</para>
+ <para>By default the auto-discovery feature uses multicast group address
+ <literal>230.0.0.4</literal> and port <literal>1102</literal>.</para>
</note>
- <para>In addition to the <literal>java.naming.provider.url</literal> property,
+ <para>In addition to the <varname>java.naming.provider.url</varname> 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
+ new <classname>InitialContext</classname>. (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>
- </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>
- </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 selects the first HA-JNDI server that responds,
- regardless of the cluster partition name.</para>
- </listitem>
- <listitem>
- <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. 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
- 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>
- </listitem>
-
- </itemizedlist>
+ <variablelist>
+ <varlistentry>
+ <term><varname>java.naming.provider.url</varname></term>
+ <listitem>
+ <para>
+ A list of IP addresses and port numbers for HA-JNDI provider nodes in the cluster.
+ The client tries each provider and uses the first one that responds.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>jnp.disableDiscovery</varname></term>
+ <listitem>
+ <para>
+ When <literal>true</literal>, disables the automatic discovery feature. The
+ default value is <literal>false</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>jnp.partitionName</varname></term>
+ <listitem>
+ <para>
+ In an environment running multiple HA-JNDI services bound to distinct clusters
+ or partitions, this property ensures that your client only accepts automatic
+ discovery responses from servers in the desired partition. If
+ <varname>jnp.disableDiscovery</varname> is set to <literal>true</literal>, this
+ property is not used. By default, this property is not set, and automatic
+ discovery selects the first HA-JNDI server that responds, regardless of the
+ cluster partition name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>jnp.discoveryTimeout</varname></term>
+ <listitem>
+ <para>
+ The time in milliseconds that the context will wait for a response to its automatic
+ discovery packet. The default value is <literal>5000</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>jnp.discoveryGroup</varname></term>
+ <listitem>
+ <para>
+ Determines which multicast group address is used for automatic discovery. The default
+ value is <literal>230.0.0.4</literal>. This value must match the value of
+ <varname>AutoDiscoveryAddress</varname> configured on the server-side HA-JNDI service.
+ By default this service listens on the address specified with the <code>-u</code>
+ startup switch, so if <code>-u</code> is used on the server side, as recommended,
+ <varname>jnp.discoveryGroup</varname> must be configured on the client side.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>jnp.discoveryPort</varname></term>
+ <listitem>
+ <para>
+ Determines the multicast port used for automatic discovery. The default value is
+ <literal>1102</literal>. This value must match the value of
+ <varname>AutoDiscoveryPort</varname> on the server-side HA-JNDI service.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>jnp.discoveryTTL</varname></term>
+ <listitem>
+ <para>
+ Specifies the TTL (time to live) for automatic discovery IP multicast packets.
+ This value represents the number of network hops a multicast packet can make
+ before networking equipment should drop the packet.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
@@ -462,212 +500,206 @@
<section id="clustering-jndi-jboss">
<title>JBoss configuration</title>
- <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>The <filename>hajndi-jboss-beans.xml</filename> file in the
+ <literal>JBOSS_HOME/server/production/deploy/cluster</literal> directory
+ includes the following bean to enable HA-JNDI services:</para>
-<programlisting><bean name="HAJNDI" class="org.jboss.ha.jndi.HANamingService">
+<programlisting><![CDATA[<bean name="HAJNDI" class="org.jboss.ha.jndi.HANamingService">
- <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX
+ <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX
(name="jboss:service=HAJNDI",
- exposedInterface=org.jboss.ha.jndi.HANamingServiceMBean.class)</annotation>
+ 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>
+ <!-- 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>
+ <!-- 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>
+ <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>
+ <!-- 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 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>
+ <!-- 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>
+ <!-- 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>
+ <!-- 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>
+ <!-- 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>
+ <!-- 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
+ <!-- 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
+ <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>
+ <property name="serverSocketFactory">custom</property>
+ -->
+ </bean>]]></programlisting>
<para>You can see that this bean has a number of other services injected
- into different properties:
+ into different properties:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>HAPartition</varname></term>
+ <listitem><para>The core clustering service used to 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 details.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>distributedTreeManager</varname></term>
+ <listitem><para>A handler for the replicated tree. The standard handler uses
+ JBoss Cache to manage the replicated tree. The cache instance is retrieved by
+ the injected <classname>HAPartitionCacheHandler</classname> bean. See
+ <xref linkend="clustering-hapartition"/> for more details.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>localNamingInstance</varname></term>
+ <listitem><para>A reference to the local JNDI service.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>lookupPool</varname></term>
+ <listitem><para>The thread pool used to provide threads to handle the bootstrap
+ and automatic discoveery lookups.</para></listitem>
+ </varlistentry>
+ </variablelist>
- <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 HA-JNDI bean are as follows:</para>
- <itemizedlist>
- <listitem>
- <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">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">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">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> 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><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> 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> 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>
- </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>
- </listitem>
- <listitem>
- <para><emphasis role="bold">loadBalancePolicy</emphasis> specifies the
- class name of the LoadBalancePolicy implementation that should be included
- in the client proxy. See <!--<xref linkend="clustering-intro-balancepolicy"/>-->
- the Introduction and Quick Start chapter 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>
+ <variablelist>
+ <varlistentry>
+ <term><varname>bindAddress</varname></term>
+ <listitem><para>The address to which the HA-JNDI server binds to listen for
+ naming proxy requests from JNP clients. The default value is the value of the
+ <varname>jboss.bind.address</varname> system property, if set with the
+ <code>-b</code> switch at server startup.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>port</varname></term>
+ <listitem><para>Specifies the port to which HA-JNDI binds to listen for naming
+ proxy download requests from JNP clients. The default value is obtained from the
+ <classname>ServiceBindingManager</classname> bean configured in
+ <filename>conf/bootstrap/bindings.xml</filename>. The default value is
+ <literal>100</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>backlog</varname></term>
+ <listitem><para>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>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>rmiBindAddress</varname></term>
+ <listitem><para>Specifies the address to which the HA-JNDI server binds to listen
+ for RMI requests from naming proxies. The default value is the value of the
+ <varname>jboss.bind.address</varname> system property, if set with the
+ <code>-b</code> switch on server startup. If the property is not set, the default
+ value is <literal>localhost</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>rmiPort</varname></term>
+ <listitem><para>Specifies the port to which the server binds to communicate
+ with the downloaded stub. The value is obtained from the
+ <classname>ServiceBindingManager</classname> bean configured in
+ <filename>conf/bootstrap/bindings.xml</filename>. The default value is
+ <literal>1101</literal>. If no value is set, the operating system
+ automatically assigns a port.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>discoveryDisabled</varname></term>
+ <listitem><para>A Boolean flaga that disables configuration of the automatic
+ discovery multicast listener. The default value is <literal>false</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>autoDiscoveryAddress</varname></term>
+ <listitem><para>Specifies the multicast address on which to listen for JNDI
+ automatic discovery. The default value is the value of the
+ <varname>jboss.partition.udpGroup</varname> system property, if set with the
+ <code>-u</code> switch on server startup; otherwise, the default is
+ <literal>230.0.0.4</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>autoDiscoveryGroup</varname></term>
+ <listitem><para>Specifies the port to listen on for multicast JNDI
+ automatic discovery packets. The default value is <literal>1102</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>autoDiscoveryBindAddress</varname></term>
+ <listitem><para>Sets the interface on which HA-JNDI listens for auto-discovery
+ request packets. If this attribute is not specified and a <varname>bindAddress</varname>
+ is specified, the <varname>bindAddress</varname> will be used.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>autoDiscoveryTTL</varname></term>
+ <listitem><para>Specifies the time-to-live (TTL) for automatic discovery IP
+ multicast packets. This value represents the number of network hops that a multicast
+ packet is allowed to make before networking equipment drops the packet.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>loadBalancePolicy</varname></term>
+ <listitem><para>Specifies the class name of the <classname>LoadBalancePolicy</classname>
+ implementation to be included in the client proxy.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>clientSocketFactory</varname></term>
+ <listitem><para>An optional attribute that specifies the fully-qualified class name
+ of the <classname>java.rmi.server.RMIServerSocketFactory</classname> used to create
+ client sockets. The default value is <literal>null</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>serverSocketFactory</varname></term>
+ <listitem><para>An optional attribute that specifies the fully qualified class name
+ of the <classname>java.rmi.server.RMIServerSocketFactory</classname> used to
+ create server sockets. The default value is <literal>null</literal>.</para></listitem>
+ </varlistentry>
+ </variablelist>
<section><title>Adding a Second HA-JNDI Service</title>
<para>
- It is possible to start several HA-JNDI services that use different HAPartitions.
+ It is possible to start several HA-JNDI services that use different <classname>HAPartition</classname>s.
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
@@ -675,54 +707,51 @@
that do not vary from the standard deployments are omitted):
</para>
-<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>
+<programlisting><![CDATA[<-- 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">
+ <-- The secondary HAPartition -->
+ <bean name="SecondaryHAPartition" class="org.jboss.ha.framework.server.ClusterPartition">
- <depends>jboss:service=Naming</depends>
+ <depends>jboss:service=Naming</depends>
- <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX
+ <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>
+ exposedInterface=org.jboss.ha.framework.server.ClusterPartitionMBean.class, registerDirectly=true)</annotation>
- <property name="cacheHandler"><inject bean="SecondaryHAPartitionCacheHandler"/></property>
+ <property name="cacheHandler"><inject bean="SecondaryHAPartitionCacheHandler"/></property>
- <property name="partitionName">SecondaryPartition</property>
+ <property name="partitionName">SecondaryPartition</property>
....
- </bean>
+ </bean>
- <bean name="MySpecialPartitionHAJNDI" class="org.jboss.ha.jndi.HANamingService">
+ <bean name="MySpecialPartitionHAJNDI" class="org.jboss.ha.jndi.HANamingService">
- <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX
+ <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX
(name="jboss:service=HAJNDI,partitionName=SecondaryPartition",
- exposedInterface=org.jboss.ha.jndi.HANamingServiceMBean.class)</annotation>
+ exposedInterface=org.jboss.ha.jndi.HANamingServiceMBean.class)</annotation>
- <property name="HAPartition"><inject bean="SecondaryHAPartition"/></property>
+ <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="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="port">56789</property>
- <property name="rmiPort">56790</property>
+ <property name="rmiPort">56790</property>
- <property name="autoDiscoveryGroup">56791</property>
+ <property name="autoDiscoveryGroup">56791</property>
.....
- </bean></programlisting>
+ </bean>]]></programlisting>
</section>
-
- </section>
-
+ </section>
</chapter>
More information about the jboss-cvs-commits
mailing list