Name

JMS — allows message to be sent to or consumed from JMS destinations

Overview

The JMS component allows messages to be sent to (or consumed from) a JMS destination. The implementation of the JMS Component uses Spring's JMS support for declarative transactions, using Spring's JmsTemplate for sending and a MessageListenerContainer for consuming.

[Note]Note

If you are using Red Hat JBoss A-MQ, use the ActiveMQ endpoint; it has been optimized for Red Hat JBoss A-MQ.

URI format

The URI format for a JMS endpoint is:

jms:[temp:][queue:|topic:]destinationName[?options]

Options

Table 31, “JMS options” lists the options for a JMS endpoint.

[Note]Note

Many of these properties map to properties on Spring JMS, which Apache Camel uses for sending and receiving messages. You can get more information about these properties by consulting the relevant Spring documentation.

Table 31. JMS options

OptionDefaultDescription
acceptMessagesWhileStoppingfalseSpecifies whether the consumer accept messages while it is stopping.
acknowledgementModeNameAUTO_ACKNOWLEDGE

Specifies the JMS acknowledgement mode. Valid values are:

  • TRANSACTED

  • CLIENT_ACKNOWLEDGE

  • AUTO_ACKNOWLEDGE

  • DUPS_OK_ACKNOWLEDGE

acknowledgementMode-1Specifies the JMS acknowledgement mode defined as an integer. Allows you to set vendor-specific extensions to the acknowledgment mode. For the regular modes, it is preferable to use the acknowledgementModeName instead.
alwaysCopyMessagefalseSpecifies if Apache Camel will make a JMS message copy of the message when it is passed to the producer for sending.
asyncStartListenerfalse

Specifies whether to startup the JmsConsumer message listener asynchronously when starting a route.

For example, when a JmsConsumer cannot get a connection to a remote JMS broker, it may block while retrying or failover. Either causes Camel to block while starting routes.

Setting this option to true enables routes to startup while the JmsConsumer uses a dedicated thread in asynchronous mode to connect to the JMS broker. Note that if the connection fails, it generates an exception logged at WARN level, and the consumer will not receive messages. You can restart the route to try connecting.

asyncStopListenerfalseSpecifies whether to stop the JmsConsumer message listener asynchronously when stopping a route.
autoStartuptrueSpecifies whether the consumer container should auto-startup.
cacheLevelNameCACHE_CONSUMER

Specifies the cache level by name for the underlying JMS resources. Possible values are:

  • CACHE_AUTO

  • CACHE_CONNECTION

  • CACHE_CONSUMER

  • CACHE_NONE

  • CACHE_SESSION

cacheLevel-1Specifies the cache level by ID for the underlying JMS resources.
clientIdnullSpecifies the JMS client ID to use. This value, if specified, must be unique and can only be used by a single JMS connection instance. It is typically only required for durable topic subscriptions.
consumerTypeDefault

Specifies the consumer type to use. Valid values are one of:

  • Simple

  • Default

  • ServerSessionPool

The consumer type determines which Spring JMS listener to use.

concurrentConsumers 1 Specifies the default number of concurrent consumers.
connectionFactory null Specifies the default JMS connection factory to use for the listenerConnectionFactory and templateConnectionFactory, if neither is specified.
deliveryMode 2 Specifies the delivery mode when sending messages. 1 = non-persistent; 2 = persistent.
deliveryPersistent true Specifies whether persistent delivery is used by default.
destination null Specifies the JMS Destination object to use on this endpoint.
destinationName null Specifies the JMS destination name to use on this endpoint.
destinationResolver null Specifies an implementation of the Spring framework's DestinationResolver to use.
disableReplyTo false Specifies whether to ignore the JMSReplyTo header and treat messages as InOnly by default.
durableSubscriptionName null Specifies the durable subscriber name for specifying durable topic subscriptions. The clientId option must be configured as well.
eagerLoadingOfProperties false Enables eager loading of JMS properties as soon as a message is received.
exceptionListener null Specifies the JMS Exception Listener that is to be notified of any underlying JMS exceptions.
explicitQosEnabledfalseSpecifies whether the deliveryMode, priority or timeToLive qualities of service should be used when sending messages.
exposeListenerSession true Specifies whether the listener session should be exposed when consuming messages.
idleTaskExecutionLimit 1 Specifies the limit for idle executions of a receive task, not having received any message within its execution. If this limit is reached, the task will shut down and leave receiving to other executing tasks.
jmsMessageType null

Forces the use of a specific javax.jms.Message implementation for sending JMS messages. Possible values are:

  • Bytes

  • Map

  • Object

  • Stream

  • Text

jmsKeyFormatStrategy default

Specifies a pluggable strategy for encoding and decoding JMS keys so they can be compliant with the JMS specification. Apache Camel provides two implementations out of the box:

  • default

  • passthrough

