[[jms-namespace]]
= JMS Namespace Support

Spring provides an XML namespace for simplifying JMS configuration. To use the JMS
namespace elements, you need to reference the JMS schema, as the following example shows:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<?xml version="1.0" encoding="UTF-8"?>
	<beans xmlns="http://www.springframework.org/schema/beans"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xmlns:jms="http://www.springframework.org/schema/jms" <1>
		xsi:schemaLocation="
			http://www.springframework.org/schema/beans
			https://www.springframework.org/schema/beans/spring-beans.xsd
			http://www.springframework.org/schema/jms
			https://www.springframework.org/schema/jms/spring-jms.xsd">

		<!-- bean definitions here -->

	</beans>
----
<1> Referencing the JMS schema.


The namespace consists of three top-level elements: `<annotation-driven/>`, `<listener-container/>`
and `<jca-listener-container/>`. `<annotation-driven/>` enables the use of xref:integration/jms/annotated.adoc[annotation-driven listener endpoints]
. `<listener-container/>` and `<jca-listener-container/>`
define shared listener container configuration and can contain `<listener/>` child elements.
The following example shows a basic configuration for two listeners:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<jms:listener-container>

		<jms:listener destination="queue.orders" ref="orderService" method="placeOrder"/>

		<jms:listener destination="queue.confirmations" ref="confirmationLogger" method="log"/>

	</jms:listener-container>
----

The preceding example is equivalent to creating two distinct listener container bean
definitions and two distinct `MessageListenerAdapter` bean definitions, as shown
in xref:integration/jms/receiving.adoc#jms-receiving-async-message-listener-adapter[Using `MessageListenerAdapter`]. In addition to the attributes shown
in the preceding example, the `listener` element can contain several optional ones.
The following table describes all of the available attributes:

[[jms-namespace-listener-tbl]]
.Attributes of the JMS <listener> element
[cols="1,6"]
|===
| Attribute | Description

| `id`
| A bean name for the hosting listener container. If not specified, a bean name is
  automatically generated.

| `destination` (required)
| The destination name for this listener, resolved through the `DestinationResolver`
  strategy.

| `ref` (required)
| The bean name of the handler object.

| `method`
| The name of the handler method to invoke. If the `ref` attribute points to a `MessageListener`
  or Spring `SessionAwareMessageListener`, you can omit this attribute.

| `response-destination`
| The name of the default response destination to which to send response messages. This is
  applied in case of a request message that does not carry a `JMSReplyTo` field. The
  type of this destination is determined by the listener-container's
  `response-destination-type` attribute. Note that this applies only to a listener method with a
  return value, for which each result object is converted into a response message.

| `subscription`
| The name of the durable subscription, if any.

| `selector`
| An optional message selector for this listener.

| `concurrency`
| The number of concurrent sessions or consumers to start for this listener. This value can either be
  a simple number indicating the maximum number (for example, `5`) or a range indicating the lower
  as well as the upper limit (for example, `3-5`). Note that a specified minimum is only a hint
  and might be ignored at runtime. The default is the value provided by the container.
|===

The `<listener-container/>` element also accepts several optional attributes. This
allows for customization of the various strategies (for example, `taskExecutor` and
`destinationResolver`) as well as basic JMS settings and resource references. By using
these attributes, you can define highly-customized listener containers while
still benefiting from the convenience of the namespace.

You can automatically expose such settings as a `JmsListenerContainerFactory` by
specifying the `id` of the bean to expose through the `factory-id` attribute,
as the following example shows:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<jms:listener-container connection-factory="myConnectionFactory"
			task-executor="myTaskExecutor"
			destination-resolver="myDestinationResolver"
			transaction-manager="myTransactionManager"
			concurrency="10">

		<jms:listener destination="queue.orders" ref="orderService" method="placeOrder"/>

		<jms:listener destination="queue.confirmations" ref="confirmationLogger" method="log"/>

	</jms:listener-container>
----

The following table describes all available attributes. See the class-level javadoc
of the {spring-framework-api}/jms/listener/AbstractMessageListenerContainer.html[`AbstractMessageListenerContainer`]
and its concrete subclasses for more details on the individual properties. The javadoc
also provides a discussion of transaction choices and message redelivery scenarios.

[[jms-namespace-listener-container-tbl]]
.Attributes of the JMS <listener-container> element
[cols="1,6"]
|===
| Attribute | Description

| `container-type`
| The type of this listener container. The available options are `default`, `simple`,
  `default102`, or `simple102` (the default option is `default`).

| `container-class`
| A custom listener container implementation class as a fully qualified class name.
  The default is Spring's standard `DefaultMessageListenerContainer` or
  `SimpleMessageListenerContainer`, according to the `container-type` attribute.

| `factory-id`
| Exposes the settings defined by this element as a `JmsListenerContainerFactory`
  with the specified `id` so that they can be reused with other endpoints.

| `connection-factory`
| A reference to the JMS `ConnectionFactory` bean (the default bean name is
  `connectionFactory`).

| `task-executor`
| A reference to the Spring `TaskExecutor` for the JMS listener invokers.

| `destination-resolver`
| A reference to the `DestinationResolver` strategy for resolving JMS `Destination` instances.

| `message-converter`
| A reference to the `MessageConverter` strategy for converting JMS Messages to listener
  method arguments. The default is a `SimpleMessageConverter`.

| `error-handler`
| A reference to an `ErrorHandler` strategy for handling any uncaught exceptions that
  may occur during the execution of the `MessageListener`.

| `destination-type`
| The JMS destination type for this listener: `queue`, `topic`, `durableTopic`, `sharedTopic`,
  or `sharedDurableTopic`. This potentially enables the `pubSubDomain`, `subscriptionDurable`
  and `subscriptionShared` properties of the container. The default is `queue` (which disables
  those three properties).

