[jboss-cvs] JBossAS SVN: r103883 - projects/docs/enterprise/4.3.8/Server_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Apr 13 02:03:09 EDT 2010
Author: laubai
Date: 2010-04-13 02:03:09 -0400 (Tue, 13 Apr 2010)
New Revision: 103883
Modified:
projects/docs/enterprise/4.3.8/Server_Configuration_Guide/en-US/Clustering_Guide_JMS.xml
projects/docs/enterprise/4.3.8/Server_Configuration_Guide/en-US/Server_Configuration_Guide_CP08.xml
Log:
JBPAPP-4069 Removed Clustered JMS chapter to remove info about JBossMQ.
Modified: projects/docs/enterprise/4.3.8/Server_Configuration_Guide/en-US/Clustering_Guide_JMS.xml
===================================================================
--- projects/docs/enterprise/4.3.8/Server_Configuration_Guide/en-US/Clustering_Guide_JMS.xml 2010-04-13 05:31:25 UTC (rev 103882)
+++ projects/docs/enterprise/4.3.8/Server_Configuration_Guide/en-US/Clustering_Guide_JMS.xml 2010-04-13 06:03:09 UTC (rev 103883)
@@ -4,352 +4,8 @@
<chapter id="clustering-jms">
<title>Clustered JMS Services</title>
- <para>JBoss AS 3.2.4 and above support high availability JMS (HA-JMS) services in the <literal>all</literal>
- server configuration. In the current production release of JBoss AS, the HA-JMS service is implemented
- as a clustered singleton fail-over service.
- </para>
-<note>
- <para>If you are willing to configure HA-JMS yourself, you can get it to work with earlier versions of JBoss AS. We have a customer who uses HA-JMS successfully in JBoss AS 3.0.7. Please contact JBoss support for more questions.
- </para>
-</note>
- <note>
- <para>
- The HA-JMS in JBoss AS 4.2.2 and earlier is based on the JBoss MQ messaging product. In later releases of the AS, JBoss MQ will be replaced by the newer JBoss Messaging project. JBoss Messaging's clustering implementation is considerably different from HA-JMS based on JBoss MQ; most notably it is not based on a singleton service only running on one node in the cluster.
- </para>
- </note>
-
-
-
-
-<section id="clustering-jms-singleton">
- <title>High Availability Singleton Fail-over</title>
- <para>The JBoss HA-JMS service (i.e., message queues topics and supporting services) only runs on a single node (i.e., the master node) in the cluster at any given time. If that node fails, the cluster simply elects another node to run the JMS service, and the queues, topics and supporting services are deployed on that server (fail-over). This setup provides redundancy against server failures but does not reduce the work load on the JMS server node.</para>
- <note>
- <para>While you cannot load balance HA-JMS queues (there is only one master node that runs the
- queues), you can load balance the MDBs that process messages from those queues (see <xref linkend="clustering-jms-loadbalanced"/>).</para>
- </note>
-
-<section id="clustering-jms-singleton-server">
- <title>Server Side Configuration</title>
-
<para>
- The biggest configuration difference between HA-JMS in the all configuration and the non-HA version found in the default configuration is the location of most configuration files. For HA-JMS, most configuration files are found in the deploy-hasingleton/jms directory, not in deploy/jms. Your queues and topics must be deployed in deploy-hasingleton (or a subdirectory of it like deploy-hasingleton/jms.) Application components that act as clients to HA-JMS (e.g., MDBs and other JMS clients) do not need to be deployed in deploy-hasingleton. They should only be deployed there if you only want them running on one node in the cluster at a time.
- </para>
- <para>
- To use the singleton fail-over HA-JMS service, you must configure JMS services identically on all nodes in the cluster. That includes all JMS related service MBeans and all deployed queues and topics. However, applications that use JMS (e.g., MDBs and other JMS clients) do not need to be deployed identically across the cluster.
- </para>
-
-
-
- <para>
- The JMS server is configured to persist its data in the <literal>DefaultDS</literal>. By default, that is the embedded HSQLDB. However, for the HA-JMS service fail-over to work, the newly started HA-JMS server needs to be able to find the data persisted by the old server. That's not likely to happen if the data is persisted in files written by the old servers' HSQLDB. In almost any cluster environments, all nodes need to persist data against a shared database. So, the first thing to do before you start clustered JMS is to setup a shared database for JMS. You need to do the following:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>Configure <literal>DefaultDS</literal> to point to the database server of your choice.
- That is to replace the <literal>deploy/hsqlsb-ds.xml</literal> file with the
- <literal>xxx-ds.xml</literal> file in the <literal>docs/examples/jca</literal>
- directory, where <literal>xxx</literal> is the name of the target shared database (e.g.,
- <literal>mysql-ds.xml</literal>).</para>
- </listitem>
- <listitem>
- <para>Replace the <literal>hsqldb-jdbc2-service.xml</literal> file under the
- <literal>server/all/deploy-hasingleton/jms</literal> directory with one tuned to the
- specific database. For example if you use MySQL the file is
- <literal>mysql-jdbc2-service.xml</literal>. Configuration files for a number of
- RDBMS are bundled with the JBoss AS distribution. They can be found under
- <literal>docs/examples/jms</literal>.</para>
- </listitem>
- </itemizedlist>
- <note>
- <para>There is no need to replace the <literal>hsqldb-jdbc-state-service.xml</literal> file
- under the <literal>server/all/deploy-hasingleton/jms</literal> directory. Despite the
- <literal>hsql</literal> in its name, it works with all SQL92 compliant databases,
- including HSQL, MySQL, SQL Server, and more. It automatically uses the
- <literal>DefaultDS</literal> for storage, which we configured above.</para>
- </note>
- </section>
-
-
-
- <section id="clustering-jms-singleton-client">
- <title>Non-MDB HA-JMS Clients </title>
-
- <para>The HA-JMS client is different from regular JMS clients in two important aspects.</para>
-
- <itemizedlist>
- <listitem>
- <para>
- The HA-JMS client must look up JMS connection factories as well as queues and topicsusing HA-JNDI (the default port is 1100). This ensures the factory/queue/topic can be found no matter which cluster node is running the HA-JMS server.
- </para>
- </listitem>
- </itemizedlist>
-
- <itemizedlist>
- <listitem>
- <para>
- If the client is a J2EE component (session bean or web application) running inside the AS, the lookup via HA-JNDI can be configured using the component's deployment descriptors: In the standard deployment descriptor (ejb-jar.xml or web.xml):
- </para>
- </listitem>
-
- </itemizedlist>
-
-
-<programlisting><![CDATA[
-<resource-ref>
- <res-ref-name>jms/ConnectionFactory</res-ref-name>
- <res-type>javax.jms.QueueConnectionFactory</res-type>
- <res-auth>Container</res-auth>
-</resource-ref>
-
-<resource-ref>
- <res-ref-name>jms/Queue</res-ref-name>
- <res-type>javax.jms.Queue</res-type>
- <res-auth>Container</res-auth>
-</resource-ref>
-]]></programlisting>
+ The most current information about using JBoss Messaging in a clustered environment is always available from the relevant <citetitle>JBoss Messaging User Guide</citetitle> at <ulink url="http://www.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/">http://www.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/</ulink>.
+ </para>
-<para>
-And in the JBoss-specific descriptor (jboss.xml or jboss-web.xml):
-</para>
-
-<programlisting><![CDATA[
-<resource-ref>
- <res-ref-name>jms/ConnectionFactory</res-ref-name>
- <!-- Use the JMS Resource Adapter, let it deal
- with knowing where the JMS server is -->
- <jndi-name>java:/JmsXA</jndi-name>
- </resource-ref>
-
-<resource-ref>
- <res-ref-name>jms/Queue</res-ref-name>
- <!-- Use HA-JNDI so we can find the queue on any node -->
- <jndi-name>jnp://localhost:1100/queue/A</jndi-name>
-</resource-ref>]]>
-</programlisting>
-
-
- <itemizedlist>
- <listitem>
- <para>
- The HA-JMS client must deal with exceptions that will occur on the JMS connection if server failover occurs. Unlike, for example, clustered EJB proxies, the JMS connection object does not include automatic failover logic. If the HA-JMS service fails over to a different master node, all client operations on the current connection will fail with a JMSException. To deal with this:
- </para>
- </listitem>
- </itemizedlist>
-
- <itemizedlist>
- <listitem>
- <para>If the client is running inside the application server, the client should obtain the ConnectionFactory by looking up java:/JmsXAin JNDI. This will find the JBoss JMS Resource Adapter; the resource adapter will handle the task of detecting server failover and reconnecting to the new server when it starts.
- </para>
- </listitem>
- <listitem>
- <para>For clients outside the application server, the best approach is to register an ExceptionListener with the connection; the listener will get a callback if there is an exception on the connection. The callback should then handle the task of closing the old connection and reconnecting. Following is a example application that continuously sends messages to a queue, handling any exceptions that occur:
- </para>
- </listitem>
- </itemizedlist>
-
-
-<programlisting><![CDATA[
-package com.test.hajms.client;
-
-import javax.naming.InitialContext;
-import javax.jms.ConnectionFactory;
-import javax.jms.Destination;
-import javax.jms.Connection;
-import javax.jms.Session;
-import javax.jms.MessageProducer;
-import javax.jms.Message;
-import javax.jms.ExceptionListener;
-import javax.jms.JMSException;
-import javax.jms.DeliveryMode;
-
-import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
-
-public class FailoverJMSClient
-{
-private static final Log log = LogFactory.getLog(FailoverJMSClient.class);
-
-public static final int NUM_RETRIES = 3;
-
-volatile boolean doSend = true;
-ConnectionFactory connectionFactory;
-Destination queue;
-Connection connection;
-Session session;
-MessageProducer producer;
-
-
-public static void main(String[] args) throws Exception
-{
-FailoverJMSClient jmsClient = new FailoverJMSClient();
-jmsClient.setUpJMS();
-jmsClient.sendMessages();
-}
-
-
-public boolean setUpJMS()
-{
-InitialContext ic;
-try
-{
-// assume jndi.properties is configured for HA-JNDI
-ic = new InitialContext();
-connectionFactory = (ConnectionFactory)ic.lookup("ConnectionFactory");
-queue = (Destination)ic.lookup("queue/FailoverTestQueue");
-connection = connectionFactory.createConnection();
-try
-{
-log.debug("Connection created ...");
-
-// KEY - register for exception callbacks
-connection.setExceptionListener(new ExceptionListenerImpl());
-
-session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-log.debug("Session created ...");
-producer = session.createProducer(queue);
-
-producer.setDeliveryMode(DeliveryMode.NON_PERSISTENT);
-log.debug("Producer created ...");
-
-return true;
-}
-catch (Exception e)
-{
-// We failed so close the connection
-try
-{
-connection.close();
-}
-catch (JMSException ignored)
-{
-// Pointless
-}
-// Rethrow the initial problem to where we will log it
-throw e;
-}
-finally
-{
-// And close the initial context
-// We don't want to wait for the garbage collector to close it
-// otherwise we'll have useless hanging network connections
-ic.close();
-}
-}
-catch (Exception e)
-{
-log.error("Error setting up JMS", e);
-return false;
-}
-}
-
-public void sendMessages()
-{
-int cnt = 0;
-while(doSend)
-{
-try
-{
-Thread.sleep(100);
-
-Message m = session.createObjectMessage(new Integer(cnt++));
-producer.send(m);
-
-log.trace("message " + cnt + " sent");
-
-}
-catch(Exception e)
-{
-cnt--;
-log.error(e.getMessage());
-}
-}
-}
-
-
-
-private class ExceptionListenerImpl implements ExceptionListener
-{
-public void onException(JMSException e)
-{
-
-for(int i = 0; i < NUM_RETRIES; i++)
- {
- log.warn("Connection has problems, trying to re-create it, attempt " +
- (i + 1) + " ...");
-
- try
- {
- connection.close(); // unregisters the ExceptionListener
- }
- catch(Exception e2) {
- // I will get an Exception anyway, since the connection to the
- //server is broken, but close() frees up resources associated
- // with the connection
- }
-
- boolean setupOK = setUpJMS();
-
- if (setupOK)
- {
- log.info("Connection re-established");
- return;
- }
- else
- {
- log.warn("Re-creating connection failed, retrying ...");
- }
- }
-
- log.error("Cannot re-establish connection, giving up ...");
- doSend = false;
- }
- }
-}
-]]>
-</programlisting>
-
-
-
-<section><title>MDBs and HA-JMS Failover</title>
- <para>
- When you deploy an MDB in JBoss, JBoss' MDB container handles for you all issues associated with finding the cluster singleton HA-JMS server and with reconnecting to it if it fails over.
- </para>
-</section>
-
- </section>
-
-
-
- <section id="clustering-jms-loadbalanced">
- <title>Load Balanced HA-JMS MDBs</title>
- <para>While the HA-JMS queues and topics only run on a single node at a time, MDBs on multiple nodes
- can receive and process messages from the HA-JMS master node. The contested queues and topics
- result in load balancing behavior for MDBs. To enable loading balancing for MDBs, you can
- specify a receiver for the queue. The receiver records which node is waiting for a message and
- in which order the messages should be processed. JBoss provides three receiver implementations.</para>
- <itemizedlist>
- <listitem>
- <para>The <literal>org.jboss.mq.server.ReceiversImpl</literal> is the default implementation
- using a <literal>HashSet</literal>.</para>
- </listitem>
- <listitem>
- <para>The <literal>org.jboss.mq.server.ReceiversImplArrayList</literal> is the implementation
- using an <literal>ArrayList</literal>.</para>
- </listitem>
- <listitem>
- <para>The <literal>org.jboss.mq.server.ReceiversImplLinkedList</literal> is the
- implementation using a <literal>LinkedList</literal>.</para>
- </listitem>
- </itemizedlist>
- <para>You can specify the receiver implementation class name as an attribute in the MBean that
- defines the permanent JMS <literal>Queue</literal> or <literal>DestinationManager</literal> on
- each node. For best load balancing performance, we suggest you
- to use the <literal>ReceiversImplArrayList</literal> or
- <literal>ReceiversImplLinkedList</literal> implementations due to an undesirable implementation
- detail of <literal>HashSet</literal> in the JVM.</para>
- </section>
- </section>
-
</chapter>
Modified: projects/docs/enterprise/4.3.8/Server_Configuration_Guide/en-US/Server_Configuration_Guide_CP08.xml
===================================================================
--- projects/docs/enterprise/4.3.8/Server_Configuration_Guide/en-US/Server_Configuration_Guide_CP08.xml 2010-04-13 05:31:25 UTC (rev 103882)
+++ projects/docs/enterprise/4.3.8/Server_Configuration_Guide/en-US/Server_Configuration_Guide_CP08.xml 2010-04-13 06:03:09 UTC (rev 103883)
@@ -35,7 +35,7 @@
<xi:include href="Clustering_Guide_Entity_EJBs.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Clustering_Guide_HTTP.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Clustering_Guide_Clustered_Singleton_Services.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-<xi:include href="Clustering_Guide_JMS.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<!--<xi:include href="Clustering_Guide_JMS.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />-->
<xi:include href="Clustering_Guide_JBoss_Cache_JGroups.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</part>
<part id="Legacy_EJB_Support" label="IV">
More information about the jboss-cvs-commits
mailing list