JMS 命名空间支持

ChatGPT-4o 中英对照 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>

xml

• 参考 JMS 架构。

命名空间由三个顶级元素组成：<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>

xml

前面的示例相当于创建两个不同的监听器容器 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 设置和资源引用。通过使用这些属性，您可以定义高度自定义的监听器容器，同时仍然受益于命名空间的便利性。

您可以通过 factory-id 属性指定要公开的 bean 的 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>

xml

下表描述了所有可用的属性。有关各个属性的更多详细信息，请参阅 AbstractMessageListenerContainer 的类级 javadoc 及其具体子类。javadoc 还提供了关于事务选择和消息重新传递场景的讨论。

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

属性	描述
container-type	此侦听器容器的类型。可用选项有 default、simple、default102 或 simple102（默认选项是 default）。
container-class	一个自定义监听器容器实现类，使用完全限定类名。默认值是 Spring 的标准 DefaultMessageListenerContainer 或 SimpleMessageListenerContainer，具体取决于 container-type 属性。
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。当您使用持久订阅时，必须指定它。
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 值。默认是一个间隔为 5000 毫秒（即五秒）的 FixedBackOff。
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>

xml

下表描述了 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。使用持久订阅时需要指定。
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	加载到单个会话中的最大消息数。请注意，提高此数字可能导致并发消费者的饥饿。