9ac0b65c77
* Mostly driver by suggestions from IDEA language plugin * Add Maven-Gradle code switch for dependency in the modules
180 lines
10 KiB
Plaintext
180 lines
10 KiB
Plaintext
[[chain]]
|
|
=== Message Handler Chain
|
|
|
|
The `MessageHandlerChain` is an implementation of `MessageHandler` that can be configured as a single message endpoint while actually delegating to a chain of other handlers, such as filters, transformers, splitters, and so on.
|
|
When several handlers need to be connected in a fixed, linear progression, this can lead to a much simpler configuration.
|
|
For example, it is fairly common to provide a transformer before other components.
|
|
Similarly, when you provide a filter before some other component in a chain, you essentially create a https://www.enterpriseintegrationpatterns.com/MessageSelector.html[selective consumer].
|
|
In either case, the chain requires only a single `input-channel` and a single `output-channel`, eliminating the need to define channels for each individual component.
|
|
|
|
NOTE: The `MessageHandlerChain` is mostly designed for an XML configuration.
|
|
For Java DSL, an `IntegrationFlow` definition can be treated as a chain component, but it has nothing to do with concepts and principles described in this chapter below.
|
|
See <<./dsl.adoc#java-dsl,Java DSL>> for more information.
|
|
|
|
TIP: Spring Integration's `Filter` provides a boolean property: `throwExceptionOnRejection`.
|
|
When you provide multiple selective consumers on the same point-to-point channel with different acceptance criteria, you should set this value 'true' (the default is `false`) so that the dispatcher knows that the message was rejected and, as a result, tries to pass the message on to other subscribers.
|
|
If the exception were not thrown, it would appear to the dispatcher that the message had been passed on successfully even though the filter had dropped the message to prevent further processing.
|
|
If you do indeed want to "`drop`" the messages, the filter's 'discard-channel' might be useful, since it does give you a chance to perform some operation with the dropped message (such as sending it to a JMS queue or writing it to a log).
|
|
|
|
The handler chain simplifies configuration while internally maintaining the same degree of loose coupling between components, and it is trivial to modify the configuration if at some point a non-linear arrangement is required.
|
|
|
|
Internally, the chain is expanded into a linear setup of the listed endpoints, separated by anonymous channels.
|
|
The reply channel header is not taken into account within the chain.
|
|
Only after the last handler is invoked is the resulting message forwarded to the reply channel or the chain's output channel.
|
|
Because of this setup, all handlers except the last must implement the `MessageProducer` interface (which provides a 'setOutputChannel()' method).
|
|
If the `outputChannel` on the `MessageHandlerChain` is set, the last handler needs only an output channel.
|
|
|
|
NOTE: As with other endpoints, the `output-channel` is optional.
|
|
If there is a reply message at the end of the chain, the output-channel takes precedence.
|
|
However, if it is not available, the chain handler checks for a reply channel header on the inbound message as a fallback.
|
|
|
|
In most cases, you need not implement `MessageHandler` yourself.
|
|
The next section focuses on namespace support for the chain element.
|
|
Most Spring Integration endpoints, such as service activators and transformers, are suitable for use within a `MessageHandlerChain`.
|
|
|
|
[[chain-namespace]]
|
|
==== Configuring a Chain
|
|
|
|
The `<chain>` element provides an `input-channel` attribute.
|
|
If the last element in the chain is capable of producing reply messages (optional), it also supports an `output-channel` attribute.
|
|
The sub-elements are then filters, transformers, splitters, and service-activators.
|
|
The last element may also be a router or an outbound channel adapter.
|
|
The following example shows a chain definition:
|
|
|
|
====
|
|
[source,xml]
|
|
----
|
|
<int:chain input-channel="input" output-channel="output">
|
|
<int:filter ref="someSelector" throw-exception-on-rejection="true"/>
|
|
<int:header-enricher>
|
|
<int:header name="thing1" value="thing2"/>
|
|
</int:header-enricher>
|
|
<int:service-activator ref="someService" method="someMethod"/>
|
|
</int:chain>
|
|
----
|
|
====
|
|
|
|
The `<header-enricher>` element used in the preceding example sets a message header named `thing1` with a value of `thing2` on the message.
|
|
A header enricher is a specialization of `Transformer` that touches only header values.
|
|
You could obtain the same result by implementing a `MessageHandler` that did the header modifications and wiring that as a bean, but the header-enricher is a simpler option.
|
|
|
|
The `<chain>` can be configured as the last "`closed-box`" consumer of the message flow.
|
|
For this solution, you can to put it at the end of the <chain> some <outbound-channel-adapter>, as the following example shows:
|
|
|
|
====
|
|
[source,xml]
|
|
----
|
|
<int:chain input-channel="input">
|
|
<int-xml:marshalling-transformer marshaller="marshaller" result-type="StringResult" />
|
|
<int:service-activator ref="someService" method="someMethod"/>
|
|
<int:header-enricher>
|
|
<int:header name="thing1" value="thing2"/>
|
|
</int:header-enricher>
|
|
<int:logging-channel-adapter level="INFO" log-full-message="true"/>
|
|
</int:chain>
|
|
----
|
|
====
|
|
|
|
.Disallowed Attributes and Elements
|
|
[IMPORTANT]
|
|
=====
|
|
Certain attributes, such as `order` and `input-channel` are not allowed to be specified on components used within a chain.
|
|
The same is true for the poller sub-element.
|
|
|
|
For the Spring Integration core components, the XML schema itself enforces some of these constraints.
|
|
However, for non-core components or your own custom components, these constraints are enforced by the XML namespace parser, not by the XML schema.
|
|
|
|
These XML namespace parser constraints were added with Spring Integration 2.2.
|
|
If you try to use disallowed attributes and elements, the XML namespace parser throws a `BeanDefinitionParsingException`.
|
|
=====
|
|
|
|
==== Using the 'id' Attribute
|
|
|
|
Beginning with Spring Integration 3.0, if a chain element is given an `id` attribute, the bean name for the element is a combination of the chain's `id` and the `id` of the element itself.
|
|
Elements without `id` attributes are not registered as beans, but each one is given a `componentName` that includes the chain `id`.
|
|
Consider the following example:
|
|
|
|
====
|
|
[source,xml]
|
|
----
|
|
<int:chain id="somethingChain" input-channel="input">
|
|
<int:service-activator id="somethingService" ref="someService" method="someMethod"/>
|
|
<int:object-to-json-transformer/>
|
|
</int:chain>
|
|
----
|
|
====
|
|
|
|
In the preceding example:
|
|
|
|
* The `<chain>` root element has an `id` of 'somethingChain'.
|
|
Consequently, the `AbstractEndpoint` implementation (`PollingConsumer` or `EventDrivenConsumer`, depending on the `input-channel` type) bean takes this value as its bean name.
|
|
|
|
* The `MessageHandlerChain` bean acquires a bean alias ('somethingChain.handler'), which allows direct access to this bean from the `BeanFactory`.
|
|
|
|
* The `<service-activator>` is not a fully fledged messaging endpoint (it is not a `PollingConsumer` or `EventDrivenConsumer`).
|
|
It is a `MessageHandler` within the `<chain>`.
|
|
In this case, the bean name registered with the `BeanFactory` is 'somethingChain$child.somethingService.handler'.
|
|
|
|
* The `componentName` of this `ServiceActivatingHandler` takes the same value but without the '.handler' suffix.
|
|
It becomes 'somethingChain$child.somethingService'.
|
|
|
|
* The last `<chain>` sub-component, `<object-to-json-transformer>`, does not have an `id` attribute.
|
|
Its `componentName` is based on its position in the `<chain>`.
|
|
In this case, it is 'somethingChain$child#1'.
|
|
(The final element of the name is the order within the chain, beginning with '#0').
|
|
Note, this transformer is not registered as a bean within the application context, so it does not get a `beanName`.
|
|
However, its `componentName` has a value that is useful for logging and other purposes.
|
|
|
|
The `id` attribute for `<chain>` elements lets them be eligible for <<./jmx.adoc#jmx-mbean-exporter,JMX export>>, and they are trackable in the <<./message-history.adoc#message-history,message history>>.
|
|
You can access them from the `BeanFactory` by using the appropriate bean name, as discussed earlier.
|
|
|
|
TIP: It is useful to provide an explicit `id` attribute on `<chain>` elements to simplify the identification of sub-components in logs and to provide access to them from the `BeanFactory` etc.
|
|
|
|
[[chain-gateway]]
|
|
==== Calling a Chain from within a Chain
|
|
|
|
Sometimes, you need to make a nested call to another chain from within a chain and then come back and continue execution within the original chain.
|
|
To accomplish this, you can use a messaging gateway by including a <gateway> element, as the following example shows:
|
|
|
|
====
|
|
[source,xml]
|
|
----
|
|
<int:chain id="main-chain" input-channel="in" output-channel="out">
|
|
<int:header-enricher>
|
|
<int:header name="name" value="Many" />
|
|
</int:header-enricher>
|
|
<int:service-activator>
|
|
<bean class="org.foo.SampleService" />
|
|
</int:service-activator>
|
|
<int:gateway request-channel="inputA"/>
|
|
</int:chain>
|
|
|
|
<int:chain id="nested-chain-a" input-channel="inputA">
|
|
<int:header-enricher>
|
|
<int:header name="name" value="Moe" />
|
|
</int:header-enricher>
|
|
<int:gateway request-channel="inputB"/>
|
|
<int:service-activator>
|
|
<bean class="org.foo.SampleService" />
|
|
</int:service-activator>
|
|
</int:chain>
|
|
|
|
<int:chain id="nested-chain-b" input-channel="inputB">
|
|
<int:header-enricher>
|
|
<int:header name="name" value="Jack" />
|
|
</int:header-enricher>
|
|
<int:service-activator>
|
|
<bean class="org.foo.SampleService" />
|
|
</int:service-activator>
|
|
</int:chain>
|
|
----
|
|
====
|
|
|
|
In the preceding example, `nested-chain-a` is called at the end of `main-chain` processing by the 'gateway' element configured there.
|
|
While in `nested-chain-a`, a call to a `nested-chain-b` is made after header enrichment.
|
|
Then the flow comes back to finish execution in `nested-chain-b`.
|
|
Finally, the flow returns to `main-chain`.
|
|
When the nested version of a `<gateway>` element is defined in the chain, it does not require the `service-interface` attribute.
|
|
Instead, it takes the message in its current state and places it on the channel defined in the `request-channel` attribute.
|
|
When the downstream flow initiated by that gateway completes, a `Message` is returned to the gateway and continues its journey within the current chain.
|