Red Hat Training

A Red Hat training course is available for Red Hat Fuse

3.4. Configuring How Replies are Sent

If your endpoint is participating in in/out message exchanges, or exceptions need to be returned to the external endpoint, you need to configure how your endpoint will handle the reply messages. You can configure the JMS destination used to send the reply and how the endpoint specifies the reply message's correlation ID. In addition, you can specify a number of QoS settings including:
  • the reply message's priority
  • the reply message's persistence
  • the reply message's lifespan
You can also specify a number of custom properties to place in a reply message's JMS header.

3.4.1. Configuring the Reply Destination

Overview

Red Hat JBoss Fuse JMS consumers determine destination of reply messages and exceptions uses a straightforward algorithm. By default, the reply destination is supplied by the message that started the exchange. If the reply destination cannot be determined from the request message, the endpoint will use a number of strategies to determine the reply destination.
You can customize how the endpoint determines the reply destination using the endpoint's configuration. You can also supply fall back values for the endpoint to use.

Determining the reply destination

Consumer endpoints use the following algorithm to determine the reply destination for a message exchange:
  1. If the in message of the exchange includes a value for the JMSReplyTo property, that value is used as the reply destination.
  2. If the JMSReplyTo is not specified, the endpoint looks for a destination chooser implementation to use.
    If you have configured your endpoint with a destination chooser, the endpoint will use the destination chooser to select the reply destination.
    For more information on using destination choosers see Section 7.1, “Using a Custom Destination Chooser”.
  3. If the JMSReplyTo is not specified and there is no configured destination chooser, the endpoint checks its replyDestination attribute for a destination.
    You configure a destination using a Spring bean. The recommend method to configure the destination is to configure the bean separately and refer the bean using the endpoint's replyDestination attribute as shown in Example 3.11, “Configuring a Consumer's Reply Destination”. You can also add the bean directly to the endpoint by wrapping it in a jms:replyDestination child element.
  4. As a last resort, the endpoint will use the value of the replyDestinationName attribute to determine the reply destination.
    The replyDestinationName attribute takes a string that is used as the name of the destination to use. The binding component's default behavior when you provide a destination name is to resolve the destination using the standard JMS Session.createTopic() and Session.createTopic() methods to resolve the JMS destination.
    Note
    You can override the binding component's default behavior by providing a custom DestinationResolver implementation. See Section 7.2, “Using a Custom Destination Resolver”.

Example

Example 3.11, “Configuring a Consumer's Reply Destination” shows an example of configuring a consumer endpoint to use a dedicated JMS destination.

Example 3.11. Configuring a Consumer's Reply Destination

<beans xmlns:jms="http://servicemix.apache.org/jms/1.0"
       ... >
  ...
  <jms:consumer service="my:widgetService"
                endpoint="jbiWidget"
                destinationName="my.widgetQueue"
                connectionFactory="#connectionFactory"
                replyDestination="#widgetReplyQueue" />
  ...
  <jee:jndi-lookup id="widgetReplyQueue" jndi-name="my.widget.reply.queue">
    <jee:environment>
      java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory
      java.naming.provider.url=t3://localhost:7001
    </jee:environment>
  </jee:jndi-lookup>
  ...
</beans>

3.4.2. Configuring the Qualities of Service

Overview

You can specify a number of the reply message's QoS settings including:
  • the reply message's priority
  • the reply message's persistence
  • the reply message's lifespan
These properties are stored in the JMS message header. By default, the JMS broker automatically populates their values. You can, however, configure an endpoint to override the broker's default.

Setting the reply message's priority

JMS uses a priority system to determine the relative importance of delivering a message. Messages with higher priority are delivered before messages with a lower priority.
You configure the priority of the reply message messages by setting the consumer's replyPriority attribute. The value is used to set the reply message's JMSPriority property.
JMS supports priority values between 0 and 9. The lowest priority is 0 and the highest priority is 9. The default priority for a message is 4.

Setting the reply message's persistence