jmsOperations null Specifies an implementation of the Spring Framework's JmsOperations interface to use in place of JmsTemplate.
lazyCreateTransactionManager true Specifies if Apache Camel will create a JmsTransactionManager when no transactionManager injected when transacted=true.
listenerConnectionFactory null Specifies the JMS connection factory used for consuming messages.
mapJmsMessagetrueSpecifies whether Apache Camel should auto map the received JMS message to an appropriate payload type, such as javax.jms.TextMessage to a String etc.
maxConcurrentConsumers1 Specifies the maximum number of concurrent consumers.
maxMessagesPerTask-1 (unlimited)Specifies the maximum number of messages per task.
messageConverternullSpecifies a custom implementation of the Spring MessageConverter so you can control how to map to/from a javax.jms.Message.
messageIdEnabled true Specifies whether message IDs should be added to outgoing messages.
messageTimestampEnabledtrue Specifies whether timestamps should be enabled by default on sending messages.
password null Specifies the password for the connector factory.
priority 4 Specifies the priority of outgoing messages. The explicitQosEnabled option must also be enabled in order for this option to have any effect.
pubSubNoLocal false Specifies whether to inhibit the delivery of messages published by its own connection.
receiveTimeout Specifies the timeout for receiving messages (in milliseconds).
recoveryInterval 5000 Specifies the interval between recovery attempts, in milliseconds.
preserveMessageQos false Specifies if you want to send message using the QoS settings specified on the message instead of the QoS settings on the JMS endpoint. The following three headers are considered: JMSPriority, JMSDeliveryMode, and JMSExpiration.
replyTo null Specifies an explicit ReployTo destination, which overrides any incoming value of Message.getJMSReplyTo().
replyToCacheLevelName CACHE_CONSUMER

Sets the cache level by name for the reply consumer when doing request-reply over JMS. This option applies only when using fixed (not temporary) reply queues. By default, Camel uses CACHE_CONSUMER for exclusive or shared with replyToSelectorName and CACHE_SESSION for shared without replyToSelectorName.

Some JMS brokers, such as IBM WebSphere, may require this option be set to CACHE_NONE.

replyToDestinationSelectorName null Specifies the JMS Selector using the fixed name to be used so you can filter out your own replies from the others when using a shared queue (that is, if you are not using a temporary reply queue).
replyToDeliveryPersistent true Specifies whether to use persistent delivery by default for replies.
requestTimeout 20000 Specifies the timeout, in milliseconds, to wait for a reply when using the InOut Exchange Pattern.
requestTimeoutCheckerInterval 1000

Specifies how often, in milliseconds, Camel should check for time out exchanges when doing request-reply over JMS. The default is one second, but if your application must react faster to timeouts, decrease this interval to have Camel check more frequently.

The option requestTimeout determines the timeout.

selector null Specifies the JMS Selector, which is an SQL 92 predicate that is used to filter messages within the broker.
taskExecutor null Specifies a custom task executor for consuming messages.
taskExecutorSpring2 null Specifies a custom task executor for consuming messages when using Spring 2.x.
templateConnectionFactory null Specifies the JMS connection factory used for sending messages.
timeToLive null Specifies the time-to-live of the message in milliseconds. The explicitQosEnabled option must also be enabled in order for this option to have any effect.
transacted false Specifies whether to use transacted mode for sending/receiving messages using the InOnly Exchange Pattern.
transactionManager null Specifies the Spring transaction manager to use.
transactionName null Specifies the name of the transaction to use.
transactionTimeout null Specifies the timeout value of the transaction.
transferException false Specifies if enabled an exception thrown by a client during processing is returned as the response message.
transferExchange false Specifies if the exchange is transmitted over the wire instead of just the body and headers. The following fields are transferred: In body, Out body, Fault body, In headers, Out headers, Fault headers, exchange properties, exchange exception.
username null Specifies the username for the connector factory.
useMessageIDAsCorrelationID false Specifies whether JMSMessageID should always be used as JMSCorrelationID for InOut messages.

Message mapping

Apache Camel automatically maps messages between javax.jms.Message and org.apache.camel.Message.

When sending a JMS message, Apache Camel converts the message body to the JMS message types shown in Table 32, “Mapping from Apache Camel to JMS” .

Table 32. Mapping from Apache Camel to JMS

Body TypeJMS Message
Stringjavax.jms.TextMessage
org.w3c.dom.Node javax.jms.TextMessage
Map javax.jms.MapMessage
java.io.Serializable javax.jms.ObjectMessage
byte[]javax.jms.BytesMessage
java.io.File javax.jms.BytesMessage
java.io.Reader javax.jms.BytesMessage
java.io.InputStream javax.jms.BytesMessage
java.nio.ByteBuffer javax.jms.BytesMessage

When receiving a JMS message, Apache Camel converts the JMS message to body type listed in Table 33, “Mapping from JMS to Apache Camel”.

Table 33. Mapping from JMS to Apache Camel

JMS MessageBody Type
javax.jms.TextMessageString
javax.jms.BytesMessagebyte[]
javax.jms.MapMessageMap<String, Object>
javax.jms.ObjectMessageObject

Related topics

ActiveMQ
AMQP