JMS命名空间支持

Hunyuan 7b 中英对照 JMS Namespace Support

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

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

• 参考JMS模式（schema）。

命名空间由三个顶级元素组成：<annotation-driven/>、<listener-container/>和<jca-listener-container/>。<annotation-driven/>使得可以使用注解驱动的监听器端点。<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>

前面的例子相当于创建了两个不同的监听器容器bean定义和两个不同的MessageListenerAdapter bean定义，如使用MessageListenerAdapter中所展示的。除了前面例子中展示的属性之外，listener元素还可以包含几个可选属性。下表描述了所有可用的属性：

表1. JMS <listener>元素的属性

属性	说明
id	托管监听器容器的Bean名称。如果未指定，将自动生成一个Bean名称。
destination (必需)	该监听器的目标名称，通过DestinationResolver策略进行解析。
ref (必需)	处理器对象的Bean名称。
method	要调用的处理方法的名称。如果ref属性指向一个MessageListener或Spring的SessionAwareMessageListener，则可以省略此属性。
response-destination	发送响应消息的默认目标名称。当请求消息不包含JMSReplyTo字段时，会使用此名称。此目标的类型由监听器容器的response-destination-type属性决定。请注意，这仅适用于具有返回值的监听器方法，因为每个结果对象都会被转换成响应消息。
subscription	持久订阅的名称（如果有的话）。
selector	该监听器的可选消息选择器。
concurrency	为此监听器启动的并发会话或消费者的数量。此值可以是一个简单的数字，表示最大数量（例如，5），也可以是一个范围，表示下限和上限（例如，3-5）。请注意，指定的最小值仅作为提示，在运行时可能会被忽略。默认值由容器提供。

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

你可以通过指定要公开的Bean的id并通过factory-id属性来自动公开诸如JmsListenerContainerFactory这样的设置，如下例所示：

<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还提供了关于事务选择和消息重新传递场景的讨论。

表2. JMS <listener-container>元素的属性

属性；特征	描述
container-type	此监听器容器的类型。可用选项有 default、simple、default102 或 simple102（默认选项是 default）。
container-class	一个自定义监听器容器实现类，作为完全限定类名。默认值是根据container-type属性来使用的Spring的标准DefaultMessageListenerContainer或SimpleMessageListenerContainer。
factory-id	将此元素定义的设置作为具有指定id的JmsListenerContainerFactory公开，以便可以与其他端点复用。
connection-factory	对JMS ConnectionFactory bean的引用（默认bean名称为connectionFactory）。
task-executor	对JMS监听器调用者的Spring TaskExecutor的引用。
destination-resolver	对用于解析JMS Destination 实例的 DestinationResolver 策略的引用。
message-converter	对MessageConverter策略的引用，用于将JMS消息转换为监听器方法参数。默认值为SimpleMessageConverter。
error-handler	对ErrorHandler策略的引用，用于处理在MessageListener执行过程中可能发生的任何未被捕获的异常。
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变体的可用配置选项：

表3. JMS <jca-listener-container/> 元素的属性

属性	描述
factory-id	以指定的 id 将此元素定义的设置公开为 JmsListenerContainerFactory，以便可以与其他端点重用。
resource-adapter	对 JCA ResourceAdapter bean 的引用（默认 bean 名称为 resourceAdapter）。
activation-spec-factory	对 JmsActivationSpecFactory 的引用。默认情况下会自动检测 JMS 提供者及其 ActivationSpec 类（参见 DefaultJmsActivationSpecFactory）。
destination-resolver	用于解析 JMS Destinations 的 DestinationResolver 策略的引用。
message-converter	用于将 JMS 消息转换为监听器方法参数的 MessageConverter 策略的引用。默认值为 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。在使用持久订阅时需要指定此 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	单个会话中可预取的最大消息数量。请注意，提高此数值可能会导致并发消费者无法获取消息。