[jboss-cvs] JBoss Messaging SVN: r5005 - branches/Branch_1_4/docs/userguide/en/modules.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Sep 22 15:40:34 EDT 2008
Author: clebert.suconic at jboss.com
Date: 2008-09-22 15:40:34 -0400 (Mon, 22 Sep 2008)
New Revision: 5005
Modified:
branches/Branch_1_4/docs/userguide/en/modules/bridge.xml
branches/Branch_1_4/docs/userguide/en/modules/c_configuration.xml
branches/Branch_1_4/docs/userguide/en/modules/configuration.xml
branches/Branch_1_4/docs/userguide/en/modules/installation.xml
branches/Branch_1_4/docs/userguide/en/modules/recovery_config.xml
Log:
Format & small tweaks
Modified: branches/Branch_1_4/docs/userguide/en/modules/bridge.xml
===================================================================
--- branches/Branch_1_4/docs/userguide/en/modules/bridge.xml 2008-09-22 18:18:43 UTC (rev 5004)
+++ branches/Branch_1_4/docs/userguide/en/modules/bridge.xml 2008-09-22 19:40:34 UTC (rev 5005)
@@ -1,103 +1,123 @@
<?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 a 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, and where the
- connection may be unreliable.</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.</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, the bridge
- will retry connecting to the source and/or target until they come back
- online. When it comes back online it will resume operation as
- normal.</para>
- <para>The bridge can be configured with an optional JMS selector, so it
- will only consume messages matching that JMS 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 logging on both the
- transaction manager and resource side for recovery. 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. 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>
+ <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 a 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, and where the connection
+ may be unreliable.</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.</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, the bridge
+ will retry connecting to the source and/or target until they come back
+ online. When it comes back online it will resume operation as
+ normal.</para>
+
+ <para>The bridge can be configured with an optional JMS selector, so it
+ will only consume messages matching that JMS 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 logging on both the transaction
+ manager and resource side for recovery. 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. 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">
@@ -174,159 +194,205 @@
</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: <itemizedlist>
- <listitem>
- QOS_AT_MOST_ONCE = 0
- </listitem>
- <listitem>
- QOS_DUPLICATES_OK = 1
- </listitem>
- <listitem>
- QOS_ONCE_AND_ONLY_ONCE = 2
- </listitem>
- </itemizedlist></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"></ulink></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 id="bridge.configuration.addmessageidinheader">
- <title>AddMessageIDInHeader</title>
- <para>If true, then the original message's message id will appended
- in the message sent to the destination in the header
- JBossMessage.JBOSS_MESSAGING_BRIDGE_MESSAGE_ID_LIST. If the message
- is bridged more than once each message-id will be appended. This
- enables a distributed request-response pattern to be used</para>
- </section>
- </section>
+
+ <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: <itemizedlist>
+ <listitem>
+ QOS_AT_MOST_ONCE = 0
+ </listitem>
+
+ <listitem>
+ QOS_DUPLICATES_OK = 1
+ </listitem>
+
+ <listitem>
+ QOS_ONCE_AND_ONLY_ONCE = 2
+ </listitem>
+ </itemizedlist></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"></ulink></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 id="bridge.configuration.addmessageidinheader">
+ <title>AddMessageIDInHeader</title>
+
+ <para>If true, then the original message's message id will appended in
+ the message sent to the destination in the header
+ JBossMessage.JBOSS_MESSAGING_BRIDGE_MESSAGE_ID_LIST. If the message is
+ bridged more than once each message-id will be appended. This enables a
+ distributed request-response pattern to be used</para>
+ </section>
+ </section>
</chapter>
\ No newline at end of file
Modified: branches/Branch_1_4/docs/userguide/en/modules/c_configuration.xml
===================================================================
--- branches/Branch_1_4/docs/userguide/en/modules/c_configuration.xml 2008-09-22 18:18:43 UTC (rev 5004)
+++ branches/Branch_1_4/docs/userguide/en/modules/c_configuration.xml 2008-09-22 19:40:34 UTC (rev 5005)
@@ -1,97 +1,115 @@
-<?xml version="1.0" encoding="UTF8"?>
+<?xml version="1.0" encoding="UTF-8"?>
<chapter id="c_configuration">
- <title>JBoss Messaging Clustering Notes</title>
-
- <section id="c_conf.serverpeerid">
- <title>Unique server peer id</title>
- <para>JBoss Messaging clustering should work out of the box in most cases
- with no configuration changes. It is however crucial that every node is
- assigned a unique server id, as specified in the installation guide.</para>
- <para>Every node deployed must have a unique id, including those in a
- particular LAN cluster, and also those only linked by mesage
- bridges.</para>
- </section>
-
- <section id="c_conf.clustereddests">
- <title>Clustered destinations</title>
- <para>JBoss Messaging clusters JMS queues and topics transparently across
- the cluster. Messages sent to a distributed queue or topic on one node are
- consumable on other nodes. To designate that a particular destination is
- clustered simply set the clustered attribute in the destination deployment
- descriptor to true.</para>
- <para>JBoss Messaging balances messages between nodes, catering for faster
- or slower consumers to efficiently balance processing load across the
- cluster.</para>
- <para>If you do not want message redistribution between nodes, but still want to retain the other charactereristics
- of clustered destinations. You can do this by not specifying the attribute ClusterPullConnectionFactoryName on the server peer
- </para>
- </section>
-
- <section id="c_conf.clustereddursubs">
- <title>Clustered durable subs</title>
- <para>JBoss Messaging durable subscriptions can also be clustered. This
- means multiple subscribers can consume from the same durable subscription
- from different nodes of the cluster. A durable subscription will be
- clustered if it's topic is clustered</para>
- </section>
-
- <section id="c_conf.clusteredtempdest">
- <title>Clustered temporary destinations</title>
- <para>JBoss Messaging also supports clustered temporary topics and queues.
- All temporary topics and queues will be clustered if the post office is
- clustered</para>
- </section>
-
- <section id="c_conf.nonclusteredserver">
- <title>Non clustered servers</title>
- <para>If you don't want your nodes to participate in a cluster, or only
- have one non clustered server you can set the clustered attribute on the
- postoffice to false</para>
- </section>
-
-
- <section id="c_conf.orderingincluster">
- <title>Message ordering in the cluster</title>
- <para>If you wish to apply strict JMS ordering to messages, such that a
- particular JMS consumer consumes messages in the same order as they were
- produced by a particular producer, you can set the DefaultPreserveOrdering
- attribute in the server peer to true. By default this is false. The
- sideeffect of setting this to true is that messages cannot be distributed
- as freely around the cluster</para>
- </section>
-
-
- <section id="c_conf.idempotentops">
- <title>Idempotent operations</title>
- <para>If the call to send a persistent message to a persistent destination
- returns successfully with no exception, then you can be sure that the
- message was persisted. However if the call doesn't return successfully e.g.
- if an exception is thrown, then you *can't be sure the message wasn't
- persisted*. Since the failure might have occurred after persisting the
- message but before writing the response to the caller. This is a common
- attribute of any RPC type call: You can't tell by the call not returning
- that the call didn't actually succeed. Whether it's a web services call, an
- HTTP get request, an ejb invocation the same applies. The trick is to code
- your application so your operations are *idempotent* i.e. they can be
- repeated without getting the system into an inconsistent state. With a
- messaging system you can do this on the application level, by checking for
- duplicate messages, and discarding them if they arrive. Duplicate checking
- is a very powerful technique that can remove the need for XA transactions
- in many cases.</para>
- <para>In the clustered case. JBM is by default configured to detect duplicate automatically messages by default</para>
- </section>
-
-
- <section id="c_conf.clusteredcfs">
- <title>Clustered connection factories</title>
- <para>If the supportsLoadBalancing attribute of the connection factory is set to true then consecutive create connection attempts will round robin between available servers. The first node to try is chosen randomly</para>
- <para>If the supportsFailover attribute of the connection factory is set to true then automatic failover is enabled.
- This will automatically failover from one server to another, transparently to the user, in case of failure.</para>
- <para>If automatic failover is not required or you wish to do manual failover (JBoss MQ style) this can be set to false, and you can supply a standard JMS ExceptionListener on the connection which will be called in case of
- connection failure. You would then need to manually close the connection, lookup a new connection factory from
- HA JNDI and recreate the connection.</para>
-
- </section>
-
-
+ <title>JBoss Messaging Clustering Notes</title>
+
+ <section id="c_conf.serverpeerid">
+ <title>Unique server peer id</title>
+
+ <para>JBoss Messaging clustering should work out of the box in most cases
+ with no configuration changes. It is however crucial that every node is
+ assigned a unique server id, as specified in the installation
+ guide.</para>
+
+ <para>Every node deployed must have a unique id, including those in a
+ particular LAN cluster, and also those only linked by mesage
+ bridges.</para>
+ </section>
+
+ <section id="c_conf.clustereddests">
+ <title>Clustered destinations</title>
+
+ <para>JBoss Messaging clusters JMS queues and topics transparently across
+ the cluster. Messages sent to a distributed queue or topic on one node are
+ consumable on other nodes. To designate that a particular destination is
+ clustered simply set the clustered attribute in the destination deployment
+ descriptor to true.</para>
+
+ <para>JBoss Messaging balances messages between nodes, catering for faster
+ or slower consumers to efficiently balance processing load across the
+ cluster.</para>
+
+ <para>If you do not want message redistribution between nodes, but still
+ want to retain the other charactereristics of clustered destinations. You
+ can do this by not specifying the attribute
+ ClusterPullConnectionFactoryName on the server peer</para>
+ </section>
+
+ <section id="c_conf.clustereddursubs">
+ <title>Clustered durable subs</title>
+
+ <para>JBoss Messaging durable subscriptions can also be clustered. This
+ means multiple subscribers can consume from the same durable subscription
+ from different nodes of the cluster. A durable subscription will be
+ clustered if it's topic is clustered</para>
+ </section>
+
+ <section id="c_conf.clusteredtempdest">
+ <title>Clustered temporary destinations</title>
+
+ <para>JBoss Messaging also supports clustered temporary topics and queues.
+ All temporary topics and queues will be clustered if the post office is
+ clustered</para>
+ </section>
+
+ <section id="c_conf.nonclusteredserver">
+ <title>Non clustered servers</title>
+
+ <para>If you don't want your nodes to participate in a cluster, or only
+ have one non clustered server you can set the clustered attribute on the
+ postoffice to false</para>
+ </section>
+
+ <section id="c_conf.orderingincluster">
+ <title>Message ordering in the cluster</title>
+
+ <para>If you wish to apply strict JMS ordering to messages, such that a
+ particular JMS consumer consumes messages in the same order as they were
+ produced by a particular producer, you can set the DefaultPreserveOrdering
+ attribute in the server peer to true. By default this is false. The
+ sideeffect of setting this to true is that messages cannot be distributed
+ as freely around the cluster</para>
+ </section>
+
+ <section id="c_conf.idempotentops">
+ <title>Idempotent operations</title>
+
+ <para>If the call to send a persistent message to a persistent destination
+ returns successfully with no exception, then you can be sure that the
+ message was persisted. However if the call doesn't return successfully
+ e.g. if an exception is thrown, then you *can't be sure the message wasn't
+ persisted*. Since the failure might have occurred after persisting the
+ message but before writing the response to the caller. This is a common
+ attribute of any RPC type call: You can't tell by the call not returning
+ that the call didn't actually succeed. Whether it's a web services call,
+ an HTTP get request, an ejb invocation the same applies. The trick is to
+ code your application so your operations are *idempotent* i.e. they can be
+ repeated without getting the system into an inconsistent state. With a
+ messaging system you can do this on the application level, by checking for
+ duplicate messages, and discarding them if they arrive. Duplicate checking
+ is a very powerful technique that can remove the need for XA transactions
+ in many cases.</para>
+
+ <para>In the clustered case. JBM is by default configured to detect
+ duplicate automatically messages by default</para>
+ </section>
+
+ <section id="c_conf.clusteredcfs">
+ <title>Clustered connection factories</title>
+
+ <para>If the supportsLoadBalancing attribute of the connection factory is
+ set to true then consecutive create connection attempts will round robin
+ between available servers. The first node to try is chosen randomly</para>
+
+ <para>If the supportsFailover attribute of the connection factory is set
+ to true then automatic failover is enabled. This will automatically
+ failover from one server to another, transparently to the user, in case of
+ failure.</para>
+
+ <para>If automatic failover is not required or you wish to do manual
+ failover (JBoss MQ style) this can be set to false, and you can supply a
+ standard JMS ExceptionListener on the connection which will be called in
+ case of connection failure. You would then need to manually close the
+ connection, lookup a new connection factory from HA JNDI and recreate the
+ connection.</para>
+ </section>
</chapter>
\ No newline at end of file
Modified: branches/Branch_1_4/docs/userguide/en/modules/configuration.xml
===================================================================
--- branches/Branch_1_4/docs/userguide/en/modules/configuration.xml 2008-09-22 18:18:43 UTC (rev 5004)
+++ branches/Branch_1_4/docs/userguide/en/modules/configuration.xml 2008-09-22 19:40:34 UTC (rev 5005)
@@ -31,8 +31,8 @@
considered the security implications before removing the security
interceptor.</para>
- <section id="conf.securityMetadataStore">
- <title>Configuring the SecurityStore</title>
+ <section id="conf.jb5.securityMetadataStore">
+ <title>JBoss5 Specific - Configuring the SecurityStore</title>
<para>Starting on JBossMessaging 1.4.1 the SecurityStore is a pluggable
object, and it has a default implementation on
@@ -96,14 +96,20 @@
<para>The JAAS security domain to be used by this server peer</para>
</section>
+
<section id="conf.securityMetadataStore.attributes.suckerpassword">
<title>SuckerPassword</title>
- <para>This defines how the SecurityStore will authenticate the sucker user (JBM.SUCKER)</para>
+ <para>This defines how the SecurityStore will authenticate the sucker
+ user (JBM.SUCKER)</para>
</section>
</section>
</section>
+ <section id="conf.jb4.security">
+ <title>JBoss4/EAP4.3 Specific - Configuring the SecurityStore</title>
+ </section>
+
<section id="conf.serverpeer">
<title>Configuring the ServerPeer</title>
@@ -367,11 +373,12 @@
messages will timeout and be added back to the queue. The value is in
ms. The default is 5 mins.</para>
</section>
-
+
<section id="conf.serverpeer.attributes.enablemessagecounters">
- <title>EnableMessageCounters</title>
-
- <para>Set this to true to enable message counters when the server starts</para>
+ <title>EnableMessageCounters</title>
+
+ <para>Set this to true to enable message counters when the server
+ starts</para>
</section>
<section id="conf.serverpeer.attributes.suckerpassword">
@@ -865,32 +872,31 @@
<para>By default the value of <literal>CreateTablesOnStartup</literal>
attribute is set to <literal>true</literal></para>
</section>
-
+
<section id="conf.postoffice.attributes.detectdups">
- <title>DetectDuplicates</title>
-
- <para>Set this to <literal>true</literal> if you wish the post office detect duplicate messages
- that may sent when a send is retried on a different node after server failure.
- </para>
-
- <para>By default the value of <literal>DetectDuplicates</literal>
- attribute is set to <literal>true</literal></para>
- </section>
-
+ <title>DetectDuplicates</title>
+
+ <para>Set this to <literal>true</literal> if you wish the post office
+ detect duplicate messages that may sent when a send is retried on a
+ different node after server failure.</para>
+
+ <para>By default the value of <literal>DetectDuplicates</literal>
+ attribute is set to <literal>true</literal></para>
+ </section>
+
<section id="conf.postoffice.attributes.idcachesize">
- <title>IDCacheSize</title>
-
- <para>If duplicate detection is enabled. (See <literal>DetectDuplicates</literal>), then the server will rememeber the last
- <literal>n</literal> message ids
- sent, to prevent duplicate messages sent after failover has occurred. The value of <literal>n</literal> is determined by this attribute.
- </para>
-
- <para>By default the value of <literal>IDCacheSize</literal>
- attribute is set to <literal>500</literal></para>
- </section>
-
+ <title>IDCacheSize</title>
+ <para>If duplicate detection is enabled. (See
+ <literal>DetectDuplicates</literal>), then the server will rememeber
+ the last <literal>n</literal> message ids sent, to prevent duplicate
+ messages sent after failover has occurred. The value of
+ <literal>n</literal> is determined by this attribute.</para>
+ <para>By default the value of <literal>IDCacheSize</literal> attribute
+ is set to <literal>500</literal></para>
+ </section>
+
<section id="conf.postoffice.attributes.postofficename">
<title>PostOfficeName</title>
@@ -940,17 +946,18 @@
<para>The default value is <literal>5000</literal>
milliseconds.</para>
</section>
-
+
<section id="conf.postoffice.attributes.failoveronnodeleave">
- <title>FailoverOnNodeLeave</title>
-
- <para>If this attribute is <literal>true</literal> then if a server node is shut down cleanly, then this will cause any
- connections on the shutting down node to failover onto another node.</para>
+ <title>FailoverOnNodeLeave</title>
- <para>The default value for this is attribute is <literal>false</literal></para>
-
- </section>
+ <para>If this attribute is <literal>true</literal> then if a server
+ node is shut down cleanly, then this will cause any connections on the
+ shutting down node to failover onto another node.</para>
+ <para>The default value for this is attribute is
+ <literal>false</literal></para>
+ </section>
+
<section id="conf.postoffice.attributes.maxconcurrentreplications">
<title>MaxConcurrentReplications</title>
@@ -1036,7 +1043,7 @@
<para>JBoss Messaging also ships with pre-made Persistence Manager
configurations for MySQL, Oracle, PostgreSQL, Sybase and MS SQL Server.
The example <filename>mysql-persistence-service.xml</filename>,
- <filename>ndb-persistence-service.xml</filename>,
+ <filename>ndb-persistence-service.xml</filename>,
<filename>oracle-persistence-service.xml</filename>,
<filename>postgres-persistence-service.xml</filename> and
<filename>sybase-persistence-service.xml</filename> and
@@ -1052,8 +1059,8 @@
of changing DDL in the configuration which is likely to be different for
different databases.</para>
- <para>JBoss Messaging also ships with a Null Persistence Manager config - this can be used when you don't want any persistence at all.
- </para>
+ <para>JBoss Messaging also ships with a Null Persistence Manager config -
+ this can be used when you don't want any persistence at all.</para>
<para>The default Hypersonic persistence configuration file is listed
below:</para>
@@ -1225,19 +1232,22 @@
is set to <literal>100</literal></para>
</section>
- <section id="conf.persistencemanager.attributes.usendbfailoverstrategy">
- <title>UseNDBFailoverStrategy</title>
- <para>When running in a clustered database environment it is possible that some databases,
- MySQL for instance, can fail during the commit of a database transaction. This can happen
- if the database node dies whilst committing meaning that the final state of the transaction is
- unknown. If this attribute is set to true and the above happens then the SQL statement will be
- re-executed, however if there is a further error an assumption is made that this is because the
- previous transaction committed successfully and the error is ignored.
- </para>
+ <section id="conf.persistencemanager.attributes.usendbfailoverstrategy">
+ <title>UseNDBFailoverStrategy</title>
- <para>By default the value of <literal>UseNDBFailoverStrategy</literal> attribute
- is set to <literal>false</literal></para>
- </section>
+ <para>When running in a clustered database environment it is possible
+ that some databases, MySQL for instance, can fail during the commit of
+ a database transaction. This can happen if the database node dies
+ whilst committing meaning that the final state of the transaction is
+ unknown. If this attribute is set to true and the above happens then
+ the SQL statement will be re-executed, however if there is a further
+ error an assumption is made that this is because the previous
+ transaction committed successfully and the error is ignored.</para>
+
+ <para>By default the value of
+ <literal>UseNDBFailoverStrategy</literal> attribute is set to
+ <literal>false</literal></para>
+ </section>
</section>
<!-- end conf.persistencemanager.attributes -->
@@ -2202,9 +2212,13 @@
<section id="conf.connectionfactory.attributes.prefetchsize">
<title>PrefetchSize</title>
- <para>This parameter specifies the window size in numbers of messages, for consumer flow control.
- The window size determines the number of messages a server can send to a consumer without blocking.
- Each consumer maintains a buffer of messages from which it consumes. Please note that TCP also implements its own flow control, so if you set this to too large a number, then the TCP window size may be hit before the prefetchSize, which can cause writes to block.</para>
+ <para>This parameter specifies the window size in numbers of messages,
+ for consumer flow control. The window size determines the number of
+ messages a server can send to a consumer without blocking. Each
+ consumer maintains a buffer of messages from which it consumes. Please
+ note that TCP also implements its own flow control, so if you set this
+ to too large a number, then the TCP window size may be hit before the
+ prefetchSize, which can cause writes to block.</para>
</section>
<section id="conf.connectionfactory.attributes.slowconsumers">
@@ -2212,7 +2226,8 @@
<para>If you have very slow consumers, then you probably want to make
sure they don't buffer any messages. Since this can prevent them from
- being consumed by faster consumers. Setting this to true is equivalent to setting PrefetchSize to 1</para>
+ being consumed by faster consumers. Setting this to true is equivalent
+ to setting PrefetchSize to 1</para>
</section>
<section id="conf.connectionfactory.attributes.tckstrictbehavior">
@@ -2221,11 +2236,13 @@
<para>Set this to true if you want strict JMS behaviour as required by
the TCK.</para>
</section>
-
+
<section id="conf.connectionfactory.attributes.sendacksasync">
- <title>SendAcksAsync</title>
-
- <para>Set this to true if you want acknowledgements to be sent asynchronously. This can speed up performance especially if you are using auto_acknowledge mode</para>
+ <title>SendAcksAsync</title>
+
+ <para>Set this to true if you want acknowledgements to be sent
+ asynchronously. This can speed up performance especially if you are
+ using auto_acknowledge mode</para>
</section>
<section id="conf.connectionfactory.attributes.tempqueuepaging">
Modified: branches/Branch_1_4/docs/userguide/en/modules/installation.xml
===================================================================
--- branches/Branch_1_4/docs/userguide/en/modules/installation.xml 2008-09-22 18:18:43 UTC (rev 5004)
+++ branches/Branch_1_4/docs/userguide/en/modules/installation.xml 2008-09-22 19:40:34 UTC (rev 5005)
@@ -3,16 +3,17 @@
<title>JBoss Messaging Installation</title>
<para>This section describes procedures on how to install JBoss Messaging
- into JBoss Application Server community edition 4.2.
- At the end of this procedure, you will create a JBoss
- Messaging configuration that will start a clustered or non-clustered
- messaging server.</para>
+ into JBoss Application Server community edition 4.2. At the end of this
+ procedure, you will create a JBoss Messaging configuration that will start a
+ clustered or non-clustered messaging server.</para>
- <para>Please note that JBoss EAP 4.3 or later comes with JBoss Messaging pre-installed as default JMS provider so there is no need to manually install it.</para>
+ <para>Please note that JBoss EAP 4.3 or later comes with JBoss Messaging
+ pre-installed as default JMS provider so there is no need to manually
+ install it.</para>
- <para>By default, JBoss AS 4.2 ships with JBossMQ as default JMS provider. In
- order to use the JBoss AS instance with JBoss Messaging, you need to perform
- the installation procedure described below.</para>
+ <para>By default, JBoss AS 4.2 ships with JBossMQ as default JMS provider.
+ In order to use the JBoss AS instance with JBoss Messaging, you need to
+ perform the installation procedure described below.</para>
<para><note>
A JBossMQ and a JBoss Messaging instance cannot coexist, at least not unless special precautions are taken. Do not simply attempt to copy the Messaging release artifact
@@ -962,46 +963,75 @@
</listitem>
</itemizedlist>
</section>
- <section id="inst.mqmessagemigration">
- <title>Migrating Messages from JBoss MQ to JBoss Messaging</title>
- <para>This configuration will allow you to migrate your systems using JBossMQ to JBM(JBoss Messaging).
- Many Enterprise systems are complex and have multiple applications and can't be migrated from JBossMQ to
- JBM all at one time.</para>
- <para>Made up Use Case: For instance, your business is selling items, some you make directly and some you farm
- out to other distributors. Your ordering system is JBossMQ based. Customers place orders that are then queued
- up to be processed(via JBossMQ). You also use MQ to queue up the orders that you need to produce and you also
- queue up the orders that will go to your other distributors. You use MDB's in three separate places in your
- operation. You want to do a staged migration from JBossMQ to JBM. That requires that JBossMQ and JBM work
- together. This is exactly what the JBM bridge was meant to do. It's meant to take messages from one queue/topic
- and transfer them to another queue/topic. This helps with the migration by allowing you to pull messages from
- your JBossMQ queues automatically and push them into your JBM Queues. You can also do the opposite, you can
- push messages from your JBM system to your JBossMQ system. In our example, we want to replace the ordering
- side(producer) with JBM. We push messages into the JBM Order queue, but we set the bridge up to send all of
- those messages to the JBossMQ Order queue. The rest of your processing happens as normal. Lets say you want
- to leave your ordering system intact, but you want to have JBM and EJB3 MDBs process the orders. You can have
- your old client put messages in JBossMQ as normal, but you set the bridge up to pull the messages from JBossMQ
- Order queue and push them into the JBM Order queue.</para>
- <para>This allows JBM and JBossMQ to interact together by pushing messages back and forth between different systems.</para>
- <para>The Following Assumptions are made:</para>
+
+ <section id="inst.mqmessagemigration">
+ <title>Migrating Messages from JBoss MQ to JBoss Messaging</title>
+
+ <para>This configuration will allow you to migrate your systems using
+ JBossMQ to JBM(JBoss Messaging). Many Enterprise systems are complex and
+ have multiple applications and can't be migrated from JBossMQ to JBM all
+ at one time.</para>
+
+ <para>Made up Use Case: For instance, your business is selling items, some
+ you make directly and some you farm out to other distributors. Your
+ ordering system is JBossMQ based. Customers place orders that are then
+ queued up to be processed(via JBossMQ). You also use MQ to queue up the
+ orders that you need to produce and you also queue up the orders that will
+ go to your other distributors. You use MDB's in three separate places in
+ your operation. You want to do a staged migration from JBossMQ to JBM.
+ That requires that JBossMQ and JBM work together. This is exactly what the
+ JBM bridge was meant to do. It's meant to take messages from one
+ queue/topic and transfer them to another queue/topic. This helps with the
+ migration by allowing you to pull messages from your JBossMQ queues
+ automatically and push them into your JBM Queues. You can also do the
+ opposite, you can push messages from your JBM system to your JBossMQ
+ system. In our example, we want to replace the ordering side(producer)
+ with JBM. We push messages into the JBM Order queue, but we set the bridge
+ up to send all of those messages to the JBossMQ Order queue. The rest of
+ your processing happens as normal. Lets say you want to leave your
+ ordering system intact, but you want to have JBM and EJB3 MDBs process the
+ orders. You can have your old client put messages in JBossMQ as normal,
+ but you set the bridge up to pull the messages from JBossMQ Order queue
+ and push them into the JBM Order queue.</para>
+
+ <para>This allows JBM and JBossMQ to interact together by pushing messages
+ back and forth between different systems.</para>
+
+ <para>The Following Assumptions are made:</para>
+
+ <itemizedlist>
+ <listitem>You have one JBoss instance set up for JBoss Messaging and One
+ Jboss instance set up that has your old JBoss MQ on it.</listitem>
+
+ <listitem>We are copying messages from JBossMQ(Source) to
+ JBM(Target)</listitem>
+ </itemizedlist>
+
+ <section id="inst.mqmessagemigration.steps">
+ <title>Steps to Set up the bridge</title>
+
<itemizedlist>
- <listitem>You have one JBoss instance set up for JBoss Messaging and One Jboss instance set up that has your old JBoss MQ on it.</listitem>
- <listitem>We are copying messages from JBossMQ(Source) to JBM(Target)</listitem>
- </itemizedlist>
- <section id="inst.mqmessagemigration.steps">
- <title>Steps to Set up the bridge</title>
- <itemizedlist>
- <listitem>
- <para>Copy the jbossmq.jar from the Source Machine(JBossMQ) under the server/default/lib/ to the
- messaging configuration on the Target JBM machine(server/messaging/lib)</para>
- <note>substitute what ever your messaging server configuration is above. I used the default stand alone
- messaging server configuration note: This is required to dereference the JBossMQ objects that are
- dereferenced on the JBM side. If you don't copy the jar over, you will get a
- "java.lang.ClassCastException: javax.naming.Reference" exception and the bridge will not be able to start</note>
- </listitem>
- <listitem><para>Add the remote JBossMQ provider to the jms-ds.xml file in the server/messaging/deploy
- directory on your target(JBM) machine.</para>
- <para>Here is an example of the provider to add.</para>
- <programlisting>
+ <listitem>
+ <para>Copy the jbossmq.jar from the Source Machine(JBossMQ) under
+ the server/default/lib/ to the messaging configuration on the Target
+ JBM machine(server/messaging/lib)</para>
+
+ <note>substitute what ever your messaging server configuration is
+ above. I used the default stand alone messaging server configuration
+ note: This is required to dereference the JBossMQ objects that are
+ dereferenced on the JBM side. If you don't copy the jar over, you
+ will get a "java.lang.ClassCastException: javax.naming.Reference"
+ exception and the bridge will not be able to start</note>
+ </listitem>
+
+ <listitem>
+ <para>Add the remote JBossMQ provider to the jms-ds.xml file in the
+ server/messaging/deploy directory on your target(JBM)
+ machine.</para>
+
+ <para>Here is an example of the provider to add.</para>
+
+ <programlisting>
<mbean code="org.jboss.jms.jndi.JMSProviderLoader"
name="jboss.messaging:service=JMSProviderLoader,
name=MyRemoteJMSProvider">
@@ -1020,15 +1050,21 @@
</attribute>
</mbean>
</programlisting>
- <note>you will need to change the java.naming.provider.url so that it points to your JBossMQ machine.
- Everything else should remain the same. Keep your jms-ds.xml file open, because you will be addning
- another entry in it for the next step.</note>
- </listitem>
- <listitem>
- <para>Add the Bridge provider to the jms-ds.xml file in the server/messaging/deploy directory on your
- target(JBM) machine.</para>
- <para>Here is an example bridge configuration</para>
- <programlisting>
+
+ <note>you will need to change the java.naming.provider.url so that
+ it points to your JBossMQ machine. Everything else should remain the
+ same. Keep your jms-ds.xml file open, because you will be addning
+ another entry in it for the next step.</note>
+ </listitem>
+
+ <listitem>
+ <para>Add the Bridge provider to the jms-ds.xml file in the
+ server/messaging/deploy directory on your target(JBM)
+ machine.</para>
+
+ <para>Here is an example bridge configuration</para>
+
+ <programlisting>
<mbean code="org.jboss.jms.server.bridge.BridgeService"
name="jboss.messaging:service=Bridge,name=TestBridge"
xmbean-dd="xmdesc/Bridge-xmbean.xml">
@@ -1048,20 +1084,30 @@
<attribute name="AddMessageIDInHeader">false</attribute>
</mbean>
</programlisting>
- <note>my target is the current JBM JMS Provider and the source is the JBossMQ remote provider. If you
- have a pretty stock system and you want to move messages from JBossMQ to JBM, you will not have to
- change this example except for the queue Names. If you wish to move from JBM to JBossMQ, just switch
- the soure and target definitions.</note>
- </listitem>
- </itemizedlist>
- <para>Start the JBossMQ system and then just start the JBM system and the messages will begin to move over.</para>
- <para>The following is an example of the jms-ds.xml file that was used for the test. If you want to test the bridge first
- and you have a stock JBM system(JBM has been installed using the default configuration), then you can just
- copy the jms-ds.xml file over the one in server/messaging/deploy and begin to put messages in the JBossMQ
- system under the /queue/TestQueue. The messages will then be moved over to your JBM queue /queue/A. Both of
- these queues exist in the stock versions of JBM and JBossMQ.</para>
- </section>
- <programlisting>
+
+ <note>my target is the current JBM JMS Provider and the source is
+ the JBossMQ remote provider. If you have a pretty stock system and
+ you want to move messages from JBossMQ to JBM, you will not have to
+ change this example except for the queue Names. If you wish to move
+ from JBM to JBossMQ, just switch the soure and target
+ definitions.</note>
+ </listitem>
+ </itemizedlist>
+
+ <para>Start the JBossMQ system and then just start the JBM system and
+ the messages will begin to move over.</para>
+
+ <para>The following is an example of the jms-ds.xml file that was used
+ for the test. If you want to test the bridge first and you have a stock
+ JBM system(JBM has been installed using the default configuration), then
+ you can just copy the jms-ds.xml file over the one in
+ server/messaging/deploy and begin to put messages in the JBossMQ system
+ under the /queue/TestQueue. The messages will then be moved over to your
+ JBM queue /queue/A. Both of these queues exist in the stock versions of
+ JBM and JBossMQ.</para>
+ </section>
+
+ <programlisting>
<?xml version="1.0" encoding="UTF-8"?>
<connection-factories>
@@ -1164,7 +1210,9 @@
</connection-factories>
</programlisting>
- <para>You can also merge topics back and forth from JBM to JBossMQ, by setting the subscription name and client id.
- You can see these arguments in the JBM Bridge chapter. </para>
- </section>
+
+ <para>You can also merge topics back and forth from JBM to JBossMQ, by
+ setting the subscription name and client id. You can see these arguments
+ in the JBM Bridge chapter.</para>
+ </section>
</chapter>
\ No newline at end of file
Modified: branches/Branch_1_4/docs/userguide/en/modules/recovery_config.xml
===================================================================
--- branches/Branch_1_4/docs/userguide/en/modules/recovery_config.xml 2008-09-22 18:18:43 UTC (rev 5004)
+++ branches/Branch_1_4/docs/userguide/en/modules/recovery_config.xml 2008-09-22 19:40:34 UTC (rev 5005)
@@ -1,17 +1,22 @@
<?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>
+ <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?
@@ -31,22 +36,27 @@
</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>
- <para>Please note that to configure the recovery manager to recovery
- transactions from any node of the cluster it will be necessary to specify a
- line in the configuration for every node of the cluster</para>
+
+ <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>
+
+ <para>Please note that to configure the recovery manager to recovery
+ transactions from any node of the cluster it will be necessary to specify a
+ line in the configuration for every node of the cluster</para>
</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list