| `response-destination-type`
| The JMS destination type for responses: `queue` or `topic`. The default is the value of the
  `destination-type` attribute.

| `client-id`
| The JMS client ID for this listener container. You must specify it when you use
  durable subscriptions.

| `cache`
| The cache level for JMS resources: `none`, `connection`, `session`, `consumer`, or
  `auto`. By default (`auto`), the cache level is effectively `consumer`, unless
  an external transaction manager has been specified -- in which case, the effective
  default will be `none` (assuming Jakarta EE-style transaction management, where the given
  ConnectionFactory is an XA-aware pool).

| `acknowledge`
| The native JMS acknowledge mode: `auto`, `client`, `dups-ok`, or `transacted`. A value
  of `transacted` activates a locally transacted `Session`. As an alternative, you can specify
  the `transaction-manager` attribute, described later in table. The default is `auto`.

| `transaction-manager`
| A reference to an external `PlatformTransactionManager` (typically an XA-based
  transaction coordinator, such as Spring's `JtaTransactionManager`). If not specified,
  native acknowledging is used (see the `acknowledge` attribute).

| `concurrency`
| The number of concurrent sessions or consumers to start for each listener. It can either be
  a simple number indicating the maximum number (for example, `5`) or a range indicating the
  lower as well as the upper limit (for example, `3-5`). Note that a specified minimum is just a
  hint and might be ignored at runtime. The default is `1`. You should keep concurrency limited to `1` in
  case of a topic listener or if queue ordering is important. Consider raising it for
  general queues.

| `prefetch`
| The maximum number of messages to load into a single session. Note that raising this
  number might lead to starvation of concurrent consumers.

| `receive-timeout`
| The timeout (in milliseconds) to use for receive calls. The default is `1000` (one
  second). `-1` indicates no timeout.

| `back-off`
| Specifies the `BackOff` instance to use to compute the interval between recovery
  attempts. If the `BackOffExecution` implementation returns `BackOffExecution#STOP`,
  the listener container does not further try to recover. The `recovery-interval`
  value is ignored when this property is set. The default is a `FixedBackOff` with
  an interval of 5000 milliseconds (that is, five seconds).

| `recovery-interval`
| Specifies the interval between recovery attempts, in milliseconds. It offers a convenient
  way to create a `FixedBackOff` with the specified interval. For more recovery
  options, consider specifying a `BackOff` instance instead. The default is 5000 milliseconds
  (that is, five seconds).

| `phase`
| The lifecycle phase within which this container should start and stop. The lower the
  value, the earlier this container starts and the later it stops. The default is
  `Integer.MAX_VALUE`, meaning that the container starts as late as possible and stops as
  soon as possible.
|===

Configuring a JCA-based listener container with the `jms` schema support is very similar,
as the following example shows:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<jms:jca-listener-container resource-adapter="myResourceAdapter"
			destination-resolver="myDestinationResolver"
			transaction-manager="myTransactionManager"
			concurrency="10">

		<jms:listener destination="queue.orders" ref="myMessageListener"/>

	</jms:jca-listener-container>
----

The following table describes the available configuration options for the JCA variant:

[[jms-namespace-jca-listener-container-tbl]]
.Attributes of the JMS <jca-listener-container/> element
[cols="1,6"]
|===
| Attribute | Description

| `factory-id`
| Exposes the settings defined by this element as a `JmsListenerContainerFactory`
  with the specified `id` so that they can be reused with other endpoints.

| `resource-adapter`
| A reference to the JCA `ResourceAdapter` bean (the default bean name is
  `resourceAdapter`).

| `activation-spec-factory`
| A reference to the `JmsActivationSpecFactory`. The default is to autodetect the JMS
  provider and its `ActivationSpec` class (see {spring-framework-api}/jms/listener/endpoint/DefaultJmsActivationSpecFactory.html[`DefaultJmsActivationSpecFactory`]).

| `destination-resolver`
| A reference to the `DestinationResolver` strategy for resolving JMS `Destinations`.

| `message-converter`
| A reference to the `MessageConverter` strategy for converting JMS Messages to listener
  method arguments. The default is `SimpleMessageConverter`.

| `destination-type`
| The JMS destination type for this listener: `queue`, `topic`, `durableTopic`, `sharedTopic`.
  or `sharedDurableTopic`. This potentially enables the `pubSubDomain`, `subscriptionDurable`,
  and `subscriptionShared` properties of the container. The default is `queue` (which disables
  those three properties).

| `response-destination-type`
| The JMS destination type for responses: `queue` or `topic`. The default is the value of the
  `destination-type` attribute.

| `client-id`
| The JMS client ID for this listener container. It needs to be specified when using
  durable subscriptions.

| `acknowledge`
| The native JMS acknowledge mode: `auto`, `client`, `dups-ok`, or `transacted`. A value
  of `transacted` activates a locally transacted `Session`. As an alternative, you can specify
  the `transaction-manager` attribute described later. The default is `auto`.

| `transaction-manager`
| A reference to a Spring `JtaTransactionManager` or a
  `jakarta.transaction.TransactionManager` for kicking off an XA transaction for each
  incoming message. If not specified, native acknowledging is used (see the
  `acknowledge` attribute).

| `concurrency`
| The number of concurrent sessions or consumers to start for each listener. It can either be
  a simple number indicating the maximum number (for example `5`) or a range indicating the
  lower as well as the upper limit (for example, `3-5`). Note that a specified minimum is only a
  hint and is typically ignored at runtime when you use a JCA listener container.
  The default is 1.

| `prefetch`
| The maximum number of messages to load into a single session. Note that raising this
  number might lead to starvation of concurrent consumers.
|===