JMS Namespace Support

Spring 提供了一个 XML 命名空间来简化 JMS 配置。若要使用 JMS 命名空间元素，你需要引用 JMS 模式，如下例所示：

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:

<?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.

该命名空间由三个顶级元素组成： <annotation-driven/>、 <listener-container/>`和 `<jca-listener-container/>。<annotation-driven/>`允许 annotation-driven listener endpoints的使用。<listener-container/>`和 `<jca-listener-container/>`定义共享侦听器容器配置，并且可以包含 `<listener/>`子元素。以下示例展示了两个侦听器的基本配置：

The namespace consists of three top-level elements: <annotation-driven/>, <listener-container/> and <jca-listener-container/>. <annotation-driven/> enables the use of 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:

<jms:listener-container>

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

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

</jms:listener-container>

前面这个示例相当于创建两个不同的侦听器容器 beanDefinition 元素和两个不同的 MessageListenerAdapter bean 定义，如 xref:integration/jms/receiving.adoc#jms-receiving-async-message-listener-adapter[Using MessageListenerAdapter 中所示。除了前面示例中所示的属性之外，listener 元素还可以包含几个可选属性。下表描述了所有可用的属性：

The preceding example is equivalent to creating two distinct listener container bean definitions and two distinct MessageListenerAdapter bean definitions, as shown in 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:

Table 1. Attributes of the JMS <listener> element
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.

<listener-container/> 元素还接受几个可选属性。这允许自定义各种策略（例如，taskExecutor 和 destinationResolver）以及基本的 JMS 设置和资源引用。通过使用这些属性，你可以定义高度定制的侦听器容器，同时仍然受益于命名空间的便利性。

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.

你可以自动公开诸如 JmsListenerContainerFactory 的设置，方法是通过 factory-id attribute 指定要公开的 bean 的 id，如下例所示：

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:

<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>

下表描述了所有可用的属性。请参阅 AbstractMessageListenerContainer 及其具体子类的类级别 javadoc 以获取每个属性的更多详细信息。javadoc 还讨论了事务选择和消息重新发送的场景。

The following table describes all available attributes. See the class-level javadoc of the 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.

Table 2. Attributes of the JMS <listener-container> element
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.

使用 jms 模式支持配置基于 JCA 的侦听器容器的方式与以下所示示例非常相似：

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

<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>

下表对 JCA 变量中可用的配置选项进行了说明：

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

Table 3. Attributes of the JMS <jca-listener-container/> element
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 `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.