JMS Namespace Support

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

<?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/>`子元素。以下示例展示了两个侦听器的基本配置：

<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 元素还可以包含几个可选属性。下表描述了所有可用的属性：

Table 1. Attributes of the JMS <listener> element
Attribute	Description
`id`	用于托管监听器容器的 bean 名称。如果没有指定该名称，系统会自动生成。
`destination` (required)	此侦听器的目标名称，通过 `DestinationResolver` 策略解析。
`ref` (required)	处理程序对象的 bean 名称。
`method`	要调用的处理程序方法的名称。如果 `ref` 属性指向 `MessageListener` 或 Spring `SessionAwareMessageListener`，则可以省略此属性。
`response-destination`	要将响应消息发送到的默认响应目标的名称。这是针对不包含 `JMSReplyTo` 字段的请求消息应用的。此目标的类型由侦听器容器的 `response-destination-type` 属性确定。请注意，这只适用于具有返回值的侦听器方法，对于这样的方法，每个结果对象都会转换为响应消息。
`subscription`	如果有的话，durable 订阅的名称。
`selector`	此侦听器的可选消息选择器。
`concurrency`	为该侦听器启动的并发会话或使用者的数量。此值可以是一个简单的数字，表示最大数量（例如，`5`），或者是一个同时表示下限和上限的范围（例如，`3-5`）。请注意，指定的最小值仅是一个提示，在运行期间可能会被忽略。缺省值为容器提供的值。

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

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

<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 还讨论了事务选择和消息重新发送的场景。

Table 2. Attributes of the JMS <listener-container> element
Attribute	Description
`container-type`	此侦听器容器类型。可用的选项是 `default`，`simple`，`default102` 或 `simple102`（缺省选项是 `default`）。
`container-class`	一个自定义侦听器容器实现类作为完全限定类名。缺省值为 Spring 的标准 `DefaultMessageListenerContainer` 或 `SimpleMessageListenerContainer`，根据 `container-type` 属性。
`factory-id`	将此元素定义的设置公开为 `JmsListenerContainerFactory`，并同时指定 `id`，以便其可与其他端点一起重复使用。
`connection-factory`	对 JMS `ConnectionFactory` Bean 的引用（缺省 bean 名称是 `connectionFactory`）。
`task-executor`	对 JMS 侦听器调用者的 Spring `TaskExecutor` 的引用。
`destination-resolver`	对用于解析 JMS `Destination` 实例的 `DestinationResolver` 策略的引用。
`message-converter`	对用于将 JMS 消息转换为侦听器方法参数的 `MessageConverter` 策略的引用。缺省值是 `SimpleMessageConverter`。
`error-handler`	对用于处理在 `MessageListener` 执行期间可能发生的任何未捕获异常的 `ErrorHandler` 策略的引用。
`destination-type`	此侦听器的 JMS 目标类型：`queue`、`topic`、`durableTopic`、`sharedTopic` 或 `sharedDurableTopic`。这可能启用容器的 `pubSubDomain`、`subscriptionDurable` 和 `subscriptionShared` 属性。缺省值为 `queue`（禁用这三个属性）。
`response-destination-type`	答复的 JMS 目标类型：`queue` 或 `topic`。缺省值为 `destination-type` 属性的值。
`client-id`	此侦听容器的 JMS 客户端 ID。在使用持久订阅时，必须指定该 ID。
`cache`	JMS 资源的缓存级别：`none`、`connection`、`session`、`consumer` 或 `auto`。默认情况下（`auto`），缓存级别实际上为 `consumer`，除非指定了外部事务管理器，在这种情况下，有效默认值将为 `none`（假设是 Jakarta EE 样式的事务管理，其中给定的 ConnectionFactory 是一个 XA 感知池）。
`acknowledge`	本机 JMS 确认模式：`auto`、`client`、`dups-ok` 或 `transacted`。`transacted` 的值会激活本地的事务型 `Session`。或者，可以指定 `transaction-manager` 属性，该属性在表中后面描述。默认值为 `auto`。
`transaction-manager`	对外部 `PlatformTransactionManager` 的引用（通常是基于 XA 的事务协调器，如 Spring 的 `JtaTransactionManager`）。如果未指定，则使用本机确认（请参见 `acknowledge` 属性）。
`concurrency`	针对每个侦听器启动的并发会话或消费者的数量。它可以是表示最大数量的简单数字（例如 `5`），也可以是表示下限和上限的范围（例如 `3-5`）。请注意，指定的最小值只是一个提示，可能会在运行时被忽略。默认值为 `1`。如果是主题侦听器或队列顺序很重要，则应将并发限制为 `1`。考虑为普通队列提高它。
`prefetch`	加载到单个会话中的消息的最大数量。请注意，增加此数字可能会导致并发消费者匮乏。
`receive-timeout`	接收调用使用的超时（以毫秒为单位）。默认值为 `1000`（一秒）。`-1` 表示没有超时。
`back-off`	指定要用于计算恢复尝试间隔的 `BackOff` 实例。如果 `BackOffExecution` 实现返回 `BackOffExecution#STOP`，则侦听容器不会进一步尝试恢复。设置此属性后，将忽略 `recovery-interval` 值。默认值为 `FixedBackOff`，间隔为 5000 毫秒（即五秒）。
`recovery-interval`	指定恢复尝试之间的间隔，以毫秒为单位。它提供了一种便捷的方法来创建具有指定间隔的 `FixedBackOff`。对于更多恢复选项，请考虑指定 `BackOff` 实例。默认值为 5000 毫秒（即五秒）。
`phase`	此容器应启动和停止的生命周期阶段。值越低，该容器启动越早，停止时间越晚。默认值为 `Integer.MAX_VALUE`，表示容器在尽可能晚的时候启动并在尽可能早的时候停止。

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