JMS uses a message's delivery mode to determine its persistence in the system. You can set the delivery mode for the reply messages sent by an endpoint by setting the endpoint's replyDeliveryMode attribute. The value you provide for the replyDeliveryMode attribute is used to set the reply message's JMSDeliveryMode property.
JMS implementations support two delivery modes: persistent and non-persistent.
Persistent messages can survive a shutdown of the JMS broker. This is the default setting for JMS messages. You can specify persistence by setting the endpoint's deliveryMode attribute to 2. This setting corresponds to DeliveryMode.PERSISTENT.
Non-persistent messages are lost if the JMS broker is shutdown before they are delivered. You can specify non-persistence by setting the endpoint's deliveryMode attribute to 1. This setting corresponds to DeliveryMode.NON_PERSISTENT.

Setting a reply message's lifespan

You can control how long reply messages live before the JMS broker reap them by setting the endpoint's replyTimeToLive attribute. The value is the number of milliseconds you want the message to be available from the time it is sent.
The value of the replyTimeToLive attribute is used to compute the value for the reply message's JMSExpirary property. The value is computed by adding the specified number of milliseconds to the time the message is created.
The default behavior is to allow messages to persist forever.

Enforcing the configured values

By default, the consumer ignores these settings and allows the JMS provider to insert its own default values for the reply message's QoS settings. To force your settings to be used, you need to set the endpoint's replyExplicitQosEnabled to true. Doing so instructs the consumer to always use the values provided in the configuration.

Example

Example 3.12, “Consumer with Reply QoS Properties” shows the configuration for a consumer whose reply messages are set to have low priority and to be non-persistent.

Example 3.12. Consumer with Reply QoS Properties

<beans xmlns:jms="http://servicemix.apache.org/jms/1.0"
       ... >
  ...
  <jms:jca-consumer service="my:widgetService"
                endpoint="jbiWidget"
                connectionFactory="#connectionFactory"
                destinationName="widgetQueue"
                resourceAdapter="#ra"
                activationSpec="#as"
                replyExplicitQosEnabled="true"
                replyDeliveryMode="1"
                replyPriority="0" />
  ...
</beans>

3.4.3. Setting Custom JMS Properties

Overview

The JMS specification allows for the placing of custom properties into a message's header. These custom properties are specified as a set of name/value pairs that can store both simple types and Java objects. The properties can be used for a number of tasks including message selection.
When using the Red Hat JBoss Fuse JMS binding component, you define the custom properties added to the reply messages as property map. This is done using the Spring map element. You can configure one static map that will be applied to every reply message generated by the consumer.

Setting custom JMS header properties

You can configure a consumer to add custom properties to reply messages in one of two ways:
  1. Use the endpoint's replyProperties attribute to refer to the property map defining the custom properties.
  2. Add a jms:replyProperties child element to the endpoint. The jms:replyProperties element wraps the property map.

Defining the property map

The property map containing the custom properties you want added to the reply messages is stored in a java.util.Map object. You define that map object using the Spring util:map element.
The util:map element is defined in the http://www.springframework.org/schema/util namespace. In order to use the element you will need to add the following namespace alias to your beans element:
xmlns:util="http://www.springframework.org/schema/util"
The entries in the map are defined by adding entry child element's to the util:map element. Each entry element takes two attributes. The key entry is the map key and corresponds to the properties name. The value attribute is the value of the property.
Tip
If you want the value of a property to be complex type that is stored in a Java object, you can use the entry element's ref attribute instead of the value attribute. The ref attribute points to another bean element that defines a Java object.

Example

Example 3.13, “Adding Custom Properties to a Reply Message” shows an example of a SOAP consumer whose reply messages have a set of custom properties added to their header.

Example 3.13. Adding Custom Properties to a Reply Message

<beans xmlns:jms="http://servicemix.apache.org/jms/1.0"
       xmlns:util="http://www.springframework.org/schema/util"
       ... >
  ...
  <jms:consumer service="my:widgetService"
                endpoint="jbiWidget"
                destinationName="my.widgetQueue"
                connectionFactory="#connectionFactory"
                replyDestination="#widgetReplyQueue"
                replyProperties="#jmsProps" />
  ...
  <util:map id="jmsProps">
    <entry key="location" value="San Jose"/>
    <entry key="orig_code" value="sjwf"/>
    <entry key="client_code" value="widget010"/>
  </util:map>
  ...
</beans>