第27章 Configuring JMS Bridges
JBoss EAP messaging includes a fully functional JMS message bridge. The function of a JMS 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.
If the source destination is a topic, the JMS bridge creates a subscription for it. If the client-id and subscription-name attributes are configured for the JMS bridge, the subscription is durable. This means that no messages are missed if the JMS bridge is stopped and then restarted.
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.
Do not confuse a JMS bridge with a core bridge. A JMS bridge can be used to bridge any two JMS 1.1 compliant JMS providers and uses the JMS API. A core bridge is used to bridge any two JBoss EAP messaging instances and uses the core API. It is preferable to use a core bridge instead of a JMS bridge whenever possible.
Below is an example configuration of a JBoss EAP JMS bridge.
<subsystem xmlns="urn:jboss:domain:messaging-activemq:4.0">
<server name="default">
...
</server>
<jms-bridge name="my-jms-bridge" module="org.apache.activemq.artemis" max-batch-time="100" max-batch-size="10" max-retries="1" failure-retry-interval="500" quality-of-service="AT_MOST_ONCE">
<source destination="jms/queue/InQueue" connection-factory="ConnectionFactory">
<source-context/>
</source>
<target destination="jms/queue/OutQueue" connection-factory="jms/RemoteConnectionFactory">
<target-context>
<property name="java.naming.factory.initial" value="org.wildfly.naming.client.WildFlyInitialContextFactory"/>
<property name="java.naming.provider.url" value="http-remoting://192.168.40.1:8080"/>
</target-context>
</target>
</jms-bridge>
...
</subsystem>Adding a JMS Bridge Using the Management CLI
A JMS bridge can be added using the following management CLI command. Note that the source and target destinations must already be defined in the configuration. See the table in the appendix for a full list of configurable attributes.
/subsystem=messaging-activemq/jms-bridge=my-jms-bridge:add(quality-of-service=AT_MOST_ONCE,module=org.apache.activemq.artemis,failure-retry-interval=500,max-retries=1,max-batch-size=10,max-batch-time=100,source-connection-factory=ConnectionFactory,source-destination=jms/queue/InQueue,source-context={},target-connection-factory=jms/RemoteConnectionFactory,target-destination=jms/queue/OutQueue,target-context={java.naming.factory.initial=org.wildfly.naming.client.WildFlyInitialContextFactory,java.naming.provider.url=http-remoting://192.168.40.1:8080})
You can review the configuration of a JMS bridge using the read-resource command in the management CLI as in the following example.
/subsystem=messaging-activemq/jms-bridge=my-jms-bridge:read-resource
Add configuration to a JMS bridge by using the write-attribute, as done in this example:
/subsystem=messaging-activemq/jms-bridge=my-jms-bridge:write-attribute(name=ATTRIBUTE,value=VALUE)
Adding a JMS Bridge Using the Management Console
You can also use the management console to add a JMS bridge by following these steps.
-
Open the management console in a browser and navigate to Configuration
Subsystems Messaging (ActiveMQ) JMS Bridge. - Click the Add (+) button and provide the required information when prompted.
- Click Add when finished.
27.1. Quality of Service
In JBoss EAP, quality-of-service is a configurable attribute that determines how messages are consumed and acknowledged. The valid values for quality-of-service and their descriptions are below. See the table in the appendix for a full list of JMS bridge attributes.
- AT_MOST_ONCE
Messages will reach the destination from the source at the most one time. The messages are consumed from the source and acknowledged before sending to the destination. Therefore, there is a possibility that messages could be lost if a failure occurs between their removal from the source and their arrival at the destination. This mode is the default value.
This mode is available for both durable and non-durable messages.
- DUPLICATES_OK
Messages are consumed from the source and then acknowledged after they have been successfully sent to the destination. Therefore, there is a possibility that messages could be sent again if a failure occurs after the initial message was sent but before it is acknowledged.
This mode is available for both durable and non-durable messages.
- ONCE_AND_ONLY_ONCE
Messages will reach the destination from the source once and only once. If both the source and the destination are on the same server instance, 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 a JTA Transaction Manager which will need to be set using the
setTransactionManager()method on the bridge.This mode is only available for durable messages.
警告When shutting down a server that has a deployed JMS bridge with the
quality-of-serviceattribute set toONCE_AND_ONLY_ONCE, be sure to shut the server down with the JMS bridge first to avoid unexpected errors.
It may possible to provide once and only once semantics by using the DUPLICATES_OK mode instead of ONCE_AND_ONLY_ONCE and then checking for duplicates at the destination and discarding them. See Configuring Duplicate Message Detection for more information. However, the cache would only be valid for a certain period of time. This approach therefore is not as watertight as using ONCE_AND_ONLY_ONCE, but it may be a good choice depending on your specific application needs.
27.2. Timeouts and the JMS Bridge
There is a possibility that the target or source server will not be available at some point in time. If this occurs, the bridge will try to reconnect a number of times equal to the value of max-retries. The wait between attempts is set by failure-retry-interval.
Because each JMS bridge has its own max-retries parameter, you should use a connection factory that does not set the reconnect-attempts parameter, or sets it to 0. This will avoid a potential collision that may result in longer reconnection times. Also note that any connection factory referenced by a JMS bridge with the quality-of-service set to ONCE_AND_ONLY_ONCE needs to have the factory-type set to XA_GENERIC, XA_TOPIC, or XA_QUEUE.