<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 变量中可用的配置选项进行了说明：

Table 3. Attributes of the JMS <jca-listener-container/> element
Attribute	Description
`factory-id`	将此元素定义的设置公开为 `JmsListenerContainerFactory`，并同时指定 `id`，以便其可与其他端点一起重复使用。
`resource-adapter`	对 JCA `ResourceAdapter` bean 的引用（默认 bean 名称是 `resourceAdapter`）。
`activation-spec-factory`	对 `JmsActivationSpecFactory` 的引用。默认情况下是自动检测 JMS 提供程序及其 `ActivationSpec` 类（请参阅 `DefaultJmsActivationSpecFactory`）。
`destination-resolver`	解析 JMS `Destinations` 的 `DestinationResolver` 策略引用。
`message-converter`	对 `MessageConverter` 的引用，用于将 JMS 消息转换成侦听器方法参数。默认值为 `SimpleMessageConverter`。
`destination-type`	此侦听器的 JMS 目标类型：`queue`、`topic`、`durableTopic`、`sharedTopic` 或 `sharedDurableTopic`。这可能启用容器的 `pubSubDomain`、`subscriptionDurable` 和 `subscriptionShared` 属性。默认值为 `queue`（这会禁用这三个属性）。
`response-destination-type`	答复的 JMS 目标类型：`queue` 或 `topic`。缺省值为 `destination-type` 属性的值。
`client-id`	此侦听器容器的 JMS 客户端 ID。在使用持久订阅时需要指定它。
`acknowledge`	原生 JMS 确认模式：`auto`、`client`、`dups-ok` 或 `transacted`。`transacted` 值激活本地事务 `Session`。或者，您可以指定后面描述的 `transaction-manager` 属性。默认值为 `auto`。
`transaction-manager`	引用 Spring `JtaTransactionManager` 或 `jakarta.transaction.TransactionManager` 以便针对每个传入消息启动 XA 事务。如果未指定，则使用原生确认（参见 `acknowledge` 属性）。
`concurrency`	为每个侦听器启动的并发会话或消费者的数量。它可以是表示最大数量的简单数字（例如 `5`），也可以是表示下限和上限的范围（例如 `3-5`）。请注意，指定最小值仅是一个提示，通常在使用 JCA 侦听器容器时会在运行时忽略它。默认值为 1。
`prefetch`	加载到单个会话中的消息的最大数量。请注意，增加此数字可能会导致并发消费者匮乏。