[jboss-cvs] JBoss Messaging SVN: r2752 - trunk/docs/userguide/en/modules.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri Jun 1 08:58:06 EDT 2007
Author: timfox
Date: 2007-06-01 08:58:06 -0400 (Fri, 01 Jun 2007)
New Revision: 2752
Added:
trunk/docs/userguide/en/modules/bridge.xml
trunk/docs/userguide/en/modules/recovery_config.xml
Log:
Added new documentation sections
Added: trunk/docs/userguide/en/modules/bridge.xml
===================================================================
--- trunk/docs/userguide/en/modules/bridge.xml (rev 0)
+++ trunk/docs/userguide/en/modules/bridge.xml 2007-06-01 12:58:06 UTC (rev 2752)
@@ -0,0 +1,297 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="bridge">
+ <title>JBoss Messaging Message Bridge Configuration</title>
+
+ <section id="bridge.overview">
+ <title>Message bridge overview</title>
+
+ <para>JBoss Messaging includes a fully functional message bridge</para>
+
+ <para>The function of the bridge is to consume messages from a source queue or topic, and send them to target
+ queue or topic, typically on a different server.
+ </para>
+
+ <para>The source and target servers do not have to be in the same cluster which makes bridging suitable for reliably sending
+ messages from one cluster to another, for instance across a WAN.
+ </para>
+
+ <para>A bridge is deployed inside a JBoss AS instance. The instance can be the same instance as either the source or target server.
+ Or could be on a third, separate JBoss AS instance.
+ </para>
+
+ <para>A bridge is deployed as an MBean inside JBoss AS. Deployment is trivial - just drop the MBean descriptor into
+the deploy directory of a JBoss configuration which contains JBoss Messaging.
+ </para>
+
+ <para>An example in docs/example/bridge demonstrates a simple bridge being deployed in JBoss AS, and moving messages
+from the source to the target destination
+ </para>
+
+ <para>The bridge can also be used to bridge messages from other non JBoss Messaging JMS servers, as long as they are JMS 1.1 compliant.
+ This is as yet untested.
+ </para>
+
+ <para>The bridge has built in resilience to failure so if the source or target server connetion is lost, e.g. due to network failure.
+
+ Then the bridge can retry connecting to the source and/or target until they come back online. When this happens it will resume
+ operation as normal.
+ </para>
+
+ <para>The bridge can be configured with an optional selector, so it will only consume messages matching that selector</para>
+
+ <para>It can be configured to consume from a queue or a topic. When it consumes from a topic it can be configured to consume
+ using a non durable or durable subscription
+ </para>
+
+ <para>The bridge can be configured to bridge messages with one of three levels of quality of service, they are:
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+
+ <para>QOS_AT_MOST_ONCE</para>
+
+ <para>
+ With this QoS mode messages will reach the destination from the source at most once.
+ The messages are consumed from the source and acknowledged
+ before sending to the destination. Therefore there is a possibility that if failure occurs between
+ removing them from the source and them arriving at the destination they could be lost. Hence delivery
+ will occur at most once.
+ This mode is avilable for both persistent and non persistent messages.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>QOS_DUPLICATES_OK</para>
+
+ <para>
+ With this QoS mode, the messages are consumed from the source and then acknowledged
+ after they have been successfully sent to the destination. Therefore there is a possibility that if
+ failure occurs after sending to the destination but before acknowledging them, they could be sent again
+ when the system recovers. I.e. the destination might receive duplicates after a failure.
+ This mode is available for both persistent and non persistent messages.
+ </para>
+
+ </listitem>
+
+ <listitem>
+ <para>QOS_ONCE_AND_ONLY_ONCE</para>
+ <para>
+ This QoS mode ensures messages will reach the destination from the source once and only once.
+ (Sometimes this mode is known as "exactly once").
+ If both the source and the destination are on the same JBoss Messaging server instance then this can
+ be achieved by sending and acknowledging the messages in the same local transaction.
+ If the source and destination are on different servers this is achieved by enlisting the sending and consuming
+ sessions in a JTA transaction. The JTA transaction is controlled by JBoss Transactions JTA implementation which
+ is a fully recovering transaction manager, thus providing a very high degree of durability.
+ If JTA is required then both supplied connection factories need to be XAConnectionFactory implementations.
+ This mode is only available for persistent messages.
+ This is likely to be the slowest mode since it requires extra persistence for the transaction logging.
+ If you require this level of QoS, please be sure to enable XA recovery with JBoss Transactions.
+
+ <note>
+ For a specific application it may possible to provide once and only once semantics without using the
+ QOS_ONCE_AND_ONLY_ONCE QoS level. This can be done by using the QOS_DUPLICATES_OK mode and then checking for
+ duplicates at the destination and discarding them. Some JMS servers provide automatic duplicate message detection
+ functionality, or this may be possible to implement on the application level by maintaining a cache of received
+ message ids on disk and comparing received messages to them. The cache would only be valid
+ for a certain period of time so this approach is not as watertight as using QOS_ONCE_AND_ONLY_ONCE but
+ may be a good choice depending on your specific application.
+ </note>
+
+
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+
+ </section>
+
+ <section id="bridge.deployment">
+
+ <title>Bridge deployment</title>
+
+ <para>A message bridge is easily deployed by dropping the MBean descriptor in the deploy directory of your JBoss AS installation which contains JBoss Messaging</para>
+
+ </section>
+
+ <section id="bridge.configuration">
+
+ <title>Bridge configuration</title>
+
+ <para>In this section we describe how to configure the message bridge</para>
+
+ <para>Here is an example of a message bridge configuration, with all the attributes shown. Note that some are commented
+out for this configuration, since it is not appropriate to specify them all at once. Which ones are specified depends on
+the configuration you want.</para>
+
+ <programlisting>
+ <mbean code="org.jboss.jms.server.bridge.BridgeService"
+ name="jboss.messaging:service=Bridge,name=TestBridge"
+ xmbean-dd="xmdesc/Bridge-xmbean.xml">
+
+ <!-- The JMS provider loader that is used to lookup the source destination -->
+ <depends optional-attribute-name="SourceProviderLoader">jboss.messaging:service=JMSProviderLoader,name=JMSProvider</depends>
+
+ <!-- The JMS provider loader that is used to lookup the target destination -->
+ <depends optional-attribute-name="TargetProviderLoader">jboss.messaging:service=JMSProviderLoader,name=JMSProvider</depends>
+
+ <!-- The JNDI lookup for the source destination -->
+ <attribute name="SourceDestinationLookup">/queue/A</attribute>
+
+ <!-- The JNDI lookup for the target destination -->
+ <attribute name="TargetDestinationLookup">/queue/B</attribute>
+
+ <!-- The username to use for the source connection
+ <attribute name="SourceUsername">bob</attribute>
+ -->
+
+ <!-- The password to use for the source connection
+ <attribute name="SourcePassword">cheesecake</attribute>
+ -->
+
+ <!-- The username to use for the target connection
+ <attribute name="TargetUsername">mary</attribute>
+ -->
+
+ <!-- The password to use for the target connection
+ <attribute name="TargetPassword">hotdog</attribute>
+ -->
+
+ <!-- Optional: The Quality Of Service mode to use, one of:
+ QOS_AT_MOST_ONCE = 0;
+ QOS_DUPLICATES_OK = 1;
+ QOS_ONCE_AND_ONLY_ONCE = 2; -->
+ <attribute name="QualityOfServiceMode">0</attribute>
+
+ <!-- JMS selector to use for consuming messages from the source
+ <attribute name="Selector">specify jms selector here</attribute>
+ -->
+
+ <!-- The maximum number of messages to consume from the source before sending to the target -->
+ <attribute name="MaxBatchSize">5</attribute>
+
+ <!-- The maximum time to wait (in ms) before sending a batch to the target even if MaxBatchSize is not exceeded.
+ -1 means wait forever -->
+ <attribute name="MaxBatchTime">-1</attribute>
+
+ <!-- If consuming from a durable subscription this is the subscription name
+ <attribute name="SubName">mysub</attribute>
+ -->
+
+ <!-- If consuming from a durable subscription this is the client ID to use
+ <attribute name="ClientID">myClientID</attribute>
+ -->
+
+ <!-- The number of ms to wait between connection retrues in the event connections to source or target fail -->
+ <attribute name="FailureRetryInterval">5000</attribute>
+
+ <!-- The maximum number of connection retries to make in case of failure, before giving up
+ -1 means try forever-->
+ <attribute name="MaxRetries">-1</attribute>
+
+ </mbean>
+ </programlisting>
+
+ <para>We will now discuss each attribute</para>
+
+ <section id="bridge.configuration.sourceproviderloader">
+ <title>SourceProviderLoader</title>
+ <para>This is the object name of the JMSProviderLoader MBean that the bridge will use to lookup the source connection factory and source destination.</para>
+ <para>By default JBoss AS ships with one JMSProviderLoader, deployed in the file <filename>jms-ds.xml</filename> - this is the default local JMSProviderLoader. (This would be in <filename>hajndi-jms-ds.xml</filename> in a clustered configuration)</para>
+ <para>If your source destination is on different servers or even correspond to a different, non JBoss JMS provider, then you can deploy another JMSProviderLoader MBean instance which references the remote JMS provider, and reference that from this attribute. The bridge would then use that remote JMS provider to contact the source destination</para>
+ <para>Note that if you are using a remote non JBoss Messaging source or target and you wish once and only once delivery then that remote JMS provider must provide a fully functional JMS XA resource implementation that works remotely from the server - it is known that some non JBoss JMS providers do not provide such a resource</para>
+ </section>
+
+ <section id="bridge.configuration.targetproviderloader">
+ <title>TargetProviderLoader</title>
+ <para>This is the object name of the JMSProviderLoader MBean that the bridge will use to lookup the target connection factory and target destination.</para>
+ <para>By default JBoss AS ships with one JMSProviderLoader, deployed in the file <filename>jms-ds.xml</filename> - this is the default local JMSProviderLoader. (This would be in <filename>hajndi-jms-ds.xml</filename> in a clustered configuration)</para>
+ <para>If your target destination is on a different server or even correspond to a different, non JBoss JMS provider, then you can deploy another JMSProviderLoader MBean instance which references the remote JMS provider, and reference that from this attribute. The bridge would then use that remote JMS provider to contact the target destination</para>
+ <para>Note that if you are using a remote non JBoss Messaging source or target and you wish once and only once delivery then that remote JMS provider must provide a fully functional JMS XA resource implementation that works remotely from the server - it is known that some non JBoss JMS providers do not provide such a resource</para>
+ </section>
+
+ <section id="bridge.configuration.sourcedestinationlookup">
+ <title>SourceDestinationLookup</title>
+ <para>This is the full JNDI lookup for the source destination using the SourceProviderLoader</para>
+ <para>An example would be /queue/mySourceQueue</para>
+ </section>
+
+ <section id="bridge.configuration.targetdestinationlookup">
+ <title>TargetDestinationLookup</title>
+ <para>This is the full JNDI lookup for the target destination using the TargetProviderLoader</para>
+ <para>An example would be /topic/myTargetTopic</para>
+ </section>
+
+ <section id="bridge.configuration.sourceusername">
+ <title>SourceUsername</title>
+ <para>This optional attribute is for when you need to specify the username for creating the source connection</para>
+ </section>
+
+ <section id="bridge.configuration.sourcepassword">
+ <title>SourcePassword</title>
+ <para>This optional attribute is for when you need to specify the password for creating the source connection</para>
+ </section>
+
+ <section id="bridge.configuration.targetusername">
+ <title>TargetUsername</title>
+ <para>This optional attribute is for when you need to specify the username for creating the target connection</para>
+ </section>
+
+ <section id="bridge.configuration.targetpassword">
+ <title>TargetPassword</title>
+ <para>This optional attribute is for when you need to specify the password for creating the target connection</para>
+ </section>
+
+ <section id="bridge.configuration.qualityofservicemode">
+ <title>QualityOfServiceMode</title>
+ <para>This integer represents the desired quality of service mode</para>
+ <para>Possible values are QOS_AT_MOST_ONCE = 0, QOS_DUPLICATES_OK = 1, QOS_ONCE_AND_ONLY_ONCE = 2</para>
+ <para>Please see <xref linkend="bridge.overview"/> for an explanation of what these mean.</para>
+ </section>
+
+ <section id="bridge.configuration.selector">
+ <title>Selector</title>
+ <para>This optional attribute can contain a JMS selector expression used for consuming messages from the source destination. Only messages that match the selector expression will be bridged from the source to the target destination</para>
+ <para>Please note it is always more performant to apply selectors on source topic subscriptions to source queue consumers.</para>
+ <para>The selector expression must follow the JMS selector syntax specified here:
+<ulink url="http://java.sun.com/j2ee/1.4/docs/api/javax/jms/Message.html"/></para>
+ </section>
+
+ <section id="bridge.configuration.maxbatchsize">
+ <title>MaxBatchSize</title>
+ <para>This attribute specifies the maximum number of messages to consume from the source destination before
+sending them in a batch to the target destination. It's value must >= 1</para>
+ </section>
+
+ <section id="bridge.configuration.maxbatchtime">
+ <title>MaxBatchTime</title>
+ <para>This attribute specifies the maximum number of milliseconds to wait before sending a batch to target, even if the number of messages consumed has not reached MaxBatchSize. It's value must can be -1 to represent 'wait forever', or >=1 to specify an actual time.</para>
+ </section>
+
+ <section id="bridge.configuration.subname">
+ <title>SubName</title>
+ <para>If the source destination represents a topic, and you want to consume from the topic using a durable subscription then this attribute represents the durable subscription name</para>
+ </section>
+
+ <section id="bridge.configuration.clientid">
+ <title>ClientID</title>
+ <para>If the source destination represents a topic, and you want to consume from the topic using a durable subscription then this attribute represents the the JMS client ID to use when creating/looking up the durable subscription</para>
+ </section>
+
+ <section id="bridge.configuration.failureretryinterval">
+ <title>FailureRetryInterval</title>
+ <para>This represents the amount of time in ms to wait between trying to recreate connections to the source or target servers when the bridge has detected they have failed</para>
+ </section>
+
+ <section id="bridge.configuration.maxretries">
+ <title>MaxRetries</title>
+ <para>This represents the number of times to attempt to recreate connections to the source or target servers when the bridge has detected they have failed. The bridge will give up after trying this number of times. -1 represents 'try forever'</para>
+ </section>
+
+ </section>
+
+</chapter>
Added: trunk/docs/userguide/en/modules/recovery_config.xml
===================================================================
--- trunk/docs/userguide/en/modules/recovery_config.xml (rev 0)
+++ trunk/docs/userguide/en/modules/recovery_config.xml 2007-06-01 12:58:06 UTC (rev 2752)
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="recovery">
+ <title>JBoss Messaging XA Recovery Configuration</title>
+
+ <para>This section describes how to configure JBoss Transactions in JBoss AS 4.2.0 to handle XA recovery for JBoss Messaging
+ resources.
+ </para>
+
+ <para>JBoss Transactions recovery manager can easily be configured to continually poll for and recover JBoss Messaging XA resources,
+ this provides an extremely high level of durability of transactions.
+ </para>
+
+ <para>Enabling JBoss Transactions Recovery Manager to recover JBoss Messaging resources is a very simple matter and involves adding a line to the file ${JBOSS_CONFIG}/conf/jbossjta-properties.xml</para>
+
+ <para>Here's an example section of a jbossjta-properties.xml file with the line added (note the whole file is not shown)</para>
+
+ <programlisting>
+ <properties depends="arjuna" name="jta">
+ <!--
+ Support subtransactions in the JTA layer?
+ Default is NO.
+ -->
+ <property name="com.arjuna.ats.jta.supportSubtransactions" value="NO"/>
+ <property name="com.arjuna.ats.jta.jtaTMImplementation" value="com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple"/>
+ <!--
+ com.arjuna.ats.internal.jta.transaction.jts.TransactionManagerImple
+ -->
+ <property name="com.arjuna.ats.jta.jtaUTImplementation" value="com.arjuna.ats.internal.jta.transaction.arjunacore.UserTransactionImple"/>
+ <!--
+ com.arjuna.ats.internal.jta.transaction.jts.UserTransactionImple
+ -->
+
+ <!-- *** Add this line to enable recovery for JMS resources using DefaultJMSProvider *** -->
+ <property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGING1" value="org.jboss.jms.server.recovery.MessagingXAResourceRecovery;DefaultJMSProvider"/>
+
+ </properties>
+
+ </programlisting>
+
+ <para>In the above example the recovery manager will attempt to recover JMS resources using the JMSProviderLoader "DefaultJMSProvider"</para>
+ <para>DefaultJMSProvider is the default JMS provider loader that ships with JBoss AS and is defined in jms-ds.xml (or hajndi-jms-ds.xml in
+ a clustered configuration). If you want to recovery using a different JMS provider loader - e.g. one corresponding to a remote JMS provider
+ then just add another line and instead of DefaultJMSProvider specify the name of the remote JMS provider as specified in it's MBean configuration.
+ </para>
+ <para>For each line you add, the name must be unique, so you could specify "com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGING1",
+ "com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGING2, ..." etc.</para>
+ <para>In actual fact, the recovery also should work with any JMS provider that implements recoverable XAResources (i.e. it properly implements XAResource.recover())
+ , not just JBoss Messaging</para>
+
+
+
+</chapter>
More information about the jboss-cvs-commits
mailing list