Common Router Parameters

本节描述了所有路由器参数通用的参数(即本章前面显示的两个表格中全部选中框的参数)。

This section describes the parameters common to all router parameters (the parameters with all their boxes ticked in the two tables shown earlier in this chapter).

Inside and Outside a Chain

以下参数对链路内外的所有路由器有效。

The following parameters are valid for all routers inside and outside of chains.

apply-sequence

This attribute specifies whether sequence number and size headers should be added to each message. This optional attribute defaults to false.

default-output-channel

If set, this attribute provides a reference to the channel where messages should be sent if channel resolution fails to return any channels. If no default output channel is provided, the router throws an exception. If you would like to silently drop those messages instead, set the default output channel attribute value to nullChannel.

从 6.0 版本开始,设置默认输出通道也会将 channelKeyFallback 选项重置为 false。因此,不会尝试从其名称解析通道,但会退回到此默认输出通道 - 类似于 Java switch 语句。如果 channelKeyFallback 显式设置为 true,进一步的逻辑将取决于 resolutionRequired 选项:仅当 resolutionRequiredfalse 时,该消息才能从键到未解析通道到达 defaultOutputChannel。因此,AbstractMappingMessageRouter 初始化阶段会拒绝提供 defaultOutputChannel 并且将 channelKeyFallbackresolutionRequired 都设置为 true 的配置。

Starting with version 6.0, setting a default output channel also resets the channelKeyFallback option to false. So, no attempts will be made to resolve a channel from its name, but rather fallback to this default output channel - similar to a Java switch statement. If channelKeyFallback is set to true explicitly, the further logic depends on the resolutionRequired option: the message to non-resolved channel from key can reach a defaultOutputChannel only if resolutionRequired is false. Therefore, a configuration where defaultOutputChannel is provided and both channelKeyFallback & resolutionRequired are set to true is rejected by the AbstractMappingMessageRouter initialization phase.

resolution-required

This attribute specifies whether channel names must always be successfully resolved to channel instances that exist. If set to true, a MessagingException is raised when the channel cannot be resolved. Setting this attribute to false causes any unresolvable channels to be ignored. This optional attribute defaults to true.

仅当指定了 resolution-requiredfalse 且未解析通道时,才会向 default-output-channel 发送消息。

A Message is sent only to the default-output-channel, if specified, when resolution-required is false and the channel is not resolved.

ignore-send-failures

If set to true, failures to send to a message channel is ignored. If set to false, a MessageDeliveryException is thrown instead, and, if the router resolves more than one channel, any subsequent channels do not receive the message.

此属性的确切行为取决于发送消息到的 Channel 的类型。例如,当使用直接通道(单线程)时,组件抛出的异常可能会导致发送失败。但是,当将消息发送到简单队列通道(异步)时,抛出异常的可能性比较小。

The exact behavior of this attribute depends on the type of the Channel to which the messages are sent. For example, when using direct channels (single threaded), send failures can be caused by exceptions thrown by components much further downstream. However, when sending messages to a simple queue channel (asynchronous), the likelihood of an exception to be thrown is rather remote.

虽然大多数路由器会路由到一个通道,但它们可以返回多个通道名称。例如,recipient-list-router 执行的操作就是这样的。如果您在一个仅路由到单个通道的路由器上将此属性设置为 true,将忽略任何造成的异常,这通常毫无意义。在这种情况中,最好在流程入口处的错误流程中捕获异常。因此,当路由器实施返回多个通道名称时,将 ignore-send-failures 属性设置为 true 通常更有意义,因为失败通道后的其他通道仍然会收到消息。

While most routers route to a single channel, they can return more than one channel name. The recipient-list-router, for instance, does exactly that. If you set this attribute to true on a router that only routes to a single channel, any caused exception is swallowed, which usually makes little sense. In that case, it would be better to catch the exception in an error flow at the flow entry point. Therefore, setting the ignore-send-failures attribute to true usually makes more sense when the router implementation returns more than one channel name, because the other channel(s) following the one that fails would still receive the message.

此属性默认为 false

This attribute defaults to false.

timeout

The timeout attribute specifies the maximum amount of time in milliseconds to wait when sending messages to the target Message Channels.

Top-Level (Outside a Chain)

以下参数仅对链路外部的所有顶级路由器有效。

The following parameters are valid only across all top-level routers that are outside of chains.

id

Identifies the underlying Spring bean definition, which, in the case of routers, is an instance of EventDrivenConsumer or PollingConsumer, depending on whether the router’s input-channel is a SubscribableChannel or a PollableChannel, respectively. This is an optional attribute.

auto-startup

This “lifecycle” attribute signaled whether this component should be started during startup of the application context. This optional attribute defaults to true.

input-channel

The receiving message channel of this endpoint.

order

This attribute defines the order for invocation when this endpoint is connected as a subscriber to a channel. This is particularly relevant when that channel uses a failover dispatching strategy. It has no effect when this endpoint itself is a polling consumer for a channel with a queue.