Spring/spring-integration
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

INT-3197: Docs to AsciiDoc from DocBook

Browse Source 
JIRA: https://jira.spring.io/browse/INT-3197

Polishing

Various glitches.

Fix Table of Contents

Polishing - Various Glitches

More Polishing

- Fixes for issues found by side-by-side comparison of htmlsingle output.

Fix Table Formats for PDF

More Polishing - PR Comments

More Polishing - Bad Titles

More Polishing

Work-Around for AsciiDoctor Problem

https://github.com/asciidoctor/asciidoctor/issues/1297

Use a blank line between includes rather than a comment
at the end of include files that end with a callout.

Remove Unresolved qName Entries

Fix Overview PDF Image Sizes

Highlight Schema Imports

More Image Fixes

INT-3197: Port DocBook Changes Since Conversion

Remove DocBook Files
This commit is contained in:
Gary Russell
2015-03-20 19:49:13 +02:00
committed by Artem Bilan
parent facffe2411
commit 056b17aaa7
181 changed files with 25308 additions and 31133 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
build.gradle
View File

@@ -9,10 +9,13 @@ buildscript {
}
dependencies {
classpath 'org.springframework.build.gradle:spring-io-plugin:0.0.3.RELEASE'
classpath 'org.springframework.build.gradle:docbook-reference-plugin:0.2.8'
classpath 'io.spring.gradle:docbook-reference-plugin:0.3.0'
classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.0'
}
}
def docsDir = 'src/reference/asciidoc' // Will be default with newer asciidoctor plugin
ext {
linkHomepage = 'https://projects.spring.io/spring-integration'
linkCi = 'https://build.springsource.org/browse/INT'
@@ -689,12 +692,40 @@ project("spring-integration-bom") {
}
}
apply plugin: 'docbook-reference'
apply plugin: org.asciidoctor.gradle.AsciidoctorPlugin
asciidoctor {
sourceDir file("$docsDir")
sourceDocumentNames = files("$docsDir/index.adoc") // Change in >= 1.5.1
outputDir file("$buildDir/html")
backends = ['html5', 'docbook']
logDocuments = true
options = [
doctype: 'book',
attributes: [
docinfo: '',
toc2: '',
'compat-mode': '',
imagesdir: '',
stylesdir: "stylesheets/",
stylesheet: 'golo.css',
'spring-integration-version': "$version",
'source-highlighter': 'highlightjs'
]
]
}
apply plugin: DocbookReferencePlugin
reference {
sourceDir = file('src/reference/docbook')
sourceFileName = 'index.xml'
sourceDir = file("$buildDir/html")
pdfFilename = 'spring-integration-reference.pdf'
expandPlaceholders = ''
}
reference.dependsOn asciidoctor
apply plugin: 'sonar-runner'
sonarRunner {

764
src/reference/asciidoc/aggregator.adoc Normal file
View File

@@ -0,0 +1,764 @@
[[aggregator]]
=== Aggregator
[[aggregator-introduction]]
==== Introduction
Basically a mirror-image of the Splitter, the Aggregator is a type of Message Handler that receives multiple Messages and combines them into a single Message.
In fact, an Aggregator is often a downstream consumer in a pipeline that includes a Splitter.
Technically, the Aggregator is more complex than a Splitter, because it is stateful as it must hold the Messages to be aggregated and determine when the complete group of Messages is ready to be aggregated.
In order to do this it requires a `MessageStore`.
[[aggregator-functionality]]
==== Functionality
The Aggregator combines a group of related messages, by correlating and storing them, until the group is deemed complete.
At that point, the Aggregator will create a single message by processing the whole group, and will send the aggregated message as output.
Implementing an Aggregator requires providing the logic to perform the aggregation (i.e., the creation of a single message from many).
Two related concepts are correlation and release.
Correlation determines how messages are grouped for aggregation.
In Spring Integration correlation is done by default based on the `IntegrationMessageHeaderAccessor.CORRELATION_ID` message header.
Messages with the same `IntegrationMessageHeaderAccessor.CORRELATION_ID` will be grouped together.
However, the correlation strategy may be customized to allow other ways of specifying how the messages should be grouped together by implementing a `CorrelationStrategy` (see below).
To determine the point at which a group of messages is ready to be processed, a `ReleaseStrategy` is consulted.
The default release strategy for the Aggregator will release a group when all messages included in a sequence are present, based on the `IntegrationMessageHeaderAccessor.SEQUENCE_SIZE` header.
This default strategy may be overridden by providing a reference to a custom `ReleaseStrategy` implementation.
[[aggregator-api]]
==== Programming model
The Aggregation API consists of a number of classes:
* The interface `MessageGroupProcessor`, and its subclasses:`MethodInvokingAggregatingMessageGroupProcessor` and `ExpressionEvaluatingMessageGroupProcessor`
* The `ReleaseStrategy` interface and its default implementation `SequenceSizeReleaseStrategy`
* The `CorrelationStrategy` interface and its default implementation `HeaderAttributeCorrelationStrategy`
===== AggregatingMessageHandler
The `AggregatingMessageHandler` (subclass of `AbstractCorrelatingMessageHandler`) is a `MessageHandler` implementation, encapsulating the common functionalities of an Aggregator (and other correlating use cases), which are:
* correlating messages into a group to be aggregated
* maintaining those messages in a `MessageStore` until the group can be released
* deciding when the group can be released
* aggregating the released group into a single message
* recognizing and responding to an expired group
The responsibility of deciding how the messages should be grouped together is delegated to a `CorrelationStrategy` instance.
The responsibility of deciding whether the message group can be released is delegated to a `ReleaseStrategy` instance.
Here is a brief highlight of the base `AbstractAggregatingMessageGroupProcessor` (the responsibility of implementing the `aggregatePayloads` method is left to the developer):
[source,java]
----
public abstract class AbstractAggregatingMessageGroupProcessor
implements MessageGroupProcessor {
protected Map<String, Object> aggregateHeaders(MessageGroup group) {
// default implementation exists
}
protected abstract Object aggregatePayloads(MessageGroup group, Map<String, Object> defaultHeaders);
}
----
The `CorrelationStrategy` is owned by the `AbstractCorrelatingMessageHandler` and it has a default value based on the `IntegrationMessageHeaderAccessor.CORRELATION_ID` message header:
[source,java]
----
public AbstractCorrelatingMessageHandler(MessageGroupProcessor processor, MessageGroupStore store,
CorrelationStrategy correlationStrategy, ReleaseStrategy releaseStrategy) {
...
this.correlationStrategy = correlationStrategy == null ?
new HeaderAttributeCorrelationStrategy(IntegrationMessageHeaderAccessor.CORRELATION_ID) : correlationStrategy;
this.releaseStrategy = releaseStrategy == null ? new SequenceSizeReleaseStrategy() : releaseStrategy;
...
}
----
As for actual processing of the message group, the default implementation is the `DefaultAggregatingMessageGroupProcessor`.
It creates a single Message whose payload is a List of the payloads received for a given group.
This works well for simple Scatter Gather implementations with either a Splitter, Publish Subscribe Channel, or Recipient List Router upstream.
NOTE: When using a Publish Subscribe Channel or Recipient List Router in this type of scenario, be sure to enable the flag to `apply-sequence`.
That will add the necessary headers (CORRELATION_ID, SEQUENCE_NUMBER and SEQUENCE_SIZE).
That behavior is enabled by default for Splitters in Spring Integration, but it is not enabled for the Publish Subscribe Channel or Recipient List Router because those components may be used in a variety of contexts in which these headers are not necessary.
When implementing a specific aggregator strategy for an application, a developer can extend `AbstractAggregatingMessageGroupProcessor` and implement the `aggregatePayloads` method.
However, there are better solutions, less coupled to the API, for implementing the aggregation logic which can be configured easily either through XML or through annotations.
In general, any POJO can implement the aggregation algorithm if it provides a method that accepts a single `java.util.List` as an argument (parameterized lists are supported as well).
This method will be invoked for aggregating messages as follows:
* if the argument is a `java.util.List<T>`, and the parameter type T is assignable to `Message`, then the whole list of messages accumulated for aggregation will be sent to the aggregator
* if the argument is a non-parameterized `java.util.List` or the parameter type is not assignable to `Message`, then the method will receive the payloads of the accumulated messages
* if the return type is not assignable to `Message`, then it will be treated as the payload for a Message that will be created automatically by the framework.
NOTE: In the interest of code simplicity, and promoting best practices such as low coupling, testability, etc., the preferred way of implementing the aggregation logic is through a POJO, and using the XML or annotation support for configuring it in the application.
===== ReleaseStrategy
The `ReleaseStrategy` interface is defined as follows:
[source,java]
----
public interface ReleaseStrategy {
boolean canRelease(MessageGroup group);
}
----
In general, any POJO can implement the completion decision logic if it provides a method that accepts a single `java.util.List` as an argument (parameterized lists are supported as well), and returns a boolean value.
This method will be invoked after the arrival of each new message, to decide whether the group is complete or not, as follows:
if the argument is a `java.util.List<T>`, and the parameter type T is assignable to `Message`, then the whole list of messages accumulated in the group will be sent to the method
if the argument is a non-parametrized `java.util.List` or the parameter type is not assignable to `Message`, then the method will receive the payloads of the accumulated messages
the method must return true if the message group is ready for aggregation, and false otherwise.
For example:
[source,java]
----
public class MyReleaseStrategy {
@ReleaseStrategy
public boolean canMessagesBeReleased(List<Message<?>>) {...}
}
----
[source,java]
----
public class MyReleaseStrategy {
@ReleaseStrategy
public boolean canMessagesBeReleased(List<String>) {...}
}
----
As you can see based on the above signatures, the POJO-based Release Strategy will be passed a `Collection` of not-yet-released Messages (if you need access to the whole `Message`) or a `Collection` of payload objects (if the type parameter is anything other than `Message`).
Typically this would satisfy the majority of use cases.
However if, for some reason, you need to access the full `MessageGroup` then you should simply provide an implementation of the `ReleaseStrategy` interface.
[WARNING]
=====
When handling potentially large groups, it is important to understand how these methods are invoked because the release strategy may be invoked multiple times before the group is released.
The most efficient is an implementation of `ReleaseStrategy` because the aggregator can invoke it directly.
The second most efficient is a POJO method with a `Collection<Message<?>>` parameter type.
The least efficient is a POJO method with a `Collection<Foo>` type - the framework has to copy the payloads from the messages in the group into a new collection (and possibly attempt conversion on the payloads to `Foo`) every time the release strategy is called.
`Collection<?>` avoids the conversion but still requires creating the new `Collection`.
*For these reasons, for large groups, it is recommended that you implement
`ReleaseStrategy`.*
=====
When the group is released for aggregation, all its not-yet-released messages are processed and removed from the group.
If the group is also complete (i.e.
if all messages from a sequence have arrived or if there is no sequence defined), then the group is marked as complete.
Any new messages for this group will be sent to the discard channel (if defined).
Setting `expire-groups-upon-completion` to `true` (default is `false`) removes the entire group and any new messages, with the same correlation id as the removed group, will form a new group.
Partial sequences can be released by using a `MessageGroupStoreReaper` together with `send-partial-result-on-expiry` being set to `true`.
IMPORTANT: To facilitate discarding of late-arriving messages, the aggregator must maintain state about the group after it has been released.
This can eventually cause out of memory conditions.
To avoid such situations, you should consider configuring a `MessageGroupStoreReaper` to remove the group metadata; the expiry parameters should be set to expire groups after it is not expected that late messages will arrive.
For information about configuring a reaper, see<<reaper>>.
Spring Integration provides an out-of-the box implementation for `ReleaseStrategy`, the `SequenceSizeReleaseStrategy`.
This implementation consults the SEQUENCE_NUMBER and SEQUENCE_SIZE headers of each arriving message to decide when a message group is complete and ready to be aggregated.
As shown above, it is also the default strategy.
===== CorrelationStrategy
The `CorrelationStrategy` interface is defined as follows:
[source,java]
----
public interface CorrelationStrategy {
Object getCorrelationKey(Message<?> message);
}
----
The method returns an Object which represents the correlation key used for associating the message with a message group.
The key must satisfy the criteria used for a key in a Map with respect to the implementation of equals() and hashCode().
In general, any POJO can implement the correlation logic, and the rules for mapping a message to a method's argument (or arguments) are the same as for a `ServiceActivator` (including support for @Header annotations).
The method must return a value, and the value must not be `null`.
Spring Integration provides an out-of-the box implementation for `CorrelationStrategy`, the `HeaderAttributeCorrelationStrategy`.
This implementation returns the value of one of the message headers (whose name is specified by a constructor argument) as the correlation key.
By default, the correlation strategy is a `HeaderAttributeCorrelationStrategy` returning the value of the CORRELATION_ID header attribute.
If you have a custom header name you would like to use for correlation, then simply configure that on an instance of `HeaderAttributeCorrelationStrategy` and provide that as a reference for the Aggregator's correlation-strategy.
[[aggregator-config]]
==== Configuring an Aggregator
[[aggregator-xml]]
===== Configuring an Aggregator with XML
Spring Integration supports the configuration of an aggregator via XML through the `<aggregator/>` element.
Below you can see an example of an aggregator.
[source,xml]
----
<channel id="inputChannel"/>
<int:aggregator id=""myAggregator" <1>
auto-startup="true" <2>
input-channel="inputChannel" <3>
output-channel="outputChannel" <4>
discard-channel="throwAwayChannel" <5>
message-store="persistentMessageStore" <6>
order="1" <7>
send-partial-result-on-expiry="false" <8>
send-timeout="1000" <9>
correlation-strategy="correlationStrategyBean" <10>
correlation-strategy-method="correlate" <11>
correlation-strategy-expression="headers['foo']" <12>
ref="aggregatorBean" <13>
method="aggregate" <14>
release-strategy="releaseStrategyBean" <15>
release-strategy-method="release" <16>
release-strategy-expression="size() == 5" <17>
expire-groups-upon-completion="false" <18>
empty-group-min-timeout="60000" <19>
lock-registry="lockRegistry" <20>
group-timeout="60000" <21>
group-timeout-expression="size() ge 2 ? 100 : -1" <22>
expire-groups-on-timeout="true" <23>
scheduler="taskScheduler" > <24>
<expire-transactional/> <25>
<expire-advice-chain/> <26>
</aggregator>
<int:channel id="outputChannel"/>
<int:channel id="throwAwayChannel"/>
<bean id="persistentMessageStore" class="org.springframework.integration.jdbc.JdbcMessageStore">
<constructor-arg ref="dataSource"/>
</bean>
<bean id="aggregatorBean" class="sample.PojoAggregator"/>
<bean id="releaseStrategyBean" class="sample.PojoReleaseStrategy"/>
<bean id="correlationStrategyBean" class="sample.PojoCorrelationStrategy"/>
----
<1> The id of the aggregator is _Optional_.
<2> Lifecycle attribute signaling if aggregator should be started during Application Context startup.
_Optional (default is 'true')_.
<3> The channel from which where aggregator will receive messages.
_Required_.
<4> The channel to which the aggregator will send the aggregation results.
_Optional (because incoming messages can specify a
reply channel themselves via 'replyChannel' Message Header)_.
<5> The channel to which the aggregator will send the messages that timed out (if `send-partial-result-on-expiry` is _false_).
_Optional_.
<6> A reference to a `MessageGroupStore` used to store groups of messages under their correlation key until they are complete.
_Optional_, by default a volatile in-memory store.
<7> Order of this aggregator when more than one handle is subscribed to the same DirectChannel (use for load balancing purposes)._Optional_.
<8> Indicates that expired messages should be aggregated and sent to the 'output-channel' or 'replyChannel' once their containing `MessageGroup` is expired (see `MessageGroupStore.expireMessageGroups(long)`).
One way of expiring `MessageGroup` s is by configuring a `MessageGroupStoreReaper`.
However `MessageGroup` s can alternatively be expired by simply calling `MessageGroupStore.expireMessageGroup(groupId)`.
That could be accomplished via a Control Bus operation or by simply invoking that method if you have a reference to the `MessageGroupStore` instance.
Otherwise by itself this attribute has no behavior.
It only serves as an indicator of what to do (discard or send to the output/reply channel) with Messages that are still in the `MessageGroup` that is about to be expired.
_Optional_.
_Default - 'false'_.
*NOTE:* This attribute is more properly 'send-partial-result-on-timeout' because the group may not actually expire if `expire-groups-on-timeout` is set to `false`.
<9> The timeout interval to wait when sending a reply `Message` to the `output-channel` or `discard-channel`.
By default the send will block for one second.
It is applied only if the output channel has some 'sending' limitations, e.g.
`QueueChannel` with a fixed 'capacity'.
In this case a `MessageDeliveryException` is thrown.
The `send-timeout` is ignored in case of `AbstractSubscribableChannel` implementations.
In case of `group-timeout(-expression)` the `MessageDeliveryException` from the scheduled expire task leads this task to be rescheduled.
_Optional_.
<10> A reference to a bean that implements the message correlation (grouping) algorithm.
The bean can be an implementation of the `CorrelationStrategy` interface or a POJO.
In the latter case the correlation-strategy-method attribute must be defined as well.
_Optional (by default, the aggregator will use
the `IntegrationMessageHeaderAccessor.CORRELATION_ID` header) _.
<11> A method defined on the bean referenced by `correlation-strategy`, that implements the correlation decision algorithm.
_Optional, with
restrictions (requires `correlation-strategy` to be
present)._
<12> A SpEL expression representing the correlation strategy.
Example: `"headers['foo']"`.
Only one of `correlation-strategy` or `correlation-strategy-expression` is allowed.
<13> A reference to a bean defined in the application context.
The bean must implement the aggregation logic as described above.
_Optional (by default the list of aggregated Messages will become a
payload of the output message)._
<14> A method defined on the bean referenced by `ref`, that implements the message aggregation algorithm.
_Optional, depends on `ref` attribute being defined._
<15> A reference to a bean that implements the release strategy.
The bean can be an implementation of the `ReleaseStrategy` interface or a POJO.
In the latter case the release-strategy-method attribute must be defined as well.
_Optional (by default, the
aggregator will use the `IntegrationMessageHeaderAccessor.SEQUENCE_SIZE` header attribute)_.
<16> A method defined on the bean referenced by `release-strategy`, that implements the completion decision algorithm.
_Optional, with
restrictions (requires `release-strategy` to be
present)._
<17> A SpEL expression representing the release strategy; the root object for the expression is a `Collection` of `Message` s.
Example: `"size() == 5"`.
Only one of `release-strategy` or `release-strategy-expression` is allowed.
<18> When set to true (default false), completed groups are removed from the message store, allowing subsequent messages with the same correlation to form a new group.
The default behavior is to send messages with the same correlation as a completed group to the _discard-channel_.
<19> Only applies if a `MessageGroupStoreReaper` is configured for the `<aggregator>`'s `MessageStore`.
By default, when a `MessageGroupStoreReaper` is configured to expire partial groups, empty groups are also removed.
Empty groups exist after a group is released normally.
This is to enable the detection and discarding of late-arriving messages.
If you wish to expire empty groups on a longer schedule than expiring partial groups, set this property.
Empty groups will then not be removed from the `MessageStore` until they have not been modified for at least this number of milliseconds.
Note that the actual time to expire an empty group will also be affected by the reaper's _timeout_ property and it could be as much as this value plus the timeout.
<20> A reference to a `org.springframework.integration.util.LockRegistry` bean; used to obtain a `Lock` based on the `groupId` for concurrent operations on the `MessageGroup`.
By default, an internal `DefaultLockRegistry` is used.
Use of a distributed `LockRegistry`, such as the `RedisLockRegistry`, ensures only one instance of the aggregator will operate on a group concurrently.
See <<redis-lock-registry>> for more information.
<21> A timeout in milliseconds to force the `MessageGroup` complete, when the `ReleaseStrategy` doesn't _release_ the group when the current Message arrives.
This attribute provides a built-in _Time-base Release Strategy_ for the aggregator, when there is a need to emit a partial result (or discard the group), if a new Message does not arrive for the `MessageGroup` within the timeout.
When a new Message arrives at the aggregator, any existing `ScheduledFuture<?>` for its `MessageGroup` is canceled.
If the `ReleaseStrategy` returns `false` (don't release) and the `groupTimeout > 0` a new task will be scheduled to expire the group.
Setting this attribute to zero is not advised because it will effectively disable the aggregator because every message group will be immediately completed.
It is possible, however to conditionally set it to zero using an expression; see `group-timeout-expression` for information.
The action taken during the completion depends on the `ReleaseStrategy` and the `send-partial-group-on-expiry` attribute.
See <<agg-and-group-to>> for more information.
Mutually exclusive with 'group-timeout-expression' attribute.
<22> The SpEL expression that evaluates to a `groupTimeout` with the `MessageGroup` as the `#root` evaluation context object.
Used for scheduling the `MessageGroup` to be forced complete.
If the expression evaluates to null or `< 0`, the completion is not scheduled.
If it evaluates to zero, the group is completed immediately on the current thread.
In effect, this provides a dynamic `group-timeout` property.
See `group-timeout` for more information.
Mutually exclusive with 'group-timeout' attribute.
<23> When a group is completed due to a timeout (or by a `MessageGroupStoreReaper`), the group is expired (completely removed) by default.
Late arriving messages will start a new group.
Set this to `false` to complete the group but have its metadata remain so that late arriving messages will be discarded.
Empty groups can be expired later using a `MessageGroupStoreReaper` together with the `empty-group-min-timeout` attribute.
Default: 'true'.
<24> A `TaskScheduler` bean reference to schedule the `MessageGroup` to be forced complete if no new message arrives for the `MessageGroup` within the `groupTimeout`.
If not provided, the default scheduler `taskScheduler`, registered in the `ApplicationContext` (`ThreadPoolTaskScheduler`) will be used.
This attribute does not apply if `group-timeout` or `group-timeout-expression` is not specified.
<25> Since _version 4.1_.
Allows a transaction to be started for the `forceComplete` operation.
It is initiated from a `group-timeout(-expression)` or by a `MessageGroupStoreReaper` and is not applied to the normal `add/release/discard` operations.
Only this sub-element or `<expire-advice-chain/>` is allowed.
<26> Since _version 4.1_.
Allows the configuration of any `Advice` for the `forceComplete` operation.
It is initiated from a `group-timeout(-expression)` or by a `MessageGroupStoreReaper` and is not applied to the normal `add/release/discard` operations.
Only this sub-element or `<expire-transactional/>` is allowed.
A transaction `Advice` can also be configured here using the Spring `tx` namespace.
[IMPORTANT]
.Expiring Groups
=====
There are two attributes related to expiring (completely removing) groups.
When a group is expired, there is no record of it and if a new message arrives with the same correlation, a new group is started.
When a group is completed (without expiry), the empty group remains and late arriving messages are discarded.
Empty groups can be removed later using a `MessageGroupStoreReaper` in combination with the `empty-group-min-timeout` attribute.
`expire-groups-upon-completion` relates to "normal" completion - when the `ReleaseStrategy` releases the group.
This defaults to `false`.
If a group is not completed normally, but is released or discarded because of a timeout, the group is normally expired.
Since _version 4.1_, you can now control this behavior using `expire-groups-upon-timeout`; this defaults to `true` for backwards compatibility.
NOTE: When a group is timed out, the `ReleaseStrategy` is given one more opportunity to release the group; if it does so, and `expire-groups-upon-timeout` is false, then expiration is controlled by `expire-groups-upon-completion`.
If the group is not released by the release strategy during timeout, then the expiration is controlled by the `expire-groups-upon-timeout`.
Timed-out groups are either discarded, or a partial release occurs (based on `send-partial-result-on-expiry`).
=====
Using a `ref` attribute is generally recommended if a custom aggregator handler implementation may be referenced in other`<aggregator>` definitions.
However if a custom aggregator implementation is only being used by a single definition of the `<aggregator>`, you can use an inner bean definition (starting with version 1.0.3) to configure the aggregation POJO within the `<aggregator>` element:
[source,xml]
----
<aggregator input-channel="input" method="sum" output-channel="output">
<beans:bean class="org.foo.PojoAggregator"/>
</aggregator>
----
NOTE: Using both a `ref` attribute and an inner bean definition in the same `<aggregator>` configuration is not allowed, as it creates an ambiguous condition.
In such cases, an Exception will be thrown.
An example implementation of the aggregator bean looks as follows:
[source,java]
----
public class PojoAggregator {
public Long add(List<Long> results) {
long total = 0l;
for (long partialResult: results) {
total += partialResult;
}
return total;
}
}
----
An implementation of the completion strategy bean for the example above may be as follows:
[source,java]
----
public class PojoReleaseStrategy {
...
public boolean canRelease(List<Long> numbers) {
int sum = 0;
for (long number: numbers) {
sum += number;
}
return sum >= maxValue;
}
}
----
NOTE: Wherever it makes sense, the release strategy method and the aggregator method can be combined in a single bean.
An implementation of the correlation strategy bean for the example above may be as follows:
[source,java]
----
public class PojoCorrelationStrategy {
...
public Long groupNumbersByLastDigit(Long number) {
return number % 10;
}
}
----
For example, this aggregator would group numbers by some criterion (in our case the remainder after dividing by 10) and will hold the group until the sum of the numbers provided by the payloads exceeds a certain value.
NOTE: Wherever it makes sense, the release strategy method, correlation strategy method and the aggregator method can be combined in a single bean (all of them or any two).
_Aggregators and Spring Expression Language (SpEL)_
Since Spring Integration 2.0, the various strategies (correlation, release, and aggregation) may be handled with http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html[SpEL] which is recommended if the logic behind such _release strategy_ is relatively simple.
Let's say you have a legacy component that was designed to receive an array of objects.
We know that the default release strategy will assemble all aggregated messages in the List.
So now we have two problems.
First we need to extract individual messages from the list, and then we need to extract the payload of each message and assemble the array of objects (see code below).
[source,java]
----
public String[] processRelease(List<Message<String>> messages){
List<String> stringList = new ArrayList<String>();
for (Message<String> message : messages) {
stringList.add(message.getPayload());
}
return stringList.toArray(new String[]{});
}
----
However, with SpEL such a requirement could actually be handled relatively easily with a one-line expression, thus sparing you from writing a custom class and configuring it as a bean.
[source,xml]
----
<int:aggregator input-channel="aggChannel"
output-channel="replyChannel"
expression="#this.![payload].toArray()"/>
----
In the above configuration we are using a http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html#d0e12113[Collection Projection] expression to assemble a new collection from the payloads of all messages in the list and then transforming it to an Array, thus achieving the same result as the java code above.
The same expression-based approach can be applied when dealing with custom _Release_ and _Correlation_ strategies.
Instead of defining a bean for a custom `CorrelationStrategy` via the `correlation-strategy` attribute, you can implement your simple correlation logic via a SpEL expression and configure it via the `correlation-strategy-expression` attribute.
For example:
[source,xml]
----
correlation-strategy-expression="payload.person.id"
----
In the above example it is assumed that the payload has an attribute `person` with an `id` which is going to be used to correlate messages.
Likewise, for the `ReleaseStrategy` you can implement your release logic as a SpEL expression and configure it via the `release-strategy-expression` attribute.
The only difference is that since ReleaseStrategy is passed the List of Messages, the root object in the SpEL evaluation context is the List itself.
That List can be referenced as `#this` within the expression.
For example:
[source,xml]
----
release-strategy-expression="#this.size() gt 5"
----
In this example the root object of the SpEL Evaluation Context is the `MessageGroup` itself, and you are simply stating that as soon as there are more than 5 messages in this group, it should be released.
[[agg-and-group-to]]
====== Aggregator and Group Timeout
Starting with _version 4.0_, two new mutually exclusive attributes have been introduced: `group-timeout` and `group-timeout-expression` (see the description above).
There are some cases where it is needed to emit the aggregator result (or discard the group) after a timeout if the `ReleaseStrategy` doesn't _release_ when the current Message arrives.
For this purpose the `groupTimeout` option allows scheduling the `MessageGroup` to be forced complete:
[source,xml]
----
<aggregator input-channel="input" output-channel="output"
send-partial-result-on-expiry="true"
group-timeout-expression="size() ge 2 ? 10000 : -1"
release-strategy-expression="[0].headers.sequenceNumber == [0].headers.sequenceSize"/>
----
With this example, the normal _release_ will be possible if the aggregator receives the last message in sequence as defined by the `release-strategy-expression`.
If that specific message does not arrive, the `groupTimeout` will force the group complete after 10 seconds as long as the group contains at least 2 Messages.
The results of forcing the group complete depends on the `ReleaseStrategy` and the `send-partial-result-on-expiry`.
First, the release strategy is again consulted to see if a _normal_ release is to be made - while the group won't have changed, the `ReleaseStrategy` can decide to release the group at this time.
If the release strategy still does not release the group, it will be expired.
If `send-partial-result-on-expiry` is `true`, existing messages in the (partial) `MessageGroup` will be released as a normal aggregator reply Message to the `output-channel`, otherwise it will be discarded.
There is a difference between `groupTimeout` behavior and `MessageGroupStoreReaper` (see <<aggregator-config>>).
The reaper initiates forced completion for all `MessageGroup` s in the `MessageGroupStore` periodically.
The `groupTimeout` does it for each `MessageGroup` individually, if a new Message doesn't arrive during the `groupTimeout`.
Also, the reaper can be used to remove empty groups (empty groups are retained in order to discard late messages, if `expire-groups-upon-completion` is false).
[[aggregator-annotations]]
===== Configuring an Aggregator with Annotations
An aggregator configured using annotations would look like this.
[source,java]
----
public class Waiter {
...
@Aggregator <1>
public Delivery aggregatingMethod(List<OrderItem> items) {
...
}
@ReleaseStrategy <2>
public boolean releaseChecker(List<Message<?>> messages) {
...
}
@CorrelationStrategy <3>
public String correlateBy(OrderItem item) {
...
}
}
----
<1> An annotation indicating that this method shall be used as an aggregator.
Must be specified if this class will be used as an aggregator.
<2> An annotation indicating that this method shall be used as the release strategy of an aggregator.
If not present on any method, the aggregator will use the SequenceSizeReleaseStrategy.
<3> An annotation indicating that this method shall be used as the correlation strategy of an aggregator.
If no correlation strategy is indicated, the aggregator will use the HeaderAttributeCorrelationStrategy based on CORRELATION_ID.
All of the configuration options provided by the xml element are also available for the @Aggregator annotation.
The aggregator can be either referenced explicitly from XML or, if the @MessageEndpoint is defined on the class, detected automatically through classpath scanning.
[[reaper]]
==== Managing State in an Aggregator: MessageGroupStore
Aggregator (and some other patterns in Spring Integration) is a stateful pattern that requires decisions to be made based on a group of messages that have arrived over a period of time, all with the same correlation key.
The design of the interfaces in the stateful patterns (e.g.
`ReleaseStrategy`) is driven by the principle that the components (whether defined by the framework or a user) should be able to remain stateless.
All state is carried by the `MessageGroup` and its management is delegated to the `MessageGroupStore`.
[source,java]
----
public interface MessageGroupStore {
int getMessageCountForAllMessageGroups();
int getMarkedMessageCountForAllMessageGroups();
int getMessageGroupCount();
MessageGroup getMessageGroup(Object groupId);
MessageGroup addMessageToGroup(Object groupId, Message<?> message);
MessageGroup markMessageGroup(MessageGroup group);
MessageGroup removeMessageFromGroup(Object key, Message<?> messageToRemove);
MessageGroup markMessageFromGroup(Object key, Message<?> messageToMark);
void removeMessageGroup(Object groupId);
void registerMessageGroupExpiryCallback(MessageGroupCallback callback);
int expireMessageGroups(long timeout);
}
----
For more information please refer to the http://static.springsource.org/spring-integration/api/org/springframework/integration/store/MessageGroupStore.html[JavaDoc].
The `MessageGroupStore` accumulates state information in `MessageGroups` while waiting for a release strategy to be triggered, and that event might not ever happen.
So to prevent stale messages from lingering, and for volatile stores to provide a hook for cleaning up when the application shuts down, the `MessageGroupStore` allows the user to register callbacks to apply to its `MessageGroups` when they expire.
The interface is very straightforward:
[source,java]
----
public interface MessageGroupCallback {
void execute(MessageGroupStore messageGroupStore, MessageGroup group);
}
----
The callback has direct access to the store and the message group so it can manage the persistent state (e.g.
by removing the group from the store entirely).
The `MessageGroupStore` maintains a list of these callbacks which it applies, on demand, to all messages whose timestamp is earlier than a time supplied as a parameter (see the `registerMessageGroupExpiryCallback(..)` and `expireMessageGroups(..)` methods above).
The `expireMessageGroups` method can be called with a timeout value.
Any message older than the current time minus this value will be expired, and have the callbacks applied.
Thus it is the user of the store that defines what is meant by message group "expiry".
As a convenience for users, Spring Integration provides a wrapper for the message expiry in the form of a `MessageGroupStoreReaper`:
[source,xml]
----
<bean id="reaper" class="org...MessageGroupStoreReaper">
<property name="messageGroupStore" ref="messageStore"/>
<property name="timeout" value="30000"/>
</bean>
<task:scheduled-tasks scheduler="scheduler">
<task:scheduled ref="reaper" method="run" fixed-rate="10000"/>
</task:scheduled-tasks>
----
The reaper is a `Runnable`, and all that is happening in the example above is that the message group store's expire method is being called once every 10 seconds.
The timeout itself is 30 seconds.
NOTE: It is important to understand that the 'timeout' property of the `MessageGroupStoreReaper` is an approximate value and is impacted by the the rate of the task scheduler since this property will only be checked on the next scheduled execution of the `MessageGroupStoreReaper` task.
For example if the timeout is set for 10 min, but the `MessageGroupStoreReaper` task is scheduled to run every 60 min and the last execution of the `MessageGroupStoreReaper` task happened 1 min before the timeout, the `MessageGroup` will not expire for the next 59 min.
So it is recommended to set the rate at least equal to the value of the timeout or shorter.
In addition to the reaper, the expiry callbacks are invoked when the application shuts down via a lifecycle callback in the `AbstractCorrelatingMessageHandler`.
The `AbstractCorrelatingMessageHandler` registers its own expiry callback, and this is the link with the boolean flag` send-partial-result-on-expiry` in the XML configuration of the aggregator.
If the flag is set to true, then when the expiry callback is invoked, any unmarked messages in groups that are not yet released can be sent on to the output channel.
[IMPORTANT]
=====
When using a `MessageGroupStoreReaper`, it is generally recommended to use a separate `MessageStore` for each correlating endpoint.
Otherwise, unexpected results may occur because one endpoint may remove another endpoint's groups.
Some `MessageStore` implementations allow using the same physical resources, by partitioning the data; for example, the `JdbcMessageStore` has a `region` property; the `MongoDbMessageStore` has a `collectionName` property.
For more information about `MessageStore` interface and its implementations, please read <<message-store>>.
=====

662
src/reference/asciidoc/amqp.adoc Normal file
View File

@@ -0,0 +1,662 @@
[[amqp]]
== AMQP Support
[[amqp-introduction]]
=== Introduction
Spring Integration provides Channel Adapters for receiving and sending messages using the Advanced Message Queuing Protocol (AMQP).
The following adapters are available:
* Inbound Channel Adapter
* Outbound Channel Adapter
* Inbound Gateway
* Outbound Gateway
Spring Integration also provides a point-to-point Message Channel as well as a publish/subscribe Message Channel backed by AMQP Exchanges and Queues.
In order to provide AMQP support, Spring Integration relies on Spring AMQP (http://www.springsource.org/spring-amqp[http://www.springsource.org/spring-amqp]) which "applies core Spring concepts to the development of AMQP-based messaging solutions".
Spring AMQP provides similar semantics as Spring JMS (http://static.springsource.org/spring/docs/current/spring-framework-reference/html/jms.html[http://static.springsource.org/spring/docs/current/spring-framework-reference/html/jms.html]).
Whereas the provided AMQP Channel Adapters are intended for unidirectional Messaging (send or receive) only, Spring Integration also provides inbound and outbound AMQP Gateways for request/reply operations.
[TIP]
=====
Please familiarize yourself with the reference documentation of the Spring AMQP project as well.
It provides much more in-depth information regarding Spring's integration with AMQP in general and RabbitMQ in particular.
You can find the documentation at: http://static.springsource.org/spring-amqp/reference/html/[http://static.springsource.org/spring-amqp/reference/html/]
=====
[[amqp-inbound-channel-adapter]]
=== Inbound Channel Adapter
A configuration sample for an AMQP Inbound Channel Adapter is shown below.
[source,xml]
----
<int-amqp:inbound-channel-adapter
id="inboundAmqp" <1>
channel="inboundChannel" <2>
queue-names="si.test.queue" <3>
acknowledge-mode="AUTO" <4>
advice-chain="" <5>
channel-transacted="" <6>
concurrent-consumers="" <7>
connection-factory="" <8>
error-channel="" <9>
expose-listener-channel="" <10>
header-mapper="" <11>
mapped-request-headers="" <12>
listener-container="" <13>
message-converter="" <14>
message-properties-converter="" <15>
phase="" <16>
prefetch-count="" <17>
receive-timeout="" <18>
recovery-interval="" <19>
missing-queues-fatal="" <20>
shutdown-timeout="" <21>
task-executor="" <22>
transaction-attribute="" <23>
transaction-manager="" <24>
tx-size="" /> <25>
----
<1> Unique ID for this adapter.
_Optional_.
<2> Message Channel to which converted Messages should be sent.
_Required_.
<3> Names of the AMQP Queues from which Messages should be consumed (comma-separated list)._Required_.
<4> Acknowledge Mode for the `MessageListenerContainer`.
When set to MANUAL, the delivery tag and channel are provided in message headers `amqp_deliveryTag` and `amqp_channel` respectively; the user application is responsible for acknowledgement.
NONE means no acknowledgements (autoAck); AUTO means the adapter's container will acknowledge when the downstream flow completes._Optional (Defaults to AUTO)_ see <<amqp-inbound-ack>>.
<5> Extra AOP Advice(s) to handle cross cutting behavior associated with this Inbound Channel Adapter.
_Optional_.
<6> Flag to indicate that channels created by this component will be transactional.
Ff true, tells the framework to use a transactional channel and to end all operations (send or receive) with a commit or rollback depending on the outcome, with an exception signalling a rollback.
_Optional (Defaults to false)_.
<7> Specify the number of concurrent consumers to create.
Default is 1.
Raising the number of concurrent consumers is recommended in order to scale the consumption of messages coming in from a queue.
However, note that any ordering guarantees are lost once multiple consumers are registered.
In general, stick with 1 consumer for low-volume queues.
_Optional_.
<8> Bean reference to the RabbitMQ ConnectionFactory.
_Optional (Defaults to 'connectionFactory')_.
<9> Message Channel to which error Messages should be sent.
_Optional_.
<10> Shall the listener channel (com.rabbitmq.client.Channel) be exposed to a registered `ChannelAwareMessageListener`.
_Optional (Defaults to true)_.
<11> A reference to an `AmqpHeaderMapper` to use when receiving AMQP Messages.
_Optional_.
By default only standard AMQP properties (e.g.
`contentType`) will be copied to Spring Integration `MessageHeaders`.
Any user-defined headers within the AMQP `MessageProperties` will NOT be copied to the Message by the default `DefaultAmqpHeaderMapper`.
Not allowed if 'request-header-names' is provided.
<12> Comma-separated list of names of AMQP Headers to be mapped from the AMQP request into the MessageHeaders.
This can only be provided if the 'header-mapper' reference is not provided.
The values in this list can also be simple patterns to be matched against the header names (e.g.
"\*" or "foo*, bar" or "*foo").
<13> Reference to the `SimpleMessageListenerContainer` to use for receiving AMQP Messages.
If this attribute is provided, then no other attribute related to the listener container configuration should be provided.
In other words, by setting this reference, you must take full responsibility of the listener container configuration.
The only exception is the MessageListener itself.
Since that is actually the core responsibility of this Channel Adapter implementation, the referenced listener container must NOT already have its own MessageListener configured.
_Optional_.
<14> The MessageConverter to use when receiving AMQP Messages.
_Optional_.
<15> The MessagePropertiesConverter to use when receiving AMQP Messages.
_Optional_.
<16> Specify the phase in which the underlying `SimpleMessageListenerContainer` should be started and stopped.
The startup order proceeds from lowest to highest, and the shutdown order is the reverse of that.
By default this value is Integer.MAX_VALUE meaning that this container starts as late as possible and stops as soon as possible.
_Optional_.
<17> Tells the AMQP broker how many messages to send to each consumer in a single request.
Often this can be set quite high to improve throughput.
It should be greater than or equal to the transaction size (see attribute "tx-size")._Optional (Defaults to 1)_.
<18> Receive timeout in milliseconds.
_Optional (Defaults to 1000)_.
<19> Specifies the interval between recovery attempts of the underlying `SimpleMessageListenerContainer` (in milliseconds)._Optional (Defaults to 5000)_.
<20> If 'true', and none of the queues are available on the broker, the container will throw a fatal exception during startup and will stop if the queues are deleted when the container is running (after making 3 attempts to passively declare the queues).
If false, the container will not throw an exception and go into recovery mode, attempting to restart according to the `revcovery-interval`.
_Optional (Defaults to `true`)_.
<21> The time to wait for workers in milliseconds after the underlying `SimpleMessageListenerContainer` is stopped, and before the AMQP connection is forced closed.
If any workers are active when the shutdown signal comes they will be allowed to finish processing as long as they can finish within this timeout.
Otherwise the connection is closed and messages remain unacked (if the channel is transactional).
Defaults to 5000 milliseconds._Optional (Defaults to 5000)_.
<22> By default, the underlying `SimpleMessageListenerContainer` uses a SimpleAsyncTaskExecutor implementation, that fires up a new Thread for each task, executing it asynchronously.
By default, the number of concurrent threads is unlimited.
*NOTE:* This implementation does not reuse threads.
Consider a thread-pooling TaskExecutor implementation as an alternative.
_Optional (Defaults to SimpleAsyncTaskExecutor)_.
<23> By default the underlying `SimpleMessageListenerContainer` creates a new instance of the DefaultTransactionAttribute (takes the EJB approach to rolling back on runtime, but not checked exceptions.
_Optional (Defaults to DefaultTransactionAttribute)_.
<24> Sets a Bean reference to an external `PlatformTransactionManager` on the underlying SimpleMessageListenerContainer.
The transaction manager works in conjunction with the "channel-transacted" attribute.
If there is already a transaction in progress when the framework is sending or receiving a message, and the channelTransacted flag is true, then the commit or rollback of the messaging transaction will be deferred until the end of the current transaction.
If the channelTransacted flag is false, then no transaction semantics apply to the messaging operation (it is auto-acked).
For further information see chapter 1.9 of the Spring AMQP reference guide: http://static.springsource.org/spring-amqp/docs/1.0.x/reference/html/#d0e525 _Optional_.
<25> Tells the `SimpleMessageListenerContainer` how many messages to process in a single transaction (if the channel is transactional).
For best results it should be less than or equal to the set "prefetch-count".
_Optional (Defaults to 1)_.
[NOTE]
.container
=====
Note that when configuring an external container, you cannot use the *Spring AMQP* namespace to define the container.
This is because the namespace requires at least one `<listener/>` element.
In this environment, the listener is internal to the adapter.
For this reason, you must define the container using a normal Spring `<bean/>` definition, such as:
[source,xml]
----
<bean id="container"
class="org.springframework.amqp.rabbit.listener.SimpleMessageListenerContainer">
<property name="connectionFactory" ref="connectionFactory" />
<property name="queueNames" value="foo.queue" />
<property name="defaultRequeueRejected" value="false"/>
</bean>
----
=====
IMPORTANT: Even though the Spring Integration JMS and AMQP support is very similar, important differences exist.
The JMS Inbound Channel Adapter is using a JmsDestinationPollingSource under the covers and expects a configured Poller.
The AMQP Inbound Channel Adapter on the other side uses a`SimpleMessageListenerContainer` and is message driven.
In that regard it is more similar to the JMS Message Driven Channel Adapter.
[[amqp-inbound-gateway]]
=== Inbound Gateway
The inbound gateway supports all the attributes on the inbound channel adapter (except 'channel' is replaced by 'request-channel'), plus some additional attributes:
[source,xml]
----
<int-amqp:inbound-gateway
id="inboundGateway" <1>
request-channel="myRequestChannel" <2>
header-mapper="" <3>
mapped-request-headers="" <4>
mapped-reply-headers="" <5>
reply-channel="myReplyChannel" <6>
reply-timeout="1000" /> <7>
----
<1> Unique ID for this adapter.
_Optional_.
<2> Message Channel to which converted Messages should be sent.
_Required_.
<3> A reference to an `AmqpHeaderMapper` to use when receiving AMQP Messages.
_Optional_.
By default only standard AMQP properties (e.g.
`contentType`) will be copied to and from Spring Integration `MessageHeaders`.
Any user-defined headers within the AMQP`MessageProperties` will NOT be copied to or from an AMQP Message by the default `DefaultAmqpHeaderMapper`.
Not allowed if 'request-header-names' or 'reply-header-names' is provided.
<4> Comma-separated list of names of AMQP Headers to be mapped from the AMQP request into the `MessageHeaders`.
This can only be provided if the 'header-mapper' reference is not provided.
The values in this list can also be simple patterns to be matched against the header names (e.g.
"\*" or "foo*, bar" or "*foo").
<5> Comma-separated list of names of `MessageHeaders` to be mapped into the AMQP Message Properties of the AMQP reply message.
All standard Headers (e.g., `contentType`) will be mapped to AMQP Message Properties while user-defined headers will be mapped to the 'headers' property.
This can only be provided if the 'header-mapper' reference is not provided.
The values in this list can also be simple patterns to be matched against the header names (e.g.
"\*" or "foo*, bar" or "*foo").
<6> Message Channel where reply Messages will be expected.
_Optional_.
<7> Used to set the `receiveTimeout` on the underlying `org.springframework.integration.core.MessagingTemplate` for receiving messages from the reply channel.
If not specified this property will default to "1000" (1 second).
Only applies if the container thread hands off to another thread before the reply is sent.
See the note in <<amqp-inbound-channel-adapter>> about configuring the `listener-container` attribute.
[[amqp-inbound-ack]]
=== Inbound Endpoint Acknowledge Mode
By default the inbound endpoints use acknowledge mode `AUTO`, which means the container automatically _acks_ the message when the downstream integration flow completes (or a message is handed off to another thread using a `QueueChannel` or `ExecutorChannel`).
Setting the mode to `NONE` configures the consumer such that acks are not used at all (the broker automatically acks the message as soon as it is sent).
Setting the mode to`MANUAL` allows user code to ack the message at some other point during processing.
To support this, with this mode, the endpoints provide the `Channel` and `deliveryTag` in the `amqp_channel` and `amqp_deliveryTag` headers respectively.
You can perform any valid rabbit command on the `Channel` but, generally, only `basicAck` and `basicNack` (or `basicReject`) would be used.
In order to not interfere with the operation of the container, you should not retain a reference to the channel and just use it in the context of the current message.
NOTE: Since the `Channel` is a reference to a "live" object, it cannot be serialized and will be lost if a message is persisted.
This is an example of how you might use `MANUAL` acknowledgement:
[source,java]
----
@ServiceActivator(inputChannel = "foo", outputChannel = "bar")
public Object handle(@Payload String payload, @Header(AmqpHeaders.CHANNEL) Channel channel,
@Header(AmqpHeaders.DELIVERY_TAG) Long deliveryTag) throws Exception {
// Do some processing
if (allOK) {
channel.basicAck(deliveryTag, false);
// perhaps do some more processing
}
else {
channel.basicNack(deliveryTag, false, true);
}
return someResultForDownStreamProcessing;
}
----
[[amqp-outbound-channel-adapter]]
=== Outbound Channel Adapter
A configuration sample for an AMQP Outbound Channel Adapter is shown below.
[source,xml]
----
<int-amqp:outbound-channel-adapter id="outboundAmqp" <1>
channel="outboundChannel" <2>
amqp-template="myAmqpTemplate" <3>
exchange-name="" <4>
exchange-name-expression="" <5>
order="1" <6>
routing-key="" <7>
routing-key-expression="" <8>
default-delivery-mode"" <9>
confirm-correlation-expression="" <10>
confirm-ack-channel="" <11>
confirm-nack-channel="" <12>
return-channel="" <13>
header-mapper="" <14>
mapped-request-headers="" <15>
lazy-connect="true" /> <16>
----
<1> Unique ID for this adapter.
_Optional_.
<2> Message Channel to which Messages should be sent in order to have them converted and published to an AMQP Exchange.
_Required_.
<3> Bean Reference to the configured AMQP Template _Optional (Defaults to "amqpTemplate")_.
<4> The name of the AMQP Exchange to which Messages should be sent.
If not provided, Messages will be sent to the default, no-name Exchange.
Mutually exclusive with 'exchange-name-expression'.
_Optional_.
<5> A SpEL expression that is evaluated to determine the name of the AMQP Exchange to which Messages should be sent, with the message as the root object.
If not provided, Messages will be sent to the default, no-name Exchange.
Mutually exclusive with 'exchange-name'.
_Optional_.
<6> The order for this consumer when multiple consumers are registered thereby enabling load- balancing and/or failover.
_Optional (Defaults to Ordered.LOWEST_PRECEDENCE [=Integer.MAX_VALUE])_.
<7> The fixed routing-key to use when sending Messages.
By default, this will be an empty String.
Mutually exclusive with 'routing-key-expression'._Optional_.
<8> A SpEL expression that is evaluated to determine the routing-key to use when sending Messages, with the message as the root object (e.g.
'payload.key').
By default, this will be an empty String.
Mutually exclusive with 'routing-key'.
_Optional_.
<9> The default delivery mode for messages; 'PERSISTENT' or 'NON_PERSISTENT'.
Overridden if the 'header-mapper' sets the delivery mode.
The 'DefaultHeaderMapper' sets the value if the Spring Integration message header `amqp_deliveryMode` is present.
If this attribute is not supplied and the header mapper doesn't set it, the default depends on the underlying spring-amqp 'MessagePropertiesConverter' used by the 'RabbitTemplate'.
If that is not customized at all, the default is 'PERSISTENT'.
_Optional_.
<10> An expression defining correlation data.
When provided, this configures the underlying amqp template to receive publisher confirms.
Requires a dedicated`RabbitTemplate` and a `CachingConnectionFactory` with the `publisherConfirms` property set to `true`.
When a publisher confirm is received, and correlation data is supplied, it is written to either the confirm-ack-channel, or the confirm-nack-channel, depending on the confirmation type.
The payload of the confirm is the correlation data as defined by this expression and the message will have a header 'amqp_publishConfirm' set to true (ack) or false (nack).
Examples: "headers['myCorrelationData']", "payload".
_Optional_.
Starting with _version 4.1_ the `amqp_publishConfirmNackCause` message header has been added.
It contains the `cause` of a 'nack' for publisher confirms.
<11> The channel to which positive (ack) publisher confirms are sent; payload is the correlation data defined by the _confirm-correlation-expression_.
_Optional, default=nullChannel_.
<12> The channel to which negative (nack) publisher confirms are sent; payload is the correlation data defined by the _confirm-correlation-expression_.
_Optional, default=nullChannel_.
<13> The channel to which returned messages are sent.
When provided, the underlying amqp template is configured to return undeliverable messages to the adapter.
The message will be constructed from the data received from amqp, with the following additional headers: _amqp_returnReplyCode,
amqp_returnReplyText, amqp_returnExchange, amqp_returnRoutingKey_.
_Optional_.
<14> A reference to an `AmqpHeaderMapper` to use when sending AMQP Messages.
_Optional_.
By default only standard AMQP properties (e.g.
`contentType`) will be copied to the Spring Integration `MessageHeaders`.
Any user-defined headers will NOT be copied to the Message by the default`DefaultAmqpHeaderMapper`.
Not allowed if 'request-header-names' is provided.
<15> Comma-separated list of names of AMQP Headers to be mapped from the `MessageHeaders` to the AMQP Message.
Not allowed if the 'header-mapper' reference is provided.
The values in this list can also be simple patterns to be matched against the header names (e.g.
"\*" or "foo*, bar" or "*foo").
<16> When set to `false`, the endpoint will attempt to connect to the broker during application context initialization.
This allows "fail fast" detection of bad configuration, but will also cause initialization to fail if the broker is down.
When true (default), the connection is established (if it doesn't already exist because some other component established it) when the first message is sent.
[IMPORTANT]
.return-channel
=====
Using a `return-channel` requires a `RabbitTemplate` with the `mandatory` property set to `true`, and a `CachingConnectionFactory` with the `publisherReturns` property set to `true`.
When using multiple outbound endpoints with returns, a separate `RabbitTemplate` is needed for each endpoint.
=====
[[amqp-outbound-gateway]]
=== Outbound Gateway
A configuration sample for an AMQP Outbound Gateway is shown below.
[source,xml]
----
<int-amqp:outbound-gateway id="inboundGateway" <1>
request-channel="myRequestChannel" <2>
amqp-template="" <3>
exchange-name="" <4>
exchange-name-expression="" <5>
order="1" <6>
reply-channel="" <7>
reply-channel="" <8>
requires-reply="" <9>
routing-key="" <10>
routing-key-expression="" <11>
default-delivery-mode"" <12>
return-channel="" <13>
lazy-connect="true" /> <14>
----
<1> Unique ID for this adapter.
_Optional_.
<2> Message Channel to which Messages should be sent in order to have them converted and published to an AMQP Exchange.
_Required_.
<3> Bean Reference to the configured AMQP Template _Optional (Defaults to "amqpTemplate")_.
<4> The name of the AMQP Exchange to which Messages should be sent.
If not provided, Messages will be sent to the default, no-name Exchange.
Mutually exclusive with 'exchange-name-expression'.
_Optional_.
<5> A SpEL expression that is evaluated to determine the name of the AMQP Exchange to which Messages should be sent, with the message as the root object.
If not provided, Messages will be sent to the default, no-name Exchange.
Mutually exclusive with 'exchange-name'.
_Optional_.
<6> The order for this consumer when multiple consumers are registered thereby enabling load- balancing and/or failover.
_Optional (Defaults to Ordered.LOWEST_PRECEDENCE [=Integer.MAX_VALUE])_.
<7> Message Channel to which replies should be sent after being received from an AQMP Queue and converted._Optional_.
<8> The time the gateway will wait when sending the reply message to the `reply-channel`.
This only applies if the `reply-channel` can block - such as a `QueueChannel` with a capacity limit that is currently full.
Default: infinity.
<9> When `true`, the gateway will throw an exception if no reply message is received within the `AmqpTemplate`'s `replyTimeout` property.
Default: `true`.
<10> The routing-key to use when sending Messages.
By default, this will be an empty String.
Mutually exclusive with 'routing-key-expression'_Optional_.
<11> A SpEL expression that is evaluated to determine the routing-key to use when sending Messages, with the message as the root object (e.g.
'payload.key').
By default, this will be an empty String.
Mutually exclusive with 'routing-key'.
_Optional_.
<12> The default delivery mode for messages; 'PERSISTENT' or 'NON_PERSISTENT'.
Overridden if the 'header-mapper' sets the delivery mode.
The 'DefaultHeaderMapper' sets the value if the Spring Integration message header `amqp_deliveryMode` is present.
If this attribute is not supplied and the header mapper doesn't set it, the default depends on the underlying spring-amqp 'MessagePropertiesConverter' used by the 'RabbitTemplate'.
If that is not customized at all, the default is 'PERSISTENT'._Optional_.
<13> The channel to which returned messages are sent.
When provided, the underlying amqp template is configured to return undeliverable messages to the gateway.
The message will be constructed from the data received from amqp, with the following additional headers: _amqp_returnReplyCode,
amqp_returnReplyText, amqp_returnExchange, amqp_returnRoutingKey_.
_Optional_.
<14> When set to `false`, the endpoint will attempt to connect to the broker during application context initialization.
This allows "fail fast" detection of bad configuration, but will also cause initialization to fail if the broker is down.
When true (default), the connection is established (if it doesn't already exist because some other component established it) when the first message is sent.
[IMPORTANT]
.return-channel
=====
Using a `return-channel` requires a `RabbitTemplate` with the `mandatory` property set to `true`, and a `CachingConnectionFactory` with the `publisherReturns` property set to `true`.
When using multiple outbound endpoints with returns, a separate `RabbitTemplate` is needed for each endpoint.
=====
IMPORTANT: The underlying `AmqpTemplate` has a default `replyTimeout` of 5 seconds.
If you require a longer timeout, it must be configured on the `template`.
[[amqp-channels]]
=== AMQP Backed Message Channels
There are two Message Channel implementations available.
One is point-to-point, and the other is publish/subscribe.
Both of these channels provide a wide range of configuration attributes for the underlying AmqpTemplate and SimpleMessageListenerContainer as you have seen on the Channel Adapters and Gateways.
However, the examples we'll show here are going to have minimal configuration.
Explore the XML schema to view the available attributes.
A point-to-point channel would look like this:
[source,xml]
----
<int-amqp:channel id="p2pChannel"/>
----
Under the covers a Queue named "si.p2pChannel" would be declared, and this channel will send to that Queue (technically by sending to the no-name Direct Exchange with a routing key that matches this Queue's name).
This channel will also register a consumer on that Queue.
If for some reason, you want the Queue to be "pollable" instead of message-driven, then simply provide the "message-driven" flag with a value of false:
[source,xml]
----
<int-amqp:channel id="p2pPollableChannel" message-driven="false"/>
----
A publish/subscribe channel would look like this:
[source,xml]
----
<int-amqp:publish-subscribe-channel id="pubSubChannel"/>
----
Under the covers a Fanout Exchange named "si.fanout.pubSubChannel" would be declared, and this channel will send to that Fanout Exchange.
This channel will also declare a server-named exclusive, autodelete, non-durable Queue and bind that to the Fanout Exchange while registering a consumer on that Queue to receive Messages.
There is no "pollable" option for a publish-subscribe-channel; it must be message-driven.
Starting with _version 4.1_ AMQP Backed Message Channels, alongside with `channel-transacted`, support `template-channel-transacted` to separate `transactional` configuration for the `AbstractMessageListenerContainer` and for the `RabbitTemplate`.
Note, previously, the `channel-transacted` was `true` by default, now it changed to `false` as standard default value for the `AbstractMessageListenerContainer`.
[[amqp-message-headers]]
=== AMQP Message Headers
The Spring Integration AMPQ Adapters will map standard AMQP properties automatically.
These properties will be copied by default to and from Spring Integration `MessageHeaders` using the http://static.springsource.org/spring-integration/api/org/springframework/integration/amqp/support/DefaultAmqpHeaderMapper.html[DefaultAmqpHeaderMapper].
Of course, you can pass in your own implementation of AMQP specific header mappers, as the adapters have respective properties to support that.
Any user-defined headers within the AMQP http://static.springsource.org/spring-amqp/api/org/springframework/amqp/core/MessageProperties.html[MessageProperties] will NOT be copied to or from an AMQP Message, unless explicitly specified by the _requestHeaderNames_ and/or _replyHeaderNames_ properties of the `DefaultAmqpHeaderMapper`.
TIP: When mapping user-defined headers, the values can also contain simple wildcard patterns (e.g. "foo*" or "*foo") to be matched.
For example, if you need to copy all user-defined headers simply use the wild-card character `*`.
Starting with _version 4.1_, the `AbstractHeaderMapper` (a `DefaultAmqpHeaderMapper` superclass) allows the `NON_STANDARD_HEADERS` token to be configured for the _requestHeaderNames_ and/or _replyHeaderNames_ properties (in addition to existing `STANDARD_REQUEST_HEADERS` and `STANDARD_REPLY_HEADERS`) to map all user-defined headers.
Note, it is recommended to use the combination like this `STANDARD_REPLY_HEADERS, NON_STANDARD_HEADERS` instead of generic `*`, to avoid mapping of _request_ headers to the reply.
Class `org.springframework.amqp.support.AmqpHeaders` identifies the default headers that will be used by the `DefaultAmqpHeaderMapper`:
* amqp_appId
* amqp_clusterId
* amqp_contentEncoding
* amqp_contentLength
* content-type
* amqp_correlationId
* amqp_deliveryMode
* amqp_deliveryTag
* amqp_expiration
* amqp_messageCount
* amqp_messageId
* amqp_receivedExchange
* amqp_receivedRoutingKey
* amqp_redelivered
* amqp_replyTo
* amqp_timestamp
* amqp_type
* amqp_userId
* amqp_publishConfirm
* amqp_publishConfirmNackCause
* amqp_returnReplyCode
* amqp_returnReplyText
* amqp_returnExchange
* amqp_returnRoutingKey
=== AMQP Samples
To experiment with the AMQP adapters, check out the samples available in the Spring Integration Samples Git repository at:
* https://github.com/SpringSource/spring-integration-samples[https://github.com/SpringSource/spring-integration-samples]
Currently there is one sample available that demonstrates the basic functionality of the Spring Integration AMQP Adapter using an Outbound Channel Adapter and an Inbound Channel Adapter.
As AMQP Broker implementation the sample uses RabbitMQ (http://www.rabbitmq.com/[http://www.rabbitmq.com/]).
NOTE: In order to run the example you will need a running instance of RabbitMQ.
A local installation with just the basic defaults will be sufficient.
For detailed RabbitMQ installation procedures please visit: http://www.rabbitmq.com/install.html[http://www.rabbitmq.com/install.html]
Once the sample application is started, you enter some text on the command prompt and a message containing that entered text is dispatched to the AMQP queue.
In return that message is retrieved via Spring Integration and then printed to the console.
The image belows illustrates the basic set of Spring Integration components used in this sample.
.The Spring Integration graph of the AMQP sample
image::images/spring-integration-amqp-sample-graph.png[]

52
src/reference/asciidoc/bridge.adoc Normal file
View File

@@ -0,0 +1,52 @@
[[bridge]]
=== Messaging Bridge
[[bridge-introduction]]
==== Introduction
A Messaging Bridge is a relatively trivial endpoint that simply connects two Message Channels or Channel Adapters.
For example, you may want to connect a `PollableChannel` to a `SubscribableChannel` so that the subscribing endpoints do not have to worry about any polling configuration.
Instead, the Messaging Bridge provides the polling configuration.
By providing an intermediary poller between two channels, a Messaging Bridge can be used to throttle inbound Messages.
The poller's trigger will determine the rate at which messages arrive on the second channel, and the poller's "maxMessagesPerPoll" property will enforce a limit on the throughput.
Another valid use for a Messaging Bridge is to connect two different systems.
In such a scenario, Spring Integration's role would be limited to making the connection between these systems and managing a poller if necessary.
It is probably more common to have at least a _Transformer_ between the two systems to translate between their formats, and in that case, the channels would be provided as the 'input-channel' and 'output-channel' of a Transformer endpoint.
If data format translation is not required, the Messaging Bridge may indeed be sufficient.
[[bridge-namespace]]
==== Configuring Bridge
The <bridge> element is used to create a Messaging Bridge between two Message Channels or Channel Adapters.
Simply provide the "input-channel" and "output-channel" attributes:
[source,xml]
----
<int:bridge input-channel="input" output-channel="output"/>
----
As mentioned above, a common use case for the Messaging Bridge is to connect a `PollableChannel` to a `SubscribableChannel`, and when performing this role, the Messaging Bridge may also serve as a throttler:
[source,xml]
----
<int:bridge input-channel="pollable" output-channel="subscribable">
<int:poller max-messages-per-poll="10" fixed-rate="5000"/>
</int:bridge>
----
Connecting Channel Adapters is just as easy.
Here is a simple echo example between the "stdin" and "stdout" adapters from Spring Integration's "stream" namespace.
[source,xml]
----
<int-stream:stdin-channel-adapter id="stdin"/>
<int-stream:stdout-channel-adapter id="stdout"/>
<int:bridge id="echo" input-channel="stdin" output-channel="stdout"/>
----
Of course, the configuration would be similar for other (potentially more useful) Channel Adapter bridges, such as File to JMS, or Mail to File.
The various Channel Adapters will be discussed in upcoming chapters.
NOTE: If no 'output-channel' is defined on a bridge, the reply channel provided by the inbound Message will be used, if available.
If neither output or reply channel is available, an Exception will be thrown.

161
src/reference/asciidoc/chain.adoc Normal file
View File

@@ -0,0 +1,161 @@
[[chain]]
=== Message Handler Chain
[[chain-introduction]]
==== Introduction
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.
This can lead to a much simpler configuration when several handlers need to be connected in a fixed, linear progression.
For example, it is fairly common to provide a Transformer before other components.
Similarly, when providing a _Filter_ before some other component in a chain, you are essentially creating a http://www.eaipatterns.com/MessageSelector.html[Selective Consumer].
In either case, the chain only requires a single `input-channel` and a single `output-channel` eliminating the need to define channels for each individual component.
TIP: Spring Integration's `Filter` provides a boolean property `throwExceptionOnRejection`.
When providing multiple Selective Consumers on the same point-to-point channel with different acceptance criteria, this value should be set to 'true' (the default is false) so that the dispatcher will know that the Message was rejected and as a result will attempt to pass the Message on to other subscribers.
If the Exception were not thrown, then it would appear to the dispatcher as if 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, then the Filter's 'discard-channel' might be useful since it does give you a chance to perform some operation with the dropped message (e.g.
send to a JMS queue or simply write 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 will be expanded into a linear setup of the listed endpoints, separated by anonymous channels.
The reply channel header will not be taken into account within the chain: only after the last handler is invoked will the resulting message be forwarded on to the reply channel or the chain's output channel.
Because of this setup all handlers except the last required to implement the MessageProducer interface (which provides a 'setOutputChannel()' method).
The last handler only needs an output channel if the outputChannel on the MessageHandlerChain is set.
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, but if not available, the chain handler will check for a reply channel header on the inbound Message as a fallback.
In most cases there is no need to implement MessageHandlers yourself.
The next section will focus on namespace support for the chain element.
Most Spring Integration endpoints, like Service Activators and Transformers, are suitable for use within a `MessageHandlerChain`.
[[chain-namespace]]
==== Configuring a Chain
The <chain> element provides an `input-channel` attribute, and 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.
[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="foo" value="bar"/>
</int:header-enricher>
<int:service-activator ref="someService" method="someMethod"/>
</int:chain>
----
The <header-enricher> element used in the above example will set a message header named "foo" with a value of "bar" 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 obviously a simpler option.
The <chain> can be configured as the last 'black-box' consumer of the message flow.
For this solution it is enough to put at the end of the <chain> some <outbound-channel-adapter>:
[source,xml]
----
<int:chain input-channel="input">
<si-xml:marshalling-transformer marshaller="marshaller" result-type="StringResult" />
<int:service-activator ref="someService" method="someMethod"/>
<int:header-enricher>
<int:header name="foo" value="bar"/>
</int:header-enricher>
<int:logging-channel-adapter level="INFO" log-full-message="true"/>
</int:chain>
----
_Disallowed Attributes and Elements_
It is important to note that 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.
[IMPORTANT]
=====
For the _Spring Integration_ core components, the XML Schema itself will enforce 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_.
The XML namespace parser will throw an `BeanDefinitionParsingException` if you try to use disallowed attributes and elements.
=====
_'id' Attribute_
Beginning with Spring Integration 3.0, if a chain element is given an _id_, the bean name for the element is a combination of the chain's _id_ and the _id_ of the element itself.
Elements without an _id_ are not registered as beans, but they are given `componentName` s that include the chain id.
For example:
[source,xml]
----
<int:chain id="fooChain" input-channel="input">
<int:service-activator id="fooService" ref="someService" method="someMethod"/>
<int:object-to-json-transformer/>
</int:chain>
----
* The `<chain>` root element has an _id_ 'fooChain'.
So, the `AbstractEndpoint` implementation (`PollingConsumer` or `EventDrivenConsumer`, depending on the _input-channel_ type) bean takes this value as it's bean name.
* The `MessageHandlerChain` bean acquires a bean alias 'fooChain.handler', which allows direct access to this bean from the `BeanFactory`.
* The `<service-activator>` is not a fully-fledged Messaging Endpoint (`PollingConsumer` or `EventDrivenConsumer`) - it is simply a `MessageHandler` within the `<chain>`.
In this case, the bean name registered with the `BeanFactory` is 'fooChain$child.fooService.handler'.
* The _componentName_ of this `ServiceActivatingHandler` takes the same value, but without the '.handler' suffix - 'fooChain$child.fooService'.
* The last `<chain>` sub-component, `<object-to-json-transformer>`, doesn't have an _id_ attribute.
Its _componentName_ is based on its position in the `<chain>`.
In this case, it is 'fooChain$child#1'.
(The final element of the name is the order within the chain, beginning with '#0').
Note, this transformer isn't registered as a bean within the application context, so, it doesn't get a _beanName_, however its _componentName_ has a value which is useful for logging etc.
The _id_ attribute for `<chain>` elements allows them to be eligible for <<jmx-mbean-exporter,JMX export>> and they are trackable via <<message-history,Message History>>.
They can also be accessed from the `BeanFactory` using the appropriate bean name as discussed above.
TIP: It is useful to provide an explicit _id_ attribute on `<chain>` s to simplify the identification of sub-components in logs, and to provide access to them from the `BeanFactory` etc.
_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 utilize a Messaging Gateway by including a <gateway> element.
For example:
[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 above example the _nested-chain-a_ will be 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_ will be made after header enrichment and then it will come back to finish execution in _nested-chain-b_.
Finally the flow returns to the _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 simple takes the message in its current state and places it on the channel defined via the `request-channel` attribute.
When the downstream flow initiated by that gateway completes, a `Message` will be returned to the gateway and continue its journey within the current chain.

178
src/reference/asciidoc/changes-1.0-2.0.adoc Normal file
View File

@@ -0,0 +1,178 @@
[[migration-1.0-2.0]]
=== Changes between 1.0 and 2.0
For a detailed migration guide in regards to upgrading an existing application that uses Spring Integration older than version 2.0, please see:
null
[[migration-spring-30-support]]
==== Spring 3 support
Spring Integration 2.0 is built on top of Spring 3.0.5 and makes many of its features available to our users.
[[spel-support]]
===== Support for the Spring Expression Language (SpEL)
You can now use SpEL expressions within the _transformer, router, filter,
splitter, aggregator, service-activator, header-enricher_, and many more elements of the Spring Integration core namespace as well as various adapters.
There are many samples provided throughout this manual.
[[conversion-support]]
===== ConversionService and Converter
You can now benefit from _Conversion Service_ support provided with Spring while configuring many Spring Integration components such as http://www.eaipatterns.com/DatatypeChannel.html[Datatype Channel].
See <<channel-implementations>> as well <<service-activator-introduction>>.
Also, the SpEL support mentioned in the previous point also relies upon the ConversionService.
Therefore, you can register Converters once, and take advantage of them anywhere you are using SpEL expressions.
[[task-scheduler-poller-support]]
===== TaskScheduler and Trigger
Spring 3.0 defines two new strategies related to scheduling: _TaskScheduler and Trigger_ Spring Integration (which uses a lot of scheduling) now builds upon these.
In fact, Spring Integration 1.0 had originally defined some of the components (e.g.
CronTrigger) that have now been migrated into Spring 3.0's core API.
Now, you can benefit from reusing the same components within the entire Application Context (not just Spring Integration configuration).
Configuration of Spring Integration Pollers has been greatly simplified as well by providing attributes for directly configuring rates, delays, cron expressions, and trigger references.
See <<channel-adapter>> for sample configurations.
[[rest-support]]
===== RestTemplate and HttpMessageConverter
Our outbound HTTP adapters now delegate to Spring's RestTemplate for executing the HTTP request and handling its response.
This also means that you can reuse any custom HttpMessageConverter implementations.
See <<http-outbound>> for more details.
[[new-eip]]
==== Enterprise Integration Pattern Additions
Also in 2.0 we have added support for even more of the patterns described in Hohpe and Woolf's http://www.eaipatterns.com/[Enterprise Integration Patterns] book.
[[new-message-history]]
===== Message History
We now provide support for the http://www.eaipatterns.com/MessageHistory.html[Message History] pattern allowing you to keep track of all traversed components, including the name of each channel and endpoint as well as the timestamp of that traversal.
See <<message-history>> for more details.
[[new-message-store]]
===== Message Store
We now provide support for the http://www.eaipatterns.com/MessageStore.html[Message Store] pattern.
The Message Store provides a strategy for persisting messages on behalf of any process whose scope extends beyond a single transaction, such as the Aggregator and Resequencer.
Many sections of this document provide samples on how to use a Message Store as it affects several areas of Spring Integration.
See <<message-store>>, <<claim-check>>, <<channel>>, <<aggregator>>, <<jdbc>>, and <<resequencer>> for more details
[[new-claim-check]]
===== Claim Check
We have added an implementation of the http://www.eaipatterns.com/StoreInLibrary.html[Claim Check] pattern.
The idea behind the Claim Check pattern is that you can exchange a Message payload for a "claim ticket" and vice-versa.
This allows you to reduce bandwidth and/or avoid potential security issues when sending Messages across channels.
See <<claim-check>> for more details.
[[new-control-bus]]
===== Control Bus
We have provided implementations of the http://www.eaipatterns.com/ControlBus.html[Control Bus] pattern which allows you to use messaging to manage and monitor endpoints and channels.
The implementations include both a SpEL-based approach and one that executes Groovy scripts.
See <<control-bus>> and <<groovy-control-bus>> for more details.
[[new-adapters]]
==== New Channel Adapters and Gateways
We have added several new Channel Adapters and Messaging Gateways in Spring Integration 2.0.
[[new-ip]]
===== TCP/UDP Adapters
We have added Channel Adapters for receiving and sending messages over the TCP and UDP internet protocols.
See <<ip>> for more details.
Also, you can checkout the following blog: http://blog.springsource.com/2010/03/29/using-udp-and-tcp-adapters-in-spring-integration-2-0-m3/[TCP/UDP support]
[[new-twitter]]
===== Twitter Adapters
Twitter adapters provides support for sending and receiving Twitter Status updates as well as Direct Messages.
You can also perform Twitter Searches with an inbound Channel Adapter.
See <<twitter>> for more details.
[[new-xmpp]]
===== XMPP Adapters
The new XMPP adapters support both Chat Messages and Presence events.
See <<xmpp>> for more details.
[[new-ftp]]
===== FTP/FTPS Adapters
Inbound and outbound File transfer support over FTP/FTPS is now available.
See <<ftp>> for more details.
[[new-sftp]]
===== SFTP Adapters
Inbound and outbound File transfer support over SFTP is now available.
See <<sftp>> for more details.
[[new-feed]]
===== Feed Adapters
We have also added Channel Adapters for receiving news feeds (ATOM/RSS).
See <<feed>> for more details.
[[new-other]]
==== Other Additions
[[new-groovy]]
===== Groovy Support
With Spring Integration 2.0 we've added Groovy support allowing you to use Groovy scripting language to provide integration and/or business logic.
See <<groovy>> for more details.
[[new-map-transformer]]
===== Map Transformers
These symmetrical transformers convert payload objects to and from a Map.
See <<transformer>> for more details.
[[new-json-transformer]]
===== JSON Transformers
These symmetrical transformers convert payload objects to and from JSON.
See <<transformer>> for more details.
[[new-serialize-transformer]]
===== Serialization Transformers
These symmetrical transformers convert payload objects to and from byte arrays.
They also support the Serializer and Deserializer strategy interfaces that have been added as of Spring 3.0.5.
See <<transformer>> for more details.
[[new-refactoring]]
==== Framework Refactoring
The core API went through some significant refactoring to make it simpler and more usable.
Although we anticipate that the impact to the end user should be minimal, please read through this document to find what was changed.
Especially, visit <<dynamic-routers>> , <<gateway>>, <<http-outbound>>, <<message>>, and <<aggregator>> for more details.
If you are depending directly on some of the core components (Message, MessageHeaders, MessageChannel, MessageBuilder, etc.), you will notice that you need to update any import statements.
We restructured some packaging to provide the flexibility we needed for extending the domain model while avoiding any cyclical dependencies (it is a policy of the framework to avoid such "tangles").
[[new-infrastructure]]
==== New Source Control Management and Build Infrastructure
With Spring Integration 2.0 we have switched our build environment to use Git for source control.
To access our repository simply follow this URL: http://git.springsource.org/spring-integration[http://git.springsource.org/spring-integration].
We have also switched our build system to http://gradle.org/[Gradle].
[[new-samples]]
==== New Spring Integration Samples
With Spring Integration 2.0 we have decoupled the samples from our main release distribution.
Please read this blog to get more info http://blog.springsource.com/2010/09/29/new-spring-integration-samples/[New Spring Integration Samples] We have also created many new samples, including samples for every new Adapter.
[[new-sts]]
==== Spring Tool Suite Visual Editor for Spring Integration
There is an amazing new visual editor for Spring Integration included within the latest version of SpringSource Tool Suite.
If you are not already using STS, please download it here:
https://spring.io/tools/sts[Spring Tool Suite]

220
src/reference/asciidoc/changes-2.0-2.1.adoc Normal file
View File

@@ -0,0 +1,220 @@
[[migration-2.0-2.1]]
=== Changes between 2.0 and 2.1
[[x2.1-new-components]]
==== New Components
[[x2.1-new-scripting-support]]
===== JSR-223 Scripting Support
In Spring Integration 2.0, support for http://groovy.codehaus.org/[Groovy] was added.
With Spring Integration 2.1 we expanded support for additional languages substantially by implementing support for http://www.jcp.org/en/jsr/detail?id=223[JSR-223] (Scripting for the Java™ Platform).
Now you have the ability to use any scripting language that supports JSR-223 including:
* Javascript
* Ruby/JRuby
* Python/Jython
* Groovy
For further details please see <<scripting>>.
[[x2.1-new-gemfire-support]]
===== GemFire Support
Spring Integration provides support for http://www.vmware.com/products/application-platform/vfabric-gemfire/overview.html[GemFire] by providing inbound adapters for entry and continuous query events, an outbound adapter to write entries to the cache, and http://static.springsource.org/spring-integration/api/org/springframework/integration/store/MessageStore.html[`MessageStore`] and http://static.springsource.org/spring-integration/api/org/springframework/integration/store/MessageGroupStore.html[`MessageGroupStore`] implementations.
Spring integration leverages the http://www.springsource.org/spring-gemfire[_Spring Gemfire_] project, providing a thin wrapper over its components.
For further details please see <<gemfire>>.
[[x2.1-new-amqp-support]]
===== AMQP Support
Spring Integration 2.1 adds several Channel Adapters for receiving and sending messages using thehttp://www.amqp.org/[_Advanced Message Queuing Protocol_] (AMQP).
Furthermore, Spring Integration also provides a point-to-point Message Channel, as well as a publish/subscribe Message Channel that are backed by AMQP Exchanges and Queues.
For further details please see <<amqp>>.
[[x2.1-new-mongodb-support]]
===== MongoDB Support
As of version 2.1 Spring Integration provides support for http://www.mongodb.org/[MongoDB] by providing a MongoDB-based MessageStore.
For further details please see <<mongodb>>.
[[x2.1-new-redis-support]]
===== Redis Support
As of version 2.1 Spring Integration supports http://redis.io/[Redis], an advanced key-value store, by providing a Redis-based MessageStore as well as Publish-Subscribe Messaging adapters.
For further details please see <<redis>>.
[[x2.1-new-resource-support]]
===== Support for Spring's Resource abstraction
As of version 2.1, we've introduced a new _Resource Inbound Channel Adapter_ that builds upon Spring's Resource abstraction to support greater flexibility across a variety of actual types of underlying resources, such as a file, a URL, or a class path resource.
Therefore, it's similar to but more generic than the _File Inbound Channel Adapter_.
For further details please see <<resource-inbound-channel-adapter>>.
[[x2.1-new-stored-proc-support]]
===== Stored Procedure Components
With Spring Integration 2.1, the `JDBC` Module also provides Stored Procedure support by adding several new components, including inbound/outbound channel adapters and an Outbound Gateway.
The Stored Procedure support leverages Spring'shttp://static.springsource.org/spring/docs/3.0.x/javadoc-api/org/springframework/jdbc/core/simple/SimpleJdbcCall.html[`SimpleJdbcCall`] class and consequently supports stored procedures for:
* Apache Derby
* DB2
* MySQL
* Microsoft SQL Server
* Oracle
* PostgreSQL
* Sybase
The Stored Procedure components also support Sql Functions for the following databases:
* MySQL
* Microsoft SQL Server
* Oracle
* PostgreSQL
For further details please see <<stored-procedures>>.
[[x2.1-new-xpath-filter-support]]
===== XPath and XML Validating Filter
Spring Integration 2.1 provides a new XPath-based Message Filter, that is part of the `XML` module.
The XPath Filter allows you to filter messages using provided XPath Expressions.
Furthermore, documentation was added for the XML Validating Filter.
For more details please see <<xml-xpath-filter>> and <<xml-validating-filter>>.
[[x2.1-new-payload-enricher-support]]
===== Payload Enricher
Since Spring Integration 2.1, the Payload Enricher is provided.
A Payload Enricher defines an endpoint that typically passes ahttp://static.springsource.org/spring-integration/api/org/springframework/integration/Message.html[`Message`] to the exposed request channel and then expects a reply message.
The reply message then becomes the root object for evaluation of expressions to enrich the target payload.
For further details please see <<payload-enricher>>.
[[x2.1-new-ftp-outbound-gateway]]
===== FTP and SFTP Outbound Gateways
Spring Integration 2.1 provides two new Outbound Gateways in order to interact with remote File Transfer Protocol (FTP) or Secure File Transfer Protocol (SFT) servers.
These two gateways allow you to directly execute a limited set of remote commands.
For instance, you can use these Outbound Gateways to list, retrieve and delete remote files and have the Spring Integration message flow continue with the remote server's response.
For further details please see <<ftp-outbound-gateway>> and <<sftp-outbound-gateway>>.
[[x2.1-new-ftp-session-caching]]
===== FTP Session Caching
As of version 2.1, we have exposed more flexibility with regards to session management for remote file adapters (e.g., FTP, SFTP etc).
Specifically, the `cache-sessions` attribute, which is available via the XML namespace support, is now_deprecated_.
Alternatively, we added the `sessionCacheSize` and `sessionWaitTimeout` attributes on the `CachingSessionFactory`.
For further details please see <<ftp-session-caching>> and <<sftp-session-caching>>.
[[x2.1-framework-refactorings]]
==== Framework Refactoring
[[x2.1-router-standardization]]
===== Standardizing Router Configuration
Router parameters have been standardized across all router implementations with Spring Integration 2.1 providing a more consistent user experience.
With Spring Integration 2.1 the `ignore-channel-name-resolution-failures` attribute has been removed in favor of consolidating its behavior with the `resolution-required` attribute.
Also, the `resolution-required` attribute now defaults to `true`.
Starting with Spring Integration 2.1, routers will no longer silently drop any messages, if no default output channel was defined.
This means, that by default routers now require at least one resolved channel (if no `default-output-channel` was set) and by default will throw a `MessageDeliveryException` if no channel was determined (or an attempt to send was not successful).
If, however, you do desire to drop messages silently, simply set `default-output-channel="nullChannel"`.
IMPORTANT: With the standardization of Router parameters and the consolidation of the parameters described above, there is the possibility of breaking older Spring Integration based applications.
For further details please see <<router>>
[[x2.1-schema-updated]]
===== XML Schemas updated to 2.1
Spring Integration 2.1 ships with an updated XML Schema (version 2.1), providing many improvements, e.g.
the Router standardizations discussed above.
From now on, users _must_ always declare the latest XML schema (currently version 2.1).
Alternatively, they can use the version-less schema.
Generally, the best option is to use version-less namespaces, as these will automatically use the latest available version of Spring Integration.
Declaring a version-less Spring Integration namespace:
[source,xml]
----
<?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:int="http://www.springframework.org/schema/integration"
xsi:schemaLocation="http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration.xsd
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
...
</beans>
----
Declaring a Spring Integration namespace using an explicit version:
[source,xml]
----
<?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:int="http://www.springframework.org/schema/integration"
xsi:schemaLocation="http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration-2.2.xsd
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
...
</beans>
----
The old 1.0 and 2.0 schemas are still there, but if an Application Context still references one of those deprecated schemas, the validator will fail on initialization.
[[x2.1-source-control-infrastructure]]
==== Source Control Management and Build Infrastructure
[[x2.1-move-to-github]]
===== Source Code now hosted on Github
Since version 2.0, the Spring Integration project uses http://git-scm.com/[Git] for version control.
In order to increase community visibility even further, the project was moved from SpringSource hosted Git repositories to http://www.github.com/[Github].
The Spring Integration Git repository is located at:null
For the project we also improved the process of providing code contributions and we ensure that every commit is peer-reviewed.
In fact, core committers now follow the same process as contributors.
For more details please see:
null
[[x2.1-sonar]]
===== Improved Source Code Visibility with Sonar
In an effort to provide better source code visibility and consequently to monitor the quality of Spring Integration's source code, an instance of http://www.sonarsource.org/[Sonar] was setup and metrics are gathered nightly and made avaiblable at:
null
[[x2.1-new-samples]]
==== New Samples
For the 2.1 release of Spring Integration we also expanded the Spring Integration Samples project and added many new samples, e.g.
samples covering AMQP support, the new payload enricher, a sample illustrating techniques for testing Spring Integration flow fragments, as well as an example for executing Stored Procedures against Oracle.
For details please visit:
null

175
src/reference/asciidoc/changes-2.1-2.2.adoc Normal file
View File

@@ -0,0 +1,175 @@
[[migration-2.1-2.2]]
=== Changes between 2.1 and 2.2
[[x2.2-new-components]]
==== New Components
[[x2.2-redis-store-adapters]]
===== RedisStore Inbound and Outbound Channel Adapters
Spring Integration now has RedisStore Inbound and Outbound Channel Adapters allowing you to write and read Message payloads to/from Redis collection(s).
For more information please see <<redis-store-outbound-channel-adapter>> and <<redis-store-inbound-channel-adapter>>.
[[x2.2-mongo-adapters]]
===== MongoDB Inbound and Outbound Channel Adapters
Spring Integration now has MongoDB Inbound and Outbound Channel Adapters allowing you to write and read Message payloads to/from a MongoDB document store.
For more information please see <<mongodb-outbound-channel-adapter>> and <<mongodb-inbound-channel-adapter>>.
[[x2.2-jpa]]
===== JPA Endpoints
Spring Integration now includes components for the Java Persistence API (JPA) for retrieving and persisting JPA entity objects.
The JPA Adapter includes the following components:
* _<<jpa-inbound-channel-adapter,Inbound Channel Adapter>>_
* _<<jpa-outbound-channel-adapter,Outbound Channel Adapter>>_
* _<<jpa-updating-outbound-gateway,Updating Outbound Gateway>>_
* _<<jpa-retrieving-outbound-gateway,Retrieving Outbound Gateway>>_
For more information please see <<jpa>>
[[x2.2-general]]
==== General Changes
[[x2.2-spring-31]]
===== Spring 3.1 Used by Default
Spring Integration now uses Spring 3.1.
[[x2.2-handler-advice]]
===== Adding Behavior to Endpoints
The ability to add an <advice-chain/> to a poller has been available for some time.
However, the behavior added by this affects the entire integration flow.
It did not address the ability to add, say, retry, to an individual endpoint.
The 2.2.
release introduces the <request-handler-advice-chain/> to many endpoints.
In addition, 3 standard Advice classes have been provided for this purpose:
* MessageHandlerRetryAdvice
* MessageHandlerCircuitBreakerAdvice
* ExpressionEvaluatingMessageHandlerAdvice
For more information, see <<message-handler-advice-chain>>.
[[x2.2-transaction-sync]]
===== Transaction Synchronization and Pseudo Transactions
Pollers can now participate in Spring's _Transaction Synchronization_ feature.
This allows for synchronizing such operations as renaming files by an inbound channel adapter depending on whether the transaction commits, or rolls back.
In addition, these features can be enabled when there is not a 'real' transaction present, by means of a `PseudoTransactionManager`.
For more information see <<transaction-synchronization>>.
[[x2.2-file-adapter]]
===== File Adapter - Improved File Overwrite/Append Handling
When using the _File Oubound Channel Adapter_ or the _File Outbound Gateway_, a new _mode_ property was added.
Prior to _Spring Integration 2.2_, target files were replaced when they existed.
Now you can specify the following options:
* REPLACE (Default)
* APPEND
* FAIL
* IGNORE
For more information please see <<file-writing-destination-exists>>.
[[x2.2-outbound-gateways]]
===== Reply-Timeout added to more Outbound Gateways
The XML Namespace support adds the _reply-timeout_ attribute to the following _Outbound Gateways_:
* Amqp Outbound Gateway
* File Outbound Gateway
* Ftp Outbound Gateway
* Sftp Outbound Gateway
* Ws Outbound Gateway
[[x2.2-amqp-11]]
===== Spring-AMQP 1.1
Spring Integration now uses Spring AMQP 1.1.
This enables several features to be used within a Spring Integration application, including...
* A fixed reply queue for the outbound gateway
* HA (mirrored) queues
* Publisher Confirms
* Returned Messages
* Support for Dead Letter Exchanges/Dead Letter Queues
[[x2.2-jdbc-11]]
===== JDBC Support - Stored Procedures Components
_SpEL Support_
When using the Stored Procedure components of the Spring Integration JDBC Adapter, you can now provide Stored Procedure Names or Stored Function Names using Spring Expression Language (SpEL).
This allows you to specify the Stored Procedures to be invoked at runtime.
For example, you can provide Stored Procedure names that you would like to execute via Message Headers.
For more information please see <<stored-procedures>>.
_JMX Support_
The Stored Procedure components now provide basic JMX support, exposing some of their properties as MBeans:
* Stored Procedure Name
* Stored Procedure Name Expression
* JdbcCallOperations Cache Statistics
[[x2.2-jdbc-gateway-update-optional]]
===== JDBC Support - Outbound Gateway
When using the JDBC Outbound Gateway, the update query is no longer mandatory.
You can now provide solely a select query using the request message as a source of parameters.
[[x2.2-jdbc-message-store-channels]]
===== JDBC Support - Channel-specific Message Store Implementation
A new _Message Channel_-specific Message Store Implementation has been added, providing a more scalable solution using database-specific SQL queries.
For more information please see: <<jdbc-message-store-channels>>.
[[x2.2-shutdown]]
===== Orderly Shutdown
A method `stopActiveComponents()` has been added to the IntegrationMBeanExporter.
This allows a Spring Integration application to be shut down in an orderly manner, disallowing new inbound messages to certain adapters and waiting for some time to allow in-flight messages to complete.
[[x2.2-jms-og]]
===== JMS Oubound Gateway Improvements
The JMS Outbound Gateway can now be configured to use a`MessageListener` container to receive replies.
This can improve performance of the gateway.
[[x2.2-o-t-j-t]]
===== object-to-json-transformer
The `ObjectToJsonTransformer` now sets the _content-type_ header to _application/json_ by default.
For more information see <<transformer>>.
[[httpChanges]]
===== HTTP Support
Java serialization over HTTP is no longer enabled by default.
Previously, when setting a `expected-response-type` to a `Serializable` object, the `Accept` header was not properly set up.
The `SerializingHttpMessageConverter` has now been updated to set the Accept header to `application/x-java-serialized-object`.
However, because this could cause incompatibility with existing applications, it was decided to no longer automatically add this converter to the HTTP endpoints.
If you wish to use Java serialization, you will need to add the `SerializingHttpMessageConverter` to the appropriate endpoints, using the `message-converters` attribute, when using XML configuration, or using the `setMessageConverters()` method.
Alternatively, you may wish to consider using JSON instead which is enabled by simply having `Jackson` on the classpath.

421
src/reference/asciidoc/changes-2.2-3.0.adoc Normal file
View File

@@ -0,0 +1,421 @@
[[migration-2.2-3.0]]
=== Changes Between 2.2 and 3.0
[[x3.0-new-components]]
==== New Components
[[x3.0-request-mapping]]
===== HTTP Request Mapping
The HTTP module now provides powerful Request Mapping support for Inbound Endpoints.
Class `UriPathHandlerMapping` was replaced by `IntegrationRequestMappingHandlerMapping`, which is registered under the bean name `integrationRequestMappingHandlerMapping` in the application context.
Upon parsing of the HTTP Inbound Endpoint, a new `IntegrationRequestMappingHandlerMapping` bean is either registered or an existing bean is being reused.
To achieve flexible Request Mapping configuration, Spring Integration provides the `<request-mapping/>` sub-element for the `<http:inbound-channel-adapter/>` and the `<http:inbound-gateway/>`.
Both HTTP Inbound Endpoints are now fully based on the Request Mapping infrastructure that was introduced with Spring MVC 3.1.
For example, multiple paths are supported on a single inbound endpoint.
For more information see <<http-namespace>>.
[[x3.0-spel-customization]]
===== Spring Expression Language (SpEL) Configuration
A new `IntegrationEvaluationContextFactoryBean` is provided to allow configuration of custom `PropertyAccessor` s and functions for use in SpEL expressions throughout the framework.
For more information see <<spel>>.
[[x3.0-spel-functions]]
===== SpEL Functions Support
To customize the SpEL `EvaluationContext` with static `Method` functions, the new `<spel-function/>` component is introduced.
Two built-in functions are also provided (`#jsonPath` and `#xpath`).
For more information see <<spel-functions>>.
[[x3.0-spel-property-accessors]]
===== SpEL PropertyAccessors Support
To customize the SpEL `EvaluationContext` with `PropertyAccessor` implementations the new `<spel-property-accessors/>` component is introduced.
For more information see <<spel-property-accessors>>.
[[x3.0-redis-new-components]]
===== Redis: New Components
A new Redis-based http://docs.spring.io/spring-integration/docs/latest-ga/api/org/springframework/integration/store/MetadataStore.html[MetadataStore] implementation has been added.
The `RedisMetadataStore` can be used to maintain state of a `MetadataStore` across application restarts.
This new `MetadataStore` implementation can be used with adapters such as:
* Twitter Inbound Adapters
* Feed Inbound Channel Adapter
New queue-based components have been added.
The `<int-redis:queue-inbound-channel-adapter/>` and the `<int-redis:queue-outbound-channel-adapter/>` components are provided to perform 'right pop' and 'left push' operations on a Redis List, respectively.
For more information see <<redis>>.
[[x3.0-hcr]]
===== Header Channel Registry
It is now possible to instruct the framework to store reply and error channels in a registry for later resolution.
This is useful for cases where the `replyChannel` or `errorChannel` might be lost; for example when serializing a message.
See <<header-enricher>> for more information.
[[x3.0-configurable-mongo-MS]]
===== MongoDB support: New ConfigurableMongoDbMessageStore
In addition to the existing `eMongoDbMessageStore`, a new `ConfigurableMongoDbMessageStore` has been introduced.
This provides a more robust and flexible implementation of `MessageStore` for MongoDB.
It does not have backward compatibility, with the existing store, but it is recommended to use it for new applications.
Existing applications can use it, but messages in the old store will not be available.
See <<mongodb>> for more information.
[[x3.0-syslog]]
===== Syslog Support
Building on the 2.2 `SyslogToMapTransformer` Spring Integration 3.0 now introduces `UDP` and `TCP` inbound channel adapters especially tailored for receiving SYSLOG messages.
For more information, see<<syslog>>.
[[x3.0-tail]]
===== 'Tail' Support
File 'tail'ing inbound channel adapters are now provided to generate messages when lines are added to the end of text files; see <<file-tailing>>.
[[x3.0-jmx]]
===== JMX Support
* A new `<int-jmx:tree-polling-channel-adapter/>` is provided; this adapter queries the JMX MBean tree and sends a message with a payload that is the graph of objects that matches the query.
By default the MBeans are mapped to primitives and simple Objects like Map, List and arrays - permitting simple transformation, for example, to JSON.
* The `IntegrationMBeanExporter` now allows the configuration of a custom `ObjectNamingStrategy` using the `naming-strategy` attribute.
For more information, see <<jmx>>.
[[x3.0-tcp-events]]
===== TCP/IP Connection Events and Connection Management
`TcpConnection` s now emit `ApplicationEvent` s (specifically `TcpConnectionEvent` s) when connections are opened, closed, or an exception occurs.
This allows applications to be informed of changes to TCP connections using the normal Spring `ApplicationListener` mechanism.
`AbstractTcpConnection` has been renamed `TcpConnectionSupport`; custom connections that are subclasses of this class, can use its methods to publish events.
Similarly, `AbstractTcpConnectionInterceptor` has been renamed to `TcpConnectionInterceptorSupport`.
In addition, a new `<int-ip:tcp-connection-event-inbound-channel-adapter/>` is provided; by default, this adapter sends all `TcpConnectionEvent` s to a `Channel`.
Further, the TCP Connection Factories, now provide a new method `getOpenConnectionIds()`, which returns a list of identifiers for all open connections; this allows applications, for example, to broadcast to all open connections.
Finally, the connection factories also provide a new method `closeConnection(String connectionId)` which allows applications to explicitly close a connection using its ID.
For more information see <<tcp-events>>.
[[x3.0-inbound-script]]
===== Inbound Channel Adapter Script Support
The `<int:inbound-channel-adapter/>` now supports `<expression/>` and `<script/>` sub-elements to create a `MessageSource`; see <<channel-adapter-expressions-and-scripts>>.
[[x3.0-content-enricher-headers]]
===== Content Enricher: Headers Enrichment Support
The Content Enricher now provides configuration for `<header/>` sub-elements, to enrich the outbound Message with headers based on the reply Message from the underlying message flow.
For more information see <<payload-enricher>>.
[[x3.0-general]]
==== General Changes
[[x3.0-message-id]]
===== Message ID Generation
Previously, message ids were generated using the JDK `UUID.randomUUID()` method.
With this release, the default mechanism has been changed to use a more efficient algorithm which is significantly faster.
In addition, the ability to change the strategy used to generate message ids has been added.
For more information see <<message-id-generation>>.
[[x3.0-gateway]]
===== <gateway> Changes
* It is now possible to set common headers across all gateway methods, and more options are provided for adding, to the message, information about which method was invoked.
* It is now possible to entirely customize the way that gateway method calls are mapped to messages.
* The `GatewayMethodMetadata` is now public class and it makes possible flexibly to configure the `GatewayProxyFactoryBean` programmatically from Java code.
For more information see <<gateway>>.
[[x3.0-http-endpointss]]
===== HTTP Endpoint Changes
* *Outbound Endpoint 'encode-uri'* - `<http:outbound-gateway/>` and `<http:outbound-channel-adapter/>` now provide an `encode-uri` attribute to allow disabling the encoding of the URI object before sending the request.
* *Inbound Endpoint 'merge-with-default-converters'* - `<http:inbound-gateway/>` and `<http:inbound-channel-adapter/>` now have a `merge-with-default-converters` attribute to include the list of default `HttpMessageConverter` s after the custom message converters.
* *'If-(Un)Modified-Since' HTTP Headers* - previously, 'If-Modified-Since' and 'If-Unmodified-Since' HTTP headers were incorrectly processed within from/to HTTP headers mapping in the `DefaultHttpHeaderMapper`.
Now, in addition correcting that issue, `DefaultHttpHeaderMapper` provides date parsing from formatted strings for any HTTP headers that accept date-time values.
* *Inbound Endpoint Expression Variables* - In addition to the existing _#requestParams_ and _#pathVariables_, the `<http:inbound-gateway/>` and `<http:inbound-channel-adapter/>` now support additional useful variables: _#matrixVariables_, _#requestAttributes_, _#requestHeaders_ and _#cookies_.
These variables are available in both payload and header expressions.
* *Outbound Endpoint 'uri-variables-expression'* - HTTP Outbound Endpoints now support the `uri-variables-expression` attribute to specify an `Expression` to evaluate a `Map` for all URI variable placeholders within URL template.
This allows selection of a different map of expressions based on the outgoing message.
For more information see <<http>>.
[[x3.0-json-transformers]]
===== Jackson Support (JSON)
* A new abstraction for JSON conversion has been introduced.
Implementations for Jackson 1.x and Jackson 2 are currently provided, with the version being determined by presence on the classpath.
Previously, only Jackson 1.x was supported.
* The `ObjectToJsonTransformer` and `JsonToObjectTransformer` now emit/consume headers containing type information.
For more information, see 'JSON Transformers' in <<transformer>>.
[[x3.0-id-for-chain-sub-components]]
===== Chain Elements 'id' Attribute
Previously, the _id_ attribute for elements within a `<chain>` was ignored and, in some cases, disallowed.
Now, the _id_ attribute is allowed for all elements within a `<chain>`.
The bean names of chain elements is a combination of the surrounding chain's _id_ and the _id_ of the element itself.
For example: 'fooChain$child.fooTransformer.handler'.
For more information see <<chain>>.
[[x3.0-corr-endpoint-empty-groups]]
===== Aggregator 'empty-group-min-timeout' property
The `AbstractCorrelatingMessageHandler` provides a new property `empty-group-min-timeout` to allow empty group expiry to run on a longer schedule than expiring partial groups.
Empty groups will not be removed from the `MessageStore` until they have not been modified for at least this number of milliseconds.
For more information see <<aggregator-config>>.
[[x3.0-filelistfilter]]
===== Persistent File List Filters (file, (S)FTP)
New `FileListFilter` s that use a persistent `MetadataStore` are now available.
These can be used to prevent duplicate files after a system restart.
See<<file-reading>>, <<ftp-inbound>>, and <<sftp-inbound>> for more information.
[[x3.0-scripting-variables]]
===== Scripting Support: Variables Changes
A new `variables` attribute has been introduced for scripting components.
In addition, variable bindings are now allowed for inline scripts.
See <<groovy>> and <<scripting>> for more information.
[[x3.0-direct-channel-lb-ref]]
===== Direct Channel Load Balancing configuration
Previously, when configuring `LoadBalancingStrategy` on the channel's 'dispatcher' sub-element, the only available option was to use a pre-defined enumeration of values which did not allow one to set a custom implementation of the `LoadBalancingStrategy`.
You can now use `load-balancer-ref` to provide a reference to a custom implementation of the `LoadBalancingStrategy`.
For more information see <<channel-implementations-directchannel>>.
[[x3.0-pub-sub]]
===== PublishSubscribeChannel Behavior
Previously, sending to a <publish-subscribe-channel/> that had no subscribers would return a `false` result.
If used in conjunction with a `MessagingTemplate`, this would result in an exception being thrown.
Now, the `PublishSubscribeChannel` has a property `minSubscribers` (default 0).
If the message is sent to at least the minimum number of subscribers, the send is deemed to be successful (even if zero).
If an application is expecting to get an exception under these conditions, set the minimum subscribers to at least 1.
[[x3.0--s-ftp-changes]]
===== FTP, SFTP and FTPS Changes
*The FTP, SFTP and FTPS endpoints no longer cache sessions by default*
The deprecated `cached-sessions` attribute has been removed from all endpoints.
Previously, the embedded caching mechanism controlled by this attribute's value didn't provide a way to limit the size of the cache, which could grow indefinitely.
The `CachingConnectionFactory` was introduced in release 2.1 and it became the preferred (and is now the only) way to cache sessions.
The `CachingConnectionFactory` now provides a new method `resetCache()`.
This immediately closes idle sessions and causes in-use sessions to be closed as and when they are returned to the cache.
The `DefaultSftpSessionFactory` (in conjunction with a `CachingSessionFactory`) now supports multiplexing channels over a single SSH connection (SFTP Only).
*FTP, SFTP and FTPS Inbound Adapters*
Previously, there was no way to override the default filter used to process files retrieved from a remote server.
The `filter` attribute determines which files are retrieved but the `FileReadingMessageSource` uses an `AcceptOnceFileListFilter`.
This means that if a new copy of a file is retrieved, with the same name as a previously copied file, no message was sent from the adapter.
With this release, a new attribute `local-filter` allows you to override the default filter, for example with an `AcceptAllFileListFilter`, or some other custom filter.
For users that wish the behavior of the `AcceptOnceFileListFilter` to be maintained across JVM executions, a custom filter that retains state, perhaps on the file system, can now be configured.
Inbound Channel Adapters now support the `preserve-timestamp` attribute, which sets the local file modified timestamp to the timestamp from the server (default false).
*FTP, SFTP and FTPS Gateways*
* The gateways now support the *mv* command, enabling the renaming of remote files.
* The gateways now support recursive *ls* and *mget* commands, enabling the retrieval of a remote file tree.
* The gateways now support *put* and *mput* commands, enabling sending file(s) to the remote server.
* The `local-filename-generator-expression` attribute is now supported, enabling the naming of local files during retrieval.
By default, the same name as the remote file is used.
* The `local-directory-expression` attribute is now supported, enabling the naming of local directories during retrieval based on the remote directory.
*Remote File Template*
A new higher-level abstraction (`RemoteFileTemplate`) is provided over the `Session` implementations used by the FTP and SFTP modules.
While it is used internally by endpoints, this abstraction can also be used programmatically and, like all Spring `*Template` implementations, reliably closes the underlying session while allowing low level access to the session when needed.
For more information, see <<ftp>> and <<sftp>>.
[[x3.0-outbound-gateway-requires-reply]]
===== 'requires-reply' Attribute for Outbound Gateways
All Outbound Gateways (e.g.
`<jdbc:outbound-gateway/>` or `<jms:outbound-gateway/>`) are designed for 'request-reply' scenarios.
A response is expected from the external service and will be published to the `reply-channel`, or the `replyChannel` message header.
However, there are some cases where the external system might not always return a result, e.g.
a `<jdbc:outbound-gateway/>`, when a SELECT ends with an empty `ResultSet` or, say, a Web Service is One-Way.
An option is therefore needed to configure whether or not a _reply_ is required.
For this purpose, the _requires-reply_ attribute has been introduced for Outbound Gateway components.
In most cases, the default value for _requires-reply_ is `true` and, if there is not any result, a `ReplyRequiredException` will be thrown.
Changing the value to `false` means that, if an external service doesn't return anything, the message-flow will end at that point, similar to an Outbound Channel Adapter.
NOTE: The WebService outbound gateway has an additional attribute `ignore-empty-responses`; this is used to treat an empty String response as if no response was received.
It is true by default but can be set to false to allow the application to receive an empty String in the reply message payload.
When the attribute is true an empty string is treated as no response for the purposes of the _requires-reply_ attribute.
_requires-reply_ is false by default for the WebService outbound gateway.
Note, the `requiresReply` property was previously present in the `AbstractReplyProducingMessageHandler` but set to `false`, and there wasn't any way to configure it on Outbound Gateways using the XML namespace.
IMPORTANT: Previously, a gateway receiving no reply would silently end the flow (with a DEBUG log message); with this change an exception will now be thrown by default by most gateways.
To revert to the previous behavior, set `requires-reply` to false.
[[x3.0-amqp-mapping]]
===== AMQP Outbound Gateway Header Mapping
Previously, the <int-amqp:outbound-gateway/> mapped headers before invoking the message converter, and the converter could overwrite headers such as `content-type`.
The outbound adapter maps the headers after the conversion, which means headers like `content-type` from the outbound `Message` (if present) are used.
Starting with this release, the gateway now maps the headers after the message conversion, consistent with the adapter.
If your application relies on the previous behavior (where the converter's headers overrode the mapped headers), you either need to filter those headers (before the message reaches the gateway) or set them appropriately.
The headers affected by the `SimpleMessageConverter` are `content-type` and `content-encoding`.
Custom message converters may set other headers.
[[x3.0-stored-proc-sql-return-type]]
===== Stored Procedure Components Improvements
For more complex database-specific types, not supported by the standard `CallableStatement.getObject` method, 2 new additional attributes were introduced to the `<sql-parameter-definition/>` element with OUT-direction:
_type-name_
_return-type_
The `row-mapper` attribute of the Stored Procedure Inbound Channel Adapter `<returning-resultset/>` sub-element now supports a reference to a `RowMapper` bean definition.
Previously, it contained just a class name (which is still supported).
For more information see <<stored-procedures>>.
[[x3.0-ws-outbound-uri-substitution]]
===== Web Service Outbound URI Configuration
Web Service Outbound Gateway 'uri' attribute now supports `<uri-variable/>` substitution for all URI-schemes supported by Spring Web Services.
For more information see <<outbound-uri>>.
[[x3.0-redis]]
===== Redis Adapter Changes
The Redis Inbound Channel Adapter can now use a `null` value for `serializer` property, with the raw data being the message payload.
The Redis Outbound Channel Adapter now has the `topic-expression` property to determine the Redis topic against the Message at runtime.
The Redis Inbound Channel Adapter, in addition to the existing `topics` attribute, now has the `topic-patterns` attribute.
For more information, see <<redis>>.
[[x3.0-advising-filters]]
===== Advising Filters
Previously, when a <filter/> had a <request-handler-advice-chain/>, the discard action was all performed within the scope of the advice chain (including any downstream flow on the `discard-channel`).
The filter element now has an attribute `discard-within-advice` (default `true`), to allow the discard action to be performed after the advice chain completes.
See <<advising-filters>>.
[[x3.0-annotation-advice]]
===== Advising Endpoints using Annotations
Request Handler Advice Chains can now be configured using annotations.
See <<advising-with-annotations>>.
[[x3.0-o-t-s-t]]
===== ObjectToStringTransformer Improvements
This transformer now correctly transforms `byte[]` and `char[]` payloads to `String`.
For more information see <<transformer>>.
[[x3.0-jpa-changes]]
===== JPA Support Changes
Payloads to _persist_ or _merge_ can now be of type `http://docs.oracle.com/javase/7/docs/api/java/lang/Iterable.html[java.lang.Iterable]`.
In that case, each object returned by the `Iterable` is treated as an entity and persisted or merged using the underlying `EntityManager`.
_NULL_ values returned by the iterator are ignored.
The JPA adapters now have additional attributes to optionally 'flush' and 'clear' entities from the associated persistence context after performing persistence operations.
Retrieving gateways had no mechanism to specify the first record to be retrieved which is a common use case.
The retrieving gateways now support specifying this parameter using a `first-result` and `first-result-expression` attributes to the gateway definition.
<<jpa-retrieving-outbound-gateway>>.
The JPA retrieving gateway and inbound adapter now have an attribute to specify the maximum number of results in a result set as an expression.
In addition, the `max-results` attribute has been introduced to replace `max-number-of-results`, which has been deprecated.
`max-results` and `max-results-expression` are used to provide the maximum number of results, or an expression to compute the maximum number of results, respectively, in the result set.
For more information see <<jpa>>.
[[x3.0-dalay-expression]]
===== Delayer: delay expression
Previously, the `<delayer>` provided a `delay-header-name` attribute to determine the _delay_ value at runtime.
In complex cases it was necessary to precede the `<delayer>` with a `<header-enricher>`.
Spring Integration 3.0 introduced the `expression` attribute and `expression` sub-element for dynamic delay determination.
The `delay-header-name` attribute is now deprecated because the header evaluation can be specified in the `expression`.
In addition, the `ignore-expression-failures` was introduced to control the behavior when an expression evaluation fails.
For more information see <<delayer>>.
[[x3.0-jdbc-mysql-v5_6_4]]
===== JDBC Message Store Improvements
_Spring Integration 3.0_ adds a new set of DDL scripts for _MySQL_ version 5.6.4 and higher.
Now _MySQL_ supports _fractional
seconds_ and is thus improving the FIFO ordering when polling from a MySQL-based Message Store.
For more information, please see <<jdbc-message-store-generic>>.
[[x3.0-event-for-imap-idle]]
===== IMAP Idle Connection Exceptions
Previously, if an IMAP idle connection failed, it was logged but there was no mechanism to inform an application.
Such exceptions now generate `ApplicationEvent` s.
Applications can obtain these events using an `<int-event:inbound-channel-adapter>` or any `ApplicationListener` configured to receive an `ImapIdleExceptionEvent` or one of its super classes.
[[x3.0-tcp-headers]]
===== Message Headers and TCP
The TCP connection factories now enable the configuration of a flexible mechanism to transfer selected headers (as well as the payload) over TCP.
A new `TcpMessageMapper` enables the selection of the headers, and an appropriate (de)serializer needs to be configured to write the resulting `Map` to the TCP stream.
A `MapJsonSerializer` is provided as a convenient mechanism to transfer headers and payload over TCP.
For more information see <<ip-headers>>.
[[x3.0-jms-mdca-te]]
===== JMS Message Driven Channel Adapter
Previously, when configuring a `<message-driven-channel-adapter/>`, if you wished to use a specific `TaskExecutor`, it was necessary to declare a container bean and provide it to the adapter using the `container` attribute.
The `task-executor` is now provided, allowing it to be set directly on the adapter.
This is in addition to several other container attributes that were already available.
[[x3.0-rmi-ec]]
===== RMI Inbound Gateway
The RMI Inbound Gateway now supports an `error-channel` attribute.
See <<rmi-inbound>>.
[[x3.0-xslt-transformer]]
===== XsltPayloadTransformer
You can now specify the transformer factory class name using the `transformer-factory-class` attribute.
See <<xml-xslt-payload-transformers>>

262
src/reference/asciidoc/changes-3.0-4.0.adoc Normal file
View File

@@ -0,0 +1,262 @@
[[migration-3.0-4.0]]
=== Changes between 3.0 and 4.0
Please be sure to also see the https://github.com/spring-projects/spring-integration/wiki/Spring-Integration-3.0-to-4.0-Migration-Guide[Migration Guide] for important changes that might affect your applications.
Migration guides for all versions back to _2.1_ can be found on the https://github.com/spring-projects/spring-integration/wiki[Wiki].
[[x4.0-new-components]]
==== New Components
[[x4.0-mqtt]]
===== MQTT Channel Adapters
The MQTT channel adapters (previously available in the Spring Integration Extensions repository) are now available as part of the normal Spring Integration distribution.
See <<mqtt>>
[[x4.0-enable-configuration]]
===== @EnableIntegration
The `@EnableIntegration` annotation has been added, to permit declaration of standard Spring Integration beans when using `@Configuration` classes.
See <<enable-integration>> for more information.
[[x4.0-component-scan]]
===== @IntegrationComponentScan
The `@IntegrationComponentScan` annotation has been added, to permit classpath scanning for Spring Integration specific components.
See <<enable-integration>> for more information.
[[x4.0-message-history]]
===== @EnableMessageHistory
Message history can now be enabled with the `@EnableMessageHistory` annotation in a `@Configuration` class; in addition the message history settings can be modified by a JMX MBean.
In addition auto-created `MessageHandler` s for annotated endpoints (e.g.
`@ServiceActivator`, `@Splitter` etc.) now are also trackable by `MessageHistory`.
For more information, see <<message-history>>.
[[x4.0-messaging-gateway]]
===== @MessagingGateway
Messaging gateway interfaces can now be configured with the `@MessagingGateway` annotation.
It is an analogue of the `<int:gateway/>` xml element.
For more information, see <<messaging-gateway-annotation>>.
[[x4.0-boot]]
===== Spring Boot @EnableAutoConfiguration
As well as the `@EnableIntegration` annotation mentioned above, a a hook has been introduced to allow the Spring Integration infrastructure beans to be configured using Spring Boot's `@EnableAutoConfiguration`.
For more information seehttp://docs.spring.io/spring-boot/docs/current/reference/html/using-boot-auto-configuration.html[Spring Boot - AutoConfigure].
[[x4.0-global-channel-interceptor]]
===== @GlobalChannelInterceptor
As well as the `@EnableIntegration` annotation mentioned above, the `@GlobalChannelInterceptor` annotation has bean introduced.
For more information, see <<enable-integration>>.
[[x4.0-integration-converter]]
===== @IntegrationConverter
The `@IntegrationConverter` annotation has bean introduced, as an analogue of `<int:converter/>` component.
For more information, see <<enable-integration>>.
[[x4.0-enable-publisher]]
===== @EnablePublisher
The `@EnablePublisher` annotation has been added, to allow the specification of a `default-publisher-channel` for `@Publisher` annotations.
See <<enable-integration>> for more information.
[[x4.0-redis-cms]]
===== Redis Channel Message Stores
A new Redis `MessageGroupStore`, that is optimized for use when backing a `QueueChannel` for persistence, is now provided.
For more information, see <<redis-cms>>.
A new Redis `ChannelPriorityMessageStore` is now provided.
This can be used to retrieve messages by priority.
For more information, see <<redis-cms>>.
[[x4.0-priority-channel-mondodb]]
===== MongodDB Channel Message Store
MongoDB support now provides the `MongoDbChannelMessageStore` - a _channel_ specific `MessageStore` implementation.
With `priorityEnabled = true`, it can be used in `<int:priority-queue>` s to achieve _priority_ order polling of persisted messages.
For more information see <<mongodb-priority-channel-message-store>>.
[[x4.0-MBeanExport-annotation]]
===== @EnableIntegrationMBeanExport
The `IntegrationMBeanExporter` can now be enabled with the `@EnableIntegrationMBeanExport` annotation in a `@Configuration` class.
For more information, see <<jmx-mbean-exporter>>.
[[x4.0-channel-security-interceptor]]
===== ChannelSecurityInterceptorFactoryBean
Configuration of Spring Security for message channels using `@Configuration` classes is now supported by using a `ChannelSecurityInterceptorFactoryBean`.
For more information, see <<security>>.
[[x4.0-redis-outbound-gateway]]
===== Redis Command Gateway
The Redis support now provides the `<outbound-gateway>` component to perform generic Redis commands using the `RedisConnection#execute` method.
For more information, see <<redis-outbound-gateway>>.
[[x4.0-redis-gemfire-lock-registry]]
===== RedisLockRegistry and GemfireLockRegistry
The `RedisLockRegistry` and `GemfireLockRegistry` are now available supporting global locks visible to multiple application instances/servers.
These can be used with aggregating message handlers across multiple application instances such that group release will occur on only one instance.
For more information, see <<redis-lock-registry>>, <<gemfire-lock-registry>> and <<aggregator>>.
[[x4.0-poller-annotation]]
===== @Poller
Annotation-based messaging configuration can now have a `poller` attribute.
This means that methods annotated with (`@ServiceActivator`, `@Aggregator` etc.) can now use an `inputChannel` that is a reference to a `PollableChannel`.
For more information, see <<annotations>>.
[[x4.0-inbound-channel-adapter-annotation]]
===== @InboundChannelAdapter and SmartLifecycle for Annotated Endpoints
The `@InboundChannelAdapter` method annotation is now available.
It is an analogue of the `<int:inbound-channel-adapter>` XML component.
In addition, all Messaging Annotations now provide `SmartLifecycle` options.
For more information, see <<annotations>>.
[[x4.0-twitter-sog]]
===== Twitter Search Outbound Gateway
A new twitter endpoint `<int-twitter-search-outbound-gateway/>` has been added.
Unlike the search inbound adapter which polls using the same search query each time, the outbound gateway allows on-demand customized queries.
For more information, see <<twitter-sog>>.
[[x4.0-gemfire-metadata]]
===== Gemfire Metadata Store
The `GemfireMetadataStore` is provided, allowing it to be used, for example, in a `AbstractPersistentAcceptOnceFileListFilter` implementation in a multiple application instance/server environment.
For more information, see <<metadata-store>>, <<file-reading>>, <<ftp-inbound>> and <<sftp-inbound>>.
[[x4.0-bridge-annotations]]
===== @BridgeFrom and @BridgeTo Annotations
Annotation and Java configuration has introduced `@BridgeFrom` and `@BridgeTo` `@Bean` method annotations to mark `MessageChannel` beans in `@Configuration` classes.
For more information, see <<annotations>>.
[[x4.0-meta-messaging-annotations]]
===== Meta Messaging Annotations
Messaging Annotations (`@ServiceActivator`, `@Router`, `@MessagingGateway` etc.) can now be configured as meta-annotations for user-defined Messaging Annotations.
In addition the user-defined annotations can have the same attributes (`inputChannel`, `@Poller`, `autoStartup` etc.).
For more information, see <<annotations>>.
[[x4.0-general]]
==== General Changes
===== Requires Spring Framework 4.0
Core messaging abstractions (`Message`, `MessageChannel` etc) have moved to the Spring Framework `spring-messaging` module.
Users who reference these classes directly in their code will need to make changes as described in the first section of the https://github.com/spring-projects/spring-integration/wiki/Spring-Integration-3.0-to-4.0-Migration-Guide[Migration Guide].
[[x4.0-xpath-header-enricher-header-type]]
===== Header Type for XPath Header Enricher
The `header-type` attribute has been introduced for the `header` sub-element of the `<int-xml:xpath-header-enricher>`.
This attribute provides the target type for the header value to which the result of the XPath expression evaluation will be converted.
For more information see <<xml-xpath-header-enricher>>.
[[x4.0-object-to-json-transformer-result-type]]
===== Object To Json Transformer: Node Result
The `result-type` attribute has been introduced for the `<int:object-to-json-transformer>`.
This attribute provides the target type for the result of object mapping to JSON.
It supports `STRING` (default) and `NODE`.
For more information see <<transformer-xpath-spel-function>>.
[[x4.0-jms-header-mapping]]
===== JMS Header Mapping
The `DefaultJmsHeaderMapper` now maps an incoming `JMSPriority` header to the Spring Integration `priority` header.
Previously `priority` was only considered for outbound messages.
For more information see <<jms-header-mapping>>.
[[x4.0-jms-ob]]
===== JMS Outbound Channel Adapter
The JMS outbound channel adapter now supports the `session-transacted` attribute (default false).
Previously, you had to inject a customized `JmsTemplate` to use transactions.
See <<jms-outbound-channel-adapter>>.
[[x4.0-jms-ib]]
===== JMS Inbound Channel Adapter
The JMS inbound channel adapter now supports the `session-transacted` attribute (default false).
Previously, you had to inject a customized `JmsTemplate` to use transactions (the adapter allowed 'transacted' in the acknowledgeMode which was incorrect, and didn't work; this value is no longer allowed).
See<<jms-inbound-channel-adapter>>.
[[x4.0-datatype-channel]]
===== Datatype Channels
You can now specify a `MessageConverter` to be used when converting (if necessary) payloads to one of the accepted `datatype` s in a Datatype channel.
For more information see <<channel-datatype-channel>>.
[[x4.0-retry-config]]
===== Simpler Retry Advice Configuration
Simplified namespace support has been added to configure a `RequestHandlerRetryAdvice`.
For more information see <<retry-config>>.
[[x4.0-release-strategy-group-timeout]]
===== Correlation Endpoint: Time-based Release Strategy
The mutually exclusive `group-timeout` and `group-timeout-expression` attributes have been added to the `<int:aggregator>` and `<int:resequencer>`.
These attributes allow forced completion of a partial `MessageGroup`, if the `ReleaseStrategy` does not release a group and no further messages arrive within the time specified.
For more information see <<aggregator-config>>.
[[x4.0-redis-metadata]]
===== Redis Metadata Store
The `RedisMetadataStore` now implements `ConcurrentMetadataStore`, allowing it to be used, for example, in a `AbstractPersistentAcceptOnceFileListFilter` implementation in a multiple application instance/server environment.
For more information, see <<redis-metadata-store>>, <<file-reading>>, <<ftp-inbound>> and <<sftp-inbound>>.
[[x4.0-jdbc-cs]]
===== JdbcChannelMessageStore and PriorityChannel
The `JdbcChannelMessageStore` now implements `PriorityCapableChannelMessageStore`, allowing it to be used as a `message-store` reference for `priority-queue` s.
For more information, see <<jdbc-message-store-channels>>.
[[x4.0-amqp]]
===== AMQP Endpoints Delivery Mode
Spring AMQP, by default, creates persistent messages on the broker.
This behavior can be overridden by setting the `amqp_deliveryMode` header and/or customizing the mappers.
A convenient `default-delivery-mode` attribute has now been added to the adapters to provide easier configuration of this important setting.
For more information, see <<amqp-outbound-channel-adapter>> and <<amqp-outbound-gateway>>.
[[x4.0-ftp]]
===== FTP Timeouts
The `DefaultFtpSessionFactory` now exposes the `connectTimeout`, `defaultTimeout` and `dataTimeout` properties, avoiding the need to subclass the factory just to set these common properties.
The `postProcess*` methods are still available for more advanced configuration.
See <<ftp-session-factory>> for more information.
[[x4.0-twitter-status-updating]]
===== Twitter: StatusUpdatingMessageHandler
The `StatusUpdatingMessageHandler` (`<int-twitter:outbound-channel-adapter>`) now supports the `tweet-data-expression` attribute to build a `org.springframework.social.twitter.api.TweetData` object for updating the timeline status allowing, for example, attaching an image.
See <<outbound-twitter-update>> for more information.
[[x4.0-jpa-id-expression]]
===== JPA Retrieving Gateway: id-expression
The `id-expression` attribute has been introduced for `<int-jpa:retrieving-outbound-gateway>` to perform `EntityManager.find(Class entityClass, Object primaryKey)`.
See <<jpa-retrieving-outbound-gateway>> for more information.
[[x4.0-tcp-deserializer-events]]
===== TCP Deserialization Events
When one of the standard deserializers encounters a problem decoding the input stream to a message, it will now emit a `TcpDeserializationExceptionEvent`, allowing applications to examine the data at the point the exception occurred.
See <<tcp-events>> for more information.
[[x4.0-bean-messaging-annotations]]
===== Messaging Annotations on @Bean Definitions
Messaging Annotations (`@ServiceActivator`, `@Router`, `@InboundChannelAdapter` etc.) can now be configured on `@Bean` definitions in `@Configuration` classes.
For more information, see <<annotations>>.

225
src/reference/asciidoc/changes-4.0-4.1.adoc Normal file
View File

@@ -0,0 +1,225 @@
[[migration-4.0-4.1]]
=== Changes between 4.0 and 4.1
Please be sure to also see the https://github.com/spring-projects/spring-integration/wiki/Spring-Integration-4.0-to-4.1-Migration-Guide[Migration Guide] for important changes that might affect your applications.
Migration guides for all versions back to _2.1_ can be found on the https://github.com/spring-projects/spring-integration/wiki[Wiki].
==== New Components
[[x4.1-promise-gateway]]
===== Promise<?> Gateway
A Reactor `Promise` return type is now supported for Messaging Gateway methods.
See <<async-gateway>>.
[[x4.1-web-socket-adapters]]
===== WebSocket support
The _WebSocket_ module is now available.
It is fully based on the Spring WebSocket and Spring Messaging modules and provides an `<inbound-channel-adapter>` and an `<outbound-channel-adapter>`.
See <<web-sockets>> for more information.
[[x4.1-scatter-gather]]
===== Scatter-Gather EIP pattern
The _Scatter-Gather_ EIP pattern is now implemented.
See <<scatter-gather>> for more information.
[[x4.1-Routing-Slip]]
===== Routing Slip Pattern
The _Routing Slip_ EIP pattern implementation is now provided.
See <<routing-slip>> for more information.
[[x4.1-idempotent-receiver]]
===== Idempotent Receiver Pattern
The _Idempotent Receiver_ EIP implementation is now provided via the `<idempotent-receiver>` component in XML, or the `IdempotentReceiverInterceptor` and `IdempotentReceiver` annotation when using Java Configuration.
See <<idempotent-receiver>> and their JavaDocs for more information.
[[x4.1-BoonJsonObjectMapper]]
===== BoonJsonObjectMapper
The _Boon_`JsonObjectMapper` is now provided for the JSON transformers.
See <<transformer>> for more information.
[[x4.1-redis-queue-gateways]]
===== Redis Queue Gateways
The `<redis-queue-inbound-gateway>` and `<redis-queue-outbound-gateway>` components are now provided.
See <<redis-queue-inbound-gateway>> and <<redis-queue-outbound-gateway>>.
[[x4.1-PollSkipAdvice]]
===== PollSkipAdvice
The `PollSkipAdvice` is now provided to be used within `<advice-chain>` of the `<poller>` to determine if the current _poll_ should be suppressed (skipped) by some condition implemented with `PollSkipStrategy`.
See <<polling-consumer>> for more information.
[[x4.1-general]]
==== General Changes
[[x4.1-amqp-inbound-missing-queues]]
===== AMQP Inbound Endpoints, Channel
Elements that utilize a message listener container (inbound endpoints, channel) now support the `missing-queues-fatal` attribute.
See <<amqp>> for more information.
[[x4.1-amqp-outbound-lazy-connect]]
===== AMQP Outbound Endpoints
The AMQP outbound endpoints support a new property `lazy-connect` (default true).
When true, the connection to the broker is not established until the first message arrives (assuming there are no inbound endpoints, which always attempt to establish the connection during startup).
When set the 'false' an attempt to establish the connection is made during application startup.
See <<amqp>> for more information.
[[x4.1-sms-copy-on-get]]
===== SimpleMessageStore
The `SimpleMessageStore` no longer makes a copy of the group when calling `getMessageGroup()`.
See <<sms-caution>> for more information.
[[x4.1-ws-encode-uri]]
===== Web Service Outbound Gateway: encode-uri
The `<ws:outbound-gateway/>` now provides an `encode-uri` attribute to allow disabling the encoding of the URI object before sending the request.
[[x4.1-http-status-code]]
===== Http Inbound Channel Adapter and StatusCode
The `<http:inbound-channel-adapter>` can now be configured with a `status-code-expression` to override the default `200 OK` status.
See <<http-namespace>> for more information.
[[x4.1-mqtt]]
===== MQTT Adapter Changes
The MQTT channel adapters can now be configured to connect to multiple servers, for example, to support High Availability (HA).
See <<mqtt>> for more information.
The MQTT message-driven channel adapter now supports specifying the QoS setting for each subscription.
See <<mqtt-inbound>> for more information.
The MQTT outbound channel adapter now supports asynchronous sends, avoiding blocking until delivery is confirmed.
See <<mqtt-outbound>> for more information.
It is now possible to programmatically subscribe to and unsubscribe from topics at runtime.
See <<mqtt-inbound>> for more information.
[[x4.1-sftp]]
===== FTP/SFTP Adapter Changes
The FTP and SFTP outbound channel adapters now support appending to remote files, as well as taking specific actions when a remote file already exists.
The remote file templates now also support this as well as `rmdir()` and `exists()`.
In addition, the remote file templates provide access to the underlying client object enabling access to low-level APIs.
See <<ftp>> and <<sftp>> for more information.
[[x4.1-splitter-iterator]]
===== Splitter and Iterator
`Splitter` components now support an `Iterator` as the result object for producing output messages.
See <<splitter>> for more information.
[[x4.1-aggregator]]
===== Aggregator
`Aggregator` s now support a new attribute `expire-groups-on-timeout`.
See <<aggregator-config>> for more information.
[[x4.1-content-enricher-improvement]]
===== Content Enricher Improvements
An `null-result-expression` attribute has been added, which is evaluated and returned if `<enricher>` returns `null`.
It can be added in `<header>` and `<property>`.
See <<content-enricher>> for more information.
An `error-channel` attribute has been added, which is used to handle an error flow if `Exception` occurs downstream of the `request-channel`.
This enable you to return an alternative object to use for enrichment.
See <<content-enricher>> for more information.
[[x4.1-header-channel-registry]]
===== Header Channel Registry
The `<header-enricher/>`'s `<header-channels-to-string/>` element can now override the header channel registry's default time for retaining channel mappings.
See <<header-channel-registry>> for more information.
[[x4.1-orderly-shutdown]]
===== Orderly Shutdown
Improvements have been made to the orderly shutdown algorithm.
See <<jmx-shutdown>> for more information.
[[x4.1-recipientListRouter]]
===== Management for RecipientListRouter
The `RecipientListRouter` provides now several _management_ operations to configure _recipients_ at runtime.
With that the `<recipient-list-router>` can now be configured without any `<recipient>` from the start.
See <<recipient-list-router-management>> for more information.
[[x4.1-AbstractHeaderMapper-changes]]
===== AbstractHeaderMapper: NON_STANDARD_HEADERS token
The `AbstractHeaderMapper` implementations now provides the additional `NON_STANDARD_HEADERS` token to map any user-defined headers, which aren't mapped by default.
See <<amqp-message-headers>> for more information.
[[x4.1-amqp-channels]]
===== AMQP Channels: template-channel-transacted
The new `template-channel-transacted` attribute has been introduced for AMQP `MessageChannel` s.
See <<amqp-channels>> for more information.
[[x4.1-syslog]]
===== Syslog Adapter
The default syslog message converter now has an option to retain the original message in the payload, while still setting the headers.
See <<syslog-inbound-adapter>> for more information.
[[x4.1-async-gateway]]
===== Async Gateway
In addition to the `Promise` return type mentioned above, gateway methods may now return a `ListenableFuture`, introduced in Spring Framework 4.0.
You can also disable the async processing in the gateway, allowing a downstream flow to directly return a `Future`.
See <<async-gateway>>.
[[x4.1-aggregator-advice-chain]]
===== Aggregator Advice Chain
`Aggregator` s and `Resequencer` s now support an `<expire-advice-chain/>` and `<expire-transactional/>` sub-elements to _advise_ the `forceComplete` operation.
See <<aggregator-config>> for more information.
[[x4.1-script-outbound-channel-adapter]]
===== Outbound Channel Adapter and Scripts
The `<int:outbound-channel-adapter/>` now supports the `<script/>` sub-element.
The underlying script must have a `void` return type or return `null`.
See <<groovy>> and <<scripting>>.
[[x4.1-reseq]]
===== Resequencer Changes
When a message group in a resequencer is timed out (using `group-timeout` or a `MessageGroupStoreReaper`), late arriving messages will now be discarded immediately by default.
See <<resequencer>>.
[[x4.1-Optional-Parameter]]
===== Optional POJO method parameter
Now Spring Integration consistently handles the Java 8's `Optional` type.
See <<service-activator-namespace>>.
[[x4.1-queue-channel-queue.typ]]
===== QueueChannel: backed Queue type
The `QueueChannel` backed `Queue type` has been changed from `BlockingQueue` to the more generic `Queue`.
It allows the use of any external `Queue` implementation, for example Reactor's `PersistentQueue`.
See <<channel-configuration-queuechannel>>.
[[x4.1-channel-interceptor]]
===== ChannelInterceptor Changes
The `ChannelInterceptor` now supports additional `afterSendCompletion()` and `afterReceiveCompletion()` methods.
See <<channel-interceptors>>.
[[x4.1-mail-peek]]
===== IMAP PEEK
Since _version 4.1.1_ there is a change of behavior if you explicitly set the javamail property `mail.[protocol].peek` to `false` (where `[protocol]` is `imap` or `imaps`).
See <<imap-peek>>.

4
src/reference/asciidoc/changes-4.1-4.2.adoc Normal file
View File

@@ -0,0 +1,4 @@
[[migration-4.1-4.2]]
=== Changes between 4.1 and 4.2
For an overview of the changes in Spring Integration 4.2 since version 4.1, please see <<whats-new>>.

142
src/reference/asciidoc/channel-adapter.adoc Normal file
View File

@@ -0,0 +1,142 @@
[[channel-adapter]]
=== Channel Adapter
A Channel Adapter is a Message Endpoint that enables connecting a single sender or receiver to a Message Channel.
Spring Integration provides a number of adapters out of the box to support various transports, such as JMS, File, HTTP, Web Services, Mail, and more.
Those will be discussed in upcoming chapters of this reference guide.
However, this chapter focuses on the simple but flexible Method-invoking Channel Adapter support.
There are both inbound and outbound adapters, and each may be configured with XML elements provided in the core namespace.
These provide an easy way to extend Spring Integration as long as you have a method that can be invoked as either a source or destination.
[[channel-adapter-namespace-inbound]]
==== Configuring An Inbound Channel Adapter
An "inbound-channel-adapter" element can invoke any method on a Spring-managed Object and send a non-null return value to a `MessageChannel` after converting it to a `Message`.
When the adapter's subscription is activated, a poller will attempt to receive messages from the source.
The poller will be scheduled with the `TaskScheduler` according to the provided configuration.
To configure the polling interval or cron expression for an individual channel-adapter, provide a 'poller' element with one of the scheduling attributes, such as 'fixed-rate' or 'cron'.
[source,xml]
----
<int:inbound-channel-adapter ref="source1" method="method1" channel="channel1">
<int:poller fixed-rate="5000"/>
</int:inbound-channel-adapter>
<int:inbound-channel-adapter ref="source2" method="method2" channel="channel2">
<int:poller cron="30 * 9-17 * * MON-FRI"/>
</int:channel-adapter>
----
Also see <<channel-adapter-expressions-and-scripts>>.
NOTE: If no poller is provided, then a single default poller must be registered within the context.
See <<endpoint-namespace>> for more detail.
[IMPORTANT]
.Important: Poller Configuration
=====
Some `inbound-channel-adapter` types are backed by a `SourcePollingChannelAdapter` which means they contain Poller configuration which will poll the `MessageSource` (invoke a custom method which produces the value that becomes a `Message` payload) based on the configuration specified in the Poller.
For example:
[source,xml]
----
<int:poller max-messages-per-poll="1" fixed-rate="1000"/>
<int:poller max-messages-per-poll="10" fixed-rate="1000"/>
----
In the the first configuration the polling task will be invoked once per poll and during such task (poll) the method (which results in the production of the Message) will be invoked once based on the `max-messages-per-poll` attribute value.
In the second configuration the polling task will be invoked 10 times per poll or until it returns 'null' thus possibly producing 10 Messages per poll while each poll happens at 1 second intervals.
However what if the configuration looks like this:
[source,xml]
----
<int:poller fixed-rate="1000"/>
----
Note there is no `max-messages-per-poll` specified.
As you'll learn later the identical poller configuration in the `PollingConsumer` (e.g., service-activator, filter, router etc.) would have a default value of -1 for `max-messages-per-poll` which means "execute poling task non-stop unless polling method returns null (e.g., no more Messages in the QueueChannel)" and then sleep for 1 second.
However in the SourcePollingChannelAdapter it is a bit different.
The default value for `max-messages-per-poll` will be set to 1 by default unless you explicitly set it to a negative value (e.g., -1).
It is done so to make sure that poller can react to a LifeCycle events (e.g., start/stop) and prevent it from potentially spinning in the infinite loop if the implementation of the custom method of the `MessageSource` has a potential to never return null and happened to be non-interruptible.
However if you are sure that your method can return null and you need the behavior where you want to poll for as many sources as available per each poll, then you should explicitly set `max-messages-per-poll` to a negative value.
[source,xml]
----
<int:poller max-messages-per-poll="-1" fixed-rate="1000"/>
----
=====
[[channel-adapter-namespace-outbound]]
==== Configuring An Outbound Channel Adapter
An "outbound-channel-adapter" element can also connect a `MessageChannel` to any POJO consumer method that should be invoked with the payload of Messages sent to that channel.
[source,xml]
----
<int:outbound-channel-adapter channel="channel1" ref="target" method="handle"/>
<beans:bean id="target" class="org.Foo"/>
----
If the channel being adapted is a `PollableChannel`, provide a poller sub-element:
[source,xml]
----
<int:outbound-channel-adapter channel="channel2" ref="target" method="handle">
<int:poller fixed-rate="3000" />
</int:outbound-channel-adapter>
<beans:bean id="target" class="org.Foo"/>
----
Using a "ref" attribute is generally recommended if the POJO consumer implementation can be reused in other `<outbound-channel-adapter>` definitions.
However if the consumer implementation is only referenced by a single definition of the `<outbound-channel-adapter>`, you can define it as inner bean:
[source,xml]
----
<int:outbound-channel-adapter channel="channel" method="handle">
<beans:bean class="org.Foo"/>
</int:outbound-channel-adapter>
----
NOTE: Using both the "ref" attribute and an inner handler definition in the same `<outbound-channel-adapter>` configuration is not allowed as it creates an ambiguous condition.
Such a configuration will result in an Exception being thrown.
Any Channel Adapter can be created without a "channel" reference in which case it will implicitly create an instance of `DirectChannel`.
The created channel's name will match the "id" attribute of the `<inbound-channel-adapter>` or `<outbound-channel-adapter>` element.
Therefore, if the "channel" is not provided, the "id" is required.
[[channel-adapter-expressions-and-scripts]]
==== Channel Adapter Expressions and Scripts
Like many other Spring Integration components, the `<inbound-channel-adapter>` and `<outbound-channel-adapter>` also provide support for SpEL expression evaluation.
To use SpEL, provide the expression string via the 'expression' attribute instead of providing the 'ref' and 'method' attributes that are used for method-invocation on a bean.
When an Expression is evaluated, it follows the same contract as method-invocation where: the _expression_ for an `<inbound-channel-adapter>` will generate a message anytime the evaluation result is a _non-null_ value, while the _expression_ for an `<outbound-channel-adapter>` must be the equivalent of a _void_ returning method invocation.
Starting with Spring Integration 3.0, an `<int:inbound-channel-adapter/>` can also be configured with a SpEL `<expression/>` (or even with `<script/>`) sub-element, for when more sophistication is required than can be achieved with the simple 'expression' attribute.
If you provide a script as a `Resource` using the `location` attribute, you can also set the _refresh-check-delay_ allowing the resource to be refreshed periodically.
If you want the script to be checked on each poll, you would need to coordinate this setting with the poller's trigger:
[source,xml]
----
<int:inbound-channel-adapter ref="source1" method="method1" channel="channel1">
<int:poller max-messages-per-poll="1" fixed-delay="5000"/>
<script:script lang="ruby" location="Foo.rb" refresh-check-delay="5000"/>
</int:inbound-channel-adapter>
----
Also see the `cacheSeconds` property on the `ReloadableResourceBundleExpressionSource` when using the `<expression/>` sub-element.
For more information regarding expressions see <<spel>>, and for scripts - <<groovy>> and <<scripting>>.
IMPORTANT: The `<int:inbound-channel-adapter/>` is an endpoint that starts a message flow via periodic triggering to poll some underlying `MessageSource`.
Since, at the time of polling, there is not yet a message object, expressions and scripts don't have access to a root `Message`, so there are no _payload_ or _headers_ properties that are available in most other messaging SpEL expressions.
Of course, the script *can* generate and return a complete `Message` object with headers and payload, or just a payload, which will be added to a message with basic headers.

788
src/reference/asciidoc/channel.adoc Normal file
View File

@@ -0,0 +1,788 @@
[[channel]]
=== Message Channels
While the `Message` plays the crucial role of encapsulating data, it is the `MessageChannel` that decouples message producers from message consumers.
[[channel-interfaces]]
==== The MessageChannel Interface
Spring Integration's top-level `MessageChannel` interface is defined as follows.
[source,java]
----
public interface MessageChannel {
boolean send(Message message);
boolean send(Message message, long timeout);
}
----
When sending a message, the return value will be _true_ if the message is sent successfully.
If the send call times out or is interrupted, then it will return _false_.
[[channel-interfaces-pollablechannel]]
===== PollableChannel
Since Message Channels may or may not buffer Messages (as discussed in the overview), there are two sub-interfaces defining the buffering (pollable) and non-buffering (subscribable) channel behavior.
Here is the definition of `PollableChannel`.
[source,java]
----
public interface PollableChannel extends MessageChannel {
Message<?> receive();
Message<?> receive(long timeout);
}
----
Similar to the send methods, when receiving a message, the return value will be _null_ in the case of a timeout or interrupt.
[[channel-interfaces-subscribablechannel]]
===== SubscribableChannel
The `SubscribableChannel` base interface is implemented by channels that send Messages directly to their subscribed `MessageHandler` s.
Therefore, they do not provide receive methods for polling, but instead define methods for managing those subscribers:
[source,java]
----
public interface SubscribableChannel extends MessageChannel {
boolean subscribe(MessageHandler handler);
boolean unsubscribe(MessageHandler handler);
}
----
[[channel-implementations]]
==== Message Channel Implementations
Spring Integration provides several different Message Channel implementations.
Each is briefly described in the sections below.
[[channel-implementations-publishsubscribechannel]]
===== PublishSubscribeChannel
The `PublishSubscribeChannel` implementation broadcasts any Message sent to it to all of its subscribed handlers.
This is most often used for sending_Event Messages_ whose primary role is notification as opposed to _Document Messages_ which are generally intended to be processed by a single handler.
Note that the `PublishSubscribeChannel` is intended for sending only.
Since it broadcasts to its subscribers directly when its` send(Message)` method is invoked, consumers cannot poll for Messages (it does not implement `PollableChannel` and therefore has no `receive()` method).
Instead, any subscriber must be a `MessageHandler` itself, and the subscriber's `handleMessage(Message)` method will be invoked in turn.
Prior to version 3.0, invoking the send method on a `PublishSubscribeChannel` that had no subscribers returned `false`.
When used in conjunction with a `MessagingTemplate`, a `MessageDeliveryException` was thrown.
Starting with version 3.0, the behavior has changed such that a send is always considered successful if at least the minimum subscribers are present (and successfully handle the message).
This behavior can be modified by setting the `minSubscribers` property, which defaults to `0`.
NOTE: If a `TaskExecutor` is used, only the presence of the correct number of subscribers is used for this determination, because the actual handling of the message is performed asynchronously.
[[channel-implementations-queuechannel]]
===== QueueChannel
The `QueueChannel` implementation wraps a queue.
Unlike the `PublishSubscribeChannel`, the `QueueChannel` has point-to-point semantics.
In other words, even if the channel has multiple consumers, only one of them should receive any Message sent to that channel.
It provides a default no-argument constructor (providing an essentially unbounded capacity of `Integer.MAX_VALUE`) as well as a constructor that accepts the queue capacity:
[source,java]
----
public QueueChannel(int capacity)
----
A channel that has not reached its capacity limit will store messages in its internal queue, and the `send()` method will return immediately even if no receiver is ready to handle the message.
If the queue has reached capacity, then the sender will block until room is available.
Or, if using the send call that accepts a timeout, it will block until either room is available or the timeout period elapses, whichever occurs first.
Likewise, a receive call will return immediately if a message is available on the queue, but if the queue is empty, then a receive call may block until either a message is available or the timeout elapses.
In either case, it is possible to force an immediate return regardless of the queue's state by passing a timeout value of 0.
Note however, that calls to the no-arg versions of `send()` and `receive()` will block indefinitely.
[[channel-implementations-prioritychannel]]
===== PriorityChannel
Whereas the `QueueChannel` enforces first-in/first-out (FIFO) ordering, the `PriorityChannel` is an alternative implementation that allows for messages to be ordered within the channel based upon a priority.
By default the priority is determined by the '`priority`' header within each message.
However, for custom priority determination logic, a comparator of type `Comparator<Message<?>>` can be provided to the `PriorityChannel`'s constructor.
[[channel-implementations-rendezvouschannel]]
===== RendezvousChannel
The `RendezvousChannel` enables a "direct-handoff" scenario where a sender will block until another party invokes the channel's `receive()` method or vice-versa.
Internally, this implementation is quite similar to the `QueueChannel` except that it uses a `SynchronousQueue` (a zero-capacity implementation of `BlockingQueue`).
This works well in situations where the sender and receiver are operating in different threads but simply dropping the message in a queue asynchronously is not appropriate.
In other words, with a `RendezvousChannel` at least the sender knows that some receiver has accepted the message, whereas with a `QueueChannel`, the message would have been stored to the internal queue and potentially never received.
TIP: Keep in mind that all of these queue-based channels are storing messages in-memory only by default.
When persistence is required, you can either provide a 'message-store' attribute within the 'queue' element to reference a persistent MessageStore implementation, or you can replace the local channel with one that is backed by a persistent broker, such as a JMS-backed channel or Channel Adapter.
The latter option allows you to take advantage of any JMS provider's implementation for message persistence, and it will be discussed in <<jms>>.
However, when buffering in a queue is not necessary, the simplest approach is to rely upon the `DirectChannel` discussed next.
The `RendezvousChannel` is also useful for implementing request-reply operations.
The sender can create a temporary, anonymous instance of `RendezvousChannel` which it then sets as the 'replyChannel' header when building a Message.
After sending that Message, the sender can immediately call receive (optionally providing a timeout value) in order to block while waiting for a reply Message.
This is very similar to the implementation used internally by many of Spring Integration's request-reply components.
[[channel-implementations-directchannel]]
===== DirectChannel
The `DirectChannel` has point-to-point semantics but otherwise is more similar to the `PublishSubscribeChannel` than any of the queue-based channel implementations described above.
It implements the `SubscribableChannel` interface instead of the `PollableChannel` interface, so it dispatches Messages directly to a subscriber.
As a point-to-point channel, however, it differs from the `PublishSubscribeChannel` in that it will only send each Message to a _single_ subscribed `MessageHandler`.
In addition to being the simplest point-to-point channel option, one of its most important features is that it enables a single thread to perform the operations on "both sides" of the channel.
For example, if a handler is subscribed to a `DirectChannel`, then sending a Message to that channel will trigger invocation of that handler's `handleMessage(Message)` method _directly in the
sender's thread_, before the send() method invocation can return.
The key motivation for providing a channel implementation with this behavior is to support transactions that must span across the channel while still benefiting from the abstraction and loose coupling that the channel provides.
If the send call is invoked within the scope of a transaction, then the outcome of the handler's invocation (e.g.
updating a database record) will play a role in determining the ultimate result of that transaction (commit or rollback).
NOTE: Since the `DirectChannel` is the simplest option and does not add any additional overhead that would be required for scheduling and managing the threads of a poller, it is the default channel type within Spring Integration.
The general idea is to define the channels for an application and then to consider which of those need to provide buffering or to throttle input, and then modify those to be queue-based `PollableChannels`.
Likewise, if a channel needs to broadcast messages, it should not be a `DirectChannel` but rather a `PublishSubscribeChannel`.
Below you will see how each of these can be configured.
The `DirectChannel` internally delegates to a Message Dispatcher to invoke its subscribed Message Handlers, and that dispatcher can have a load-balancing strategy exposed via_load-balancer_ or _load-balancer-ref_ attributes (mutually exclusive).
The load balancing strategy is used by the Message Dispatcher to help determine how Messages are distributed amongst Message Handlers in the case that there are multiple Message Handlers subscribed to the same channel.
As a convinience the _load-balancer_ attribute exposes enumeration of values pointing to pre-existing implementations of `LoadBalancingStrategy`.
The "round-robin" (load-balances across the handlers in rotation) and "none" (for the cases where one wants to explicitely disable load balancing) are the only available values.
Other strategy implementations may be added in future versions.
However, since version 3.0 you can provide your own implementation of the `LoadBalancingStrategy` and inject it using _load-balancer-ref_ attribute which should point to a bean that implements `LoadBalancingStrategy`.
[source,xml]
----
<int:channel id="lbRefChannel">
<int:dispatcher load-balancer-ref="lb"/>
</int:channel>
<bean id="lb" class="foo.bar.SampleLoadBalancingStrategy"/>
----
Note that _load-balancer_ or _load-balancer-ref_ attributes are mutually exclusive.
The load-balancing also works in combination with a boolean _failover_ property.
If the "failover" value is true (the default), then the dispatcher will fall back to any subsequent handlers as necessary when preceding handlers throw Exceptions.
The order is determined by an optional order value defined on the handlers themselves or, if no such value exists, the order in which the handlers are subscribed.
If a certain situation requires that the dispatcher always try to invoke the first handler, then fallback in the same fixed order sequence every time an error occurs, no load-balancing strategy should be provided.
In other words, the dispatcher still supports the failover boolean property even when no load-balancing is enabled.
Without load-balancing, however, the invocation of handlers will always begin with the first according to their order.
For example, this approach works well when there is a clear definition of primary, secondary, tertiary, and so on.
When using the namespace support, the "order" attribute on any endpoint will determine that order.
NOTE: Keep in mind that load-balancing and failover only apply when a channel has more than one subscribed Message Handler.
When using the namespace support, this means that more than one endpoint shares the same channel reference in the "input-channel" attribute.
[[executor-channel]]
===== ExecutorChannel
The `ExecutorChannel` is a point-to-point channel that supports the same dispatcher configuration as `DirectChannel` (load-balancing strategy and the failover boolean property).
The key difference between these two dispatching channel types is that the `ExecutorChannel` delegates to an instance of `TaskExecutor` to perform the dispatch.
This means that the send method typically will not block, but it also means that the handler invocation may not occur in the sender's thread.
It therefore _does not support transactions spanning the sender and receiving handler_.
TIP: Note that there are occasions where the sender may block.
For example, when using a TaskExecutor with a rejection-policy that throttles back on the client (such as the `ThreadPoolExecutor.CallerRunsPolicy`), the sender's thread will execute the method directly anytime the thread pool is at its maximum capacity and the executor's work queue is full.
Since that situation would only occur in a non-predictable way, that obviously cannot be relied upon for transactions.
[[channel-implementations-threadlocalchannel]]
===== Scoped Channel
Spring Integration 1.0 provided a `ThreadLocalChannel` implementation, but that has been removed as of 2.0.
Now, there is a more general way for handling the same requirement by simply adding a "scope" attribute to a channel.
The value of the attribute can be any name of a Scope that is available within the context.
For example, in a web environment, certain Scopes are available, and any custom Scope implementations can be registered with the context.
Here's an example of a ThreadLocal-based scope being applied to a channel, including the registration of the Scope itself.
[source,xml]
----
<int:channel id="threadScopedChannel" scope="thread">
<int:queue />
</int:channel>
<bean class="org.springframework.beans.factory.config.CustomScopeConfigurer">
<property name="scopes">
<map>
<entry key="thread" value="org.springframework.context.support.SimpleThreadScope" />
</map>
</property>
</bean>
----
The channel above also delegates to a queue internally, but the channel is bound to the current thread, so the contents of the queue are as well.
That way the thread that sends to the channel will later be able to receive those same Messages, but no other thread would be able to access them.
While thread-scoped channels are rarely needed, they can be useful in situations where `DirectChannels` are being used to enforce a single thread of operation but any reply Messages should be sent to a "terminal" channel.
If that terminal channel is thread-scoped, the original sending thread can collect its replies from it.
Now, since any channel can be scoped, you can define your own scopes in addition to Thread Local.
[[channel-interceptors]]
==== Channel Interceptors
One of the advantages of a messaging architecture is the ability to provide common behavior and capture meaningful information about the messages passing through the system in a non-invasive way.
Since the `Message` s are being sent to and received from `MessageChannels`, those channels provide an opportunity for intercepting the send and receive operations.
The `ChannelInterceptor` strategy interface provides methods for each of those operations:
[source,java]
----
public interface ChannelInterceptor {
Message<?> preSend(Message<?> message, MessageChannel channel);
void postSend(Message<?> message, MessageChannel channel, boolean sent);
void afterSendCompletion(Message<?> message, MessageChannel channel, boolean sent, Exception ex);
boolean preReceive(MessageChannel channel);
Message<?> postReceive(Message<?> message, MessageChannel channel);
void afterReceiveCompletion(Message<?> message, MessageChannel channel, Exception ex);
}
----
After implementing the interface, registering the interceptor with a channel is just a matter of calling:
[source,java]
----
channel.addInterceptor(someChannelInterceptor);
----
The methods that return a Message instance can be used for transforming the Message or can return 'null' to prevent further processing (of course, any of the methods can throw a RuntimeException).
Also, the `preReceive` method can return '`false`' to prevent the receive operation from proceeding.
NOTE: Keep in mind that `receive()` calls are only relevant for `PollableChannels`.
In fact the `SubscribableChannel` interface does not even define a `receive()` method.
The reason for this is that when a Message is sent to a `SubscribableChannel` it will be sent directly to one or more subscribers depending on the type of channel (e.g.
a PublishSubscribeChannel sends to all of its subscribers).
Therefore, the `preReceive(..)` and `postReceive(..)` interceptor methods are only invoked when the interceptor is applied to a `PollableChannel`.
Spring Integration also provides an implementation of the http://eaipatterns.com/WireTap.html[Wire Tap] pattern.
It is a simple interceptor that sends the Message to another channel without otherwise altering the existing flow.
It can be very useful for debugging and monitoring.
An example is shown in <<channel-wiretap>>.
Because it is rarely necessary to implement all of the interceptor methods, a `ChannelInterceptorAdapter` class is also available for sub-classing.
It provides no-op methods (the `void` method is empty, the `Message` returning methods return the Message as-is, and the `boolean` method returns `true`).
Therefore, it is often easiest to extend that class and just implement the method(s) that you need as in the following example.
[source,java]
----
public class CountingChannelInterceptor extends ChannelInterceptorAdapter {
private final AtomicInteger sendCount = new AtomicInteger();
@Override
public Message<?> preSend(Message<?> message, MessageChannel channel) {
sendCount.incrementAndGet();
return message;
}
}
----
TIP: The order of invocation for the interceptor methods depends on the type of channel.
As described above, the queue-based channels are the only ones where the receive method is intercepted in the first place.
Additionally, the relationship between send and receive interception depends on the timing of separate sender and receiver threads.
For example, if a receiver is already blocked while waiting for a message the order could be: preSend, preReceive, postReceive, postSend.
However, if a receiver polls after the sender has placed a message on the channel and already returned, the order would be: preSend, postSend, (some-time-elapses) preReceive, postReceive.
The time that elapses in such a case depends on a number of factors and is therefore generally unpredictable (in fact, the receive may never happen!).
Obviously, the type of queue also plays a role (e.g.
rendezvous vs.
priority).
The bottom line is that you cannot rely on the order beyond the fact that preSend will precede postSend and preReceive will precede postReceive.
Starting with _Spring Framework 4.1_ and Spring Integration 4.1, the `ChannelInterceptor` provides new methods - `afterSendCompletion()` and `afterReceiveCompletion()`.
They are invoked after `send()/receive()` calls, regardless of any exception that is raised, thus allowing for resource cleanup.
Note, the Channel invokes these methods on the ChannelInterceptor List in the reverse order of the initial `preSend()/preReceive()` calls.
[[channel-template]]
==== MessagingTemplate
As you will see when the endpoints and their various configuration options are introduced, Spring Integration provides a foundation for messaging components that enables non-invasive invocation of your application code_from the messaging system_.
However, sometimes it is necessary to invoke the messaging system _from your application code_.
For convenience when implementing such use-cases, Spring Integration provides a `MessagingTemplate` that supports a variety of operations across the Message Channels, including request/reply scenarios.
For example, it is possible to send a request and wait for a reply.
[source,java]
----
MessagingTemplate template = new MessagingTemplate();
Message reply = template.sendAndReceive(someChannel, new GenericMessage("test"));
----
In that example, a temporary anonymous channel would be created internally by the template.
The 'sendTimeout' and 'receiveTimeout' properties may also be set on the template, and other exchange types are also supported.
[source,java]
----
public boolean send(final MessageChannel channel, final Message<?> message) { ...
}
public Message<?> sendAndReceive(final MessageChannel channel, final Message<?> request) { ..
}
public Message<?> receive(final PollableChannel<?> channel) { ...
}
----
NOTE: A less invasive approach that allows you to invoke simple interfaces with payload and/or header values instead of Message instances is described in <<gateway-proxy>>.
[[channel-configuration]]
==== Configuring Message Channels
To create a Message Channel instance, you can use the <channel/> element:
[source,xml]
----
<int:channel id="exampleChannel"/>
----
The default channel type is _Point to Point_.
To create a _Publish Subscribe_ channel, use the <publish-subscribe-channel/> element:
[source,xml]
----
<int:publish-subscribe-channel id="exampleChannel"/>
----
When using the <channel/> element without any sub-elements, it will create a `DirectChannel` instance (a `SubscribableChannel`).
However, you can alternatively provide a variety of <queue/> sub-elements to create any of the pollable channel types (as described in<<channel-implementations>>).
Examples of each are shown below.
[[channel-configuration-directchannel]]
===== DirectChannel Configuration
As mentioned above, `DirectChannel` is the default type.
[source,xml]
----
<int:channel id="directChannel"/>
----
A default channel will have a _round-robin_ load-balancer and will also have failover enabled (See the discussion in <<channel-implementations-directchannel>> for more detail).
To disable one or both of these, add a <dispatcher/> sub-element and configure the attributes:
[source,xml]
----
<int:channel id="failFastChannel">
<int:dispatcher failover="false"/>
</channel>
<int:channel id="channelWithFixedOrderSequenceFailover">
<int:dispatcher load-balancer="none"/>
</int:channel>
----
[[channel-datatype-channel]]
===== Datatype Channel Configuration
There are times when a consumer can only process a particular type of payload and you need to therefore ensure the payload type of input Messages.
Of course the first thing that comes to mind is Message Filter.
However all that Message Filter will do is filter out Messages that are not compliant with the requirements of the consumer.
Another way would be to use a Content Based Router and route Messages with non-compliant data-types to specific Transformers to enforce transformation/conversion to the required data-type.
This of course would work, but a simpler way of accomplishing the same thing is to apply the http://www.eaipatterns.com/DatatypeChannel.html[Datatype Channel] pattern.
You can use separate Datatype Channels for each specific payload data-type.
To create a Datatype Channel that only accepts messages containing a certain payload type, provide the fully-qualified class name in the channel element's `datatype` attribute:
[source,xml]
----
<int:channel id="numberChannel" datatype="java.lang.Number"/>
----
Note that the type check passes for any type that is _assignable_ to the channel's datatype.
In other words, the "numberChannel" above would accept messages whose payload is `java.lang.Integer` or `java.lang.Double`.
Multiple types can be provided as a comma-delimited list:
[source,xml]
----
<int:channel id="stringOrNumberChannel" datatype="java.lang.String,java.lang.Number"/>
----
So the 'numberChannel' above will only accept Messages with a data-type of `java.lang.Number`.
But what happens if the payload of the Message is not of the required type? It depends on whether you have defined a bean named "integrationConversionService" that is an instance of Spring's http://static.springsource.org/spring/docs/current/spring-framework-reference/html/validation.html#core-convert-ConversionService-API[Conversion Service].
If not, then an Exception would be thrown immediately, but if you do have an "integrationConversionService" bean defined, it will be used in an attempt to convert the Message's payload to the acceptable type.
You can even register custom converters.
For example, let's say you are sending a Message with a String payload to the 'numberChannel' we configured above.
[source,java]
----
MessageChannel inChannel = context.getBean("numberChannel", MessageChannel.class);
inChannel.send(new GenericMessage<String>("5"));
----
Typically this would be a perfectly legal operation, however since we are using Datatype Channel the result of such operation would generate an exception:
[source,java]
----
Exception in thread "main" org.springframework.integration.MessageDeliveryException:
Channel 'numberChannel'
expected one of the following datataypes [class java.lang.Number],
but received [class java.lang.String]
…
----
And rightfully so since we are requiring the payload type to be a Number while sending a String.
So we need something to convert String to a Number.
All we need to do is implement a Converter.
[source,java]
----
public static class StringToIntegerConverter implements Converter<String, Integer> {
public Integer convert(String source) {
return Integer.parseInt(source);
}
}
----
Then, register it as a Converter with the Integration Conversion Service:
[source,java]
----
<int:converter ref="strToInt"/>
<bean id="strToInt" class="org.springframework.integration.util.Demo.StringToIntegerConverter"/>
----
When the 'converter' element is parsed, it will create the "integrationConversionService" bean on-demand if one is not already defined.
With that Converter in place, the send operation would now be successful since the Datatype Channel will use that Converter to convert the String payload to an Integer.
NOTE: For more information regarding Payload Type Conversion, please read <<payload-type-conversion>>.
Beginning with _version 4.0_, the `integrationConversionService` is invoked by the `DefaultDatatypeChannelMessageConverter`, which looks up the conversion service in the application context.
To use a different conversion technique, you can specify the `message-converter` attribute on the channel.
This must be a reference to a `MessageConverter` implementation.
Only the `fromMessage` method is used, which provides the converter with access to the message headers (for example if the conversion might need information from the headers, such as `content-type`).
The method can return just the converted payload, or a full `Message` object.
If the latter, the converter must be careful to copy all the headers from the inbound message.
Alternatively, declare a `<bean/>` of type `MessageConverter` with an id `"datatypeChannelMessageConverter"` and that converter will be used by all channels with a `datatype`.
[[channel-configuration-queuechannel]]
===== QueueChannel Configuration
To create a `QueueChannel`, use the <queue/> sub-element.
You may specify the channel's capacity:
[source,xml]
----
<int:channel id="queueChannel">
<queue capacity="25"/>
</int:channel>
----
NOTE: If you do not provide a value for the 'capacity' attribute on this <queue/> sub-element, the resulting queue will be unbounded.
To avoid issues such as OutOfMemoryErrors, it is highly recommended to set an explicit value for a bounded queue.
_Persistent QueueChannel Configuration_
Since a `QueueChannel` provides the capability to buffer Messages, but does so in-memory only by default, it also introduces a possibility that Messages could be lost in the event of a system failure.
To mitigate this risk, a `QueueChannel` may be backed by a persistent implementation of the `MessageGroupStore` strategy interface.
For more details on `MessageGroupStore` and `MessageStore` see <<message-store>>.
When a `QueueChannel` receives a Message, it will add it to the Message Store, and when a Message is polled from a `QueueChannel`, it is removed from the Message Store.
By default, a `QueueChannel` stores its Messages in an in-memory Queue and can therefore lead to the lost message scenario mentioned above.
However Spring Integration provides persistent stores, such as the `JdbcMessageStore`.
You can configure a Message Store for any `QueueChannel` by adding the `message-store` attribute as shown in the next example.
[source,xml]
----
<int:channel id="dbBackedChannel">
<int:queue message-store="channelStore"/>
</int:channel>
<bean id="channelStore" class="o.s.i.jdbc.store.JdbcChannelMessageStore">
<property name="dataSource" ref="dataSource"/>
<property name="channelMessageStoreQueryProvider" ref="queryProvider"/>
</bean>
----
The Spring Integration JDBC module also provides schema DDL for a number of popular databases.
These schemas are located in the _org.springframework.integration.jdbc.store.channel_ package of that module (spring-integration-jdbc).
IMPORTANT: One important feature is that with any transactional persistent store (e.g., JdbcChannelMessageStore), as long as the poller has a transaction configured, a Message removed from the store will only be permanently removed if the transaction completes successfully, otherwise the transaction will roll back and the Message will not be lost.
Many other implementations of the Message Store will be available as the growing number of Spring projects related to "NoSQL" data stores provide the underlying support.
Of course, you can always provide your own implementation of the MessageGroupStore interface if you cannot find one that meets your particular needs.
Since _version 4.0_, it is recommended that `QueueChannel` s are configured to use a `ChannelMessageStore` if possible.
These are generally optimized for this use, when compared with a general message store.
If the `ChannelMessageStore` is a `ChannelPriorityMessageStore` the messages will be received in FIFO within priority order.
The notion of priority is determined by the message store implementation.
Another option to customize the QueueChannel environment is provided by the `ref` attribute of the `<int:queue>` sub-element.
This attribute implies the reference to any `java.util.Queue` implementation.
An implementation is provided by the https://github.com/reactor/reactor[Project Reactor] and its `reactor.queue.PersistentQueue` implementation for the https://github.com/OpenHFT/Chronicle-Queue[IndexedChronicle]:
[source,java]
----
@Bean
public QueueChannel reactorQueue() {
return new QueueChannel(new PersistentQueueSpec<Message<?>>()
.codec(new JavaSerializationCodec<Message<?>>())
.basePath(System.getProperty("java.io.tmpdir") + "/reactor-queue")
.get());
}
----
[[channel-configuration-pubsubchannel]]
===== PublishSubscribeChannel Configuration
To create a `PublishSubscribeChannel`, use the <publish-subscribe-channel/> element.
When using this element, you can also specify the `task-executor` used for publishing Messages (if none is specified it simply publishes in the sender's thread):
[source,xml]
----
<int:publish-subscribe-channel id="pubsubChannel" task-executor="someExecutor"/>
----
If you are providing a _Resequencer_ or _Aggregator_ downstream from a `PublishSubscribeChannel`, then you can set the 'apply-sequence' property on the channel to `true`.
That will indicate that the channel should set the sequence-size and sequence-number Message headers as well as the correlation id prior to passing the Messages along.
For example, if there are 5 subscribers, the sequence-size would be set to 5, and the Messages would have sequence-number header values ranging from 1 to 5.
[source,xml]
----
<int:publish-subscribe-channel id="pubsubChannel" apply-sequence="true"/>
----
NOTE: The `apply-sequence` value is `false` by default so that a Publish Subscribe Channel can send the exact same Message instances to multiple outbound channels.
Since Spring Integration enforces immutability of the payload and header references, the channel creates new Message instances with the same payload reference but different header values when the flag is set to `true`.
[[channel-configuration-executorchannel]]
===== ExecutorChannel
To create an `ExecutorChannel`, add the <dispatcher> sub-element along with a `task-executor` attribute.
Its value can reference any `TaskExecutor` within the context.
For example, this enables configuration of a thread-pool for dispatching messages to subscribed handlers.
As mentioned above, this does break the "single-threaded" execution context between sender and receiver so that any active transaction context will not be shared by the invocation of the handler (i.e.
the handler may throw an Exception, but the send invocation has already returned successfully).
[source,xml]
----
<int:channel id="executorChannel">
<int:dispatcher task-executor="someExecutor"/>
</int:channel>
----
[NOTE]
=====
The `load-balancer` and `failover` options are also both available on the <dispatcher/> sub-element as described above in <<channel-configuration-directchannel>>.
The same defaults apply as well.
So, the channel will have a round-robin load-balancing strategy with failover enabled unless explicit configuration is provided for one or both of those attributes.
[source,xml]
----
<int:channel id="executorChannelWithoutFailover">
<int:dispatcher task-executor="someExecutor" failover="false"/>
</int:channel>
----
=====
[[channel-configuration-prioritychannel]]
===== PriorityChannel Configuration
To create a `PriorityChannel`, use the <priority-queue/> sub-element:
[source,xml]
----
<int:channel id="priorityChannel">
<int:priority-queue capacity="20"/>
</int:channel>
----
By default, the channel will consult the `priority` header of the message.
However, a custom `Comparator` reference may be provided instead.
Also, note that the `PriorityChannel` (like the other types) does support the `datatype` attribute.
As with the QueueChannel, it also supports a `capacity` attribute.
The following example demonstrates all of these:
[source,xml]
----
<int:channel id="priorityChannel" datatype="example.Widget">
<int:priority-queue comparator="widgetComparator"
capacity="10"/>
</int:channel>
----
Since _version 4.0_, the `priority-channel` child element supports the `message-store` option (`comparator` is not allowed in that case).
The message store must be a `PriorityCapableChannelMessageStore` and, in this case, the namespace parser will declare a `QueueChannel` instead of a `PriorityChannel`.
Implementations of the `PriorityCapableChannelMessageStore` are currently provided for `Redis`, `JDBC` and `MongoDB`.
See <<channel-configuration-queuechannel>>.
[[channel-configuration-rendezvouschannel]]
===== RendezvousChannel Configuration
A `RendezvousChannel` is created when the queue sub-element is a <rendezvous-queue>.
It does not provide any additional configuration options to those described above, and its queue does not accept any capacity value since it is a 0-capacity direct handoff queue.
[source,xml]
----
<int:channel id="rendezvousChannel"/>
<int:rendezvous-queue/>
</int:channel>
----
[[channel-configuration-threadlocalchannel]]
===== Scoped Channel Configuration
Any channel can be configured with a "scope" attribute.
[source,xml]
----
<int:channel id="threadLocalChannel" scope="thread"/>
----
[[channel-configuration-interceptors]]
===== Channel Interceptor Configuration
Message channels may also have interceptors as described in <<channel-interceptors>>.
The `<interceptors/>` sub-element can be added within a `<channel/>` (or the more specific element types).
Provide the `ref` attribute to reference any Spring-managed object that implements the `ChannelInterceptor` interface:
[source,xml]
----
<int:channel id="exampleChannel">
<int:interceptors>
<ref bean="trafficMonitoringInterceptor"/>
</int:interceptors>
</int:channel>
----
In general, it is a good idea to define the interceptor implementations in a separate location since they usually provide common behavior that can be reused across multiple channels.
[[global-channel-configuration-interceptors]]
===== Global Channel Interceptor Configuration
Channel Interceptors provide a clean and concise way of applying cross-cutting behavior per individual channel.
If the same behavior should be applied on multiple channels, configuring the same set of interceptors for each channel _would not be_ the most efficient way.
To avoid repeated configuration while also enabling interceptors to apply to multiple channels, Spring Integration provides _Global Interceptors_.
Look at the example below:
[source,xml]
----
<int:channel-interceptor pattern="input*, bar*, foo" order="3">
<bean class="foo.barSampleInterceptor"/>
</int:channel-interceptor>
----
or
[source,xml]
----
<int:channel-interceptor ref="myInterceptor" pattern="input*, bar*, foo" order="3"/>
<bean id="myInterceptor" class="foo.barSampleInterceptor"/>
----
Each <channel-interceptor/> element allows you to define a global interceptor which will be applied on all channels that match any patterns defined via the `pattern` attribute.
In the above case the global interceptor will be applied on the 'foo' channel and all other channels that begin with 'bar' or 'input'.
The _order_ attribute allows you to manage where this interceptor will be injected if there are multiple interceptors on a given channel.
For example, channel 'inputChannel' could have individual interceptors configured locally (see below):
[source,xml]
----
<int:channel id="inputChannel"> 
<int:interceptors>
<int:wire-tap channel="logger"/> 
</int:interceptors>
</int:channel>
----
A reasonable question is how will a global interceptor be injected in relation to other interceptors configured locally or through other global interceptor definitions? The current implementation provides a very simple mechanism for defining the order of interceptor execution.
A positive number in the `order` attribute will ensure interceptor injection after any existing interceptors and a negative number will ensure that the interceptor is injected before existing interceptors.
This means that in the above example, the global interceptor will be injected _AFTER_ (since its order is greater than 0) the 'wire-tap' interceptor configured locally.
If there were another global interceptor with a matching `pattern`, its order would be determined by comparing the values of the `order` attribute.
To inject a global interceptor _BEFORE_ the existing interceptors, use a negative value for the `order` attribute.
NOTE: Note that both the `order` and `pattern` attributes are optional.
The default value for `order` will be 0 and for `pattern`, the default is '*' (to match all channels).
[[channel-wiretap]]
===== Wire Tap
As mentioned above, Spring Integration provides a simple _Wire Tap_ interceptor out of the box.
You can configure a _Wire Tap_ on any channel within an <interceptors/> element.
This is especially useful for debugging, and can be used in conjunction with Spring Integration's logging Channel Adapter as follows:
[source,xml]
----
<int:channel id="in">
<int:interceptors>
<int:wire-tap channel="logger"/>
</int:interceptors>
</int:channel>
<int:logging-channel-adapter id="logger" level="DEBUG"/>
----
TIP: The 'logging-channel-adapter' also accepts an 'expression' attribute so that you can evaluate a SpEL expression against 'payload' and/or 'headers' variables.
Alternatively, to simply log the full Message toString() result, provide a value of "true" for the 'log-full-message' attribute.
That is `false` by default so that only the payload is logged.
Setting that to `true` enables logging of all headers in addition to the payload.
The 'expression' option does provide the most flexibility, however (e.g.
expression="payload.user.name").
*A little more on Wire Tap*
One of the common misconceptions about the wire tap and other similar components (<<message-publishing-config>>) is that they are automatically asynchronous in nature.
Wire-tap as a component is not invoked asynchronously be default.
Instead, Spring Integration focuses on a single unified approach to configuring asynchronous behavior: the Message Channel.
What makes certain parts of the message flow _sync_ or _async_ is the type of _Message Channel_ that has been configured within that flow.
That is one of the primary benefits of the Message Channel abstraction.
From the inception of the framework, we have always emphasized the need and the value of the _Message Channel_ as a first-class citizen of the framework.
It is not just an internal, implicit realization of the EIP pattern, it is fully exposed as a configurable component to the end user.
So, the Wire-tap component is ONLY responsible for performing the following 3 tasks:
* intercept a message flow by tapping into a channel (e.g., channelA)
* grab each message
* send the message to another channel (e.g., channelB)
It is essentially a variation of the Bridge, but it is encapsulated within a channel definition (and hence easier to enable and disable without disrupting a flow).
Also, unlike the bridge, it basically forks another message flow.
Is that flow _synchronous_ or _asynchronous_? The answer simply depends on the type of _Message Channel_ that 'channelB' is.
And, now you know that we have: _Direct Channel_, _Pollable Channel_, and _Executor Channel_ as options.
The last two do break the thread boundary making communication via such channels_asynchronous_ simply because the dispatching of the message from that channel to its subscribed handlers happens on a different thread than the one used to send the message to that channel.
That is what is going to make your wire-tap flow _sync_ or _async_.
It is consistent with other components within the framework (e.g., Message Publisher) and actually brings a level of consistency and simplicity by sparing you from worrying in advance (other than writing thread safe code) whether a particular piece of code should be implemented as _sync_ or _async_.
The actual wiring of two pieces of code (component A and component B) via _Message Channel_ is what makes their collaboration _sync_ or _async_.
You may even want to change from _sync_ to _async_ in the future and _Message Channel_ is what's going to allow you to do it swiftly without ever touching the code.
One final point regarding the Wire Tap is that, despite the rationale provided above for not being async be default, one should keep in mind it is usually desirable to hand off the Message as soon as possible.
Therefore, it would be quite common to use an asynchronous channel option as the wire-tap's outbound channel.
Nonetheless, another reason that we do not enforce asynchronous behavior by default is that you might not want to break a transactional boundary.
Perhaps you are using the Wire Tap for auditing purposes, and you DO want the audit Messages to be sent within the original transaction.
As an example, you might connect the wire-tap to a JMS outbound-channel-adapter.
That way, you get the best of both worlds: 1) the sending of a JMS Message can occur within the transaction while 2) it is still a "fire-and-forget" action thereby preventing any noticeable delay in the main message flow.
IMPORTANT: Starting with _version 4.0_, it is important to avoid circular references when an interceptor (such as `WireTap`) references a channel itself.
You need to exclude such channels from those being intercepted by the current interceptor.
This can be done with appropriate `patterns` or programmatically.
If you have a custom `ChannelInterceptor` that references a `channel`, consider implementing `VetoCapableInterceptor`.
That way, the framework will ask the interceptor if it's OK to intercept each channel that is a candidate based on the pattern.
You can also add runtime protection in the interceptor methods that ensures that the channel is not one that is referenced by the interceptor.
The `WireTap` uses both of these techniques.
[[conditional-wiretap]]
===== Conditional Wire Taps
Wire taps can be made conditional, using the `selector` or `selector-expression` attributes.
The `selector` references a `MessageSelector` bean, which can determine at runtime whether the message should go to the tap channel.
Similarly, the` selector-expression` is a boolean SpEL expression that performs the same purpose - if the expression evaluates to true, the message will be sent to the tap channel.
[[channel-global-wiretap]]
===== Global Wire Tap Configuration
It is possible to configure a global wire tap as a special case of the <<global-channel-configuration-interceptors>>.
Simply configure a top level `wire-tap` element.
Now, in addition to the normal `wire-tap` namespace support, the `pattern` and `order` attributes are supported and work in exactly the same way as with the `channel-interceptor`
[source,xml]
----
<int:wire-tap pattern="input*, bar*, foo" order="3" channel="wiretapChannel"/>
----
TIP: A global wire tap provides a convenient way to configure a single channel wire tap externally without modifying the existing channel configuration.
Simply set the `pattern` attribute to the target channel name.
For example, This technique may be used to configure a test case to verify messages on a channel.
[[channel-special-channels]]
==== Special Channels
If namespace support is enabled, there are two special channels defined within the application context by default: `errorChannel` and `nullChannel`.
The 'nullChannel' acts like `/dev/null`, simply logging any Message sent to it at DEBUG level and returning immediately.
Any time you face channel resolution errors for a reply that you don't care about, you can set the affected component's `output-channel` attribute to 'nullChannel' (the name 'nullChannel' is reserved within the application context).
The 'errorChannel' is used internally for sending error messages and may be overridden with a custom configuration.
This is discussed in greater detail in <<namespace-errorhandler>>.

214
src/reference/asciidoc/claim-check.adoc Normal file
View File

@@ -0,0 +1,214 @@
[[claim-check]]
=== Claim Check
[[claim-check-introduction]]
==== Introduction
In the earlier sections we've covered several Content Enricher type components that help you deal with situations where a message is missing a piece of data.
We also discussed Content Filtering which lets you remove data items from a message.
However there are times when we want to hide data temporarily.
For example, in a distributed system we may receive a Message with a very large payload.
Some intermittent message processing steps may not need access to this payload and some may only need to access certain headers, so carrying the large Message payload through each processing step may cause performance degradation, may produce a security risk, and may make debugging more difficult.
The http://www.eaipatterns.com/StoreInLibrary.html[Claim Check] pattern describes a mechanism that allows you to store data in a well known place while only maintaining a pointer (Claim Check) to where that data is located.
You can pass that pointer around as a payload of a new Message thereby allowing any component within the message flow to get the actual data as soon as it needs it.
This approach is very similar to the Certified Mail process where you'll get a Claim Check in your mailbox and would have to go to the Post Office to claim your actual package.
Of course it's also the same idea as baggage-claim on a flight or in a hotel.
Spring Integration provides two types of Claim Check transformers:
* _Incoming Claim Check Transformer_
* _Outgoing Claim Check Transformer_
Convenient namespace-based mechanisms are available to configure them.
[[claim-check-in]]
==== Incoming Claim Check Transformer
An _Incoming Claim Check Transformer_ will transform an incoming Message by storing it in the Message Store identified by its `message-store` attribute.
[source,xml]
----
<int:claim-check-in id="checkin"
input-channel="checkinChannel"
message-store="testMessageStore"
output-channel="output"/>
----
In the above configuration the Message that is received on the `input-channel` will be persisted to the Message Store identified with the `message-store` attribute and indexed with generated ID.
That ID is the Claim Check for that Message.
The Claim Check will also become the payload of the new (transformed) Message that will be sent to the `output-channel`.
Now, lets assume that at some point you do need access to the actual Message.
You can of course access the Message Store manually and get the contents of the Message, or you can use the same approach as before except now you will be transforming the Claim Check to the actual Message by using an _Outgoing Claim Check Transformer_.
Here is an overview of all available parameters of an Incoming Claim Check Transformer:
[source,xml]
----
<int:claim-check-in auto-startup="true" <1>
id="" <2>
input-channel="" <3>
message-store="messageStore" <4>
order="" <5>
output-channel="" <6>
send-timeout=""> <7>
<int:poller></int:poller> <8>
</int:claim-check-in>
----
<1> Lifecycle attribute signaling if this component should be started during Application Context startup.
Defaults to true.
Attribute is not available inside a `Chain` element.
_Optional_.
<2> Id identifying the underlying bean definition (`MessageTransformingHandler`).
Attribute is not available inside a `Chain` element.
_Optional_.
<3> The receiving Message channel of this endpoint.
Attribute is not available inside a `Chain` element.
_Optional_.
<4> Reference to the MessageStore to be used by this Claim Check transformer.
If not specified, the default reference will be to a bean named _messageStore_.
_Optional_.
<5> Specifies the order for invocation when this endpoint is connected as a subscriber to a channel.
This is particularly relevant when that channel is using a _failover_ dispatching strategy.
It has no effect when this endpoint itself is a Polling Consumer for a channel with a queue.
Attribute is not available inside a `Chain` element.
_Optional_.
<6> Identifies the Message channel where Message will be sent after its being processed by this endpoint.
Attribute is not available inside a `Chain` element.
_Optional_.
<7> Specify the maximum amount of time in milliseconds to wait when sending a reply Message to the output channel.
By default the send will block for one second.
Attribute is not available inside a `Chain` element.
_Optional_.
<8> Defines a poller.
Element is not available inside a `Chain` element.
_Optional_.
[[claim-check-out]]
==== Outgoing Claim Check Transformer
An _Outgoing Claim Check Transformer_ allows you to transform a Message with a Claim Check payload into a Message with the original content as its payload.
[source,xml]
----
<int:claim-check-out id="checkout"
input-channel="checkoutChannel"
message-store="testMessageStore"
output-channel="output"/>
----
In the above configuration, the Message that is received on the `input-channel` should have a Claim Check as its payload and the _Outgoing Claim Check Transformer_ will transform it into a Message with the original payload by simply querying the Message store for a Message identified by the provided Claim Check.
It then sends the newly checked-out Message to the `output-channel`.
Here is an overview of all available parameters of an Outgoing Claim Check Transformer:
[source,xml]
----
<int:claim-check-out auto-startup="true" <1>
id="" <2>
input-channel="" <3>
message-store="messageStore" <4>
order="" <5>
output-channel="" <6>
remove-message="false" <7>
send-timeout=""> <8>
<int:poller></int:poller> <9>
</int:claim-check-out>
----
<1> Lifecycle attribute signaling if this component should be started during Application Context startup.
Defaults to true.
Attribute is not available inside a `Chain` element.
_Optional_.
<2> Id identifying the underlying bean definition (`MessageTransformingHandler`).
Attribute is not available inside a `Chain` element.
_Optional_.
<3> The receiving Message channel of this endpoint.
Attribute is not available inside a `Chain` element.
_Optional_.
<4> Reference to the MessageStore to be used by this Claim Check transformer.
If not specified, the default reference will be to a bean named _messageStore_.
_Optional_.
<5> Specifies the order for invocation when this endpoint is connected as a subscriber to a channel.
This is particularly relevant when that channel is using a _failover_ dispatching strategy.
It has no effect when this endpoint itself is a Polling Consumer for a channel with a queue.
Attribute is not available inside a `Chain` element.
_Optional_.
<6> Identifies the Message channel where Message will be sent after its being processed by this endpoint.
Attribute is not available inside a `Chain` element.
_Optional_.
<7> If set to `true` the Message will be removed from the MessageStore by this transformer.
Useful when Message can be "claimed" only once.
Defaults to `false`.
_Optional_.
<8> Specify the maximum amount of time in milliseconds to wait when sending a reply Message to the output channel.
By default the send will block for one second.
Attribute is not available inside a `Chain` element.
_Optional_.
<9> Defines a poller.
Element is not available inside a `Chain` element.
_Optional_.
_Claim Once_
There are scenarios when a particular message must be claimed only once.
As an analogy, consider the airplane luggage check-in/out process.
Checking-in your luggage on departure and and then claiming it on arrival is a classic example of such a scenario.
Once the luggage has been claimed, it can not be claimed again without first checking it back in.
To accommodate such cases, we introduced a `remove-message` boolean attribute on the `claim-check-out` transformer.
This attribute is set to `false` by default.
However, if set to `true`, the claimed Message will be removed from the MessageStore, so that it can no longer be claimed again.
This is also something to consider in terms of storage space, especially in the case of the in-memory Map-based `SimpleMessageStore`, where failing to remove the Messages could ultimately lead to an `OutOfMemoryException`.
Therefore, if you don't expect multiple claims to be made, it's recommended that you set the `remove-message` attribute's value to `true`.
[source,xml]
----
<int:claim-check-out id="checkout"
input-channel="checkoutChannel"
message-store="testMessageStore"
output-channel="output"
remove-message="true"/>
----
==== A word on Message Store
Although we rarely care about the details of the claim checks as long as they work, it is still worth knowing that the current implementation of the actual Claim Check (the pointer) in Spring Integration is a UUID to ensure uniqueness.
`org.springframework.integration.store.MessageStore` is a strategy interface for storing and retrieving messages.
Spring Integration provides two convenient implementations of it.
`SimpleMessageStore`: an in-memory, Map-based implementation (the default, good for testing) and `JdbcMessageStore`: an implementation that uses a relational database via JDBC.

745
src/reference/asciidoc/configuration.adoc Normal file
View File

@@ -0,0 +1,745 @@
[[configuration]]
== Configuration
[[configuration-introduction]]
=== Introduction
Spring Integration offers a number of configuration options.
Which option you choose depends upon your particular needs and at what level you prefer to work.
As with the Spring framework in general, it is also possible to mix and match the various techniques according to the particular problem at hand.
For example, you may choose the XSD-based namespace for the majority of configuration combined with a handful of objects that are configured with annotations.
As much as possible, the two provide consistent naming.
XML elements defined by the XSD schema will match the names of annotations, and the attributes of those XML elements will match the names of annotation properties.
Direct usage of the API is of course always an option, but we expect that most users will choose one of the higher-level options, or a combination of the namespace-based and annotation-driven configuration.
[[configuration-namespace]]
=== Namespace Support
Spring Integration components can be configured with XML elements that map directly to the terminology and concepts of enterprise integration.
In many cases, the element names match those of thehttp://www.eaipatterns.com[Enterprise Integration Patterns].
To enable Spring Integration's core namespace support within your Spring configuration files, add the following namespace reference and schema mapping in your top-level 'beans' element:
// We lose coloring here, but we want to bold the lines we're talking about...
[subs="+quotes"]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
*xmlns:int="http://www.springframework.org/schema/integration"*
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
*http://www.springframework.org/schema/integration*
*http://www.springframework.org/schema/integration/spring-integration.xsd*">
----
You can choose any name after "xmlns:"; _int_ is used here for clarity, but you might prefer a shorter abbreviation.
Of course if you are using an XML-editor or IDE support, then the availability of auto-completion may convince you to keep the longer name for clarity.
Alternatively, you can create configuration files that use the Spring Integration schema as the primary namespace:
// We lose coloring here, but we want to bold the lines we're talking about...
[subs=+quotes]
----
*<beans:beans xmlns="http://www.springframework.org/schema/integration"*
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:beans="http://www.springframework.org/schema/beans"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
*http://www.springframework.org/schema/integration*
*http://www.springframework.org/schema/integration/spring-integration.xsd*">
----
When using this alternative, no prefix is necessary for the Spring Integration elements.
On the other hand, if you want to define a generic Spring "bean" within the same configuration file, then a prefix would be required for the bean element (`<beans:bean .../>`).
Since it is generally a good idea to modularize the configuration files themselves based on responsibility and/or architectural layer, you may find it appropriate to use the latter approach in the integration-focused configuration files, since generic beans are seldom necessary within those same files.
For purposes of this documentation, we will assume the "integration" namespace is primary.
Many other namespaces are provided within the Spring Integration distribution.
In fact, each adapter type (JMS, File, etc.) that provides namespace support defines its elements within a separate schema.
In order to use these elements, simply add the necessary namespaces with an "xmlns" entry and the corresponding "schemaLocation" mapping.
For example, the following root element shows several of these namespace declarations:
[source,xml]
----
<?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:int="http://www.springframework.org/schema/integration"
xmlns:int-file="http://www.springframework.org/schema/integration/file"
xmlns:int-jms="http://www.springframework.org/schema/integration/jms"
xmlns:int-mail="http://www.springframework.org/schema/integration/mail"
xmlns:int-rmi="http://www.springframework.org/schema/integration/rmi"
xmlns:int-ws="http://www.springframework.org/schema/integration/ws"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration.xsd
http://www.springframework.org/schema/integration/file
http://www.springframework.org/schema/integration/file/spring-integration-file.xsd
http://www.springframework.org/schema/integration/jms
http://www.springframework.org/schema/integration/jms/spring-integration-jms.xsd
http://www.springframework.org/schema/integration/mail
http://www.springframework.org/schema/integration/mail/spring-integration-mail.xsd
http://www.springframework.org/schema/integration/rmi
http://www.springframework.org/schema/integration/rmi/spring-integration-rmi.xsd
http://www.springframework.org/schema/integration/ws
http://www.springframework.org/schema/integration/ws/spring-integration-ws.xsd">
...
</beans>
----
The reference manual provides specific examples of the various elements in their corresponding chapters.
Here, the main thing to recognize is the consistency of the naming for each namespace URI and schema location.
[[namespace-taskscheduler]]
=== Configuring the Task Scheduler
In Spring Integration, the ApplicationContext plays the central role of a Message Bus, and there are only a couple configuration options to consider.
First, you may want to control the central TaskScheduler instance.
You can do so by providing a single bean with the name "taskScheduler".
This is also defined as a constant:
[source,java]
----
IntegrationContextUtils.TASK_SCHEDULER_BEAN_NAME
----
By default Spring Integration relies on an instance of ThreadPoolTaskScheduler as described in the http://static.springsource.org/spring/docs/3.1.x/spring-framework-reference/html/scheduling.html[Task Execution and Scheduling] section of the Spring Framework reference manual.
That default TaskScheduler will startup automatically with a pool of 10 threads.
If you provide your own TaskScheduler instance instead, you can set the 'autoStartup' property to _false_, and/or you can provide your own pool size value.
When Polling Consumers provide an explicit task-executor reference in their configuration, the invocation of the handler methods will happen within that executor's thread pool and not the main scheduler pool.
However, when no task-executor is provided for an endpoint's poller, it will be invoked by one of the main scheduler's threads.
NOTE: An endpoint is a _Polling Consumer_ if its input channel is one of the queue-based (i.e.
pollable) channels.
On the other hand, _Event Driven Consumers_ are those whose input channels have dispatchers instead of queues (i.e.
they are subscribable).
Such endpoints have no poller configuration since their handlers will be invoked directly.
[IMPORTANT]
=====
When running in a JEE container, you may need to use Spring's `TimerManagerTaskScheduler` as described http://static.springsource.org/spring/docs/3.1.x/spring-framework-reference/html/scheduling.html#scheduling-task-scheduler-implementations[here], instead of the default _taskScheduler_.
To do that, simply define a bean with the appropriate JNDI name for your environment, for example:
[source,xml]
----
<bean id="taskScheduler" class="o.s.scheduling.commonj.TimerManagerTaskScheduler">
<property name="timerManagerName" value="tm/MyTimerManager" />
<property name="resourceRef" value="true" />
</bean>
----
=====
The next section will describe what happens if Exceptions occur within the asynchronous invocations.
[[namespace-errorhandler]]
=== Error Handling
As described in the overview at the very beginning of this manual, one of the main motivations behind a Message-oriented framework like Spring Integration is to promote loose-coupling between components.
The Message Channel plays an important role in that producers and consumers do not have to know about each other.
However, the advantages also have some drawbacks.
Some things become more complicated in a very loosely coupled environment, and one example is error handling.
When sending a Message to a channel, the component that ultimately handles that Message may or may not be operating within the same thread as the sender.
If using a simple default DirectChannel (with the<channel> element that has no <queue> sub-element and no 'task-executor' attribute), the Message-handling will occur in the same thread as the Message-sending.
In that case, if an Exception is thrown, it can be caught by the sender (or it may propagate past the sender if it is an uncaught RuntimeException).
So far, everything is fine.
This is the same behavior as an Exception-throwing operation in a normal call stack.
However, when adding the asynchronous aspect, things become much more complicated.
For instance, if the 'channel' element _does_ provide a 'queue' sub-element, then the component that handles the Message _will_ be operating in a different thread than the sender.
The sender may have dropped the Message into the channel and moved on to other things.
There is no way for the Exception to be thrown directly back to that sender using standard Exception throwing techniques.
Instead, to handle errors for asynchronous processes requires an asynchronous error-handling mechanism as well.
Spring Integration supports error handling for its components by publishing errors to a Message Channel.
Specifically, the Exception will become the payload of a Spring Integration Message.
That Message will then be sent to a Message Channel that is resolved in a way that is similar to the 'replyChannel' resolution.
First, if the request Message being handled at the time the Exception occurred contains an 'errorChannel' header (the header name is defined in the constant: IntegrationMessageHeaderAccessor.ERROR_CHANNEL), the ErrorMessage will be sent to that channel.
Otherwise, the error handler will send to a "global" channel whose bean name is "errorChannel" (this is also defined as a constant: IntegrationContextUtils.ERROR_CHANNEL_BEAN_NAME).
Whenever relying on Spring Integration's XML namespace support, a default "errorChannel" bean will be created behind the scenes.
However, you can just as easily define your own if you want to control the settings.
[source,xml]
----
<int:channel id="errorChannel">
<int:queue capacity="500"/>
</int:channel>
----
NOTE: The default "errorChannel" is a PublishSubscribeChannel.
The most important thing to understand here is that the messaging-based error handling will only apply to Exceptions that are thrown by a Spring Integration task that is executing within a TaskExecutor.
This does _not_ apply to Exceptions thrown by a handler that is operating within the same thread as the sender (e.g.
through a DirectChannel as described above).
NOTE: When Exceptions occur in a scheduled poller task's execution, those exceptions will be wrapped in `ErrorMessages` and sent to the 'errorChannel' as well.
To enable global error handling, simply register a handler on that channel.
For example, you can configure Spring Integration's `ErrorMessageExceptionTypeRouter` as the handler of an endpoint that is subscribed to the 'errorChannel'.
That router can then spread the error messages across multiple channels based on `Exception` type.
[[annotations]]
=== Annotation Support
In addition to the XML namespace support for configuring Message Endpoints, it is also possible to use annotations.
First, Spring Integration provides the class-level `@MessageEndpoint` as a _stereotype_ annotation, meaning that it is itself annotated with Spring's `@Component` annotation and is therefore recognized automatically as a bean definition when using Spring component-scanning.
Even more important are the various method-level annotations that indicate the annotated method is capable of handling a message.
The following example demonstrates both:
[source,java]
----
@MessageEndpoint
public class FooService {
@ServiceActivator
public void processMessage(Message message) {
...
}
}
----
Exactly what it means for the method to "handle" the Message depends on the particular annotation.
Annotations available in Spring Integration include:
* @Aggregator
* @Filter
* @Router
* @ServiceActivator
* @Splitter
* @Transformer
* @InboundChannelAdapter
* @BridgeFrom
* @BridgeTo
The behavior of each is described in its own chapter or section within this reference.
NOTE: If you are using XML configuration in combination with annotations, the `@MessageEndpoint` annotation is not required.
If you want to configure a POJO reference from the "ref" attribute of a<service-activator/> element, it is sufficient to provide the method-level annotations.
In that case, the annotation prevents ambiguity even when no "method" attribute exists on the <service-activator/> element.
In most cases, the annotated handler method should not require the `Message` type as its parameter.
Instead, the method parameter type can match the message's payload type.
[source,java]
----
public class FooService {
@ServiceActivator
public void bar(Foo foo) {
...
}
}
----
When the method parameter should be mapped from a value in the `MessageHeaders`, another option is to use the parameter-level `@Header` annotation.
In general, methods annotated with the Spring Integration annotations can either accept the `Message` itself, the message payload, or a header value (with @Header) as the parameter.
In fact, the method can accept a combination, such as:
[source,java]
----
public class FooService {
@ServiceActivator
public void bar(String payload, @Header("x") int valueX, @Header("y") int valueY) {
...
}
}
----
There is also a @Headers annotation that provides all of the Message headers as a Map:
[source,java]
----
public class FooService {
@ServiceActivator
public void bar(String payload, @Headers Map<String, Object> headerMap) {
...
}
}
----
NOTE: The value of the annotation can also be a SpEL expression (e.g., 'payload.getCustomerId()') which is quite useful when the name of the header has to be dynamically computed.
It also provides an optional 'required' property which specifies whether the attribute value must be available within the header.
The default value for 'required' is `true`.
For several of these annotations, when a Message-handling method returns a non-null value, the endpoint will attempt to send a reply.
This is consistent across both configuration options (namespace and annotations) in that such an endpoint's output channel will be used if available, and the REPLY_CHANNEL message header value will be used as a fallback.
TIP: The combination of output channels on endpoints and the reply channel message header enables a pipeline approach where multiple components have an output channel, and the final component simply allows the reply message to be forwarded to the reply channel as specified in the original request message.
In other words, the final component depends on the information provided by the original sender and can dynamically support any number of clients as a result.
This is an example of http://eaipatterns.com/ReturnAddress.html[Return Address].
In addition to the examples shown here, these annotations also support inputChannel and outputChannel properties.
[source,java]
----
public class FooService {
@ServiceActivator(inputChannel="input", outputChannel="output")
public void bar(String payload, @Headers Map<String, Object> headerMap) {
...
}
}
----
The processing of these annotations creates the same beans (`AbstractEndpoint` s and `MessageHandler` s (or `MessageSource` s for the inbound channel adapter - see below) as with similar xml components.
The bean names are generated with this pattern: `[componentName].[methodName].[decapitalizedAnnotationClassShortName]` for the `AbstractEndpoint` and the same name with an additional `.handler` (`.source`) suffix for the `MessageHandler` (`MessageSource`) bean.
The `MessageHandler` s (`MessageSource` s) are also eligible to be tracked by <<message-history>>.
Starting with _version 4.0_, all Messaging Annotations provide `SmartLifecycle` options - `autoStartup` and `phase` to allow endpoint lifecycle control on application context initialization.
They default to `true` and `0` respectively.
To change the state of an endpoint (e.g` start()/stop()`) obtain a reference to the endpoint bean using the `BeanFactory` (or autowiring) and invoke the method(s), or send a _command message_ to the `Control Bus` (<<control-bus>>).
For these purposes you should use the `beanName` mentioned above.
*@Poller*
Before _Spring Integration 4.0_, the above Messaging Annotations required that the `inputChannel` was a reference to a `SubscribableChannel`.
For `PollableChannel` s there was need to use a `<int:bridge/>`, to configure a `<int:poller/>` to make the composite endpoint - a `PollingConsumer`.
Starting with _version 4.0_, the `@Poller` annotation has been introduced to allow the configuration of `poller` attributes directly on the above Messaging Annotations:
[source,java]
----
public class AnnotationService {
@Transformer(inputChannel = "input", outputChannel = "output",
poller = @Poller(maxMessagesPerPoll = "${poller.maxMessagesPerPoll}", fixedDelay = "${poller.fixedDelay}"))
public String handle(String payload) {
...
}
}
----
This annotation provides only simple `PollerMetadata` options.
The `@Poller`'s attributes `maxMessagesPerPoll`, `fixedDelay`, `fixedRate` and `cron` can be configured with _property-placeholder_s.
If it is necessary to provide more polling options (e.g.
transaction, advice-chain, error-handler), the`PollerMetadata` should be configured as a generic bean with its bean name used for `@Poller`'s `value` attribute.
In this case, no other attributes are allowed (they would be specified on the `PollerMetadata` bean).
Note, if `inputChannel` is `PollableChannel` and no `@Poller` is configured, the default `PollerMetadata` will be used, if it is present in the application context.
To declare the default poller using `@Configuration`, use:
[source,java]
----
@Bean(name = PollerMetadata.DEFAULT_POLLER)
public PollerMetadata defaultPoller() {
PollerMetadata pollerMetadata = new PollerMetadata();
pollerMetadata.setTrigger(new PeriodicTrigger(10));
return pollerMetadata;
}
----
With this endpoint using the default poller:
[source,java]
----
public class AnnotationService {
@Transformer(inputChannel = "aPollableChannel", outputChannel = "output")
public String handle(String payload) {
...
}
}
----
To use a named poller, use:
[source,java]
----
@Bean
public PollerMetadata myPoller() {
PollerMetadata pollerMetadata = new PollerMetadata();
pollerMetadata.setTrigger(new PeriodicTrigger(1000));
return pollerMetadata;
}
----
With this endpoint using the default poller:
[source,java]
----
public class AnnotationService {
@Transformer(inputChannel = "aPollableChannel", outputChannel = "output"
poller = @Poller("myPoller")
public String handle(String payload) {
...
}
}
----
*@InboundChannelAdapter*
Starting with _version 4.0_, the `@InboundChannelAdapter` method annotation is available.
This produces a `SourcePollingChannelAdapter` integration component based on a `MethodInvokingMessageSource` for the annotated method.
This annotation is an analogue of `<int:inbound-channel-adapter>` XML component and has the same restrictions: the method cannot have parameters, and the return type must not be `void`.
It has two attributes: `value` - the required `MessageChannel` bean name and `poller` - an optional `@Poller` annotation, as described above.
If there is need to provide some `MessageHeaders`, use a `Message<?>` return type and build the `Message<?>` within the method using a `MessageBuilder` to configure its `MessageHeaders`.
[source,java]
----
@InboundChannelAdapter("counterChannel")
public Integer count() {
return this.counter.incrementAndGet();
}
@InboundChannelAdapter(value = "fooChannel", poller = @Poller(fixed-rate = "5000"))
public String foo() {
return "foo";
}
----
The first example requires that the default poller has been declared elsewhere in the application context.
[[meta-annotations]]
==== Messaging Meta-Annotations
Starting with _version 4.0_, all Messaging Annotations can be configured as meta-annotations and all user-defined Messaging Annotations can define the same attributes to override their default values.
In addition, meta-annotations can be configured hierarchically:
[source,java]
----
@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@ServiceActivator(inputChannel = "annInput", outputChannel = "annOutput")
public @interface MyServiceActivator {
String[] adviceChain = { "annAdvice" };
}
@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@MyServiceActivator
public @interface MyServiceActivator1 {
String inputChannel();
String outputChannel();
}
...
@MyServiceActivator1(inputChannel = "inputChannel", outputChannel = "outputChannel")
public Object service(Object payload) {
...
}
----
This allows users to set defaults for various attributes and enables isolation of framework Java dependencies to user annotations, avoiding their use in user classes.
If the framework finds a method with a user annotation that has a framework meta-annotation, it is treated as if the method was annotated directly with the framework annotation.
==== Annotations on @Beans
Starting with _version 4.0_, Messaging Annotations can be configured on `@Bean` method definitions in `@Configuration` classes, to produce Message Endpoints based on the beans, not methods.
It is useful when `@Bean` definitions are "out of the box" `MessageHandler` s (`AggregatingMessageHandler`, `DefaultMessageSplitter` etc.), `Transformer` s (`JsonToObjectTransformer`, `ClaimCheckOutTransformer` etc.), `MessageSource` s (`FileReadingMessageSource`, `RedisStoreMessageSource` etc.):
[source,java]
----
@Configuration
@EnableIntegration
public class MyFlowConfiguration {
@Bean
@InboundChannelAdapter(value = "inputChannel", poller = @Poller(fixedDelay = "1000"))
public MessageSource<String> consoleSource() {
return CharacterStreamReadingMessageSource.stdin();
}
@Bean
@Transformer(inputChannel = "inputChannel", outputChannel = "httpChannel")
public ObjectToMapTransformer toMapTransformer() {
return new ObjectToMapTransformer();
}
@Bean
@ServiceActivator(inputChannel = "httpChannel")
public MessageHandler httpHandler() {
HttpRequestExecutingMessageHandler handler = new HttpRequestExecutingMessageHandler("http://foo/service");
handler.setExpectedResponseType(String.class);
handler.setOutputChannelName("outputChannel");
return handler;
}
@Bean
@ServiceActivator(inputChannel = "outputChannel")
public LoggingHandler loggingHandler() {
return new LoggingHandler("info");
}
}
----
The meta-annotation rules work on `@Bean` methods as well (`@MyServiceActivator` above can be applied to a `@Bean` definition).
NOTE: When using these annotations on consumer `@Bean` definitions, if the bean definition returns an appropriate `MessageHandler` (depending on the annotation type), attributes such as `outputChannel, requiresReply` etc, must be set on the `@Bean` itself.
The only annotation attributes used are `adviceChain, autoStartup, inputChannel, phase, poller`, all other attributes are for the handler.
IMPORTANT: When using these annotations on `@Bean` definitions, the `inputChannel` must reference a declared bean; channels are not automatically declared in this case.
==== Creating a Bridge with Annotations
Starting with _version 4.0_, the Messaging Annotation and Java configuration provides `@BridgeFrom` and `@BridgeTo` `@Bean` method annotations to mark `MessageChannel` beans in `@Configuration` classes.
This is just for completeness, providing a convenient mechanism to declare a`BridgeHandler` and its Message Endpoint configuration:
[source,java]
----
@Bean
public PollableChannel bridgeFromInput() {
return new QueueChannel();
}
@Bean
@BridgeFrom(value = "bridgeFromInput", poller = @Poller(fixedDelay = "1000"))
public MessageChannel bridgeFromOutput() {
return new DirectChannel();
}
@Bean
public QueueChannel bridgeToOutput() {
return new QueueChannel();
}
@Bean
@BridgeTo("bridgeToOutput")
public MessageChannel bridgeToInput() {
return new DirectChannel();
}
----
These annotations can be used as meta-annotations as well.
==== Advising Annotated Endpoints
See <<advising-with-annotations>>.
[[message-mapping-rules]]
=== Message Mapping rules and conventions
Spring Integration implements a flexible facility to map Messages to Methods and their arguments without providing extra configuration by relying on some default rules as well as defining certain conventions.
[[sample-scenarios]]
==== Simple Scenarios
_Single un-annotated parameter (object or primitive) which is not a Map/Properties with non-void return type;_
[source,java]
----
public String foo(Object o);
----
Details:
Input parameter is Message Payload.
If parameter type is not compatible with Message Payload an attempt will be made to convert it using Conversion Service provided by Spring 3.0.
The return value will be incorporated as a Payload of the returned Message
_Single un-annotated parameter (object or primitive) which is not a Map/Properties with Message return type;_
[source,java]
----
public Message  foo(Object o);
----
Details:
Input parameter is Message Payload.
If parameter type is not compatible with Message Payload an attempt will be made to convert it using Conversion Service provided by Spring 3.0.
The return value is a newly constructed Message that will be sent to the next destination.
_Single parameter which is a Message or its subclass with arbitrary object/primitive return type; _
[source,java]
----
public int foo(Message  msg);
----
Details:
Input parameter is Message itself. The return value will become a payload of the Message that will be sent to the next destination.
_Single parameter which is a Message or its subclass with Message or its subclass as a return type;_
[source,java]
----
public Message foo(Message msg);
----
Details:
Input parameter is Message itself. The return value is a newly constructed Message that will be sent to the next destination.
_Single parameter which is of type Map or Properties with Message as a return type;_
[source,java]
----
public Message foo(Map m);
----
Details:
This one is a bit interesting.
Although at first it might seem like an easy mapping straight to Message Headers, the preference is always given to a Message Payload.
This means that if Message Payload is of type Map, this input argument will represent Message Payload.
However if Message Payload is not of type Map, then no conversion via Conversion Service will be attempted and the input argument will be mapped to Message Headers.
_Two parameters where one of them is arbitrary non-Map/Properties type object/primitive and another is Map/Properties type object (regardless of the return)_
[source,java]
----
public Message foo(Map h, <T> t);
----
Details:
This combination contains two input parameters where one of them is of type Map.
Naturally the non-Map parameters (regardless of the order) will be mapped to a Message Payload and the Map/Properties (regardless of the order) will be mapped to  Message Headers giving you a nice POJO way of interacting with Message structure.
_No parameters (regardless of the return)_
[source,java]
----
public String foo();
----
Details:
This Message Handler method will be invoked based on the Message sent to the input channel this handler is hooked up to, however no Message data will be mapped, thus making Message act as event/trigger to invoke such handlerThe output will be mapped according to the rules above
_No parameters, void return_
[source,java]
----
public void foo();
----
Details:
Same as above, but no output 
_Annotation based mappings_
Annotation based mapping is the safest and least ambiguous approach to map Messages to Methods.
There wil be many pointers to annotation based mapping throughout this manual, however here are couple of examples:
[source,java]
----
public String foo(@Payload String s, @Header("foo") String b) 
----
Very simple and explicit way of mapping Messages to method.
As you'll see later on, without an annotation this signature would result in an ambiguous condition.
However by explicitly mapping the first argument to a Message Payload and the second argument to a value of the 'foo' Message Header, we have avoided any ambiguity.
[source,java]
----
public String foo(@Payload String s, @RequestParam("foo") String b) 
----
Looks almost identical to the previous example, however @RequestMapping or any other non-Spring Integration mapping annotation is irrelevant and therefore will be ignored leaving the second parameter unmapped.
Although the second parameter could easily be mapped to a Payload, there can only be one Payload.
Therefore this method mapping is ambiguous.
[source,java]
----
public String foo(String s, @Header("foo") String b) 
----
The same as above.
The only difference is that the first argument will be mapped to the Message Payload implicitly.
[source,java]
----
public String foo(@Headers Map m, @Header("foo")Map f, @Header("bar") String bar)
----
Yet another signature that would definitely be treated as ambiguous without annotations because it has more than 2 arguments.
Furthermore, two of them are Maps.
However, with annotation-based mapping, the ambiguity is easily avoided.
In this example the first argument is mapped to all the Message Headers, while the second and third argument map to the values of Message Headers 'foo' and 'bar'.
The payload is not being mapped to any argument.
[[complex-scenarios]]
==== Complex Scenarios
_Multiple parameters:_
Multiple parameters could create a lot of ambiguity with regards to determining the appropriate mappings.
The general advice is to annotate your method parameters with @Payload and/or @Header/@Headers Below are some of the examples of ambiguous conditions which result in an Exception being raised.
[source,java]
----
public String foo(String s, int i)
----
- the two parameters are equal in weight, therefore there is no way to determine which one is a payload.
[source,java]
----
public String foo(String s, Map m, String b)
----
- almost the same as above.
Although the Map could be easily mapped to Message Headers, there is no way to determine what to do with the two Strings.
[source,java]
----
public String foo(Map m, Map f)
----
- although one might argue that one Map could be mapped to Message Payload and another one to Message Headers, it would be unreasonable to rely on the order (e.g., first is Payload, second Headers)
TIP: Basically any method signature with more than one method argument which is not (Map, <T>), and those parameters are not annotated, will result in an ambiguous condition thus triggering an Exception.
_Multiple methods:_
Message Handlers with multiple methods are mapped based on the same rules that are described above, however some scenarios might still look confusing.
_Multiple methods (same or different name) with legal (mappable) signatures:_
[source,java]
----
public class Foo {
public String foo(String str, Map m);
public String foo(Map m);
}
----
As you can see, the Message could be mapped to either method.
The first method would be invoked where Message Payload could be mapped to 'str'  and Message Headers could be mapped to 'm'.
The second method could easily also be a candidate where only Message Headers are mapped to 'm'.
To make meters worse both methods have the same name which at first might look very ambiguous considering the following configuration:
[source,xml]
----
<int:service-activator input-channel="input" output-channel="output" method="foo">
<bean class="org.bar.Foo"/>
</int:service-activator>
----
At this point it would be important to understand Spring Integration mapping Conventions where at the very core, mappings are based on Payload first and everything else next.
In other words the method whose argument could be mapped to a Payload will take precedence over all other methods.
On the other hand let's look at slightly different example:
[source,java]
----
public class Foo {
public String foo(String str, Map m);
public String foo(String str);
}
----
If you look at it you can probably see a truly ambiguous condition.
In this example since both methods have signatures that could be mapped to a Message Payload.
They also have the same name.
Such handler methods will trigger an Exception.
However if the method names were different you could influence the mapping with a 'method' attribute (see below):
[source,java]
----
public class Foo {
public String foo(String str, Map m);
public String bar(String str);
}
----
[source,xml]
----
<int:service-activator input-channel="input" output-channel="output" method="bar">
<bean class="org.bar.Foo"/>
</int:service-activator>
----
Now there is no ambiguity since the configuration explicitly maps to the 'bar' method which has no name conflicts.

386
src/reference/asciidoc/content-enrichment.adoc Normal file
View File

@@ -0,0 +1,386 @@
[[content-enricher]]
=== Content Enricher
[[content-enricher-introduction]]
==== Introduction
At times you may have a requirement to enhance a request with more information than was provided by the target system.
Thehttp://www.eaipatterns.com/DataEnricher.html[Content Enricher] pattern describes various scenarios as well as the component (Enricher), which allows you to address such requirements.
The Spring Integration `Core` module includes 2 enrichers:
* <<header-enricher,Header Enricher>>
* <<payload-enricher,Payload Enricher>>
Furthermore, several _Adapter specific Header Enrichers_ are included as well:
* <<xml-xpath-header-enricher,XPath Header Enricher (XML Module)>>
* <<mail-namespace,Mail Header Enricher (Mail Module)>>
* <<xmpp-message-outbound-channel-adapter,XMPP Header Enricher (XMPP Module)>>
Please go to the adapter specific sections of this reference manual to learn more about those adapters.
For more information regarding expressions support, please see <<spel>>.
[[header-enricher]]
==== Header Enricher
If you only need to add headers to a Message, and they are not dynamically determined by the Message content, then referencing a custom implementation of a Transformer may be overkill.
For that reason, Spring Integration provides support for the _Header Enricher_ pattern.
It is exposed via the `<header-enricher>` element.
[source,xml]
----
<int:header-enricher input-channel="in" output-channel="out">
<int:header name="foo" value="123"/>
<int:header name="bar" ref="someBean"/>
</int:header-enricher>
----
The _Header Enricher_ also provides helpful sub-elements to set well-known header names.
[source,xml]
----
<int:header-enricher input-channel="in" output-channel="out">
<int:error-channel ref="applicationErrorChannel"/>
<int:reply-channel ref="quoteReplyChannel"/>
<int:correlation-id value="123"/>
<int:priority value="HIGHEST"/>
<routing-slip value="channel1; routingSlipRoutingStrategy; request.headers[myRoutingSlipChannel]"/>
<int:header name="bar" ref="someBean"/>
</int:header-enricher>
----
In the above configuration you can clearly see that for well-known headers such as `errorChannel`, `correlationId`, `priority`, `replyChannel`, `routing-slip` etc., instead of using generic _<header>_ sub-elements where you would have to provide both header 'name' and 'value', you can use convenient sub-elements to set those values directly.
Starting with _version 4.1_ the _Header Enricher_ provides `routing-slip` sub-element.
See <<routing-slip>> for more information.
*POJO Support*
Often a header value cannot be defined statically and has to be determined dynamically based on some content in the Message.
That is why_Header Enricher_ allows you to also specify a bean reference using the `ref` and `method` attribute.
The specified method will calculate the header value.
Let's look at the following configuration:
[source,xml]
----
<int:header-enricher input-channel="in" output-channel="out">
<int:header name="foo" method="computeValue" ref="myBean"/>
</int:header-enricher>
<bean id="myBean" class="foo.bar.MyBean"/>
----
[source,java]
----
public class MyBean {
public String computeValue(String payload){
return payload.toUpperCase() + "_US";
}
}
----
You can also configure your POJO as inner bean:
[source,xml]
----
<int:header-enricher input-channel="inputChannel" output-channel="outputChannel">
<int:header name="some_header">
<bean class="org.MyEnricher"/>
</int:header>
</int:header-enricher>
----
as well as point to a Groovy script:
[source,xml]
----
<int:header-enricher input-channel="inputChannel" output-channel="outputChannel">
<int:header name="some_header">
<int-groovy:script location="org/SampleGroovyHeaderEnricher.groovy"/>
</int:header>
</int:header-enricher>
----
*SpEL Support*
In Spring Integration 2.0 we have introduced the convenience of the http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html[Spring Expression Language (SpEL)] to help configure many different components.
The _Header
Enricher_ is one of them.
Looking again at the POJO example above, you can see that the computation logic to determine the header value is actually pretty simple.
A natural question would be: "is there a simpler way to accomplish this?".
That is where SpEL shows its true power.
[source,xml]
----
<int:header-enricher input-channel="in" output-channel="out">
<int:header name="foo" expression="payload.toUpperCase() + '_US'"/>
</int:header-enricher>
----
As you can see, by using SpEL for such simple cases, we no longer have to provide a separate class and configure it in the application context.
All we need is the _expression_ attribute configured with a valid SpEL expression.
The 'payload' and 'headers' variables are bound to the SpEL Evaluation Context, giving you full access to the incoming Message.
[[header-channel-registry]]
===== Header Channel Registry
Starting with _Spring Integration 3.0_, a new sub-element `<int:header-channels-to-string/>` is available; it has no attributes.
This converts existing `replyChannel` and `errorChannel` headers (when they are a `MessageChannel`) to a String and stores the channel(s) in a registry for later resolution when it is time to send a reply, or handle an error.
This is useful for cases where the headers might be lost; for example when serializing a message into a message store or when transporting the message over JMS.
If the header does not already exist, or it is not a `MessageChannel`, no changes are made.
Use of this functionality requires the presence of a `HeaderChannelRegistry` bean.
By default, the framework creates a `DefaultHeaderChannelRegistry` with the default expiry (60 seconds).
Channels are removed from the registry after this time.
To change this, simply define a bean with id `integrationHeaderChannelRegistry` and configure the required default delay using a constructor argument (milliseconds).
Since _version 4.1_, you can set a property `removeOnGet` to `true` on the `<bean/>` definition, and the mapping entry will be removed immediately on first use.
This might be useful in a high-volume environment and when the channel is only used once, rather than waiting for the reaper to remove it.
The `HeaderChannelRegistry` has a `size()` method to determine the current size of the registry.
The `runReaper()` method cancels the current scheduled task and runs the reaper immediately; the task is then scheduled to run again based on the current delay.
These methods can be invoked directly by getting a reference to the registry, or you can send a message with, for example, the following content to a control bus:
[source]
----
"@integrationHeaderChannelRegistry.runReaper()"
----
This sub-element is a convenience only, and is the equivalent of specifying:
[source,xml]
----
<int:reply-channel
expression="@integrationHeaderChannelRegistry.channelToChannelName(headers.replyChannel)"
overwrite="true" />
<int:error-channel
expression="@integrationHeaderChannelRegistry.channelToChannelName(headers.errorChannel)"
overwrite="true" />
----
Starting with _version 4.1_, you can now override the registry's configured reaper delay, so the the channel mapping is retained for at least the specified time, regardless of the reaper delay:
[source,xml]
----
<int:header-enricher input-channel="inputTtl" output-channel="next">
<int:header-channels-to-string time-to-live-expression="120000" />
</int:header-enricher>
<int:header-enricher input-channel="inputCustomTtl" output-channel="next">
<int:header-channels-to-string
time-to-live-expression="headers['channelTTL'] ?: 120000" />
</int:header-enricher>
----
In the first case, the time to live for every header channel mapping will be 2 minutes; in the second case, the time to live is specified in the message header and uses an elvis operator to use 2 minutes if there is no header.
[[payload-enricher]]
==== Payload Enricher
In certain situations the Header Enricher, as discussed above, may not be sufficient and payloads themselves may have to be enriched with additional information.
For example, order messages that enter the Spring Integration messaging system have to look up the order's customer based on the provided customer number and then enrich the original payload with that information.
Since Spring Integration 2.1, the Payload Enricher is provided.
A Payload Enricher defines an endpoint that passes a `Message` to the exposed request channel and then expects a reply message.
The reply message then becomes the root object for evaluation of expressions to enrich the target payload.
The Payload Enricher provides full XML namespace support via the `enricher` element.
In order to send request messages, the payload enricher has a `request-channel` attribute that allows you to dispatch messages to a request channel.
Basically by defining the request channel, the Payload Enricher acts as a Gateway, waiting for the message that were sent to the request channel to return, and the Enricher then augments the message's payload with the data provided by the reply message.
When sending messages to the request channel you also have the option to only send a subset of the original payload using the `request-payload-expression` attribute.
The enriching of payloads is configured through SpEL expressions, providing users with a maximum degree of flexibility.
Therefore, users are not only able to enrich payloads with direct values from the reply channel's `Message`, but they can use SpEL expressions to extract a subset from that Message, only, or to apply addtional inline transformations, allowing them to further manipulate the data.
If you only need to enrich payloads with static values, you don't have to provide the `request-channel` attribute.
NOTE: Enrichers are a variant of Transformers and in many cases you could use a Payload Enricher or a generic Transformer implementation to add additional data to your messages payloads.
Thus, familiarize yourself with all transformation-capable components that are provided by Spring Integration and carefully select the implementation that semantically fits your business case best.
[[payload-enricher-configuration]]
===== Configuration
Below, please find an overview of all available configuration options that are available for the payload enricher:
[source,xml]
----
<int:enricher request-channel="" <1>
auto-startup="true" <2>
id="" <3>
order="" <4>
output-channel="" <5>
request-payload-expression="" <6>
reply-channel="" <7>
error-channel="" <8>
send-timeout="" <9>
should-clone-payload="false"> <10>
<int:poller></int:poller> <11>
<int:property name="" expression="" null-result-expression="'Could not determine the name'"/> <12>
<int:property name="" value="23" type="java.lang.Integer" null-result-expression="'0'"/>
<int:header name="" expression="" null-result-expression=""/> <13>
<int:header name="" value="" overwrite="" type="" null-result-expression=""/>
</int:enricher>
----
<1> Channel to which a Message will be sent to get the data to use for enrichment.
_Optional_.
<2> Lifecycle attribute signaling if this component should be started during Application Context startup.
Defaults to true._Optional_.
<3> Id of the underlying bean definition, which is either an `EventDrivenConsumer` or a `PollingConsumer`.
_Optional_.
<4> Specifies the order for invocation when this endpoint is connected as a subscriber to a channel.
This is particularly relevant when that channel is using a "failover" dispatching strategy.
It has no effect when this endpoint itself is a Polling Consumer for a channel with a queue.
_Optional_.
<5> Identifies the Message channel where a Message will be sent after it is being processed by this endpoint._Optional_.
<6> By default the original message's payload will be used as payload that will be send to the `request-channel`.
By specifying a SpEL expression as value for the `request-payload-expression` attribute, a subset of the original payload, a header value or any other resolvable SpEL expression can be used as the basis for the payload, that will be sent to the request-channel.
For the Expression evaluation the full message is available as the 'root object'.
For instance the following SpEL expressions (among others) are possible:
`payload.foo`,
`headers.foobar`,
`new java.util.Date()`,
`'foo' + 'bar'`.
<7> Channel where a reply Message is expected.
This is optional; typically the auto-generated temporary reply channel is sufficient._Optional_.
<8> Channel to which an `ErrorMessage` will be sent if an `Exception` occurs downstream of the `request-channel`.
This enables you to return an alternative object to use for enrichment.
This is optional; if it is not set then `Exception` is thrown to the caller.
_Optional_.
<9> Maximum amount of time in milliseconds to wait when sending a message to the channel, if such channel may block.
For example, a Queue Channel can block until space is available, if its maximum capacity has been reached.
Internally the send timeout is set on the `MessagingTemplate` and ultimately applied when invoking the send operation on the `MessageChannel`.
By default the send timeout is set to '-1', which may cause the send operation on the `MessageChannel`, depending on the implementation, to block indefinitely._Optional_.
<10> Boolean value indicating whether any payload that implements `Cloneable` should be cloned prior to sending the Message to the request chanenl for acquiring the enriching data.
The cloned version would be used as the target payload for the ultimate reply.
Default is `false`.
_Optional_.
<11> Allows you to configure a Message Poller if this endpoint is a Polling Consumer._Optional_.
<12> Each `property` sub-element provides the name of a property (via the mandatory `name` attribute).
That property should be settable on the target payload instance.
Exactly one of the `value` or `expression` attributes must be provided as well.
The former for a literal value to set, and the latter for a SpEL expression to be evaluated.
The root object of the evaluation context is the Message that was returned from the flow initiated by this enricher, the input Message if there is no request channel, or the application context (using the '@<beanName>.<beanProperty>' SpEL syntax).
Starting with _4.0_, when specifying a `value` attribute, you can also specify an optional `type` attribute.
When the destination is a typed setter method, the framework will coerce the value appropriately (as long as a `PropertyEditor`) exists to handle the conversion.
If however, the target payload is a `Map` the entry will be populated with the value without conversion.
The `type` attribute allows you to, say, convert a String containing a number to an `Integer` value in the target payload.
Starting with _4.1_, you can also specify an optional `null-result-expression` attribute.
When the `enricher` returns null, it will be evaluated and the output of the evaluation will be returned instead.
<13> Each `header` sub-element provides the name of a Message header (via the mandatory `name` attribute).
Exactly one of the `value` or `expression` attributes must be provided as well.
The former for a literal value to set, and the latter for a SpEL expression to be evaluated.
The root object of the evaluation context is the Message that was returned from the flow initiated by this enricher, the input Message if there is no request channel, or the application context (using the '@<beanName>.<beanProperty>' SpEL syntax).
Note, similar to the `<header-enricher>`, the `<enricher>`'s `header` element has `type` and `overwrite` attributes.
However, a difference is that, with the `<enricher>`, the `overwrite` attribute is `true` by default, to be consistent with `<enricher>`'s `<property>` sub-element.
Starting with _4.1_, you can also specify an optional `null-result-expression` attribute.
When the `enricher` returns null, it will be evaluated and the output of the evaluation will be returned instead.
[[payload-enricher-examples]]
===== Examples
Below, please find several examples of using a Payload Enricher in various situations.
In the following example, a `User` object is passed as the payload of the `Message`.
The `User` has several properties but only the `username` is set initially.
The Enricher's `request-channel` attribute below is configured to pass the `User` on to the `findUserServiceChannel`.
Through the implicitly set `reply-channel` a `User` object is returned and using the `property` sub-element, properties from the reply are extracted and used to enrich the original payload.
[source,xml]
----
<int:enricher id="findUserEnricher"
input-channel="findUserEnricherChannel"
request-channel="findUserServiceChannel">
<int:property name="email" expression="payload.email"/>
<int:property name="password" expression="payload.password"/>
</int:enricher>
----
NOTE: The code samples shown here, are part of the _Spring
Integration Samples_ project.
Please feel free to check it out at:null
_How do I pass only a subset of data to the request channel?_
Using a `request-payload-expression` attribute a single property of the payload can be passed on to the request channel instead of the full message.
In the example below on the username property is passed on to the request channel.
Keep in mind, that alwhough only the username is passed on, the resulting message send to the request channel will contain the full set of `MessageHeaders`.
[source,xml]
----
<int:enricher id="findUserByUsernameEnricher"
input-channel="findUserByUsernameEnricherChannel"
request-channel="findUserByUsernameServiceChannel"
request-payload-expression="payload.username">
<int:property name="email" expression="payload.email"/>
<int:property name="password" expression="payload.password"/>
</int:enricher>
----
_How can I enrich payloads that consist of Collection data?_
In the following example, instead of a `User` object, a `Map` is passed in.
The `Map` contains the username under the map key `username`.
Only the `username` is passed on to the request channel.
The reply contains a full `User` object, which is ultimately added to the `Map` under the `user` key.
[source,xml]
----
<int:enricher id="findUserWithMapEnricher"
input-channel="findUserWithMapEnricherChannel"
request-channel="findUserByUsernameServiceChannel"
request-payload-expression="payload.username">
<int:property name="user" expression="payload"/>
</int:enricher>
----
_How can I enrich payloads with static information without using a request channel?_
Here is an example that does not use a request channel at all, but solely enriches the message's payload with static values.
But please be aware that the word 'static' is used loosly here.
You can still use SpEL expressions for setting those values.
[source,xml]
----
<int:enricher id="userEnricher"
input-channel="input">
<int:property name="user.updateDate" expression="new java.util.Date()"/>
<int:property name="user.firstName" value="foo"/>
<int:property name="user.lastName" value="bar"/>
<int:property name="user.age" value="42"/>
</int:enricher>
----

33
src/reference/asciidoc/control-bus.adoc Normal file
View File

@@ -0,0 +1,33 @@
[[control-bus]]
=== Control Bus
As described in (EIP), the idea behind the Control Bus is that the same messaging system can be used for monitoring and managing the components within the framework as is used for "application-level" messaging.
In Spring Integration we build upon the adapters described above so that it's possible to send Messages as a means of invoking exposed operations.
[source,xml]
----
<int:control-bus input-channel="operationChannel"/>
----
The Control Bus has an input channel that can be accessed for invoking operations on the beans in the application context.
It also has all the common properties of a service activating endpoint, e.g.
you can specify an output channel if the result of the operation has a return value that you want to send on to a downstream channel.
The Control Bus executes messages on the input channel as Spring Expression Language expressions.
It takes a message, compiles the body to an expression, adds some context, and then executes it.
The default context supports any method that has been annotated with @ManagedAttribute or @ManagedOperation.
It also supports the methods on Spring's Lifecycle interface, and it supports methods that are used to configure several of Spring's TaskExecutor and TaskScheduler implementations.
The simplest way to ensure that your own methods are available to the Control Bus is to use the @ManagedAttribute and/or @ManagedOperation annotations.
Since those are also used for exposing methods to a JMX MBean registry, it's a convenient by-product (often the same types of operations you want to expose to the Control Bus would be reasonable for exposing via JMS).
Resolution of any particular instance within the application context is achieved in the typical SpEL syntax.
Simply provide the bean name with the SpEL prefix for beans (@).
For example, to execute a method on a Spring Bean a client could send a message to the operation channel as follows:
[source,java]
----
Message operation = MessageBuilder.withPayload("@myServiceBean.shutdown()").build();
operationChannel.send(operation)
----
The root of the context for the expression is the `Message` itself, so you also have access to the 'payload' and 'headers' as variables within your expression.
This is consistent with all the other expression support in Spring Integration endpoints.

131
src/reference/asciidoc/delayer.adoc Normal file
View File

@@ -0,0 +1,131 @@
[[delayer]]
=== Delayer
[[delayer-introduction]]
==== Introduction
A Delayer is a simple endpoint that allows a Message flow to be delayed by a certain interval.
When a Message is delayed, the original sender will not block.
Instead, the delayed Messages will be scheduled with an instance of `org.springframework.scheduling.TaskScheduler` to be sent to the output channel after the delay has passed.
This approach is scalable even for rather long delays, since it does not result in a large number of blocked sender Threads.
On the contrary, in the typical case a thread pool will be used for the actual execution of releasing the Messages.
Below you will find several examples of configuring a Delayer.
[[delayer-namespace]]
==== Configuring Delayer
The `<delayer>` element is used to delay the Message flow between two Message Channels.
As with the other endpoints, you can provide the 'input-channel' and 'output-channel' attributes, but the delayer also has 'default-delay' and 'expression' attributes (and 'expression' sub-element) that are used to determine the number of milliseconds that each Message should be delayed.
The following delays all messages by 3 seconds:
[source,xml]
----
<int:delayer id="delayer" input-channel="input"
default-delay="3000" output-channel="output"/>
----
If you need per-Message determination of the delay, then you can also provide the SpEL expression using the 'expression' attribute:
[source,xml]
----
<int:delayer id="delayer" input-channel="input" output-channel="output"
default-delay="3000" expression="headers['delay']"/>
----
In the example above, the 3 second delay would only apply when the expression evaluates to _null_ for a given inbound Message.
If you only want to apply a delay to Messages that have a valid result of the expression evaluation, then you can use a 'default-delay' of 0 (the default).
For any Message that has a delay of 0 (or less), the Message will be sent immediately, on the calling Thread.
tTIP: The delay handler supports expression evaluation results that represent an interval in milliseconds (any Object whose `toString()` method produces a value that can be parsed into a Long) as well as `java.util.Date` instances representing an absolute time.
In the first case, the milliseconds will be counted from the current time (e.g.
a value of 5000 would delay the Message for at least 5 seconds from the time it is received by the Delayer).
With a Date instance, the Message will not be released until the time represented by that Date object.
In either case, a value that equates to a non-positive delay, or a Date in the past, will not result in any delay.
Instead, it will be sent directly to the output channel on the original sender's Thread.
If the expression evaluation result is not a Date, and can not be parsed as a Long, the default delay (if any) will be applied.
IMPORTANT: The expression evaluation may throw an evaluation Exception for various reasons, including an invalid expression, or other conditions.
By default, such exceptions are ignored (logged at DEBUG level) and the delayer falls back to the default delay (if any).
You can modify this behavior by setting the `ignore-expression-failures` attribute.
By default this attribute is set to `true` and the Delayer behavior is as described above.
However, if you wish to not ignore expression evaluation exceptions, and throw them to the delayer's caller, set the `ignore-expression-failures` attribute to `false`.
[TIP]
=====
Notice in the example above that the delay expression is specified as `headers['delay']`.
This is the SpEL `Indexer` syntax to access a `Map` element (`MessageHeaders` implements `Map`), it invokes: `headers.get("delay")`.
For simple map element names (that do not contain '.') you can also use the SpEL _dot accessor_ syntax, where the above header expression can be specified as `headers.delay`.
But, different results are achieved if the header is missing.
In the first case, the expression will evaluate to `null`; the second will result in something like:
[source,java]
----
org.springframework.expression.spel.SpelEvaluationException: EL1008E:(pos 8):
Field or property 'delay' cannot be found on object of type 'org.springframework.messaging.MessageHeaders'
----
So, if there is a possibility of the header being omitted, and you want to fall back to the default delay, it is generally more efficient (and recommended) to use the_Indexer_ syntax instead of _dot property accessor_ syntax, because detecting the null is faster than catching an exception.
=====
The delayer delegates to an instance of Spring's `TaskScheduler` abstraction.
The default scheduler used by the delayer is the `ThreadPoolTaskScheduler` instance provided by Spring Integration on startup: <<namespace-taskscheduler>>.
If you want to delegate to a different scheduler, you can provide a reference through the delayer element's 'scheduler' attribute:
[source,xml]
----
<int:delayer id="delayer" input-channel="input" output-channel="output"
expression="headers.delay"
scheduler="exampleTaskScheduler"/>
<task:scheduler id="exampleTaskScheduler" pool-size="3"/>
----
TIP: If you configure an external `ThreadPoolTaskScheduler` you can set on this scheduler property `waitForTasksToCompleteOnShutdown = true`.
It allows successful completion of 'delay' tasks, which already in the execution state (releasing the Message), when the application is shutdown.
Before Spring Integration 2.2 this property was available on the `<delayer>` element, because `DelayHandler` could create its own scheduler on the background.
Since 2.2 delayer requires an external scheduler instance and `waitForTasksToCompleteOnShutdown` was deleted; you should use the scheduler's own configuration.
TIP: Also keep in mind `ThreadPoolTaskScheduler` has a property `errorHandler` which can be injected with some implementation of `org.springframework.util.ErrorHandler`.
This handler allows to process an `Exception` from the thread of the scheduled task sending the delayed message.
By default it uses an `org.springframework.scheduling.support.TaskUtils$LoggingErrorHandler` and you will see a stack trace in the logs.
You might want to consider using an `org.springframework.integration.channel.MessagePublishingErrorHandler`, which sends an `ErrorMessage` into an `error-channel`, either from the failed Message's header or into the default `error-channel`.
[[delayer-message-store]]
==== Delayer and Message Store
The `DelayHandler` persists delayed Messages into the Message Group in the provided `MessageStore`.
(The 'groupId' is based on required 'id' attribute of `<delayer>` element.) A delayed message is removed from the `MessageStore` by the scheduled task just before the `DelayHandler` sends the Message to the `output-channel`.
If the provided `MessageStore` is persistent (e.g.
`JdbcMessageStore`) it provides the ability to not lose Messages on the application shutdown.
After application startup, the`DelayHandler` reads Messages from its Message Group in the `MessageStore` and reschedules them with a delay based on the original arrival time of the Message (if the delay is numeric).
For messages where the delay header was a `Date`, that is used when rescheduling.
If a delayed Message remained in the `MessageStore` more than its 'delay', it will be sent immediately after startup.
The `<delayer>` can be enriched with mutually exclusive sub-elements `<transactional>` or `<advice-chain>`.
The List of these AOP Advices is applied to the proxied internal `DelayHandler.ReleaseMessageHandler`, which has the responsibility to release the Message, after the delay, on a `Thread` of the scheduled task.
It might be used, for example, when the downstream message flow throws an Exception and the `ReleaseMessageHandler`'s transaction will be rolled back.
In this case the delayed Message will remain in the persistent `MessageStore`.
You can use any custom `org.aopalliance.aop.Advice` implementation within the `<advice-chain>`.
A sample configuration of the `<delayer>` may look like this:
[source,xml]
----
<int:delayer id="delayer" input-channel="input" output-channel="output"
expression="headers.delay"
message-store="jdbcMessageStore">
<int:advice-chain>
<beans:ref bean="customAdviceBean"/>
<tx:advice>
<tx:attributes>
<tx:method name="*" read-only="true"/>
</tx:attributes>
</tx:advice>
</int:advice-chain>
</int:delayer>
----
The `DelayHandler` can be exported as a JMX `MBean` with managed operations `getDelayedMessageCount` and `reschedulePersistedMessages`, which allows the rescheduling of delayed persisted Messages at runtime, for example, if the`TaskScheduler` has previously been stopped.
These operations can be invoked via a `Control Bus` command:
[source,java]
----
Message<String> delayerReschedulingMessage =
MessageBuilder.withPayload("@'delayer.handler'.reschedulePersistedMessages()").build();
controlBusChannel.send(delayerReschedulingMessage);
----
NOTE: For more information regarding the Message Store, JMX and the Control Bus, please read <<system-management-chapter>>.

594
src/reference/asciidoc/endpoint-summary.adoc Normal file
View File

@@ -0,0 +1,594 @@
[[endpoint-summary]]
== Endpoint Quick Reference Table
As discussed in the sections above, Spring Integration provides a number of endpoints used to interface with external systems, file systems etc.
The following is a summary of the various endpoints with quick links to the appropriate chapter.
To recap, *Inbound Channel Adapters* are used for one-way integration bringing data into the messaging application.
*Outbound Channel Adapters* are used for one-way integration to send data out of the messaging application.
*Inbound Gateways* are used for a bidirectional integration flow where some other system invokes the messaging application and receives a reply.*Outbound Gateways* are used for a bidirectional integration flow where the messaging application invokes some external service or entity, expecting a result.
.Endpoint Quick Reference
[cols="1,1,1,1,1", options="header"]
|===
| Module
| Inbound Adapter
| Outbound Adapter
| Inbound Gateway
| Outbound Gateway
| *AMQP*
| <<amqp-inbound-channel-adapter>>
| <<amqp-outbound-channel-adapter>>
| <<amqp-inbound-gateway>>
| <<amqp-outbound-gateway>>
| *Events*
| <<applicationevent-inbound>>
| <<applicationevent-outbound>>
| N
| N
| *Feed*
| <<feed-inbound-channel-adapter>>
| N
| N
| N
| *File*
| <<file-reading>> and <<file-tailing>>
| <<file-writing>>
| N
| <<file-writing>>
| *FTP(S)*
| <<ftp-inbound>>
| <<ftp-outbound>>
| N
| <<ftp-outbound-gateway>>
| *Gemfire*
| <<gemfire-inbound>> and <<gemfire-cq>>
| <<gemfire-outbound>>
| N
| N
| *HTTP*
| <<http-namespace>>
| <<http-namespace>>
| <<http-inbound>>
| <<http-outbound>>
| *JDBC*
| <<jdbc-inbound-channel-adapter>> and <<stored-procedure-inbound-channel-adapter>>
| <<jdbc-outbound-channel-adapter>> and <<stored-procedure-outbound-channel-adapter>>
| N
| <<jdbc-outbound-gateway>> and <<stored-procedure-outbound-gateway>>
| *JMS*
| <<jms-inbound-channel-adapter>> and <<jms-message-driven-channel-adapter>>
| <<jms-outbound-channel-adapter>>
| <<jms-inbound-gateway>>
| <<jms-outbound-gateway>>
| *JMX*
| <<jmx-notification-listening-channel-adapter>> and <<jmx-attribute-polling-channel-adapter>> and <<tree-polling-channel-adapter>>
| <<jmx-notification-publishing-channel-adapter>> and <<jmx-operation-invoking-channel-adapter>>
| N
| <<jmx-operation-invoking-outbound-gateway>>
| *JPA*
| <<jpa-inbound-channel-adapter>>
| <<jpa-outbound-channel-adapter>>
| N
| <<jpa-updating-outbound-gateway>> and <<jpa-retrieving-outbound-gateway>>
| *Mail*
| <<mail-inbound>>
| <<mail-outbound>>
| N
| N
| *MongoDB*
| <<mongodb-inbound-channel-adapter>>
| <<mongodb-outbound-channel-adapter>>
| N
| N
| *MQTT*
| <<mqtt-inbound>>
| <<mqtt-outbound>>
| N
| N
| *Redis*
| <<redis-inbound-channel-adapter>> and <<redis-queue-inbound-channel-adapter>> and <<redis-store-inbound-channel-adapter>>
| <<redis-outbound-channel-adapter>> and <<redis-queue-outbound-channel-adapter>> and <<redis-store-outbound-channel-adapter>>
| <<redis-queue-inbound-gateway>>
| <<redis-outbound-gateway>> and <<redis-queue-outbound-gateway>>
| *Resource*
| <<resource-inbound-channel-adapter>>
| N
| N
| N
| *RMI*
| N
| N
| <<rmi-inbound>>
| <<rmi-outbound>>
| *SFTP*
| <<sftp-inbound>>
| <<sftp-outbound>>
| N
| <<sftp-outbound-gateway>>
| *Stream*
| <<stream-reading>>
| <<stream-writing>>
| N
| N
| *Syslog*
| <<syslog-inbound-adapter>>
| N
| N
| N
| *TCP*
| <<tcp-adapters>>
| <<tcp-adapters>>
| <<tcp-gateways>>
| <<tcp-gateways>>
| *Twitter*
| <<twitter-inbound>>
| <<twitter-outbound>>
| N
| <<twitter-sog>>
| *UDP*
| <<udp-adapters>>
| <<udp-adapters>>
| N
| N
| *Web Services*
| N
| N
| <<webservices-inbound>>
| <<webservices-outbound>>
| *Web Sockets*
| <<web-socket-inbound-adapter>>
| <<web-socket-outbound-adapter>>
| N
| N
| *XMPP*
| <<xmpp-messages>> and <<xmpp-presence>>
| <<xmpp-messages>> and <<xmpp-presence>>
| N
| N
|===
In addition, as discussed in <<spring-integration-core-messaging>>, endpoints are provided for interfacing with Plain Old Java Objects (POJOs).
As discussed in <<channel-adapter>>, the `<int:inbound-channel-adapter>` allows polling a java method for data; the `<int:outbound-channel-adapter>` allows sending data to a `void` method, and as discussed in <<gateway>>, the `<int:gateway>` allows any Java program to invoke a messaging flow.
Each of these without requiring any source level dependencies on Spring Integration.
The equivalent of an outbound gateway in this context would be to use a <<service-activator>> to invoke a method that returns an Object of some kind.

566
src/reference/asciidoc/endpoint.adoc Normal file
View File

@@ -0,0 +1,566 @@
[[endpoint]]
=== Message Endpoints
The first part of this chapter covers some background theory and reveals quite a bit about the underlying API that drives Spring Integration's various messaging components.
This information can be helpful if you want to really understand what's going on behind the scenes.
However, if you want to get up and running with the simplified namespace-based configuration of the various elements, feel free to skip ahead to<<endpoint-namespace>> for now.
As mentioned in the overview, Message Endpoints are responsible for connecting the various messaging components to channels.
Over the next several chapters, you will see a number of different components that consume Messages.
Some of these are also capable of sending reply Messages.
Sending Messages is quite straightforward.
As shown above in <<channel>>, it's easy to _send_ a Message to a Message Channel.
However, receiving is a bit more complicated.
The main reason is that there are two types of consumers:http://www.eaipatterns.com/PollingConsumer.html[Polling Consumers] and http://www.eaipatterns.com/EventDrivenConsumer.html[Event Driven Consumers].
Of the two, Event Driven Consumers are much simpler.
Without any need to manage and schedule a separate poller thread, they are essentially just listeners with a callback method.
When connecting to one of Spring Integration's subscribable Message Channels, this simple option works great.
However, when connecting to a buffering, pollable Message Channel, some component has to schedule and manage the polling thread(s).
Spring Integration provides two different endpoint implementations to accommodate these two types of consumers.
Therefore, the consumers themselves can simply implement the callback interface.
When polling is required, the endpoint acts as a_container_ for the consumer instance.
The benefit is similar to that of using a container for hosting Message Driven Beans, but since these consumers are simply Spring-managed Objects running within an ApplicationContext, it more closely resembles Spring's own MessageListener containers.
[[endpoint-handler]]
==== Message Handler
Spring Integration's `MessageHandler` interface is implemented by many of the components within the framework.
In other words, this is not part of the public API, and a developer would not typically implement `MessageHandler` directly.
Nevertheless, it is used by a Message Consumer for actually handling the consumed Messages, and so being aware of this strategy interface does help in terms of understanding the overall role of a consumer.
The interface is defined as follows:
[source,java]
----
public interface MessageHandler {
void handleMessage(Message<?> message);
}
----
Despite its simplicity, this provides the foundation for most of the components that will be covered in the following chapters (Routers, Transformers, Splitters, Aggregators, Service Activators, etc).
Those components each perform very different functionality with the Messages they handle, but the requirements for actually receiving a Message are the same, and the choice between polling and event-driven behavior is also the same.
Spring Integration provides two endpoint implementations that _host_ these callback-based handlers and allow them to be connected to Message Channels.
[[endpoint-eventdrivenconsumer]]
==== Event Driven Consumer
Because it is the simpler of the two, we will cover the Event Driven Consumer endpoint first.
You may recall that the `SubscribableChannel` interface provides a `subscribe()` method and that the method accepts a `MessageHandler` parameter (as shown in <<channel-interfaces-subscribablechannel>>):
[source,java]
----
subscribableChannel.subscribe(messageHandler);
----
Since a handler that is subscribed to a channel does not have to actively poll that channel, this is an Event Driven Consumer, and the implementation provided by Spring Integration accepts a a `SubscribableChannel` and a `MessageHandler`:
[source,java]
----
SubscribableChannel channel = context.getBean("subscribableChannel", SubscribableChannel.class);
EventDrivenConsumer consumer = new EventDrivenConsumer(channel, exampleHandler);
----
[[endpoint-pollingconsumer]]
==== Polling Consumer
Spring Integration also provides a `PollingConsumer`, and it can be instantiated in the same way except that the channel must implement `PollableChannel`:
[source,java]
----
PollableChannel channel = context.getBean("pollableChannel", PollableChannel.class);
PollingConsumer consumer = new PollingConsumer(channel, exampleHandler);
----
NOTE: For more information regarding Polling Consumers, please also read <<polling-consumer>> as well as <<channel-adapter>>.
There are many other configuration options for the Polling Consumer.
For example, the trigger is a required property:
[source,java]
----
PollingConsumer consumer = new PollingConsumer(channel, handler);
consumer.setTrigger(new IntervalTrigger(30, TimeUnit.SECONDS));
----
Spring Integration currently provides two implementations of the `Trigger` interface: `IntervalTrigger` and `CronTrigger`.
The `IntervalTrigger` is typically defined with a simple interval (in milliseconds), but also supports an _initialDelay_ property and a boolean _fixedRate_ property (the default is false, i.e.
fixed delay):
[source,java]
----
IntervalTrigger trigger = new IntervalTrigger(1000);
trigger.setInitialDelay(5000);
trigger.setFixedRate(true);
----
The `CronTrigger` simply requires a valid cron expression (see the Javadoc for details):
[source,java]
----
CronTrigger trigger = new CronTrigger("*/10 * * * * MON-FRI");
----
In addition to the trigger, several other polling-related configuration properties may be specified:
[source,java]
----
PollingConsumer consumer = new PollingConsumer(channel, handler);
consumer.setMaxMessagesPerPoll(10);
consumer.setReceiveTimeout(5000);
----
The _maxMessagesPerPoll_ property specifies the maximum number of messages to receive within a given poll operation.
This means that the poller will continue calling receive() _without waiting_ until either `null` is returned or that max is reached.
For example, if a poller has a 10 second interval trigger and a _maxMessagesPerPoll_ setting of 25, and it is polling a channel that has 100 messages in its queue, all 100 messages can be retrieved within 40 seconds.
It grabs 25, waits 10 seconds, grabs the next 25, and so on.
The _receiveTimeout_ property specifies the amount of time the poller should wait if no messages are available when it invokes the receive operation.
For example, consider two options that seem similar on the surface but are actually quite different: the first has an interval trigger of 5 seconds and a receive timeout of 50 milliseconds while the second has an interval trigger of 50 milliseconds and a receive timeout of 5 seconds.
The first one may receive a message up to 4950 milliseconds later than it arrived on the channel (if that message arrived immediately after one of its poll calls returned).
On the other hand, the second configuration will never miss a message by more than 50 milliseconds.
The difference is that the second option requires a thread to wait, but as a result it is able to respond much more quickly to arriving messages.
This technique, known as _long polling_, can be used to emulate event-driven behavior on a polled source.
A Polling Consumer may also delegate to a Spring `TaskExecutor`, as illustrated in the following example:
[source,java]
----
PollingConsumer consumer = new PollingConsumer(channel, handler);
TaskExecutor taskExecutor = context.getBean("exampleExecutor", TaskExecutor.class);
consumer.setTaskExecutor(taskExecutor);
----
Furthermore, a `PollingConsumer` has a property called _adviceChain_.
This property allows you to specify a `List` of AOP Advices for handling additional cross cutting concerns including transactions.
These advices are applied around the `doPoll()` method.
For more in-depth information, please see the sections _AOP Advice chains_ and _Transaction Support_ under <<endpoint-namespace>>.
The examples above show dependency lookups, but keep in mind that these consumers will most often be configured as Spring _bean definitions_.
In fact, Spring Integration also provides a `FactoryBean` called `ConsumerEndpointFactoryBean` that creates the appropriate consumer type based on the type of channel, and there is full XML namespace support to even further hide those details.
The namespace-based configuration will be featured as each component type is introduced.
NOTE: Many of the `MessageHandler` implementations are also capable of generating reply Messages.
As mentioned above, sending Messages is trivial when compared to the Message reception.
Nevertheless,_when_ and _how many_ reply Messages are sent depends on the handler type.
For example, an _Aggregator_ waits for a number of Messages to arrive and is often configured as a downstream consumer for a _Splitter_ which may generate multiple replies for each Message it handles.
When using the namespace configuration, you do not strictly need to know all of the details, but it still might be worth knowing that several of these components share a common base class, the `AbstractReplyProducingMessageHandler`, and it provides a `setOutputChannel(..)` method.
[[endpoint-namespace]]
==== Namespace Support
Throughout the reference manual, you will see specific configuration examples for endpoint elements, such as router, transformer, service-activator, and so on.
Most of these will support an _input-channel_ attribute and many will support an _output-channel_ attribute.
After being parsed, these endpoint elements produce an instance of either the `PollingConsumer` or the `EventDrivenConsumer` depending on the type of the _input-channel_ that is referenced: `PollableChannel` or `SubscribableChannel` respectively.
When the channel is pollable, then the polling behavior is determined based on the endpoint element's _poller_ sub-element and its attributes.
_Configuration_Below you find a _poller_ with all available configuration options:
[source,xml]
----
<int:poller cron="" <1>
default="false" <2>
error-channel="" <3>
fixed-delay="" <4>
fixed-rate="" <5>
id="" <6>
max-messages-per-poll="" <7>
receive-timeout="" <8>
ref="" <9>
task-executor="" <10>
time-unit="MILLISECONDS" <11>
trigger=""> <12>
<int:advice-chain /> <13>
<int:transactional /> <14>
</int:poller>
----
<1> Provides the ability to configure Pollers using Cron expressions.
The underlying implementation uses an `org.springframework.scheduling.support.CronTrigger`.
If this attribute is set, none of the following attributes must be specified: `fixed-delay`, `trigger`, `fixed-rate`, `ref`.
<2> By setting this attribute to _true_, it is possible to define exactly one (1) global default poller.
An exception is raised if more than one default poller is defined in the application context.
Any endpoints connected to a PollableChannel (PollingConsumer) or any SourcePollingChannelAdapter that does not have any explicitly configured poller will then use the global default Poller._Optional_.
Defaults to `false`.
<3> Identifies the channel which error messages will be sent to if a failure occurs in this poller's invocation.
To completely suppress Exceptions, provide a reference to the `nullChannel`.
_Optional_.
<4> The fixed delay trigger uses a `PeriodicTrigger` under the covers.
If the `time-unit` attribute is not used, the specified value is represented in milliseconds.
If this attribute is set, none of the following attributes must be specified: `fixed-rate`, `trigger`, `cron`, `ref`.
<5> The fixed rate trigger uses a `PeriodicTrigger` under the covers.
If the `time-unit` attribute is not used the specified value is represented in milliseconds.
If this attribute is set, none of the following attributes must be specified: `fixed-delay`, `trigger`, `cron`, `ref`.
<6> The Id referring to the Poller's underlying bean-definition, which is of type `org.springframework.integration.scheduling.PollerMetadata`.
The _id_ attribute is required for a top-level poller element unless it is the default poller (`default="true"`).
<7> Please see <<channel-adapter-namespace-inbound>> for more information.
_Optional_.
If not specified the default values used depends on the context.
If a `PollingConsumer` is used, this atribute will default to _-1_.
However, if a `SourcePollingChannelAdapter` is used, then the `max-messages-per-poll` attribute defaults to _1_.
<8> Value is set on the underlying class `PollerMetadata`_Optional_.
If not specified it defaults to 1000 (milliseconds).
<9> Bean reference to another top-level poller.
The `ref` attribute must not be present on the top-level `poller` element.
However, if this attribute is set, none of the following attributes must be specified: `fixed-rate`, `trigger`, `cron`, `fixed-deleay`.
<10> Provides the ability to reference a custom _task executor_.
Please see the section below titled _TaskExecutor Support_ for further information.
_Optional_.
<11> This attribute specifies the `java.util.concurrent.TimeUnit` enum value on the underlying `org.springframework.scheduling.support.PeriodicTrigger`.
Therefore, this attribute can _ONLY_ be used in combination with the `fixed-delay` or `fixed-rate` attributes.
If combined with either `cron` or a `trigger` reference attribute, it will cause a failure.
The minimal supported granularity for a `PeriodicTrigger` is MILLISECONDS.
Therefore, the only available options are MILLISECONDS and SECONDS.
If this value is not provided, then any `fixed-delay` or `fixed-rate` value will be interpreted as MILLISECONDS by default.
Basically this enum provides a convenience for SECONDS-based interval trigger values.
For hourly, daily, and monthly settings, consider using a `cron` trigger instead.
<12> Reference to any spring configured bean which implements the `org.springframework.scheduling.Trigger` interface.
_Optional_.
However, if this attribute is set, none of the following attributes must be specified:`fixed-delay`, `fixed-rate`, `cron`, `ref`.
<13> Allows to specify extra AOP Advices to handle additional cross cutting concerns.
Please see the section below titled _Transaction Support_ for further information.
_Optional_.
<14> Pollers can be made transactional.
Please see the section below titled _AOP Advice chains_ for further information.
_Optional_.
_Examples_
For example, a simple interval-based poller with a 1-second interval would be configured like this:
[source,xml]
----
<int:transformer input-channel="pollable"
ref="transformer"
output-channel="output">
<int:poller fixed-rate="1000"/>
</int:transformer>
----
As an alternative to _fixed-rate_ you can also use the _fixed-delay_ attribute.
For a poller based on a Cron expression, use the _cron_ attribute instead:
[source,xml]
----
<int:transformer input-channel="pollable"
ref="transformer"
output-channel="output">
<int:poller cron="*/10 * * * * MON-FRI"/>
</int:transformer>
----
If the input channel is a `PollableChannel`, then the poller configuration is required.
Specifically, as mentioned above, the _trigger_ is a required property of the PollingConsumer class.
Therefore, if you omit the _poller_ sub-element for a Polling Consumer endpoint's configuration, an Exception may be thrown.
The exception will also be thrown if you attempt to configure a poller on the element that is connected to a non-pollable channel.
It is also possible to create top-level pollers in which case only a _ref_ is required:
[source,xml]
----
<int:poller id="weekdayPoller" cron="*/10 * * * * MON-FRI"/>
<int:transformer input-channel="pollable"
ref="transformer"
output-channel="output">
<int:poller ref="weekdayPoller"/>
</int:transformer>
----
NOTE: The _ref_ attribute is only allowed on the inner-poller definitions.
Defining this attribute on a top-level poller will result in a configuration exception thrown during initialization of the Application Context.
_Global Default Pollers_
In fact, to simplify the configuration even further, you can define a global default poller.
A single top-level poller within an ApplicationContext may have the `default` attribute with a value of _true_.
In that case, any endpoint with a PollableChannel for its input-channel that is defined within the same ApplicationContext and has no explicitly configured _poller_ sub-element will use that default.
[source,xml]
----
<int:poller id="defaultPoller" default="true" max-messages-per-poll="5" fixed-rate="3000"/>
<!-- No <poller/> sub-element is necessary since there is a default -->
<int:transformer input-channel="pollable"
ref="transformer"
output-channel="output"/>
----
_Transaction Support_
Spring Integration also provides transaction support for the pollers so that each receive-and-forward operation can be performed as an atomic unit-of-work.
To configure transactions for a poller, simply add the_<transactional/>_ sub-element.
The attributes for this element should be familiar to anyone who has experience with Spring's Transaction management:
[source,xml]
----
<int:poller fixed-delay="1000">
<int:transactional transaction-manager="txManager"
propagation="REQUIRED"
isolation="REPEATABLE_READ"
timeout="10000"
read-only="false"/>
</int:poller>
----
For more information please refer to <<transaction-poller>>.
_AOP Advice chains_
Since Spring transaction support depends on the Proxy mechanism  with `TransactionInterceptor` (AOP Advice) handling transactional behavior of the message flow initiated by the poller, some times there is a need to provide extra Advice(s) to handle other cross cutting behavior associated with the poller.
For that poller defines an _advice-chain_ element allowing you to add more advices - class that  implements `MethodInterceptor` interface...
[source,xml]
----
<int:service-activator id="advicedSa" input-channel="goodInputWithAdvice" ref="testBean"
method="good" output-channel="output">
<int:poller max-messages-per-poll="1" fixed-rate="10000">
<int:advice-chain>
<ref bean="adviceA" />
<beans:bean class="org.bar.SampleAdvice" />
<ref bean="txAdvice" />
</int:advice-chain>
</int:poller>
</int:service-activator>
----
For more information on how to implement MethodInterceptor please refer to AOP sections of Spring reference manual (section 8 and 9).
Advice chain can also be applied on the poller that does not have any transaction configuration essentially allowing you to enhance the behavior of the message flow initiated by the poller.
IMPORTANT: When using an advice chain, the `<transactional/>` child element cannot be specified; instead, declare a `<tx:advice/>` bean and add it to the `<advice-chain/>`.
See <<transaction-poller>> for complete configuration.
_TaskExecutor Support_
The polling threads may be executed by any instance of Spring's `TaskExecutor` abstraction.
This enables concurrency for an endpoint or group of endpoints.
As of Spring 3.0, there is a _task_ namespace in the core Spring Framework, and its <executor/> element supports the creation of a simple thread pool executor.
That element accepts attributes for common concurrency settings such as pool-size and queue-capacity.
Configuring a thread-pooling executor can make a substantial difference in how the endpoint performs under load.
These settings are available per-endpoint since the performance of an endpoint is one of the major factors to consider (the other major factor being the expected volume on the channel to which the endpoint subscribes).
To enable concurrency for a polling endpoint that is configured with the XML namespace support, provide the _task-executor_ reference on its <poller/> element and then provide one or more of the properties shown below:
[source,xml]
----
<int:poller task-executor="pool" fixed-rate="1000"/>
<task:executor id="pool"
pool-size="5-25"
queue-capacity="20"
keep-alive="120"/>
----
If no _task-executor_ is provided, the consumer's handler will be invoked in the caller's thread.
Note that the _caller_ is usually the default `TaskScheduler` (see <<namespace-taskscheduler>>).
Also, keep in mind that the _task-executor_ attribute can provide a reference to any implementation of Spring's `TaskExecutor` interface by specifying the bean name.
The _executor_ element above is simply provided for convenience.
As mentioned in the background section for Polling Consumers above, you can also configure a Polling Consumer in such a way as to emulate event-driven behavior.
With a long receive-timeout and a short interval-trigger, you can ensure a very timely reaction to arriving messages even on a polled message source.
Note that this will only apply to sources that have a blocking wait call with a timeout.
For example, the File poller does not block, each receive() call returns immediately and either contains new files or not.
Therefore, even if a poller contains a long receive-timeout, that value would never be usable in such a scenario.
On the other hand when using Spring Integration's own queue-based channels, the timeout value does have a chance to participate.
The following example demonstrates how a Polling Consumer will receive Messages nearly instantaneously.
[source,xml]
----
<int:service-activator input-channel="someQueueChannel"
output-channel="output">
<int:poller receive-timeout="30000" fixed-rate="10"/>
</int:service-activator>
----
Using this approach does not carry much overhead since internally it is nothing more then a timed-wait thread which does not require nearly as much CPU resource usage as a thrashing, infinite while loop for example.
[[polling-consumer-change-polling-rate]]
==== Change Polling Rate at Runtime
When configuring Pollers with a `fixed-delay` or `fixed-rate` attribute, the default implementation will use a `PeriodicTrigger` instance.
The `PeriodicTrigger` is part of the Core Spring Framework and it accepts the _interval_ as a constructor argument, only.
Therefore it cannot be changed at runtime.
However, you can define your own implementation of the `org.springframework.scheduling.Trigger` interface.
You could even use the PeriodicTrigger as a starting point.
Then, you can add a setter for the interval (period), or you could even embed your own throttling logic within the trigger itself if desired.
The _period_ property will be used with each call to _nextExecutionTime_ to schedule the next poll.
To use this custom trigger within pollers, declare the bean defintion of the custom Trigger in your application context and inject the dependency into your Poller configuration using the `trigger` attribute, which references the custom Trigger bean instance.
You can now obtain a reference to the Trigger bean and the polling interval can be changed between polls.
For an example, please see the Spring Integration Samples project.
It contains a sample called _dynamic-poller_, which uses a custom Trigger and demonstrates the ability to change the polling interval at runtime.
https://github.com/SpringSource/spring-integration-samples/tree/master/intermediate[https://github.com/SpringSource/spring-integration-samples/tree/master/intermediate]
The sample provides a custom Trigger which implements the _http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/scheduling/Trigger.html[org.springframework.scheduling.Trigger]_ interface.
The sample's Trigger is based on Spring's http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/scheduling/support/PeriodicTrigger.html[PeriodicTrigger] implementation.
However, the fields of the custom trigger are not final and the properties have explicit getters and setters, allowing to dynamically change the polling period at runtime.
NOTE: It is important to note, though, that because the Trigger method is _nextExecutionTime()_, any changes to a dynamic trigger will not take effect until the next poll, based on the existing configuration.
It is not possible to force a trigger to fire before it's currently configured next execution time.
[[payload-type-conversion]]
==== Payload Type Conversion
Throughout the reference manual, you will also see specific configuration and implementation examples of various endpoints which can accept a Message or any arbitrary Object as an input parameter.
In the case of an Object, such a parameter will be mapped to a Message payload or part of the payload or header (when using the Spring Expression Language).
However there are times when the type of input parameter of the endpoint method does not match the type of the payload or its part.
In this scenario we need to perform type conversion.
Spring Integration provides a convenient way for registering type converters (using the Spring 3.x ConversionService) within its own instance of a conversion service bean named_integrationConversionService_.
That bean is automatically created as soon as the first converter is defined using the Spring Integration infrastructure.
To register a Converter all you need is to implement `org.springframework.core.convert.converter.Converter`, `org.springframework.core.convert.converter.GenericConverter` or `org.springframework.core.convert.converter.ConverterFactory`.
The `Converter` implementation is the simplest and converts from a single type to another.
For more sophistication, such as converting to a class hierarchy, you would implement a `GenericConverter` and possibly a `ConditionalConverter`.
These give you complete access to the _from_ and _to_ type descriptors enabling complex conversions.
For example, if you have an abstract class `Foo` that is the target of your conversion (parameter type, channel data type etc) and you have two concrete implementations `Bar` and `Baz` and you wish to convert to one or the other based on the input type, the `GenericConverter` would be a good fit.
Refer to the JavaDocs for these interfaces for more information.
When you have implemented your converter, you can register it with convenient namespace support:
[source,xml]
----
<int:converter ref="sampleConverter"/>
<bean id="sampleConverter" class="foo.bar.TestConverter"/>
----
or as an inner bean:
[source,xml]
----
<int:converter>
<bean class="o.s.i.config.xml.ConverterParserTests$TestConverter3"/>
</int:converter>
----
Starting with _Spring Integration 4.0_, the above configuration is available using annotations:
[source,java]
----
@Component
@IntegrationConverter
public class TestConverter implements Converter<Boolean, Number> {
public Number convert(Boolean source) {
return source ? 1 : 0;
}
}
----
or as a `@Configuration` part:
[source,java]
----
@Configuration
@EnableIntegration
public class ContextConfiguration {
@Bean
@IntegrationConverter
public SerializingConverter serializingConverter() {
return new SerializingConverter();
}
}
----
[IMPORTANT]
=====
When configuring an _Application Context_, the Spring Framework allows you to add a _conversionService_ bean (see http://static.springsource.org/spring/docs/current/spring-framework-reference/html/validation.html#core-convert-Spring-config[Configuring a ConversionService] chapter).
This service is used, when needed, to perform appropriate conversions during bean creation and configuration.
In contrast, the _integrationConversionService_ is used for runtime conversions.
These uses are quite different; converters that are intended for use when wiring bean constructor-args and properties may produce unintended results if used at runtime for Spring Integration expression evaluation against Messages within Datatype Channels, Payload Type transformers etc.
However, if you do want to use the Spring _conversionService_ as the Spring Integration _integrationConversionService_, you can configure an _alias_ in the Application Context:
[source,xml]
----
<alias name="conversionService" alias="integrationConversionService"/>
----
In this case the _conversionService_'s Converters will be available for Spring Integration runtime conversion.
=====
[[async-polling]]
==== Asynchronous polling
If you want the polling to be asynchronous, a Poller can optionally specify a _task-executor_ attribute pointing to an existing instance of any `TaskExecutor` bean (Spring 3.0 provides a convenient namespace configuration via the `task` namespace).
However, there are certain things you must understand when configuring a Poller with a TaskExecutor. 
The problem is that there are two configurations in place.
The _Poller_ and the _TaskExecutor_, and they both have to be in tune with each other otherwise you might end up creating an artificial memory leak.
Let's look at the following configuration provided by one of the users on the Spring Integration forum (http://forum.springsource.org/showthread.php?t=94519):
[source,xml]
----
<int:service-activator input-channel="publishChannel" ref="myService">
<int:poller receive-timeout="5000" task-executor="taskExecutor" fixed-rate="50"/>
</int:service-activator>
<task:executor id="taskExecutor" pool-size="20" queue-capacity="20"/>
----
The above configuration demonstrates one of those out of tune configurations.
The poller keeps scheduling new tasks even though all the threads are blocked waiting for either a new message to arrive, or the timeout to expire.
Given that there are 20 threads executing tasks with a 5 second timeout, they will be executed at a rate of 4 per second (5000/20 = 250ms).
But, new tasks are being scheduled at a rate of 20 per second, so the internal queue in the task executor will grow at a rate of 16 per second (while the process is idle), so we essentially have a memory leak.
One of the ways to handle this is to set the `queue-capacity` attribute of the Task Executor to 0.
You can also manage it by specifying what to do with messages that can not be queued by setting the `rejection-policy` attribute of the Task Executor (e.g., DISCARD).
In other words there are certain details you must understand with regard to configuring the TaskExecutor.
Please refer to - _Section 25 - Task Execution and Scheduling_ of the Spring reference manual for more detail on the subject.
[[endpoint-inner]]
==== Endpoint Inner Beans
Many endpoints are composite beans; this includes all consumers and all polled inbound channel adapters.
Consumers (polled or event- driven) delegate to a `MessageHandler`; polled adapters obtain messages by delegating to a `MessageSource`.
Often, it is useful to obtain a reference to the delegate bean, perhaps to change configuration at runtime, or for testing.
These beans can be obtained from the `ApplicationContext` with well-known names.
`MessageHandler` s are registered with the application context with a bean id `someConsumer.handler` (where 'consumer' is the endpoint's `id` attribute).
`MessageSource` s are registered with a bean id `somePolledAdapter.source`, again where 'somePolledAdapter' is the id of the adapter.
The above only applies to the framework component itself.
If you use an inner bean definition such as this:
[source,xml]
----
<int:service-activator id="exampleServiceActivator" input-channel="inChannel"
output-channel = "outChannel" method="foo">
<beans:bean class="org.foo.ExampleServiceActivator"/>
</int:service-activator>
----
the bean is treated like any inner bean declared that way and is not registered with the application context.
If you wish to access this bean in some other manner, declare it at the top level with an `id` and use the `ref` attribute instead.
See the http://docs.spring.io/spring-framework/docs/current/spring-framework-reference/html/beans.html#beans-inner-beans[Spring Documentation] for more information.

67
src/reference/asciidoc/event.adoc Normal file
View File

@@ -0,0 +1,67 @@
[[applicationevent]]
== Spring ApplicationEvent Support
Spring Integration provides support for inbound and outbound `ApplicationEvents` as defined by the underlying Spring Framework.
For more information about Spring's support for events and listeners, refer to the http://static.springsource.org/spring/docs/2.5.x/reference/beans.html#context-functionality-events[Spring Reference Manual].
[[applicationevent-inbound]]
=== Receiving Spring ApplicationEvents
To receive events and send them to a channel, simply define an instance of Spring Integration's `ApplicationEventListeningMessageProducer`.
This class is an implementation of Spring's `ApplicationListener` interface.
By default it will pass all received events as Spring Integration Messages.
To limit based on the type of event, configure the list of event types that you want to receive with the 'eventTypes' property.
If a received event has a Message instance as its 'source', then that will be passed as-is.
Otherwise, if a SpEL-based "payloadExpression" has been provided, that will be evaluated against the ApplicationEvent instance.
If the event's source is not a Message instance and no "payloadExpression" has been provided, then the ApplicationEvent itself will be passed as the payload.
For convenience namespace support is provided to configure an `ApplicationEventListeningMessageProducer` via the _inbound-channel-adapter_ element.
[source,xml]
----
<int-event:inbound-channel-adapter channel="eventChannel"
error-channel="eventErrorChannel"
event-types="example.FooEvent, example.BarEvent"/>
<int:publish-subscribe-channel id="eventChannel"/>
----
In the above example, all Application Context events that match one of the types specified by the 'event-types' (optional) attribute will be delivered as Spring Integration Messages to the Message Channel named 'eventChannel'.
If a downstream component throws an exception, a MessagingException containing the failed message and exception will be sent to the channel named 'eventErrorChannel'.
If no "error-channel" is specified and the downstream channels are synchronous, the Exception will be propagated to the caller.
[[applicationevent-outbound]]
=== Sending Spring ApplicationEvents
To send Spring `ApplicationEvents`, create an instance of the `ApplicationEventPublishingMessageHandler` and register it within an endpoint.
This implementation of the `MessageHandler` interface also implements Spring's `ApplicationEventPublisherAware` interface and thus acts as a bridge between Spring Integration Messages and `ApplicationEvents`.
For convenience namespace support is provided to configure an `ApplicationEventPublishingMessageHandler` via the _outbound-channel-adapter_ element.
[source,xml]
----
<int:channel id="eventChannel"/>
<int-event:outbound-channel-adapter channel="eventChannel"/>
----
If you are using a PollableChannel (e.g., Queue), you can also provide _poller_ as a sub-element of the _outbound-channel-adapter_ element.
You can also optionally provide a _task-executor_ reference for that poller.
The following example demonstrates both.
[source,xml]
----
<int:channel id="eventChannel">
<int:queue/>
</int:channel>
<int-event:outbound-channel-adapter channel="eventChannel">
<int:poller max-messages-per-poll="1" task-executor="executor" fixed-rate="100"/>
</int-event:outbound-channel-adapter>
<task:executor id="executor" pool-size="5"/>
----
In the above example, all messages sent to the 'eventChannel' channel will be published as ApplicationEvents to any relevant ApplicationListener instances that are registered within the same Spring ApplicationContext.
If the payload of the Message is an ApplicationEvent, it will be passed as-is.
Otherwise the Message itself will be wrapped in a MessagingEvent instance.

57
src/reference/asciidoc/feed.adoc Normal file
View File

@@ -0,0 +1,57 @@
[[feed]]
== Feed Adapter
Spring Integration provides support for Syndication via Feed Adapters
[[feed-intro]]
=== Introduction
Web syndication is a form of publishing material such as news stories, press releases, blog posts, and other items typically available on a website but also made available in a feed format such as RSS or ATOM.
Spring integration provides support for Web Syndication via its 'feed' adapter and provides convenient namespace-based configuration for it.
To configure the 'feed' namespace, include the following elements within the headers of your XML configuration file:
[source,xml]
----
xmlns:int-feed="http://www.springframework.org/schema/integration/feed"
xsi:schemaLocation="http://www.springframework.org/schema/integration/feed
http://www.springframework.org/schema/integration/feed/spring-integration-feed.xsd"
----
[[feed-inbound-channel-adapter]]
=== Feed Inbound Channel Adapter
The only adapter that is really needed to provide support for retrieving feeds is an _inbound channel adapter_.
This allows you to subscribe to a particular URL.
Below is an example configuration:
[source,xml]
----
<int-feed:inbound-channel-adapter id="feedAdapter"
channel="feedChannel"
url="http://feeds.bbci.co.uk/news/rss.xml">
<int:poller fixed-rate="10000" max-messages-per-poll="100" />
</int-feed:inbound-channel-adapter>
----
In the above configuration, we are subscribing to a URL identified by the `url` attribute.
As news items are retrieved they will be converted to Messages and sent to a channel identified by the `channel` attribute.
The payload of each message will be a `com.sun.syndication.feed.synd.SyndEntry` instance.
That encapsulates various data about a news item (content, dates, authors, etc.).
You can also see that the _Inbound Feed Channel Adapter_ is a Polling Consumer.
That means you have to provide a poller configuration.
However, one important thing you must understand with regard to Feeds is that its inner-workings are slightly different then most other poling consumers.
When an Inbound Feed adapter is started, it does the first poll and receives a `com.sun.syndication.feed.synd.SyndEntryFeed` instance.
That is an object that contains multiple `SyndEntry` objects.
Each entry is stored in the local entry queue and is released based on the value in the `max-messages-per-poll` attribute such that each Message will contain a single entry.
If during retrieval of the entries from the entry queue the queue had become empty, the adapter will attempt to update the Feed thereby populating the queue with more entries (SyndEntry instances) if available.
Otherwise the next attempt to poll for a feed will be determined by the trigger of the poller (e.g., every 10 seconds in the above configuration).
_Duplicate Entries_
Polling for a Feed might result in entries that have already been processed ("I already read that news item, why are you showing it to me again?").
Spring Integration provides a convenient mechanism to eliminate the need to worry about duplicate entries.
Each feed entry will have a _published date_ field.
Every time a new Message is generated and sent, Spring Integration will store the value of the latest _published date_ in an instance of the `MetadataStore` strategy (<<metadata-store>>).
NOTE: The key used to persist the latest _published date_ is the value of the (required) `id` attribute of the Feed Inbound Channel Adapter component plus the `feedUrl` from the adapter's configuration.

436
src/reference/asciidoc/file.adoc Normal file
View File

@@ -0,0 +1,436 @@
[[files]]
== File Support
[[file-intro]]
=== Introduction
Spring Integration's File support extends the Spring Integration Core with a dedicated vocabulary to deal with reading, writing, and transforming files.
It provides a namespace that enables elements defining Channel Adapters dedicated to files and support for Transformers that can read file contents into strings or byte arrays.
This section will explain the workings of `FileReadingMessageSource` and `FileWritingMessageHandler` and how to configure them as _beans_.
Also the support for dealing with files through file specific implementations of `Transformer` will be discussed.
Finally the file specific namespace will be explained.
[[file-reading]]
=== Reading Files
A `FileReadingMessageSource` can be used to consume files from the filesystem.
This is an implementation of `MessageSource` that creates messages from a file system directory.
[source,xml]
----
<bean id="pollableFileSource"
class="org.springframework.integration.file.FileReadingMessageSource"
p:directory="${input.directory}"/>
----
To prevent creating messages for certain files, you may supply a `FileListFilter`.
By default, an `AcceptOnceFileListFilter` is used.
This filter ensures files are picked up only once from the directory.
[NOTE]
=====
The `AcceptOnceFileListFilter` stores its state in memory.
If you wish the state to survive a system restart, consider using the`FileSystemPersistentAcceptOnceFileListFilter` instead.
This filter stores the accepted file names in a `MetadataStore` implementation (<<metadata-store>>).
This filter matches on the filename and modified time.
Since _version 4.0_, this filter requires a `ConcurrentMetadataStore`.
When used with a shared data store (such as `Redis` with the `RedisMetadataStore`) this allows filter keys to be shared across multiple application instances, or when a network file share is being used by multiple servers.
=====
[source,xml]
----
<bean id="pollableFileSource"
class="org.springframework.integration.file.FileReadingMessageSource"
p:inputDirectory="${input.directory}"
p:filter-ref="customFilterBean"/>
----
A common problem with reading files is that a file may be detected before it is ready.
The default `AcceptOnceFileListFilter` does not prevent this.
In most cases, this can be prevented if the file-writing process renames each file as soon as it is ready for reading.
A filename-pattern or filename-regex filter that accepts only files that are ready (e.g.
based on a known suffix), composed with the default`AcceptOnceFileListFilter` allows for this.
The `CompositeFileListFilter` enables the composition.
[source,xml]
----
<bean id="pollableFileSource"
class="org.springframework.integration.file.FileReadingMessageSource"
p:inputDirectory="${input.directory}"
p:filter-ref="compositeFilter"/>
<bean id="compositeFilter"
class="org.springframework.integration.file.filters.CompositeFileListFilter">
<constructor-arg>
<list>
<bean class="o.s.i.file.filters.AcceptOnceFileListFilter"/>
<bean class="o.s.i.file.filters.RegexPatternFileListFilter">
<constructor-arg value="^test.*$"/>
</bean>
</list>
</constructor-arg>
</bean>
----
The configuration can be simplified using the file specific namespace.
To do this use the following template.
[source,xml]
----
<?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:int="http://www.springframework.org/schema/integration"
xmlns:int-file="http://www.springframework.org/schema/integration/file"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration.xsd
http://www.springframework.org/schema/integration/file
http://www.springframework.org/schema/integration/file/spring-integration-file.xsd">
</beans>
----
Within this namespace you can reduce the FileReadingMessageSource and wrap it in an inbound Channel Adapter like this:
[source,xml]
----
<int-file:inbound-channel-adapter id="filesIn1"
directory="file:${input.directory}" prevent-duplicates="true"/>
<int-file:inbound-channel-adapter id="filesIn2"
directory="file:${input.directory}"
filter="customFilterBean" />
<int-file:inbound-channel-adapter id="filesIn3"
directory="file:${input.directory}"
filename-pattern="test*" />
<int-file:inbound-channel-adapter id="filesIn4"
directory="file:${input.directory}"
filename-regex="test[0-9]+\.txt" />
----
The first channel adapter is relying on the default filter that just prevents duplication, the second is using a custom filter, the third is using the_filename-pattern_ attribute to add an `AntPathMatcher` based filter, and the fourth is using the _filename-regex_ attribute to add a regular expression Pattern based filter to the `FileReadingMessageSource`.
The _filename-pattern_ and _filename-regex_ attributes are each mutually exclusive with the regular _filter_ reference attribute.
However, you can use the _filter_ attribute to reference an instance of `CompositeFileListFilter` that combines any number of filters, including one or more pattern based filters to fit your particular needs.
When multiple processes are reading from the same directory it can be desirable to lock files to prevent them from being picked up concurrently.
To do this you can use a `FileLocker`.
There is a java.nio based implementation available out of the box, but it is also possible to implement your own locking scheme.
The nio locker can be injected as follows
[source,xml]
----
<int-file:inbound-channel-adapter id="filesIn"
directory="file:${input.directory}" prevent-duplicates="true">
<int-file:nio-locker/>
</int-file:inbound-channel-adapter>
----
A custom locker you can configure like this:
[source,xml]
----
<int-file:inbound-channel-adapter id="filesIn"
directory="file:${input.directory}" prevent-duplicates="true">
<int-file:locker ref="customLocker"/>
</int-file:inbound-channel-adapter>
----
NOTE: When a file inbound adapter is configured with a locker, it will take the responsibility to acquire a lock before the file is allowed to be received.
*It will not assume the responsibility to unlock the file.* If you have processed the file and keeping the locks hanging around you have a memory leak.
If this is a problem in your case you should call FileLocker.unlock(File file) yourself at the appropriate time.
When filtering and locking files is not enough it might be needed to control the way files are listed entirely.
To implement this type of requirement you can use an implementation of `DirectoryScanner`.
This scanner allows you to determine entirely what files are listed each poll.
This is also the interface that Spring Integration uses internally to wire FileListFilters FileLocker to the FileReadingMessageSource.
A custom DirectoryScanner can be injected into the <int-file:inbound-channel-adapter/> on the `scanner` attribute.
[source,xml]
----
<int-file:inbound-channel-adapter id="filesIn" directory="file:${input.directory}"
prevent-duplicates="true" scanner="customDirectoryScanner"/>
----
This gives you full freedom to choose the ordering, listing and locking strategies.
IMPORTANT: It is important to understand that filters (including patterns, regex, prevent-duplicates etc) and lockers, are actually used by the scanner.
Any of these attributes set on the adapter are subsequently injected into the scanner.
For this reason, if you need to provide a custom scanner and you have multiple file inbound adapters in the same application context, each adapter must be provided with its own instance of the scanner, either by declaring separate beans, or declaring `scope="prototype"` on the scanner bean so that the context will create a new instance for each use.
[[file-tailing]]
==== 'Tail'ing Files
Another popular use case is to get 'lines' from the end (or tail) of a file, capturing new lines when they are added.
Two implementations are provided; the first, `OSDelegatingFileTailingMessageProducer`, uses the native `tail` command (on operating systems that have one).
This is likely the most efficient implementation on those platforms.
For operating systems that do not have a `tail` command, the second implementation `ApacheCommonsFileTailingMessageProducer` which uses the Apache `commons-io
Tailer` class.
In both cases, file system events, such as files being unavailable etc, are published as `ApplicationEvent` s using the normal Spring event publishing mechanism.
Examples of such events are:
`[message=tail: cannot open `/tmp/foo' for reading:
No such file or directory, file=/tmp/foo]`
`[message=tail: `/tmp/foo' has become accessible, file=/tmp/foo]`
`[message=tail: `/tmp/foo' has become inaccessible:
No such file or directory, file=/tmp/foo]`
`[message=tail: `/tmp/foo' has appeared;
following end of new file, file=/tmp/foo]`
This sequence of events might occur, for example, when a file is rotated.
NOTE: Not all platforms supporting a `tail` command provide these status messages.
Example configurations:
[source,xml]
----
<int-file:tail-inbound-channel-adapter id="native"
channel="input"
task-executor="exec"
file="/tmp/foo"/>
----
This creates a native adapter with default '-F -n 0' options (follow the file name from the current end).
[source,xml]
----
<int-file:tail-inbound-channel-adapter id="native"
channel="input"
native-options="-F -n +0"
task-executor="exec"
file-delay=10000
file="/tmp/foo"/>
----
This creates a native adapter with '-F -n +0' options (follow the file name, emitting all existing lines).
If the tail command fails (on some platforms, a missing file causes the `tail` to fail, even with `-F` specified), the command will be retried every 10 seconds.
[source,xml]
----
<int-file:tail-inbound-channel-adapter id="apache"
channel="input"
task-executor="exec"
file="/tmp/bar"
delay="2000"
end="false"
reopen="true"
file-delay="10000"/>
----
This creates an Apache commons-io `Tailer` adapter that examines the file for new lines every 2 seconds, and checks for existence of a missing file every 10 seconds.
The file will be tailed from the beginning (`end="false"`) instead of the end (which is the default).
The file will be reopened for each chunk (the default is to keep the file open).
IMPORTANT: Specifying the `delay`, `end` or `reopen` attributes, forces the use of the Apache commons-io adapter and the `native-options` attribute is not allowed.
[[file-writing]]
=== Writing files
To write messages to the file system you can use a http://static.springsource.org/spring-integration/api/org/springframework/integration/file/FileWritingMessageHandler.html[FileWritingMessageHandler].
This class can deal with _File_, _String_, or _byte array_ payloads.
You can configure the encoding and the charset that will be used in case of a String payload.
To make things easier, you can configure the `FileWritingMessageHandler` as part of an _Outbound Channel Adapter_ or _Outbound Gateway_ using the provided XML namespace support.
[[file-writing-file-names]]
==== Generating Filenames
In its simplest form, the `FileWritingMessageHandler` only requires a destination directory for writing the files.
The name of the file to be written is determined by the handler'shttp://static.springsource.org/spring-integration/api/org/springframework/integration/file/FileNameGenerator.html[FileNameGenerator].
The http://static.springsource.org/spring-integration/api/org/springframework/integration/file/DefaultFileNameGenerator.html[default implementation] looks for a Message header whose key matches the constant defined as http://static.springsource.org/spring-integration/api/constant-values.html#org.springframework.integration.file.FileHeaders.FILENAME[FileHeaders.FILENAME].
Alternatively, you can specify an expression to be evaluated against the Message in order to generate a file name, e.g.:_headers['myCustomHeader'] + '.foo'_.
The expression must evaluate to a `String`.
For convenience, the `DefaultFileNameGenerator` also provides the _setHeaderName_ method, allowing you to explicitly specify the Message header whose value shall be used as the filename.
Once setup, the `DefaultFileNameGenerator` will employ the following resolution steps to determine the filename for a given Message payload:
. Evaluate the expression against the Message and, if the result is a non-empty `String`, use it as the filename.
. Otherwise, if the payload is a `java.io.File`, use the file's filename.
. Otherwise, use the Message ID appended with .`msg` as the filename.
When using the XML namespace support, both, the _File Oubound Channel Adapter_ and the _File Outbound Gateway_ support the following two mutually exclusive configuration attributes:
* `filename-generator` (a reference to a `FileNameGenerator`) implementation)
* `filename-generator-expression` (an expression evaluating to a `String`)
While writing files, a temporary file suffix will be used (default: `.writing`).
It is appended to the filename while the file is being written.
To customize the suffix, you can set the _temporary-file-suffix_ attribute on both the _File Oubound Channel Adapter_ and the _File Outbound Gateway_.
NOTE: When using the _APPEND_ file _mode_, the _temporary-file-suffix_ attribute is ignored, since the data is appended to the file directly.
[[file-writing-output-directory]]
==== Specifying the Output Directory
Both, the _File Oubound Channel Adapter_ and the _File Outbound Gateway_ provide two configuration attributes for specifying the output directory:
* _directory_
* _directory-expression_
NOTE: The _directory-expression_ attribute is available since Spring Integration 2.2.
*Using the directory attribute*
When using the _directory_ attribute, the output directory will be set to a fixed value, that is set at intialization time of the `FileWritingMessageHandler`.
If you don't specify this attribute, then you must use the_directory-expression_ attribute.
*Using the directory-expression attribute*
If you want to have full SpEL support you would choose the _directory-expression_ attribute.
This attribute accepts a SpEL expression that is evaluated for each message being processed.
Thus, you have full access to a Message's payload and its headers to dynamically specify the output file directory.
The SpEL expression must resolve to either a `String` or to `java.io.File`.
Furthermore the resulting `String` or `File` must point to a directory.
If you don't specify the_directory-expression_ attribute, then you must set the _directory_ attribute.
*Using the auto-create-directory attribute*
If the destination directory does not exists, yet, by default the respective destination directory and any non-existing parent directories are being created automatically.
You can set the _auto-create-directory_ attribute to _false_ in order to prevent that.
This attribute applies to both, the _directory_ and the _directory-expression_ attribute.
[NOTE]
=====
When using the _directory_ attribute and _auto-create-directory_ is `false`, the following change was made starting with Spring Integration 2.2:
Instead of checking for the existence of the destination directory at initialization time of the adapter, this check is now performed for each message being processed.
Furthermore, if _auto-create-directory_ is `true` and the directory was deleted between the processing of messages, the directory will be re-created for each message being processed.
=====
[[file-writing-destination-exists]]
==== Dealing with Existing Destination Files
When writing files and the destination file already exists, the default behavior is to overwrite that target file.
This behavior, though, can be changed by setting the _mode_ attribute on the respective File Outbound components.
The following options exist:
* REPLACE (Default)
* APPEND
* FAIL
* IGNORE
NOTE: The _mode_ attribute and the options _APPEND_, _FAIL_ and _IGNORE_, are available since _Spring Integration 2.2_.
_REPLACE_
If the target file already exists, it will be overwritten.
If the _mode_ attribute is not specified, then this is the default behavior when writing files.
_APPEND_
This mode allows you to append Message content to the existing file instead of creating a new file each time.
Note that this attribute is mutually exclusive with _temporary-file-suffix_ attribute since when appending content to the existing file, the adapter no longer uses a temporary file.
_FAIL_
If the target file exists, a http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/messaging/MessageHandlingException.html[MessageHandlingException] is thrown.
_IGNORE_
If the target file exists, the message payload is silently ignored.
NOTE: When using a temporary file suffix (default: `.writing`), the _IGNORE_ mode will apply if the final file name exists, or the temporary file name exists.
[[file-outbound-channel-adapter]]
==== File Outbound Channel Adapter
[source,xml]
----
<int-file:outbound-channel-adapter id="filesOut" directory="${input.directory.property}"/>
----
The namespace based configuration also supports a `delete-source-files` attribute.
If set to `true`, it will trigger the deletion of the original source files after writing to a destination.
The default value for that flag is `false`.
[source,xml]
----
<int-file:outbound-channel-adapter id="filesOut"
directory="${output.directory}"
delete-source-files="true"/>
----
NOTE: The `delete-source-files` attribute will only have an effect if the inbound Message has a File payload or if the `FileHeaders.ORIGINAL_FILE` header value contains either the source File instance or a String representing the original file path.
Starting with _version 4.2_ The `FileWritingMessageHandler` supports an `append-new-line` option.
If set to `true`, a new line is appended to the file after a message is written.
The default attribute value is `false`.
[source,xml]
----
<int-file:outbound-channel-adapter id="newlineAdapter"
append-new-line="true"
directory="${output.directory}"/>
----
[[file-writing-output-gateway]]
==== Outbound Gateway
In cases where you want to continue processing messages based on the written file, you can use the `outbound-gateway` instead.
It plays a very similar role as the `outbound-channel-adapter`.
However, after writing the file, it will also send it to the reply channel as the payload of a Message.
[source,xml]
----
<int-file:outbound-gateway id="mover" request-channel="moveInput"
reply-channel="output"
directory="${output.directory}"
mode="REPLACE" delete-source-files="true"/>
----
As mentioned earlier, you can also specify the _mode_ attribute, which defines the behavior of how to deal with situations where the destination file already exists.
Please see<<file-writing-destination-exists>> for further details.
Generally, when using the_File Outbound Gateway_, the result file is returned as the Message payload on the reply channel.
This also applies when specifying the _IGNORE_ mode.
In that case the pre-existing destination file is returned.
If the payload of the request message was a file, you still have access to that original file through the Message Header http://static.springsource.org/spring-integration/api/org/springframework/integration/file/FileHeaders.html[FileHeaders.ORIGINAL_FILE].
NOTE: The 'outbound-gateway' works well in cases where you want to first move a file and then send it through a processing pipeline.
In such cases, you may connect the file namespace's 'inbound-channel-adapter' element to the 'outbound-gateway' and then connect that gateway's reply-channel to the beginning of the pipeline.
If you have more elaborate requirements or need to support additional payload types as input to be converted to file content you could extend the FileWritingMessageHandler, but a much better option is to rely on a `Transformer`.
[[file-transforming]]
=== File Transformers
To transform data read from the file system to objects and the other way around you need to do some work.
Contrary to `FileReadingMessageSource` and to a lesser extent `FileWritingMessageHandler`, it is very likely that you will need your own mechanism to get the job done.
For this you can implement the`Transformer` interface.
Or extend the `AbstractFilePayloadTransformer` for inbound messages.
Some obvious implementations have been provided.
`FileToByteArrayTransformer` transforms Files into byte[]s using Spring's `FileCopyUtils`.
It is often better to use a sequence of transformers than to put all transformations in a single class.
In that case the File to byte[] conversion might be a logical first step.
`FileToStringTransformer` will convert Files to Strings as the name suggests.
If nothing else, this can be useful for debugging (consider using with a Wire Tap).
To configure File specific transformers you can use the appropriate elements from the file namespace.
[source,xml]
----
<int-file:file-to-bytes-transformer input-channel="input" output-channel="output"
delete-files="true"/>
<int-file:file-to-string-transformer input-channel="input" output-channel="output"
delete-files="true" charset="UTF-8"/>
----
The _delete-files_ option signals to the transformer that it should delete the inbound File after the transformation is complete.
This is in no way a replacement for using the`AcceptOnceFileListFilter` when the FileReadingMessageSource is being used in a multi-threaded environment (e.g.
Spring Integration in general).

163
src/reference/asciidoc/filter.adoc Normal file
View File

@@ -0,0 +1,163 @@
[[filter]]
=== Filter
[[filter-introduction]]
==== Introduction
Message Filters are used to decide whether a Message should be passed along or dropped based on some criteria such as a Message Header value or Message content itself.
Therefore, a Message Filter is similar to a router, except that for each Message received from the filter's input channel, that same Message may or may not be sent to the filter's output channel.
Unlike the router, it makes no decision regarding_which_ Message Channel to send the Message to but only decides _whether_ to send.
NOTE: As you will see momentarily, the Filter also supports a discard channel, so in certain cases it _can_ play the role of a very simple router (or "switch") based on a boolean condition.
In Spring Integration, a Message Filter may be configured as a Message Endpoint that delegates to an implementation of the `MessageSelector` interface.
That interface is itself quite simple:
[source,java]
----
public interface MessageSelector {
boolean accept(Message<?> message);
}
----
The `MessageFilter` constructor accepts a selector instance:
[source,java]
----
MessageFilter filter = new MessageFilter(someSelector);
----
In combination with the namespace and SpEL, very powerful filters can be configured with very little java code.
[[filter-config]]
==== Configuring Filter
[[filter-xml]]
===== Configuring a Filter with XML
The <filter> element is used to create a Message-selecting endpoint.
In addition to "`input-channel` and `output-channel` attributes, it requires a `ref`.
The `ref` may point to a `MessageSelector` implementation:
[source,xml]
----
<int:filter input-channel="input" ref="selector" output-channel="output"/>
<bean id="selector" class="example.MessageSelectorImpl"/>
----
Alternatively, the `method` attribute can be added at which point the `ref` may refer to any object.
The referenced method may expect either the `Message` type or the payload type of inbound Messages.
The method must return a boolean value.
If the method returns 'true', the Message _will_ be sent to the output-channel.
[source,xml]
----
<int:filter input-channel="input" output-channel="output"
ref="exampleObject" method="someBooleanReturningMethod"/>
<bean id="exampleObject" class="example.SomeObject"/>
----
If the selector or adapted POJO method returns `false`, there are a few settings that control the handling of the rejected Message.
By default (if configured like the example above), rejected Messages will be silently dropped.
If rejection should instead result in an error condition, then set the `throw-exception-on-rejection` attribute to `true`:
[source,xml]
----
<int:filter input-channel="input" ref="selector"
output-channel="output" throw-exception-on-rejection="true"/>
----
If you want rejected messages to be routed to a specific channel, provide that reference as the `discard-channel`:
[source,xml]
----
<int:filter input-channel="input" ref="selector"
output-channel="output" discard-channel="rejectedMessages"/>
----
NOTE: Message Filters are commonly used in conjunction with a Publish Subscribe Channel.
Many filter endpoints may be subscribed to the same channel, and they decide whether or not to pass the Message to the next endpoint which could be any of the supported types (e.g.
Service Activator).
This provides a _reactive_ alternative to the more _proactive_ approach of using a Message Router with a single Point-to-Point input channel and multiple output channels.
Using a `ref` attribute is generally recommended if the custom filter implementation is referenced in other `<filter>` definitions.
However if the custom filter implementation is scoped to a single `<filter>` element, provide an inner bean definition:
[source,xml]
----
<int:filter method="someMethod" input-channel="inChannel" output-channel="outChannel">
<beans:bean class="org.foo.MyCustomFilter"/>
</filter>
----
NOTE: Using both the `ref` attribute and an inner handler definition in the same `<filter>` configuration is not allowed, as it creates an ambiguous condition, and an Exception will be thrown.
With the introduction of SpEL support, Spring Integration added the `expression` attribute to the filter element.
It can be used to avoid Java entirely for simple filters.
[source,xml]
----
<int:filter input-channel="input" expression="payload.equals('nonsense')"/>
----
The string passed as the expression attribute will be evaluated as a SpEL expression with the Message available in the evaluation context.
If it is necessary to include the result of an expression in the scope of the application context you can use the #{} notation as defined in thehttp://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html#expressions-beandef[SpEL reference documentation].
[source,xml]
----
<int:filter input-channel="input"
expression="payload.matches(#{filterPatterns.nonsensePattern})"/>
----
If the Expression itself needs to be dynamic, then an 'expression' sub-element may be used.
That provides a level of indirection for resolving the Expression by its key from an ExpressionSource.
That is a strategy interface that you can implement directly, or you can rely upon a version available in Spring Integration that loads Expressions from a "resource bundle" and can check for modifications after a given number of seconds.
All of this is demonstrated in the following configuration sample where the Expression could be reloaded within one minute if the underlying file had been modified.
If the ExpressionSource bean is named "expressionSource", then it is not necessary to provide the` source` attribute on the <expression> element, but in this case it's shown for completeness.
[source,xml]
----
<int:filter input-channel="input" output-channel="output">
<int:expression key="filterPatterns.example" source="myExpressions"/>
</int:filter>
<beans:bean id="myExpressions" id="myExpressions"
class="o.s.i.expression.ReloadableResourceBundleExpressionSource">
<beans:property name="basename" value="config/integration/expressions"/>
<beans:property name="cacheSeconds" value="60"/>
</beans:bean>
----
Then, the 'config/integration/expressions.properties' file (or any more specific version with a locale extension to be resolved in the typical way that resource-bundles are loaded) would contain a key/value pair:
[source,xml]
----
filterPatterns.example=payload > 100
----
NOTE: All of these examples that use `expression` as an attribute or sub-element can also be applied within transformer, router, splitter, service-activator, and header-enricher elements.
Of course, the semantics/role of the given component type would affect the interpretation of the evaluation result in the same way that the return value of a method-invocation would be interpreted.
For example, an expression can return Strings that are to be treated as Message Channel names by a router component.
However, the underlying functionality of evaluating the expression against the Message as the root object, and resolving bean names if prefixed with '@' is consistent across all of the core EIP components within Spring Integration.
[[filter-annotations]]
===== Configuring a Filter with Annotations
A filter configured using annotations would look like this.
[source,java]
----
public class PetFilter {
...
@Filter <1>
public boolean dogsOnly(String input) {
...
}
}
----
<1> An annotation indicating that this method shall be used as a filter.
Must be specified if this class will be used as a filter.
All of the configuration options provided by the xml element are also available for the `@Filter` annotation.
The filter can be either referenced explicitly from XML or, if the `@MessageEndpoint` annotation is defined on the class, detected automatically through classpath scanning.
Also see <<advising-with-annotations>>.

480
src/reference/asciidoc/ftp.adoc Normal file
View File

@@ -0,0 +1,480 @@
[[ftp]]
== FTP/FTPS Adapters
Spring Integration provides support for file transfer operations via FTP and FTPS.
[[ftp-intro]]
=== Introduction
The File Transfer Protocol (FTP) is a simple network protocol which allows you to transfer files between two computers on the Internet.
There are two actors when it comes to FTP communication: _client_ and _server_.
To transfer files with FTP/FTPS, you use a _client_ which initiates a connection to a remote computer that is running an FTP _server_.
After the connection is established, the _client_ can choose to send and/or receive copies of files.
Spring Integration supports sending and receiving files over FTP/FTPS by providing three _client_ side endpoints: _Inbound Channel Adapter_, _Outbound Channel Adapter_, and _Outbound Gateway_.
It also provides convenient namespace-based configuration options for defining these _client_ components.
To use the _FTP_ namespace, add the following to the header of your XML file:
[source,xml]
----
xmlns:int-ftp="http://www.springframework.org/schema/integration/ftp"
xsi:schemaLocation="http://www.springframework.org/schema/integration/ftp
http://www.springframework.org/schema/integration/ftp/spring-integration-ftp.xsd"
----
[[ftp-session-factory]]
=== FTP Session Factory
IMPORTANT: Starting with version 3.0, sessions are no longer cached by default.
See <<ftp-session-caching>>.
Before configuring FTP adapters you must configure an _FTP Session Factory_.
You can configure the _FTP Session Factory_ with a regular bean definition where the implementation class is `org.springframework.integration.ftp.session.DefaultFtpSessionFactory`: Below is a basic configuration:
[source,xml]
----
<bean id="ftpClientFactory"
class="org.springframework.integration.ftp.session.DefaultFtpSessionFactory">
<property name="host" value="localhost"/>
<property name="port" value="22"/>
<property name="username" value="kermit"/>
<property name="password" value="frog"/>
<property name="clientMode" value="0"/>
<property name="fileType" value="2"/>
<property name="bufferSize" value="100000"/>
</bean>
----
For FTPS connections all you need to do is use `org.springframework.integration.ftp.session.DefaultFtpsSessionFactory` instead.
Below is the complete configuration sample:
[source,xml]
----
<bean id="ftpClientFactory"
class="org.springframework.integration.ftp.client.DefaultFtpsClientFactory">
<property name="host" value="localhost"/>
<property name="port" value="22"/>
<property name="username" value="oleg"/>
<property name="password" value="password"/>
<property name="clientMode" value="1"/>
<property name="fileType" value="2"/>
<property name="useClientMode" value="true"/>
<property name="cipherSuites" value="a,b.c"/>
<property name="keyManager" ref="keyManager"/>
<property name="protocol" value="SSL"/>
<property name="trustManager" ref="trustManager"/>
<property name="prot" value="P"/>
<property name="needClientAuth" value="true"/>
<property name="authValue" value="oleg"/>
<property name="sessionCreation" value="true"/>
<property name="protocols" value="SSL, TLS"/>
<property name="implicit" value="true"/>
</bean>
----
Every time an adapter requests a session object from its `SessionFactory` the session is returned from a session pool maintained by a caching wrapper around the factory.
A Session in the session pool might go stale (if it has been disconnected by the server due to inactivity) so the `SessionFactory` will perform validation to make sure that it never returns a stale session to the adapter.
If a stale session was encountered, it will be removed from the pool, and a new one will be created.
NOTE: If you experience connectivity problems and would like to trace Session creation as well as see which Sessions are polled you may enable it by setting the logger to TRACE level (e.g., log4j.category.org.springframework.integration.file=TRACE)
Now all you need to do is inject these session factories into your adapters.
Obviously the protocol (FTP or FTPS) that an adapter will use depends on the type of session factory that has been injected into the adapter.
NOTE: A more practical way to provide values for _FTP/FTPS Session Factories_ is by using Spring's property placeholder support (See: http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-factory-placeholderconfigurer).
*Advanced Configuration*
`DefaultFtpSessionFactory` provides an abstraction over the underlying client API which, since _Spring Integration 2.0_, is http://commons.apache.org/net/[Apache Commons Net].
This spares you from the low level configuration details of the `org.apache.commons.net.ftp.FTPClient`.
Several common properties are exposed on the session factory (since _version 4.0_, this now includes `connectTimeout`, `defaultTimeout` and `dataTimeout`).
However there are times when access to lower level `FTPClient` configuration is necessary to achieve more advanced configuration (e.g., setting the port range for active mode etc.).
For that purpose, `AbstractFtpSessionFactory` (the base class for all FTP Session Factories) exposes hooks, in the form of the two post-processing methods below.
[source,java]
----
/**
* Will handle additional initialization after client.connect() method was invoked,
* but before any action on the client has been taken
*/
protected void postProcessClientAfterConnect(T t) throws IOException {
// NOOP
}
/**
* Will handle additional initialization before client.connect() method was invoked.
*/
protected void postProcessClientBeforeConnect(T client) throws IOException {
// NOOP
}
----
As you can see, there is no default implementation for these two methods.
However, by extending `DefaultFtpSessionFactory` you can override these methods to provide more advanced configuration of the `FTPClient`.
For example:
[source,java]
----
public class AdvancedFtpSessionFactory extends DefaultFtpSessionFactory {
protected void postProcessClientBeforeConnect(FTPClient ftpClient) throws IOException {
ftpClient.setActivePortRange(4000, 5000);
}
}
----
[[ftp-inbound]]
=== FTP Inbound Channel Adapter
The _FTP Inbound Channel Adapter_ is a special listener that will connect to the FTP server and will listen for the remote directory events (e.g., new file created) at which point it will initiate a file transfer.
[source,xml]
----
<int-ftp:inbound-channel-adapter id="ftpInbound"
channel="ftpChannel"
session-factory="ftpSessionFactory"
charset="UTF-8"
auto-create-local-directory="true"
delete-remote-files="true"
filename-pattern="*.txt"
remote-directory="some/remote/path"
remote-file-separator="/"
preserve-timestamp="true"
local-filename-generator-expression="#this.toUpperCase() + '.a'"
local-filter="myFilter"
temporary-file-suffix=".writing"
local-directory=".">
<int:poller fixed-rate="1000"/>
</int-ftp:inbound-channel-adapter>
----
As you can see from the configuration above you can configure an _FTP Inbound Channel Adapter_ via the `inbound-channel-adapter` element while also providing values for various attributes such as `local-directory`, `filename-pattern` (which is based on simple pattern matching, not regular expressions), and of course the reference to a `session-factory`.
By default the transferred file will carry the same name as the original file.
If you want to override this behavior you can set the `local-filename-generator-expression` attribute which allows you to provide a SpEL Expression to generate the name of the local file.
Unlike outbound gateways and adapters where the root object of the SpEL Evaluation Context is a `Message`, this inbound adapter does not yet have the Message at the time of evaluation since that's what it ultimately generates with the transferred file as its payload.
So, the root object of the SpEL Evaluation Context is the original name of the remote file (String).
Starting with _Spring Integration 3.0_, you can specify the `preserve-timestamp` attribute (default `false`); when `true`, the local file's modified timestamp will be set to the value retrieved from the server; otherwise it will be set to the current time.
Sometimes file filtering based on the simple pattern specified via `filename-pattern` attribute might not be sufficient.
If this is the case, you can use the `filename-regex` attribute to specify a Regular Expression (e.g.
`filename-regex=".*\.test$"`).
And of course if you need complete control you can use `filter` attribute and provide a reference to any custom implementation of the `org.springframework.integration.file.filters.FileListFilter`, a strategy interface for filtering a list of files.
This filter determines which remote files are retrieved.
You can also combine a pattern based filter with other filters, such as an `AcceptOnceFileListFilter` to avoid synchronizing files that have previously been fetched, by using a `CompositeFileListFilter`.
The `AcceptOnceFileListFilter` stores its state in memory.
If you wish the state to survive a system restart, consider using the`FtpPersistentAcceptOnceFileListFilter` instead.
This filter stores the accepted file names in an instance of the`MetadataStore` strategy (<<metadata-store>>).
This filter matches on the filename and the remote modified time.
Since _version 4.0_, this filter requires a `ConcurrentMetadataStore`.
When used with a shared data store (such as `Redis` with the `RedisMetadataStore`) this allows filter keys to be shared across multiple application or server instances.
The above discussion refers to filtering the files before retrieving them.
Once the files have been retrieved, an additional filter is applied to the files on the file system.
By default, this is an`AcceptOnceFileListFilter` which, as discussed, retains state in memory and does not consider the file's modified time.
Unless your application removes files after processing, the adapter will re-process the files on disk by default after an application restart.
Also, if you configure the `filter` to use a `FtpPersistentAcceptOnceFileListFilter`, and the remote file timestamp changes (causing it to be re-fetched), the default local filter will not allow this new file to be processed.
Use the `local-filter` attribute to configure the behavior of the local file system filter.
To solve these particular use cases, you can use a`FileSystemPersistentAcceptOnceFileListFilter` as a local filter instead.
This filter also stores the accepted file names and modified timestamp in an instance of the`MetadataStore` strategy (<<metadata-store>>), and will detect the change in the local file modified time.
IMPORTANT: Further, if you use a distributed `MetadataStore` (such as <<redis-metadata-store>> or <<gemfire-metadata-store>>) you can have multiple instances of the same adapter/application and be sure that one and only one will process a file.
The actual local filter is a `CompositeFileListFilter` containing the supplied filter and a pattern filter that prevents processing files that are in the process of being downloaded (based on the `temporary-file-suffix`); files are downloaded with this suffix (default: `.writing`) and the file is renamed to its final name when the transfer is complete, making it 'visible' to the filter.
The `remote-file-separator` attribute allows you to configure a file separator character to use if the default '/' is not applicable for your particular environment.
Please refer to the schema for more details on these attributes.
It is also important to understand that the _FTP Inbound Channel Adapter_ is a _Polling Consumer_ and therefore you must configure a poller (either via a global default or a local sub-element).
Once a file has been transferred, a Message with a `java.io.File` as its payload will be generated and sent to the channel identified by the `channel` attribute.
_More on File Filtering and Large Files_
Sometimes the file that just appeared in the monitored (remote) directory is not complete.
Typically such a file will be written with temporary extension (e.g., foo.txt.writing) and then renamed after the writing process finished.
As a user in most cases you are only interested in files that are complete and would like to filter only files that are complete.
To handle these scenarios you can use the filtering support provided by the `filename-pattern`, `filename-regex` and `filter` attributes.
Here is an example that uses a custom Filter implementation.
[source,xml]
----
<int-ftp:inbound-channel-adapter
channel="ftpChannel"
session-factory="ftpSessionFactory"
filter="customFilter"
local-directory="file:/my_transfers">
remote-directory="some/remote/path"
<int:poller fixed-rate="1000"/>
</int-ftp:inbound-channel-adapter>
<bean id="customFilter" class="org.example.CustomFilter"/>
----
_Poller configuration notes for the inbound FTP adapter_
The job of the inbound FTP adapter consists of two tasks: _1) Communicate with a remote server in order to transfer files from a remote directory to a local directory.__2) For each transferred file, generate a Message with that file as a payload and send it to the channel identified by the 'channel' attribute._ That is why they are called 'channel-adapters' rather than just 'adapters'.
The main job of such an adapter is to generate a Message to be sent to a Message Channel.
Essentially, the second task mentioned above takes precedence in such a way that *IF* your local directory already has one or more files it will first generate Messages from those, and *ONLY* when all local files have been processed, will it initiate the remote communication to retrieve more files.
Also, when configuring a trigger on the poller you should pay close attention to the `max-messages-per-poll` attribute.
Its default value is 1 for all `SourcePollingChannelAdapter` instances (including FTP).
This means that as soon as one file is processed, it will wait for the next execution time as determined by your trigger configuration.
If you happened to have one or more files sitting in the `local-directory`, it would process those files before it would initiate communication with the remote FTP server.
And, if the `max-messages-per-poll` were set to 1 (default), then it would be processing only one file at a time with intervals as defined by your trigger, essentially working as _one-poll = one-file_.
For typical file-transfer use cases, you most likely want the opposite behavior: to process all the files you can for each poll and only then wait for the next poll.
If that is the case, set `max-messages-per-poll` to -1.
Then, on each poll, the adapter will attempt to generate as many Messages as it possibly can.
In other words, it will process everything in the local directory, and then it will connect to the remote directory to transfer everything that is available there to be processed locally.
Only then is the poll operation considered complete, and the poller will wait for the next execution time.
You can alternatively set the 'max-messages-per-poll' value to a positive value indicating the upward limit of Messages to be created from files with each poll.
For example, a value of 10 means that on each poll it will attempt to process no more than 10 files.
[[ftp-outbound]]
=== FTP Outbound Channel Adapter
The _FTP Outbound Channel Adapter_ relies upon a `MessageHandler` implementation that will connect to the FTP server and initiate an FTP transfer for every file it receives in the payload of incoming Messages.
It also supports several representations of the _File_ so you are not limited only to java.io.File typed payloads.
The _FTP Outbound Channel Adapter_ supports the following payloads: 1) `java.io.File` - the actual file object; 2) `byte[]` - a byte array that represents the file contents; and 3) `java.lang.String` - text that represents the file contents.
[source,xml]
----
<int-ftp:outbound-channel-adapter id="ftpOutbound"
channel="ftpChannel"
session-factory="ftpSessionFactory"
charset="UTF-8"
remote-file-separator="/"
auto-create-directory="true"
remote-directory-expression="headers.['remote_dir']"
temporary-remote-directory-expression="headers.['temp_remote_dir']"
filename-generator="fileNameGenerator"
use-temporary-filename="true"
mode="REPLACE"/>
----
As you can see from the configuration above you can configure an _FTP Outbound Channel Adapter_ via the `outbound-channel-adapter` element while also providing values for various attributes such as `filename-generator` (an implementation of the `org.springframework.integration.file.FileNameGenerator` strategy interface), a reference to a `session-factory`, as well as other attributes.
You can also see some examples of `*expression` attributes which allow you to use SpEL to configure things like `remote-directory-expression`, `temporary-remote-directory-expression` and `remote-filename-generator-expression` (a SpEL alternative to `filename-generator` shown above).
As with any component that allows the usage of SpEL, access to Payload and Message Headers is available via 'payload' and 'headers' variables.
Please refer to the schema for more details on the available attributes.
NOTE: By default Spring Integration will use `o.s.i.file.DefaultFileNameGenerator` if none is specified.
`DefaultFileNameGenerator` will determine the file name based on the value of the `file_name` header (if it exists) in the MessageHeaders, or if the payload of the Message is already a `java.io.File`, then it will use the original name of that file.
IMPORTANT: Defining certain values (e.g., remote-directory) might be platform/ftp server dependent.
For example as it was reported on this forum http://forum.springsource.org/showthread.php?p=333478&posted=1#post333478 on some platforms you must add slash to the end of the directory definition (e.g., remote-directory="/foo/bar/" instead of remote-directory="/foo/bar")
Starting with _version 4.1_, you can specify the `mode` when transferring the file.
By default, an existing file will be overwritten; the modes are defined on `enum` `FileExistsMode`, having values `REPLACE` (default), `APPEND`, `IGNORE`, and `FAIL`.
With `IGNORE` and `FAIL`, the file is not transferred; `FAIL` causes an exception to be thrown whereas `IGNORE` silently ignores the transfer (although a `DEBUG` log entry is produced).
_Avoiding Partially Written Files_
One of the common problems, when dealing with file transfers, is the possibility of processing a _partial file_ - a file might appear in the file system before its transfer is actually complete.
To deal with this issue, Spring Integration FTP adapters use a very common algorithm where files are transferred under a temporary name and then renamed once they are fully transferred.
By default, every file that is in the process of being transferred will appear in the file system with an additional suffix which, by default, is `.writing`; this can be changed using the `temporary-file-suffix` attribute.
However, there may be situations where you don't want to use this technique (for example, if the server does not permit renaming files).
For situations like this, you can disable this feature by setting `use-temporary-file-name` to `false` (default is `true`).
When this attribute is `false`, the file is written with its final name and the consuming application will need some other mechanism to detect that the file is completely uploaded before accessing it.
[[ftp-outbound-gateway]]
=== FTP Outbound Gateway
The _FTP Outbound Gateway_ provides a limited set of commands to interact with a remote FTP/FTPS server.
Commands supported are:
* ls (list files)
* get (retrieve file)
* mget (retrieve file(s))
* rm (remove file(s))
* mv (move/rename file)
* put (send file)
* mput (send multiple files)
*ls*
ls lists remote file(s) and supports the following options:
* -1 - just retrieve a list of filenames, default is to retrieve a list of `FileInfo` objects.
* -a - include all files (including those starting with '.')
* -f - do not sort the list
* -dirs - include directories (excluded by default)
* -links - include symbolic links (excluded by default)
* -R - list the remote directory recursively
In addition, filename filtering is provided, in the same manner as the `inbound-channel-adapter`.
The message payload resulting from an _ls_ operation is a list of file names, or a list of `FileInfo` objects.
These objects provide information such as modified time, permissions etc.
The remote directory that the _ls_ command acted on is provided in the `file_remoteDirectory` header.
When using the recursive option (`-R`), the `fileName` includes any subdirectory elements, representing a relative path to the file (relative to the remote directory).
If the `-dirs` option is included, each recursive directory is also returned as an element in the list.
In this case, it is recommended that the `-1` is not used because you would not be able to determine files Vs.
directories, which is achievable using the `FileInfo` objects.
*get*
_get_ retrieves a remote file and supports the following option:
* -P - preserve the timestamp of the remote file
The message payload resulting from a _get_ operation is a `File` object representing the retrieved file.
The remote directory is provided in the `file_remoteDirectory` header, and the filename is provided in the `file_remoteFile` header.
*mget*
_mget_ retrieves multiple remote files based on a pattern and supports the following option:
* -P - preserve the timestamps of the remote files
* -x - Throw an exception if no files match the pattern (otherwise an empty list is returned)
The message payload resulting from an _mget_ operation is a `List<File>` object - a List of File objects, each representing a retrieved file.
The remote directory is provided in the `file_remoteDirectory` header, and the pattern for the filenames is provided in the `file_remoteFile` header.
[NOTE]
.Notes for when using recursion (`-R`)
=====
The pattern is ignored, and `*` is assumed.
By default, the entire remote tree is retrieved.
However, files in the tree can be filtered, by providing a`FileListFilter`; directories in the tree can also be filtered this way.
A `FileListFilter` can be provided by reference or by `filename-pattern` or `filename-regex` attributes.
For example, `filename-regex="(subDir|.*1.txt)"` will retrieve all files ending with `1.txt` in the remote directory and the subdirectory `subDir`.
If a subdirectory is filtered, no additional traversal of that subdirectory is performed.
The `-dirs` option is not allowed (the recursive mget uses the recursive `ls` to obtain the directory tree and the directories themselves cannot be included in the list).
Typically, you would use the `#remoteDirectory` variable in the `local-directory-expression` so that the remote directory structure is retained locally.
=====
*put*
_put_ sends a file to the remote server; the payload of the message can be a `java.io.File`, a `byte[]` or a `String`.
A `remote-filename-generator` (or expression) is used to name the remote file.
Other available attributes include `remote-directory`, `temporary-remote-directory` (and their `*-expression`) equivalents, `use-temporary-file-name`, and `auto-create-directory`.
Refer to the schema documentation for more information.
The message payload resulting from a _put_ operation is a `String` representing the full path of the file on the server after transfer.
*mput*
_mput_ sends multiple files to the server and supports the following option:
* -R - Recursive - send all files (possibly filtered) in the directory and subdirectories
The message payload must be a `java.io.File` representing a local directory.
The same attributes as the `put` command are supported.
In addition, files in the local directory can be filtered with one of `mput-pattern`, `mput-regex` or `mput-filter`.
The filter works with recursion, as long as the subdirectories themselves pass the filter.
Subdirectories that do not pass the filter are not recursed.
The message payload resulting from an _mget_ operation is a `List<String>` object - a List of remote file paths resulting from the transfer.
*rm*
The _rm_ command has no options.
The message payload resulting from an _rm_ operation is Boolean.TRUE if the remove was successful, Boolean.FALSE otherwise.
The remote directory is provided in the `file_remoteDirectory` header, and the filename is provided in the `file_remoteFile` header.
*mv*
The _mv_ command has no options.
The _expression_ attribute defines the "from" path and the _rename-expression_ attribute defines the "to" path.
By default, the _rename-expression_ is `headers['file_renameTo']`.
This expression must not evaluate to null, or an empty `String`.
If necessary, any remote directories needed will be created.
The payload of the result message is `Boolean.TRUE`.
The original remote directory is provided in the `file_remoteDirectory` header, and the filename is provided in the `file_remoteFile` header.
The new path is in the `file_renameTo` header.
*Additional Information*
The _get_ and _mget_ commands support the _local-filename-generator-expression_ attribute.
It defines a SpEL expression to generate the name of local file(s) during the transfer.
The root object of the evaluation context is the request Message but, in addition, the `remoteFileName` variable is also available, which is particularly useful for _mget_, for example: `local-filename-generator-expression="#remoteFileName.toUpperCase() + headers.foo"`.
The _get_ and _mget_ commands support the _local-directory-expression_ attribute.
It defines a SpEL expression to generate the name of local directory(ies) during the transfer.
The root object of the evaluation context is the request Message but, in addition, the `remoteDirectory` variable is also available, which is particularly useful for _mget_, for example: `local-directory-expression="'/tmp/local/' + #remoteDirectory.toUpperCase() + headers.foo"`.
This attribute is mutually exclusive with _local-directory_ attribute.
For all commands, the PATH that the command acts on is provided by the 'expression' property of the gateway.
For the mget command, the expression might evaluate to '*', meaning retrieve all files, or 'somedirectory/*' etc.
Here is an example of a gateway configured for an ls command...
[source,xml]
----
<int-ftp:outbound-gateway id="gateway1"
session-factory="ftpSessionFactory"
request-channel="inbound1"
command="ls"
command-options="-1"
expression="payload"
reply-channel="toSplitter"/>
----
The payload of the message sent to the toSplitter channel is a list of String objects containing the filename of each file.
If the `command-options` was omitted, it would be a list of `FileInfo` objects.
Options are provided space-delimited, e.g.
`command-options="-1 -dirs -links"`.
[[ftp-session-caching]]
=== FTP Session Caching
IMPORTANT: Starting with _Spring Integration version 3.0_, sessions are no longer cached by default; the `cache-sessions` attribute is no longer supported on endpoints.
You must use a `CachingSessionFactory` (see below) if you wish to cache sessions.
In versions prior to 3.0, the sessions were cached automatically by default.
A `cache-sessions` attribute was available for disabling the auto caching, but that solution did not provide a way to configure other session caching attributes.
For example, you could not limit on the number of sessions created.
To support that requirement and other configuration options, a `CachingSessionFactory` was provided.
It provides `sessionCacheSize` and `sessionWaitTimeout` properties.
As its name suggests, the `sessionCacheSize` property controls how many active sessions the factory will maintain in its cache (the DEFAULT is unbounded).
If the `sessionCacheSize` threshold has been reached, any attempt to acquire another session will block until either one of the cached sessions becomes available or until the wait time for a Session expires (the DEFAULT wait time is Integer.MAX_VALUE).
The `sessionWaitTimeout` property enables configuration of that value.
If you want your Sessions to be cached, simply configure your default Session Factory as described above and then wrap it in an instance of `CachingSessionFactory` where you may provide those additional properties.
[source,xml]
----
<bean id="ftpSessionFactory" class="o.s.i.ftp.session.DefaultFtpSessionFactory">
<property name="host" value="localhost"/>
</bean>
<bean id="cachingSessionFactory" class="o.s.i.file.remote.session.CachingSessionFactory">
<constructor-arg ref="ftpSessionFactory"/>
<constructor-arg value="10"/>
<property name="sessionWaitTimeout" value="1000"/>
</bean>
----
In the above example you see a `CachingSessionFactory` created with the `sessionCacheSize` set to 10 and the `sessionWaitTimeout` set to 1 second (its value is in millliseconds).
Starting with _Spring Integration version 3.0_, the `CachingConnectionFactory` provides a `resetCache()` method.
When invoked, all idle sessions are immediately closed and in-use sessions are closed when they are returned to the cache.
New requests for sessions will establish new sessions as necessary.
[[ftp-rft]]
=== RemoteFileTemplate
Starting with _Spring Integration version 3.0_ a new abstraction is provided over the `FtpSession` object.
The template provides methods to send, retrieve (as an `InputStream`), remove, and rename files.
In addition an `execute` method is provided allowing the caller to execute multiple operations on the session.
In all cases, the template takes care of reliably closing the session.
For more information, refer to the http://docs.spring.io/spring-integration/api/org/springframework/integration/file/remote/RemoteFileTemplate.html[javadocs for `RemoteFileTemplate`] There is a subclass for FTP: `FtpRemoteFileTemplate`.
Additional methods were added in _version 4.1_ including `getClientInstance()` which provides access to the underlying `FTPClient` enabling access to low-level APIs.

581
src/reference/asciidoc/gateway.adoc Normal file
View File

@@ -0,0 +1,581 @@
[[gateway]]
=== Messaging Gateways
The primary purpose of a Gateway is to hide the messaging API provided by Spring Integration.
It allows your application's business logic to be completely unaware of the Spring Integration API and using a generic Gateway, your code interacts instead with a simple interface, only.
[[gateway-proxy]]
==== Enter the GatewayProxyFactoryBean
As mentioned above, it would be great to have no dependency on the Spring Integration API at all - including the gateway class.
For that reason, Spring Integration provides the `GatewayProxyFactoryBean` that generates a proxy for any interface and internally invokes the gateway methods shown below.
Using dependency injection you can then expose the interface to your business methods.
Here is an example of an interface that can be used to interact with Spring Integration:
[source,java]
----
package org.cafeteria;
public interface Cafe {
void placeOrder(Order order);
}
----
[[gateway-namespace]]
==== Gateway XML Namespace Support
Namespace support is also provided which allows you to configure such an interface as a service as demonstrated by the following example.
[source,xml]
----
<int:gateway id="cafeService"
service-interface="org.cafeteria.Cafe"
default-request-channel="requestChannel"
default-reply-channel="replyChannel"/>
----
With this configuration defined, the "cafeService" can now be injected into other beans, and the code that invokes the methods on that proxied instance of the Cafe interface has no awareness of the Spring Integration API.
The general approach is similar to that of Spring Remoting (RMI, HttpInvoker, etc.).
See the "Samples" Appendix for an example that uses this "gateway" element (in the Cafe demo).
[[gateway-default-reply-channel]]
==== Setting the Default Reply Channel
Typically you don't have to specify the `default-reply-channel`, since a Gateway will auto-create a temporary, anonymous reply channel, where it will listen for the reply.
However, there are some cases which may prompt you to define a `default-reply-channel` (or `reply-channel` with adapter gateways such as HTTP, JMS, etc.).
For some background, we'll quickly discuss some of the inner-workings of the Gateway.
A Gateway will create a temporary point-to-point reply channel which is anonymous and is added to the Message Headers with the name `replyChannel`.
When providing an explicit `default-reply-channel` (`reply-channel` with remote adapter gateways), you have the option to point to a publish-subscribe channel, which is so named because you can add more than one subscriber to it.
Internally Spring Integration will create a Bridge between the temporary `replyChannel` and the explicitly defined `default-reply-channel`.
So let's say you want your reply to go not only to the gateway, but also to some other consumer.
In this case you would want two things: _a) a named channel you can subscribe to and b) that channel is a publish-subscribe-channel._ The default strategy used by the gateway will not satisfy those needs, because the reply channel added to the header is anonymous and point-to-point.
This means that no other subscriber can get a handle to it and even if it could, the channel has point-to-point behavior such that only one subscriber would get the Message.
So by defining a `default-reply-channel` you can point to a channel of your choosing, which in this case would be a `publish-subscribe-channel`.
The Gateway would create a bridge from it to the temporary, anonymous reply channel that is stored in the header.
Another case where you might want to provide a reply channel explicitly is for monitoring or auditing via an interceptor (e.g., wiretap).
You need a named channel in order to configure a Channel Interceptor.
[[gateway-configuration-annotations]]
==== Gateway Configuration with Annotations and/or XML
The reason that the attributes on the 'gateway' element are named 'default-request-channel' and 'default-reply-channel' is that you may also provide per-method channel references by using the`@Gateway` annotation.
[source,java]
----
public interface Cafe {
@Gateway(requestChannel="orders")
void placeOrder(Order order);
}
----
You may alternatively provide such content in `method` sub-elements if you prefer XML configuration (see the next paragraph).
It is also possible to pass values to be interpreted as Message headers on the Message that is created and sent to the request channel by using the @Header annotation:
[source,java]
----
public interface FileWriter {
@Gateway(requestChannel="filesOut")
void write(byte[] content, @Header(FileHeaders.FILENAME) String filename);
}
----
If you prefer the XML approach of configuring Gateway methods, you can provide _method_ sub-elements to the gateway configuration.
[source,xml]
----
<int:gateway id="myGateway" service-interface="org.foo.bar.TestGateway"
default-request-channel="inputC">
<int:default-header name="calledMethod" expression="#gatewayMethod.name"/>
<int:method name="echo" request-channel="inputA" reply-timeout="2" request-timeout="200"/>
<int:method name="echoUpperCase" request-channel="inputB"/>
<int:method name="echoViaDefault"/>
</int:gateway>
----
You can also provide individual headers per method invocation via XML.
This could be very useful if the headers you want to set are static in nature and you don't want to embed them in the gateway's method signature via `@Header` annotations.
For example, in the Loan Broker example we want to influence how aggregation of the Loan quotes will be done based on what type of request was initiated (single quote or all quotes). Determining the type of the request by evaluating what gateway method was invoked, although possible, would violate the separation of concerns paradigm (the method is a java artifact),  but expressing your intention (meta information) via Message headers is natural in a Messaging architecture.
[source,xml]
----
<int:gateway id="loanBrokerGateway"
service-interface="org.springframework.integration.loanbroker.LoanBrokerGateway">
<int:method name="getLoanQuote" request-channel="loanBrokerPreProcessingChannel">
<int:header name="RESPONSE_TYPE" value="BEST"/>
</int:method>
<int:method name="getAllLoanQuotes" request-channel="loanBrokerPreProcessingChannel">
<int:header name="RESPONSE_TYPE" value="ALL"/>
</int:method>
</int:gateway>
----
In the above case you can clearly see how a different value will be set for the 'RESPONSE_TYPE' header based on the gateway's method.
*Expressions and "Global" Headers*
The `<header/>` element supports `expression` as an alternative to `value`.
The SpEL expression is evaluated to determine the value of the header.
There is no `#root` object but the following variables are available:
#args - an `Object[]` containing the method arguments
#gatewayMethod - the `java.reflect.Method` object representing the method in the `service-interface` that was invoked.
A header containing this variable can be used later in the flow, for example, for routing.
For example, if you wish to route on the simple method name, you might add a header, with expression `#gatewayMethod.name`.
NOTE: The `java.reflect.Method` is not serializable; a header with expression `#gatewayMethod` will be lost if you later serialize the message.
So, you may wish to use `#gatewayMethod.name` or `#gatewayMethod.toString()` in those cases; the `toString()` method provides a String representation of the method, including parameter and return types.
NOTE: Prior to 3.0, the `#method` variable was available, representing the method name only.
This is still available, but deprecated; use `#gatewayMethod.name` instead.
Since 3.0, `<default-header/>` s can be defined to add headers to all messages produced by the gateway, regardless of the method invoked.
Specific headers defined for a method take precedence over default headers.
Specific headers defined for a method here will override any `@Header` annotations in the service interface.
However, default headers will NOT override any `@Header` annotations in the service interface.
The gateway now also supports a `default-payload-expression` which will be applied for all methods (unless overridden).
[[gateway-mapping]]
==== Mapping Method Arguments to a Message
Using the configuration techniques in the previous section allows control of how method arguments are mapped to message elements (payload and header(s)).
When no explicit configuration is used, certain conventions are used to perform the mapping.
In some cases, these conventions cannot determine which argument is the payload and which should be mapped to headers.
[source,java]
----
public String send1(Object foo, Map bar);
public String send2(Map foo, Map bar);
----
In the first case, the convention will map the first argument to the payload (as long as it is not a `Map`) and the contents of the second become headers.
In the second case (or the first when the argument for parameter `foo` is a `Map`), the framework cannot determine which argument should be the payload; mapping will fail.
This can generally be resolved using a `payload-expression`, a `@Payload` annotation and/or a `@Headers` annotation.
Alternatively, and whenever the conventions break down, you can take the entire responsibility for mapping the method calls to messages.
To do this, implement an`MethodArgsMessageMapper` and provide it to the `<gateway/>` using the `mapper` attribute.
The mapper maps a `MethodArgsHolder`, which is a simple class wrapping the `java.reflect.Method` instance and an `Object[]` containing the arguments.
When providing a custom mapper, the `default-payload-expression` attribute and `<default-header/>` elements are not allowed on the gateway; similarly, the `payload-expression` attribute and `<header/>` elements are not allowed on any `<method/>` elements.
*Mapping Method Arguments*
Here are examples showing how method arguments can be mapped to the message (and some examples of invalid configuration):
[source,java]
----
public interface MyGateway {
void payloadAndHeaderMapWithoutAnnotations(String s, Map<String, Object> map);
void payloadAndHeaderMapWithAnnotations(@Payload String s, @Headers Map<String, Object> map);
void headerValuesAndPayloadWithAnnotations(@Header("k1") String x, @Payload String s, @Header("k2") String y);
void mapOnly(Map<String, Object> map); // the payload is the map and no custom headers are added
void twoMapsAndOneAnnotatedWithPayload(@Payload Map<String, Object> payload, Map<String, Object> headers);
@Payload("#args[0] + #args[1] + '!'")
void payloadAnnotationAtMethodLevel(String a, String b);
@Payload("@someBean.exclaim(#args[0])")
void payloadAnnotationAtMethodLevelUsingBeanResolver(String s);
void payloadAnnotationWithExpression(@Payload("toUpperCase()") String s);
void payloadAnnotationWithExpressionUsingBeanResolver(@Payload("@someBean.sum(#this)") String s); // <1>
// invalid
void twoMapsWithoutAnnotations(Map<String, Object> m1, Map<String, Object> m2);
// invalid
void twoPayloads(@Payload String s1, @Payload String s2);
// invalid
void payloadAndHeaderAnnotationsOnSameParameter(@Payload @Header("x") String s);
// invalid
void payloadAndHeadersAnnotationsOnSameParameter(@Payload @Headers Map<String, Object> map);
}
----
<1> Note that in this example, the SpEL variable `#this` refers to the argument - in this case, the value of `'s'`.
The XML equivalent looks a little different, since there is no `#this` context for the method argument, but expressions can refer to method arguments using the `#args` variable:
[source,xml]
----
<int:gateway id="myGateway" service-interface="org.foo.bar.MyGateway">
<int:method name="send1" payload-expression="#args[0] + 'bar'"/>
<int:method name="send2" payload-expression="@someBean.sum(#args[0])"/>
<int:method name="send3" payload-expression="#method"/>
<int:method name="send4">
<int:header name="foo" expression="#args[2].toUpperCase()"/>
</int:method>
</int:gateway>
----
[[messaging-gateway-annotation]]
==== @MessagingGateway Annotation
Starting with _version 4.0_, gateway service interfaces can be marked with a `@MessagingGateway` annotation instead of requiring the definition of a `<gateway />` xml element for configuration.
The following compares the two approaches for configuring the same gateway:
[source,xml]
----
<int:gateway id="myGateway" service-interface="org.foo.bar.TestGateway"
default-request-channel="inputC">
<int:default-header name="calledMethod" expression="#gatewayMethod.name"/>
<int:method name="echo" request-channel="inputA" reply-timeout="2" request-timeout="200"/>
<int:method name="echoUpperCase" request-channel="inputB">
<int:header name="foo" value="bar"/>
</int:method>
<int:method name="echoViaDefault"/>
</int:gateway>
----
[source,java]
----
@MessagingGateway(name = "myGateway", defaultRequestChannel = "inputC",
defaultHeaders = @GatewayHeader(name = "calledMethod",
expression="#gatewayMethod.name"))
public interface TestGateway {
@Gateway(requestChannel = "inputA", replyTimeout = 2, requestTimeout = 200)
String echo(String payload);
@Gateway(requestChannel = "inputB, headers = @GatewayHeader(name = "foo", value="bar"))
String echoUpperCase(String payload);
String echoViaDefault(String payload);
}
----
As with the XML version, Spring Integration creates the `proxy` implementation with its messaging infrastructure, when discovering these annotations during a component scan.
To perform this scan and register the `BeanDefinition` in the application context, add the `@IntegrationComponentScan` annotation to a `@Configuration` class - see also <<enable-integration>>.
[[gateway-calling-no-argument-methods]]
==== Invoking No-Argument Methods
When invoking methods on a Gateway interface that do not have any arguments, the default behavior is to _receive_ a `Message` from a `PollableChannel`.
At times however, you may want to trigger no-argument methods so that you can in fact interact with other components downstream that do not require user-provided parameters, e.g.
triggering no-argument SQL calls or Stored Procedures.
In order to achieve _send-and-receive_ semantics, you must provide a payload.
In order to generate a payload, method parameters on the interface are not necessary.
You can either use the `@Payload` annotation or the `payload-expression` attribute in XML on the `method` sub-element.
Below please find a few examples of what the payloads could be:
* a literal string
* #gatewayMethod.name
* new java.util.Date()
* @someBean.someMethod()'s return value
Here is an example using the `@Payload` annotation:
[source,xml]
----
public interface Cafe {
@Payload("new java.util.Date()")
List<Order> retrieveOpenOrders();
}
----
If a method has no argument and no return value, but does contain a payload expression, it will be treated as a _send-only_ operation.
[[gateway-error-handling]]
==== Error Handling
Of course, the Gateway invocation might result in errors.
By default any error that has occurred downstream will be re-thrown as a`MessagingException` (RuntimeException) upon the Gateway's method invocation.
However there are times when you may want to simply log the error rather than propagating it, or you may want to treat an Exception as a valid reply, by mapping it to a Message that will conform to some "error message" contract that the caller understands.
To accomplish this, our Gateway provides support for a Message Channel dedicated to the errors via the_error-channel_ attribute.
In the example below, you can see that a 'transformer' is used to create a reply Message from the Exception.
[source,xml]
----
<int:gateway id="sampleGateway"
default-request-channel="gatewayChannel"
service-interface="foo.bar.SimpleGateway"
error-channel="exceptionTransformationChannel"/>
<int:transformer input-channel="exceptionTransformationChannel"
ref="exceptionTransformer" method="createErrorResponse"/>
----
The _exceptionTransformer_ could be a simple POJO that knows how to create the expected error response objects.
That would then be the payload that is sent back to the caller.
Obviously, you could do many more elaborate things in such an "error flow" if necessary.
It might involve routers (including Spring Integration's ErrorMessageExceptionTypeRouter), filters, and so on.
Most of the time, a simple 'transformer' should be sufficient, however.
Alternatively, you might want to only log the Exception (or send it somewhere asynchronously).
If you provide a one-way flow, then nothing would be sent back to the caller.
In the case that you want to completely suppress Exceptions, you can provide a reference to the global "nullChannel" (essentially a /dev/null approach).
Finally, as mentioned above, if no "error-channel" is defined at all, then the Exceptions will propagate as usual.
IMPORTANT: Exposing the messaging system via simple POJI Gateways obviously provides benefits, but "hiding" the reality of the underlying messaging system does come at a price so there are certain things you should consider.
We want our Java method to return as quickly as possible and not hang for an indefinite amount of time while the caller is waiting on it to return (void, return value, or a thrown Exception).
When regular methods are used as a proxies in front of the Messaging system, we have to take into account the potentially asynchronous nature of the underlying messaging.
This means that there might be a chance that a Message that was initiated by a Gateway could be dropped by a Filter, thus never reaching a component that is responsible for producing a reply.
Some Service Activator method might result in an Exception, thus providing no reply (as we don't generate Null messages).
So as you can see there are multiple scenarios where a reply message might not be coming.
That is perfectly natural in messaging systems.
However think about the implication on the gateway method. The Gateway's method input arguments  were incorporated into a Message and sent downstream.
The reply Message would be converted to a return value of the Gateway's method.
So you might want to ensure that for each Gateway call there will always be a reply Message.
Otherwise, your Gateway method might never return and will hang indefinitely.
One of the ways of handling this situation is via an Asynchronous Gateway (explained later in this section).
Another way of handling it is to explicitly set the reply-timeout attribute.
That way, the gateway will not hang any longer than the time specified by the reply-timeout and will return 'null' if that timeout does elapse.
Finally, you might want to consider setting downstream flags such as 'requires-reply' on a service-activator or 'throw-exceptions-on-rejection' on a filter. These options will be discussed in more detail in the final section of this chapter.
[[async-gateway]]
==== Asynchronous Gateway
As a pattern, the Messaging Gateway is a very nice way to hide messaging-specific code while still exposing the full capabilities of the messaging system.
As you've seen, the `GatewayProxyFactoryBean` provides a convenient way to expose a Proxy over a service-interface thus giving you POJO-based access to a messaging system (based on objects in your own domain, or primitives/Strings, etc).
 But when a gateway is exposed via simple POJO methods which return values it does imply that for each Request message (generated when the method is invoked) there must be a Reply message (generated when the method has returned).
Since Messaging systems naturally are asynchronous you may not always be able to guarantee the contract where _"for each request there will always be be a reply"_.  With Spring Integration 2.0 we introduced support for an _Asynchronous Gateway_ which is a convenient way to initiate flows where you may not know if a reply is expected or how long will it take for replies to arrive.
A natural way to handle these types of scenarios in Java would be relying upon _java.util.concurrent.Future_ instances, and that is exactly what Spring Integration uses to support an _Asynchronous Gateway_.
From the XML configuration, there is nothing different and you still define _Asynchronous Gateway_ the same way as a regular Gateway.
[source,xml]
----
<int:gateway id="mathService" 
service-interface="org.springframework.integration.sample.gateway.futures.MathServiceGateway"
default-request-channel="requestChannel"/>
----
However the Gateway Interface (service-interface) is a little different:
[source,java]
----
public interface MathServiceGateway {
Future<Integer> multiplyByTwo(int i);
}
----
As you can see from the example above, the return type for the gateway method is a `Future`.
When `GatewayProxyFactoryBean` sees that the return type of the gateway method is a `Future`, it immediately switches to the async mode by utilizing an `AsyncTaskExecutor`.
That is all.
The call to such a method always returns immediately with a `Future` instance.
Then, you can interact with the `Future` at your own pace to get the result, cancel, etc.
And, as with any other use of Future instances, calling get() may reveal a timeout, an execution exception, and so on.
[source,java]
----
MathServiceGateway mathService = ac.getBean("mathService", MathServiceGateway.class);
Future<Integer> result = mathService.multiplyByTwo(number);
// do something else here since the reply might take a moment
int finalResult =  result.get(1000, TimeUnit.SECONDS);
----
For a more detailed example, please refer to the https://github.com/SpringSource/spring-integration-samples/tree/master/intermediate/async-gateway[_async-gateway_] sample distributed within the Spring Integration samples.
*ListenableFuture*
Starting with _version 4.1_, async gateway methods can also return `ListenableFuture` (introduced in Spring Framework 4.0).
These return types allow you to provide a callback which is invoked when the result is available (or an exception occurs).
When the gateway detects this return type, and the task executor (see below) is an `AsyncListenableTaskExecutor`, the executor's `submitListenable()` method is invoked.
[source,java]
----
ListenableFuture<String> result = this.asyncGateway.async("foo");
result.addCallback(new ListenableFutureCallback<String>() {
@Override
public void onSuccess(String result) {
...
}
@Override
public void onFailure(Throwable t) {
...
}
});
----
*Asynchronous Gateway and AsyncTaskExecutor*
By default, the `GatewayProxyFactoryBean` uses `org.springframework.core.task.SimpleAsyncTaskExecutor` when submitting internal `AsyncInvocationTask` instances for any gateway method whose return type is `Future`.
However the `async-executor` attribute in the `<gateway/>` element's configuration allows you to provide a reference to any implementation of `java.util.concurrent.Executor` available within the Spring application context.
The (default) `SimpleAsyncTaskExecutor` supports both `Future` and `ListenableFuture` return types, returning `FutureTask` or `ListenableFutureTask` respectively.
Even though there is a default executor, it is often useful to provide an external one so that you can identify its threads in logs (when using XML, the thread name is based on the executor's bean name):
[source,java]
----
@Bean
public AsyncTaskExecutor exec() {
SimpleAsyncTaskExecutor simpleAsyncTaskExecutor = new SimpleAsyncTaskExecutor();
simpleAsyncTaskExecutor.setThreadNamePrefix("exec-");
return simpleAsyncTaskExecutor;
}
@MessagingGateway(asyncExecutor = "exec")
public interface ExecGateway {
@Gateway(requestChannel = "gatewayChannel")
Future<?> doAsync(String foo);
}
----
If you wish to return a different `Future` implementation, you can provide a custom executor, or disable the executor altogether and return the `Future` in the reply message payload from the downstream flow.
To disable the executor, simply set it to `null` in the `GatewayProxyFactoryBean` (`setAsyncTaskExecutor(null)`).
When configuring the gateway with XML, use `async-executor=""`; when configuring using the `@MessagingGateway` annotation, use:
[source,java]
----
@MessagingGateway(asyncExecutor = AnnotationConstants.NULL)
public interface NoExecGateway {
@Gateway(requestChannel = "gatewayChannel")
Future<?> doAsync(String foo);
}
----
IMPORTANT: If the return type is a specific concrete `Future` implementation or some other subinterface that is not supported by the configured executor, the flow will run on the caller's thread and the flow must return the required type in the reply message payload.
*Asynchronous Gateway and Reactor Promise*
Also starting with _version 4.1_, the `GatewayProxyFactoryBean` allows the use of a `Reactor` with gateway interface methods, utilizing a https://github.com/reactor/reactor/wiki/Promises[`Promise<?>`] return type.
The internal `AsyncInvocationTask` is wrapped in a `reactor.function.Supplier` with the provided `reactorEnvironment`, using a default `RingBufferDispatcher` for the `Promise` consumption.
Note, a `reactorEnvironment` reference is required whenever a service interface has at least one method with a `Promise<?>` return type.
(Only those methods run on the reactor's dispatcher).
A `Promise` can be used to retrieve the result later (similar to a `Future<?>`) or you can consume from it with the dispatcher invoking your `Consumer` when the result is returned to the gateway.
IMPORTANT: The `Promise` isn't _flushed_ immediately by the framework.
Hence the underlying message flow won't be started before the gateway method returns (as it is with `Future<?>` `Executor` task).
The flow will be started when the `Promise` is _flushed_ or via `Promise.await()`.
Alternatively, the `Promise` (being a `Composable`) might be a part of Reactor `Stream<?>`, when the `flush()` is related to the entire `Stream`.
For example:
[source,java]
----
@MessagingGateway(reactorEnvironment = "reactorEnv")
public static interface TestGateway {
@Gateway(requestChannel = "promiseChannel")
Promise<Integer> multiply(Integer value);
}
...
@ServiceActivator(inputChannel = "promiseChannel")
public Integer multiply(Integer value) {
return value * 2;
}
...
Streams.defer(Arrays.asList("1", "2", "3", "4", "5"))
.env(this.environment)
.get()
.map(Integer::parseInt)
.mapMany(integer -> testGateway.multiply(integer))
.collect()
.consume(integers -> ...)
.flush();
----
Another example is a simple callback scenario:
[source,java]
----
Promise<Invoice> promise = service.process(myOrder);
promise.consume(new Consumer<Invoice>() {
@Override
public void accept(Invoice invoice) {
handleInvoice(invoice);
}
})
.flush();
----
The calling thread continues, with `handleInvoice()` being called when the flow completes.
==== Gateway behavior when no response arrives
As it was explained earlier, the Gateway provides a convenient way of interacting with a Messaging system via POJO method invocations, but realizing that a typical method invocation, which is generally expected to always return (even with an Exception), might not always map one-to-one to message exchanges (e.g., a reply message might not arrive - which is equivalent to a method not returning).
It is important to go over several scenarios especially in the Sync Gateway case and understand the default behavior of the Gateway and how to deal with these scenarios to make the Sync Gateway behavior more predictable regardless of the outcome of the message flow that was initialed from such Gateway.
There are certain attributes that could be configured to make Sync Gateway behavior more predictable, but some of them might not always work as you might have expected.
One of them is _reply-timeout_.
So, lets look at the _reply-timeout_ attribute and see how it can/can't influence the behavior of the Sync Gateway in various scenarios.
We will look at single-threaded scenario (all components downstream are connected via Direct Channel) and multi-threaded scenarios (e.g., somewhere downstream you may have Pollable or Executor Channel which breaks single-thread boundary)
_Long running process downstream_
_Sync Gateway - single-threaded_.
If a component downstream is still running (e.g., infinite loop or a very slow service), then setting a _reply-timeout_ has no effect and the Gateway method call will not return until such downstream service exits (via return or exception).
_Sync Gateway - multi-threaded_.
If a component downstream is still running (e.g., infinite loop or a very slow service), in a multi-threaded message flow setting the _reply-timeout_ will have an effect by allowing gateway method invocation to return once the timeout has been reached, since the `GatewayProxyFactoryBean`  will simply poll on the reply channel waiting for a message until the timeout expires.
However it could result in a 'null' return from the Gateway method if the timeout has been reached before the actual reply was produced. It is also important to understand that the reply message (if produced) will be sent to a reply channel after the Gateway method invocation might have returned, so you must be aware of that and design your flow with this in mind.
_Downstream component returns 'null'_
_Sync Gateway - single-threaded_.
If a component downstream returns 'null' and no _reply-timeout_ has been configured, the Gateway method call will hang indefinitely unless: a) a _reply-timeout_ has been configured or b) the _requires-reply_ attribute has been set on the downstream component (e.g., service-activator) that might return 'null'.
In this case, an Exception would be thrown and propagated to the Gateway._Sync Gateway - multi-threaded_.
Behavior is the same as above.
_Downstream component return signature is 'void' while Gateway method signature is non-void_
_Sync Gateway - single-threaded_.
If a component downstream returns 'void' and no _reply-timeout_ has been configured, the Gateway method call will hang indefinitely unless a _reply-timeout_ has been configured  _Sync Gateway - multi-threaded_ Behavior is the same as above.
_Downstream component results in Runtime Exception (regardless of the method signature)_
_Sync Gateway - single-threaded_.
If a component downstream throws a Runtime Exception, such exception will be propagated via an Error Message back to the gateway and re-thrown.
_Sync Gateway - multi-threaded_ Behavior is the same as above.
IMPORTANT: It is also important to understand that by default _reply-timeout_ is unbounded* which means that if not explicitly set there are several scenarios (described above) where your Gateway method invocation might hang indefinitely.
So, make sure you analyze your flow and if there is even a remote possibility of one of these scenarios to occur, set the _reply-timeout_ attribute to a 'safe' value or, even better, set the _requires-reply_ attribute of the downstream component to 'true' to ensure a timely response as produced by the throwing of an Exception as soon as that downstream component does return null internally.
But also, realize that there are some scenarios (see the very first one) where _reply-timeout_ will not help.
That means it is also important to analyze your message flow and decide when to use a Sync Gateway vs an Async Gateway.
As you've seen the latter case is simply a matter of defining Gateway methods that return Future instances.
Then, you are guaranteed to receive that return value, and you will have more granular control over the results of the invocation.Also, when dealing with a Router you should remember that setting the _resolution-required_ attribute to 'true' will result in an Exception thrown by the router if it can not resolve a particular channel.
Likewise, when dealing with a Filter, you can set the _throw-exception-on-rejection_ attribute.
In both of these cases, the resulting flow will behave like that containing a service-activator with the 'requires-reply' attribute.
In other words, it will help to ensure a timely response from the Gateway method invocation.
NOTE: * _reply-timeout_ is unbounded for _<gateway/>_ elements (created by the GatewayProxyFactoryBean).
Inbound gateways for external integration (ws, http, etc.) share many characteristics and attributes with these gateways.
However, for those inbound gateways, the default _reply-timeout_ is 1000 milliseconds (1 second).
If a downstream async handoff is made to another thread, you may need to increase this attribute to allow enough time for the flow to complete before the gateway times out.

223
src/reference/asciidoc/gemfire.adoc Normal file
View File

@@ -0,0 +1,223 @@
[[gemfire]]
== GemFire Support
Spring Integration provides support for VMWare vFabric GemFire
[[gemfire-intro]]
=== Introduction
VMWare vFabric GemFire (GemFire) is a distributed data management platform providing a key-value data grid along with advanced distributed system features such as event processing, continuous querying, and remote function execution.
This guide assumes some familiarity with http://www.vmware.com/support/pubs/vfabric-gemfire.html[GemFire] and its http://www.vmware.com/support/developer/vfabric-gemfire/662-api/index.html[API].
Spring integration provides support for GemFire by providing inbound adapters for entry and continuous query events, an outbound adapter to write entries to the cache, and `MessageStore` and `MessageGroupStore` implementations.
Spring integration leverages thehttp://www.springsource.org/spring-gemfire[Spring Gemfire] project, providing a thin wrapper over its components.
To configure the 'int-gfe' namespace, include the following elements within the headers of your XML configuration file:
[source,xml]
----
xmlns:int-gfe="http://www.springframework.org/schema/integration/gemfire"
xsi:schemaLocation="http://www.springframework.org/schema/integration/gemfire
http://www.springframework.org/schema/integration/gemfire/spring-integration-gemfire.xsd"
----
[[gemfire-inbound]]
=== Inbound Channel Adapter
The _inbound-channel-adapter_ produces messages on a channel triggered by a GemFire `EntryEvent`.
GemFire generates events whenever an entry is CREATED, UPDATED, DESTROYED, or INVALIDATED in the associated region.
The inbound channel adapter allows you to filter on a subset of these events.
For example, you may want to only produce messages in response to an entry being CREATED.
In addition, the inbound channel adapter can evaluate a SpEL expression if, for example, you want your message payload to contain an event property such as the new entry value.
[source,xml]
----
<gfe:cache/>
<gfe:replicated-region id="region"/>
<int-gfe:inbound-channel-adapter id="inputChannel" region="region"
cache-events="CREATED" expression="newValue"/>
----
In the above configuration, we are creating a GemFire `Cache` and `Region` using Spring GemFire's 'gfe' namespace.
The inbound-channel-adapter requires a reference to the GemFire region for which the adapter will be listening for events.
Optional attributes include `cache-events` which can contain a comma separated list of event types for which a message will be produced on the input channel.
By default CREATED and UPDATED are enabled.
Note that this adapter conforms to Spring integration conventions.
If no `channel` attribute is provided, the channel will be created from the `id` attribute.
This adapter also supports an `error-channel`.
The GemFire http://www.gemstone.com/docs/current/product/docs/japi/com/gemstone/gemfire/cache/EntryEvent.html[EntryEvent] is the `#root` object of the `expression` evaluation.
Example:
[source]
----
expression="new foo.MyEvent(key, oldValue, newValue)"
----
If the `expression` attribute is not provided, the message payload will be the GemFire `EntryEvent` itself.
[[gemfire-cq]]
=== Continuous Query Inbound Channel Adapter
The _cq-inbound-channel-adapter_ produces messages a channel triggered by a GemFire continuous query or `CqEvent` event.
Spring GemFire introduced continuous query support in release 1.1, including a `ContinuousQueryListenerContainer` which provides a nice abstraction over the GemFire native API.
This adapter requires a reference to a ContinuousQueryListenerContainer, and creates a listener for a given `query` and executes the query.
The continuous query acts as an event source that will fire whenever its result set changes state.
NOTE: GemFire queries are written in OQL and are scoped to the entire cache (not just one region).
Additionally, continuous queries require a remote (i.e., running in a separate process or remote host) cache server.
Please consult the http://www.gemstone.com/docs/6.6.RC/product/docs/html/user_guide/UserGuide_GemFire.html#Continuous%20Querying[GemFire documentation] for more information on implementing continuous queries.
[source,xml]
----
<gfe:client-cache id="client-cache" pool-name="client-pool"/>
<gfe:pool id="client-pool" subscription-enabled="true" >
<!--configure server or locator here required to address the cache server -->
</gfe:pool>
<gfe:client-region id="test" cache-ref="client-cache" pool-name="client-pool"/>
<gfe:cq-listener-container id="queryListenerContainer" cache="client-cache"
pool-name="client-pool"/>
<int-gfe:cq-inbound-channel-adapter id="inputChannel"
cq-listener-container="queryListenerContainer"
query="select * from /test"/>
----
In the above configuration, we are creating a GemFire client cache (recall a remote cache server is required for this implementation and its address is configured as a sub-element of the pool), a client region and a `ContinuousQueryListenerContainer` using Spring GemFire.
The continuous query inbound channel adapter requires a `cq-listener-container` attribute which contains a reference to the `ContinuousQueryListenerContainer`.
Optionally, it accepts an `expression` attribute which uses SpEL to transform the `CqEvent` or extract an individual property as needed.
The cq-inbound-channel-adapter provides a `query-events` attribute, containing a comma separated list of event types for which a message will be produced on the input channel.
Available event types are CREATED, UPDATED, DESTROYED, REGION_DESTROYED, REGION_INVALIDATED.
CREATED and UPDATED are enabled by default.
Additional optional attributes include, `query-name` which provides an optional query name, and `expression` which works as described in the above section, and `durable` - a boolean value indicating if the query is durable (false by default).
Note that this adapter conforms to Spring integration conventions.
If no `channel` attribute is provided, the channel will be created from the `id` attribute.
This adapter also supports an `error-channel`
[[gemfire-outbound]]
=== Outbound Channel Adapter
The _outbound-channel-adapter_ writes cache entries mapped from the message payload.
In its simplest form, it expects a payload of type `java.util.Map` and puts the map entries into its configured region.
[source,xml]
----
<int-gfe:outbound-channel-adapter id="cacheChannel" region="region"/>
----
Given the above configuration, an exception will be thrown if the payload is not a Map.
Additionally, the outbound channel adapter can be configured to create a map of cache entries using SpEL of course.
[source,xml]
----
<int-gfe:outbound-channel-adapter id="cacheChannel" region="region">
<int-gfe:cache-entries>
<entry key="payload.toUpperCase()" value="payload.toLowerCase()"/>
<entry key="'foo'" value="'bar'"/>
</int-gfe:cache-entries>
</int-gfe:outbound-channel-adapter>
----
In the above configuration, the inner element `cache-entries` is semantically equivalent to Spring 'map' element.
The adapter interprets the `key` and `value` attributes as SpEL expressions with the message as the evaluation context.
Note that this contain arbitrary cache entries (not only those derived from the message) and that literal values must be enclosed in single quotes.
In the above example, if the message sent to `cacheChannel` has a String payload with a value "Hello", two entries `[HELLO:hello, foo:bar]` will be written (created or updated) in the cache region.
This adapter also supports the `order` attribute which may be useful if it is bound to a PublishSubscribeChannel.
[[gemfire-message-store]]
=== Gemfire Message Store
As described in EIP, a http://www.eaipatterns.com/MessageStore.html[Message Store] allows you to persist Messages.
This can be very useful when dealing with components that have a capability to buffer messages (_QueueChannel, Aggregator, Resequencer_, etc.) if reliability is a concern.
In Spring Integration, the MessageStore strategy also provides the foundation for thehttp://www.eaipatterns.com/StoreInLibrary.html[ClaimCheck] pattern, which is described in EIP as well.
Spring Integration's Gemfire module provides the `GemfireMessageStore` which is an implementation of both the the `MessageStore` strategy (mainly used by the _QueueChannel_ and _ClaimCheck_ patterns) and the `MessageGroupStore` strategy (mainly used by the _Aggregator_ and _Resequencer_ patterns).
[source,xml]
----
<bean id="gemfireMessageStore" class="o.s.i.gemfire.store.GemfireMessageStore">
<constructor-arg ref="myCache"/>
</bean>
<bean id="myCache" class="org.springframework.data.gemfire.CacheFactoryBean"/>
<int:channel id="somePersistentQueueChannel">
<int:queue message-store="gemfireMessageStore"/>
<int:channel>
<int:aggregator input-channel="inputChannel" output-channel="outputChannel"
message-store="gemfireMessageStore"/>
----
Above is a sample `GemfireMessageStore` configuration that shows its usage by a _QueueChannel_ and an _Aggregator_.
As you can see it is a normal Spring bean configuration.
The simplest configuration requires a reference to a `GemFireCache` (created by `CacheFactoryBean`) as a constructor argument.
If the cache is standalone, i.e., embedded in the same JVM, the MessageStore will create a message store region named "messageStoreRegion".
If your application requires customization of the messageStore region, for example, multiple Gemfire message stores each with its own region, you can configure a region for each message store instance and use the `Region` as the constructor argument:
[source,xml]
----
<bean id="gemfireMessageStore" class="o.s.i.gemfire.store.GemfireMessageStore">
<constructor-arg ref="myRegion"/>
</bean>
<gfe:cache/>
<gfe:replicated-region id="myRegion"/>
----
In the above examle, the cache and region are configured using the spring-gemfire namespace (not to be confused with the spring-integration-gemfire namespace).
Often it is desirable for the message store to be maintained in one or more remote cache servers in a client-server configuration (See the http://www.vmware.com/support/pubs/vfabric-gemfire.html[GemFire product documentation] for more details).
In this case, you configure a client cache, client region, and client pool and inject the region into the MessageStore.
Here is an example:
[source,xml]
----
<bean id="gemfireMessageStore"
class="org.springframework.integration.gemfire.store.GemfireMessageStore">
<constructor-arg ref="myRegion"/>
</bean>
<gfe:client-cache/>
<gfe:client-region id="myRegion" shortcut="PROXY" pool-name="messageStorePool"/>
<gfe:pool id="messageStorePool">
<gfe:server host="localhost" port="40404" />
</gfe:pool>
----
Note the _pool_ element is configured with the address of a cache server (a locator may be substituted here).
The region is configured as a 'PROXY' so that no data will be stored locally.
The region's id corresponds to a region with the same name configured in the cache server.
[[gemfire-lock-registry]]
=== Gemfire Lock Registry
Starting with _version 4.0_, the `GemfireLockRegistry` is available.
Certain components (for example aggregator and resequencer) use a lock obtained from a `LockRegistry` instance to ensure that only one thread is manipulating a group at a time.
The `DefaultLockRegistry` performs this function within a single component; you can now configure an external lock registry on these components.
When used with a shared `MessageGroupStore`, the `GemfireLockRegistry` can be use to provide this functionality across multiple application instances, such that only one instance can manipulate the group at a time.
NOTE: One of the `GemfireLockRegistry` constructors requires a `Region` as an argument; it is used to obtain a `Lock` via the `getDistributedLock()` method.
This operation requires `GLOBAL` scope for the `Region`.
Another constructor requires `Cache` and the `Region` will be created with `GLOBAL` scope and with the name `LockRegistry`.
[[gemfire-metadata-store]]
=== Gemfire Metadata Store
As of _Spring Integration 4.0_, a new Gemfire-based `MetadataStore` (<<metadata-store>>) implementation is available.
The `GemfireMetadataStore` can be used to maintain metadata state across application restarts.
This new `MetadataStore` implementation can be used with adapters such as:
* <<twitter-inbound>>
* <<feed-inbound-channel-adapter>>
* <<file-reading>>
* <<ftp-inbound>>
* <<sftp-inbound>>
In order to instruct these adapters to use the new `GemfireMetadataStore`, simply declare a Spring bean using the bean name *metadataStore*.
The _Twitter Inbound Channel Adapter_ and the _Feed Inbound Channel Adapter_ will both automatically pick up and use the declared `GemfireMetadataStore`.
NOTE: The `GemfireMetadataStore` also implements `ConcurrentMetadataStore`, allowing it to be reliably shared across multiple application instances where only one instance will be allowed to store or modify a key's value.
These methods give various levels of concurrency guarantees based on the scope and data policy of the region.
They are implemented in the peer cache and client/server cache but are disallowed in peer Regions having NORMAL or EMPTY data policies.

96
src/reference/asciidoc/groovy.adoc Normal file
View File

@@ -0,0 +1,96 @@
[[groovy]]
=== Groovy support
In Spring Integration 2.0 we added Groovy support allowing you to use the Groovy scripting language to provide the logic for various integration components similar to the way the Spring Expression Language (SpEL) is supported for routing, transformation and other integration concerns.
For more information about Groovy please refer to the Groovy documentation which you can find on the http://groovy.codehaus.org[project website]
[[groovy-config]]
==== Groovy configuration
With Spring Integration 2.1, Groovy Support's configuration namespace is an extension of Spring Integration's Scripting Support and shares the core configuration and behavior described in detail in the <<scripting,Scripting Support>> section.
Even though Groovy scripts are well supported by generic Scripting Support, Groovy Support provides the_Groovy_ configuration namespace which is backed by the Spring Framework's `org.springframework.scripting.groovy.GroovyScriptFactory` and related components, offering extended capabilities for using Groovy.
Below are a couple of sample configurations:
_Filter_
[source,xml]
----
<int:filter input-channel="referencedScriptInput">
<int-groovy:script location="some/path/to/groovy/file/GroovyFilterTests.groovy"/>
</int:filter>
<int:filter input-channel="inlineScriptInput">
<int-groovy:script><![CDATA[
return payload == 'good'
]]></int-groovy:script>
</int:filter>
----
As the above examples show, the configuration looks identical to the general Scripting Support configuration.
The only difference is the use of the Groovy namespace as indicated in the examples by the _int-groovy_ namespace prefix.
Also note that the `lang` attribute on the `<script>` tag is not valid in this namespace.
_Groovy object customization_
If you need to customize the Groovy object itself, beyond setting variables, you can reference a bean that implements `org.springframework.scripting.groovy.GroovyObjectCustomizer` via the `customizer` attribute.
For example, this might be useful if you want to implement a domain-specific language (DSL) by modifying the MetaClass and registering functions to be available within the script:
[source,xml]
----
<int:service-activator input-channel="groovyChannel">
<int-groovy:script location="foo/SomeScript.groovy" customizer="groovyCustomizer"/>
</int:service-activator>
<beans:bean id="groovyCustomizer" class="org.foo.MyGroovyObjectCustomizer"/>
----
Setting a custom GroovyObjectCustomizer is not mutually exclusive with `<variable>` sub-elements or the `script-variable-generator` attribute.
It can also be provided when defining an inline script.
With _Spring Integration 3.0_, in addition to the `variable` sub-element, the `variables` attribute has been introduced.
Also, groovy scripts have the ability to resolve a variable to a bean in the`BeanFactory`, if a binding variable was not provided with the name:
[source,xml]
----
<int-groovy:script>
<![CDATA[
entityManager.persist(payload)
payload
]]>
</int-groovy:script>
----
where variable `entityManager` is an appropriate bean in the application context.
For more information regarding `<variable>`, `variables`, and `script-variable-generator`, see the paragraph '_Script variable bindings_' of <<scripting-config>>.
[[groovy-control-bus]]
==== Control Bus
As described in (http://www.eaipatterns.com/ControlBus.html[EIP]), the idea behind the Control Bus is that the same messaging system can be used for monitoring and managing the components within the framework as is used for "application-level" messaging.
In Spring Integration we build upon the adapters described above so that it's possible to send Messages as a means of invoking exposed operations.
One option for those operations is Groovy scripts.
[source,xml]
----
<int-groovy:control-bus input-channel="operationChannel"/>
----
The Control Bus has an input channel that can be accessed for invoking operations on the beans in the application context.
The Groovy Control Bus executes messages on the input channel as Groovy scripts.
It takes a message, compiles the body to a Script, customizes it with a `GroovyObjectCustomizer`, and then executes it.
The Control Bus' `MessageProcessor` exposes all beans in the application context that are annotated with `@ManagedResource`, implement Spring's `Lifecycle` interface or extend Spring's `CustomizableThreadCreator` base class (e.g.
several of the `TaskExecutor` and `TaskScheduler` implementations).
IMPORTANT: Be careful about using managed beans with custom scopes (e.g.
'request') in the Control Bus' command scripts, especially inside an _async_ message flow.
If The Control Bus' `MessageProcessor` can't expose a bean from the application context, you may end up with some `BeansException` during _command script's_ executing.
For example, if a custom scope's context is not established, the attempt to get a bean within that scope will trigger a `BeanCreationException`.
If you need to further customize the Groovy objects, you can also provide a reference to a bean that implements `org.springframework.scripting.groovy.GroovyObjectCustomizer` via the `customizer` attribute.
[source,xml]
----
<int-groovy:control-bus input-channel="input"
output-channel="output"
customizer="groovyCustomizer"/>
<beans:bean id="groovyCustomizer" class="org.foo.MyGroovyObjectCustomizer"/>
----

620
src/reference/asciidoc/handler-advice.adoc Normal file
View File

@@ -0,0 +1,620 @@
[[message-handler-advice-chain]]
=== Adding Behavior to Endpoints
Prior to Spring Integration 2.2, you could add behavior to an entire Integration flow by adding an AOP Advice to a poller's <advice-chain /> element.
However, let's say you want to retry, say, just a ReST Web Service call, and not any downstream endpoints.
For example, consider the following flow:
_inbound-adapter->poller->http-gateway1->http-gateway2->jdbc-outbound-adapter_
If you configure some retry-logic into an advice chain on the poller, and, the call to _http-gateway2_ failed because of a network glitch, the retry would cause both _http-gateway1_ and _http-gateway2_ to be called a second time.
Similarly, after a transient failure in the_jdbc-outbound-adapter_, both http-gateways would be called a second time before again calling the _jdbc-outbound-adapter_.
Spring Integration 2.2 adds the ability to add behavior to individual endpoints.
This is achieved by the addition of the <request-handler-advice-chain /> element to many endpoints.
For example:
[source,xml]
----
<int-http:outbound-gateway id="withAdvice"
url-expression="'http://localhost/test1'"
request-channel="requests"
reply-channel="nextChannel">
<int:request-handler-advice-chain>
<ref bean="myRetryAdvice" />
</request-handler-advice-chain>
</int-http:outbound-gateway>
----
In this case, _myRetryAdvice_ will only be applied locally to this gateway and will not apply to further actions taken downstream after the reply is sent to the_nextChannel_.
The scope of the advice is limited to the endpoint itself.
[IMPORTANT]
=====
At this time, you cannot advise an entire <chain/> of endpoints.
The schema does not allow a <request-handler-advice-chain/> as a child element of the chain itself.
However, a <request-handler-advice-chain/> can be added to individual reply-producing endpoints _within_ a <chain/> element.
An exception is that, in a chain that produces no reply, because the last element in the chain is an_outbound-channel-adapter_, that _last_ element cannot be advised.
If you need to advise such an element, it must be moved outside of the chain (with the_output-channel_ of the chain being the _input-channel_ of the adapter.
The adapter can then be advised as normal.
For chains that produce a reply, every child element can be advised.
=====
[[advice-classes]]
==== Provided Advice Classes
In addition to providing the general mechanism to apply AOP Advice classes in this way, three standard Advices are provided:
* RequestHandlerRetryAdvice
* RequestHandlerCircuitBreakerAdvice
* ExpressionEvaluatingRequestHandlerAdvice
These are each described in detail in the following sections.
[[retry-advice]]
===== Retry Advice
The retry advice (`o.s.i.handler.advice.RequestHandlerRetryAdvice`) leverages the rich retry mechanisms provided by thehttps://github.com/SpringSource/spring-retry[Spring Retry] project.
The core component of `spring-retry` is the `RetryTemplate`, which allows configuration of sophisticated retry scenarios, including `RetryPolicy` and `BackoffPolicy` strategies, with a number of implementations, as well as a `RecoveryCallback` strategy to determine the action to take when retries are exhausted.
*Stateless Retry*
Stateless retry is the case where the retry activity is handled entirely within the advice, where the thread pauses (if so configured) and retries the action.
*Stateful Retry*
Stateful retry is the case where the retry state is managed within the advice, but where an exception is thrown and the caller resubmits the request.
An example for stateful retry is when we want the message originator (e.g.
JMS) to be responsible for resubmitting, rather than performing it on the current thread.
Stateful retry needs some mechanism to detect a retried submission.
*Further Information*
For more information on `spring-retry`, refer to the project's javadocs, as well as the reference documentation for http://static.springsource.org/spring-batch/reference/html/retry.html[Spring Batch], where `spring-retry` originated.
WARNING: The default back off behavior is no back off - retries are attempted immediately.
Using a back off policy that causes threads to pause between attempts may cause performance issues, including excessive memory use and thread starvation.
In high volume environments, back off policies should be used with caution.
[[retry-config]]
====== Configuring the Retry Advice
The following examples use a simple <service-activator />> that always throws an exception:
[source,java]
----
public class FailingService {
public void service(String message) {
throw new RuntimeException("foo");
}
}
----
*Simple Stateless Retry*
This example uses the default `RetryTemplate` which has a `SimpleRetryPolicy` which tries 3 times.
There is no `BackOffPolicy` so the 3 attempts are made back-to-back-to-back with no delay between attempts.
There is no `RecoveryCallback` so, the result is to throw the exception to the caller after the final failed retry occurs.
In a _Spring Integration_ environment, this final exception might be handled using an `error-channel` on the inbound endpoint.
[source,xml]
----
<int:service-activator input-channel="input" ref="failer" method="service">
<int:request-handler-advice-chain>
<bean class="o.s.i.handler.advice.RequestHandlerRetryAdvice"/>
</request-handler-advice-chain>
</int:service-activator>
DEBUG [task-scheduler-2]preSend on channel 'input', message: [Payload=...]
DEBUG [task-scheduler-2]Retry: count=0
DEBUG [task-scheduler-2]Checking for rethrow: count=1
DEBUG [task-scheduler-2]Retry: count=1
DEBUG [task-scheduler-2]Checking for rethrow: count=2
DEBUG [task-scheduler-2]Retry: count=2
DEBUG [task-scheduler-2]Checking for rethrow: count=3
DEBUG [task-scheduler-2]Retry failed last attempt: count=3
----
*Simple Stateless Retry with Recovery*
This example adds a `RecoveryCallback` to the above example; it uses a `ErrorMessageSendingRecoverer` to send an `ErrorMessage` to a channel.
[source,xml]
----
<int:service-activator input-channel="input" ref="failer" method="service">
<int:request-handler-advice-chain>
<bean class="o.s.i.handler.advice.RequestHandlerRetryAdvice">
<property name="recoveryCallback">
<bean class="o.s.i.handler.advice.ErrorMessageSendingRecoverer">
<constructor-arg ref="myErrorChannel" />
</bean>
</property>
</bean>
</request-handler-advice-chain>
</int:int:service-activator>
DEBUG [task-scheduler-2]preSend on channel 'input', message: [Payload=...]
DEBUG [task-scheduler-2]Retry: count=0
DEBUG [task-scheduler-2]Checking for rethrow: count=1
DEBUG [task-scheduler-2]Retry: count=1
DEBUG [task-scheduler-2]Checking for rethrow: count=2
DEBUG [task-scheduler-2]Retry: count=2
DEBUG [task-scheduler-2]Checking for rethrow: count=3
DEBUG [task-scheduler-2]Retry failed last attempt: count=3
DEBUG [task-scheduler-2]Sending ErrorMessage :failedMessage:[Payload=...]
----
*Stateless Retry with Customized Policies, and Recovery*
For more sophistication, we can provide the advice with a customized `RetryTemplate`.
This example continues to use the `SimpleRetryPolicy` but it increases the attempts to 4.
It also adds an `ExponentialBackoffPolicy` where the first retry waits 1 second, the second waits 5 seconds and the third waits 25 (for 4 attempts in all).
[source,xml]
----
<int:service-activator input-channel="input" ref="failer" method="service">
<int:request-handler-advice-chain>
<bean class="o.s.i.handler.advice.RequestHandlerRetryAdvice">
<property name="recoveryCallback">
<bean class="o.s.i.handler.advice.ErrorMessageSendingRecoverer">
<constructor-arg ref="myErrorChannel" />
</bean>
</property>
<property name="retryTemplate" ref="retryTemplate" />
</bean>
</request-handler-advice-chain>
</int:service-activator>
<bean id="retryTemplate" class="org.springframework.retry.support.RetryTemplate">
<property name="retryPolicy">
<bean class="org.springframework.retry.policy.SimpleRetryPolicy">
<property name="maxAttempts" value="4" />
</bean>
</property>
<property name="backOffPolicy">
<bean class="org.springframework.retry.backoff.ExponentialBackOffPolicy">
<property name="initialInterval" value="1000" />
<property name="multiplier" value="5.0" />
<property name="maxInterval" value="60000" />
</bean>
</property>
</bean>
27.058 DEBUG [task-scheduler-1]preSend on channel 'input', message: [Payload=...]
27.071 DEBUG [task-scheduler-1]Retry: count=0
27.080 DEBUG [task-scheduler-1]Sleeping for 1000
28.081 DEBUG [task-scheduler-1]Checking for rethrow: count=1
28.081 DEBUG [task-scheduler-1]Retry: count=1
28.081 DEBUG [task-scheduler-1]Sleeping for 5000
33.082 DEBUG [task-scheduler-1]Checking for rethrow: count=2
33.082 DEBUG [task-scheduler-1]Retry: count=2
33.083 DEBUG [task-scheduler-1]Sleeping for 25000
58.083 DEBUG [task-scheduler-1]Checking for rethrow: count=3
58.083 DEBUG [task-scheduler-1]Retry: count=3
58.084 DEBUG [task-scheduler-1]Checking for rethrow: count=4
58.084 DEBUG [task-scheduler-1]Retry failed last attempt: count=4
58.086 DEBUG [task-scheduler-1]Sending ErrorMessage :failedMessage:[Payload=...]
----
*Namespace Support for Stateless Retry*
Starting with _version 4.0_, the above configuration can be greatly simplified with the namespace support for the retry advice:
[source,xml]
----
<int:service-activator input-channel="input" ref="failer" method="service">
<int:request-handler-advice-chain>
<bean ref="retrier" />
</request-handler-advice-chain>
</int:service-activator>
<int:handler-retry-advice id="retrier" max-attempts="4" recovery-channel="myErrorChannel">
<int:exponential-back-off initial="1000" multiplier="5.0" maximum="60000" />
</int:handler-retry-advice>
----
In this example, the advice is defined as a top level bean so it can be used in multiple `request-handler-advice-chain` s.
You can also define the advice directly within the chain:
[source,xml]
----
<int:service-activator input-channel="input" ref="failer" method="service">
<int:request-handler-advice-chain>
<int:retry-advice id="retrier" max-attempts="4" recovery-channel="myErrorChannel">
<int:exponential-back-off initial="1000" multiplier="5.0" maximum="60000" />
</int:retry-advice>
</request-handler-advice-chain>
</int:service-activator>
----
A `<handler-retry-advice/>` with no child element uses no back off; it can have a `fixed-back-off` or `exponential-back-off` child element.
If there is no `recovery-channel`, the exception is thrown when retries are exhausted.
The namespace can only be used with stateless retry.
For more complex environments (custom policies etc), use normal `<bean/>` definitions.
*Simple Stateful Retry with Recovery*
To make retry stateful, we need to provide the Advice with a RetryStateGenerator implementation.
This class is used to identify a message as being a resubmission so that the `RetryTemplate` can determine the current state of retry for this message.
The framework provides a `SpelExpressionRetryStateGenerator` which determines the message identifier using a SpEL expression.
This is shown below; this example again uses the default policies (3 attempts with no back off); of course, as with stateless retry, these policies can be customized.
[source,xml]
----
<int:service-activator input-channel="input" ref="failer" method="service">
<int:request-handler-advice-chain>
<bean class="o.s.i.handler.advice.RequestHandlerRetryAdvice">
<property name="retryStateGenerator">
<bean class="o.s.i.handler.advice.SpelExpressionRetryStateGenerator">
<constructor-arg value="headers['jms_messageId']" />
</bean>
</property>
<property name="recoveryCallback">
<bean class="o.s.i.handler.advice.ErrorMessageSendingRecoverer">
<constructor-arg ref="myErrorChannel" />
</bean>
</property>
</bean>
</int:request-handler-advice-chain>
</int:service-activator>
24.351 DEBUG [Container#0-1]preSend on channel 'input', message: [Payload=...]
24.368 DEBUG [Container#0-1]Retry: count=0
24.387 DEBUG [Container#0-1]Checking for rethrow: count=1
24.387 DEBUG [Container#0-1]Rethrow in retry for policy: count=1
24.387 WARN [Container#0-1]failure occurred in gateway sendAndReceive
org.springframework.integration.MessagingException: Failed to invoke handler
...
Caused by: java.lang.RuntimeException: foo
...
24.391 DEBUG [Container#0-1]Initiating transaction rollback on application exception
...
25.412 DEBUG [Container#0-1]preSend on channel 'input', message: [Payload=...]
25.412 DEBUG [Container#0-1]Retry: count=1
25.413 DEBUG [Container#0-1]Checking for rethrow: count=2
25.413 DEBUG [Container#0-1]Rethrow in retry for policy: count=2
25.413 WARN [Container#0-1]failure occurred in gateway sendAndReceive
org.springframework.integration.MessagingException: Failed to invoke handler
...
Caused by: java.lang.RuntimeException: foo
...
25.414 DEBUG [Container#0-1]Initiating transaction rollback on application exception
...
26.418 DEBUG [Container#0-1]preSend on channel 'input', message: [Payload=...]
26.418 DEBUG [Container#0-1]Retry: count=2
26.419 DEBUG [Container#0-1]Checking for rethrow: count=3
26.419 DEBUG [Container#0-1]Rethrow in retry for policy: count=3
26.419 WARN [Container#0-1]failure occurred in gateway sendAndReceive
org.springframework.integration.MessagingException: Failed to invoke handler
...
Caused by: java.lang.RuntimeException: foo
...
26.420 DEBUG [Container#0-1]Initiating transaction rollback on application exception
...
27.425 DEBUG [Container#0-1]preSend on channel 'input', message: [Payload=...]
27.426 DEBUG [Container#0-1]Retry failed last attempt: count=3
27.426 DEBUG [Container#0-1]Sending ErrorMessage :failedMessage:[Payload=...]
----
Comparing with the stateless examples, you can see that with stateful retry, the exception is thrown to the caller on each failure.
*Exception Classification for Retry*
Spring Retry has a great deal of flexibility for determining which exceptions can invoke retry.
The default configuration will retry for all exceptions and the exception classifier just looks at the top level exception.
If you configure it to, say, only retry on `BarException` and your application throws a `FooException` where the cause is a `BarException`, retry will not occur.
Since _Spring Retry 1.0.3_, the `BinaryExceptionClassifier` has a property `traverseCauses` (default `false`).
When `true` it will traverse exception causes until it finds a match or there is no cause.
To use this classifier for retry, use a `SimpleRetryPolicy` created with the constructor that takes the max attempts, the `Map` of `Exception` s and the boolean (traverseCauses), and inject this policy into the `RetryTemplate`.
[[circuit-breaker-advice]]
===== Circuit Breaker Advice
The general idea of the Circuit Breaker Pattern is that, if a service is not currently available, then don't waste time (and resources) trying to use it.
The `o.s.i.handler.advice.RequestHandlerCircuitBreakerAdvice` implements this pattern.
When the circuit breaker is in the _closed_ state, the endpoint will attempt to invoke the service.
The circuit breaker goes to the _open_ state if a certain number of consecutive attempts fail; when it is in the _open_ state, new requests will "fail fast" and no attempt will be made to invoke the service until some time has expired.
When that time has expired, the circuit breaker is set to the _half-open_ state.
When in this state, if even a single attempt fails, the breaker will immediately go to the _open_ state; if the attempt succeeds, the breaker will go to the _closed_ state, in which case, it won't go to the _open_ state again until the configured number of consecutive failures again occur.
Any successful attempt resets the state to zero failures for the purpose of determining when the breaker might go to the _open_ state again.
Typically, this Advice might be used for external services, where it might take some time to fail (such as a timeout attempting to make a network connection).
The `RequestHandlerCircuitBreakerAdvice` has two properties: `threshold` and `halfOpenAfter`.
The _threshold_ property represents the number of consecutive failures that need to occur before the breaker goes _open_.
It defaults to 5.
The _halfOpenAfter_ property represents the time after the last failure that the breaker will wait before attempting another request.
Default is 1000 milliseconds.
Example:
[source,xml]
----
<int:service-activator input-channel="input" ref="failer" method="service">
<int:request-handler-advice-chain>
<bean class="o.s.i.handler.advice.RequestHandlerCircuitBreakerAdvice">
<property name="threshold" value="2" />
<property name="halfOpenAfter" value="12000" />
</bean>
</int:request-handler-advice-chain>
</int:service-activator>
05.617 DEBUG [task-scheduler-1]preSend on channel 'input', message: [Payload=...]
05.638 ERROR [task-scheduler-1]org.springframework.messaging.MessageHandlingException: java.lang.RuntimeException: foo
...
10.598 DEBUG [task-scheduler-2]preSend on channel 'input', message: [Payload=...]
10.600 ERROR [task-scheduler-2]org.springframework.messaging.MessageHandlingException: java.lang.RuntimeException: foo
...
15.598 DEBUG [task-scheduler-3]preSend on channel 'input', message: [Payload=...]
15.599 ERROR [task-scheduler-3]org.springframework.messaging.MessagingException: Circuit Breaker is Open for ServiceActivator
...
20.598 DEBUG [task-scheduler-2]preSend on channel 'input', message: [Payload=...]
20.598 ERROR [task-scheduler-2]org.springframework.messaging.MessagingException: Circuit Breaker is Open for ServiceActivator
...
25.598 DEBUG [task-scheduler-5]preSend on channel 'input', message: [Payload=...]
25.601 ERROR [task-scheduler-5]org.springframework.messaging.MessageHandlingException: java.lang.RuntimeException: foo
...
30.598 DEBUG [task-scheduler-1]preSend on channel 'input', message: [Payload=foo...]
30.599 ERROR [task-scheduler-1]org.springframework.messaging.MessagingException: Circuit Breaker is Open for ServiceActivator
----
In the above example, the threshold is set to 2 and halfOpenAfter is set to 12 seconds; a new request arrives every 5 seconds.
You can see that the first two attempts invoked the service; the third and fourth failed with an exception indicating the circuit breaker is open.
The fifth request was attempted because the request was 15 seconds after the last failure; the sixth attempt fails immediately because the breaker immediately went to _open_.
[[expression-advice]]
===== Expression Evaluating Advice
The final supplied advice class is the `o.s.i.handler.advice.ExpressionEvaluatingRequestHandlerAdvice`.
This advice is more general than the other two advices.
It provides a mechanism to evaluate an expression on the original inbound message sent to the endpoint.
Separate expressions are available to be evaluated, either after success, or failure.
Optionally, a message containing the evaluation result, together with the input message, can be sent to a message channel.
A typical use case for this advice might be with an <ftp:outbound-channel-adapter />, perhaps to move the file to one directory if the transfer was successful, or to another directory if it fails:
The Advice has properties to set an expression when successful, an expression for failures, and corresponding channels for each.
For the successful case, the message sent to the_successChannel_ is an `AdviceMessage`, with the payload being the result of the expression evaluation, and an additional property `inputMessage` which contains the original message sent to the handler.
A message sent to the _failureChannel_ (when the handler throws an excecption) is an ErrorMessage with a payload of `MessageHandlingExpressionEvaluatingAdviceException`.
Like all `MessagingException` s, this payload has `failedMessage` and `cause` properties, as well as an additional property `evaluationResult`, containing the result of the expression evaluation.
[[custom-advice]]
==== Custom Advice Classes
In addition to the provided Advice classes above, you can implement your own Advice classes.
While you can provide any implementation of `org.aopalliance.aop.Advice`, it is generally recommended that you subclass `o.s.i.handler.advice.AbstractRequestHandlerAdvice`.
This has the benefit of avoiding writing low-level _Aspect Oriented Programming_ code as well as providing a starting point that is specifically tailored for use in this environment.
Subclasses need to implement the doInvoke() method:
[source,java]
----
/**
* Subclasses implement this method to apply behavior to the {@link MessageHandler} callback.execute()
* invokes the handler method and returns its result, or null).
* @param callback Subclasses invoke the execute() method on this interface to invoke the handler method.
* @param target The target handler.
* @param message The message that will be sent to the handler.
* @return the result after invoking the {@link MessageHandler}.
* @throws Exception
*/
protected abstract Object doInvoke(ExecutionCallback callback, Object target, Message<?> message) throws Exception;
----
The _callback_ parameter is simply a convenience to avoid subclasses dealing with AOP directly; invoking the `callback.execute()` method invokes the message handler.
The _target_ parameter is provided for those subclasses that need to maintain state for a specific handler, perhaps by maintaining that state in a `Map`, keyed by the target.
This allows the same advice to be applied to multiple handlers.
The `RequestHandlerCircuitBreakerAdvice` uses this to keep circuit breaker state for each handler.
The _message_ parameter is the message that will be sent to the handler.
While the advice cannot modify the message before invoking the handler, it can modify the payload (if it has mutable properties).
Typically, an advice would use the message for logging and/or to send a copy of the message somewhere before or after invoking the handler.
The return value would normally be the value returned by `callback.execute()`; but the advice does have the ability to modify the return value.
Note that only `AbstractReplyProducingMessageHandler` s return a value.
[source,java]
----
public class MyAdvice extends AbstractRequestHandlerAdvice {
@Override
protected Object doInvoke(ExecutionCallback callback, Object target, Message<?> message) throws Exception {
// add code before the invocation
Object result = callback.execute();
// add code after the invocation
return result;
}
}
----
[NOTE]
=====
In addition to the `execute()` method, the `ExecutionCallback` provides an additional method `cloneAndExecute()`.
This method must be used in cases where the invocation might be called multiple times within a single execution of `doInvoke()`, such as in the `RequestHandlerRetryAdvice`.
This is required because the Spring AOP `org.springframework.aop.framework.ReflectiveMethodInvocation` object maintains state of which advice in a chain was last invoked; this state must be reset for each call.
For more information, see the http://static.springsource.org/spring-framework/docs/current/javadoc-api/org/springframework/aop/framework/ReflectiveMethodInvocation.html[ReflectiveMethodInvocation] JavaDocs.
=====
[[other-advice]]
==== Other Advice Chain Elements
While the abstract class mentioned above is provided as a convenience, you can add any `Advice` to the chain, including a transaction advice.
[[advising-filters]]
==== Advising Filters
There is an additional consideration when advising `Filter` s.
By default, any discard actions (when the filter returns false) are performed _within_ the scope of the advice chain.
This could include all the flow downstream of the _discard channel_.
So, for example if an element downstream of the _discard-channel_ throws an exception, and there is a retry advice, the process will be retried.
This is also the case if_throwExceptionOnRejection_ is set to true (the exception is thrown within the scope of the advice).
Setting _discard-within-advice_ to "false" modifies this behavior and the discard (or exception) occurs after the advice chain is called.
[[advising-with-annotations]]
==== Advising Endpoints Using Annotations
When configuring certain endpoints using annotations (`@Filter`, `@ServiceActivator`, `@Splitter`, and `@Transformer`), you can supply a bean name for the advice chain in the `adviceChain` attribute.
In addition, the `@Filter` annotation also has the `discardWithinAdvice` attribute, which can be used to configure the discard behavior as discussed in <<advising-filters>>.
An example with the discard being performed after the advice is shown below.
[source,java]
----
@MessageEndpoint
public class MyAdvisedFilter {
@Filter(inputChannel="input", outputChannel="output",
adviceChain="adviceChain", discardWithinAdvice="false")
public boolean filter(String s) {
return s.contains("good");
}
}
----
[[advice-order]]
==== Ordering Advices within an Advice Chain
Advice classes are "around" advices and are applied in a nested fashion.
The first advice is the outermost, the last advice the innermost (closest to the handler being advised).
It is important to put the advice classes in the correct order to achieve the functionality you desire.
For example, let's say you want to add a retry advice and a transaction advice.
You may want to place the retry advice advice first, followed by the transaction advice.
Then, each retry will be performed in a new transaction.
On the other hand, if you want all the attempts, and any recovery operations (in the retry `RecoveryCallback`), to be scoped within the transaction, you would put the transaction advice first.
[[idempotent-receiver]]
==== Idempotent Receiver Enterprise Integration Pattern
Starting with _version 4.1_, Spring Integration provides an implementation of the http://www.eaipatterns.com/IdempotentReceiver.html[Idempotent Receiver] Enterprise Integration Pattern.
It is a _functional_ pattern and the whole _idempotency_ logic should be implemented in the application, however to simplify the decision-making, the `IdempotentReceiverInterceptor` component is provided.
This is an AOP `Advice`, which is applied to the `MessageHandler.handleMessage()` method and can `filter` a request message or mark it as a `duplicate`, according to its configuration.
Previously, users could have implemented this pattern, by using a custom MessageSelector in a `<filter/>` (<<filter>>), for example.
However, since this pattern is really behavior of an endpoint rather than being an endpoint itself, the Idempotent Receiver implementation doesn't provide an _endpoint_ component; rather, it is applied to endpoints declared in the application.
The logic of the `IdempotentReceiverInterceptor` is based on the provided `MessageSelector` and, if the message isn't accepted by that selector, it will be enriched with the `duplicateMessage` header set to `true`.
The target `MessageHandler` (or downstream flow) can consult this header to implement the correct _idempotency_ logic.
If the `IdempotentReceiverInterceptor` is configured with a `discardChannel` and/or `throwExceptionOnRejection = true`, the _duplicate_ Message won't be sent to the target `MessageHandler.handleMessage()`, but discarded.
If you simply want to discard (do nothing with) the _duplicate_ Message, the `discardChannel` should be configured with a `NullChannel`, such as the default `nullChannel` bean.
To maintain _state_ between messages and provide the ability to compare messages for the idempotency, the `MetadataStoreSelector` is provided.
It accepts a `MessageProcessor` implementation (which creates a lookup key based on the `Message`) and an optional `ConcurrentMetadataStore` (<<metadata-store>>).
See the `MetadataStoreSelector` JavaDocs for more information.
The `value` for `ConcurrentMetadataStore` also can be customized using additional `MessageProcessor`.
By default `MetadataStoreSelector` uses `timestamp` message header.
For convenience, the `MetadataStoreSelector` options are configurable directly on the `<idempotent-receiver>` component:
[source,xml]
----
<idempotent-receiver
id="" <1>
endpoint="" <2>
selector="" <3>
discard-channel="" <4>
metadata-store="" <5>
key-strategy="" <6>
key-expression="" <7>
value-strategy="" <8>
value-expression="" <9>
throw-exception-on-rejection="" /> <10>
----
<1> The id of the `IdempotentReceiverInterceptor` bean.
_Optional_.
<2> Consumer Endpoint name(s) or pattern(s) to which this interceptor will be applied.
Separate names (patterns) with commas (`,`) e.g.
`endpoint="aaa, bbb*, *ccc, *ddd*, eee*fff"`.
Endpoint bean names matching these patterns are then used to retrieve the target endpoint's `MessageHandler` bean (using its `.handler` suffix), and the `IdempotentReceiverInterceptor` will be applied to those beans.
_Required_.
<3> A `MessageSelector` bean reference.
Mutually exclusive with `metadata-store` and `key-strategy (key-expression)`.
When `selector` is not provided, one of `key-strategy` or `key-strategy-expression` is required.
<4> Identifies the channel to which to send a message when the `IdempotentReceiverInterceptor` doesn't accept it.
When omitted, duplicate messages are forwarded to the handler with a `duplicateMessage` header.
_Optional_.
<5> A `ConcurrentMetadataStore` reference.
Used by the underlying `MetadataStoreSelector`.
Mutually exclusive with `selector`.
_Optional_.
The default `MetadataStoreSelector` uses an internal `SimpleMetadataStore` which does not maintain state across application executions.
<6> A `MessageProcessor` reference.
Used by the underlying `MetadataStoreSelector`.
Evaluates an `idempotentKey` from the request Message.
Mutually exclusive with `selector` and `key-expression`.
When a `selector` is not provided, one of `key-strategy` or `key-strategy-expression` is required.
<7> A SpEL expression to populate an `ExpressionEvaluatingMessageProcessor`.
Used by the underlying `MetadataStoreSelector`.
Evaluates an `idempotentKey` using the request Message as the evaluation context root object.
Mutually exclusive with `selector` and `key-strategy`.
When a `selector` is not provided, one of `key-strategy` or `key-strategy-expression` is required.
<8> A `MessageProcessor` reference.
Used by the underlying `MetadataStoreSelector`.
Evaluates a `value` for the `idempotentKey` from the request Message.
Mutually exclusive with `selector` and `value-expression`.
By default, the 'MetadataStoreSelector' uses the 'timestamp' message header as the Metadata 'value'.
<9> A SpEL expression to populate an `ExpressionEvaluatingMessageProcessor`.
Used by the underlying `MetadataStoreSelector`.
Evaluates a `value` for the `idempotentKey` using the request Message as the evaluation context root object.
Mutually exclusive with `selector` and `value-strategy`.
By default, the 'MetadataStoreSelector' uses the 'timestamp' message header as the Metadata 'value'.
<10> Throw an exception if the `IdempotentReceiverInterceptor` rejects the message defaults to `false`.
It is applied regardless of whether or not a `discard-channel` is provided.
For Java configuration, the method level `IdempotentReceiver` annotation is provided.
It is used to mark a `method` that has a Messaging annotation (`@ServiceActivator`, `@Router` etc.) to specify which `IdempotentReceiverInterceptor` s will be applied to this endpoint:
[source,java]
----
@Bean
public IdempotentReceiverInterceptor idempotentReceiverInterceptor() {
return new IdempotentReceiverInterceptor(new MetadataStoreSelector(m ->
m.getHeaders().get(INVOICE_NBR_HEADER)));
}
@Bean
@ServiceActivator(inputChannel = "input", outputChannel = "output")
@IdempotentReceiver("idempotentReceiverInterceptor")
public MessageHandler myService() {
....
}
----

17
src/reference/asciidoc/history.adoc Normal file
View File

@@ -0,0 +1,17 @@
[[history]]
== Change History
// BE SURE TO PRECEDE ALL include:: with a blank line - see https://github.com/asciidoctor/asciidoctor/issues/1297
include::./changes-4.1-4.2.adoc[]
include::./changes-4.0-4.1.adoc[]
include::./changes-3.0-4.0.adoc[]
include::./changes-2.2-3.0.adoc[]
include::./changes-2.1-2.2.adoc[]
include::./changes-2.0-2.1.adoc[]
include::./changes-1.0-2.0.adoc[]

759
src/reference/asciidoc/http.adoc Normal file
View File

@@ -0,0 +1,759 @@
[[http]]
== HTTP Support
[[http-intro]]
=== Introduction
The HTTP support allows for the execution of HTTP requests and the processing of inbound HTTP requests.
Because interaction over HTTP is always synchronous, even if all that is returned is a 200 status code, the HTTP support consists of two gateway implementations: `HttpInboundEndpoint` and `HttpRequestExecutingMessageHandler`.
[[http-inbound]]
=== Http Inbound Gateway
To receive messages over HTTP, you need to use an _HTTP Inbound
Channel Adapter_ or _Gateway_.
To support the _HTTP Inbound Adapters_, they need to be deployed within a servlet container such as http://tomcat.apache.org/[Apache Tomcat] or http://www.eclipse.org/jetty/[Jetty].
The easiest way to do this is to use Spring's http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/web/context/support/HttpRequestHandlerServlet.html[HttpRequestHandlerServlet], by providing the following servlet definition in the _web.xml_ file:
[source,xml]
----
<servlet>
<servlet-name>inboundGateway</servlet-name>
<servlet-class>o.s.web.context.support.HttpRequestHandlerServlet</servlet-class>
</servlet>
----
Notice that the servlet name matches the bean name.
For more information on using the `HttpRequestHandlerServlet`, see chapter "http://static.springsource.org/spring/docs/current/spring-framework-reference/html/remoting.html[Remoting and web services using Spring]", which is part of the Spring Framework Reference documentation.
If you are running within a Spring MVC application, then the aforementioned explicit servlet definition is not necessary.
In that case, the bean name for your gateway can be matched against the URL path just like a Spring MVC Controller bean.
For more information, please see the chapter "http://static.springsource.org/spring/docs/current/spring-framework-reference/html/mvc.html[Web MVC framework]", which is part of the Spring Framework Reference documentation.
TIP: For a sample application and the corresponding configuration, please see the https://github.com/SpringSource/spring-integration-samples[Spring Integration Samples] repository.
It contains the https://github.com/SpringSource/spring-integration-samples/tree/master/basic/http[Http Sample] application demonstrating Spring Integration's HTTP support.
Below is an example bean definition for a simple HTTP inbound endpoint.
[source,xml]
----
<bean id="httpInbound"
class="org.springframework.integration.http.inbound.HttpRequestHandlingMessagingGateway">
<property name="requestChannel" ref="httpRequestChannel" />
<property name="replyChannel" ref="httpReplyChannel" />
</bean>
----
The `HttpRequestHandlingMessagingGateway` accepts a list of `HttpMessageConverter` instances or else relies on a default list.
The converters allow customization of the mapping from `HttpServletRequest` to `Message`.
The default converters encapsulate simple strategies, which for example will create a String message for a _POST_ request where the content type starts with "text", see the Javadoc for full details.
An additional flag (`mergeWithDefaultConverters`) can be set along with the list of custom `HttpMessageConverter` to add the default converters after the custom converters.
By default this flag is set to false, meaning that the custom converters replace the default list.
Starting with _Spring Integration 2.0_, MultiPart File support is implemented.
If the request has been wrapped as a _MultipartHttpServletRequest_, when using the default converters, that request will be converted to a Message payload that is a MultiValueMap containing values that may be byte arrays, Strings, or instances of Spring's `MultipartFile` depending on the content type of the individual parts.
NOTE: The HTTP inbound Endpoint will locate a MultipartResolver in the context if one exists with the bean name "multipartResolver" (the same name expected by Spring's DispatcherServlet).
If it does in fact locate that bean, then the support for MultipartFiles will be enabled on the inbound request mapper.
Otherwise, it will fail when trying to map a multipart-file request to a Spring Integration Message.
For more on Spring's support for MultipartResolvers, refer to the http://static.springsource.org/spring/docs/current/spring-framework-reference/html/mvc.html#mvc-multipart[Spring Reference Manual].
In sending a response to the client there are a number of ways to customize the behavior of the gateway.
By default the gateway will simply acknowledge that the request was received by sending a 200 status code back.
It is possible to customize this response by providing a 'viewName' to be resolved by the Spring MVC `ViewResolver`.
In the case that the gateway should expect a reply to the `Message` then setting the `expectReply` flag (constructor argument) will cause the gateway to wait for a reply `Message` before creating an HTTP response.
Below is an example of a gateway configured to serve as a Spring MVC Controller with a view name.
Because of the constructor arg value of TRUE, it wait for a reply.
This also shows how to customize the HTTP methods accepted by the gateway, which are _POST_ and _GET_ by default.
[source,xml]
----
<bean id="httpInbound"
class="org.springframework.integration.http.inbound.HttpRequestHandlingController">
<constructor-arg value="true" /> <!-- indicates that a reply is expected -->
<property name="requestChannel" ref="httpRequestChannel" />
<property name="replyChannel" ref="httpReplyChannel" />
<property name="viewName" value="jsonView" />
<property name="supportedMethodNames" >
<list>
<value>GET</value>
<value>DELETE</value>
</list>
</property>
</bean>
----
The reply message will be available in the Model map.
The key that is used for that map entry by default is 'reply', but this can be overridden by setting the 'replyKey' property on the endpoint's configuration.
[[http-outbound]]
=== Http Outbound Gateway
To configure the `HttpRequestExecutingMessageHandler` write a bean definition like this:
[source,xml]
----
<bean id="httpOutbound"
class="org.springframework.integration.http.outbound.HttpRequestExecutingMessageHandler">
<constructor-arg value="http://localhost:8080/example" />
<property name="outputChannel" ref="responseChannel" />
</bean>
----
This bean definition will execute HTTP requests by delegating to a `RestTemplate`.
That template in turn delegates to a list of HttpMessageConverters to generate the HTTP request body from the Message payload.
You can configure those converters as well as the ClientHttpRequestFactory instance to use:
[source,xml]
----
<bean id="httpOutbound"
class="org.springframework.integration.http.outbound.HttpRequestExecutingMessageHandler">
<constructor-arg value="http://localhost:8080/example" />
<property name="outputChannel" ref="responseChannel" />
<property name="messageConverters" ref="messageConverterList" />
<property name="requestFactory" ref="customRequestFactory" />
</bean>
----
By default the HTTP request will be generated using an instance of `SimpleClientHttpRequestFactory` which uses the JDK `HttpURLConnection`.
Use of the Apache Commons HTTP Client is also supported through the provided `CommonsClientHttpRequestFactory` which can be injected as shown above.
NOTE: In the case of the Outbound Gateway, the reply message produced by the gateway will contain all Message Headers present in the request message.
_Cookies_
Basic cookie support is provided by the _transfer-cookies_ attribute on the outbound gateway.
When set to true (default is false), a _Set-Cookie_ header received from the server in a response will be converted to _Cookie_ in the reply message.
This header will then be used on subsequent sends.
This enables simple stateful interactions, such as...
`...->logonGateway->...->doWorkGateway->...->logoffGateway->...`
If _transfer-cookies_ is false, any _Set-Cookie_ header received will remain as _Set-Cookie_ in the reply message, and will be dropped on subsequent sends.
[NOTE]
.Note: Empty Repsonse Bodies
=====
HTTP is a request/response protocol.
However the response may not have a body, just headers.
In this case, the `HttpRequestExecutingMessageHandler` produces a reply `Message` with the payload being an `org.springframework.http.ResponseEntity`, regardless of any provided `expected-response-type`.
According to the http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html[HTTP RFC Status Code Definitions], there are many statuses which identify that a response MUST NOT contain a message-body (e.g.
204 No Content).
There are also cases where calls to the same URL might, or might not, return a response body; for example, the first request to an HTTP resource returns content, but the second does not (e.g.
304 Not Modified).
In all cases, however, the `http_statusCode` message header is populated.
This can be used in some routing logic after the Http Outbound Gateway.
You could also use a`<payload-type-router/>` to route messages with an `ResponseEntity` to a different flow than that used for responses with a body.
=====
[NOTE]
.Note: expected-response-type
=====
Further to the note above regarding *empty response bodies*, if a response *does* contain a body, you must provide an appropriate `expected-response-type` attribute or, again, you will simply receive a `ResponseEntity` with no body.
The `expected-response-type` must be compatible with the (configured or default) `HttpMessageConverter` s and the `Content-Type` header in the response.
Of course, this can be an abstract class, or even an interface (such as `java.io.Serializable` when using java serialization and `Content-Type: application/x-java-serialized-object`).
=====
[[http-namespace]]
=== HTTP Namespace Support
Spring Integration provides an _http_ namespace and the corresponding schema definition.
To include it in your configuration, simply provide the following namespace declaration in your application context configuration file:
[source,xml]
----
<?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:int="http://www.springframework.org/schema/integration"
xmlns:int-http="http://www.springframework.org/schema/integration/http"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration.xsd
http://www.springframework.org/schema/integration/http
http://www.springframework.org/schema/integration/http/spring-integration-http.xsd">
...
</beans>
----
_Inbound_
The XML Namespace provides two components for handling HTTP Inbound requests.
In order to process requests without returning a dedicated response, use the _inbound-channel-adapter_:
[source,xml]
----
<int-http:inbound-channel-adapter id="httpChannelAdapter" channel="requests"
supported-methods="PUT, DELETE"/>
----
To process requests that do expect a response, use an _inbound-gateway_:
[source,xml]
----
<int-http:inbound-gateway id="inboundGateway"
request-channel="requests"
reply-channel="responses"/>
----
_Request Mapping support_
NOTE: _Spring Integration 3.0_ is improving the REST support by introducing the http://static.springsource.org/spring-integration/api/org/springframework/integration/http/inbound/IntegrationRequestMappingHandlerMapping.html[IntegrationRequestMappingHandlerMapping].
The implementation relies on the enhanced REST support provided by Spring Framework 3.1 or higher.
The parsing of the _HTTP Inbound Gateway_ or the _HTTP Inbound Channel Adapter_ registers an `integrationRequestMappingHandlerMapping` bean of type http://static.springsource.org/spring-integration/api/org/springframework/integration/http/inbound/IntegrationRequestMappingHandlerMapping.html[IntegrationRequestMappingHandlerMapping], in case there is none registered, yet.
This particular implementation of the http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/web/servlet/HandlerMapping.html[`HandlerMapping`] delegates its logic to the http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/web/servlet/mvc/method/RequestMappingInfoHandlerMapping.html[`RequestMappingInfoHandlerMapping`].
The implementation provides similar functionality as the one provided by the http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/web/bind/annotation/RequestMapping.html[`org.springframework.web.bind.annotation.RequestMapping`] annotation in Spring MVC.
NOTE: For more information, please see http://static.springsource.org/spring/docs/current/spring-framework-reference/html/mvc.html#mvc-ann-requestmapping[Mapping Requests With @RequestMapping].
For this purpose, _Spring Integration 3.0_ introduces the `<request-mapping>` sub-element.
This optional sub-element can be added to the `<http:inbound-channel-adapter>` and the `<http:inbound-gateway>`.
It works in conjunction with the `path` and `supported-methods` attributes:
[source,xml]
----
<inbound-gateway id="inboundController"
request-channel="requests"
reply-channel="responses"
path="/foo/{fooId}"
supported-methods="GET"
view-name="foo"
error-code="oops">
<request-mapping headers="User-Agent"
params="myParam=myValue"
consumes="application/json"
produces="!text/plain"/>
</inbound-gateway>
----
Based on this configuration, the namespace parser creates an instance of the `IntegrationRequestMappingHandlerMapping` (if none exists, yet), a `HttpRequestHandlingController` bean and associated with it an instance of http://static.springsource.org/spring-integration/api/org/springframework/integration/http/inbound/RequestMapping.html[`RequestMapping`], which in turn, is converted to the Spring MVC http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/web/servlet/mvc/method/RequestMappingInfo.html[`RequestMappingInfo`].
The `<request-mapping>` sub-element provides the following attributes:
* headers
* params
* consumes
* produces
With the `path` and `supported-methods` attributes of the `<http:inbound-channel-adapter>` or the `<http:inbound-gateway>`, `<request-mapping>` attributes translate directly into the respective options provided by the `org.springframework.web.bind.annotation.RequestMapping` annotation in Spring MVC.
The `<request-mapping>` sub-element allows you to configure several _Spring Integration_ HTTP Inbound Endpoints to the same `path` (or even the same `supported-methods`) and to provide different downstream message flows based on incoming HTTP requests.
Alternatively, you can also declare just one HTTP Inbound Endpoint and apply routing and filtering logic within the _Spring Integration_ flow to achieve the same result.
This allows you to get the `Message` into the flow as early as possibly, e.g.:
[source,xml]
----
<int-http:inbound-gateway request-channel="httpMethodRouter"
supported-methods="GET,DELETE"
path="/process/{entId}"
payload-expression="#pathVariables.entId"/>
<int:router input-channel="httpMethodRouter" expression="headers.http_requestMethod">
<int:mapping value="GET" channel="in1"/>
<int:mapping value="DELETE" channel="in2"/>
</int:router>
<int:service-activator input-channel="in1" ref="service" method="getEntity"/>
<int:service-activator input-channel="in2" ref="service" method="delete"/>
----
For more information regarding _Handler Mappings_, please see: http://static.springsource.org/spring/docs/current/spring-framework-reference/html/mvc.html#mvc-handlermapping[Handler Mappings].
_Response StatusCode_
Starting with _version 4.1_ the `<http:inbound-channel-adapter>` can be configured with a `status-code-expression` to override the default `200 OK` status.
The expression must return an object which can be converted to an `org.springframework.http.HttpStatus` enum value.
The `evaluationContext` has a `BeanResolver` but no variables, so the usage of this attribute is somewhat limited.
An example might be to resolve, at runtime, some scoped Bean that returns a status code value but, most likely, it will be set to a fixed value such as `status-code=expression="'204'"` (No Content), or `status-code-expression="T(org.springframework.http.HttpStatus).NO_CONTENT"`.
By default, `status-code-expression` is null meaning that the normal '200 OK' response status will be returned.
[source,xml]
----
<http:inbound-channel-adapter id="inboundController"
channel="requests" view-name="foo" error-code="oops"
status-code-expression="T(org.springframework.http.HttpStatus).ACCEPTED">
<request-mapping headers="BAR"/>
</http:inbound-channel-adapter>
----
The `<http:inbound-gateway>` resolves the 'status code' from the `http_statusCode` header of the reply Message.
_URI Template Variables and Expressions_
By Using the _path_ attribute in conjunction with the _payload-expression_ attribute as well as the _header_ sub-element, you have a high degree of flexibility for mapping inbound request data.
In the following example configuration, an Inbound Channel Adapter is configured to accept requests using the following URI: `/first-name/{firstName}/last-name/{lastName}`
Using the _payload-expression_ attribute, the URI template variable _{firstName}_ is mapped to be the Message payload, while the _{lastName}_ URI template variable will map to the _lname_ Message header.
[source,xml]
----
<int-http:inbound-channel-adapter id="inboundAdapterWithExpressions"
path="/first-name/{firstName}/last-name/{lastName}"
channel="requests"
payload-expression="#pathVariables.firstName">
<int-http:header name="lname" expression="#pathVariables.lastName"/>
</int-http:inbound-channel-adapter>
----
For more information about _URI template variables_, please see the Spring Reference Manual: http://static.springsource.org/spring/docs/current/spring-framework-reference/html/mvc.html#mvc-ann-requestmapping-uri-templates[uri template patterns].
Since _Spring Integration 3.0_, in addition to the existing `#pathVariables` and `#requestParams` variables being available in payload and header expressions, other useful variables have been added.
The entire list of available expression variables:
* _#requestParams_ - the `MultiValueMap` from the `ServletRequest` `parameterMap`.
* _#pathVariables_ - the `Map` from URI Template placeholders and their values;
* _#matrixVariables_ - the `Map` of `MultiValueMap` according to http://docs.spring.io/spring/docs/current/spring-framework-reference/html/mvc.html#mvc-ann-matrix-variables[Spring MVC Specification].
Note, _#matrixVariables_ require Spring MVC 3.2 or higher;
* _#requestAttributes_ - the `org.springframework.web.context.request.RequestAttributes` associated with the current Request;
* _#requestHeaders_ - the `org.springframework.http.HttpHeaders` object from the current Request;
* _#cookies_ - the `Map<String, Cookie>` of `javax.servlet.http.Cookie` s from the current Request.
Note, all these values (and others) can be accessed within expressions in the downstream message flow via the `ThreadLocal` `org.springframework.web.context.request.RequestAttributes` variable, if that message flow is single-threaded and lives within the request thread:
[source,xml]
----
<int-:transformer
expression="T(org.springframework.web.context.request.RequestContextHolder).
requestAttributes.request.queryString"/>
----
_Outbound_
To configure the outbound gateway you can use the namespace support as well.
The following code snippet shows the different configuration options for an outbound Http gateway.
Most importantly, notice that the 'http-method' and 'expected-response-type' are provided.
Those are two of the most commonly configured values.
The default http-method is POST, and the default response type is _null_.
With a null response type, the payload of the reply Message would contain the ResponseEntity as long as it's http status is a success (non-successful status codes will throw Exceptions).
If you are expecting a different type, such as a `String`, then provide that fully-qualified class name as shown below.
See also the note about empty response bodies in <<http-outbound>>.
IMPORTANT: Beginning with Spring Integration 2.1 the _request-timeout_ attribute of the HTTP Outbound Gateway was renamed to _reply-timeout_ to better reflect the intent.
[source,xml]
----
<int-http:outbound-gateway id="example"
request-channel="requests"
url="http://localhost/test"
http-method="POST"
extract-request-payload="false"
expected-response-type="java.lang.String"
charset="UTF-8"
request-factory="requestFactory"
reply-timeout="1234"
reply-channel="replies"/>
----
[IMPORTANT]
=====
Since _Spring Integration 2.2_, Java serialization over HTTP is no longer enabled by default.
Previously, when setting the `expected-response-type` attribute to a `Serializable` object, the `Accept` header was not properly set up.
Since _Spring Integration 2.2_, the `SerializingHttpMessageConverter` has now been updated to set the `Accept` header to `application/x-java-serialized-object`.
However, because this could cause incompatibility with existing applications, it was decided to no longer automatically add this converter to the HTTP endpoints.
If you wish to use Java serialization, you will need to add the `SerializingHttpMessageConverter` to the appropriate endpoints, using the `message-converters` attribute, when using XML configuration, or using the `setMessageConverters()` method.
Alternatively, you may wish to consider using JSON instead which is enabled by simply having `Jackson` on the classpath.
=====
Beginning with Spring Integration 2.2 you can also determine the HTTP Method dynamically using SpEL and the _http-method-expression_ attribute.
Note that this attribute is obviously murually exclusive with _http-method_ You can also use `expected-response-type-expression` attribute instead of `expected-response-type` and provide any valid SpEL expression that determines the type of the response.
[source,xml]
----
<int-http:outbound-gateway id="example"
request-channel="requests"
url="http://localhost/test"
http-method-expression="headers.httpMethod"
extract-request-payload="false"
expected-response-type-expression="payload"
charset="UTF-8"
request-factory="requestFactory"
reply-timeout="1234"
reply-channel="replies"/>
----
If your outbound adapter is to be used in a unidirectional way, then you can use an outbound-channel-adapter instead.
This means that a successful response will simply execute without sending any Messages to a reply channel.
In the case of any non-successful response status code, it will throw an exception.
The configuration looks very similar to the gateway:
[source,xml]
----
<int-http:outbound-channel-adapter id="example"
url="http://localhost/example"
http-method="GET"
channel="requests"
charset="UTF-8"
extract-payload="false"
expected-response-type="java.lang.String"
request-factory="someRequestFactory"
order="3"
auto-startup="false"/>
----
[NOTE]
=====
To specify the URL; you can use either the 'url' attribute or the 'url-expression' attribute.
The 'url' is a simple string (with placedholders for URI variables, as described below); the 'url-expression' is a SpEL expression, with the Message as the root object, enabling dynamic urls.
The url resulting from the expression evaluation can still have placeholders for URI variables.
In previous releases, some users used the place holders to replace the entire URL with a URI variable.
Changes in Spring 3.1 can cause some issues with escaped characters, such as '?'.
For this reason, it is recommended that if you wish to generate the URL entirely at runtime, you use the 'url-expression' attribute.
=====
_Mapping URI Variables_
If your URL contains URI variables, you can map them using the `uri-variable` sub-element.
This sub-element is available for the _Http Outbound Gateway_ and the _Http Outbound Channel Adapter_.
[source,xml]
----
<int-http:outbound-gateway id="trafficGateway"
url="http://local.yahooapis.com/trafficData?appid=YdnDemo&amp;zip={zipCode}"
request-channel="trafficChannel"
http-method="GET"
expected-response-type="java.lang.String">
<int-http:uri-variable name="zipCode" expression="payload.getZip()"/>
</int-http:outbound-gateway>
----
The `uri-variable` sub-element defines two attributes: `name` and `expression`.
The `name` attribute identifies the name of the URI variable, while the `expression` attribute is used to set the actual value.
Using the `expression` attribute, you can leverage the full power of the Spring Expression Language (SpEL) which gives you full dynamic access to the message payload and the message headers.
For example, in the above configuration the `getZip()` method will be invoked on the payload object of the Message and the result of that method will be used as the value for the URI variable named 'zipCode'.
Since _Spring Integration 3.0_, HTTP Outbound Endpoints support the `uri-variables-expression` attribute to specify an `Expression` which should be evaluated, resulting in a `Map` for all URI variable placeholders within the URL template.
It provides a mechanism whereby different variable expressions can be used, based on the outbound message.
This attribute is mutually exclusive with the `<uri-variable/>` sub-element:
[source,xml]
----
<int-http:outbound-gateway
url="http://foo.host/{foo}/bars/{bar}"
request-channel="trafficChannel"
http-method="GET"
uri-variables-expression="@uriVariablesBean.populate(payload)"
expected-response-type="java.lang.String"/>
----
where `uriVariablesBean` might be:
[source,java]
----
public class UriVariablesBean {
private static final ExpressionParser EXPRESSION_PARSER = new SpelExpressionParser();
public Map<String, ?> populate(Object payload) {
Map<String, Object> variables = new HashMap<String, Object>();
if (payload instanceOf String.class)) {
variables.put("foo", "foo"));
}
else {
variables.put("foo", EXPRESSION_PARSER.parseExpression("headers.bar"));
}
return variables;
}
}
----
NOTE: The `uri-variables-expression` must evaluate to a `Map`.
The values of the Map must be instances of `String` or `Expression`.
This Map is provided to an `ExpressionEvalMap` for further resolution of URI variable placeholders using those expressions in the context of the outbound `Message`.
_Controlling URI Encoding_
By default, the URL string is encoded (see http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/web/util/UriComponentsBuilder.html[UriComponentsBuilder]) to the URI object before sending the request.
In some scenarios with a non-standard URI (e.g.
the RabbitMQ Rest API) it is undesirable to perform the encoding.
The `<http:outbound-gateway/>` and `<http:outbound-channel-adapter/>` provide an `encode-uri` attribute.
To disable encoding the URL, this attribute should be set to `false` (by default it is `true`).
If you wish to partially encode some of the URL, this can be achieved using an `expression` within a `<uri-variable/>`:
[source,xml]
----
<http:outbound-gateway url="http://somehost/%2f/fooApps?bar={param}" encode-uri="false">
<http:uri-variable name="param"
expression="T(org.apache.commons.httpclient.util.URIUtil)
.encodeWithinQuery('Hellow World!')"/>
</http:outbound-gateway>
----
[[http-timeout]]
=== Timeout Handling
In the context of HTTP components, there are two timing areas that have to be considered.
Timeouts when interacting with Spring Integration Channels
Timeouts when interacting with a remote HTTP server
First, the components interact with Message Channels, for which timeouts can be specified.
For example, an HTTP Inbound Gateway will forward messages received from connected HTTP Clients to a Message Channel (Request Timeout) and consequently the HTTP Inbound Gateway will receive a reply Message from the Reply Channel (Reply Timeout) that will be used to generate the HTTP Response.
Please see the figure below for an illustration.
.How timeout settings apply to an HTTP Inbound Gateway
image::images/http-inbound-gateway.png[align="center"]
For outbound endpoints, the second thing to consider is timing while interacting with the remote server.
.How timeout settings apply to an HTTP Outbound Gateway
image::images/http-outbound-gateway.png[align="center"]
You may want to configure the HTTP related timeout behavior, when making active HTTP requests using the _HTTP Oubound Gateway_ or the _HTTP Outbound Channel Adapter_.
In those instances, these two components use Spring'shttp://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/web/client/RestTemplate.html[RestTemplate] support to execute HTTP requests.
In order to configure timeouts for the _HTTP Oubound Gateway_ and the _HTTP Outbound Channel Adapter_, you can either reference a `RestTemplate` bean directly, using the _rest-template_ attribute, or you can provide a reference to a http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/http/client/ClientHttpRequestFactory.html[ClientHttpRequestFactory] bean using the _request-factory_ attribute.
Spring provides the following implementations of the `ClientHttpRequestFactory` interface:
http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/http/client/SimpleClientHttpRequestFactory.html[SimpleClientHttpRequestFactory] - Uses standard J2SE facilities for making HTTP Requests
http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/http/client/HttpComponentsClientHttpRequestFactory.html[HttpComponentsClientHttpRequestFactory] - Uses http://hc.apache.org/httpcomponents-client-ga/[Apache HttpComponents HttpClient] (Since Spring 3.1)
http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/http/client/CommonsClientHttpRequestFactory.html[ClientHttpRequestFactory] - Uses http://hc.apache.org/httpclient-3.x/[Jakarta Commons HttpClient] (Deprecated as of Spring 3.1)
If you don't explicitly configure the _request-factory_ or _rest-template_ attribute respectively, then a default RestTemplate which uses a `SimpleClientHttpRequestFactory` will be instantiated.
[NOTE]
=====
With some JVM implementations, the handling of timeouts using the _URLConnection_ class may not be consistent.
E.g.
from the _Java™ Platform, Standard Edition 6 API Specification_ on _setConnectTimeout_: [quote]
Some non-standard implmentation of this method may ignore the specified timeout.
To see the connect timeout set, please call getConnectTimeout().
Please test your timeouts if you have specific needs.
Consider using the `HttpComponentsClientHttpRequestFactory` which, in turn, uses http://hc.apache.org/httpcomponents-client-ga/[Apache HttpComponents HttpClient] instead.
=====
IMPORTANT: When using the _Apache HttpComponents HttpClient_ with a Pooling Connection Manager, be aware that, by default, the connection manager will create no more than 2 concurrent connections per given route and no more than 20 connections in total.
For many real-world applications these limits may prove too constraining.
Refer to the Apache documentation (link above) for information about configuring this important component.
Here is an example of how to configure an _HTTP Outbound Gateway_ using a `SimpleClientHttpRequestFactory`, configured with connect and read timeouts of 5 seconds respectively:
[source,xml]
----
<int-http:outbound-gateway url="http://www.google.com/ig/api?weather={city}"
http-method="GET"
expected-response-type="java.lang.String"
request-factory="requestFactory"
request-channel="requestChannel"
reply-channel="replyChannel">
<int-http:uri-variable name="city" expression="payload"/>
</int-http:outbound-gateway>
<bean id="requestFactory"
class="org.springframework.http.client.SimpleClientHttpRequestFactory">
<property name="connectTimeout" value="5000"/>
<property name="readTimeout" value="5000"/>
</bean>
----
_HTTP Outbound Gateway_
For the _HTTP Outbound Gateway_, the XML Schema defines only the _reply-timeout_.
The _reply-timeout_ maps to the _sendTimeout_ property of the _org.springframework.integration.http.outbound.HttpRequestExecutingMessageHandler_ class.
More precisely, the property is set on the extended `AbstractReplyProducingMessageHandler` class, which ultimatelly sets the property on the _MessagingTemplate_.
The value of the _sendTimeout_ property defaults to "-1" and will be applied to the connected `MessageChannel`.
This means, that depending on the implementation, the Message Channel's_send_ method may block indefinitely.
Furthermore, the _sendTimeout_ property is only used, when the actual MessageChannel implementation has a blocking send (such as 'full' bounded QueueChannel).
_HTTP Inbound Gateway_
For the _HTTP Inbound Gateway_, the XML Schema defines the _request-timeout_ attribute, which will be used to set the _requestTimeout_ property on the `HttpRequestHandlingMessagingGateway` class (on the extended MessagingGatewaySupport class).
Secondly, the_reply-timeout_ attribute exists and it maps to the _replyTimeout_ property on the same class.
The default for both timeout properties is "1000ms".
Ultimately, the _request-timeout_ property will be used to set the _sendTimeout_ on the used `MessagingTemplate` instance.
The _replyTimeout_ property on the other hand, will be used to set the _receiveTimeout_ property on the used `MessagingTemplate` instance.
TIP: In order to simulate connection timeouts, connect to a non-routable IP address, for example 10.255.255.10.
[[http-proxy]]
=== HTTP Proxy configuration
If you are behind a proxy and need to configure proxy settings for HTTP outbound adapters and/or gateways, you can apply one of two approaches.
In most cases, you can rely on the standard Java System Properties that control the proxy settings.
Otherwise, you can explicitly configure a Spring bean for the HTTP client request factory instance.
_Standard Java Proxy configuration_
There are 3 System Properties you can set to configure the proxy settings that will be used by the HTTP protocol handler:
* _http.proxyHost_ - the host name of the proxy server.
* _http.proxyPort_ - the port number, the default value being 80.
* _http.nonProxyHosts_ - a list of hosts that should be reached directly, bypassing the proxy.
This is a list of patterns separated by '|'.
The patterns may start or end with a '*' for wildcards.
Any host matching one of these patterns will be reached through a direct connection instead of through a proxy.
And for HTTPS:
* _https.proxyHost_ - the host name of the proxy server.
* _https.proxyPort_ - the port number, the default value being 80.
For more information please refer to this document: http://download.oracle.com/javase/6/docs/technotes/guides/net/proxies.html
_Spring's SimpleClientHttpRequestFactory_
If for any reason, you need more explicit control over the proxy configuration, you can use Spring's `SimpleClientHttpRequestFactory` and configure its 'proxy' property as such:
[source,xml]
----
<bean id="requestFactory"
class="org.springframework.http.client.SimpleClientHttpRequestFactory">
<property name="proxy">
<bean id="proxy" class="java.net.Proxy">
<constructor-arg>
<util:constant static-field="java.net.Proxy.Type.HTTP"/>
</constructor-arg>
<constructor-arg>
<bean class="java.net.InetSocketAddress">
<constructor-arg value="123.0.0.1"/>
<constructor-arg value="8080"/>
</bean>
</constructor-arg>
</bean>
</property>
</bean>
----
[[http-header-mapping]]
=== HTTP Header Mappings
Spring Integration provides support for Http Header mapping for both HTTP Request and HTTP Responses.
By default all standard Http Headers as defined here http://en.wikipedia.org/wiki/List_of_HTTP_header_fields will be mapped from the message to HTTP request/response headers without further configuration.
However if you do need further customization you may provide additional configuration via convenient namespace support.
You can provide a comma-separated list of header names, and you can also include simple patterns with the '*' character acting as a wildcard.
If you do provide such values, it will override the default behavior.
Basically, it assumes you are in complete control at that point.
However, if you do want to include all of the standard HTTP headers, you can use the shortcut patterns: HTTP_REQUEST_HEADERS and HTTP_RESPONSE_HEADERS.
Here are some examples:
[source,xml]
----
<int-http:outbound-gateway id="httpGateway"
url="http://localhost/test2"
mapped-request-headers="foo, bar"
mapped-response-headers="X-*, HTTP_RESPONSE_HEADERS"
channel="someChannel"/>
<int-http:outbound-channel-adapter id="httpAdapter"
url="http://localhost/test2"
mapped-request-headers="foo, bar, HTTP_REQUEST_HEADERS"
channel="someChannel"/>
----
The adapters and gateways will use the `DefaultHttpHeaderMapper` which now provides two static factory methods for "inbound" and "outbound" adapters so that the proper direction can be applied (mapping HTTP requests/responses IN/OUT as appropriate).
If further customization is required you can also configure a `DefaultHttpHeaderMapper` independently and inject it into the adapter via the `header-mapper` attribute.
[source,xml]
----
<int-http:outbound-gateway id="httpGateway"
url="http://localhost/test2"
header-mapper="headerMapper"
channel="someChannel"/>
<bean id="headerMapper" class="o.s.i.http.support.DefaultHttpHeaderMapper">
<property name="inboundHeaderNames" value="foo*, *bar, baz"/>
<property name="outboundHeaderNames" value="a*b, d"/>
</bean>
----
Of course, you can even implement the HeaderMapper strategy interface directly and provide a reference to that if you need to do something other than what the `DefaultHttpHeaderMapper` supports.
[[http-samples]]
=== HTTP Samples
[[multipart-rest-inbound]]
==== Multipart HTTP request - RestTemplate (client) and Http Inbound Gateway (server)
This example demonstrates how simple it is to send a Multipart HTTP request via Spring's RestTemplate and receive it with a Spring Integration HTTP Inbound Adapter.
All we are doing is creating a `MultiValueMap` and populating it with multi-part data.
The `RestTemplate` will take care of the rest (no pun intended) by converting it to a `MultipartHttpServletRequest` . This particular client will send a multipart HTTP Request which contains the name of the company as well as an image file with the company logo.
[source,java]
----
RestTemplate template = new RestTemplate();
String uri = "http://localhost:8080/multipart-http/inboundAdapter.htm";
Resource s2logo = 
new ClassPathResource("org/springframework/samples/multipart/spring09_logo.png");
MultiValueMap map = new LinkedMultiValueMap();
map.add("company", "SpringSource");
map.add("company-logo", s2logo);
HttpHeaders headers = new HttpHeaders();
headers.setContentType(new MediaType("multipart", "form-data"));
HttpEntity request = new HttpEntity(map, headers);
ResponseEntity<?> httpResponse = template.exchange(uri, HttpMethod.POST, request, null);
----
That is all for the client.
On the server side we have the following configuration:
[source,xml]
----
<int-http:inbound-channel-adapter id="httpInboundAdapter"
channel="receiveChannel"
name="/inboundAdapter.htm"
supported-methods="GET, POST"/>
<int:channel id="receiveChannel"/>
<int:service-activator input-channel="receiveChannel">
<bean class="org.springframework.integration.samples.multipart.MultipartReceiver"/>
</int:service-activator>
<bean id="multipartResolver"
class="org.springframework.web.multipart.commons.CommonsMultipartResolver"/>
----
The 'httpInboundAdapter' will receive the request, convert it to a `Message` with a payload that is a `LinkedMultiValueMap`.
We then are parsing that in the 'multipartReceiver' service-activator;
[source,java]
----
public void receive(LinkedMultiValueMap<String, Object> multipartRequest){
System.out.println("### Successfully received multipart request ###");
for (String elementName : multipartRequest.keySet()) {
if (elementName.equals("company")){
System.out.println("\t" + elementName + " - " +
((String[]) multipartRequest.getFirst("company"))[0]);
}
else if (elementName.equals("company-logo")){
System.out.println("\t" + elementName + " - as UploadedMultipartFile: " +
((UploadedMultipartFile) multipartRequest
.getFirst("company-logo")).getOriginalFilename());
}
}
}
----
You should see the following output:
[source,xml]
----
### Successfully received multipart request ###
company - SpringSource
company-logo - as UploadedMultipartFile: spring09_logo.png
----

0
src/reference/docbook/images/bank-router.jpg → src/reference/asciidoc/images/bank-router.jpg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.5 KiB

After

Width:  |  Height:  |  Size: 6.5 KiB

0
src/reference/docbook/images/cafe-eip.png → src/reference/asciidoc/images/cafe-eip.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 112 KiB

After

Width:  |  Height:  |  Size: 112 KiB

0
src/reference/docbook/images/chain.png → src/reference/asciidoc/images/chain.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 41 KiB

After

Width:  |  Height:  |  Size: 41 KiB

0
src/reference/docbook/images/channel.jpg → src/reference/asciidoc/images/channel.jpg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 28 KiB

After

Width:  |  Height:  |  Size: 28 KiB

0
src/reference/docbook/images/gateway.jpg → src/reference/asciidoc/images/gateway.jpg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.6 KiB

After

Width:  |  Height:  |  Size: 3.6 KiB

0
src/reference/docbook/images/handler-endpoint.jpg → src/reference/asciidoc/images/handler-endpoint.jpg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 31 KiB

After

Width:  |  Height:  |  Size: 31 KiB

0
src/reference/docbook/images/http-inbound-gateway-pdf.png → src/reference/asciidoc/images/http-inbound-gateway-pdf.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 170 KiB

After

Width:  |  Height:  |  Size: 170 KiB

0
src/reference/docbook/images/http-inbound-gateway.png → src/reference/asciidoc/images/http-inbound-gateway.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 26 KiB

After

Width:  |  Height:  |  Size: 26 KiB

0
src/reference/docbook/images/http-outbound-gateway-pdf.png → src/reference/asciidoc/images/http-outbound-gateway-pdf.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 192 KiB

After

Width:  |  Height:  |  Size: 192 KiB

0
src/reference/docbook/images/http-outbound-gateway.png → src/reference/asciidoc/images/http-outbound-gateway.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 30 KiB

After

Width:  |  Height:  |  Size: 30 KiB

0
src/reference/docbook/images/loan-broker-eip.png → src/reference/asciidoc/images/loan-broker-eip.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 102 KiB

After

Width:  |  Height:  |  Size: 102 KiB

0
src/reference/docbook/images/message.jpg → src/reference/asciidoc/images/message.jpg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 19 KiB

After

Width:  |  Height:  |  Size: 19 KiB

0
src/reference/docbook/images/quotes-aggregator.jpg → src/reference/asciidoc/images/quotes-aggregator.jpg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.3 KiB

After

Width:  |  Height:  |  Size: 6.3 KiB

0
src/reference/docbook/images/router.jpg → src/reference/asciidoc/images/router.jpg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 19 KiB

After

Width:  |  Height:  |  Size: 19 KiB

0
src/reference/docbook/images/source-endpoint.jpg → src/reference/asciidoc/images/source-endpoint.jpg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 22 KiB

0
src/reference/docbook/images/spring-integration-amqp-sample-graph.png → src/reference/asciidoc/images/spring-integration-amqp-sample-graph.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 19 KiB

After

Width:  |  Height:  |  Size: 19 KiB

0
src/reference/docbook/images/target-endpoint.jpg → src/reference/asciidoc/images/target-endpoint.jpg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 22 KiB

0
src/reference/docbook/images/tickmark.png → src/reference/asciidoc/images/tickmark.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.0 KiB

After

Width:  |  Height:  |  Size: 4.0 KiB

62
src/reference/asciidoc/index-docinfo.xml Normal file
View File

@@ -0,0 +1,62 @@
<productname>Spring Integration</productname>
<releaseinfo>{spring-integration-version}</releaseinfo>
<authorgroup>
<author>
<firstname>Mark</firstname>
<surname>Fisher</surname>
</author><author>
<firstname>Marius</firstname>
<surname>Bogoevici</surname>
</author><author>
<firstname>Iwein</firstname>
<surname>Fuld</surname>
</author><author>
<firstname>Jonas</firstname>
<surname>Partner</surname>
</author><author>
<firstname>Oleg</firstname>
<surname>Zhurakousky</surname>
</author><author>
<firstname>Gary</firstname>
<surname>Russell</surname>
</author><author>
<firstname>Dave</firstname>
<surname>Syer</surname>
</author><author>
<firstname>Josh</firstname>
<surname>Long</surname>
</author><author>
<firstname>David</firstname>
<surname>Turanski</surname>
</author><author>
<firstname>Gunnar</firstname>
<surname>Hillert</surname>
</author><author>
<firstname>Artem</firstname>
<surname>Bilan</surname>
</author><author>
<firstname>Amol</firstname>
<surname>Nayak</surname>
</author>
</authorgroup>
<copyright>
<year>2009</year>
<year>2010</year>
<year>2011</year>
<year>2012</year>
<year>2013</year>
<year>2014</year>
<year>2015</year>
<holder>
Pivotal Software, Inc. All Rights Reserved.
</holder>
</copyright>
<legalnotice>
<para>
Copies of this document may be made for your own use and for distribution to
others, provided that you do not charge any fee for such copies and further
provided that each copy contains this Copyright Notice, whether distributed in
print or electronically.
</para>
</legalnotice>

130
src/reference/asciidoc/index.adoc Normal file
View File

@@ -0,0 +1,130 @@
[[spring-integration-reference]]
= Spring Integration Reference Manual
:toc:
include::./preface.adoc[]
[[whats-new-part]]
= What's new?
[[spring-integration-intro-new]]
For those who are already familiar with Spring Integration, this chapter provides a brief overview of the new features of version 4.2.
If you are interested in the changes and features, that were introduced in earlier versions, please see chapter:<<history>>
include::./whats-new.adoc[]
[[spring-integration-introduction]]
= Overview of Spring Integration Framework
[[spring-integration-intro]]
Spring Integration provides an extension of the Spring programming model to support the well-known http://www.eaipatterns.com/[Enterprise Integration Patterns].
It enables lightweight messaging _within_ Spring-based applications and supports integration with external systems via declarative adapters.
Those adapters provide a higher-level of abstraction over Spring's support for remoting, messaging, and scheduling.
Spring Integration's primary goal is to provide a simple model for building enterprise integration solutions while maintaining the separation of concerns that is essential for producing maintainable, testable code.
include::./overview.adoc[]
[[spring-integration-core-messaging]]
= Core Messaging
[[spring-integration-core-msg]]
This section covers all aspects of the core messaging API in Spring Integration.
Here you will learn about Messages, Message Channels, and Message Endpoints.
Many of the Enterprise Integration Patterns are covered here as well, such as Filters, Routers, Transformers, Service-Activators, Splitters, and Aggregators.
The section also contains material about System Management, including the Control Bus and Message History support.
// BE SURE TO PRECEDE ALL include:: with a blank line - see https://github.com/asciidoctor/asciidoctor/issues/1297
include::./messaging-channels.adoc[]
include::./message-construction.adoc[]
include::./message-routing.adoc[]
include::./message-transformation.adoc[]
include::./messaging-endpoints.adoc[]
include::./system-management.adoc[]
[[spring-integration-endpoints]]
= Integration Endpoints
[[spring-integration-adapters]]
This section covers the various Channel Adapters and Messaging Gateways provided by Spring Integration to support Message-based communication with external systems.
// BE SURE TO PRECEDE ALL include:: with a blank line - see https://github.com/asciidoctor/asciidoctor/issues/1297
include::./endpoint-summary.adoc[]
include::./amqp.adoc[]
include::./event.adoc[]
include::./feed.adoc[]
include::./file.adoc[]
include::./ftp.adoc[]
include::./gemfire.adoc[]
include::./http.adoc[]
include::./jdbc.adoc[]
include::./jpa.adoc[]
include::./jms.adoc[]
include::./mail.adoc[]
include::./mongodb.adoc[]
include::./mqtt.adoc[]
include::./redis.adoc[]
include::./resource.adoc[]
include::./rmi.adoc[]
include::./sftp.adoc[]
include::./stream.adoc[]
include::./syslog.adoc[]
include::./ip.adoc[]
include::./twitter.adoc[]
include::./web-sockets.adoc[]
include::./ws.adoc[]
include::./xml.adoc[]
include::./xmpp.adoc[]
// BE SURE TO PRECEDE ALL include:: with a blank line - see https://github.com/asciidoctor/asciidoctor/issues/1297
[[spring-integration-appendices]]
= Appendices
[[spring-integration-adapters-advanced]]
Advanced Topics and Additional Resources
[appendix]
include::./spel.adoc[]
[appendix]
include::./message-publishing.adoc[]
[appendix]
include::./transactions.adoc[]
[appendix]
include::./security.adoc[]
[appendix]
include::./samples.adoc[]
[appendix]
include::./configuration.adoc[]
[appendix]
include::./resources.adoc[]
[appendix]
include::./history.adoc[]

1360
src/reference/asciidoc/ip.adoc Normal file
View File

File diff suppressed because it is too large Load Diff

925
src/reference/asciidoc/jdbc.adoc Normal file
View File

@@ -0,0 +1,925 @@
[[jdbc]]
== JDBC Support
Spring Integration provides Channel Adapters for receiving and sending messages via database queries.
Through those adapters Spring Integration supports not only plain JDBC SQL Queries, but also Stored Procedure and Stored Function calls.
The following JDBC components are available by default:
* _<<jdbc-inbound-channel-adapter,Inbound Channel Adapter>>_
* _<<jdbc-outbound-channel-adapter,Outbound Channel Adapter>>_
* _<<jdbc-outbound-gateway,Outbound Gateway>>_
* _<<stored-procedure-inbound-channel-adapter,Stored Procedure Inbound Channel Adapter>>_
* _<<stored-procedure-outbound-channel-adapter,Stored Procedure Outbound Channel Adapter>>_
* _<<stored-procedure-outbound-gateway,Stored Procedure Outbound Gateway>>_
Furthermore, the Spring Integration JDBC Module also provides a _<<jdbc-message-store,JDBC Message Store>>_
[[jdbc-inbound-channel-adapter]]
=== Inbound Channel Adapter
The main function of an inbound Channel Adapter is to execute a SQL `SELECT` query and turn the result set as a message.
The message payload is the whole result set, expressed as a `List`, and the types of the items in the list depend on the row-mapping strategy that is used.
The default strategy is a generic mapper that just returns a `Map` for each row in the query result.
Optionally, this can be changed by adding a reference to a `RowMapper` instance (see the http://static.springsource.org/spring/docs/current/spring-framework-reference/html/jdbc.html[Spring JDBC] documentation for more detailed information about row mapping).
NOTE: If you want to convert rows in the SELECT query result to individual messages you can use a downstream splitter.
The inbound adapter also requires a reference to either a `JdbcTemplate` instance or a `DataSource`.
As well as the `SELECT` statement to generate the messages, the adapter above also has an `UPDATE` statement that is being used to mark the records as processed so that they don't show up in the next poll.
The update can be parameterized by the list of ids from the original select.
This is done through a naming convention by default (a column in the input result set called "id" is translated into a list in the parameter map for the update called "id").
The following example defines an inbound Channel Adapter with an update query and a `DataSource` reference.
[source,xml]
----
<int-jdbc:inbound-channel-adapter query="select * from item where status=2"
channel="target" data-source="dataSource"
update="update item set status=10 where id in (:id)" />
----
NOTE: The parameters in the update query are specified with a colon (:) prefix to the name of a parameter (which in this case is an expression to be applied to each of the rows in the polled result set).
This is a standard feature of the named parameter JDBC support in Spring JDBC combined with a convention (projection onto the polled result list) adopted in Spring Integration.
The underlying Spring JDBC features limit the available expressions (e.g.
most special characters other than period are disallowed), but since the target is usually a list of or an individual object addressable by simple bean paths this isn't unduly restrictive.
To change the parameter generation strategy you can inject a `SqlParameterSourceFactory` into the adapter to override the default behavior (the adapter has a `sql-parameter-source-factory` attribute).
Spring Integration provides a `ExpressionEvaluatingSqlParameterSourceFactory` which will create a SpEL-based parameter source, with the results of the query as the`#root` object.
(If `update-per-row` is true, the root object is the row).
If the same parameter name appears multiple times in the update query, it is evaluated only one time, and its result is cached.
You can also use a parameter source for the select query.
In this case, since there is no "result" object to evaluate against, a single parameter source is used each time (rather than using a parameter source factory).
Starting with _version 4.0_, you can use Spring to create a SpEL based parameter source as follows:
[source,xml]
----
<int-jdbc:inbound-channel-adapter query="select * from item where status=:status"
channel="target" data-source="dataSource"
select-sql-parameter-source="parameterSource" />
<bean id="parameterSource" factory-bean="parameterSourceFactory"
factory-method="createParameterSourceNoCache">
<constructor-arg value="" />
</bean>
<bean id="parameterSourceFactory"
class="o.s.integration.jdbc.ExpressionEvaluatingSqlParameterSourceFactory">
<property name="parameterExpressions">
<map>
<entry key="status" value="@statusBean.which()" />
</map>
</property>
</bean>
<bean id="statusBean" class="foo.StatusDetermination" />
----
The `value` in each parameter expression can be any valid SpEL expression.
The `#root` object for the expression evaluation is the constructor argument defined on the `parameterSource` bean.
It is static for all evaluations (in this case, an empty String).
IMPORTANT: Use the `createParameterSourceNoCache` factory method; otherwise the parameter source will cache the result of the evaluation.
Also note that, because caching is disabled, if the same parameter name appears in the select query multiple times, it will be re-evaluated for each occurrence.
==== Polling and Transactions
The inbound adapter accepts a regular Spring Integration poller as a sub element, so for instance the frequency of the polling can be controlled.
A very important feature of the poller for JDBC usage is the option to wrap the poll operation in a transaction, for example:
[source,xml]
----
<int-jdbc:inbound-channel-adapter query="..."
channel="target" data-source="dataSource" update="...">
<int:poller fixed-rate="1000">
<int:transactional/>
</int:poller>
</int-jdbc:inbound-channel-adapter>
----
NOTE: If a poller is not explicitly specified, a default value will be used (and as per normal with Spring Integration can be defined as a top level bean).
In this example the database is polled every 1000 milliseconds, and the update and select queries are both executed in the same transaction.
The transaction manager configuration is not shown, but as long as it is aware of the data source then the poll is transactional.
A common use case is for the downstream channels to be direct channels (the default), so that the endpoints are invoked in the same thread, and hence the same transaction.
Then if any of them fail, the transaction rolls back and the input data is reverted to its original state.
[[jdbc-max-rows-per-poll-versus-max-messages-per-poll]]
==== Max-rows-per-poll versus Max-messages-per-poll
The _JDBC Inbound Channel Adapter_ defines an attribute _max-rows-per-poll_.
When you specify the adapter's _Poller_, you can also define a property called _max-messages-per-poll_.
While these two attributes look similar, their meaning is quite different.
_max-messages-per-poll_ specifies the number of times the query is executed per polling interval, whereas _max-rows-per-poll_ specifies the number of rows returned for each execution.
Under normal circumstances, you would likely not want to set the Poller's _max-messages-per-poll_ property when using the _JDBC Inbound Channel Adapter_.
Its default value is _1_, which means that the _JDBC
Inbound Channel Adapter's http://static.springsource.org/spring-integration/api/org/springframework/integration/jdbc/JdbcPollingChannelAdapter.html#receive()[receive()]_ method is executed exactly once for each poll interval.
Setting the _max-messages-per-poll_ attribute to a larger value means that the query is executed that many times back to back.
For more information regarding the _max-messages-per-poll_ attribute, please see <<channel-adapter-namespace-inbound>>.
In contrast, the _max-rows-per-poll_ attribute, if greater than _0_, specifies the maximum number of rows that will be used from the query result set, per execution of the _receive()_ method.
If the attribute is set to _0_, then all rows will be included in the resulting message.
If not explicitly set, the attribute defaults to _0_.
[[jdbc-outbound-channel-adapter]]
=== Outbound Channel Adapter
The outbound Channel Adapter is the inverse of the inbound: its role is to handle a message and use it to execute a SQL query.
The message payload and headers are available by default as input parameters to the query, for instance:
[source,xml]
----
<int-jdbc:outbound-channel-adapter
query="insert into foos (id, status, name) values (:headers[id], 0, :payload[foo])"
data-source="dataSource"
channel="input"/>
----
In the example above, messages arriving on the channel labelled _input_ have a payload of a map with key _foo_, so the `[]` operator dereferences that value from the map.
The headers are also accessed as a map.
NOTE: The parameters in the query above are bean property expressions on the incoming message (not Spring EL expressions).
This behavior is part of the `SqlParameterSource` which is the default source created by the outbound adapter.
Other behavior is possible in the adapter, and requires the user to inject a different `SqlParameterSourceFactory`.
The outbound adapter requires a reference to either a `DataSource` or a `JdbcTemplate`.
It can also have a `SqlParameterSourceFactory` injected to control the binding of each incoming message to a query.
If the input channel is a direct channel, then the outbound adapter runs its query in the same thread, and therefore the same transaction (if there is one) as the sender of the message.
_Passing Parameters using SpEL Expressions_
A common requirement for most JDBC Channel Adapters is to pass parameters as part of Sql queries or Stored Procedures/Functions.
As mentioned above, these parameters are by default bean property expressions, not SpEL expressions.
However, if you need to pass SpEL expression as parameters, you must inject a `SqlParameterSourceFactory` explicitly.
The following example uses a `ExpressionEvaluatingSqlParameterSourceFactory` to achieve that requirement.
[source,xml]
----
<jdbc:outbound-channel-adapter data-source="dataSource" channel="input"
query="insert into MESSAGES (MESSAGE_ID,PAYLOAD,CREATED_DATE) \
values (:id, :payload, :createdDate)"
sql-parameter-source-factory="spelSource"/>
<bean id="spelSource"
class="o.s.integration.jdbc.ExpressionEvaluatingSqlParameterSourceFactory">
<property name="parameterExpressions">
<map>
<entry key="id" value="headers['id'].toString()"/>
<entry key="createdDate" value="new java.util.Date()"/>
<entry key="payload" value="payload"/>
</map>
</property>
</bean>
----
For further information, please also see <<sp-defining-parameter-sources>>
[[jdbc-outbound-gateway]]
=== Outbound Gateway
The outbound Gateway is like a combination of the outbound and inbound adapters: its role is to handle a message and use it to execute a SQL query and then respond with the result sending it to a reply channel.
The message payload and headers are available by default as input parameters to the query, for instance:
[source,xml]
----
<int-jdbc:outbound-gateway
update="insert into foos (id, status, name) values (:headers[id], 0, :payload[foo])"
request-channel="input" reply-channel="output" data-source="dataSource" />
----
The result of the above would be to insert a record into the "foos" table and return a message to the output channel indicating the number of rows affected (the payload is a map: `{UPDATED=1}`).
If the update query is an insert with auto-generated keys, the reply message can be populated with the generated keys by adding `keys-generated="true"` to the above example (this is not the default because it is not supported by some database platforms).
For example:
[source,xml]
----
<int-jdbc:outbound-gateway
update="insert into foos (status, name) values (0, :payload[foo])"
request-channel="input" reply-channel="output" data-source="dataSource"
keys-generated="true"/>
----
Instead of the update count or the generated keys, you can also provide a select query to execute and generate a reply message from the result (like the inbound adapter), e.g:
[source,xml]
----
<int-jdbc:outbound-gateway
update="insert into foos (id, status, name) values (:headers[id], 0, :payload[foo])"
query="select * from foos where id=:headers[$id]"
request-channel="input" reply-channel="output" data-source="dataSource"/>
----
Since _Spring Integration 2.2_ the update SQL query is no longer mandatory.
You can now solely provide a select query, using either the _query attribute_ or the _query sub-element_.
This is extremely useful if you need to actively retrieve data using e.g.
a generic Gateway or a Payload Enricher.
The reply message is then generated from the result, like the inbound adapter, and passed to the reply channel.
[source,xml]
----
<int-jdbc:outbound-gateway
query="select * from foos where id=:headers[id]"
request-channel="input"
reply-channel="output"
data-source="dataSource"/>
----
As with the channel adapters, there is also the option to provide `SqlParameterSourceFactory` instances for request and reply.
The default is the same as for the outbound adapter, so the request message is available as the root of an expression.
If keys-generated="true" then the root of the expression is the generated keys (a map if there is only one or a list of maps if multi-valued).
The outbound gateway requires a reference to either a DataSource or a JdbcTemplate.
It can also have a `SqlParameterSourceFactory` injected to control the binding of the incoming message to the query.
[[jdbc-message-store]]
=== JDBC Message Store
Spring Integration provides 2 JDBC specifc Message Store implementations.
The first one, is the `JdbcMessageStore` which is suitable to be used in conjunction with _Aggregators_ and the _Claimcheck_ pattern.
While it can be used for backing _Message Channels_ as well, you may want to consider using the `JdbcChannelMessageStore` implementation instead, as it provides a more targeted and scalable implementation.
[[jdbc-message-store-generic]]
==== The Generic JDBC Message Store
The JDBC module provides an implementation of the Spring Integration `MessageStore` (important in the Claim Check pattern) and `MessageGroupStore` (important in stateful patterns like Aggregator) backed by a database.
Both interfaces are implemented by the `JdbcMessageStore`, and there is also support for configuring store instances in XML.
For example:
[source,xml]
----
<int-jdbc:message-store id="messageStore" data-source="dataSource"/>
----
A `JdbcTemplate` can be specified instead of a `DataSource`.
Other optional attributes are show in the next example:
[source,xml]
----
<int-jdbc:message-store id="messageStore" data-source="dataSource"
lob-handler="lobHandler" table-prefix="MY_INT_"/>
----
Here we have specified a `LobHandler` for dealing with messages as large objects (e.g.
often necessary if using Oracle) and a prefix for the table names in the queries generated by the store.
The table name prefix defaults to "INT_".
[NOTE]
=====
If you plan on using *MySQL*, please use MySQL version _5.6.4_ or higher, if possible.
Prior versions do not support _fractional seconds_ for temporal data types.
Because of that, messages may not arrive in the precise FIFO order when polling from such a MySQL Message Store.
Therefore, starting with _Spring Integration 3.0_, we provide an additional set of DDL scripts for MySQL version_5.6.4_ or higher:
* schema-drop-mysql-5_6_4.sql
* schema-mysql-5_6_4.sql
For more information, please see: http://dev.mysql.com/doc/refman/5.6/en/fractional-seconds.html[Fractional Seconds in Time Values].
Also important, please ensure that you use an up-to-date version of the JDBC driver for MySQL (Connector/J), e.g.
version_5.1.24_ or higher.
=====
[[jdbc-message-store-channels]]
==== Backing Message Channels
If you intend backing _Message Channels_ using JDBC, it is recommended to use the provided `JdbcChannelMessageStore` implementation instead.
It can only be used in conjunction with _Message Channels_.
*Supported Databases*
The `JdbcChannelMessageStore` uses database specific SQL queries to retrieve messages from the database.
Therefore, users must set the `ChannelMessageStoreQueryProvider` property on the `JdbcChannelMessageStore`.
This `channelMessageStoreQueryProvider` provides the SQL queries and Spring Integration provides support for the following relational databases:
* PostgreSQL
* HSQLDB
* MySQL
* Oracle
* Derby
If your database is not listed, you can easily extend the `AbstractChannelMessageStoreQueryProvider` class and provide your own custom queries.
Since _version 4.0_, the `MESSAGE_SEQUENCE` column has been added to the table to ensure first-in-first-out (FIFO) queueing even when messages are stored in the same millisecond.
[IMPORTANT]
=====
Generally it is not recommended to use a relational database for the purpose of queuing.
Instead, if possible, consider using either JMS or AMQP backed channels instead.
For further reference please see the following resources:
* https://www.engineyard.com/blog/2011/5-subtle-ways-youre-using-mysql-as-a-queue-and-why-itll-bite-you/[5 subtle ways you’re using MySQL as a queue, and why it’ll bite you].
* http://mikehadlow.blogspot.com/2012/04/database-as-queue-anti-pattern.html[The Database As Queue Anti-Pattern].
=====
*Concurrent Polling*
When polling a _Message Channel_, you have the option to configure the associated `Poller` with a `TaskExecutor` reference.
[IMPORTANT]
=====
Keep in mind, though, that if you use a JDBC backed _Message Channel_ and you are planning on polling the channel and consequently the message store transactionally with multiple threads, you should ensure that you use a relational database that supportshttp://en.wikipedia.org/wiki/Multiversion_concurrency_control[Multiversion Concurrency Control] (MVCC).
Otherwise, locking may be an issue and the performance, when using multiple threads, may not materialize as expected.
For example Apache Derby is problematic in that regard.
To achieve better JDBC queue throughput, and avoid issues when different threads may poll the same `Message` from the queue, it is *important* to set the `usingIdCache` property of `JdbcChannelMessageStore` to `true` when using databases that do not support MVCC:
=====
[source,xml]
----
…
<bean id="queryProvider"
class="o.s.i.jdbc.store.channel.PostgresChannelMessageStoreQueryProvider"/>
<int:transaction-synchronization-factory id="syncFactory">
<int:after-commit expression="@store.removeFromIdCache(headers.id.toString())" />
<int:after-rollback expression="@store.removeFromIdCache(headers.id.toString())"/>
</int:transaction-synchronization-factory>
<task:executor id="pool" pool-size="10"
queue-capacity="10" rejection-policy="CALLER_RUNS" />
<bean id="store" class="o.s.i.jdbc.store.JdbcChannelMessageStore">
<property name="dataSource" ref="dataSource"/>
<property name="channelMessageStoreQueryProvider" ref="queryProvider"/>
<property name="region" value="TX_TIMEOUT"/>
<property name="usingIdCache" value="true"/>
</bean>
<int:channel id="inputChannel">
<int:queue message-store="store"/>
</int:channel>
<int:bridge input-channel="inputChannel" output-channel="outputChannel">
<int:poller fixed-delay="500" receive-timeout="500"
max-messages-per-poll="1" task-executor="pool">
<int:transactional propagation="REQUIRED" synchronization-factory="syncFactory"
isolation="READ_COMMITTED" transaction-manager="transactionManager" />
</int:poller>
</int:bridge>
<int:channel id="outputChannel" />
…
----
*Priority Channel*
Starting with _version 4.0_, the `JdbcChannelMessageStore` implements `PriorityCapableChannelMessageStore` and provides the `priorityEnabled` option allowing it to be used as a `message-store` reference for `priority-queue` s.
For this purpose, the `INT_CHANNEL_MESSAGE` has a `MESSAGE_PRIORITY` column to store the value of `PRIORITY` Message header.
In addition, a new `MESSAGE_SEQUENCE` column is also provided to achieve a robust first-in-first-out (FIFO) polling mechanism, even when multiple messages are stored with the same priority in the same millisecond.
Messages are polled (selected) from the database with `order by MESSAGE_PRIORITY DESC NULLS LAST, CREATED_DATE, MESSAGE_SEQUENCE`.
NOTE: It's not recommended to use the same `JdbcChannelMessageStore` bean for priority and non-priority queue channel, because `priorityEnabled` option applies to the entire store and proper FIFO queue semantics will not be retained for the queue channel.
However the same `INT_CHANNEL_MESSAGE` table, and even `region`, can be used for both `JdbcChannelMessageStore` types.
To configure that scenario, simply extend one message store bean from the other:
[source,xml]
----
<bean id="channelStore" class="o.s.i.jdbc.store.JdbcChannelMessageStore">
<property name="dataSource" ref="dataSource"/>
<property name="channelMessageStoreQueryProvider" ref="queryProvider"/>
</bean>
<int:channel id="queueChannel">
<int:queue message-store="store"/>
</int:channel>
<bean id="priorityStore" parent="channelStore">
<property name="priorityEnabled" value="true"/>
</bean>
<int:channel id="priorityChannel">
<int:priority-queue message-store="priorityStore"/>
</int:channel>
----
==== Initializing the Database
Spring Integration ships with some sample scripts that can be used to initialize a database.
In the spring-integration-jdbc JAR file you will find scripts in the `org.springframework.integration.jdbc` and in the `org.springframework.integration.jdbc.store.channel` package: there is a create and a drop script example for a range of common database platforms.
A common way to use these scripts is to reference them in a http://static.springsource.org/spring/docs/current/spring-framework-reference/html/jdbc.html#jdbc-intializing-datasource[Spring JDBC data source initializer].
Note that the scripts are provided as samples or specifications of the the required table and column names.
You may find that you need to enhance them for production use (e.g.
with index declarations).
==== Partitioning a Message Store
It is common to use a `JdbcMessageStore` as a global store for a group of applications, or nodes in the same application.
To provide some protection against name clashes, and to give control over the database meta-data configuration, the message store allows the tables to be partitioned in two ways.
One is to use separate table names, by changing the prefix as described above, and the other is to specify a "region" name for partitioning data within a single table.
An important use case for this is when the MessageStore is managing persistent queues backing a Spring Integration Message Channel.
The message data for a persistent channel is keyed in the store on the channel name, so if the channel names are not globally unique then there is the danger of channels picking up data that was not intended for them.
To avoid this, the message store _region_ can be used to keep data separate for different physical channels that happen to have the same logical name.
[[stored-procedures]]
=== Stored Procedures
In certain situations plain JDBC support is not sufficient.
Maybe you deal with legacy relational database schemas or you have complex data processing needs, but ultimately you have to use http://en.wikipedia.org/wiki/Stored_procedure[Stored Procedures] or Stored Functions.
Since Spring Integration 2.1, we provide three components in order to execute Stored Procedures or Stored Functions:
* Stored Procedures Inbound Channel Adapter
* Stored Procedures Outbound Channel Adapter
* Stored Procedures Outbound Gateway
[[sp-supported-databases]]
==== Supported Databases
In order to enable calls to _Stored Procedures_ and _Stored Functions_, the Stored Procedure components use the http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/jdbc/core/simple/SimpleJdbcCall.html[`org.springframework.jdbc.core.simple.SimpleJdbcCall`] class.
Consequently, the following databases are fully supported for executing Stored Procedures:
* Apache Derby
* DB2
* MySQL
* Microsoft SQL Server
* Oracle
* PostgreSQL
* Sybase
If you want to execute Stored Functions instead, the following databases are fully supported:
* MySQL
* Microsoft SQL Server
* Oracle
* PostgreSQL
[NOTE]
=====
Even though your particular database may not be fully supported, chances are, that you can use the Stored Procedure Spring Integration components quite successfully anyway, provided your RDBMS supports Stored Procedures or Functions.
As a matter of fact, some of the provided integration tests use the http://www.h2database.com/[H2 database].
Nevertheless, it is very important to thoroughly test those usage scenarios.
=====
[[sp-configuration]]
==== Configuration
The Stored Procedure components provide full XML Namespace support and configuring the components is similar as for the general purpose JDBC components discussed earlier.
[[sp-common-config-params]]
==== Common Configuration Attributes
Certain configuration parameters are shared among all Stored Procedure components and are described below:
*auto-startup*
Lifecycle attribute signaling if this component should be started during Application Context startup.
Defaults to `true`.
_Optional_.
*data-source*
Reference to a `javax.sql.DataSource`, which is used to access the database._Required_.
*id*
Identifies the underlying Spring bean definition, which is an instance of either `EventDrivenConsumer` or `PollingConsumer`, depending on whether the Outbound Channel Adapter's `channel` attribute references a `SubscribableChannel` or a `PollableChannel`.
_Optional_.
*ignore-column-meta-data*
For fully supported databases, the underlying http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/jdbc/core/simple/SimpleJdbcCall.html[`SimpleJdbcCall`] class can automatically retrieve the parameter information for the to be invoked Stored Procedure or Function from the JDBC Meta-data.
However, if the used database does not support meta data lookups or if you like to provide customized parameter definitions, this flag can be set to `true`.
It defaults to `false`.
_Optional_.
*is-function*
If `true`, a SQL Function is called.
In that case the `stored-procedure-name` or `stored-procedure-name-expression` attributes define the name of the called function.
Defaults to `false`.
_Optional_.
*stored-procedure-name*
The attribute specifies the name of the stored procedure.
If the `is-function` attribute is set to `true`, this attribute specifies the function name instead.
Either this property or _stored-procedure-name-expression_ must be specified.
*stored-procedure-name-expression*
This attribute specifies the name of the stored procedure using a SpEL expression.
Using SpEL you have access to the full message (if available), including its headers and payload.
You can use this attribute to invoke different Stored Procedures at runtime.
For example, you can provide Stored Procedure names that you would like to execute as a Message Header.
The expression must resolve to a String.
If the `is-function` attribute is set to `true`, this attribute specifies a Stored Function.
Either this property or _stored-procedure-name_ must be specified.
*jdbc-call-operations-cache-size*
Defines the maximum number of cached `SimpleJdbcCallOperations` instances.
Basically, for each Stored Procedure Name a newhttp://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/jdbc/core/simple/SimpleJdbcCallOperations.html[`SimpleJdbcCallOperations`] instance is created that in return is being cached.
NOTE: The _stored-procedure-name-expression_ attribute and the _jdbc-call-operations-cache-size_ were added with Spring Integration 2.2.
The default cache size is _10_.
A value of _0_ disables caching.
Negative values are not permitted.
If you enable JMX, statistical information about the _
jdbc-call-operations-cache_ is exposed as MBean.
Please see <<jmx-mbean-exporter>> for more information.
*sql-parameter-source-factory* (Not available for the Stored Procedure Inbound Channel Adapter.)
Reference to a `SqlParameterSourceFactory`.
By default bean properties of the passed in `Message` payload will be used as a source for the Stored Procedure's input parameters using a `BeanPropertySqlParameterSourceFactory`.
This may be sufficient for basic use cases.
For more sophisticated options, consider passing in one or more `ProcedureParameter`.
Please also refer to <<sp-defining-parameter-sources>>.
_Optional_.
*use-payload-as-parameter-source* (Not available for the Stored Procedure Inbound Channel Adapter.)
If set to `true`, the payload of the Message will be used as a source for providing parameters.
If false, however, the entire Message will be available as a source for parameters.
If no Procedure Parameters are passed in, this property will default to `true`.
This means that using a default `BeanPropertySqlParameterSourceFactory` the bean properties of the payload will be used as a source for parameter values for the to-be-executed Stored Procedure or Stored Function.
However, if Procedure Parameters are passed in, then this property will by default evaluate to `false`.
`ProcedureParameter` allow for SpEL Expressions to be provided and therefore it is highly beneficial to have access to the entire Message.
The property is set on the underlying `StoredProcExecutor`.
_Optional_.
[[sp-common-config-subelements]]
==== Common Configuration Sub-Elements
The Stored Procedure components share a common set of sub-elements to define and pass parameters to Stored Procedures or Functions.
The following elements are available:
* parameter
* returning-resultset
* sql-parameter-definition
* poller
*parameter*
Provides a mechanism to provide Stored Procedure parameters.
Parameters can be either static or provided using a SpEL Expressions._Optional_.
[source,xml]
----
<int-jdbc:parameter name="" <1>
type="" <2>
value=""/> <3>
<int-jdbc:parameter name=""
expression=""/> <4>
----
<1> The name of the parameter to be passed into the Stored Procedure or Stored Function._Required_.
<2> This attribute specifies the type of the value.
If nothing is provided this attribute will default to `java.lang.String`.
This attribute is only used when the `value` attribute is used._Optional_.
<3> The value of the parameter.
You have to provider either this attribute or the `expression` attribute must be provided instead._Optional_.
<4> Instead of the `value` attribute, you can also specify a SpEL expression for passing the value of the parameter.
If you specify the `expression` the `value` attribute is not allowed.
_Optional_.
*returning-resultset*
Stored Procedures may return multiple resultsets.
By setting one or more `returning-resultset` elements, you can specify `RowMappers` in order to convert each returned `ResultSet` to meaningful objects.
_Optional_.
[source,xml]
----
<int-jdbc:returning-resultset name="" row-mapper="" />
----
*sql-parameter-definition*
If you are using a database that is fully supported, you typically don't have to specify the Stored Procedure parameter definitions.
Instead, those parameters can be automatically derived from the JDBC Meta-data.
However, if you are using databases that are not fully supported, you must set those parameters explicitly using the `sql-parameter-definition` sub-element.
You can also choose to turn off any processing of parameter meta data information obtained via JDBC using the `ignore-column-meta-data` attribute.
[source,xml]
----
<int-jdbc:sql-parameter-definition
name="" <1>
direction="IN" <2>
type="STRING" <3>
scale="5" <4>
type-name="FOO_STRUCT" <5>
return-type="fooSqlReturnType"/> <6>
----
<1> Specifies the name of the SQL parameter.
_Required_.
<2> Specifies the direction of the SQL parameter definition.
Defaults to `IN`.
Valid values are: `IN`, `OUT` and `INOUT`.
If your procedure is returning ResultSets, please use the `returning-resultset` element.
_Optional_.
<3> The SQL type used for this SQL parameter definition.
Will translate into the integer value as defined by java.sql.Types.
Alternatively you can provide the integer value as well.
If this attribute is not explicitly set, then it will default to 'VARCHAR'._Optional_.
<4> The scale of the SQL parameter.
Only used for numeric and decimal parameters._Optional_.
<5> The typeName for types that are user-named like: STRUCT, DISTINCT, JAVA_OBJECT, named array types.
This attribute is mutually exclusive with the _scale_ attribute.
_Optional_.
<6> The reference to a custom value handler for complex types.
An implementation of http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/jdbc/core/SqlReturnType.html[SqlReturnType].
This attribute is mutually exclusive with the _scale_ attribute and is applicable for OUT(INOUT)-parameters only._Optional_.
*poller*
Allows you to configure a Message Poller if this endpoint is a `PollingConsumer`.
_Optional_.
[[sp-defining-parameter-sources]]
==== Defining Parameter Sources
Parameter Sources govern the techniques of retrieving and mapping the Spring Integration Message properties to the relevant Stored Procedure input parameters.
The Stored Procedure components follow certain rules.
By default bean properties of the passed in `Message` payload will be used as a source for the Stored Procedure's input parameters.
In that case a `BeanPropertySqlParameterSourceFactory` will be used.
This may be sufficient for basic use cases.
The following example illustrates that default behavior.
IMPORTANT: Please be aware that for the "automatic" lookup of bean properties using the `BeanPropertySqlParameterSourceFactory` to work, your bean properties must be defined in lower case.
This is due to the fact that in `org.springframework.jdbc.core.metadata.CallMetaDataContext` (method matchInParameterValuesWithCallParameters()), the retrieved Stored Procedure parameter declarations are converted to lower case.
As a result, if you have camel-case bean properties such as "lastName", the lookup will fail.
In that case, please provide an explicit `ProcedureParameter`.
Let's assume we have a payload that consists of a simple bean with the following three properties: _id_, _name_ and _description_.
Furthermore, we have a simplistic Stored Procedure called _INSERT_COFFEE_ that accepts three input parameters: _id_, _name_ and _description_.
We also use a fully supported database.
In that case the following configuration for a Stored Procedure Oubound Adapter will be sufficient:
[source,xml]
----
<int-jdbc:stored-proc-outbound-channel-adapter data-source="dataSource"
channel="insertCoffeeProcedureRequestChannel"
stored-procedure-name="INSERT_COFFEE"/>
----
For more sophisticated options consider passing in one or more `ProcedureParameter`.
If you do provide `ProcedureParameter` explicitly, then as default an `ExpressionEvaluatingSqlParameterSourceFactory` will be used for parameter processing in order to enable the full power of SpEL expressions.
Furthermore, if you need even more control over how parameters are retrieved, consider passing in a custom implementation of a `SqlParameterSourceFactory` using the `sql-parameter-source-factory` attribute.
[[stored-procedure-inbound-channel-adapter]]
==== Stored Procedure Inbound Channel Adapter
[source,xml]
----
<int-jdbc:stored-proc-inbound-channel-adapter
channel="" <1>
stored-procedure-name=""
data-source=""
auto-startup="true"
id=""
ignore-column-meta-data="false"
is-function="false"
max-rows-per-poll="" <2>
skip-undeclared-results="" <3>
return-value-required="false" <4>
<int:poller/>
<int-jdbc:sql-parameter-definition name="" direction="IN"
type="STRING"
scale=""/>
<int-jdbc:parameter name="" type="" value=""/>
<int-jdbc:parameter name="" expression=""/>
<int-jdbc:returning-resultset name="" row-mapper="" />
</int-jdbc:stored-proc-inbound-channel-adapter>
----
<1> Channel to which polled messages will be sent.
If the stored procedure or function does not return any data, the payload of the Message will be Null.
_Required_.
<2> Limits the number of rows extracted per query.
Otherwise all rows are extracted into the outgoing message._Optional_.
<3> If this attribute is set to `true`, then all results from a stored procedure call that don't have a corresponding `SqlOutParameter` declaration will be bypassed.
E.g. Stored Procedures may return an update count value, even though your Stored Procedure only declared a single result parameter.
The exact behavior depends on the used database.
The value is set on the underlying `JdbcTemplate`.
Few developers will probably ever want to process update counts, thus the value defaults to `true`.
_Optional_.
<4> Indicates whether this procedure's return value should be included.
Since _Spring Integration 3.0.__Optional_.
NOTE: When you declare a Poller, you may notice the Poller's _max-messages-per-poll_ attribute.
For information about how it relates to the _max-rows-per-poll_ attribute of the _Stored Procedure Inbound Channel Adapter_, please see <<jdbc-max-rows-per-poll-versus-max-messages-per-poll>> for a thourough discussion.
The meaning of the attributes is the same as for the _JDBC Inbound Channel Adapter_.
[[stored-procedure-outbound-channel-adapter]]
==== Stored Procedure Outbound Channel Adapter
[source,xml]
----
<int-jdbc:stored-proc-outbound-channel-adapter channel="" <1>
stored-procedure-name=""
data-source=""
auto-startup="true"
id=""
ignore-column-meta-data="false"
order="" <2>
sql-parameter-source-factory=""
use-payload-as-parameter-source="">
<int:poller fixed-rate=""/>
<int-jdbc:sql-parameter-definition name=""/>
<int-jdbc:parameter name=""/>
</int-jdbc:stored-proc-outbound-channel-adapter>
----
<1> The receiving Message Channel of this endpoint.
_Required_.
<2> Specifies the order for invocation when this endpoint is connected as a subscriber to a channel.
This is particularly relevant when that channel is using a _failover_ dispatching strategy.
It has no effect when this endpoint itself is a Polling Consumer for a channel with a queue.
_Optional_.
[[stored-procedure-outbound-gateway]]
==== Stored Procedure Outbound Gateway
[source,xml]
----
<int-jdbc:stored-proc-outbound-gateway request-channel="" <1>
stored-procedure-name=""
data-source=""
auto-startup="true"
id=""
ignore-column-meta-data="false"
is-function="false"
order=""
reply-channel="" <2>
reply-timeout="" <3>
return-value-required="false" <4>
skip-undeclared-results="" <5>
sql-parameter-source-factory=""
use-payload-as-parameter-source="">
<int-jdbc:sql-parameter-definition name="" direction="IN"
type=""
scale="10"/>
<int-jdbc:sql-parameter-definition name=""/>
<int-jdbc:parameter name="" type="" value=""/>
<int-jdbc:parameter name="" expression=""/>
<int-jdbc:returning-resultset name="" row-mapper="" />
----
<1> The receiving Message Channel of this endpoint.
_Required_.
<2> Message Channel to which replies should be sent, after receiving the database response._Optional_.
<3> Allows you to specify how long this gateway will wait for the reply message to be sent successfully before throwing an exception.
Keep in mind that when sending to a `DirectChannel`, the invocation will occur in the sender's thread so the failing of the send operation may be caused by other components further downstream.
By default the Gateway will wait indefinitely.
The value is specified in milliseconds._Optional_.
<4> Indicates whether this procedure's return value should be included._Optional_.
<5> If the `skip-undeclared-results` attribute is set to `true`, then all results from a stored procedure call that don't have a corresponding `SqlOutParameter` declaration will be bypassed.
E.g. Stored Procedures may return an update count value, even though your Stored Procedure only declared a single result parameter.
The exact behavior depends on the used database.
The value is set on the underlying `JdbcTemplate`.
Few developers will probably ever want to process update counts, thus the value defaults to `true`.
_Optional_.
[[sp-examples]]
==== Examples
In the following two examples we call http://db.apache.org/derby/[Apache Derby] Stored Procedures.
The first procedure will call a Stored Procedure that returns a `ResultSet`, and using a `RowMapper` the data is converted into a domain object, which then becomes the Spring Integration message payload.
In the second sample we call a Stored Procedure that uses Output Parameters instead, in order to return data.
[NOTE]
=====
Please have a look at the _Spring Integration Samples_ project, located at null
The project contains the Apache Derby example referenced here, as well as instruction on how to run it.
The_Spring Integration Samples_ project also provides anhttps://github.com/SpringSource/spring-integration-samples/tree/master/intermediate/stored-procedures-oracle[example] using Oracle Stored Procedures.
=====
In the first example, we call a Stored Procedure named _FIND_ALL_COFFEE_BEVERAGES_ that does not define any input parameters but which returns a `ResultSet`.
In Apache Derby, Stored Procedures are implemented using Java.
Here is the method signature followed by the corresponding Sql:
[source,java]
----
public static void findAllCoffeeBeverages(ResultSet[] coffeeBeverages)
throws SQLException {
...
}
----
[source,xml]
----
CREATE PROCEDURE FIND_ALL_COFFEE_BEVERAGES() \
PARAMETER STYLE JAVA LANGUAGE JAVA MODIFIES SQL DATA DYNAMIC RESULT SETS 1 \
EXTERNAL NAME 'org.springframework.integration.jdbc.storedproc.derby.DerbyStoredProcedures.findAllCoffeeBeverages';
----
In Spring Integration, you can now call this Stored Procedure using e.g.
a `stored-proc-outbound-gateway`
[source,xml]
----
<int-jdbc:stored-proc-outbound-gateway id="outbound-gateway-storedproc-find-all"
data-source="dataSource"
request-channel="findAllProcedureRequestChannel"
expect-single-result="true"
stored-procedure-name="FIND_ALL_COFFEE_BEVERAGES">
<int-jdbc:returning-resultset name="coffeeBeverages"
row-mapper="org.springframework.integration.support.CoffeBeverageMapper"/>
</int-jdbc:stored-proc-outbound-gateway>
----
In the second example, we call a Stored Procedure named _FIND_COFFEE_ that has one input parameter.
Instead of returning a ResultSet, an output parameter is used:
[source,java]
----
public static void findCoffee(int coffeeId, String[] coffeeDescription)
throws SQLException {
...
}
----
[source,sql]
----
CREATE PROCEDURE FIND_COFFEE(IN ID INTEGER, OUT COFFEE_DESCRIPTION VARCHAR(200)) \
PARAMETER STYLE JAVA LANGUAGE JAVA EXTERNAL NAME \
'org.springframework.integration.jdbc.storedproc.derby.DerbyStoredProcedures.findCoffee';
----
In Spring Integration, you can now call this Stored Procedure using e.g.
a `stored-proc-outbound-gateway`
[source,xml]
----
<int-jdbc:stored-proc-outbound-gateway id="outbound-gateway-storedproc-find-coffee"
data-source="dataSource"
request-channel="findCoffeeProcedureRequestChannel"
skip-undeclared-results="true"
stored-procedure-name="FIND_COFFEE"
expect-single-result="true">
<int-jdbc:parameter name="ID" expression="payload" />
</int-jdbc:stored-proc-outbound-gateway>
----

540
src/reference/asciidoc/jms.adoc Normal file
View File

@@ -0,0 +1,540 @@
[[jms]]
== JMS Support
Spring Integration provides Channel Adapters for receiving and sending JMS messages.
There are actually two JMS-based inbound Channel Adapters.
The first uses Spring's `JmsTemplate` to receive based on a polling period.
The second is "message-driven" and relies upon a Spring MessageListener container.
There is also an outbound Channel Adapter which uses the `JmsTemplate` to convert and send a JMS Message on demand.
As you can see from above by using `JmsTemplate` and `MessageListener` container Spring Integration relies on Spring's JMS support.
This is important to understand since most of the attributes exposed on these adapters will configure the underlying Spring's `JmsTemplate` and/or `MessageListener` container.
For more details about `JmsTemplate` and `MessageListener` container please refer to http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/jms.html[Spring JMS documentation].
Whereas the JMS Channel Adapters are intended for unidirectional Messaging (send-only or receive-only), Spring Integration also provides inbound and outbound JMS Gateways for request/reply operations.
The inbound gateway relies on one of Spring's MessageListener container implementations for Message-driven reception that is also capable of sending a return value to the `reply-to` Destination as provided by the received Message.
The outbound Gateway sends a JMS Message to a `request-destination` (or `request-destination-name` or `request-destination-expression`) and then receives a reply Message.
The `reply-destination` reference (or `reply-destination-name` or `reply-destination-expression`) can be configured explicitly or else the outbound gateway will use a JMS http://docs.oracle.com/javaee/6/api/javax/jms/TemporaryQueue.html[TemporaryQueue].
Prior to _Spring Integration 2.2_, if necessary, a `TemporaryQueue` was created (and removed) for each request/reply.
Beginning with _Spring Integration 2.2_, the outbound gateway can be configured to use a `MessageListener` container to receive replies instead of directly using a new (or cached) `Consumer` to receive the reply for each request.
When so configured, and no explicit reply destination is provided, a single `TemporaryQueue` is used for each gateway instead of one for each request.
[[jms-inbound-channel-adapter]]
=== Inbound Channel Adapter
The inbound Channel Adapter requires a reference to either a single `JmsTemplate` instance or both `ConnectionFactory` and `Destination` (a 'destinationName' can be provided in place of the 'destination' reference).
The following example defines an inbound Channel Adapter with a `Destination` reference.
[source,xml]
----
<int-jms:inbound-channel-adapter id="jmsIn" destination="inQueue" channel="exampleChannel">
<int:poller fixed-rate="30000"/>
</int-jms:inbound-channel-adapter>
----
TIP: Notice from the configuration that the inbound-channel-adapter is a Polling Consumer.
That means that it invokes receive() when triggered.
This should only be used in situations where polling is done relatively infrequently and timeliness is not important.
For all other situations (a vast majority of JMS-based use-cases), the _message-driven-channel-adapter_ described below is a better option.
NOTE: All of the JMS adapters that require a reference to the ConnectionFactory will automatically look for a bean named "connectionFactory" by default.
That is why you don't see a "connection-factory" attribute in many of the examples.
However, if your JMS ConnectionFactory has a different bean name, then you will need to provide that attribute.
If 'extract-payload' is set to true (which is the default), the received JMS Message will be passed through the MessageConverter.
When relying on the default SimpleMessageConverter, this means that the resulting Spring Integration Message will have the JMS Message's body as its payload.
A JMS TextMessage will produce a String-based payload, a JMS BytesMessage will produce a byte array payload, and a JMS ObjectMessage's Serializable instance will become the Spring Integration Message's payload.
If instead you prefer to have the raw JMS Message as the Spring Integration Message's payload, then set 'extract-payload' to false.
[source,xml]
----
<int-jms:inbound-channel-adapter id="jmsIn"
destination="inQueue"
channel="exampleChannel"
extract-payload="false"/>
<int:poller fixed-rate="30000"/>
</int-jms:inbound-channel-adapter>
----
[[jms-ib-transactions]]
==== Transactions
Starting with _version 4.0_, the inbound channel adapter supports the `session-transacted` attribute.
In earlier versions, you had to inject a `JmsTemplate` with `sessionTransacted` set to `true`.
(The adapter did allow the `acknowledge` attribute to be set to `transacted` but this was incorrect and did not work).
Note, however, that setting `session-transacted` to `true` has little value because the transaction is committed immediately after the `receive()` and before the message is sent to the `channel`,
If you want the entire flow to be transactional (for example if there is a downstream outbound channel adapter), you must use a `transactional` poller, with a `JmsTransactionManager`.
Or, consider using a `jms-message-driven-channel-adapter` with `acknowledge` set to `transacted`.
[[jms-message-driven-channel-adapter]]
=== Message-Driven Channel Adapter
The "message-driven-channel-adapter" requires a reference to either an instance of a Spring MessageListener container (any subclass of `AbstractMessageListenerContainer`) or both `ConnectionFactory` and `Destination` (a 'destinationName' can be provided in place of the 'destination' reference).
The following example defines a message-driven Channel Adapter with a `Destination` reference.
[source,xml]
----
<int-jms:message-driven-channel-adapter id="jmsIn" destination="inQueue" channel="exampleChannel"/>
----
[NOTE]
=====
The Message-Driven adapter also accepts several properties that pertain to the MessageListener container.
These values are only considered if you do not provide a `container` reference.
In that case, an instance of DefaultMessageListenerContainer will be created and configured based on these properties.
For example, you can specify the "transaction-manager" reference, the "concurrent-consumers" value, and several other property references and values.
Refer to the JavaDoc and Spring Integration's JMS Schema (spring-integration-jms.xsd) for more details.
If you have a custom listener container implementation (usually a subclass of `DefaultMessageListenerContainer`), you can either provide a reference to an instance of it using the `container` attribute, or simply provide its fully qualified class name using the `container-class` attribute.
In that case, the attributes on the adapter are transferred to an instance of your custom container.
=====
The 'extract-payload' property has the same effect as described above, and once again its default value is 'true'.
The poller sub-element is not applicable for a message-driven Channel Adapter, as it will be actively invoked.
For most usage scenarios, the message-driven approach is better since the Messages will be passed along to the `MessageChannel` as soon as they are received from the underlying JMS consumer.
Finally, the <message-driven-channel-adapter> also accepts the 'error-channel' attribute.
This provides the same basic functionality as described in <<gateway-proxy>>.
[source,xml]
----
<int-jms:message-driven-channel-adapter id="jmsIn" destination="inQueue"
channel="exampleChannel"
error-channel="exampleErrorChannel"/>
----
When comparing this to the generic gateway configuration, or the JMS 'inbound-gateway' that will be discussed below, the key difference here is that we are in a one-way flow since this is a 'channel-adapter', not a gateway.
Therefore, the flow downstream from the 'error-channel' should also be one-way.
For example, it could simply send to a logging handler, or it could be connected to a different JMS <outbound-channel-adapter> element.
[[jms-md-conversion-errors]]
==== Inbound Conversion Errors
[NOTE]
=====
Starting with _version 4.2_ the 'error-channel' is used for the conversion errors, too.
Previously, if a JMS `<message-driven-channel-adapter/>` or `<inbound-gateway/>` could not deliver a message due to a conversion error, an exception would be thrown back to the container.
If the container was configured to use transactions, the message would be rolled back and redelivered repeatedly.
The conversion process occurs before and during message construction so such errors were not sent to the 'error-channel'.
Now such conversion exceptions result in an `ErrorMessage` being sent to the 'error-channel', with the exception as the `payload`.
If you wish the transaction to be rolled back, and you have an 'error-channel' defined, the integration flow on the 'error-channel' must re-throw the exception (or another).
If the error flow does not throw an exception, the transaction will be committed and the message removed.
If no 'error-channel' is defined, the exception is thrown back to the container, as before.
=====
[[jms-outbound-channel-adapter]]
=== Outbound Channel Adapter
The `JmsSendingMessageHandler` implements the `MessageHandler` interface and is capable of converting Spring Integration `Messages` to JMS messages and then sending to a JMS destination.
It requires either a 'jmsTemplate' reference or both 'connectionFactory' and 'destination' references (again, the 'destinationName' may be provided in place of the 'destination').
As with the inbound Channel Adapter, the easiest way to configure this adapter is with the namespace support.
The following configuration will produce an adapter that receives Spring Integration Messages from the "exampleChannel" and then converts those into JMS Messages and sends them to the JMS Destination reference whose bean name is "outQueue".
[source,xml]
----
<int-jms:outbound-channel-adapter id="jmsOut" destination="outQueue" channel="exampleChannel"/>
----
As with the inbound Channel Adapters, there is an 'extract-payload' property.
However, the meaning is reversed for the outbound adapter.
Rather than applying to the JMS Message, the boolean property applies to the Spring Integration Message payload.
In other words, the decision is whether to pass the Spring Integration Message _itself_ as the JMS Message body or whether to pass the Spring Integration Message's payload as the JMS Message body.
The default value is once again 'true'.
Therefore, if you pass a Spring Integration Message whose payload is a String, a JMS TextMessage will be created.
If on the other hand you want to send the actual Spring Integration Message to another system via JMS, then simply set this to 'false'.
NOTE: Regardless of the boolean value for payload extraction, the Spring Integration MessageHeaders will map to JMS properties as long as you are relying on the default converter or provide a reference to another instance of HeaderMappingMessageConverter (the same holds true for 'inbound' adapters except that in those cases, it's the JMS properties mapping _to_ Spring Integration MessageHeaders).
[[jms-ob-transactions]]
==== Transactions
Starting with _version 4.0_, the outbound channel adapter supports the `session-transacted` attribute.
In earlier versions, you had to inject a `JmsTemplate` with `sessionTransacted` set to `true`.
The attribute now sets the property on the built-in default `JmsTemplate`.
If a transaction exists (perhaps from an upstream `message-driven-channel-adapter`) the send will be performed within the same transaction.
Otherwise a new transaction will be started.
[[jms-inbound-gateway]]
=== Inbound Gateway
Spring Integration's message-driven JMS inbound-gateway delegates to a `MessageListener` container, supports dynamically adjusting concurrent consumers, and can also handle replies.
The inbound gateway requires references to a `ConnectionFactory`, and a request `Destination` (or 'requestDestinationName').
The following example defines a JMS "inbound-gateway" that receives from the JMS queue referenced by the bean id "inQueue" and sends to the Spring Integration channel named "exampleChannel".
[source,xml]
----
<int-jms:inbound-gateway id="jmsInGateway"
request-destination="inQueue"
request-channel="exampleChannel"/>
----
Since the gateways provide request/reply behavior instead of unidirectional send _or_ receive, they also have two distinct properties for the "payload extraction" (as discussed above for the Channel Adapters' 'extract-payload' setting).
For an inbound-gateway, the 'extract-request-payload' property determines whether the received JMS Message body will be extracted.
If 'false', the JMS Message itself will become the Spring Integration Message payload.
The default is 'true'.
Similarly, for an inbound-gateway the 'extract-reply-payload' property applies to the Spring Integration Message that is going to be converted into a reply JMS Message.
If you want to pass the whole Spring Integration Message (as the body of a JMS ObjectMessage) then set this to 'false'.
By default, it is also 'true' such that the Spring Integration Message _payload_ will be converted into a JMS Message (e.g.
String payload becomes a JMS TextMessage).
As with anything else, Gateway invocation might result in error.
By default Producer will not be notified of the errors that might have occurred on the consumer side and will time out waiting for the reply.
However there might be times when you want to communicate an error condition back to the consumer, in other words treat the Exception as a valid reply by mapping it to a Message.
To accomplish this JMS Inbound Gateway provides support for a Message Channel to which errors can be sent for processing, potentially resulting in a reply Message payload that conforms to some contract defining what a caller may expect as an "error" reply.
Such a channel can be configured via the _error-channel_ attribute.
[source,xml]
----
<int-jms:inbound-gateway request-destination="requestQueue"
request-channel="jmsinputchannel"
error-channel="errorTransformationChannel"/>
<int:transformer input-channel="exceptionTransformationChannel"
ref="exceptionTransformer" method="createErrorResponse"/>
----
You might notice that this example looks very similar to that included within <<gateway-proxy>>.
The same idea applies here: The _exceptionTransformer_ could be a simple POJO that creates error response objects, you could reference the "nullChannel" to suppress the errors, or you could leave 'error-channel' out to let the Exception propagate.
NOTE: See <<jms-md-conversion-errors>>.
[[jms-outbound-gateway]]
=== Outbound Gateway
The outbound Gateway creates JMS Messages from Spring Integration Messages and then sends to a 'request-destination'.
It will then handle the JMS reply Message either by using a selector to receive from the 'reply-destination' that you configure, or if no 'reply-destination' is provided, it will create JMS `TemporaryQueue` s.
[WARNING]
=====
Using a reply-destination (or reply-destination-name), together with a `CachingConnectionFactory` with _cacheConsumers_ set to _true_, can cause Out of Memory conditions.
This is because each request gets a new consumer with a new selector (selecting on the correlation-key value, or on the sent JMSMessageID when there is no correlation-key).
Given that these selectors are unique, they will remain in the cache unused after the current request completes.
If you specify a reply destination, you are advised to NOT use cached consumers.
Alternatively, consider using a <reply-listener/> as described below.
=====
[source,xml]
----
<int-jms:outbound-gateway id="jmsOutGateway"
request-destination="outQueue"
request-channel="outboundJmsRequests"
reply-channel="jmsReplies"/>
----
The 'outbound-gateway' payload extraction properties are inversely related to those of the 'inbound-gateway' (see the discussion above).
That means that the 'extract-request-payload' property value applies to the Spring Integration Message that is being converted into a JMS Message to be _sent as a request_, and the 'extract-reply-payload' property value applies to the JMS Message that is _received as a reply_ and then converted into a Spring Integration Message to be subsequently sent to the 'reply-channel' as shown in the example configuration above.
*<reply-listener/>*
_Spring Integration 2.2_ introduced an alternative technique for handling replies.
If you add a`<reply-listener/>` child element to the gateway, instead of creating a consumer for each reply, a `MessageListener` container is used to receive the replies and hand them over to the requesting thread.
This provides a number of performance benefits as well as alleviating the cached consumer memory utilization problem described in the caution above.
When using a `<reply-listener/>` with an outbound gateway with no `reply-destination`, instead of creating a `TemporaryQueue` for each request, a single `TemporaryQueue` is used (the gateway will create an additional `TemporaryQueue`, as necessary, if the connection to the broker is lost and recovered).
When using a `correlation-key`, multiple gateways can share the same reply destination because the listener container uses a selector that is unique to each gateway.
[WARNING]
=====
If you specify a reply listener, and specify a reply destination (or reply destination name), but provide NO correlation key, the gateway will log a warning and fall back to pre-2.2 behavior.
This is because there is no way to configure a selector in this case, thus there is no way to avoid a reply going to a different gateway that might be configured with the same reply destination.
Note that, in this situation, a new consumer is used for each request, and consumers can build up in memory as described in the caution above; therefore cached consumers should not be used in this case.
=====
[source,xml]
----
<int-jms:outbound-gateway id="jmsOutGateway"
request-destination="outQueue"
request-channel="outboundJmsRequests"
reply-channel="jmsReplies">
<int-jms:reply-listener />
</int-jms-outbound-gateway>
----
In the above example, a reply listener with default attributes is used.
The listener is very lightweight and it is anticipated that, in most cases, only a single consumer will be needed.
However, attributes such as _concurrent-consumers_, _max-concurrent-consumers_ etc., can be added.
Refer to the schema for a complete list of supported attributes, together with thehttp://static.springsource.org/spring/docs/current/spring-framework-reference/html/jms.html[Spring JMS documentation] for their meanings.
==== Attribute Reference
[source,xml]
----
<int-jms:outbound-gateway
connection-factory="connectionFactory" <1>
correlation-key="" <2>
delivery-persistent="" <3>
destination-resolver="" <4>
explicit-qos-enabled="" <5>
extract-reply-payload="true" <6>
extract-request-payload="true" <7>
header-mapper="" <8>
message-converter="" <9>
priority="" <10>
receive-timeout="" <11>
reply-channel="" <12>
reply-destination="" <13>
reply-destination-expression="" <14>
reply-destination-name="" <15>
reply-pub-sub-domain="" <16>
reply-timeout="" <17>
request-channel="" <18>
request-destination="" <19>
request-destination-expression="" <20>
request-destination-name="" <21>
request-pub-sub-domain="" <22>
time-to-live="" <23>
requires-reply=""> <24>
<int-jms:reply-listener /> <25>
</int-jms:outbound-gateway>
----
<1> Reference to a `javax.jms.ConnectionFactory`; default `connectionFactory`.
<2> The name of a property that will contain correlation data to correlate responses with replies.
If omitted, the gateway will expect the responding system to return the value of the outbound JMSMessageID header in the JMSCorrelationID header.
If specified, the gateway will generate a correlation id and populate the specified property with it; the responding system must echo back that value in the same property.
Can be set to `JMSCorrelationID`, in which case the standard header is used instead of a simple String property to hold the correlation data.
When a `<reply-container/>` is used, the correlation-key MUST be specified if an explicit `reply-destination` is provided.
Starting with _version 4.0.1_ this attribute also supports the value `JMSCorrelationID*`, which means that if the outbound message already has a `JMSCorrelationID` (mapped from the `jms_correlationId`) header, it will be used, instead of generating a new one.
Note, the `JMSCorrelationID*` key is not allowed when using a `<reply-container/>` because the container needs to set up a message selector during initialization.IMPORTANT: You should understand that the gateway has no means to ensure uniqueness and unexpected side effects can occur if the provided correlation id is not unique.
<3> A boolean value indicating whether the delivery mode should be DeliveryMode.PERSISTENT (true) or DeliveryMode.NON_PERSISTENT (false).
This setting will only take effect if `explicit-qos-enabled` is `true`.
<4> A `DestinationResolver`; default is a `DynamicDestinationResolver` which simply maps the destination name to a queue or topic of that name.
<5> When set to `true`, enables the use of quality of service attributes - `priority`, `delivery-mode`, `time-to-live`.
<6> When set to `true` (default), the payload of the Spring Integration reply Message will be created from the JMS Reply Message's body (using the `MessageConverter`).
When set to `false`, the entire JMS Message will become the payload of the Spring Integration Message.
<7> When set to `true` (default), the payload of the Spring Integration Message will be converted to a JMSMessage (using the `MessageConverter`).
When set to `false`, the entire Spring Integration Message will be converted to the the JMSMessage.
In both cases, the Spring Integration Message Headers are mapped to JMS headers and properties using the HeaderMapper.
<8> A `HeaderMapper` used to map Spring Integration Message Headers to/from JMS Message Headers/Properties.
<9> A reference to a `MessageConverter` for converting between JMS Messages and the Spring Integration Message payloads (or messages if `extract-request-payload` is `false`).
Default is a `SimpleMessageConverter`.
<10> The default priority of request messages.
Overridden by the message priority header, if present; range 0-9.
This setting will only take effect if `explicit-qos-enabled` is `true`.
<11> The time (in millseconds) to wait for a reply.
Default 5 seconds.
<12> The channel to which the reply message will be sent.
<13> A reference to a `Destination` which will be set as the JMSReplyTo header.
At most, only one of `reply-destination`, `reply-destination-expression`, or `reply-destination-name` is allowed.
If none is provided, a `TemporaryQueue` is used for replies to this gateway.
<14> A SpEL expression evaluating to a `Destination` which will be set as the JMSReplyTo header.
The expression can result in a `Destination` object, or a `String`, which will be used by the `DestinationResolver` to resolve the actual `Destination`.
At most, only one of `reply-destination`, `reply-destination-expression`, or `reply-destination-name` is allowed.
If none is provided, a `TemporaryQueue` is used for replies to this gateway.
<15> The name of the destination which will be set as the JMSReplyTo header; used by the `DestinationResolver` to resolve the actual `Destination`.
At most, only one of `reply-destination`, `reply-destination-expression`, or `reply-destination-name` is allowed.
If none is provided, a `TemporaryQueue` is used for replies to this gateway.
<16> When set to `true`, indicates that any reply `Destination` resolved by the `DestinationResolver` should be a `Topic` rather then a `Queue`.
<17> The time the gateway will wait when sending the reply message to the `reply-channel`.
This only has an effect if the `reply-channel` can block - such as a `QueueChannel` with a capacity limit that is currently full.
Default: infinity.
<18> The channel on which this gateway receives request messages.
<19> A reference to a `Destination` to which request messages will be sent.
One, and only one, of `reply-destination`, `reply-destination-expression`, or `reply-destination-name` is required.
<20> A SpEL expression evaluating to a `Destination` to which request messages will be sent.
The expression can result in a `Destination` object, or a `String`, which will be used by the `DestinationResolver` to resolve the actual `Destination`.
One, and only one, of `reply-destination`, `reply-destination-expression`, or `reply-destination-name` is required.
<21> The name of the destination to which request messages will be sent; used by the `DestinationResolver` to resolve the actual `Destination`.
One, and only one, of `reply-destination`, `reply-destination-expression`, or `reply-destination-name` is required.
<22> When set to `true`, indicates that any request `Destination` resolved by the `DestinationResolver` should be a `Topic` rather then a `Queue`.
<23> Specify the message time to live.
This setting will only take effect if `explicit-qos-enabled` is `true`.
<24> Specify whether this outbound gateway must return a non-null value.
This value is `true` by default, and a `MessageTimeoutException` will be thrown when the underlying service does not return a value after the `receive-timeout`.
Note, it is important to keep in mind that, if the service is never expected to return a reply, it would be better to use a `<int-jms:outbound-channel-adapter/>` instead of a `<int-jms:outbound-gateway/>` with `requires-reply="false"`.
With the latter, the sending thread is blocked, waiting for a reply for the `receive-timeout` period.
<25> When this element is included, replies are received by a `MessageListenerContainer` rather than creating a consumer for each reply.
This can be more efficient in many cases.
[[jms-header-mapping]]
=== Mapping Message Headers to/from JMS Message
JMS Message can contain meta-information such as JMS API headers as well as simple properties.
You can map those to/from Spring Integration Message Headers using `JmsHeaderMapper`.
The JMS API headers are passed to the appropriate setter methods (e.g.
setJMSReplyTo) whereas other headers will be copied to the general properties of the JMS Message.
JMS Outbound Gateway is bootstrapped with the default implementation of `JmsHeaderMapper` which will map standard JMS API Headers as well as primitive/String Message Headers.
Custom header mapper could also be provided via `header-mapper` attribute of inbound and outbound gateways.
IMPORTANT: Since _version 4.0_, the `JMSPriority` header is mapped to the standard `priority` header for inbound messages (previously, the `priority` header was only used for outbound messages).
To revert to the previous behavior (do not map inbound priority), use the `mapInboundPriority` property of `DefaultJmsHeaderMapper` with argument set to `false`.
[[jms-conversion-and-marshalling]]
=== Message Conversion, Marshalling and Unmarshalling
If you need to convert the message, all JMS adapters and gateways, allow you to provide a `MessageConverter` via _message-converter_ attribute.
Simply provide the bean name of an instance of `MessageConverter` that is available within the same ApplicationContext.
Also, to provide some consistency with Marshaller and Unmarshaller interfaces Spring provides `MarshallingMessageConverter` which you can configure with your own custom Marshallers and Unmarshallers
[source,xml]
----
<int-jms:inbound-gateway request-destination="requestQueue"
request-channel="inbound-gateway-channel"
message-converter="marshallingMessageConverter"/>
<bean id="marshallingMessageConverter"
class="org.springframework.jms.support.converter.MarshallingMessageConverter">
<constructor-arg>
<bean class="org.bar.SampleMarshaller"/>
</constructor-arg>
<constructor-arg>
<bean class="org.bar.SampleUnmarshaller"/>
</constructor-arg>
</bean>
----
NOTE: Note, however, that when you provide your own MessageConverter instance, it will still be wrapped within the HeaderMappingMessageConverter.
This means that the 'extract-request-payload' and 'extract-reply-payload' properties may affect what actual objects are passed to your converter.
The HeaderMappingMessageConverter itself simply delegates to a target MessageConverter while also mapping the Spring Integration MessageHeaders to JMS Message properties and vice-versa.
[[jms-channel]]
=== JMS Backed Message Channels
The Channel Adapters and Gateways featured above are all intended for applications that are integrating with other external systems.
The inbound options assume that some other system is sending JMS Messages to the JMS Destination and the outbound options assume that some other system is receiving from the Destination.
The other system may or may not be a Spring Integration application.
Of course, when sending the Spring Integration Message instance as the body of the JMS Message itself (with the 'extract-payload' value set to false), it is assumed that the other system is based on Spring Integration.
However, that is by no means a requirement.
That flexibility is one of the benefits of using a Message-based integration option with the abstraction of "channels" or Destinations in the case of JMS.
There are cases where both the producer and consumer for a given JMS Destination are intended to be part of the same application, running within the same process.
This could be accomplished by using a pair of inbound and outbound Channel Adapters.
The problem with that approach is that two adapters are required even though conceptually the goal is to have a single Message Channel.
A better option is supported as of Spring Integration version 2.0.
Now it is possible to define a single "channel" when using the JMS namespace.
[source,xml]
----
<int-jms:channel id="jmsChannel" queue="exampleQueue"/>
----
The channel in the above example will behave much like a normal <channel/> element from the main Spring Integration namespace.
It can be referenced by both "input-channel" and "output-channel" attributes of any endpoint.
The difference is that this channel is backed by a JMS Queue instance named "exampleQueue".
This means that asynchronous messaging is possible between the producing and consuming endpoints, but unlike the simpler asynchronous Message Channels created by adding a <queue/> sub-element within a non-JMS <channel/> element, the Messages are not just stored in an in-memory queue.
Instead those Messages are passed within a JMS Message body, and the full power of the underlying JMS provider is then available for that channel.
Probably the most common rationale for using this alternative would be to take advantage of the persistence made available by the _store and forward_ approach of JMS messaging.
If configured properly, the JMS-backed Message Channel also supports transactions.
In other words, a producer would not actually write to a transactional JMS-backed channel if its send operation is part of a transaction that rolls back.
Likewise, a consumer would not physically remove a JMS Message from the channel if the reception of that Message is part of a transaction that rolls back.
Note that the producer and consumer transactions are separate in such a scenario.
This is significantly different than the propagation of a transactional context across the simple, synchronous <channel/> element that has no <queue/> sub-element.
Since the example above is referencing a JMS Queue instance, it will act as a point-to-point channel.
If on the other hand, publish/subscribe behavior is needed, then a separate element can be used, and a JMS Topic can be referenced instead.
[source,xml]
----
<int-jms:publish-subscribe-channel id="jmsChannel" topic="exampleTopic"/>
----
For either type of JMS-backed channel, the name of the destination may be provided instead of a reference.
[source,xml]
----
<int-jms:channel id="jmsQueueChannel" queue-name="exampleQueueName"/>
<jms:publish-subscribe-channel id="jmsTopicChannel" topic-name="exampleTopicName"/>
----
In the examples above, the Destination names would be resolved by Spring's default `DynamicDestinationResolver` implementation, but any implementation of the `DestinationResolver` interface could be provided.
Also, the JMS `ConnectionFactory` is a required property of the channel, but by default the expected bean name would be "connectionFactory".
The example below provides both a custom instance for resolution of the JMS Destination names and a different name for the ConnectionFactory.
[source,xml]
----
<int-jms:channel id="jmsChannel" queue-name="exampleQueueName"
destination-resolver="customDestinationResolver"
connection-factory="customConnectionFactory"/>
----
[[jms-selectors]]
=== Using JMS Message Selectors
With JMS message selectors you can filter http://docs.oracle.com/javaee/6/api/javax/jms/Message.html[JMS Messages] based on JMS headers as well as JMS properties.
For example, if you want to listen to messages whose custom JMS header property _fooHeaderProperty_ equals _bar_, you can specify the following expression:
[source,xml]
----
fooHeaderProperty = 'bar'
----
Message selector expressions are a subset of the http://en.wikipedia.org/wiki/SQL-92[SQL-92] conditional expression syntax, and are defined as part of the _http://download.oracle.com/otn-pub/jcp/7195-jms-1.1-fr-spec-oth-JSpec/jms-1_1-fr-spec.pdf[Java Message Service]_ specification (Version 1.1 April 12, 2002).
Specifically, please see chapter "3.8 Message Selection".
It contains a detailed explanation of the expressions syntax.
You can specify the JMS message _selector_ attribute using XML Namespace configuration for the following Spring Integration JMS components:
* JMS Channel
* JMS Publish Subscribe Channel
* JMS Inbound Channel Adapter
* JMS Inbound Gateway
* JMS Message-driven Channel Adapter
IMPORTANT: It is important to remember that you cannot reference message body values using JMS Message selectors.
[[jms-samples]]
=== JMS Samples
To experiment with these JMS adapters, check out the JMS samples available in the _Spring Integration Samples_ Git repository:
* https://github.com/SpringSource/spring-integration-samples/tree/master/basic/jms[https://github.com/SpringSource/spring-integration-samples/tree/master/basic/jms]
There are two samples included.
One provides _Inbound_ and _Outbound Channel Adapters_, and the other provides _Inbound_ and _Outbound Gateways_.
They are configured to run with an embedded_http://activemq.apache.org/[ActiveMQ]_ process, but the samples' _https://github.com/SpringSource/spring-integration-samples/blob/master/basic/jms/src/main/resources/META-INF/spring/integration/common.xml[common.xml]__Spring Application Context_ file can easily be modified to support either a different JMS provider or a standalone _ActiveMQ_ process.
In other words, you can split the configuration, so that the Inbound and Outbound Adapters are running in separate JVMs.
If you have_ActiveMQ_ installed, simply modify the _brokerURL_ property within the _common.xml_ file to use _tcp://localhost:61616_ (instead of _vm://localhost_).
Both of the samples accept input via stdin and then echo back to stdout.
Look at the configuration to see how these messages are routed over JMS.

578
src/reference/asciidoc/jmx.adoc Normal file
View File

@@ -0,0 +1,578 @@
[[jmx]]
=== JMX Support
Spring Integration provides _Channel Adapters_ for receiving and publishing JMX Notifications.
There is also an_Inbound Channel Adapter_ for polling JMX MBean attribute values, and an _Outbound Channel Adapter_ for invoking JMX MBean operations.
[[jmx-notification-listening-channel-adapter]]
==== Notification Listening Channel Adapter
The _Notification-listening Channel Adapter_ requires a JMX ObjectName for the MBean that publishes notifications to which this listener should be registered.
A very simple configuration might look like this:
[source,xml]
----
<int-jmx:notification-listening-channel-adapter id="adapter"
channel="channel"
object-name="example.domain:name=publisher"/>
----
TIP: The _notification-listening-channel-adapter_ registers with an `MBeanServer` at startup, and the default bean name is _mbeanServer_ which happens to be the same bean name generated when using Spring's _<context:mbean-server/>_ element.
If you need to use a different name, be sure to include the_mbean-server_ attribute.
The adapter can also accept a reference to a `NotificationFilter` and a _handback_ Object to provide some context that is passed back with each Notification.
Both of those attributes are optional.
Extending the above example to include those attributes as well as an explicit `MBeanServer` bean name would produce the following:
[source,xml]
----
<int-jmx:notification-listening-channel-adapter id="adapter"
channel="channel"
mbean-server="someServer"
object-name="example.domain:name=somePublisher"
notification-filter="notificationFilter"
handback="myHandback"/>
----
The _Notification-listening Channel Adapter_ is event-driven and registered with the `MBeanServer` directly.
It does not require any poller configuration.
[NOTE]
=====
For this component only, the _object-name_ attribute can contain an ObjectName pattern (e.g.
"org.foo:type=Bar,name=*") and the adapter will receive notifications from all MBeans with ObjectNames that match the pattern.
In addition, the _object-name_ attribute can contain a SpEL reference to a <util:list/> of ObjectName patterns:
[source,xml]
----
<jmx:notification-listening-channel-adapter id="manyNotificationsAdapter"
channel="manyNotificationsChannel"
object-name="#{patterns}"/>
<util:list id="patterns">
<value>org.foo:type=Foo,name=*</value>
<value>org.foo:type=Bar,name=*</value>
</util:list>
----
The names of the located MBean(s) will be logged when DEBUG level logging is enabled.
=====
[[jmx-notification-publishing-channel-adapter]]
==== Notification Publishing Channel Adapter
The _Notification-publishing Channel Adapter_ is relatively simple.
It only requires a JMX ObjectName in its configuration as shown below.
[source,xml]
----
<context:mbean-export/>
<int-jmx:notification-publishing-channel-adapter id="adapter"
channel="channel"
object-name="example.domain:name=publisher"/>
----
It does also require that an `MBeanExporter` be present in the context.
That is why the _<context:mbean-export/>_ element is shown above as well.
When Messages are sent to the channel for this adapter, the Notification is created from the Message content.
If the payload is a String it will be passed as the _message_ text for the Notification.
Any other payload type will be passed as the_userData_ of the Notification.
JMX Notifications also have a _type_, and it should be a dot-delimited String.
There are two ways to provide the_type_.
Precedence will always be given to a Message header value associated with the `JmxHeaders.NOTIFICATION_TYPE` key.
On the other hand, you can rely on a fallback _default-notification-type_ attribute provided in the configuration.
[source,xml]
----
<context:mbean-export/>
<int-jmx:notification-publishing-channel-adapter id="adapter"
channel="channel"
object-name="example.domain:name=publisher"
default-notification-type="some.default.type"/>
----
[[jmx-attribute-polling-channel-adapter]]
==== Attribute Polling Channel Adapter
The _Attribute Polling Channel Adapter_ is useful when you have a requirement, to periodically check on some value that is available through an MBean as a managed attribute.
The poller can be configured in the same way as any other polling adapter in Spring Integration (or it's possible to rely on the default poller).
The _object-name_ and _attribute-name_ are required.
An MBeanServer reference is also required, but it will automatically check for a bean named _mbeanServer_ by default, just like the _Notification-listening Channel Adapter_ described above.
[source,xml]
----
<int-jmx:attribute-polling-channel-adapter id="adapter"
channel="channel"
object-name="example.domain:name=someService"
attribute-name="InvocationCount">
<int:poller max-messages-per-poll="1" fixed-rate="5000"/>
</int-jmx:attribute-polling-channel-adapter>
----
[[tree-polling-channel-adapter]]
==== Tree Polling Channel Adapter
The _Tree Polling Channel Adapter_ queries the JMX MBean tree and sends a message with a payload that is the graph of objects that matches the query.
By default the MBeans are mapped to primitives and simple Objects like Map, List and arrays - permitting simple transformation, for example, to JSON.
An MBeanServer reference is also required, but it will automatically check for a bean named _mbeanServer_ by default, just like the _Notification-listening Channel Adapter_ described above.
A basic configuration would be:
[source,xml]
----
<int-jmx:tree-polling-channel-adapter id="adapter"
channel="channel"
query-name="example.domain:type=*">
<int:poller max-messages-per-poll="1" fixed-rate="5000"/>
</int-jmx:tree-polling-channel-adapter>
----
This will include all attributes on the MBeans selected.
You can filter the attributes by providing an `MBeanObjectConverter` that has an appropriate filter configured.
The converter can be provided as a reference to a bean definition using the `converter` attribute, or as an inner <bean/> definition.
A `DefaultMBeanObjectConverter` is provided which can take a `MBeanAttributeFilter` in its constructor argument.
Two standard filters are provided; the `NamedFieldsMBeanAttributeFilter` allows you to specify a list of attributes to include and the `NotNamedFieldsMBeanAttributeFilter` allows you to specify a list of attributes to exclude.
You can also implement your own filter
[[jmx-operation-invoking-channel-adapter]]
==== Operation Invoking Channel Adapter
The _operation-invoking-channel-adapter_ enables Message-driven invocation of any managed operation exposed by an MBean.
Each invocation requires the operation name to be invoked and the ObjectName of the target MBean.
Both of these must be explicitly provided via adapter configuration:
[source,xml]
----
<int-jmx:operation-invoking-channel-adapter id="adapter"
object-name="example.domain:name=TestBean"
operation-name="ping"/>
----
Then the adapter only needs to be able to discover the _mbeanServer_ bean.
If a different bean name is required, then provide the _mbean-server_ attribute with a reference.
The payload of the Message will be mapped to the parameters of the operation, if any.
A Map-typed payload with String keys is treated as name/value pairs, whereas a List or array would be passed as a simple argument list (with no explicit parameter names).
If the operation requires a single parameter value, then the payload can represent that single value, and if the operation requires no parameters, then the payload would be ignored.
If you want to expose a channel for a single common operation to be invoked by Messages that need not contain headers, then that option works well.
[[jmx-operation-invoking-outbound-gateway]]
==== Operation Invoking Outbound Gateway
Similar to the _operation-invoking-channel-adapter_ Spring Integration also provides a _operation-invoking-outbound-gateway_, which could be used when dealing with non-void operations and a return value is required.
Such return value will be sent as message payload to the _reply-channel_ specified by this Gateway.
[source,xml]
----
<int-jmx:operation-invoking-outbound-gateway request-channel="requestChannel"
reply-channel="replyChannel"
object-name="o.s.i.jmx.config:type=TestBean,name=testBeanGateway"
operation-name="testWithReturn"/>
----
If the _reply-channel_ attribute is not provided, the reply message will be sent to the channel that is identified by the `IntegrationMessageHeaderAccessor.REPLY_CHANNEL` header.
That header is typically auto-created by the entry point into a message flow, such as any _Gateway_ component.
However, if the message flow was started by manually creating a Spring Integration Message and sending it directly to a _Channel_, then you must specify the message header explicitly or use the provided _reply-channel_ attribute.
[[jmx-mbean-exporter]]
==== MBean Exporter
Spring Integration components themselves may be exposed as MBeans when the `IntegrationMBeanExporter` is configured.
To create an instance of the `IntegrationMBeanExporter`, define a bean and provide a reference to an `MBeanServer` and a domain name (if desired).
The domain can be left out, in which case the default domain is _org.springframework.integration_.
[source,xml]
----
<int-jmx:mbean-export id="integrationMBeanExporter"
default-domain="my.company.domain" server="mbeanServer"/>
<bean id="mbeanServer" class="org.springframework.jmx.support.MBeanServerFactoryBean">
<property name="locateExistingServerIfPossible" value="true"/>
</bean>
----
[IMPORTANT]
=====
The MBean exporter is orthogonal to the one provided in Spring core - it registers message channels and message handlers, but not itself.
You can expose the exporter itself, and certain other components in Spring Integration, using the standard `<context:mbean-export/>` tag.
The exporter has a some metrics attached to it, for instance a count of the number of active handlers and the number of queued messages.
It also has a useful operation, as discussed in <<jmx-mbean-shutdown>>.
=====
Starting with _Spring Integration 4.0_ the `@EnableIntegrationMBeanExport` annotation has been introduced for convenient configuration of a default (`integrationMbeanExporter`) bean of type `IntegrationMBeanExporter` with several useful options at the `@Configuration` class level.
For example:
[source,java]
----
@Configuration
@EnableIntegration
@EnableIntegrationMBeanExport(server = "mbeanServer", managedComponents = "input")
public class ContextConfiguration {
@Bean
public MBeanServerFactoryBean mbeanServer() {
return new MBeanServerFactoryBean();
}
}
----
If there is a need to provide more options, or have several `IntegrationMBeanExporter` beans e.g.
for different MBean Servers, or to avoid conflicts with the standard Spring `MBeanExporter` (e.g.
via `@EnableMBeanExport`), you can simply configure an `IntegrationMBeanExporter` as a generic bean.
[[jmx-mbean-features]]
===== MBean ObjectNames
All the `MessageChannel`, `MessageHandler` and `MessageSource` instances in the application are wrapped by the MBean exporter to provide management and monitoring features.
The generated JMX object names for each component type are listed in the table below:
.MBean ObjectNames
[cols="1,3l", options="header"]
|===
| Component Type
| ObjectName
| MessageChannel
| o.s.i:type=MessageChannel,name=<channelName>
| MessageSource
| o.s.i:type=MessageSource,name=<channelName>,bean=<source>
| MessageHandler
| o.s.i:type=MessageSource,name=<channelName>,bean=<source>
|===
The _bean_ attribute in the object names for sources and handlers takes one of the values in the table below:
.bean ObjectName Part
[cols="1,3", options="header"]
|===
| Bean Value
| Description
| endpoint
| The bean name of the enclosing endpoint (e.g.
<service-activator>) if there is one
| anonymous
| An indication that the enclosing endpoint didn't have a user-specified bean name, so the JMX name is the input channel name
| internal
| For well-known Spring Integration default components
| handler/source
| None of the above: fallback to the `toString()` of the object being monitored (handler or source)
|===
Custom elements can be appended to the object name by providing a reference to a `Properties` object in the `object-name-static-properties` attribute.
Also, since _Spring Integration 3.0_, you can use a custom http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/jmx/export/naming/ObjectNamingStrategy.html[ObjectNamingStrategy] using the `object-naming-strategy` attribute.
This permits greater control over the naming of the MBeans.
For example, to group all Integration MBeans under an 'Integration' type.
A simple custom naming strategy implementation might be:
[source,java]
----
public class Namer implements ObjectNamingStrategy {
private final ObjectNamingStrategy realNamer = new KeyNamingStrategy();
@Override
public ObjectName getObjectName(Object managedBean, String beanKey) throws MalformedObjectNameException {
String actualBeanKey = beanKey.replace("type=", "type=Integration,componentType=");
return realNamer.getObjectName(managedBean, actualBeanKey);
}
}
----
The `beanKey` argument is a String containing the standard object name beginning with the `default-domain` and including any additional static properties.
This example simply moves the standard `type` part to `componentType` and sets the `type` to 'Integration', enabling selection of all Integration MBeans in one query:`"my.domain:type=Integration,*`.
This also groups the beans under one tree entry under the domain in tools like VisualVM.
NOTE: The default naming strategy is a http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/jmx/export/naming/MetadataNamingStrategy.html[MetadataNamingStrategy].
The exporter propagates the `default-domain` to that object to allow it to generate a fallback object name if parsing of the bean key fails.
If your custom naming strategy is a `MetadataNamingStrategy` (or subclass), the exporter will *not* propagate the `default-domain`; you will need to configure it on your strategy bean.
[[jmx-channel-features]]
===== MessageChannel MBean Features
Message channels report metrics according to their concrete type.
If you are looking at a `DirectChannel`, you will see statistics for the send operation.
If it is a `QueueChannel`, you will also see statistics for the receive operation, as well as the count of messages that are currently buffered by this `QueueChannel`.
In both cases there are some metrics that are simple counters (message count and error count), and some that are estimates of averages of interesting quantities.
The algorithms used to calculate these estimates are described briefly in the section below.
.MessageChannel Metrics
[cols="1,2,3", options="header"]
|===
| Metric Type
| Example
| Algorithm
| Count
| Send Count
| Simple incrementer.
Increases by one when an event occurs.
| Error Count
| Send Error Count
| Simple incrementer.
Increases by one when an send results in an error.
| Duration
| Send Duration (method execution time in milliseconds)
| Exponential Moving Average with decay factor (10 by default).
Average of the method execution time over roughly the last 10 (default) measurements.
| Rate
| Send Rate (number of operations per second)
| Inverse of Exponential Moving Average of the interval between events with decay in time (lapsing over 60 seconds by default) and per measurement (last 10 events by default).
| Error Rate
| Send Error Rate (number of errors per second)
| Inverse of Exponential Moving Average of the interval between error events with decay in time (lapsing over 60 seconds by default) and per measurement (last 10 events by default).
| Ratio
| Send Success Ratio (ratio of successful to total sends)
| Estimate the success ratio as the Exponential Moving Average of the series composed of values 1 for success and 0 for failure (decaying as per the rate measurement over time and events by default).
Error ratio is 1 - success ratio.
|===
[[jmx-handler-features]]
===== MessageHandler MBean Features
The following table shows the statistics maintained for message handlers.
Some metrics are simple counters (message count and error count), and one is an estimate of averages of send duration.
The algorithms used to calculate these estimates are described briefly in the table below:
.MessageHandlerMetrics
[cols="1,2,3", options="header"]
|===
| Metric Type
| Example
| Algorithm
| Count
| Handle Count
| Simple incrementer.
Increases by one when an event occurs.
| Error Count
| Handler Error Count
| Simple incrementer.
Increases by one when an invocation results in an error.
| Active Count
| Handler Active Count
| Indicates the number of currently active threads currently invoking the handler (or any downstream synchronous flow).
| Duration
| Handle Duration (method execution time in milliseconds)
| Exponential Moving Average with decay factor (10 by default).
Average of the method execution time over roughly the last 10 (default) measurements.
|===
[[jmx-statistics]]
===== Time-Based Average Estimates
A feature of the time-based average estimates is that they decay with time if no new measurements arrive.
To help interpret the behaviour over time, the time (in seconds) since the last measurement is also exposed as a metric.
There are two basic exponential models: decay per measurement (appropriate for duration and anything where the number of measurements is part of the metric), and decay per time unit (more suitable for rate measurements where the time in between measurements is part of the metric).
Both models depend on the fact that
`S(n) = sum(i=0,i=n) w(i) x(i)`has a special form when `w(i) = r^i`, with `r=constant`:
`S(n) = x(n) + r S(n-1)`(so you only have to store `S(n-1)`, not the whole series `x(i)`, to generate a new metric estimate from the last measurement).
The algorithms used in the duration metrics use `r=exp(-1/M)` with `M=10`.
The net effect is that the estimate `S(n)` is more heavily weighted to recent measurements and is composed roughly of the last `M` measurements.
So `M` is the "window" or lapse rate of the estimate In the case of the vanilla moving average, `i` is a counter over the number of measurements.
In the case of the rate we interpret `i` as the elapsed time, or a combination of elapsed time and a counter (so the metric estimate contains contributions roughly from the last `M` measurements and the last `T` seconds).
[[jmx-42-improvements]]
===== JMX Improvements
_Version 4.2_ introduced some important improvements, representing a fairly major overhaul to the JMX support in the framework.
These resulted in a significant performance improvement of the JMX statistics collection and much more control thereof, but has some implications for user code in a few specific (uncommon) situations.
These changes are detailed below, with a *caution* where necessary.
* *Metrics Capture*
Previously, `MessageSource`, `MessageChannel` and `MessageHandler` metrics were captured by wrapping the object in a JDK dynamic proxy to intercept appropriate method calls and capture the statistics.
The proxy was added when an integration MBean exporter was declared in the context.
Now, the statistics are captured by the beans themselves; but they are still enabled (by default) only if the integration MBean exporter is declared.
WARNING: This change means that you no longer automatically get an MBean or statistics for custom `MessageHandler` implementations, unless those custom handlers extend `AbstractMessageHandler`.
The simplest way to resolve this is to extend `AbstractMessageHandler`.
If that's not possible, or desired, another work-around is to implement the `MessageHandlerMetrics` interface.
For convenience, a `DefaultMessageHandlerMetrics` is provided to capture and report statistics.
Invoke the `beforeHandle` and `afterHandle` at the appropriate times.
Your `MessageHandlerMetrics` methods can then delegate to this object to obtain each statistic.
Similarly, `MessageSource` implementations must extend `AbstractMessageSource` or implement `MessageSourceMetrics`.
Message sources only capture a count so there is no provided convenience class; simply maintain the count in an `AtomicLong` field.
The removal of the proxy has two additional benefits; 1) stack traces in exceptions are reduced (when JMX is enabled) because the proxy is not on the stack; 2) cases where 2 MBeans were exported for the same bean now only export a single MBean with consolidated attributes/operations (see the MBean consolidation bullet below).
* *Resolution*
`System.nanoTime()` is now used to capture times instead of `System.currentTimeMillis()`.
This may provide more accuracy on some JVMs, espcially when durations of less than 1 millisecond are expected
* *Setting Initial Statistics Collection State*
Previously, when JMX was enabled, all sources, channels, handlers captured statistics.
It is now possible to control whether the statisics are enabled on an individual component.
Further, it is possible to capture simple counts on `MessageChannel` s and `MessageHandler` s instead of the complete time-based statistics.
This can have significant performance implications because you can selectively configure where you need detailed statistics, as well as enable/disable at runtime.
Also see the bullet below about setting initial collection state.
Two new attributes have been added to the `<int-jmx:mbean-exporter/>`.
`counts-enabled` is a list of bean name patterns where simple message counts will be enabled.
`stats-enabled` is a list of bean name patterns where full time-based statistics will be enabled.
These are initial settings only and each component can have its settings changed at runtime, using JMX or a <control-bus/> using the `enableCounts()` and `enableStats()` operations.
*Note:* stats is a superset of counts, enabling stats will enable counts (this is true for the initial setting via the patterns and at runtime).
Disabling counts at runtime will also disable stats.
A pattern can be negated by preceding it with `!`; patterns are evaluated left to right; the first match (positive or negative) wins and the remaining patterns won't be evaluated against that bean.
If your bean name begins with `!`, the `!` in the pattern can be escaped.
`"\!foo"` will positively match a bean named `"!foo"`.
* *@IntegrationManagedResource*
Similar to the `@ManagedResource` annotation, the `@IntegrationManagedResource` marks a class as eligible to be exported as an MBean; however, it will only be exported if there is an `IntegrationMBeanExporter` in the application context.
Certain Spring Integration classes (in the `org.springframework.integration`) package) that were previously annotated with`@ManagedResource` are now annotated with both `@ManagedResource` and `@IntegrationManagedResource`.
This is for backwards compatibility (see the next bullet).
Such MBeans will be exported by any context `MBeanServer`*or* an `IntegrationMBeanExporter` (but not both - if both exporters are present, the bean is exported by the integration exporter if the bean matches a `managed-components` pattern).
* *Consolidated MBeans*
Certain classes within the framework (mapping routers for example) have additional attributes/operations over and above those provided by metrics and `Lifecycle`.
We will use a `Router` as an example here.
Previously, beans of these types were exported as two distinct MBeans: 1) the metrics MBean (with an objectName such as: `intDomain:type=MessageHandler,name=myRouter,bean=endpoint`).
This MBean had metrics attributes and metrics/Lifecycle operations.
A second MBean (with an objectName such as: `ctxDomain:name=org.springframework.integration.config.RouterFactoryBean#0
,type=MethodInvokingRouter`) was exported with the channel mappings attribute and operations.
Now, the attributes and operations are consolidated into a single MBean.
The objectName will depend on the exporter.
If exported by the integration MBean exporter, the objectName will be, for example: `intDomain:type=MessageHandler,name=myRouter,bean=endpoint`.
If exported by another exporter, the objectName will be, for example: `ctxDomain:name=org.springframework.integration.config.RouterFactoryBean#0
,type=MethodInvokingRouter`.
There is no difference between these MBeans (aside from the objectName), except that the statistics will *not* be enabled (the attributes will be 0) by exporters other than the integration exporter; statistics can be enabled at runtime using the JMX operations.
When exported by the integration MBean exporter, the initial state can be managed as described above.
WARNING: If you are currently using the second MBean to change, for example, channel mappings, *and* you are using the integration MBean exporter, note that the objectName has changed because of the MBean consolidation.
There is no change if you are not using the integration MBean exporter.
* *MBean Exporter Bean Name Patterns*
Previously, the `managed-components` patterns were inclusive only.
If a bean name matched one of the patterns it would be included.
Now, the pattern can be negated by prefixing it with `!`.
i.e.
`"!foo*, foox"` will match all beans that don't start with `foo`, except `foox`.
Patterns are evaluated left to right and the first match (positive or negative) wins and no further patterns are applied.
WARNING: The addition of this syntax to the pattern causes one possible (although perhaps unlikey) problem.
If you have a bean `"!foo"`*and* you included a pattern `"!foo"` in your MBean exporter's `managed-components` patterns; it will no long match; the pattern will now match all beans *not* named `foo`.
In this case, you can escape the `!` in the pattern with `\`.
The pattern `"\!foo"` means match a bean named `"!foo"`.
* *Replacing the Default Channel/Handler Statistics*
A new strategy interface `MetricsFactory` has been introduced allowing you to provide custom channel metrics for your `MessageChannel` s and `MessageHandler` s.
By default, a `DefaultMetricsFactory` provides default implementation of `MessageChannelMetrics` and `MessageHandlerMetrics` which are described in the next bullet.
To override the default `MetricsFactory` use the MBean exporter's `metrics-factory` attribute to provide a reference to your `MetricsFactory` bean instance.
You can either customize the default implementations as described in the next bullet, or provide completely different implementations by overriding `AbstractMessageChannelMetrics` and/or `AbstractMessageHandlerMetrics`.
* *Customizing the Default Channel/Handler Statistics*
See <<jmx-statistics>> and the Javadocs for the `ExponentialMovingAverage*` classes for more information about these values.
By default, the `DefaultMessageChannelMetrics` and `DefaultMessageHandlerMetrics` use a `window` of 10 measurements, a rate period of 1 second (rate per second) and a decay lapse period of 1 minute.
If you wish to override these defaults, you can provide a custom `MetricsFactory` that returns appropriately configured metrics and provide a reference to it to the MBean exporter as described above.
Example:
[source,java]
----
public static class CustomMetrics implements MetricsFactory {
@Override
public AbstractMessageChannelMetrics createChannelMetrics(String name) {
return new DefaultMessageChannelMetrics(name,
new ExponentialMovingAverage(20, 1000000.),
new ExponentialMovingAverageRate(2000, 120000, 30, true),
new ExponentialMovingAverageRatio(130000, 40, true),
new ExponentialMovingAverageRate(3000, 140000, 50, true));
}
@Override
public AbstractMessageHandlerMetrics createHandlerMetrics(String name) {
return new DefaultMessageHandlerMetrics(name, new ExponentialMovingAverage(20, 1000000.));
}
}
----
* *Advanced Customization*
The customizations described above are wholesale and will apply to all appropriate beans exported by the MBean exporter.
This is the extent of customization available using XML configuration.
Individual beans can be provided with different implementations using java `@Configuration` or programmatically at runtime, after the application context has been refreshed, by invoking the `configureMetrics` methods on `AbstractMessageChannel` and `AbstractMessageHandler`.
* *Performance Improvement*
Previously, the time-based metrics (see <<jmx-statistics>>) were calculated in real time.
The statistics are now calculated when retrieved instead.
This resulted in a significant performance improvement, at the expense of a small amount of additional memory for each statistic.
As discussed in the bullet above, the statistics can be disabled altogether, while retaining the MBean allowing the invocation of `Lifecycle` methods.
* *IntegrationMBeanExporter changes*
The `IntegrationMBeanExporter` no longer implements `SmartLifecycle`; this means that `start()` and `stop()` operations are no longer available to register/unregister MBeans.
The MBeans are now registered during context initialization and unregistered when the context is destroyed.
[[jmx-mbean-shutdown]]
===== Orderly Shutdown Managed Operation
The MBean exporter provides a JMX operation to shut down the application in an orderly manner, intended for use before terminating the JVM.
[source,java]
----
public void stopActiveComponents(long howLong)
----
Its use and operation are described in <<jmx-shutdown>>.

1016
src/reference/asciidoc/jpa.adoc Normal file
View File

File diff suppressed because it is too large Load Diff

42
src/reference/asciidoc/logging-adapter.adoc Normal file
View File

@@ -0,0 +1,42 @@
[[logging-channel-adapter]]
=== Logging Channel Adapter
The `<logging-channel-adapter/>` is often used in conjunction with a Wire Tap, as discussed in<<channel-wiretap>>.
However, it can also be used as the ultimate consumer of any flow.
For example, consider a flow that ends with a `<service-activator/>` that returns a result, but you wish to discard that result.
To do that, you could send the result to `NullChannel`.
Alternatively, you can route it to an `INFO` level `<logging-channel-adapter/>`; that way, you can see the discarded message when logging at `INFO` level, but not see it when logging at, say, `WARN` level.
With a `NullChannel`, you would only see the discarded message when logging at `DEBUG` level.
[source]
----
<int:logging-channel-adapter
channel="" <1>
level="INFO" <2>
expression="" <3>
log-full-message="false" <4>
logger-name="" /> <5>
----
<1> The channel connecting the logging adapter to an upstream component.
<2> The logging level at which messages sent to this adapter will be logged.
Default: `INFO`.
<3> A SpEL expression representing exactly what part(s) of the message will be logged.
Default: `payload` - just the payload will be logged.
This attribute cannot be specified if `log-full-message` is specified.
<4> When `true`, the entire message will be logged (including headers).
Default: `false` - just the payload will be logged.
This attribute cannot be specified if `expression` is specified.
<5> Specifies the _name_ of the logger (known as `category` in `log4j`) used for log messages created by this adapter.
This enables setting the log name (in the logging subsystem) for individual adapters.
By default, all adapters will log under the name `org.springframework.integration.handler.LoggingHandler`.

345
src/reference/asciidoc/mail.adoc Normal file
View File

@@ -0,0 +1,345 @@
[[mail]]
== Mail Support
[[mail-outbound]]
=== Mail-Sending Channel Adapter
Spring Integration provides support for outbound email with the `MailSendingMessageHandler`.
It delegates to a configured instance of Spring's `JavaMailSender`:
[source,java]
----
JavaMailSender mailSender = context.getBean("mailSender", JavaMailSender.class);
MailSendingMessageHandler mailSendingHandler = new MailSendingMessageHandler(mailSender);
----
`MailSendingMessageHandler` has various mapping strategies that use Spring's `MailMessage` abstraction.
If the received Message's payload is already a `MailMessage` instance, it will be sent directly.
Therefore, it is generally recommended to precede this consumer with a Transformer for non-trivial MailMessage construction requirements.
However, a few simple Message mapping strategies are supported out-of-the-box.
For example, if the message payload is a byte array, then that will be mapped to an attachment.
For simple text-based emails, you can provide a String-based Message payload.
In that case, a MailMessage will be created with that String as the text content.
If you are working with a Message payload type whose toString() method returns appropriate mail text content, then consider adding Spring Integration's _ObjectToStringTransformer_ prior to the outbound Mail adapter (see the example within <<transformer-namespace>> for more detail).
The outbound MailMessage may also be configured with certain values from the `MessageHeaders`.
If available, values will be mapped to the outbound mail's properties, such as the recipients (TO, CC, and BCC), the from/reply-to, and the subject.
The header names are defined by the following constants:
[source,java]
----
MailHeaders.SUBJECT
MailHeaders.TO
MailHeaders.CC
MailHeaders.BCC
MailHeaders.FROM
MailHeaders.REPLY_TO
----
NOTE: `MailHeaders` also allows you to override corresponding `MailMessage` values.
For example: If `MailMessage.to` is set to 'foo@bar.com' and `MailHeaders.TO` Message header is provided it will take precedence and override the corresponding value in `MailMessage`
[[mail-inbound]]
=== Mail-Receiving Channel Adapter
Spring Integration also provides support for inbound email with the `MailReceivingMessageSource`.
It delegates to a configured instance of Spring Integration's own `MailReceiver` interface, and there are two implementations: `Pop3MailReceiver` and `ImapMailReceiver`.
The easiest way to instantiate either of these is by passing the 'uri' for a Mail store to the receiver's constructor.
For example:
[source,java]
----
MailReceiver receiver = new Pop3MailReceiver("pop3://usr:pwd@localhost/INBOX");
----
Another option for receiving mail is the IMAP "idle" command (if supported by the mail server you are using).
Spring Integration provides the `ImapIdleChannelAdapter` which is itself a Message-producing endpoint.
It delegates to an instance of the `ImapMailReceiver` but enables asynchronous reception of Mail Messages.
There are examples in the next section of configuring both types of inbound Channel Adapter with Spring Integration's namespace support in the 'mail' schema.
[[mail-namespace]]
=== Mail Namespace Support
Spring Integration provides a namespace for mail-related configuration.
To use it, configure the following schema locations.
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:int-mail="http://www.springframework.org/schema/integration/mail"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/integration/mail
http://www.springframework.org/schema/integration/mail/spring-integration-mail.xsd">
----
To configure an outbound Channel Adapter, provide the channel to receive from, and the MailSender:
[source,xml]
----
<int-mail:outbound-channel-adapter channel="outboundMail"
mail-sender="mailSender"/>
----
Alternatively, provide the host, username, and password:
[source,xml]
----
<int-mail:outbound-channel-adapter channel="outboundMail"
host="somehost" username="someuser" password="somepassword"/>
----
NOTE: Keep in mind, as with any outbound Channel Adapter, if the referenced channel is a PollableChannel, a <poller> sub-element should be provided with either an interval-trigger or cron-trigger.
When using the namespace support, a _header-enricher_ Message Transformer is also available.
This simplifies the application of the headers mentioned above to any Message prior to sending to the Mail Outbound Channel Adapter.
[source,xml]
----
<int-mail:header-enricher input-channel="expressionsInput" default-overwrite="false">
<int-mail:to expression="payload.to"/>
<int-mail:cc expression="payload.cc"/>
<int-mail:bcc expression="payload.bcc"/>
<int-mail:from expression="payload.from"/>
<int-mail:reply-to expression="payload.replyTo"/>
<int-mail:subject expression="payload.subject" overwrite="true"/>
</int-mail:header-enricher>
----
This example assumes the payload is a JavaBean with appropriate getters for the specified properties, but any SpEL expression can be used.
Alternatively, use the `value` attribute to specify a literal.
Notice also that you can specify `default-overwrite` and individual `overwrite` attributes to control the behavior with existing headers.
To configure an Inbound Channel Adapter, you have the choice between polling or event-driven (assuming your mail server supports IMAP IDLE - if not, then polling is the only option).
A polling Channel Adapter simply requires the store URI and the channel to send inbound Messages to.
The URI may begin with "pop3" or "imap":
[source,xml]
----
<int-mail:inbound-channel-adapter id="imapAdapter"
store-uri="imaps://[username]:[password]@imap.gmail.com/INBOX"
java-mail-properties="javaMailProperties"
channel="receiveChannel"
should-delete-messages="true"
should-mark-messages-as-read="true"
auto-startup="true">
<int:poller max-messages-per-poll="1" fixed-rate="5000"/>
</int-mail:inbound-channel-adapter>
----
If you do have IMAP idle support, then you may want to configure the "imap-idle-channel-adapter" element instead.
Since the "idle" command enables event-driven notifications, no poller is necessary for this adapter.
It will send a Message to the specified channel as soon as it receives the notification that new mail is available:
[source,xml]
----
<int-mail:imap-idle-channel-adapter id="customAdapter"
store-uri="imaps://[username]:[password]@imap.gmail.com/INBOX"
channel="receiveChannel"
auto-startup="true"
should-delete-messages="false"
should-mark-messages-as-read="true"
java-mail-properties="javaMailProperties"/>
----
\...where _javaMailProperties_ could be provided by creating and populating a regular `java.utils.Properties` object.
For example via _util_ namespace provided by Spring.
IMPORTANT: If your username contains the '@' character use '%40' instead of '@' to avoid parsing errors from the underlying JavaMail API.
[source,xml]
----
<util:properties id="javaMailProperties">
<prop key="mail.imap.socketFactory.class">javax.net.ssl.SSLSocketFactory</prop>
<prop key="mail.imap.socketFactory.fallback">false</prop>
<prop key="mail.store.protocol">imaps</prop>
<prop key="mail.debug">false</prop>
</util:properties>
----
By default, the `ImapMailReceiver` will search for Messages based on the default `SearchTerm` which is _All mails that are RECENT (if supported), that are NOT ANSWERED, that are NOT DELETED, that are NOT SEEN and have not
been processed by this mail receiver (enabled by the use of the custom USER flag or simply NOT FLAGGED if not supported)_.
Since version 2.2, the `SearchTerm` used by the `ImapMailReceiver` is fully configurable via the `SearchTermStrategy` which you can inject via the `search-term-strategy` attribute.
`SearchTermStrategy` is a simple strategy interface with a single method that allows you to create an instance of the `SearchTerm` that will be used by the `ImapMailReceiver`.
[source,java]
----
public interface SearchTermStrategy {
SearchTerm generateSearchTerm(Flags supportedFlags, Folder folder);
}
----
For example:
[source,xml]
----
<mail:imap-idle-channel-adapter id="customAdapter"
store-uri="imap:foo"
…
search-term-strategy="searchTermStrategy"/>
<bean id="searchTermStrategy"
class="o.s.i.mail.config.ImapIdleChannelAdapterParserTests.TestSearchTermStrategy"/>
----
In the above example instead of relying on the default `SearchTermStrategy` the `TestSearchTermStrategy` will be used instead
[IMPORTANT]
.Important: IMAP PEEK
=====
Starting with _version 4.1.1_, the IMAP mail receiver will use the `mail.imap.peek` or `mail.imaps.peek` javamail property, if specified.
Previously, the receiver ignored the property and always set the PEEK flag.
Now, if you explicitly set this property to `false`, the message will be marked as `\Seen` regardless of the setting of `shouldMarkMessagesRead`.
If not specified, the previous behavior is retained (peek is `true`).
=====
*IMAP IDLE and lost connection*
When using IMAP IDLE channel adapter there might be situations where connection to the server may be lost (e.g., network failure) and since Java Mail documentation explicitly states that the actual IMAP API is EXPERIMENTAL it is important to understand the differences in the API and how to deal with them when configuring IMAP IDLE adapters.
Currently Spring Integration Mail adapters was tested with Java Mail 1.4.1 and Java Mail 1.4.3 and depending on which one is used special attention must be payed to some of the java mail properties that needs to be set with regard to auto-reconnect.
_
The following behavior was observed with GMAIL but should provide you with some tips on how to solve re-connect
issue with other providers, however feedback is always welcome.
Again, below notes are based on GMAIL.
_
With Java Mail 1.4.1 if `mail.imaps.timeout` property is set for a relatively short period of time (e.g., ~ 5 min) then `IMAPFolder.idle()` will throw `FolderClosedException` after this timeout.
However if this property is not set (should be indefinite) the behavior that was observed is that `IMAPFolder.idle()` method never returns nor it throws an exception.
It will however reconnect automatically if connection was lost for a short period of time (e.g., under 10 min), but if connection was lost for a long period of time (e.g., over 10 min), then`IMAPFolder.idle()` will not throw `FolderClosedException` nor it will re-establish connection and will remain in the blocked state indefinitely, thus leaving you no possibility to reconnect without restarting the adapter.
So the only way to make re-connect to work with Java Mail 1.4.1 is to set `mail.imaps.timeout` property explicitly to some value, but it also means that such value shoudl be relatively short (under 10 min) and the connection should be re-estabished relatively quickly.
Again, it may be different with other providers.
With Java Mail 1.4.3 there was significant improvements to the API ensuring that there will always be a condition which will force `IMAPFolder.idle()` method to return via `StoreClosedException` or `FolderClosedException` or simply return, thus allowing us to proceed with auto-reconnect.
Currently auto-reconnect will run infinitely making attempts to reconnect every 10 sec.
IMPORTANT: In both configurations `channel` and `should-delete-messages` are the _REQUIRED_     attributes.
The important thing to understand is why `should-delete-messages` is required.
    The issue is with the POP3 protocol, which does NOT have any knowledge of messages that were READ.
It can only know what's been read      within a single session.
This means that when your POP3 mail adapter is running, emails are successfully consumed as as they become available during each poll     and no single email message will be delivered more then once.
However, as soon as you restart your adapter and begin a new session     all the email messages that might have been retrieved in the previous session will be retrieved again.
That is the nature of POP3.
Some might argue     that `should-delete-messages` should be TRUE by default.
In other words, there are two valid and mutually exclusive use cases      which make it very hard to pick a single "best" default.
You may want to configure your adapter as the only email receiver in which     case you want to be able to restart such adapter without fear that messages that were delivered before will not be redelivered again.      In this case setting `should-delete-messages` to TRUE would make most sense.
However, you may have another use case where      you may want to have multiple adapters that simply monitor email servers and their content.
In other words you just want to 'peek but not touch'.      Then setting `should-delete-messages` to FALSE would be much more appropriate.
So since it is hard to choose what should be     the right default value for the `should-delete-messages` attribute, we simply made it a required attribute, to be set by the user.
Leaving it up to the user also means, you will be less likely to end up with unintended behavior.
NOTE: When configuring a polling email adapter's _should-mark-messages-as-read_ attribute, be aware of the protocol you are configuring to retrieve messages.
For example POP3 does not support this flag which means setting it to either value will have no effect as messages will NOT be marked as read.
[IMPORTANT]
=====
It is important to understand that that these actions (marking messages read, and deleting messages) are performed after the messages are received, but before they are processed.
This can cause messages to be lost.
You may wish to consider using transaction synchronization instead - see <<mail-tx-sync>>
=====
The <imap-idle-channel-adapter/> also accepts the 'error-channel' attribute.
If a downstream exception is thrown and an 'error-channel' is specified, a MessagingException message containing the failed message and original exception, will be sent to this channel.
Otherwise, if the downstream channels are synchronous, any such exception will simply be logged as a warning by the channel adapter.
NOTE: Beginning with the 3.0 release, the IMAP idle adapter emits application events (specifically `ImapIdleExceptionEvent` s) when exceptions occur.
This allows applications to detect and act on those exceptions.
The events can be obtained using an `<int-event:inbound-channel-adapter>` or any `ApplicationListener` configured to receive an `ImapIdleExceptionEvent` or one of its super classes.
[[mail-filtering]]
=== Email Message Filtering
Very often you may encounter a requirement to filter incoming messages (e.g., You want to only read emails that have 'Spring Integration' in the _Subject_ line).
This could be easily accomplished by connecting Inbound Mail adapter with an expression-based _Filter_.
Although it would work, there is a downside to this approach.
Since messages would be filtered after going through inbound mail adapter all such messages would be marked as read (SEEN) or Un-read (depending on the value of `should-mark-messages-as-read` attribute).
However in reality what would be more useful is to mark messages as SEEN only if they passed the filtering criteria.
This is very similar to looking at your email client while scrolling through all the messages in the preview pane, but only flagging messages as SEEN that were actually opened and read.
In Spring Integration 2.0.4 we've introduced `mail-filter-expression` attribute on `inbound-channel-adapter` and `imap-idle-channel-adapter`.
This attribute allows you to provide an expression which is a combination of SpEL and Regular Expression.
For example if you would like to read only emails that contain 'Spring Integration' in the Subject line, you would configure `mail-filter-expression` attribute like this this: `mail-filter-expression="subject matches '(?i).*Spring Integration.*"`
Since `javax.mail.internet.MimeMessage` is the root context of SpEL Evaluation Context, you can filter on any value available through MimeMessage including the actual body of the message.
This one is particularly important since reading the body of the message would typically result in such message to be marked as SEEN by default, but since we now setting PEAK flag of every incomming message to 'true', only messages that were explicitly marked as SEEN will be seen as read.
So in the below example only messages that match the filter expression will be output by this adapter and only those messages will be marked as SEEN.
In this case based on the `mail-filter-expression` only messages that contain 'Spring Integration' in the subject line will be produced by this adapter.
[source,xml]
----
<int-mail:imap-idle-channel-adapter id="customAdapter"
store-uri="imaps://some_google_address:${password}@imap.gmail.com/INBOX"
channel="receiveChannel"
should-mark-messages-as-read="true"
java-mail-properties="javaMailProperties"
mail-filter-expression="subject matches '(?i).*Spring Integration.*'"/>
----
Another reasonable question is what happens on the next poll, or idle event, or what happens when such adapter is restarted.
Will there be a potential duplication of massages to be filtered? In other words if on the last retrieval where you had 5 new messages and only 1 passed the filter what would happen with the other 4.
Would they go through the filtering logic again on the next poll or idle? After all they were not marked as SEEN.
The actual answer is no.
They would not be subject of duplicate processing due to another flag (RECENT) that is set by the Email server and is used by Spring Integration mail search filter.
Folder implementations set this flag to indicate that this message is new to this folder, that is, it has arrived since the last time this folder was opened.
In other while our adapter may peek at the email it also lets the email server know that such email was touched and therefore will be marked as RECENT by the email server.
[[mail-tx-sync]]
=== Transaction Synchronization
Transaction synchronization for inbound adapters allows you to take different actions after a transaction commits, or rolls back.
Transaction synchronization is enabled by adding a <transactional/> element to the poller for the polled <inbound-adapter/>, or to the <imap-idle-inbound-adapter/>.
Even if there is no 'real' transaction involved, you can still enable this feature by using a`PseudoTransactionManager` with the <transactional/> element.
For more information, see <<transaction-synchronization>>.
Because of the many different mail servers, and specifically the limitations that some have, at this time we only provide a strategy for these transaction synchronizations.
You can send the messages to some other Spring Integration components, or invoke a custom bean to perform some action.
For example, to move an IMAP message to a different folder after the transaction commits, you might use something similar to the following:
[source,xml]
----
<int-mail:imap-idle-channel-adapter id="customAdapter"
store-uri="imaps://foo.com:password@imap.foo.com/INBOX"
channel="receiveChannel"
auto-startup="true"
should-delete-messages="false"
java-mail-properties="javaMailProperties">
<int:transactional synchronization-factory="syncFactory"/>
</int-mail:imap-idle-channel-adapter>
<int:transaction-synchronization-factory id="syncFactory">
<int:after-commit expression="@syncProcessor.process(payload)"/>
</int:transaction-synchronization-factory>
<bean id="syncProcessor" class="foo.bar.Mover"/>
----
[source,java]
----
public class Mover {
public void process(MimeMessage message) throws Exception{
Folder folder = message.getFolder();
folder.open(Folder.READ_WRITE);
String messageId = message.getMessageID();
Message[] messages = folder.getMessages();
FetchProfile contentsProfile = new FetchProfile();
contentsProfile.add(FetchProfile.Item.ENVELOPE);
contentsProfile.add(FetchProfile.Item.CONTENT_INFO);
contentsProfile.add(FetchProfile.Item.FLAGS);
folder.fetch(messages, contentsProfile);
// find this message and mark for deletion
for (int i = 0; i < messages.length; i++) {
if (((MimeMessage) messages[i]).getMessageID().equals(messageId)) {
messages[i].setFlag(Flags.Flag.DELETED, true);
break;
}
}
Folder fooFolder = store.getFolder("FOO"));
fooFolder.appendMessages(new MimeMessage[]{message});
folder.expunge();
folder.close(true);
fooFolder.close(false);
}
}
----
IMPORTANT: For the message to be still available for manipulation after the transaction, _should-delete-messages_ must be set to 'false'.

4
src/reference/asciidoc/message-construction.adoc Normal file
View File

@@ -0,0 +1,4 @@
[[messaging-construction-chapter]]
== Message Construction
include::./message.adoc[]

82
src/reference/asciidoc/message-history.adoc Normal file
View File

@@ -0,0 +1,82 @@
[[message-history]]
=== Message History
The key benefit of a messaging architecture is loose coupling where participating components do not maintain any awareness about one another.
This fact alone makes your application extremely flexible, allowing you to change components without affecting the rest of the flow, change messaging routes,   message consuming styles (polling vs event driven), and so on.
However, this unassuming style of architecture could prove to be difficult when things go wrong.
When debugging, you would probably like to get as much information about the message as you can (its origin, channels it has traversed, etc.)
Message History is one of those patterns that helps by giving you an option to maintain some level of awareness of a message path either for debugging purposes or to maintain an audit trail.
Spring integration provides a simple way to configure your message flows to maintain the Message History by adding a header to the Message and updating that header every time a message passes through a tracked component.
[[message-history-config]]
==== Message History Configuration
To enable Message History all you need is to define the `message-history` element in your configuration.
[source,xml]
----
<int:message-history/>
----
Now every named component (component that has an 'id' defined) will be tracked.
The framework will set the 'history' header in your Message.
Its value is very simple - `List<Properties>`.
[source,xml]
----
<int:gateway id="sampleGateway" 
service-interface="org.springframework.integration.history.sample.SampleGateway"
default-request-channel="bridgeInChannel"/>
<int:chain id="sampleChain" input-channel="chainChannel" output-channel="filterChannel">
<int:header-enricher>
<int:header name="baz" value="baz"/>
</int:header-enricher>
</int:chain>
----
The above configuration will produce a very simple Message History structure:
[source,java]
----
[{name=sampleGateway, type=gateway, timestamp=1283281668091},
{name=sampleChain, type=chain, timestamp=1283281668094}]
----
To get access to Message History all you need is access the MessageHistory header.
For example:
[source,java]
----
Iterator<Properties> historyIterator =
message.getHeaders().get(MessageHistory.HEADER_NAME, MessageHistory.class).iterator();
assertTrue(historyIterator.hasNext());
Properties gatewayHistory = historyIterator.next();
assertEquals("sampleGateway", gatewayHistory.get("name"));
assertTrue(historyIterator.hasNext());
Properties chainHistory = historyIterator.next();
assertEquals("sampleChain", chainHistory.get("name"));
----
You might not want to track all of the components.
To limit the history to certain components based on their names, all you need is provide the `tracked-components` attribute and specify a comma-delimited list of component names and/or patterns that match the components you want to track.
[source,xml]
----
<int:message-history tracked-components="*Gateway, sample*, foo"/>
----
In the above example, Message History will only be maintained for all of the components that end with 'Gateway', start with 'sample', or match the name 'foo' exactly.
Starting with _version 4.0_, you can also use the `@EnableMessageHistory` annotation in a `@Configuration` class.
In addition, the `MessageHistoryConfigurer` bean is now exposed as a JMX MBean by the `IntegrationMBeanExporter` (see <<jmx-mbean-exporter>>), allowing the patterns to be changed at runtime.
Note, however, that the bean must be stopped (turning off message history) in order to change the patterns.
This feature might be useful to temporarily turn on history to analyze a system.
The MBean's object name is `"<domain>:name=messageHistoryConfigurer,type=MessageHistoryConfigurer"`.
IMPORTANT: If multiple beans (declared by `@EnableMessageHistory` and/or `<message-history/>`) they all must have identical component name patterns (when trimmed and sorted).
*Do not use a generic
`<bean/>` definition for the `MessageHistoryConfigurer`*.
NOTE: Remember that by definition the Message History header is immutable (you can't re-write history, although some try).
Therefore, when writing Message History values, the components are either creating brand new Messages (when the component is an origin), or they are copying the history from a request Message, modifying it and setting the new list on a reply Message.
In either case, the values can be appended even if the Message itself is crossing thread boundaries.
That means that the history values can greatly simplify debugging in an asynchronous message flow.

341
src/reference/asciidoc/message-publishing.adoc Normal file
View File

@@ -0,0 +1,341 @@
[[message-publishing]]
== Message Publishing
The AOP Message Publishing feature allows you to construct and send a message as a by-product of a method invocation.
For example, imagine you have a component and every time the state of this component changes you would like to be notified via a Message.
The easiest way to send such notifications would be to send a message to a dedicated channel, but how would you connect the method invocation that changes the state of the object to a message sending process, and how should the notification Message be structured? The AOP Message Publishing feature handles these responsibilities with a configuration-driven approach.
[[message-publishing-config]]
=== Message Publishing Configuration
Spring Integration provides two approaches: XML and Annotation-driven.
[[publisher-annotation]]
==== Annotation-driven approach via @Publisher annotation
The annotation-driven approach allows you to annotate any method with the `@Publisher` annotation, specifying a 'channel' attribute.
The Message will be constructed from the return value of the method invocation and sent to a channel specified by the 'channel' attribute.
To further manage message structure, you can also use a combination of both `@Payload` and `@Header` annotations.
Internally this message publishing feature of Spring Integration uses both Spring AOP by defining `PublisherAnnotationAdvisor` and Spring 3.0's Expression Language (SpEL) support, giving you considerable flexibility and control over the structure of the_Message_ it will publish.
The `PublisherAnnotationAdvisor` defines and binds the following variables:
* _#return_ - will bind to a return value allowing you to reference it or its attributes (e.g., _#return.foo_ where 'foo' is an attribute of the object bound to _#return_)
* _#exception_ - will bind to an exception if one is thrown by the method invocation.
* _#args_ - will bind to method arguments, so individual arguments could be extracted by name (e.g., _#args.fname_ as in the above method)
Let's look at a couple of examples:
[source,java]
----
@Publisher
public String defaultPayload(String fname, String lname) {
return fname + " " + lname;
}
----
In the above example the Message will be constructed with the following structure:
* Message payload - will be the return type and value of the method.
This is the default.
* A newly constructed message will be sent to a default publisher channel configured with an annotation post processor (see the end of this section).
[source,java]
----
@Publisher(channel="testChannel")
public String defaultPayload(String fname, @Header("last") String lname) {
return fname + " " + lname;
}
----
In this example everything is the same as above, except that we are not using a default publishing channel.
Instead we are specifying the publishing channel via the 'channel' attribute of the `@Publisher` annotation.
We are also adding a `@Header` annotation which results in the Message header named 'last' having the same value as the 'lname' method parameter.
That header will be added to the newly constructed Message.
[source,java]
----
@Publisher(channel="testChannel")
@Payload
public String defaultPayloadButExplicitAnnotation(String fname, @Header String lname) {
return fname + " " + lname;
}
----
The above example is almost identical to the previous one.
The only difference here is that we are using a `@Payload` annotation on the method, thus explicitly specifying that the return value of the method should be used as the payload of the Message.
[source,java]
----
@Publisher(channel="testChannel")
@Payload("#return + #args.lname")
public String setName(String fname, String lname, @Header("x") int num) {
return fname + " " + lname;
}
----
Here we are expanding on the previous configuration by using the Spring Expression Language in the `@Payload` annotation to further instruct the framework how the message should be constructed.
In this particular case the message will be a concatenation of the return value of the method invocation and the 'lname' input argument.
The Message header named 'x' will have its value determined by the 'num' input argument.
That header will be added to the newly constructed Message.
[source,java]
----
@Publisher(channel="testChannel")
public String argumentAsPayload(@Payload String fname, @Header String lname) {
return fname + " " + lname;
}
----
In the above example you see another usage of the `@Payload` annotation.
Here we are annotating a method argument which will become the payload of the newly constructed message.
As with most other annotation-driven features in Spring, you will need to register a post-processor (`PublisherAnnotationBeanPostProcessor`).
[source,xml]
----
<bean class="org.springframework.integration.aop.PublisherAnnotationBeanPostProcessor"/>
----
You can instead use namespace support for a more concise configuration:
[source,xml]
----
<int:annotation-config default-publisher-channel="defaultChannel"/>
----
Similar to other Spring annotations (@Component, @Scheduled, etc.), `@Publisher` can also be used as a meta-annotation.
That means you can define your own annotations that will be treated in the same way as the `@Publisher` itself.
[source,java]
----
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Publisher(channel="auditChannel")
public @interface Audit {
}
----
Here we defined the `@Audit` annotation which itself is annotated with `@Publisher`.
Also note that you can define a `channel` attribute on the meta-annotation thus encapsulating the behavior of where messages will be sent inside of this annotation.
Now you can annotate any method:
[source,java]
----
@Audit
public String test() {
    return "foo";
}
----
In the above example every invocation of the `test()` method will result in a Message with a payload created from its return value.
Each Message will be sent to the channel named _auditChannel_.
One of the benefits of this technique is that you can avoid the duplication of the same channel name across multiple annotations.
You also can provide a level of indirection between your own, potentially domain-specific annotations and those provided by the framework.
You can also annotate the class which would mean that the properties of this annotation will be applied on every public method of that class.
[source,java]
----
@Audit
static class BankingOperationsImpl implements BankingOperations {
  public String debit(String amount) {
     . . .
  }
  public String credit(String amount) {
     . . .
  }
}
----
[[aop-based-interceptor]]
==== XML-based approach via the <publishing-interceptor> element
The XML-based approach allows you to configure the same AOP-based Message Publishing functionality with simple namespace-based configuration of a `MessagePublishingInterceptor`.
It certainly has some benefits over the annotation-driven approach since it allows you to use AOP pointcut expressions, thus possibly intercepting multiple methods at once or intercepting and publishing methods to which you don't have the source code.
To configure Message Publishing via XML, you only need to do the following two things:
* Provide configuration for `MessagePublishingInterceptor` via the `<publishing-interceptor>` XML element.
* Provide AOP configuration to apply the `MessagePublishingInterceptor` to managed objects.
[source,xml]
----
<aop:config>
<aop:advisor advice-ref="interceptor" pointcut="bean(testBean)" />
</aop:config>
<publishing-interceptor id="interceptor" default-channel="defaultChannel">
<method pattern="echo" payload="'Echoing: ' + #return" channel="echoChannel">
<header name="foo" value="bar"/>
</method>
<method pattern="repl*" payload="'Echoing: ' + #return" channel="echoChannel">
<header name="foo" expression="'bar'.toUpperCase()"/>
</method>
<method pattern="echoDef*" payload="#return"/>
</publishing-interceptor>
----
As you can see the `<publishing-interceptor>` configuration looks rather similar to the Annotation-based approach, and it also utilizes the power of the Spring 3.0 Expression Language.
In the above example the execution of the `echo` method of a `testBean` will render a _Message_ with the following structure:
* The Message payload will be of type String with the content "Echoing: [value]" where `value` is the value returned by an executed method.
* The Message will have a header with the name "foo" and value "bar".
* The Message will be sent to `echoChannel`.
The second method is very similar to the first.
Here every method that begins with 'repl' will render a Message with the following structure:
* The Message payload will be the same as in the above sample
* The Message will have a header named "foo" whose value is the result of the SpEL expression `'bar'.toUpperCase()` .
* The Message will be sent to `echoChannel`.
The second method, mapping the execution of any method that begins with `echoDef` of `testBean`, will produce a Message with the following structure.
* The Message payload will be the value returned by an executed method.
* Since the `channel` attribute is not provided explicitly, the Message will be sent to the `defaultChannel` defined by the _publisher_.
For simple mapping rules you can rely on the _publisher_ defaults.
For example:
[source,xml]
----
<publishing-interceptor id="anotherInterceptor"/>
----
This will map the return value of every method that matches the pointcut expression to a payload and will be sent to a _default-channel_.
If the _defaultChannel_is not specified (as above) the messages will be sent to the global _nullChannel_.
_Async Publishing_
One important thing to understand is that publishing occurs in the same thread as your component's execution.
So by default in is synchronous.
This means that the entire message flow would have to wait until the publisher's flow completes.  However, quite often you want the complete opposite and that is to use this Message publishing feature to initiate asynchronous sub-flows.
For example, you might host a service (HTTP, WS etc.) which receives a remote request.You may want to send this request internally into a process that might take a while.
However you may also want to reply to the user right away.
So, instead of sending inbound requests for processing via the output channel (the conventional way), you can simply use 'output-channel' or a 'replyChannel' header to send a simple acknowledgment-like reply back to the caller while using the Message publisher feature to initiate a complex flow.
EXAMPLE: Here is the simple service that receives a complex payload, which needs to be sent further for processing, but it also needs to reply to the caller with a simple acknowledgment.
[source,java]
----
public String echo(Object complexPayload) {
     return "ACK"; 
}
----
So instead of hooking up the complex flow to the output channel we use the Message publishing feature instead.
We configure it to create a new Message using the input argument of the service method (above) and send that to the 'localProcessChannel'.
And to make sure this sub-flow is asynchronous all we need to do is send it to any type of asynchronous channel (ExecutorChannel in this example).
[source,xml]
----
<int:service-activator  input-channel="inputChannel" output-channel="outputChannel" ref="sampleservice"/>
<bean id="sampleservice" class="test.SampleService"/>
<aop:config>
<aop:advisor advice-ref="interceptor" pointcut="bean(sampleservice)" />
</aop:config>
<int:publishing-interceptor id="interceptor" >
<int:method pattern="echo" payload="#args[0]" channel="localProcessChannel">
<int:header name="sample_header" expression="'some sample value'"/>
</int:method>
</int:publishing-interceptor>
<int:channel id="localProcessChannel">
<int:dispatcher task-executor="executor"/>
</int:channel>
<task:executor id="executor" pool-size="5"/>
----
Another way of handling this type of scenario is with a wire-tap.
[[scheduled-producer]]
==== Producing and publishing messages based on a scheduled trigger
In the above sections we looked at the Message publishing feature of Spring Integration which constructs and publishes messages as by-products of Method invocations.
However in those cases, you are still responsible for invoking the method.
In Spring Integration 2.0 we've added another related useful feature: support for scheduled Message producers/publishers via the new "expression" attribute on the 'inbound-channel-adapter' element.
Scheduling could be based on several triggers, any one of which may be configured on the 'poller' sub-element.
Currently we support `cron`, `fixed-rate`, `fixed-delay` as well as any custom trigger implemented by you and referenced by the 'trigger' attribute value.
As mentioned above, support for scheduled producers/publishers is provided via the _<inbound-channel-adapter>_ xml element.
Let's look at couple of examples:
[source,xml]
----
<int:inbound-channel-adapter id="fixedDelayProducer"
expression="'fixedDelayTest'"
channel="fixedDelayChannel">
<int:poller fixed-delay="1000"/>
</int:inbound-channel-adapter>
----
In the above example an inbound Channel Adapter will be created which will construct a Message with its payload being the result of the expression  defined in the `expression` attribute.
Such messages will be created and sent every time the delay specified by the `fixed-delay` attribute occurs.
[source,xml]
----
<int:inbound-channel-adapter id="fixedRateProducer"
expression="'fixedRateTest'"
channel="fixedRateChannel">
<int:poller fixed-rate="1000"/>
</int:inbound-channel-adapter>
----
This example is very similar to the previous one, except that we are using the `fixed-rate` attribute which will allow us to send messages at a fixed rate (measuring from the start time of each task).
[source,xml]
----
<int:inbound-channel-adapter id="cronProducer"
expression="'cronTest'"
channel="cronChannel">
<int:poller cron="7 6 5 4 3 ?"/>
</int:inbound-channel-adapter>
----
This example demonstrates how you can apply a Cron trigger with a value specified in the `cron` attribute.
[source,xml]
----
<int:inbound-channel-adapter id="headerExpressionsProducer"
expression="'headerExpressionsTest'"
channel="headerExpressionsChannel"
auto-startup="false">
<int:poller fixed-delay="5000"/>
<int:header name="foo" expression="6 * 7"/>
<int:header name="bar" value="x"/>
</int:inbound-channel-adapter>
----
Here you can see that in a way very similar to the Message publishing feature we are enriching a newly constructed Message with extra Message headers which can take scalar values or the results of evaluating Spring expressions.
If you need to implement your own custom trigger you can use the `trigger` attribute to provide a reference to any spring configured bean which implements the `org.springframework.scheduling.Trigger` interface.
[source,xml]
----
<int:inbound-channel-adapter id="triggerRefProducer"
expression="'triggerRefTest'" channel="triggerRefChannel">
<int:poller trigger="customTrigger"/>
</int:inbound-channel-adapter>
<beans:bean id="customTrigger" class="o.s.scheduling.support.PeriodicTrigger">
<beans:constructor-arg value="9999"/>
</beans:bean>
----

18
src/reference/asciidoc/message-routing.adoc Normal file
View File

@@ -0,0 +1,18 @@
[[messaging-routing-chapter]]
== Message Routing
// BE SURE TO PRECEDE ALL include:: with a blank line - see https://github.com/asciidoctor/asciidoctor/issues/1297
include::./router.adoc[]
include::./filter.adoc[]
include::./splitter.adoc[]
include::./aggregator.adoc[]
include::./resequencer.adoc[]
include::./chain.adoc[]
include::./scatter-gather.adoc[]
// BE SURE TO PRECEDE ALL include:: with a blank line - see https://github.com/asciidoctor/asciidoctor/issues/1297

85
src/reference/asciidoc/message-store.adoc Normal file
View File

@@ -0,0 +1,85 @@
[[message-store]]
=== Message Store
Enterprise Integration Patterns (EIP) identifies several patterns that have the capability to buffer messages.
For example, an _Aggregator_ buffers messages until they can be released and a _QueueChannel_ buffers messages until consumers explicitly receive those messages from that channel.
Because of the failures that can occur at any point within your message flow, EIP components that buffer messages also introduce a point where messages could be lost.
To mitigate the risk of losing Messages, EIP defines the http://eaipatterns.com/MessageStore.html[Message Store] pattern which allows EIP components to store _Messages_ typically in some type of persistent store (e.g.
RDBMS).
Spring Integration provides support for the _Message Store_ pattern by a) defining a `org.springframework.integration.store.MessageStore` strategy interface, b) providing several implementations of this interface, and c) exposing a `message-store` attribute on all components that have the capability to buffer messages so that you can inject any instance that implements the `MessageStore` interface.
Details on how to configure a specific _Message Store_ implementation and/or how to inject a `MessageStore` implementation into a specific buffering component are described throughout the manual (see the specific component, such as _QueueChannel_, _Aggregator_, _Resequencer_ etc.), but here are a couple of samples to give you an idea:
QueueChannel
[source,xml]
----
<int:channel id="myQueueChannel">
<int:queue message-store="refToMessageStore"/>
<int:channel>
----
Aggregator
[source,xml]
----
<int:aggregator … message-store="refToMessageStore"/>
----
By default _Messages_ are stored in-memory using `org.springframework.integration.store.SimpleMessageStore`, an implementation of `MessageStore`.
That might be fine for development or simple low-volume environments where the potential loss of non-persistent messages is not a concern.
However, the typical production application will need a more robust option, not only to mitigate the risk of message loss but also to avoid potential out-of-memory errors.
Therefore, we also provide MessageStore implementations for a variety of data-stores.
Below is a complete list of supported implementations:
* <<jdbc-message-store>> - uses RDBMS to store Messages
* <<redis-message-store>> - uses Redis key/value datastore to store Messages
* <<mongodb-message-store>> - uses MongoDB document store to store Messages
* <<gemfire-message-store>> - uses Gemfire distributed cache to store Messages
[IMPORTANT]
=====
However be aware of some limitations while using persistent implementations of the `MessageStore`.
The Message data (payload and headers) is _serialized_ and _deserialized_ using different serialization strategies depending on the implementation of the `MessageStore`.
For example, when using `JdbcMessageStore`, only `Serializable` data is persisted by default.
In this case non-Serializable headers are removed before serialization occurs.
Also be aware of the protocol specific headers that are injected by transport adapters (e.g., FTP, HTTP, JMS etc.).
For example, `<http:inbound-channel-adapter/>` maps HTTP-headers into Message Headers and one of them is an `ArrayList` of non-Serializable `org.springframework.http.MediaType` instances.
However you are able to inject your own implementation of the `Serializer` and/or `Deserializer` strategy interfaces into some `MessageStore` implementations (such as JdbcMessageStore) to change the behaviour of serialization and deserialization.
Special attention must be paid to the headers that represent certain types of data.
For example, if one of the headers contains an instance of some _Spring Bean_, upon deserialization you may end up with a different instance of that bean, which directly affects some of the implicit headers created by the framework (e.g., REPLY_CHANNEL or ERROR_CHANNEL).
Currently they are not serializable, but even if they were, the deserialized channel would not represent the expected instance.
Beginning with _Spring Integration version 3.0_, this issue can be resolved with a header enricher, configured to replace these headers with a name after registering the channel with the `HeaderChannelRegistry`.
Also when configuring a message-flow like this: _gateway -> queue-channel (backed by a persistent Message Store) -> service-activator_ That gateway creates a _Temporary Reply Channel_, and it will be lost by the time the service-activator's poller reads from the queue.
Again, you can use the header enricher to replace the headers with a String representation.
For more information, refer to the <<header-enricher>>.
=====
_Spring Integration 4.0_ introduced two new interfaces `ChannelMessageStore` - to implement operations specific for `QueueChannel` s, `PriorityCapableChannelMessageStore` - to mark `MessageStore` implementation to be used for `PriorityChannel` s and to provide _priority_ order for persisted Messages.
The real behaviour depends on implementation.
The Framework provides these implementations, which can be used as a persistent `MessageStore` for `PriorityChannel`:
* <<redis-cms>>
* <<mongodb-priority-channel-message-store>>
* <<jdbc-message-store-channels>>
[WARNING]
.Caution with SimpleMessageStore
=====
Starting with _version 4.1_, the `SimpleMessageStore` no longer copies the message group when calling `getMessageGroup()`.
For large message groups, this was a significant performance problem.
4.0.1 introduced a boolean `copyOnGet` allowing this to be controlled.
When used internally by the aggregator, this was set to false to improve performance.
It is now false by default.
Users accessing the group store outside of components such as aggregators, will now get a direct reference to the group being used by the aggregator, instead of a copy.
Manipulation of the group outside of the aggregator may cause unpredictable results.
For this reason, users should not perform such manipulation, or set the `copyOnGet` property to `true`.
=====

9
src/reference/asciidoc/message-transformation.adoc Normal file
View File

@@ -0,0 +1,9 @@
[[messaging-transformation-chapter]]
== Message Transformation
// BE SURE TO PRECEDE ALL include:: with a blank line - see https://github.com/asciidoctor/asciidoctor/issues/1297
include::./transformer.adoc[]
include::./content-enrichment.adoc[]
include::./claim-check.adoc[]

463
src/reference/asciidoc/message.adoc Normal file
View File

@@ -0,0 +1,463 @@
[[message]]
=== Message
The Spring Integration `Message` is a generic container for data.
Any object can be provided as the payload, and each `Message` also includes headers containing user-extensible properties as key-value pairs.
[[message-interface]]
==== The Message Interface
Here is the definition of the `Message` interface:
[source,java]
----
public interface Message<T> {
T getPayload();
MessageHeaders getHeaders();
}
----
The `Message` is obviously a very important part of the API.
By encapsulating the data in a generic wrapper, the messaging system can pass it around without any knowledge of the data's type.
As an application evolves to support new types, or when the types themselves are modified and/or extended, the messaging system will not be affected by such changes.
On the other hand, when some component in the messaging system _does_ require access to information about the `Message`, such metadata can typically be stored to and retrieved from the metadata in the Message Headers.
[[message-headers]]
==== Message Headers
Just as Spring Integration allows any Object to be used as the payload of a Message, it also supports any Object types as header values.
In fact, the `MessageHeaders` class implements the _java.util.Map_ interface:
[source,java]
----
public final class MessageHeaders implements Map<String, Object>, Serializable {
...
}
----
NOTE: Even though the MessageHeaders implements Map, it is effectively a read-only implementation.
Any attempt to _put_ a value in the Map will result in an `UnsupportedOperationException`.
The same applies for _remove_ and _clear_.
Since Messages may be passed to multiple consumers, the structure of the Map cannot be modified.
Likewise, the Message's payload Object can not be _set_ after the initial creation.
However, the mutability of the header values themselves (or the payload Object) is intentionally left as a decision for the framework user.
As an implementation of Map, the headers can obviously be retrieved by calling `get(..)` with the name of the header.
Alternatively, you can provide the expected _Class_ as an additional parameter.
Even better, when retrieving one of the pre-defined values, convenient getters are available.
Here is an example of each of these three options:
[source,java]
----
Object someValue = message.getHeaders().get("someKey");
CustomerId customerId = message.getHeaders().get("customerId", CustomerId.class);
Long timestamp = message.getHeaders().getTimestamp();
----
The following Message headers are pre-defined:
.Pre-defined Message Headers
[cols="2l,2l,6", options="header"]
|===
| Header Name
| Header Type
| Usage
| MessageHeaders.ID
| java.util.UUID
| An identifier for this message instance.
Changes each time a message is mutated.
| MessageHeaders.
TIMESTAMP
| java.lang.Long
| The time the message was created.
Changes each time a message is mutated.
| MessageHeaders.
REPLY_CHANNEL
| java.lang.Object
(String or MessageChannel)
| A channel to which a reply (if any) will be sent when no explicit output channel is configured and there is no `ROUTING_SLIP` or the `ROUTING_SLIP` is exhausted.
If the value is a `String` it must represent a bean name, or have been generated by a `ChannelRegistry.`
| MessageHeaders.
ERROR_CHANNEL
| java.lang.Object
(String or MessageChannel)
| A channel to which errors will be sent.
If the value is a `String` it must represent a bean name, or have been generated by a `ChannelRegistry.`
|===
Many inbound and outbound adapter implementations will also provide and/or expect certain headers, and additional user-defined headers can also be configured.
Constants for these headers can be found in those modules where such headers exist, for example `AmqpHeaders`, `JmsHeaders` etc.
[[message-header-accessor]]
===== MessageHeaderAccessor API
Starting with Spring Framework 4.0 and Spring Integration 4.0, the core Messaging abstraction has been moved to the _spring-messaging_ module and the new `MessageHeaderAccessor` API has been introduced to provide additional abstraction over Messaging implementations.
All (core) Spring Integration specific Message Headers constants are now declared in the `IntegrationMessageHeaderAccessor` class:
.Pre-defined Message Headers
[cols="5l,3l,5", options="header"]
|===
| Header Name
| Header Type
| Usage
| IntegrationMessageHeaderAccessor.
CORRELATION_ID
| java.lang.Object
| Used to correlate two or more messages.
| IntegrationMessageHeaderAccessor.
SEQUENCE_NUMBER
| java.lang.Integer
| Usually a sequence number with a group of messages with a `SEQUENCE_SIZE` but can also be used in a `<resequencer/>` to resequence an unbounded group of messages.
| IntegrationMessageHeaderAccessor.
SEQUENCE_SIZE
| java.lang.Integer
| The number of messages within a group of correlated messages.
| IntegrationMessageHeaderAccessor.
EXPIRATION_DATE
| java.lang.Long
| Indicates when a message is expired.
Not used by the framework directly but can be set with a header enricher and used in a `<filter/>` configured with an `UnexpiredMessageSelector`.
| IntegrationMessageHeaderAccessor.
PRIORITY
| java.lang.Integer
| Message priority; for example within a `PriorityChannel`
| IntegrationMessageHeaderAccessor.
DUPLICATE_MESSAGE
| java.lang.Boolean
| True if a message was detected as a duplicate by an idempotent receiver interceptor.
See <<idempotent-receiver>>.
|===
Convenient typed getters for some of these headers are provided on the `IntegrationMessageHeaderAccessor` class:
[source,java]
----
IntegrationMessageHeaderAccessor accessor = new IntegrationMessageHeaderAccessor(message);
int sequenceNumber = accessor.getSequenceNumber();
Object correlationId = accessor.getCorrelationId();
...
----
The following headers also appear in the `IntegrationMessageHeaderAccessor` but are generally not used by user code; their inclusion here is for completeness:
.Pre-defined Message Headers
[cols="5l,3l,5", options="header"]
|===
| Header Name
| Header Type
| Usage
| IntegrationMessageHeaderAccessor.
SEQUENCE_DETAILS
| java.util.List<
List<Object>>
| A stack of correlation data used when nested correlation is needed (e.g.
`splitter->...->splitter->...->aggregator->...->aggregator`).
| IntegrationMessageHeaderAccessor.
ROUTING_SLIP
| java.util.Map<
List<Object>, Integer>
| See <<routing-slip>>.
|===
[[message-id-generation]]
===== Message ID Generation
When a message transitions through an application, each time it is mutated (e.g.
by a transformer) a new message id is assigned.
The message id is a `UUID`.
Beginning with _Spring Integration 3.0_, the default strategy used for id generation is more efficient than the previous `java.util.UUID.randomUUID()` implementation.
It uses simple random numbers based on a secure random seed, instead of creating a secure random number each time.
A different UUID generation strategy can be selected by declaring a bean that implements `org.springframework.util.IdGenerator` in the application context.
IMPORTANT: Only one UUID generation strategy can be used in a classloader.
This means that if two or more application contexts are running in the same classloader, they will share the same strategy.
If one of the contexts changes the strategy, it will be used by all contexts.
If two or more contexts in the same classloader declare a bean of type `org.springframework.util.IdGenerator`, they must all be an instance of the same class, otherwise the context attempting to replace a custom strategy will fail to initialize.
If the strategy is the same, but parameterized, the strategy in the first context to initialize will be used.
In addition to the default strategy, two additional `IdGenerators` are provided; `org.springframework.util.JdkIdGenerator` uses the previous `UUID.randomUUID()` mechanism; `o.s.i.support.IdGenerators.SimpleIncrementingIdGenerator` can be used in cases where a UUID is not really needed and a simple incrementing value is sufficient.
[[message-implementations]]
==== Message Implementations
The base implementation of the `Message` interface is `GenericMessage<T>`, and it provides two constructors:
[source,java]
----
new GenericMessage<T>(T payload);
new GenericMessage<T>(T payload, Map<String, Object> headers)
----
When a Message is created, a random unique id will be generated.
The constructor that accepts a Map of headers will copy the provided headers to the newly created Message.
There is also a convenient implementation of `Message` designed to communicate error conditions.
This implementation takes `Throwable` object as its payload:
[source,java]
----
ErrorMessage message = new ErrorMessage(someThrowable);
Throwable t = message.getPayload();
----
Notice that this implementation takes advantage of the fact that the `GenericMessage` base class is parameterized.
Therefore, as shown in both examples, no casting is necessary when retrieving the Message payload Object.
[[message-builder]]
==== The MessageBuilder Helper Class
You may notice that the Message interface defines retrieval methods for its payload and headers but no setters.
The reason for this is that a Message cannot be modified after its initial creation.
Therefore, when a Message instance is sent to multiple consumers (e.g.
through a Publish Subscribe Channel), if one of those consumers needs to send a reply with a different payload type, it will need to create a new Message.
As a result, the other consumers are not affected by those changes.
Keep in mind, that multiple consumers may access the same payload instance or header value, and whether such an instance is itself immutable is a decision left to the developer.
In other words, the contract for Messages is similar to that of an _unmodifiable Collection_, and the MessageHeaders' map further exemplifies that; even though the MessageHeaders class implements `java.util.Map`, any attempt to invoke a _put_ operation (or 'remove' or 'clear') on the MessageHeaders will result in an `UnsupportedOperationException`.
Rather than requiring the creation and population of a Map to pass into the GenericMessage constructor, Spring Integration does provide a far more convenient way to construct Messages: `MessageBuilder`.
The MessageBuilder provides two factory methods for creating Messages from either an existing Message or with a payload Object.
When building from an existing Message, the headers _and payload_ of that Message will be copied to the new Message:
[source,java]
----
Message<String> message1 = MessageBuilder.withPayload("test")
.setHeader("foo", "bar")
.build();
Message<String> message2 = MessageBuilder.fromMessage(message1).build();
assertEquals("test", message2.getPayload());
assertEquals("bar", message2.getHeaders().get("foo"));
----
If you need to create a Message with a new payload but still want to copy the headers from an existing Message, you can use one of the 'copy' methods.
[source,java]
----
Message<String> message3 = MessageBuilder.withPayload("test3")
.copyHeaders(message1.getHeaders())
.build();
Message<String> message4 = MessageBuilder.withPayload("test4")
.setHeader("foo", 123)
.copyHeadersIfAbsent(message1.getHeaders())
.build();
assertEquals("bar", message3.getHeaders().get("foo"));
assertEquals(123, message4.getHeaders().get("foo"));
----
Notice that the `copyHeadersIfAbsent` does not overwrite existing values.
Also, in the second example above, you can see how to set any user-defined header with `setHeader`.
Finally, there are set methods available for the predefined headers as well as a non-destructive method for setting any header (MessageHeaders also defines constants for the pre-defined header names).
[source,java]
----
Message<Integer> importantMessage = MessageBuilder.withPayload(99)
.setPriority(5)
.build();
assertEquals(5, importantMessage.getHeaders().getPriority());
Message<Integer> lessImportantMessage = MessageBuilder.fromMessage(importantMessage)
.setHeaderIfAbsent(IntegrationMessageHeaderAccessor.PRIORITY, 2)
.build();
assertEquals(2, lessImportantMessage.getHeaders().getPriority());
----
The `priority` header is only considered when using a `PriorityChannel` (as described in the next chapter).
It is defined as _java.lang.Integer_.

11
src/reference/asciidoc/messaging-channels.adoc Normal file
View File

@@ -0,0 +1,11 @@
[[messaging-channels-section]]
== Messaging Channels
// BE SURE TO PRECEDE ALL include:: with a blank line - see https://github.com/asciidoctor/asciidoctor/issues/1297
include::./channel.adoc[]
include::./polling-consumer.adoc[]
include::./channel-adapter.adoc[]
include::./bridge.adoc[]

20
src/reference/asciidoc/messaging-endpoints.adoc Normal file
View File

@@ -0,0 +1,20 @@
[[messaging-endpoints-chapter]]
== Messaging Endpoints
// BE SURE TO PRECEDE ALL include:: with a blank line - see https://github.com/asciidoctor/asciidoctor/issues/1297
include::./endpoint.adoc[]
include::./gateway.adoc[]
include::./service-activator.adoc[]
include::./delayer.adoc[]
include::./scripting.adoc[]
include::./groovy.adoc[]
include::./handler-advice.adoc[]
include::./logging-adapter.adoc[]
// BE SURE TO PRECEDE ALL include:: with a blank line - see https://github.com/asciidoctor/asciidoctor/issues/1297

58
src/reference/asciidoc/meta-data-store.adoc Normal file
View File

@@ -0,0 +1,58 @@
[[metadata-store]]
=== Metadata Store
Many external systems, services or resources aren't transactional (Twitter, RSS, file system etc.) and there is no any ability to mark the data as read.
Or there is just need to implement the Enterprise Integration Pattern http://eaipatterns.com/IdempotentReceiver.html[Idempotent Receiver] in some integration solutions.
To achieve this goal and store some previous state of the Endpoint before the next interaction with external system, or deal with the next Message, Spring Integration provides the _Metadata Store_ component being an implementation of the `org.springframework.integration.metadata.MetadataStore` interface with a general _key-value_ contract.
The _Metadata Store_ is designed to store various types of generic meta-data (e.g., published date of the last feed entry that has been processed) to help components such as the Feed adapter deal with duplicates.
If a component is not directly provided with a reference to a `MetadataStore`, the algorithm for locating a metadata store is as follows: First, look for a bean with id `metadataStore` in the ApplicationContext.
If one is found then it will be used, otherwise it will create a new instance of `SimpleMetadataStore` which is an in-memory implementation that will only persist metadata within the lifecycle of the currently running Application Context.
This means that upon restart you may end up with duplicate entries.
If you need to persist metadata between Application Context restarts, two persistent `MetadataStores` are provided by the framework:
* PropertiesPersistingMetadataStore
* <<redis-metadata-store>>
* <<gemfire-metadata-store>>
The `PropertiesPersistingMetadataStore` is backed by a properties file and a http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/util/PropertiesPersister.html[PropertiesPersister].
[source,xml]
----
<bean id="metadataStore"
class="org.springframework.integration.store.PropertiesPersistingMetadataStore"/>
----
Alternatively, you can provide your own implementation of the `MetadataStore` interface (e.g.
JdbcMetadataStore) and configure it as a bean in the Application Context.
Starting with _version 4.0_, `SimpleMetadataStore`, `PropertiesPersistingMetadataStore` and `RedisMetadataStore` implement `ConcurrentMetadataStore`.
These provide for atomic updates and can be used across multiple component or application instances.
[[idempotent-receiver-pattern]]
==== Idempotent Receiver and Metadata Store
The _Metadata Store_ is useful for implementing the EIP http://eaipatterns.com/IdempotentReceiver.html[Idempotent Receiver] pattern, when there is need to _filter_ an incoming Message if it has already been processed, and just discard it or perform some other logic on discarding.
The following configuration is an example of how to do this:
[source,xml]
----
<int:filter input-channel="serviceChannel"
output-channel="idempotentServiceChannel"
discard-channel="discardChannel"
expression="@metadataStore.get(headers.businessKey) == null"/>
<int:publish-subscribe-channel id="idempotentServiceChannel"/>
<int:outbound-channel-adapter channel="idempotentServiceChannel"
expression="@metadataStore.put(headers.businessKey, '')"/>
<int:service-activator input-channel="idempotentServiceChannel" ref="service"/>
----
The `value` of the idempotent entry may be some expiration date, after which that entry should be removed from _Metadata Store_ by some scheduled reaper.
Also see <<idempotent-receiver>>.

260
src/reference/asciidoc/mongodb.adoc Normal file
View File

@@ -0,0 +1,260 @@
[[mongodb]]
== MongoDb Support
As of version 2.1 Spring Integration introduces support for http://www.mongodb.org/[MongoDB]: a _"high-performance, open source, document-oriented database"_.
This support comes in the form of a MongoDB-based MessageStore.
[[mongodb-intro]]
=== Introduction
To download, install, and run MongoDB please refer to the http://www.mongodb.org/downloads[MongoDB documentation].
[[mongodb-connection]]
=== Connecting to MongoDb
To begin interacting with MongoDB you first need to connect to it.
Spring Integration builds on the support provided by another Spring project, http://www.springsource.org/spring-data/mongodb[Spring Data MongoDB], which provides a factory class called `MongoDbFactory` that simplifies integration with the MongoDB Client API.
_MongoDbFactory_
To connect to MongoDB you can use an implementation of the `MongoDbFactory` interface:
[source,java]
----
public interface MongoDbFactory {
/**
* Creates a default {@link DB} instance.
*
* @return the DB instance
* @throws DataAccessException
*/
DB getDb() throws DataAccessException;
/**
* Creates a {@link DB} instance to access the database with the given name.
*
* @param dbName must not be {@literal null} or empty.
*
* @return the DB instance
* @throws DataAccessException
*/
DB getDb(String dbName) throws DataAccessException;
}
----
The example below shows `SimpleMongoDbFactory`, the out-of-the-box implementation:
In Java:
[source,java]
----
MongoDbFactory mongoDbFactory = new SimpleMongoDbFactory(new Mongo(), "test");
----
Or in Spring's XML configuration:
[source,xml]
----
<bean id="mongoDbFactory" class="o.s.data.mongodb.core.SimpleMongoDbFactory">
<constructor-arg>
<bean class="com.mongodb.Mongo"/>
</constructor-arg>
<constructor-arg value="test"/>
</bean>
----
As you can see `SimpleMongoDbFactory` takes two arguments: 1) a `Mongo` instance and 2) a String specifying the name of the database.
If you need to configure properties such as `host`, `port`, etc, you can pass those using one of the constructors provided by the underlying `Mongo` class.
For more information on how to configure MongoDB, please refer to thehttp://static.springsource.org/spring-data/data-document/docs/current/reference/html/[Spring-Data-Document] reference.
[[mongodb-message-store]]
=== MongoDB Message Store
As described in EIP, a http://www.eaipatterns.com/MessageStore.html[Message Store] allows you to persist Messages.
This can be very useful when dealing with components that have a capability to buffer messages (_QueueChannel, Aggregator, Resequencer_, etc.) if reliability is a concern.
In Spring Integration, the MessageStore strategy also provides the foundation for thehttp://www.eaipatterns.com/StoreInLibrary.html[ClaimCheck] pattern, which is described in EIP as well.
Spring Integration's MongoDB module provides the `MongoDbMessageStore` which is an implementation of both the `MessageStore` strategy (mainly used by the _ClaimCheck_pattern) and the `MessageGroupStore` strategy (mainly used by the _Aggregator_ and _Resequencer_ patterns).
[source,xml]
----
<bean id="mongoDbMessageStore" class="o.s.i.mongodb.store.MongoDbMessageStore">
<constructor-arg ref="mongoDbFactory"/>
</bean>
<int:channel id="somePersistentQueueChannel">
<int:queue message-store="mongoDbMessageStore"/>
<int:channel>
<int:aggregator input-channel="inputChannel" output-channel="outputChannel"
message-store="mongoDbMessageStore"/>
----
Above is a sample `MongoDbMessageStore` configuration that shows its usage by a _QueueChannel_ and an _Aggregator_.
As you can see it is a simple bean configuration, and it expects a `MongoDbFactory` as a constructor argument.
The `MongoDbMessageStore` expands the `Message` as a Mongo document with all nested properties using the Spring Data Mongo Mapping mechanism.
It is useful when you need to have access to the `payload` or `headers` for auditing or analytics, for example, against stored messages.
IMPORTANT: The `MongoDbMessageStore` uses a custom `MappingMongoConverter` implementation to store `Message` s as MongoDB documents and there are some limitations for the properties (`payload` and `header` values) of the `Message`.
For example, there is no ability to configure custom converters for complex domain `payload` s or `header` values.
Or to provide a custom `MongoTemplate` (or `MappingMongoConverter`).
To achieve these capabilities, an alternative MongoDB `MessageStore` implementation has been introduced; see next paragraph.
_Spring Integration 3.0_ introduced the `ConfigurableMongoDbMessageStore` - `MessageStore` and `MessageGroupStore` implementation.
This class can receive, as a constructor argument, a `MongoTemplate`, with which you can configure with a custom `WriteConcern`, for example.
Another constructor requires a `MappingMongoConverter`, and a `MongoDbFactory`, which allows you to provide some custom conversions for `Message` s and their properties.
Note, by default, the `ConfigurableMongoDbMessageStore` uses standard Java serialization to write/read `Message` s to/from MongoDB and relies on default values for other properties from `MongoTemplate`, which is built from the provided `MongoDbFactory` and `MappingMongoConverter`.
The default name for the collection stored by the `ConfigurableMongoDbMessageStore` is `configurableStoreMessages`.
It is recommended to use this implementation for robust and flexible solutions when messages contain complex data types.
[[mongodb-priority-channel-message-store]]
==== MongodDB Channel Message Store
Starting with _version 4.0_, the new `MongoDbChannelMessageStore` has been introduced; it is an optimized `MessageGroupStore` for use in `QueueChannel` s.
With `priorityEnabled = true`, it can be used in `<int:priority-queue>` s to achieve _priority_ order polling for persisted messages.
The _priority_ MonogDB document field is populated from the `IntegrationMessageHeaderAccessor.PRIORITY` (`priority`) message header.
In addition, all MongoDB `MessageStore` s now have a `sequence` field for MessageGroup documents.
The `sequence` value is the result of an `$inc` operation for a simple `sequence` document from the same collection, which is created on demand.
The `sequence` field is used in `poll` operations to provide first-in-first-out (FIFO) message order (within priority if configured) when messages are stored within the same millisecond.
NOTE: It is not recommended to use the same `MongoDbChannelMessageStore` bean for priority and non-priority, because the `priorityEnabled` option applies to the entire store.
However, the same `collection` can be used for both `MongoDbChannelMessageStore` types, because message polling from the store is sorted and uses indexes.
To configure that scenario, simply extend one message store bean from the other:
[source,xml]
----
<bean id="channelStore" class="o.s.i.mongodb.store.MongoDbChannelMessageStore">
<constructor-arg name="mongoDbFactory" ref="mongoDbFactory"/>
</bean>
<int:channel id="queueChannel">
<int:queue message-store="store"/>
</int:channel>
<bean id="priorityStore" parent="channelStore">
<property name="priorityEnabled" value="true"/>
</bean>
<int:channel id="priorityChannel">
<int:priority-queue message-store="priorityStore"/>
</int:channel>
----
[[mongodb-inbound-channel-adapter]]
=== MongoDB Inbound Channel Adapter
The _MongoDb Inbound Channel Adapter_ is a polling consumer that reads data from MongoDb and sends it as a Message payload.
[source,xml]
----
<int-mongodb:inbound-channel-adapter id="mongoInboundAdapter"
channel="replyChannel"
query="{'name' : 'Bob'}"
entity-class="java.lang.Object"
auto-startup="false">
<int:poller fixed-rate="100"/>
</int-mongodb:inbound-channel-adapter>
----
As you can see from the configuration above, you configure a _MongoDb Inbound Channel Adapter_ using the `inbound-channel-adapter` element, providing values for various attributes such as:
* `query` or `query-expression` - a JSON query (see http://www.mongodb.org/display/DOCS/Querying[MongoDb Querying])
* `entity-class` - the type of the payload object; if not supplied, a `com.mongodb.DBObject` will be returned.
* `collection-name` or `collection-name-expression` - Identifies the name of the MongoDb collection to use.
* `mongodb-factory` - reference to an instance of `o.s.data.mongodb.MongoDbFactory`
* `mongo-template` - reference to an instance of `o.s.data.mongodb.core.MongoTemplate`
and other attributes that are common across all other inbound adapters (e.g., 'channel').
NOTE: You cannot set both `mongo-template` and `mongodb-factory`.
The example above is relatively simple and static since it has a literal value for the `query` and uses the default name for a `collection`.
Sometimes you may need to change those values at runtime, based on some condition.
To do that, simply use their `-expression` equivalents (`query-expression` and `collection-name-expression`) where the provided expression can be any valid SpEL expression.
Also, you may wish to do some post-processing to the successfully processed data that was read from the MongoDb.
For example; you may want to move or remove a document after its been processed.
You can do this using Transaction Synchronization feature that was added with Spring Integration 2.2.
[source,xml]
----
<int-mongodb:inbound-channel-adapter id="mongoInboundAdapter"
channel="replyChannel"
query="{'name' : 'Bob'}"
entity-class="java.lang.Object"
auto-startup="false">
<int:poller fixed-rate="200" max-messages-per-poll="1">
<int:transactional synchronization-factory="syncFactory"/>
</int:poller>
</int-mongodb:inbound-channel-adapter>
<int:transaction-synchronization-factory id="syncFactory">
<int:after-commit expression="@documentCleaner.remove(#mongoTemplate, payload, headers.mongo_collectionName)" channe="someChannel"/>
</int:transaction-synchronization-factory>
<bean id="documentCleaner" class="foo.bar.DocumentCleaner"/>
<bean id="transactionManager" class="o.s.i.transaction.PseudoTransactionManager"/>
----
[source,java]
----
public class DocumentCleaner {
public void remove(MongoOperations mongoOperations, Object target, String collectionName) {
if (target instanceof List<?>){
List<?> documents = (List<?>) target;
for (Object document : documents) {
mongoOperations.remove(new BasicQuery(JSON.serialize(document)), collectionName);
}
}
}
}
----
As you can see from the above, all you need to do is declare your poller to be transactional with a `transactional` element.
This element can reference a real transaction manager (for example if some other part of your flow invokes JDBC).
If you don't have a 'real' transaction, you can use a `org.springframework.integration.transaction.PseudoTransactionManager` which is an implementation of Spring's `PlatformTransactionManager` and enables the use of the transaction synchronization features of the mongo adapter when there is no actual transaction.
IMPORTANT: This does NOT make MongoDB itself transactional, it simply allows the synchronization of actions to be taken before/after success (commit) or after failure (rollback).
Once your poller is transactional all you need to do is set an instance of the `org.springframework.integration.transaction.TransactionSynchronizationFactory` on the `transactional` element.
`TransactionSynchronizationFactory` will create an instance of the `TransactioinSynchronization`.
For your convenience, we've exposed a default SpEL-based `TransactionSynchronizationFactory` which allows you to configure SpEL expressions, with their execution being coordinated (synchronized) with a transaction.
Expressions for before-commit, after-commit, and after-rollback are supported, together with a channel for each where the evaluation result (if any) will be sent.
For each sub-element you can specify `expression` and/or `channel` attributes.
If only the `channel` attribute is present the received Message will be sent there as part of the particular synchronization scenario.
If only the `expression` attribute is present and the result of an expression is a non-Null value, a Message with the result as the payload will be generated and sent to a default channel (NullChannel) and will appear in the logs (DEBUG).
If you want the evaluation result to go to a specific channel add a `channel` attribute.
If the result of an expression is null or void, no Message will be generated.
For more information about transaction synchronization, see <<transaction-synchronization>>.
[[mongodb-outbound-channel-adapter]]
=== MongoDB Outbound Channel Adapter
The _MongoDb Outbound Channel Adapter_ allows you to write the Message payload to a MongoDb document store
[source,xml]
----
<int-mongodb:outbound-channel-adapter id="fullConfigWithCollectionExpression"
collection-name="myCollection"
mongo-converter="mongoConverter"
mongodb-factory="mongoDbFactory" />
----
As you can see from the configuration above, you configure a _MongoDb Outbound Channel Adapter_ using the `outbound-channel-adapter` element, providing values for various attributes such as:
* `collection-name` or `collection-name-expression` - Identifies the name of the MongoDb collection to use.
* `mongo-converter` - reference to an instance of `o.s.data.mongodb.core.convert.MongoConverter` to assist with converting a raw java object to a JSON document representation
* `mongodb-factory` - reference to an instance of `o.s.data.mongodb.MongoDbFactory`
* `mongo-template` - reference to an instance of `o.s.data.mongodb.core.MongoTemplate` (NOTE: you can not have both mongo-template and mongodb-factory set)
and other attributes that are common across all other inbound adapters (e.g., 'channel').
The example above is relatively simple and static since it has a literal value for the `collection-name`.
Sometimes you may need to change this value at runtime based on some condition.
To do that, simply use `collection-name-expression` where the provided expression can be any valid SpEL expression.

160
src/reference/asciidoc/mqtt.adoc Normal file
View File

@@ -0,0 +1,160 @@
[[mqtt]]
== MQTT Support
[[mqtt-intro]]
=== Introduction
Spring Integration provides inbound and outbound channel adapters supporting the MQ Telemetry Transport (MQTT) protocol.
The current implementation uses the http://www.eclipse.org/paho/[Eclipse Paho MQTT Client] library.
Configuration of both adapters is achieved using the `DefaultMqttPahoClientFactory`.
Refer to the Paho documentation for more information about configuration options.
[[mqtt-inbound]]
=== Inbound (message-driven) Channel Adapter
The inbound channel adapter is implemented by the `MqttPahoMessageDrivenChannelAdapter`.
For convenience, it can be configured using the namespace.
A minimal configuration might be:
[source,xml]
----
<bean id="clientFactory"
class="org.springframework.integration.mqtt.core.DefaultMqttPahoClientFactory">
<property name="userName" value="${mqtt.username}"/>
<property name="password" value="${mqtt.password}"/>
</bean>
<int-mqtt:message-driven-channel-adapter id="mqttInbound"
client-id="${mqtt.default.client.id}.src"
url="${mqtt.url}"
topics="sometopic"
client-factory="clientFactory"
channel="output"/>
----
Attributes:
[source]
----
<int-mqtt:message-driven-channel-adapter id="oneTopicAdapter"
client-id="foo" <1>
url="tcp://localhost:1883" <2>
topics="bar,baz" <3>
qos="1,2" <4>
converter="myConverter" <5>
client-factory="clientFactory" <6>
send-timeout="123" <7>
error-channel="errors" <8>
channel="out" />
----
<1> The client id.
<2> The broker URL.
<3> A comma delimited list of topics from which this adapter will receive messages.
<4> A comma delimited list of QoS values.
Can be a single value that is applied to all topics, or a value for each topic (in which case the lists must the same length).
<5> An `MqttMessageConverter` (optional).
The default `DefaultPahoMessageConverter` produces a message with a `String` payload (by default) with the following headers: +
`mqtt_topic` - the topic from which the message was received +
`mqtt_duplicate` - true if the message is a duplicate +
`mqtt_qos` - the quality of service +
The `DefaultPahoMessageConverter` can be configured to return the raw `byte[]` in the payload by declaring it as a `<bean/>` and setting the `payloadAsBytes` property.
<6> The client factory.
<7> The send timeout - only applies if the channel might block (such as a bounded `QueueChannel` that is currently full).
<8> The error channel - downstream exceptions will be sent to this channel, if supplied, in an `ErrorMessage`; the payload is a `MessagingException` containing the failed message and cause.
NOTE: Starting with _version 4.1_ the url can be omitted and, instead, the server URIs can be provided in the `serverURIs` property of the `DefaultMqttPahoClientFactory`.
This enables, for example, connection to a highly available (HA) cluster.
==== Adding/Removing Topics at Runtime
Starting with _version 4.1_, it is possible to programmatically change the topics to which the adapter is subscribed.
Methods `addTopic()` and `removeTopic()` are provided.
When adding topics, you can optionally specify the `QoS` (default: 1).
You can also modify the topics by sending an appropriate message to a `<control-bus/>` with an appropriate payload: `"myMqttAdapter.addTopic('foo', 1)"`.
Stopping/starting the adapter has no effect on the topic list (it does *not* revert to the original settings in the configuration).
The changes are not retained beyond the life cycle of the application context; a new application context will revert to the configured settings.
Changing the topics while the adapter is stopped (or disconnected from the broker) will take effect the next time a connection is established.
[[mqtt-outbound]]
=== Outbound Channel Adapter
The outbound channel adapter is implemented by the `MqttPahoMessageHandler` which is wrapped in a `ConsumerEndpoint`.
For convenience, it can be configured using the namespace.
Starting with _version 4.1_, the adapter supports asynchronous sends, avoiding blocking until the delivery is confirmed; application events can be emitted to enable applications to confirm delivery if desired.
Attributes:
[source]
----
<int-mqtt:outbound-channel-adapter id="withConverter"
client-id="foo" <1>
url="tcp://localhost:1883" <2>
converter="myConverter" <3>
client-factory="clientFactory" <4>
default-qos="1" <5>
default-retained="true" <6>
default-topic="bar" <7>
async="false" <8>
async-events="false" <9>
channel="target" />
----
<1> The client id.
<2> The broker URL.
<3> An `MqttMessageConverter` (optional).
The default `DefaultPahoMessageConverter` recognizes the following headers: +
`mqtt_topic` - the topic to which the message will be sent +
`mqtt_retained` - true if the message is to be retained +
`mqtt_qos` - the quality of service
<4> The client factory.
<5> The default quality of service (used if no `mqtt_qos` header is found).
Not allowed if a custom `converter` is supplied.
<6> The default value of the retained flag (used if no `mqtt_retaind` header is found).
Not allowed if a custom `converter` is supplied.
<7> The default topic to which the message will be sent (used if no `mqtt_topic` header is found).
<8> When `true`, the caller will not block waiting for delivery confirmation when a message is sent.
Default:false (the send blocks until delivery is confirmed).
<9> When `async` and `async-events` are both `true`, an `MqttMessageSentEvent` is emitted, containing the message, the topic, the `messageId` generated by the client library, the `clientId` and the `clientInstance` (incremented each time the client is connected).
When the delivery is confirmed by the client library, an `MqttMessageDeliveredEvent` is emitted, containing the the `messageId`, `clientId` and the `clientInstance`, enabling delivery to be correlated with the send.
These events can be received by any `ApplicationListener`, or by an event inbound channel adapter.
Note that it is possible that the `MqttMessageDeliveredEvent` might be received before the `MqttMessageSentEvent`.
Default: `false`.
NOTE: Starting with _version 4.1_ the url can be omitted and, instead, the server URIs can be provided in the `serverURIs` property of the `DefaultMqttPahoClientFactory`.
This enables, for example, connection to a highly available (HA) cluster.

249
src/reference/asciidoc/overview.adoc Normal file
View File

@@ -0,0 +1,249 @@
[[overview]]
== Spring Integration Overview
[[overview-background]]
=== Background
One of the key themes of the Spring Framework is _inversion of control_.
In its broadest sense, this means that the framework handles responsibilities on behalf of the components that are managed within its context.
The components themselves are simplified since they are relieved of those responsibilities.
For example, _dependency injection_ relieves the components of the responsibility of locating or creating their dependencies.
Likewise, _aspect-oriented programming_ relieves business components of generic cross-cutting concerns by modularizing them into reusable aspects.
In each case, the end result is a system that is easier to test, understand, maintain, and extend.
Furthermore, the Spring framework and portfolio provide a comprehensive programming model for building enterprise applications.
Developers benefit from the consistency of this model and especially the fact that it is based upon well-established best practices such as programming to interfaces and favoring composition over inheritance.
Spring's simplified abstractions and powerful support libraries boost developer productivity while simultaneously increasing the level of testability and portability.
Spring Integration is motivated by these same goals and principles.
It extends the Spring programming model into the messaging domain and builds upon Spring's existing enterprise integration support to provide an even higher level of abstraction.
It supports message-driven architectures where inversion of control applies to runtime concerns, such as _when_ certain business logic should execute and _where_ the response should be sent.
It supports routing and transformation of messages so that different transports and different data formats can be integrated without impacting testability.
In other words, the messaging and integration concerns are handled by the framework, so business components are further isolated from the infrastructure and developers are relieved of complex integration responsibilities.
As an extension of the Spring programming model, Spring Integration provides a wide variety of configuration options including annotations, XML with namespace support, XML with generic "bean" elements, and of course direct usage of the underlying API.
That API is based upon well-defined strategy interfaces and non-invasive, delegating adapters.
Spring Integration's design is inspired by the recognition of a strong affinity between common patterns within Spring and the well-known http://www.eaipatterns.com[Enterprise Integration Patterns] as described in the book of the same name by Gregor Hohpe and Bobby Woolf (Addison Wesley, 2004).
Developers who have read that book should be immediately comfortable with the Spring Integration concepts and terminology.
[[overview-goalsandprinciples]]
=== Goals and Principles
Spring Integration is motivated by the following goals:
* Provide a simple model for implementing complex enterprise integration solutions.
* Facilitate asynchronous, message-driven behavior within a Spring-based application.
* Promote intuitive, incremental adoption for existing Spring users.
Spring Integration is guided by the following principles:
* Components should be _loosely coupled_ for modularity and testability.
* The framework should enforce _separation of concerns_ between business logic and integration logic.
* Extension points should be abstract in nature but within well-defined boundaries to promote _reuse_ and _portability_.
[[overview-components]]
=== Main Components
From the _vertical_ perspective, a layered architecture facilitates separation of concerns, and interface-based contracts between layers promote loose coupling.
Spring-based applications are typically designed this way, and the Spring framework and portfolio provide a strong foundation for following this best practice for the full-stack of an enterprise application.
Message-driven architectures add a_horizontal_ perspective, yet these same goals are still relevant.
Just as "layered architecture" is an extremely generic and abstract paradigm, messaging systems typically follow the similarly abstract "pipes-and-filters" model.
The "filters" represent any component that is capable of producing and/or consuming messages, and the "pipes" transport the messages between filters so that the components themselves remain loosely-coupled.
It is important to note that these two high-level paradigms are not mutually exclusive.
The underlying messaging infrastructure that supports the "pipes" should still be encapsulated in a layer whose contracts are defined as interfaces.
Likewise, the "filters" themselves would typically be managed within a layer that is logically above the application's service layer, interacting with those services through interfaces much in the same way that a web-tier would.
[[overview-components-message]]
==== Message
In Spring Integration, a Message is a generic wrapper for any Java object combined with metadata used by the framework while handling that object.
It consists of a payload and headers.
The payload can be of any type and the headers hold commonly required information such as id, timestamp, correlation id, and return address.
Headers are also used for passing values to and from connected transports.
For example, when creating a Message from a received File, the file name may be stored in a header to be accessed by downstream components.
Likewise, if a Message's content is ultimately going to be sent by an outbound Mail adapter, the various properties (to, from, cc, subject, etc.) may be configured as Message header values by an upstream component.
Developers can also store any arbitrary key-value pairs in the headers.
.Message
image::images/message.jpg["Message", align="center"]
[[overview-components-channel]]
==== Message Channel
A Message Channel represents the "pipe" of a pipes-and-filters architecture.
Producers send Messages to a channel, and consumers receive Messages from a channel.
The Message Channel therefore decouples the messaging components, and also provides a convenient point for interception and monitoring of Messages.
.Message Channel
image::images/channel.jpg["Message Channel", align="center"]
A Message Channel may follow either Point-to-Point or Publish/Subscribe semantics.
With a Point-to-Point channel, at most one consumer can receive each Message sent to the channel.
Publish/Subscribe channels, on the other hand, will attempt to broadcast each Message to all of its subscribers.
Spring Integration supports both of these.
Whereas "Point-to-Point" and "Publish/Subscribe" define the two options for _how many_ consumers will ultimately receive each Message, there is another important consideration: should the channel buffer messages? In Spring Integration, _Pollable Channels_ are capable of buffering Messages within a queue.
The advantage of buffering is that it allows for throttling the inbound Messages and thereby prevents overloading a consumer.
However, as the name suggests, this also adds some complexity, since a consumer can only receive the Messages from such a channel if a _poller_ is configured.
On the other hand, a consumer connected to a _Subscribable Channel_ is simply Message-driven.
The variety of channel implementations available in Spring Integration will be discussed in detail in<<channel-implementations>>.
[[overview-components-endpoint]]
==== Message Endpoint
One of the primary goals of Spring Integration is to simplify the development of enterprise integration solutions through _inversion of control_.
This means that you should not have to implement consumers and producers directly, and you should not even have to build Messages and invoke send or receive operations on a Message Channel.
Instead, you should be able to focus on your specific domain model with an implementation based on plain Objects.
Then, by providing declarative configuration, you can "connect" your domain-specific code to the messaging infrastructure provided by Spring Integration.
The components responsible for these connections are Message Endpoints.
This does not mean that you will necessarily connect your existing application code directly.
Any real-world enterprise integration solution will require some amount of code focused upon integration concerns such as _routing_ and _transformation_.
The important thing is to achieve separation of concerns between such integration logic and business logic.
In other words, as with the Model-View-Controller paradigm for web applications, the goal should be to provide a thin but dedicated layer that translates inbound requests into service layer invocations, and then translates service layer return values into outbound replies.
The next section will provide an overview of the Message Endpoint types that handle these responsibilities, and in upcoming chapters, you will see how Spring Integration's declarative configuration options provide a non-invasive way to use each of these.
[[overview-endpoints]]
=== Message Endpoints
A Message Endpoint represents the "filter" of a pipes-and-filters architecture.
As mentioned above, the endpoint's primary role is to connect application code to the messaging framework and to do so in a non-invasive manner.
In other words, the application code should ideally have no awareness of the Message objects or the Message Channels.
This is similar to the role of a Controller in the MVC paradigm.
Just as a Controller handles HTTP requests, the Message Endpoint handles Messages.
Just as Controllers are mapped to URL patterns, Message Endpoints are mapped to Message Channels.
The goal is the same in both cases: isolate application code from the infrastructure.
These concepts are discussed at length along with all of the patterns that follow in the http://www.eaipatterns.com[Enterprise Integration Patterns] book.
Here, we provide only a high-level description of the main endpoint types supported by Spring Integration and their roles.
The chapters that follow will elaborate and provide sample code as well as configuration examples.
[[overview-endpoints-transformer]]
==== Transformer
A Message Transformer is responsible for converting a Message's content or structure and returning the modified Message.
Probably the most common type of transformer is one that converts the payload of the Message from one format to another (e.g.
from XML Document to java.lang.String).
Similarly, a transformer may be used to add, remove, or modify the Message's header values.
[[overview-endpoints-filter]]
==== Filter
A Message Filter determines whether a Message should be passed to an output channel at all.
This simply requires a boolean test method that may check for a particular payload content type, a property value, the presence of a header, etc.
If the Message is accepted, it is sent to the output channel, but if not it will be dropped (or for a more severe implementation, an Exception could be thrown).
Message Filters are often used in conjunction with a Publish Subscribe channel, where multiple consumers may receive the same Message and use the filter to narrow down the set of Messages to be processed based on some criteria.
NOTE: Be careful not to confuse the generic use of "filter" within the Pipes-and-Filters architectural pattern with this specific endpoint type that selectively narrows down the Messages flowing between two channels.
The Pipes-and-Filters concept of "filter" matches more closely with Spring Integration's Message Endpoint: any component that can be connected to Message Channel(s) in order to send and/or receive Messages.
[[overview-endpoints-router]]
==== Router
A Message Router is responsible for deciding what channel or channels should receive the Message next (if any).
Typically the decision is based upon the Message's content and/or metadata available in the Message Headers.
A Message Router is often used as a dynamic alternative to a statically configured output channel on a Service Activator or other endpoint capable of sending reply Messages.
Likewise, a Message Router provides a proactive alternative to the reactive Message Filters used by multiple subscribers as described above.
.Router
image::images/router.jpg["Router", align="center"]
[[overview-endpoints-splitter]]
==== Splitter
A Splitter is another type of Message Endpoint whose responsibility is to accept a Message from its input channel, split that Message into multiple Messages, and then send each of those to its output channel.
This is typically used for dividing a "composite" payload object into a group of Messages containing the sub-divided payloads.
[[overview-endpoints-aggregator]]
==== Aggregator
Basically a mirror-image of the Splitter, the Aggregator is a type of Message Endpoint that receives multiple Messages and combines them into a single Message.
In fact, Aggregators are often downstream consumers in a pipeline that includes a Splitter.
Technically, the Aggregator is more complex than a Splitter, because it is required to maintain state (the Messages to-be-aggregated), to decide when the complete group of Messages is available, and to timeout if necessary.
Furthermore, in case of a timeout, the Aggregator needs to know whether to send the partial results or to discard them to a separate channel.
Spring Integration provides a `CompletionStrategy` as well as configurable settings for timeout, whether to send partial results upon timeout, and the discard channel.
[[overview-endpoints-service-activator]]
==== Service Activator
A Service Activator is a generic endpoint for connecting a service instance to the messaging system.
The input Message Channel must be configured, and if the service method to be invoked is capable of returning a value, an output Message Channel may also be provided.
NOTE: The output channel is optional, since each Message may also provide its own 'Return Address' header.
This same rule applies for all consumer endpoints.
The Service Activator invokes an operation on some service object to process the request Message, extracting the request Message's payload and converting if necessary (if the method does not expect a Message-typed parameter).
Whenever the service object's method returns a value, that return value will likewise be converted to a reply Message if necessary (if it's not already a Message).
That reply Message is sent to the output channel.
If no output channel has been configured, then the reply will be sent to the channel specified in the Message's "return address" if available.
.A request-reply "Service Activator" endpoint connects a target object's method to input and output Message Channels.
image::images/handler-endpoint.jpg[align="center", scaledwidth=100%]
[[overview-endpoints-channeladapter]]
==== Channel Adapter
A Channel Adapter is an endpoint that connects a Message Channel to some other system or transport.
Channel Adapters may be either inbound or outbound.
Typically, the Channel Adapter will do some mapping between the Message and whatever object or resource is received-from or sent-to the other system (File, HTTP Request, JMS Message, etc).
Depending on the transport, the Channel Adapter may also populate or extract Message header values.
Spring Integration provides a number of Channel Adapters, and they will be described in upcoming chapters.
.An inbound "Channel Adapter" endpoint connects a source system to a MessageChannel.
image::images/source-endpoint.jpg[align="center", scaledwidth=100%]
.An outbound "Channel Adapter" endpoint connects a MessageChannel to a target system.
image::images/target-endpoint.jpg[align="center", scaledwidth=100%]
=== Configuration
Throughout this document you will see references to XML namespace support for declaring elements in a Spring Integration flow.
This support is provided by a series of namespace parsers that generate appropriate bean definitions to implement a particular component.
For example, many endpoints consist of a `MessageHandler` bean and a `ConsumerEndpointFactoryBean` into which the handler and an input channel name are injected.
The first time a Spring Integration namespace element is encountered, the framework automatically declares a number of beans that are used to support the runtime environment (task scheduler, implicit channel creator, etc).
Starting with _version 4.0_, these support beans can also be defined when using `@Configuration` classes, by adding a new annotation `@EnableIntegration`.
This is useful when declaring a simple Spring Integration flow using purely Java Configuration.
For example; you can declare an endpoint with a `MessageHandler` `@Bean` as well as a `ConsumerEndpointFactoryBean` `@Bean`.
`@EnableIntegration` is also useful when you have a parent context with no Spring Integration components and 2 or more child contexts that do use Spring Integration.
It would enable these common components to be declared once only, in the parent context.
The `@IntegrationComponentScan` annotation has also been introduced to permit classpath scanning.
This annotation plays a similar role as the standard Spring Framework `@ComponentScan` annotation, but it is restricted just to Spring Integration specific components and annotations, which aren't reachable by the standard Spring Framework component scan mechanism.
For example <<messaging-gateway-annotation>>.
The `@EnablePublisher` annotation has been introduced to register a `PublisherAnnotationBeanPostProcessor` bean and configure the `default-publisher-channel` for those `@Publisher` annotations which are provided without a `channel` attribute.
If more than one `@EnablePublisher` annotation is found, they must all have the same value for the default channel.
See <<publisher-annotation>> for more information.
The `@GlobalChannelInterceptor` annotation has been introduced to mark `ChannelInterceptor` beans for global channel interception.
This annotation is an analogue of the `<int:channel-interceptor>` xml element (see <<global-channel-configuration-interceptors>>).
`@GlobalChannelInterceptor` annotations can be placed at the class level (with a `@Component` stereotype annotation), or on `@Bean` methods within `@Configuration` classes.
In either case, the bean *must* be a `ChannelInterceptor`.
The `@IntegrationConverter` annotation has been introduced to mark `Converter`, `GenericConverter` or `ConverterFactory` beans as candidate converters for `integrationConversionService`.
This annotation is an analogue of the `<int:converter>` xml element (see <<payload-type-conversion>>).
`@IntegrationConverter` annotations can be placed at the class level (with a `@Component` stereotype annotation), or on `@Bean` methods within `@Configuration` classes.
[[programming-considerations]]
=== Programming Considerations
It is generally recommended that you use plain old java objects (POJOs) whenever possible and only expose the framework in your code when absolutely necessary.
If you do expose the framework to your classes, there are some considerations that need to be taken into account, especially during application startup; some of these are listed here.
* If your component is `ApplicationContextAware`, you should generally not "use" the `ApplicationContext` in the `setApplicationContext()` method; just store a reference and defer such uses until later in the context lifecycle.
* If your component is an `InitializingBean` or uses `@PostConstruct` methods, do not send any messages from these initialization methods - the application context is not yet initialized when these methods are called, and sending such messages will likely fail.
If you need to send a messages during startup, implement `ApplicationListener` and wait for the `ContextRefreshedEvent`.
Alternatively, implement `SmartLifecycle`, put your bean in a late phase, and send the messages from the `start()` method.

106
src/reference/asciidoc/polling-consumer.adoc Normal file
View File

@@ -0,0 +1,106 @@
[[polling-consumer]]
=== Poller
==== Polling Consumer
When Message Endpoints (Channel Adapters) are connected to channels and instantiated, they produce one of the following 2 instances:
* http://static.springsource.org/spring-integration/api/org/springframework/integration/endpoint/PollingConsumer.html[PollingConsumer]
* http://static.springsource.org/spring-integration/api/org/springframework/integration/endpoint/EventDrivenConsumer.html[EventDrivenConsumer]
The actual implementation depends on which type of channel these Endpoints are connected to.
A channel adapter connected to a channel that implements the http://docs.spring.io/spring/docs/current/javadoc-api/index.html?org/springframework/messaging/SubscribableChannel.html[org.springframework.messaging.SubscribableChannel] interface will produce an instance of `EventDrivenConsumer`.
On the other hand, a channel adapter connected to a channel that implements the http://docs.spring.io/spring/docs/current/javadoc-api/index.html?org/springframework/messaging/PollableChannel.html[org.springframework.messaging.PollableChannel] interface (e.g. a QueueChannel) will produce an instance of `PollingConsumer`.
Polling Consumers allow Spring Integration components to actively poll for Messages, rather than to process Messages in an event-driven manner.
They represent a critical cross cutting concern in many messaging scenarios.
In Spring Integration, Polling Consumers are based on the pattern with the same name, which is described in the book "Enterprise Integration Patterns" by Gregor Hohpe and Bobby Woolf.
You can find a description of the pattern on the book's website at:
http://www.enterpriseintegrationpatterns.com/PollingConsumer.html[http://www.enterpriseintegrationpatterns.com/PollingConsumer.html]
==== Pollable Message Source
Furthermore, in Spring Integration a second variation of the Polling Consumer pattern exists.
When Inbound Channel Adapters are being used, these adapters are often wrapped by a `SourcePollingChannelAdapter`.
For example, when retrieving messages from a remote FTP Server location, the adapter described in <<ftp-inbound>> is configured with a _poller_ to retrieve messages periodically.
So, when components are configured with Pollers, the resulting instances are of one of the following types:
* http://static.springsource.org/spring-integration/api/org/springframework/integration/endpoint/PollingConsumer.html[PollingConsumer]
* http://static.springsource.org/spring-integration/api/org/springframework/integration/endpoint/SourcePollingChannelAdapter.html[SourcePollingChannelAdapter]
This means, Pollers are used in both inbound and outbound messaging scenarios.
Here are some use-cases that illustrate the scenarios in which Pollers are used:
* Polling certain external systems such as FTP Servers, Databases, Web Services
* Polling internal (pollable) Message Channels
* Polling internal services (E.g.
repeatedly execute methods on a Java class)
NOTE: AOP Advice classes can be applied to pollers, in an `advice-chain`.
An example being a transaction advice to start a transaction.
Starting with _version 4.1_ a `PollSkipAdvice` is provided.
Pollers use triggers to determine the time of the next poll.
The `PollSkipAdvice` can be used to suppress (skip) a poll, perhaps because there is some downstream condition that would prevent the message to be processed properly.
To use this advice, you have to provide it with an implementation of a `PollSkipStrategy`.
_Version 4.2_ added more flexibility in this area - see <<conditional-pollers>>.
This chapter is meant to only give a high-level overview regarding Polling Consumers and how they fit into the concept of message channels - <<channel>> and channel adapters - <<channel-adapter>>.
For more in-depth information regarding Messaging Endpoints in general and Polling Consumers in particular, please see<<endpoint>>.
[[conditional-pollers]]
==== Conditional Pollers for Message Sources
===== Background
`Advice` objects, in an `advice-chain` on a poller, advise the whole polling task (message retrieval and processing).
These "around advice" methods do not have access to any context for the poll, just the poll itself.
This is fine for requirements such as making a task transactional, or skipping a poll due to some external condition as discussed above.
What if we wish to take some action depending on the result of the `receive` part of the poll, or if we want to adjust the poller depending on conditions?
===== "Smart" Polling
_Version 4.2_ introduced the `AbstractMessageSourceAdvice`.
Any `Advice` objects in the `advice-chain` that subclass this class, are applied to just the receive operation.
Such classes implement the following methods:
[source, java]
beforeReceive(MessageSource<?> source)
This method is called before the `MessageSource.receive()` method.
It enables you to examine and or reconfigure the source at this time. Returning `false` cancels this poll (similar to the `PollSkipAdvice` mentioned above).
[source, java]
Message<?> afterReceive(Message<?> result, MessageSource<?> source)
This method is called after the `receive()` method; again, you can reconfigure the source, or take any action perhaps depending on the result (which can be `null` if there was no message created by the source).
You can even return a different message!
===== SimpleActiveIdleMessageSourceAdvice
This advice is a simple implementation of `AbstractMessageSourceAdvice`, when used in conjunction with a `DynamicPeriodicTrigger`, it adjuststhe polling frequency depending on whether or not the previous poll resulted in a message or not.
The poller must also have a reference to the same `DynamicPeriodicTrigger`.
.Important: Async Handoff
IMPORTANT: This advice modifies the trigger based on the `receive()` result.
This will only work if the advice is called on the poller thread.
It will *not* work if the poller has a `task-executor`.
To use this advice where you wish to use async operations after the result of a poll, do the async handoff later, perhaps by using an `ExecutorChannel`.
.Advice Chain Ordering
[IMPORTANT]
=====
It is important to understand how the advice chain is processed during initialization.
`Advice` objects that do not extend `AbstractMessageSourceAdvice` are applied to the whole poll process and are all invoked first, in order, before any `AbstractMessageSourceAdvice`; then `AbstractMessageSourceAdvice` objects are invoked in order around the `MessageSource` `receive()` method.
If you have, say `Advice` objects `a, b, c, d`, where `b` and `d` are `AbstractMessageSourceAdvice`, they will be applied in the order `a, c, b, d`.
Also, if a `MessageSource` is already a `Proxy`, the `AbstractMessageSourceAdvice` will be invoked after any existing `Advice` objects.
If you wish to change the order, you should wire up the proxy yourself.
=====

60
src/reference/asciidoc/preface.adoc Normal file
View File

@@ -0,0 +1,60 @@
[[preface]]
= Preface
[preface]
[[system-requirements]]
== Requirements
This section details the compatible http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java] and http://www.springsource.org/spring-framework[Spring Framework] versions.
[[supported-java-versions]]
=== Compatible Java Versions
For _Spring Integration_*4.1.x*, the *minimum* compatible Java version is *Java SE 6*.
Older versions of Java are not supported.
_Spring Integration_*4.1.x* is also compatible with *Java SE 7* as well as *Java SE 8*.
[[supported-spring-versions]]
=== Compatible Versions of the Spring Framework
_Spring Integration_*4.1.x* requires _Spring Framework_*4.1.4* or later.
[[code-conventions]]
=== Code Conventions
The Spring Framework 2.0 introduced support for namespaces, which simplifies the Xml configuration of the application context, and consequently Spring Integration provides broad namespace support.
This reference guide applies the following conventions for all code examples that use namespace support:
The *int* namespace prefix will be used for Spring Integration's core namespace support.
Each Spring Integration adapter type (module) will provide its own namespace, which is configured using the following convention:
*int-* followed by the name of the module, e.g.
*int-twitter*, *int-stream*, …
[source,xml]
----
<?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:int="http://www.springframework.org/schema/integration"
xmlns:int-twitter="http://www.springframework.org/schema/integration/twitter"
xmlns:int-stream="http://www.springframework.org/schema/integration/stream"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration.xsd
http://www.springframework.org/schema/integration/twitter
http://www.springframework.org/schema/integration/twitter/spring-integration-twitter.xsd
http://www.springframework.org/schema/integration/stream
http://www.springframework.org/schema/integration/stream/spring-integration-stream.xsd">
…
</beans>
----
For a detailed explanation regarding Spring Integration's namespace support see _<<configuration-namespace>>_.
NOTE: Please note that the namespace prefix can be freely chosen.
You may even choose not to use any namespace prefixes at all.
Therefore, apply the convention that suits your application needs best.
Be aware, though, that SpringSource Tool Suite™ (STS) uses the same namespace conventions for Spring Integration as used in this reference guide.

744
src/reference/asciidoc/redis.adoc Normal file
View File

@@ -0,0 +1,744 @@
[[redis]]
== Redis Support
Since version 2.1 Spring Integration introduces support for http://redis.io/[Redis]: _"an open source advanced key-value store".
_ This support comes in the form of a Redis-based MessageStore as well as Publish-Subscribe Messaging adapters that are supported by Redis via its http://redis.io/topics/pubsub[PUBLISH, SUBSCRIBE and UNSUBSCRIBE] commands.
[[redis-intro]]
=== Introduction
To download, install and run Redis please refer to the http://redis.io/download[Redis documentation].
[[redis-connection]]
=== Connecting to Redis
To begin interacting with Redis you first need to connect to it.
Spring Integration uses support provided by another Spring project, https://github.com/SpringSource/spring-data-redis[Spring Data Redis], which provides typical Spring constructs: `ConnectionFactory` and `Template`.
Those abstractions simplify integration with several Redis-client Java APIs.
Currently Spring-Data-Redis supportshttps://github.com/xetorthio/jedis[jedis], http://code.google.com/p/jredis/[jredis] and https://github.com/e-mzungu/rjc[rjc]
_RedisConnectionFactory_
To connect to Redis you would use one of the implementations of the `RedisConnectionFactory` interface:
[source,java]
----
public interface RedisConnectionFactory extends PersistenceExceptionTranslator {
/**
* Provides a suitable connection for interacting with Redis.
*
* @return connection for interacting with Redis.
*/
RedisConnection getConnection();
}
----
The example below shows how to create a `JedisConnectionFactory`.
In Java:
[source,java]
----
JedisConnectionFactory jcf = new JedisConnectionFactory();
jcf.afterPropertiesSet();
----
Or in Spring's XML configuration:
[source,xml]
----
<bean id="redisConnectionFactory"
class="o.s.data.redis.connection.jedis.JedisConnectionFactory">
<property name="port" value="7379" />
</bean>
----
The implementations of RedisConnectionFactory provide a set of properties such as port and host that can be set if needed.
Once an instance of RedisConnectionFactory is created, you can create an instance of RedisTemplate and inject it with the RedisConnectionFactory.
_RedisTemplate_
As with other template classes in Spring (e.g., `JdbcTemplate`, `JmsTemplate`) `RedisTemplate` is a helper class that simplifies Redis data access code.
For more information about `RedisTemplate` and its variations (e.g., `StringRedisTemplate`) please refer to the http://static.springsource.org/spring-data/data-redis/docs/current/reference/[Spring-Data-Redis documentation]
The code below shows how to create an instance of `RedisTemplate`:
In Java:
[source,java]
----
RedisTemplate rt = new RedisTemplate<String, Object>();
rt.setConnectionFactory(redisConnectionFactory);
----
Or in Spring's XML configuration::
[source,xml]
----
<bean id="redisTemplate" class="org.springframework.data.redis.core.RedisTemplate">
<property name="connectionFactory" ref="redisConnectionFactory"/>
</bean>
----
[[redis-messages]]
=== Messaging with Redis
As mentioned in the introduction Redis provides support for Publish-Subscribe messaging via its PUBLISH, SUBSCRIBE and UNSUBSCRIBE commands.
As with JMS and AMQP, Spring Integration provides Message Channels and adapters for sending and receiving messages via Redis.
[[redis-pub-sub-channel]]
==== Redis Publish/Subscribe channel
Similar to the JMS there are cases where both the producer and consumer are intended to be part of the same application, running within the same process.
This could be accomplished by using a pair of inbound and outbound Channel Adapters, however just like with Spring Integration's JMS support, there is a simpler approach to address this use case.
[source,xml]
----
<int-redis:publish-subscribe-channel id="redisChannel" topic-name="si.test.topic"/>
----
The publish-subscribe-channel (above) will behave much like a normal `<publish-subscribe-channel/>` element from the main Spring Integration namespace.
It can be referenced by both `input-channel` and `output-channel` attributes of any endpoint.
The difference is that this channel is backed by a Redis topic name - a String value specified by the `topic-name` attribute.
However unlike JMS this topic doesn't have to be created in advance or even auto-created by Redis.
In Redis topics are simple String values that play the role of an address, and all the producer and consumer need to do to communicate is use the same String value as their topic name.
A simple subscription to this channel means that asynchronous pub-sub messaging is possible between the producing and consuming endpoints, but unlike the asynchronous Message Channels created by adding a `<queue/>` sub-element within a simple Spring Integration `<channel/>` element, the Messages are not just stored in an in-memory queue.
Instead those Messages are passed through Redis allowing you to rely on its support for persistence and clustering as well as its interoperability with other non-java platforms.
[[redis-inbound-channel-adapter]]
==== Redis Inbound Channel Adapter
The Redis-based Inbound Channel Adapter adapts incoming Redis messages into Spring Integration Messages in the same way as other inbound adapters.
It receives platform-specific messages (Redis in this case) and converts them to Spring Integration Messages using a `MessageConverter` strategy.
[source,xml]
----
<int-redis:inbound-channel-adapter id="redisAdapter"
topics="foo, bar"
channel="receiveChannel"
error-channel="testErrorChannel"
message-converter="testConverter" />
<bean id="redisConnectionFactory"
class="o.s.data.redis.connection.jedis.JedisConnectionFactory">
<property name="port" value="7379" />
</bean>
<bean id="testConverter" class="foo.bar.SampleMessageConverter" />
----
Above is a simple but complete configuration of a Redis Inbound Channel Adapter.
Note that the above configuration relies on the familiar Spring paradigm of auto-discovering certain beans.
In this case the `redisConnectionFactory` is implicitly injected into the adapter.
You can of course specify it explicitly using the `connection-factory` attribute instead.
Also, note that the above configuration injects the adapter with a custom `MessageConverter`.
The approach is similar to JMS where `MessageConverters` are used to convert between Redis Messages and the Spring Integration Message payloads.
The default is a `SimpleMessageConverter`.
Inbound adapters can subscribe to multiple topic names hence the comma-delimited set of values in the `topics` attribute.
Since _Spring Integration 3.0_, the Inbound Adapter, in addition to the existing `topics` attribute, now has the `topic-patterns` attribute.
This attribute contains a comma-delimited set of Redis topic patterns.
For more information regarding Redis publish/subscribe, see http://redis.io/topics/pubsub[Redis Pub/Sub].
Inbound adapters can use a `RedisSerializer` to deserialize the body of Redis Messages.
The `serializer` attribute of the `<int-redis:inbound-channel-adapter>` can be set to an empty string, which results in a `null` value for the `RedisSerializer` property.
In this case the raw `byte[]` bodies of Redis Messages are provided as the message payloads.
[[redis-outbound-channel-adapter]]
==== Redis Outbound Channel Adapter
The Redis-based Outbound Channel Adapter adapts outgoing Spring Integration messages into Redis messages in the same way as other outbound adapters.
It receives Spring Integration messages and converts them to platform-specific messages (Redis in this case) using a `MessageConverter` strategy.
[source,xml]
----
<int-redis:outbound-channel-adapter id="outboundAdapter"
channel="sendChannel"
topic="foo"
message-converter="testConverter"/>
<bean id="redisConnectionFactory"
class="o.s.data.redis.connection.jedis.JedisConnectionFactory">
<property name="port" value="7379"/>
</bean>
<bean id="testConverter" class="foo.bar.SampleMessageConverter" />
----
As you can see the configuration is similar to the Redis Inbound Channel Adapter.
The adapter is implicitly injected with a `RedisConnectionFactory` which was defined with '`redisConnectionFactory`' as its bean name.
This example also includes the optional, custom `MessageConverter` (the '`testConverter`' bean).
Since _Spring Integration 3.0_, the `<int-redis:outbound-channel-adapter>`, as an alternative to the `topic` attribute, has the `topic-expression` attribute to determine the Redis topic against the Message at runtime.
These attributes are mutually exclusive.
[[redis-queue-inbound-channel-adapter]]
==== Redis Queue Inbound Channel Adapter
Since _Spring Integration 3.0_, a Queue Inbound Channel Adapter is available to 'right pop' messages from a Redis List.
The adapter is message-driven using an internal listener thread and does not use a poller.
[source,xml]
----
<int-redis:queue-inbound-channel-adapter id="" <1>
channel="" <2>
auto-startup="" <3>
phase="" <4>
connection-factory="" <5>
queue="" <6>
error-channel="" <7>
serializer="" <8>
receive-timeout="" <9>
recovery-interval="" <10>
expect-message="" <11>
task-executor=""/> <12>
----
<1> The component bean name.
If the `channel` attribute isn't provided a `DirectChannel` is created and registered with application context with this `id` attribute as the bean name.
In this case, the endpoint itself is registered with the bean name `id + '.adapter'`.
<2> The `MessageChannel` to which to send `Message` s from this Endpoint.
<3> A `SmartLifecycle` attribute to specify whether this Endpoint should start automatically after the application context start or not.
Default is `true`.
<4> A `SmartLifecycle` attribute to specify the _phase_ in which this Endpoint will be started.
Default is `0`.
<5> A reference to a `RedisConnectionFactory` bean.
Defaults to `redisConnectionFactory`.
<6> The name of the Redis List on which the queue-based 'right pop' operation is performed to get Redis messages.
<7> The `MessageChannel` to which to send `ErrorMessage` s with `Exception` s from the listening task of the Endpoint.
By default the underlying `MessagePublishingErrorHandler` uses the default `errorChannel` from the application context.
<8> The `RedisSerializer` bean reference.
Can be an empty string, which means 'no serializer'.
In this case the raw `byte[]` from the inbound Redis message is sent to the `channel` as the `Message` payload.
By default it is a `JdkSerializationRedisSerializer`.
<9> The timeout in milliseconds for 'right pop' operation to wait for a Redis message from the queue.
Default is 1 second.
<10> The time in milliseconds for which the listener task should sleep after exceptions on the 'right pop' operation, before restarting the listener task.
<11> Specify if this Endpoint expects data from the Redis queue to contain entire `Message` s.
If this attribute is set to `true`, the `serializer` can't be an empty string because messages require some form of deserialization (JDK serialization by default).
Default is `false`.
<12> A reference to a Spring `TaskExecutor` (or standard JDK 1.5+ `Executor`) bean.
It is used for the underlying listening task.
By default a `SimpleAsyncTaskExecutor` is used.
[[redis-queue-outbound-channel-adapter]]
==== Redis Queue Outbound Channel Adapter
Since _Spring Integration 3.0_, a Queue Outbound Channel Adapter is available to 'left push' to a Redis List from Spring Integration messages:
[source,xml]
----
<int-redis:queue-outbound-channel-adapter id="" <1>
channel="" <2>
connection-factory="" <3>
queue="" <4>
queue-expression="" <5>
serializer="" <6>
extract-payload="" /> <7>
----
<1> The component bean name.
If the `channel` attribute isn't provided, a `DirectChannel` is created and registered with the application context with this `id` attribute as the bean name.
In this case, the endpoint is registered with the bean name `id + '.adapter'`.
<2> The `MessageChannel` from which this Endpoint receives `Message` s.
<3> A reference to a `RedisConnectionFactory` bean.
Defaults to `redisConnectionFactory`.
<4> The name of the Redis List on which the queue-based 'left push' operation is performed to send Redis messages.
This attribute is mutually exclusive with `queue-expression`.
<5> A SpEL `Expression` to determine the name of the Redis List using the incoming `Message` at runtime as the `#root` variable.
This attribute is mutually exclusive with `queue`.
<6> A `RedisSerializer` bean reference.
By default it is a `JdkSerializationRedisSerializer`.
However, for `String` payloads, a `StringRedisSerializer` is used, if a `serializer` reference isn't provided.
<7> Specify if this Endpoint should send just the _payload_ to the Redis queue, or the entire `Message`.
Default is `true`.
[[redis-application-events]]
==== Redis Application Events
Since _Spring Integration 3.0_, the Redis module provides an implementation of `IntegrationEvent` - which, in turn, is a `org.springframework.context.ApplicationEvent`.
The `RedisExceptionEvent` encapsulates an `Exception` s from Redis operations (with the Endpoint being the `source` of the event).
For example, the `<int-redis:queue-inbound-channel-adapter/>` emits those events after catching `Exception` s from the `BoundListOperations.rightPop` operation.
The exception may be any generic `org.springframework.data.redis.RedisSystemException` or a `org.springframework.data.redis.RedisConnectionFailureException`.
Handling these events using an `<int-event:inbound-channel-adapter/>` can be useful to determine problems with background Redis tasks and to take administrative actions.
[[redis-message-store]]
=== Redis Message Store
As described in EIP, a http://www.eaipatterns.com/MessageStore.html[Message Store] allows you to persist Messages.
This can be very useful when dealing with components that have a capability to buffer messages (_Aggregator, Resequencer_, etc.) if reliability is a concern.
In Spring Integration, the MessageStore strategy also provides the foundation for thehttp://www.eaipatterns.com/StoreInLibrary.html[ClaimCheck] pattern, which is described in EIP as well.
Spring Integration's Redis module provides the `RedisMessageStore`.
[source,xml]
----
<bean id="redisMessageStore" class="o.s.i.redis.store.RedisMessageStore">
<constructor-arg ref="redisConnectionFactory"/>
</bean>
<int:aggregator input-channel="inputChannel" output-channel="outputChannel"
message-store="redisMessageStore"/>
----
Above is a sample `RedisMessageStore` configuration that shows its usage by an _Aggregator_.
As you can see it is a simple bean configuration, and it expects a `RedisConnectionFactory` as a constructor argument.
By default the `RedisMessageStore` will use Java serialization to serialize the Message.
However if you want to use a different serialization technique (e.g., JSON), you can provide your own serializer via the `valueSerializer` property of the `RedisMessageStore`.
[[redis-cms]]
==== Redis Channel Message Stores
The `RedisMessageStore` above maintains each group as a value under a single key (the group id).
While this can be used to back a `QueueChannel` for persistence, a specialized `RedisChannelMessageStore` is provided for that purpose (since _version 4.0_).
This store uses a `LIST` for each channel and `LPUSH` when sending and `RPOP` when receiving messages.
This store also uses JDK serialization by default, but the value serializer can be modified as described above.
It is recommended that this store is used for backing channels, instead of the general `RedisMessageStore`.
[source,xml]
----
<bean id="redisMessageStore" class="o.s.i.redis.store.RedisChannelMessageStore">
<constructor-arg ref="redisConnectionFactory"/>
</bean>
<int:channel id="somePersistentQueueChannel">
<int:queue message-store="redisMessageStore"/>
<int:channel>
----
The keys that are used to store the data have the form `<storeBeanName>:<channelId>` (in the above example, `redisMessageStore:somePersistentQueueChannel`).
In addition, a subclass `RedisChannelPriorityMessageStore` is also provided.
When this is used with a `QueueChannel`, the messages are received in (FIFO within) priority order.
It uses the standard `IntegrationMessageHeaderAccessor.PRIORITY` header and supports priority values `0 - 9`; messages with other priorities (and messages with no priority) are retrieved in FIFO order after any messages with priority.
IMPORTANT: These stores implement only `BasicMessageGroupStore` and do not implement `MessageGroupStore`; they can only be used for situations such as backing a `QueueChannel`.
[[redis-metadata-store]]
=== Redis Metadata Store
As of _Spring Integration 3.0_ a new Redis-based http://docs.spring.io/spring-integration/docs/latest-ga/api/org/springframework/integration/metadata/MetadataStore.html[MetadataStore] (<<metadata-store>>) implementation is available.
The `RedisMetadataStore` can be used to maintain state of a `MetadataStore` across application restarts.
This new `MetadataStore` implementation can be used with adapters such as:
* <<twitter-inbound>>
* <<feed-inbound-channel-adapter>>
* <<file-reading>>
* <<ftp-inbound>>
* <<sftp-inbound>>
In order to instruct these adapters to use the new `RedisMetadataStore` simply declare a Spring bean using the bean name *metadataStore*.
The _Twitter Inbound Channel Adapter_ and the _Feed Inbound Channel Adapter_ will both automatically pick up and use the declared `RedisMetadataStore`.
[source,xml]
----
<bean name="metadataStore" class="o.s.i.redis.store.metadata.RedisMetadataStore">
<constructor-arg name="connectionFactory" ref="redisConnectionFactory"/>
</bean>
----
The `RedisMetadataStore` is backed by http://docs.spring.io/spring-data/data-redis/docs/current/api/org/springframework/data/redis/support/collections/RedisProperties.html[`RedisProperties`] and interaction with it uses http://docs.spring.io/spring-data/data-redis/docs/current/api/org/springframework/data/redis/core/BoundHashOperations.html[`BoundHashOperations`], which, in turn, requires a `key` for the entire `Properties` store.
In the case of the `MetadataStore`, this `key` plays the role of a _region_, which is useful in distributed environment, when several applications use the same Redis server.
By default this `key` has the value `MetaData`.
Starting with _version 4.0_, this store now implements `ConcurrentMetadataStore`, allowing it to be reliably shared across multiple application instances where only one instance will be allowed to store or modify a key's value.
[[redis-store-inbound-channel-adapter]]
=== RedisStore Inbound Channel Adapter
The _RedisStore Inbound Channel Adapter_ is a polling consumer that reads data from a Redis collection and sends it as a Message payload.
[source,xml]
----
<int-redis:store-inbound-channel-adapter id="listAdapter"
connection-factory="redisConnectionFactory"
key="myCollection"
channel="redisChannel"
collection-type="LIST" >
<int:poller fixed-rate="2000" max-messages-per-poll="10"/>
</int-redis:store-inbound-channel-adapter>
----
As you can see from the configuration above you configure a _Redis Store Inbound Channel Adapter_ using the `store-inbound-channel-adapter` element, providing values for various attributes such as:
* `key` or `key-expression` - The name of the key for the collection being used.
* `collection-type` - enumeration of the Collection types supported by this adapter.
Supported Collections are: LIST, SET, ZSET, PROPERTIES, MAP
* `connection-factory` - reference to an instance of `o.s.data.redis.connection.RedisConnectionFactory`
* `redis-template` - reference to an instance of `o.s.data.redis.core.RedisTemplate`
and other attributes that are common across all other inbound adapters (e.g., 'channel').
NOTE: You cannot set both `redis-template` and `connection-factory`.
[IMPORTANT]
=====
By default, the adapter uses a `StringRedisTemplate`; this uses `StringRedisSerializer` s for keys, values, hash keys and hash values.
If your Redis store contains objects that are serialized with other techniques, you must supply a `RedisTemplate` configured with appropriate serializers.
For example, if the store is written to using a RedisStore Outbound Adapter that has its `extract-payload-elements` set to false, you must provide a `RedisTemplate` configured thus:
[source,xml]
----
<bean id="redisTemplate" class="org.springframework.data.redis.core.RedisTemplate">
<property name="connectionFactory" ref="redisConnectionFactory"/>
<property name="keySerializer">
<bean class="org.springframework.data.redis.serializer.StringRedisSerializer"/>
</property>
<property name="hashKeySerializer">
<bean class="org.springframework.data.redis.serializer.StringRedisSerializer"/>
</property>
</bean>
----
This uses String serializers for keys and hash keys and the default JDK Serialization serializers for values and hash values.
=====
The example above is relatively simple and static since it has a literal value for the `key`.
Sometimes, you may need to change the value of the key at runtime based on some condition.
To do that, simply use `key-expression` instead, where the provided expression can be any valid SpEL expression.
Also, you may wish to perform some post-processing to the successfully processed data that was read from the Redis collection.
For example; you may want to move or remove the value after its been processed.
You can do this using the Transaction Synchronization feature that was added with Spring Integration 2.2.
[source,xml]
----
<int-redis:store-inbound-channel-adapter id="zsetAdapterWithSingleScoreAndSynchronization"
connection-factory="redisConnectionFactory"
key-expression="'presidents'"
channel="otherRedisChannel"
auto-startup="false"
collection-type="ZSET">
<int:poller fixed-rate="1000" max-messages-per-poll="2">
<int:transactional synchronization-factory="syncFactory"/>
</int:poller>
</int-redis:store-inbound-channel-adapter>
<int:transaction-synchronization-factory id="syncFactory">
<int:after-commit expression="payload.removeByScore(18, 18)"/>
</int:transaction-synchronization-factory>
<bean id="transactionManager" class="o.s.i.transaction.PseudoTransactionManager"/>
----
As you can see from the above all, you need to do is declare your poller to be transactional with a `transactional` element.
This element can reference a real transaction manager (for example if some other part of your flow invokes JDBC).
If you don't have a 'real' transaction, you can use a `o.s.i.transaction.PseudoTransactionManager` which is an implementation of Spring's `PlatformTransactionManager` and enables the use of the transaction synchronization features of the redis adapter when there is no actual transaction.
IMPORTANT: This does NOT make the Redis activities themselves transactional, it simply allows the synchronization of actions to be taken before/after success (commit) or after failure (rollback).
Once your poller is transactional all you need to do is set an instance of the `org.springframework.integration.transaction.TransactionSynchronizationFactory` on the `transactional` element.
`TransactionSynchronizationFactory` will create an instance of the `TransactionSynchronization`.
For your convenience we've exposed a default SpEL-based `TransactionSynchronizationFactory` which allows you to configure SpEL expressions, with their execution being coordinated (synchronized) with a transaction.
Expressions for before-commit, after-commit, and after-rollback are supported, together with a channel for each where the evaluation result (if any) will be sent.
For each sub-element you can specify `expression` and/or `channel` attributes.
If only the `channel` attribute is present the received Message will be sent there as part of the particular synchronization scenario.
If only the `expression` attribute is present and the result of an expression is a non-Null value, a Message with the result as the payload will be generated and sent to a default channel (NullChannel) and will appear in the logs (DEBUG).
If you want the evaluation result to go to a specific channel add a `channel` attribute.
If the result of an expression is null or void, no Message will be generated.
For more information about transaction synchronization, see <<transaction-synchronization>>.
[[redis-store-outbound-channel-adapter]]
=== RedisStore Outbound Channel Adapter
The _RedisStore Outbound Channel Adapter_ allows you to write a Message payload to a Redis collection
[source,xml]
----
<int-redis:store-outbound-channel-adapter id="redisListAdapter"
collection-type="LIST"
channel="requestChannel"
key="myCollection" />
----
As you can see from the configuration above, you configure a _Redis Store Outbound Channel Adapter_ using the `store-inbound-channel-adapter` element, providing values for various attributes such as:
* `key` or `key-expression` - The name of the key for the collection being used.
* `extract-payload-elements` - If set to `true` (Default) and the payload is an instance of a "multi- value" object (i.e., Collection or Map) it will be stored using addAll/ putAll semantics.
Otherwise, if set to `false` the payload will be stored as a single entry regardless of its type.
If the payload is not an instance of a "multi-value" object, the value of this attribute is ignored and the payload will always be stored as a single entry.
* `collection-type` - enumeration of the Collection types supported by this adapter.
Supported Collections are: LIST, SET, ZSET, PROPERTIES, MAP
* `map-key-expression` - SpEL expression that returns the name of the key for entry being stored.
Only applies if the `collection-type` is MAP or PROPERTIES and 'extract-payload-elements' is false.
* `connection-factory` - reference to an instance of `o.s.data.redis.connection.RedisConnectionFactory`
* `redis-template` - reference to an instance of `o.s.data.redis.core.RedisTemplate`
and other attributes that are common across all other inbound adapters (e.g., 'channel').
NOTE: You cannot set both `redis-template` and `connection-factory`.
IMPORTANT: By default, the adapter uses a `StringRedisTemplate`; this uses `StringRedisSerializer` s for keys, values, hash keys and hash values.
However, if `extract-payload-elements` is set to false, a `RedisTemplate` using `StringRedisSerializer` s for keys and hash keys, and `JdkSerializationRedisSerializer` s for values and hash values will be used.
With the JDK serializer, it is important to understand that java serialization is used for all values, regardless of whether the value is actually a collection or not.
If you need more control over the serialization of values, you may want to consider providing your own `RedisTemplate` rather than relying upon these defaults.
The example above is relatively simple and static since it has a literal values for the `key` and other attributes.
Sometimes you may need to change the values dynamically at runtime based on some condition.
To do that simply use their `-expression` equivalents (`key-expression`, `map-key-expression` etc.) where the provided expression can be any valid SpEL expression.
[[redis-outbound-gateway]]
=== Redis Outbound Command Gateway
Since _Spring Integration 4.0_, the Redis Command Gateway is available to perform any standard Redis command using generic `RedisConnection#execute` method:
[source,xml]
----
<int-redis:outbound-gateway
request-channel="" <1>
reply-channel="" <2>
requires-reply="" <3>
reply-timeout="" <4>
connection-factory="" <5>
redis-template="" <6>
arguments-serializer="" <7>
command-expression="" <8>
argument-expressions="" <9>
use-command-variable="" <10>
arguments-strategy="" /> <11>
----
<1> The `MessageChannel` from which this Endpoint receives `Message` s.
<2> The `MessageChannel` where this Endpoint sends reply `Message` s.
<3> Specify whether this outbound gateway must return a non-null value.
This value is `true` by default.
A ReplyRequiredException will be thrown when the Redis returns a `null` value.
<4> The timeout in milliseconds to wait until the reply message will be sent or not.
Typically is applied for queue-based limited reply-channels.
<5> A reference to a `RedisConnectionFactory` bean.
Defaults to `redisConnectionFactory`.
Mutually exclusive with 'redis-template' attribute.
<6> A reference to a `RedisTemplate` bean.
Mutually exclusive with 'connection-factory' attribute.
<7> Reference to an instance of `org.springframework.data.redis.serializer.RedisSerializer`.
Used to serialize each command argument to byte[] if necessary.
<8> The SpEL expression that returns the command key.
Default is the `redis_command` message header.
Must not evaluate to `null`.
<9> Comma-separate SpEL expressions that will be evaluated as command arguments.
Mutually exclusive with the `arguments-strategy` attribute.
If neither of them is provided the `payload` is used as the command argument(s).
Argument expressions may evaluate to 'null', to support a variable number of arguments.
<10> A `boolean` flag to specify if the evaluated Redis command string will be made available as the `#cmd` variable in the expression evaluation context in the `org.springframework.integration.redis.outbound.ExpressionArgumentsStrategy` when `argument-expressions` is configured, otherwise this attribute is ignored.
<11> Reference to an instance of `org.springframework.integration.redis.outbound.ArgumentsStrategy`.
Mutually exclusive with `argument-expressions` attribute.
If neither of them is provided the `payload` is used as the command argument(s).
The `<int-redis:outbound-gateway>` can be used as a common component to perform any desired Redis operation.
For example to get incremented value from Redis Atomic Number:
[source,xml]
----
<int-redis:outbound-gateway request-channel="requestChannel"
reply-channel="replyChannel"
command-expression="'INCR'"/>
----
where the Message `payload` should be a name of `redisCounter`, which may be provided by `org.springframework.data.redis.support.atomic.RedisAtomicInteger` bean definition.
The `RedisConnection#execute` has a generic `Object` as return type and real result depends on command type, for example `MGET` returns a `List<byte[]>`.
For more information about commands, their arguments and result type seehttp://redis.io/commands[Redis Specification].
[[redis-queue-outbound-gateway]]
=== Redis Queue Outbound Gateway
Since _Spring Integration 4.1_, the Redis Queue Outbound Gateway is available to perform request and reply scenarios.
It pushes a _conversation_`UUID` to the provided `queue`, then pushes the value to a Redis List with that `UUID` as its key and waits for the reply from a Redis List with a key of `UUID + '.reply'`.
A different UUID is used for each interaction.
[source,xml]
----
<int-redis:queue-outbound-gateway
request-channel="" <1>
reply-channel="" <2>
requires-reply="" <3>
reply-timeout="" <4>
connection-factory="" <5>
queue="" <6>
order="" <7>
serializer="" <8>
extract-payload="" <9>
----
<1> The `MessageChannel` from which this Endpoint receives `Message` s.
<2> The `MessageChannel` where this Endpoint sends reply `Message` s.
<3> Specify whether this outbound gateway must return a non-null value.
This value is `false` by default, otherwise a ReplyRequiredException will be thrown when the Redis returns a `null` value.
<4> The timeout in milliseconds to wait until the reply message will be sent or not.
Typically is applied for queue-based limited reply-channels.
<5> A reference to a `RedisConnectionFactory` bean.
Defaults to `redisConnectionFactory`.
Mutually exclusive with 'redis-template' attribute.
<6> The name of the Redis List to which outbound gateway will send a _conversation_`UUID`.
<7> The order for this outbound gateway when multiple gateway are registered thereby
<8> The `RedisSerializer` bean reference.
Can be an empty string, which means 'no serializer'.
In this case the raw `byte[]` from the inbound Redis message is sent to the `channel` as the `Message` payload.
By default it is a `JdkSerializationRedisSerializer`.
<9> Specify if this Endpoint expects data from the Redis queue to contain entire `Message` s.
If this attribute is set to `true`, the `serializer` can't be an empty string because messages require some form of deserialization (JDK serialization by default).
[[redis-queue-inbound-gateway]]
=== Redis Queue Inbound Gateway
Since _Spring Integration 4.1_, the Redis Queue Inbound Gateway is available to perform request and reply scenarios.
It pops a _conversation_`UUID` from the provided `queue`, then pops the value from the Redis List with that `UUID` as its key and pushes the reply to the Redis List with a key of `UUID + '.reply'`:
[source,xml]
----
<int-redis:queue-inbound-gateway
request-channel="" <1>
reply-channel="" <2>
executor="" <3>
reply-timeout="" <4>
connection-factory="" <5>
queue="" <6>
order="" <7>
serializer="" <8>
receive-timeout="" <9>
expect-message="" <10>
----
<1> The `MessageChannel` from which this Endpoint receives `Message` s.
<2> The `MessageChannel` where this Endpoint sends reply `Message` s.
<3> A reference to a Spring `TaskExecutor` (or standard JDK 1.5+ `Executor`) bean.
It is used for the underlying listening task.
By default a `SimpleAsyncTaskExecutor` is used.
<4> The timeout in milliseconds to wait until the reply message will be sent or not.
Typically is applied for queue-based limited reply-channels.
<5> A reference to a `RedisConnectionFactory` bean.
Defaults to `redisConnectionFactory`.
Mutually exclusive with 'redis-template' attribute.
<6> The name of the Redis List for the _conversation_`UUID` s.
<7> The order for this inbound gateway when multiple gateway are registered thereby
<8> The `RedisSerializer` bean reference.
Can be an empty string, which means 'no serializer'.
In this case the raw `byte[]` from the inbound Redis message is sent to the `channel` as the `Message` payload.
By default it is a `StringRedisSerializer`.
<9> The timeout in milliseconds to wait until the receive message will be get or not.
Typically is applied for queue-based limited request-channels.
<10> Specify if this Endpoint expects data from the Redis queue to contain entire `Message` s.
If this attribute is set to `true`, the `serializer` can't be an empty string because messages require some form of deserialization (JDK serialization by default).
[[redis-lock-registry]]
=== Redis Lock Registry
Starting with _version 4.0_, the `RedisLockRegistry` is available.
Certain components (for example aggregator and resequencer) use a lock obtained from a `LockRegistry` instance to ensure that only one thread is manipulating a group at a time.
The `DefaultLockRegistry` performs this function within a single component; you can now configure an external lock registry on these components.
When used with a shared `MessageGroupStore`, the `RedisLockRegistry` can be use to provide this functionality across multiple application instances, such that only one instance can manipulate the group at a time.
When a lock is released by a local thread, another local thread will generally be able to acquire the lock immediately.
If a lock is released by a thread using a different registry instance, it can take up to 100ms to acquire the lock.
To avoid "hung" locks (when a server fails), the locks in this registry are expired after a default 60 seconds, but this can be configured on the registry.
Locks are normally held for a much smaller time.
IMPORTANT: Because the keys can expire, an attempt to unlock an expired lock will result in an exception being thrown.
However, be aware that the resources protected by such a lock may have been compromised so such exceptions should be considered severe.
The expiry should be set at a large enough value to prevent this condition, while small enough that the lock can be recovered after a server failure in a reasonable amount of time.

167
src/reference/asciidoc/resequencer.adoc Normal file
View File

@@ -0,0 +1,167 @@
[[resequencer]]
=== Resequencer
==== Introduction
Related to the Aggregator, albeit different from a functional standpoint, is the Resequencer.
[[resequencer-functionality]]
==== Functionality
The Resequencer works in a similar way to the Aggregator, in the sense that it uses the CORRELATION_ID to store messages in groups, the difference being that the Resequencer does not process the messages in any way.
It simply releases them in the order of their SEQUENCE_NUMBER header values.
With respect to that, the user might opt to release all messages at once (after the whole sequence, according to the SEQUENCE_SIZE, has been released), or as soon as a valid sequence is available.
==== Configuring a Resequencer
Configuring a resequencer requires only including the appropriate element in XML.
A sample resequencer configuration is shown below.
[source,xml]
----
<int:channel id="inputChannel"/>
<int:channel id="outputChannel"/>
<int:resequencer id="completelyDefinedResequencer" <1>
input-channel="inputChannel" <2>
output-channel="outputChannel" <3>
discard-channel="discardChannel" <4>
release-partial-sequences="true" <5>
message-store="messageStore" <6>
send-partial-result-on-expiry="true" <7>
send-timeout="86420000" <8>
correlation-strategy="correlationStrategyBean" <9>
correlation-strategy-method="correlate" <10>
correlation-strategy-expression="headers['foo']" <11>
release-strategy="releaseStrategyBean" <12>
release-strategy-method="release" <13>
release-strategy-expression="size() == 10" <14>
empty-group-min-timeout="60000" <15>
lock-registry="lockRegistry" <16>
group-timeout="60000" <17>
group-timeout-expression="size() ge 2 ? 100 : -1" <18>
scheduler="taskScheduler" /> <19>
expire-group-upon-timeout="false" /> <20>
----
<1> The id of the resequencer is _optional_.
<2> The input channel of the resequencer.
_Required_.
<3> The channel to which the resequencer will send the reordered messages.
_Optional_.
<4> The channel to which the resequencer will send the messages that timed out (if `send-partial-result-on-timeout` is _false)_.
_Optional_.
<5> Whether to send out ordered sequences as soon as they are available, or only after the whole message group arrives._Optional (false by default)_.
<6> A reference to a `MessageGroupStore` that can be used to store groups of messages under their correlation key until they are complete.
_Optional_ with default a volatile in-memory store.
<7> Whether, upon the expiration of the group, the ordered group should be sent out (even if some of the messages are missing)._Optional (false by default)_.
See <<reaper>>.
<8> The timeout interval to wait when sending a reply `Message` to the `output-channel` or `discard-channel`.
By default the send will block for one second.
It is applied only if the output channel has some 'sending' limitations, e.g.
`QueueChannel` with a fixed 'capacity'.
In this case a `MessageDeliveryException` is thrown.
The `send-timeout` is ignored in case of `AbstractSubscribableChannel` implementations.
In case of `group-timeout(-expression)` the `MessageDeliveryException` from the scheduled expire task leads this task to be rescheduled.
_Optional_.
<9> A reference to a bean that implements the message correlation (grouping) algorithm.
The bean can be an implementation of the `CorrelationStrategy` interface or a POJO.
In the latter case the correlation-strategy-method attribute must be defined as well.
_Optional (by default, the aggregator will use
the `IntegrationMessageHeaderAccessor.CORRELATION_ID` header) _.
<10> A method defined on the bean referenced by `correlation-strategy`, that implements the correlation decision algorithm.
_Optional, with
restrictions (requires `correlation-strategy` to be
present)._
<11> A SpEL expression representing the correlation strategy.
Example: `"headers['foo']"`.
Only one of `correlation-strategy` or `correlation-strategy-expression` is allowed.
<12> A reference to a bean that implements the release strategy.
The bean can be an implementation of the `ReleaseStrategy` interface or a POJO.
In the latter case the release-strategy-method attribute must be defined as well.
_Optional (by default, the
aggregator will use the `IntegrationMessageHeaderAccessor.SEQUENCE_SIZE` header attribute)_.
<13> A method defined on the bean referenced by `release-strategy`, that implements the completion decision algorithm.
_Optional, with
restrictions (requires `release-strategy` to be
present)._
<14> A SpEL expression representing the release strategy; the root object for the expression is a `Collection` of `Message` s.
Example: `"size() == 5"`.
Only one of `release-strategy` or `release-strategy-expression` is allowed.
<15> Only applies if a `MessageGroupStoreReaper` is configured for the `<resequcencer>`'s `MessageStore`.
By default, when a `MessageGroupStoreReaper` is configured to expire partial groups, empty groups are also removed.
Empty groups exist after a group is released normally.
This is to enable the detection and discarding of late-arriving messages.
If you wish to expire empty groups on a longer schedule than expiring partial groups, set this property.
Empty groups will then not be removed from the `MessageStore` until they have not been modified for at least this number of milliseconds.
Note that the actual time to expire an empty group will also be affected by the reaper's _timeout_ property and it could be as much as this value plus the timeout.
<16> See <<aggregator-xml>>.
<17> See <<aggregator-xml>>.
<18> See <<aggregator-xml>>.
<19> See <<aggregator-xml>>.
<20> When a group is completed due to a timeout (or by a `MessageGroupStoreReaper`), the empty group's metadata is retained by default.
Late arriving messages will be immediately discarded.
Set this to `true` to remove the group completely; then, late arriving messages will start a new group and won't be discarded until the group again times out.
The new group will never be released normally because of the "hole" in the sequence range that caused the timeout.
Empty groups can be expired (completely removed) later using a `MessageGroupStoreReaper` together with the `empty-group-min-timeout` attribute.
Default: 'false'.
NOTE: Since there is no custom behavior to be implemented in Java classes for resequencers, there is no annotation support for it.

78
src/reference/asciidoc/resource.adoc Normal file
View File

@@ -0,0 +1,78 @@
[[resource]]
== Resource Support
[[resource-intro]]
=== Introduction
The _Resource Inbound Channel Adapter_ builds upon Spring's `Resource` abstraction to support greater flexibility across a variety of actual types of underlying resources, such as a file, a URL, or a class path resource.
Therefore, it's similar to but more generic than the _File Inbound Channel Adapter_.
[[resource-inbound-channel-adapter]]
=== Resource Inbound Channel Adapter
The _Resource Inbound Channel Adapter_ is a polling adapter that creates a `Message` whose payload is a collection of `Resource` objects.
`Resource` objects are resolved based on the pattern specified using the `pattern` attribute.
The collection of resolved `Resource` objects is then sent as a payload within a `Message` to the adapter's channel.
That is one major difference between _Resource Inbound Channel Adapter_ and _File Inbound Channel Adapter_; the latter buffers File objects and sends a single `File` object per `Message`.
Below is an example of a very simple configuration which will find all files ending with the 'properties' extension in the `foo.bar` package available on the classpath and will send them as the payload of a Message to the channel named '`resultChannel`':
[source,xml]
----
<int:resource-inbound-channel-adapter id="resourceAdapter"
channel="resultChannel"
pattern="classpath:foo/bar/*.properties">
<int:poller fixed-rate="1000"/>
</int:resource-inbound-channel-adapter>
----
The _Resource Inbound Channel Adapter_ relies on the `org.springframework.core.io.support.ResourcePatternResolver` strategy interface to resolve the provided pattern.
It defaults to an instance of the current `ApplicationContext`.
However you may provide a reference to an instance of your own implementation of `ResourcePatternResolver` using the `pattern-resolver` attribute:
[source,xml]
----
<int:resource-inbound-channel-adapter id="resourceAdapter"
channel="resultChannel"
pattern="classpath:foo/bar/*.properties"
pattern-resolver="myPatternResolver">
<int:poller fixed-rate="1000"/>
</int:resource-inbound-channel-adapter>
<bean id="myPatternResolver" class="org.example.MyPatternResolver"/>
----
You may have a use case where you need to further filter the collection of resources resolved by the `ResourcePatternResolver`.
For example, you may want to prevent resources that were resolved already from appearing in a collection of resolved resources ever again.
On the other hand your resources might be updated rather often and you _do_ want them to be picked up again.
In other words there is a valid use case for defining an additional filter as well as disabling filtering altogether.
You can provide your own implementation of the `org.springframework.integration.util.CollectionFilter` strategy interface:
[source,java]
----
public interface CollectionFilter<T> {
Collection<T> filter(Collection<T> unfilteredElements);
}
----
As you can see the `CollectionFilter` receives a collection of un-filtered elements (which would be `Resource` objects in this case), and it returns a collection of filtered elements of that same type.
If you are defining the adapter via XML but you do not specify a filter reference, a default implementation of `CollectionFilter` will be used by the _Resource Inbound Channel Adapter_.
The implementation class of that default filter is `org.springframework.integration.util.AcceptOnceCollectionFilter`.
It remembers the elements passed in the previous invocation in order to avoid returning those elements more than once.
To inject your own implementation of `CollectionFilter` instead, use the `filter` attribute.
[source,xml]
----
<int:resource-inbound-channel-adapter id="resourceAdapter"
channel="resultChannel"
pattern="classpath:foo/bar/*.properties"
filter="myFilter">
<int:poller fixed-rate="1000"/>
</int:resource-inbound-channel-adapter>
<bean id="myFilter" class="org.example.MyFilter"/>
----
If you don't need any filtering and want to disable even the default `CollectionFilter` strategy, simply provide an empty value for the filter attribute (e.g., `filter=""`)

8
src/reference/asciidoc/resources.adoc Normal file
View File

@@ -0,0 +1,8 @@
[[resources]]
== Additional Resources
[[resources-home]]
=== Spring Integration Home
The definitive source of information about Spring Integration is the http://projects.spring.io/spring-integration/[Spring Integration Home] at http://spring.io[http://spring.io].
That site serves as a hub of information and is the best place to find up-to-date announcements about the project as well as links to articles, blogs, and new sample applications.

77
src/reference/asciidoc/rmi.adoc Normal file
View File

@@ -0,0 +1,77 @@
[[rmi]]
== RMI Support
[[rmi-intro]]
=== Introduction
This Chapter explains how to use RMI specific channel adapters to distribute a system over multiple JVMs.
The first section will deal with sending messages over RMI.
The second section shows how to receive messages over RMI.
The last section shows how to define rmi channel adapters through the namespace support.
[[rmi-outbound]]
=== Outbound RMI
To send messages from a channel over RMI, simply define an `RmiOutboundGateway`.
This gateway will use Spring's RmiProxyFactoryBean internally to create a proxy for a remote gateway.
Note that to invoke a remote interface that doesn't use Spring Integration you should use a service activator in combination with Spring's RmiProxyFactoryBean.
To configure the outbound gateway write a bean definition like this:
[source,xml]
----
<bean id="rmiOutGateway" class=org.spf.integration.rmi.RmiOutboundGateway>
<constructor-arg value="rmi://host"/>
<property name="replyChannel" value="replies"/>
</bean>
----
[[rmi-inbound]]
=== Inbound RMI
To receive messages over RMI you need to use a `RmiInboundGateway`.
This gateway can be configured like this
[source,xml]
----
<bean id="rmiOutGateway" class=org.spf.integration.rmi.RmiInboundGateway>
<property name="requestChannel" value="requests"/>
</bean>
----
IMPORTANT: If you use an `errorChannel` on an inbound gateway, it would be normal for the error flow to return a result (or throw an exception).
This is because it is likely that there is a corresponding outbound gateway waiting for a response of some kind.
Consuming a message on the error flow, and not replying, will result in no reply at the inbound gateway.
Exceptions (on the main flow when there is no errorChannel, or on the error flow) will be propagated to the corresponding inbound gateway.
[[rmi-namespace]]
=== RMI namespace support
To configure the inbound gateway you can choose to use the namespace support for it.
The following code snippet shows the different configuration options that are supported.
[source,xml]
----
<int-rmi:inbound-gateway id="gatewayWithDefaults" request-channel="testChannel"/>
<int-rmi:inbound-gateway id="gatewayWithCustomProperties" request-channel="testChannel"
expect-reply="false" request-timeout="123" reply-timeout="456"/>
<int-rmi:inbound-gateway id="gatewayWithHost" request-channel="testChannel"
registry-host="localhost"/>
<int-rmi:inbound-gateway id="gatewayWithPort" request-channel="testChannel"
registry-port="1234" error-channel="rmiErrorChannel"/>
<int-rmi:inbound-gateway id="gatewayWithExecutorRef" request-channel="testChannel"
remote-invocation-executor="invocationExecutor"/>
----
To configure the outbound gateway you can use the namespace support as well.
The following code snippet shows the different configuration for an outbound rmi gateway.
[source,xml]
----
<int-rmi:outbound-gateway id="gateway"
request-channel="localChannel"
remote-channel="testChannel"
host="localhost"/>
----

1376
src/reference/asciidoc/router.adoc Normal file
View File

File diff suppressed because it is too large Load Diff

546
src/reference/asciidoc/samples.adoc Normal file
View File

@@ -0,0 +1,546 @@
[[samples]]
== Spring Integration Samples
[[samples-introduction]]
=== Introduction
As of Spring Integration 2.0, the _samples_ are no longer included with the Spring Integration distribution.
Instead we have switched to a much simpler collaborative model that should promote better community participation and, ideally, more contributions.
Samples now have a dedicated Git repository and a dedicated JIRA Issue Tracking system.
Sample development will also have its own lifecycle which is not dependent on the lifecycle of the framework releases, although the repository will still be tagged with each major release for compatibility reasons.
The great benefit to the community is that we can now add more samples and make them available to you right away without waiting for the next release.
Having its own JIRA that is not tied to the the actual framework is also a great benefit.
You now have a dedicated place to suggest samples as well as report issues with existing samples.
Or, _ you may want to submit a sample to us_ as an attachment through the JIRA or, better, through the collaborative model that Git promotes.
If we believe your sample adds value, we would be more then glad to add it to the 'samples' repository, properly crediting you as the author.
[[samples-get]]
=== Where to get Samples
The Spring Integration Samples project is hosted on https://github.com/SpringSource/spring-integration-samples/[GitHub].
You can find the repository at:
https://github.com/SpringSource/spring-integration-samples[https://github.com/SpringSource/spring-integration-samples]
In order to check out or _clone_ (Git parlance) the samples, please make sure you have a Git client installed on your system.
There are several GUI-based products available for many platforms, e.g.
http://eclipse.org/egit/[EGit] for the Eclipse IDE.
A simple Google search will help you find them.
Of course you can also just use the command line interface for <<http://git-scm.com/,Git>>.
NOTE: If you need more information on how to install and/or use Git, please visit: http://git-scm.com/[http://git-scm.com/].
In order to checkout (clone in Git terms) the Spring Integration samples repository using the Git command line tool, issue the following commands:
[source,xml]
----
$ git clone https://github.com/SpringSource/spring-integration-samples.git
----
That is all you need to do in order to clone the entire samples repository into a directory named _spring-integration-samples_ within the working directory where you issued that _git_ command.
Since the samples repository is a live repository, you might want to perform periodic _pulls_ (updates) to get new samples, as well as updates to the existing samples.
In order to do so issue the following git_PULL_ command:
[source,xml]
----
$ git pull
----
=== Submitting Samples or Sample Requests
_How can I contribute my own Samples?_
Github is for social coding: if you want to submit your own code examples to the Spring Integration Samples project, we encourage contributions through http://help.github.com/send-pull-requests/[_pull
requests_] from http://help.github.com/fork-a-repo/[_forks_] of this repository.
If you want to contribute code this way, please reference, if possible, ahttps://jira.springframework.org/browse/INTSAMPLES[_JIRA Ticket_] that provides some details regarding the provided sample.
[IMPORTANT]
.Sign the contributor license agreement
=====
Very important: before we can accept your Spring Integration sample, we will need you to sign the SpringSource contributor license agreement (CLA).
Signing the contributor's agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do.
In order to read and sign the CLA, please go to:
https://support.springsource.com/spring_committer_signup
From the Project drop down, please select _Spring Integration_.
The Project Lead is _Gary Russell_.
=====
_Code Contribution Process_
For the actual code contribution process, please read the the _Contributor Guidelines_ for Spring Integration, they apply for this project as well:
https://github.com/spring-projects/spring-integration/blob/master/CONTRIBUTING.md
This process ensures that every commit gets peer-reviewed.
As a matter of fact, the core committers follow the exact same rules.
We are gratefully looking forward to your Spring Integration Samples!
_Sample Requests_
As mentioned earlier, the _Spring Integration Samples_ project has a dedicated JIRA Issue tracking system.
To submit new sample requests, please visit our JIRA Issue Tracking system:
https://jira.springframework.org/browse/INTSAMPLES[https://jira.springframework.org/browse/INTSAMPLES].
[[samples-structure]]
=== Samples Structure
Starting with Spring Integration 2.0, the structure of the _samples_ changed as well.
With plans for more samples we realized that some samples have different goals than others.
While they all share the common goal of showing you how to apply and work with the Spring Integration framework, they also differ in areas where some samples are meant to concentrate on a technical use case while others focus on a business use case, and some samples are all about showcasing various techniques that could be applied to address certain scenarios (both technical and business).
The new categorization of samples will allow us to better organize them based on the problem each sample addresses while giving you a simpler way of finding the right sample for your needs.
Currently there are 4 categories.
Within the samples repository each category has its own directory which is named after the category name:
_BASIC (samples/basic)_
This is a good place to get started.
The samples here are technically motivated and demonstrate the bare minimum with regard to configuration and code.
These should help you to get started quickly by introducing you to the basic concepts, API and configuration of Spring Integration as well as Enterprise Integration Patterns (EIP).
For example, if you are looking for an answer on how to implement and wire a _Service Activator_ to a _Message Channel_ or how to use a _Messaging Gateway_ as a facade to your message exchange, or how to get started with using MAIL or TCP/UDP modules etc., this would be the right place to find a good sample.
The bottom line is this is a good place to get started.
_INTERMEDIATE (samples/intermediate)_
This category targets developers who are already familiar with the Spring Integration framework (past getting started), but need some more guidance while resolving the more advanced technical problems one might deal with after switching to a Messaging architecture.
For example, if you are looking for an answer on how to handle errors in various message exchange scenarios or how to properly configure the _Aggregator_ for the situations where some messages might not ever arrive for aggregation, or any other issue that goes beyond a basic implementation and configuration of a particular component and addresses _what else_ types of problems, this would be the right place to find these type of samples.
_ADVANCED (samples/advanced)_
This category targets developers who are very familiar with the Spring Integration framework but are looking to extend it to address a specific custom need by using Spring Integration's public API.
For example, if you are looking for samples showing you how to implement a custom _Channel_ or _Consumer_ (event-based or polling-based), or you are trying to figure out what is the most appropriate way to implement a custom Bean parser on top of the Spring Integration Bean parser hierarchy when implementing your own namespace and schema for a custom component, this would be the right place to look.
Here you can also find samples that will help you with _Adapter_ development.
Spring Integration comes with an extensive library of adapters to allow you to connect remote systems with the Spring Integration messaging framework.
However you might have a need to integrate with a system for which the core framework does not provide an adapter.
So, you may decide to implement your own (and potentially contribute it).
This category would include samples showing you how.
_APPLICATIONS (samples/applications)_
This category targets developers and architects who have a good understanding of Message-driven architecture and EIP, and an above average understanding of Spring and Spring Integration who are looking for samples that address a particular _business problem_.
In other words the emphasis of samples in this category is _business use cases_ and how they can be solved with a Message-Driven Architecture and Spring Integration in particular.
For example, if you are interested to see how a _Loan Broker_ or _Travel Agent_ process could be implemented and automated via Spring Integration, this would be the right place to find these types of samples.
IMPORTANT: Remember: Spring Integration is a community driven framework, therefore community participation is IMPORTANT.
That includes Samples; so, if you can't find what you are looking for, let us know!
[[samples-impl]]
=== Samples
Currently Spring Integration comes with quite a few samples and you can only expect more.
To help you better navigate through them, each sample comes with its own `readme.txt` file which covers several details about the sample (e.g., what EIP patterns it addresses, what problem it is trying to solve, how to run sample etc.).
However, certain samples require a more detailed and sometimes graphical explanation.
In this section you'll find details on samples that we believe require special attention.
[[samples-loan-broker]]
==== Loan Broker
In this section, we will review the _Loan Broker_ sample application that is included in the Spring Integration samples. This sample is inspired by one of the samples featured in Gregor Hohpe and Bobby Woolf's book, http://www.eaipatterns.com[Enterprise Integration Patterns].
The diagram below represents the entire process
.Loan Broker Sample
image::images/loan-broker-eip.png[align="center", scaledwidth=100%]
Now lets look at this process in more detail
At the core of an EIP architecture are the very simple yet powerful concepts of Pipes and Filters, and of course: Messages.
Endpoints (Filters) are connected with one another via Channels (Pipes).
The producing endpoint sends Message to the Channel, and the Message is retrieved by the Consuming endpoint.
This architecture is meant to define various mechanisms that describe HOW information is exchanged between the endpoints, without any awareness of WHAT those endpoints are or what information they are exchanging.
Thus, it provides for a very loosely coupled and flexible collaboration model while also decoupling Integration concerns from Business concerns.
EIP extends this architecture by further defining:
* The types of pipes (Point-to-Point Channel, Publish-Subscribe Channel, Channel Adapter, etc.)
* The core filters and patterns around how filters collaborate with pipes (Message Router, Splitters and Aggregators, various Message Transformation patterns, etc.)
The details and variations of this use case are very nicely described in Chapter 9 of the EIP Book, but here is the brief summary; A Consumer while shopping for the best Loan Quote(s) subscribes to the services of a Loan Broker, which handles details such as:
* Consumer pre-screening (e.g., obtain and review the consumer's Credit history)
* Determine the most appropriate Banks (e.g., based on consumer's credit history/score)
* Send a Loan quote request to each selected Bank
* Collect responses from each Bank
* Filter responses and determine the best quote(s), based on consumer's requirements.
* Pass the Loan quote(s) back to the consumer.
Obviously the real process of obtaining a loan quote is a bit more complex, but since our goal here is to demonstrate how Enterprise Integration Patterns are realized and implemented within SI, the use case has been simplified to concentrate only on the Integration aspects of the process.
It is not an attempt to give you an advice in consumer finances.
As you can see, by hiring a Loan Broker, the consumer is isolated from the details of the Loan Broker's operations, and each Loan Broker's operations may defer from one another to maintain competitive advantage, so whatever we assemble/implement must be flexible so any changes could be introduced quickly and painlessly.
Speaking of change, the Loan Broker sample does not actually talk to any 'imaginary' Banks or Credit bureaus.
Those services are stubbed out.
Our goal here is to assemble, orchestrate and test the integration aspect of the process as a whole.
Only then can we start thinking about wiring such process to the real services.
At that time the assembled process and its configuration will not change regardless of the number of Banks a particular Loan Broker is dealing with, or the type of communication media (or protocols) used (JMS, WS, TCP, etc.) to communicate with these Banks.
_DESIGN_
As you analyze the 6 requirements above you'll quickly see that they all fall into the category of Integration concerns.
For example, in the consumer pre-screening step we need to gather additional information about the consumer and the consumer's desires and enrich the loan request with additional meta information.
We then have to filter such information to select the most appropriate list of Banks, and so on.
Enrich, filter, select – these are all integration concerns for which EIP defines a solution in the form of patterns.
SI provides an implementation of these patterns.
.Messaging Gateway
image::images/gateway.jpg[align="center"]
The _Messaging Gateway_ pattern provides a simple mechanism to access messaging systems, including our Loan Broker.
In SI you define the _Gateway_ as a Plain Old Java Interface (no need to provide an implementation), configure it via the XML _<gateway>_ element or via annotation and use it as any other Spring bean.
SI will take care of delegating and mapping method invocations to the Messaging infrastructure by generating a _Message_ (payload is mapped to an input parameter of the method) and sending it to the designated channel.
[source,xml]
----
<int:gateway id="loanBrokerGateway"
default-request-channel="loanBrokerPreProcessingChannel"
service-interface="org.springframework.integration.samples.loanbroker.LoanBrokerGateway">
<int:method name="getBestLoanQuote">
<int:header name="RESPONSE_TYPE" value="BEST"/>
</int:method>
</int:gateway>
----
Our current _Gateway_ provides two methods that could be invoked.
One that will return the best single quote and another one that will return all quotes.
Somehow downstream we need to know what type of reply the caller is looking for.
The best way to achieve this in Messaging architecture is to enrich the content of the message with some meta-data describing your intentions.
_Content Enricher_ is one of the patterns that addresses this and although Spring Integration does provide a separate configuration element to enrich Message Headers with arbitrary data (we'll see it later), as a convenience, since_Gateway_ element is responsible to construct the initial _Message_ it provides embedded capability to enrich the newly created _Message_ with arbitrary _Message Headers_.
In our example we are adding header RESPONSE_TYPE with value 'BEST'' whenever the getBestQuote() method is invoked.
For other method we are not adding any header.
Now we can check downstream for an existence of this header and based on its presence and its value we can determine what type of reply the caller is looking for.
Based on the use case we also know there are some pre-screening steps that needs to be performed such as getting and evaluating the consumer's credit score, simply because some premiere Banks will only typically accept quote requests from consumers that meet a minimum credit score requirement.
So it would be nice if the _Message_ would be enriched with such information before it is forwarded to the Banks.
It would also be nice if when several processes needs to be completed to provide such meta-information, those processes could be grouped in a single unit.
In our use case we need to determine credit score and based on the credit score and some rule select a list of _Message Channels_ (Bank Channels) we will sent quote request to.
_Composed Message Processor_
The _Composed Message Processor_ pattern describes rules around building endpoints that maintain control over message flow which consists of multiple message processors.
In Spring Integration _Composed Message Processor_ pattern is implemented via _<chain>_ element.
.Chain
image::images/chain.png[align="center"]
As you can see from the above configuration we have a chain with inner header-enricher element which will further enrich the content of the _Message_ with the header CREDIT_SCORE and value that will be determined by the call to a credit service (simple POJO spring bean identified by 'creditBureau' name) and then it will delegate to the _Message Router_
.Message Router
image::images/bank-router.jpg[align="center"]
There are several implementations of the _Message Routing_ pattern available in Spring Integration.
Here we are using a router that will determine a list of channels based on evaluating an expression (Spring Expression Language) which will look at the credit score that was determined is the previous step and will select the list of channels from the Map bean with id 'banks' whose values are 'premier' or 'secondary' based o the value of credit score.
Once the list of _Channels_ is selected, the _Message_ will be routed to those _Channels_.
Now, one last thing the Loan Broker needs to to is to receive the loan quotes form the banks, aggregate them by consumer (we don't want to show quotes from one consumer to another), assemble the response based on the consumer's selection criteria (single best quote or all quotes) and reply back to the consumer.
.Message Aggregator
image::images/quotes-aggregator.jpg[align="center"]
An _Aggregator_ pattern describes an endpoint which groups related _Messages_ into a single _Message_.
Criteria and rules can be provided to determine an aggregation and correlation strategy.
SI provides several implementations of the _Aggregator_ pattern as well as a convenient name-space based configuration.
[source,xml]
----
<int:aggregator id="quotesAggregator"
input-channel="quotesAggregationChannel"
method="aggregateQuotes">
<beans:bean class="org.springframework.integration.samples.loanbroker.LoanQuoteAggregator"/>
</int:aggregator>
----
Our Loan Broker defines a 'quotesAggregator' bean via the _<aggregator>_ element which provides a default aggregation and correlation strategy.
The default correlation strategy correlates messages based on the `correlationId` header (see _Correlation Identifier_ pattern).
What's interesting is that we never provided the value for this header.
It was set earlier by the router automatically, when it generated a separate _Message_ for each Bank channel.
Once the _Messages_ are correlated they are released to the actual _Aggregator_ implementation.
Although default _Aggregator_ is provided by SI, its strategy (gather the list of payloads from all _Messages_ and construct a new _Message_ with this List as payload) does not satisfy our requirement.
The reason is that our consumer might require a single best quote or all quotes.
To communicate the consumer's intention, earlier in the process we set the RESPONSE_TYPE header.
Now we have to evaluate this header and return either all the quotes (the default aggregation strategy would work) or the best quote (the default aggregation strategy will not work because we have to determine which loan quote is the best).
Obviously selecting the best quote could be based on complex criteria and would influence the complexity of the aggregator implementation and configuration, but for now we are making it simple.
If consumer wants the best quote we will select a quote with the lowest interest rate.
To accomplish that the LoanQuoteAggregator.java will sort all the quotes and return the first one.
The `LoanQuote.java` implements `Comparable` which compares quotes based on the rate attribute.
Once the response _Message_ is created it is sent to the default-reply-channel of the _Messaging Gateway_ (thus the consumer) which started the process.
Our consumer got the Loan Quote!
Conclusion
As you can see a rather complex process was assembled based on POJO (read existing, legacy), light weight, embeddable messaging framework (Spring Integration) with a loosely coupled programming model intended to simplify integration of heterogeneous systems without requiring a heavy-weight ESB-like engine or proprietary development and deployment environment, because as a developer you should not be porting your Swing or console-based application to an ESB-like server or implementing proprietary interfaces just because you have an integration concern.
This and other samples in this section are built on top of Enterprise Integration Patterns and can be considered "building blocks" for YOUR solution; they are not intended to be complete solutions.
Integration concerns exist in all types of application (whether server based or not).
It should not require change in design, testing and deployment strategy if such applications need to be integrated.
[[samples-cafe]]
==== The Cafe Sample
In this section, we will review a _Cafe_ sample application that is included in the Spring Integration samples. This sample is inspired by another sample featured in Gregor Hohpe's http://www.eaipatterns.com/ramblings.html[Ramblings].
The domain is that of a Cafe, and the basic flow is depicted in the following diagram:
.Cafe Sample
image::images/cafe-eip.png[align="center", scaledwidth=100%]
The `Order` object may contain multiple `OrderItems`.
Once the order is placed, a _Splitter_ will break the composite order message into a single message per drink.
Each of these is then processed by a _Router_ that determines whether the drink is hot or cold (checking the `OrderItem` object's 'isIced' property).
The `Barista` prepares each drink, but hot and cold drink preparation are handled by two distinct methods: 'prepareHotDrink' and 'prepareColdDrink'.
The prepared drinks are then sent to the Waiter where they are aggregated into a `Delivery` object.
Here is the XML configuration:
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns:int="http://www.springframework.org/schema/integration"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:beans="http://www.springframework.org/schema/beans"
xmlns:int-stream="http://www.springframework.org/schema/integration/stream"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration.xsd
http://www.springframework.org/schema/integration/stream
http://www.springframework.org/schema/integration/stream/spring-integration-stream.xsd">
<int:gateway id="cafe" service-interface="o.s.i.samples.cafe.Cafe"/>
<int:channel id="orders"/>
<int:splitter input-channel="orders" ref="orderSplitter"
method="split" output-channel="drinks"/>
<int:channel id="drinks"/>
<int:router input-channel="drinks"
ref="drinkRouter" method="resolveOrderItemChannel"/>
<int:channel id="coldDrinks"><int:queue capacity="10"/></int:channel>
<int:service-activator input-channel="coldDrinks" ref="barista"
method="prepareColdDrink" output-channel="preparedDrinks"/>
<int:channel id="hotDrinks"><int:queue capacity="10"/></int:channel>
<int:service-activator input-channel="hotDrinks" ref="barista"
method="prepareHotDrink" output-channel="preparedDrinks"/>
<int:channel id="preparedDrinks"/>
<int:aggregator input-channel="preparedDrinks" ref="waiter"
method="prepareDelivery" output-channel="deliveries"/>
<int-stream:stdout-channel-adapter id="deliveries"/>
<beans:bean id="orderSplitter"
class="org.springframework.integration.samples.cafe.xml.OrderSplitter"/>
<beans:bean id="drinkRouter"
class="org.springframework.integration.samples.cafe.xml.DrinkRouter"/>
<beans:bean id="barista" class="o.s.i.samples.cafe.xml.Barista"/>
<beans:bean id="waiter" class="o.s.i.samples.cafe.xml.Waiter"/>
<int:poller id="poller" default="true" fixed-rate="1000"/>
</beans:beans>
----
As you can see, each Message Endpoint is connected to input and/or output channels.
Each endpoint will manage its own Lifecycle (by default endpoints start automatically upon initialization - to prevent that add the "auto-startup" attribute with a value of "false").
Most importantly, notice that the objects are simple POJOs with strongly typed method arguments.
For example, here is the Splitter:
[source,java]
----
public class OrderSplitter {
public List<OrderItem> split(Order order) {
return order.getItems();
}
}
----
In the case of the Router, the return value does not have to be a `MessageChannel` instance (although it can be).
As you see in this example, a String-value representing the channel name is returned instead.
[source,java]
----
public class DrinkRouter {
public String resolveOrderItemChannel(OrderItem orderItem) {
return (orderItem.isIced()) ? "coldDrinks" : "hotDrinks";
}
}
----
Now turning back to the XML, you see that there are two <service-activator> elements.
Each of these is delegating to the same `Barista` instance but different methods: 'prepareHotDrink' or 'prepareColdDrink' corresponding to the two channels where order items have been routed.
[source,java]
----
public class Barista {
private long hotDrinkDelay = 5000;
private long coldDrinkDelay = 1000;
private AtomicInteger hotDrinkCounter = new AtomicInteger();
private AtomicInteger coldDrinkCounter = new AtomicInteger();
public void setHotDrinkDelay(long hotDrinkDelay) {
this.hotDrinkDelay = hotDrinkDelay;
}
public void setColdDrinkDelay(long coldDrinkDelay) {
this.coldDrinkDelay = coldDrinkDelay;
}
public Drink prepareHotDrink(OrderItem orderItem) {
try {
Thread.sleep(this.hotDrinkDelay);
System.out.println(Thread.currentThread().getName()
+ " prepared hot drink #" + hotDrinkCounter.incrementAndGet()
+ " for order #" + orderItem.getOrder().getNumber()
+ ": " + orderItem);
return new Drink(orderItem.getOrder().getNumber(), orderItem.getDrinkType(),
orderItem.isIced(), orderItem.getShots());
}
catch (InterruptedException e) {
Thread.currentThread().interrupt();
return null;
}
}
public Drink prepareColdDrink(OrderItem orderItem) {
try {
Thread.sleep(this.coldDrinkDelay);
System.out.println(Thread.currentThread().getName()
+ " prepared cold drink #" + coldDrinkCounter.incrementAndGet()
+ " for order #" + orderItem.getOrder().getNumber() + ": "
+ orderItem);
return new Drink(orderItem.getOrder().getNumber(), orderItem.getDrinkType(),
orderItem.isIced(), orderItem.getShots());
}
catch (InterruptedException e) {
Thread.currentThread().interrupt();
return null;
}
}
}
----
As you can see from the code excerpt above, the barista methods have different delays (the hot drinks take 5 times as long to prepare).
This simulates work being completed at different rates.
When the`CafeDemo` 'main' method runs, it will loop 100 times sending a single hot drink and a single cold drink each time.
It actually sends the messages by invoking the 'placeOrder' method on the Cafe interface.
Above, you will see that the <gateway> element is specified in the configuration file.
This triggers the creation of a proxy that implements the given 'service-interface' and connects it to a channel.
The channel name is provided on the @Gateway annotation of the `Cafe` interface.
[source,java]
----
public interface Cafe {
@Gateway(requestChannel="orders")
void placeOrder(Order order);
}
----
Finally, have a look at the `main()` method of the `CafeDemo` itself.
[source,java]
----
public static void main(String[] args) {
AbstractApplicationContext context = null;
if (args.length > 0) {
context = new FileSystemXmlApplicationContext(args);
}
else {
context = new ClassPathXmlApplicationContext("cafeDemo.xml", CafeDemo.class);
}
Cafe cafe = context.getBean("cafe", Cafe.class);
for (int i = 1; i <= 100; i++) {
Order order = new Order(i);
order.addItem(DrinkType.LATTE, 2, false);
order.addItem(DrinkType.MOCHA, 3, true);
cafe.placeOrder(order);
}
}
----
TIP: To run this sample as well as 8 others, refer to the `README.txt` within the "samples" directory of the main distribution as described at the beginning of this chapter.
When you run cafeDemo, you will see that the cold drinks are initially prepared more quickly than the hot drinks.
Because there is an aggregator, the cold drinks are effectively limited by the rate of the hot drink preparation.
This is to be expected based on their respective delays of 1000 and 5000 milliseconds.
However, by configuring a poller with a concurrent task executor, you can dramatically change the results.
For example, you could use a thread pool executor with 5 workers for the hot drink barista while keeping the cold drink barista as it is:
[source,xml]
----
<int:service-activator input-channel="hotDrinks"
ref="barista"
method="prepareHotDrink"
output-channel="preparedDrinks"/>
<int:service-activator input-channel="hotDrinks"
ref="barista"
method="prepareHotDrink"
output-channel="preparedDrinks">
<int:poller task-executor="pool" fixed-rate="1000"/>
</int:service-activator>
<task:executor id="pool" pool-size="5"/>
----
Also, notice that the worker thread name is displayed with each invocation.
You will see that the hot drinks are prepared by the task-executor threads.
If you provide a much shorter poller interval (such as 100 milliseconds), then you will notice that occasionally it throttles the input by forcing the task-scheduler (the caller) to invoke the operation.
NOTE: In addition to experimenting with the poller's concurrency settings, you can also add the 'transactional' sub-element and then refer to any PlatformTransactionManager instance within the context.
[[samples-xml-messaging]]
==== The XML Messaging Sample
The xml messaging sample in the `org.springframework.integration.samples.xml` illustrates how to use some of the provided components which deal with xml payloads.
The sample uses the idea of processing an order for books represented as xml.
First the order is split into a number of messages, each one representing a single order item using the XPath splitter component.
[source,xml]
----
<int-xml:xpath-splitter id="orderItemSplitter" input-channel="ordersChannel"
output-channel="stockCheckerChannel" create-documents="true">
<int-xml:xpath-expression expression="/orderNs:order/orderNs:orderItem"
namespace-map="orderNamespaceMap" />
</int-xml:xpath-splitter>
----
A service activator is then used to pass the message into a stock checker POJO.
The order item document is enriched with information from the stock checker about order item stock level.
This enriched order item message is then used to route the message.
In the case where the order item is in stock the message is routed to the warehouse.
[source,xml]
----
<si-xml:xpath-router id="instockRouter" input-channel="orderRoutingChannel" resolution-required="true">
<si-xml:xpath-expression expression="/orderNs:orderItem/@in-stock" namespace-map="orderNamespaceMap" />
<si-xml:mapping value="true" channel="warehouseDispatchChannel"/>
<si-xml:mapping value="false" channel="outOfStockChannel"/>
</si-xml:xpath-router>
----
Where the order item is not in stock the message is transformed using xslt into a format suitable for sending to the supplier.
[source,xml]
----
<int-xml:xslt-transformer input-channel="outOfStockChannel"
output-channel="resupplyOrderChannel"
xsl-resource="classpath:org/springframework/integration/samples/xml/bigBooksSupplierTransformer.xsl"/>
----

184
src/reference/asciidoc/scatter-gather.adoc Normal file
View File

@@ -0,0 +1,184 @@
[[scatter-gather]]
=== Scatter-Gather
[[scatter-gather-introduction]]
==== Introduction
Starting with _version 4.1_, Spring Integration provides an implementation of the http://www.eaipatterns.com/BroadcastAggregate.html[Scatter-Gather] Enterprise Integration Pattern.
It is a compound endpoint, where the goal is to send a message to the recipients and aggregate the results.
Quoting the EIP Book, it is a component for scenarios like_best quote_, when we need to request information from several suppliers and decide which one provides us with the best term for the requested item.
Previously, the pattern could be configured using discrete components, this enhancement brings more convenient configuration.
The `ScatterGatherHandler` is a _request-reply_ endpoint that combines a`PublishSubscribeChannel` (or `RecipientListRouter`) and an `AggregatingMessageHandler`.
The request message is sent to the `scatter` channel and the `ScatterGatherHandler` waits for the reply from the aggregator to sends to the `outputChannel`.
[[scatter-gather-functionality]]
==== Functionality
The `Scatter-Gather` pattern suggests two scenarios - _Auction_ and _Distribution_.
In both cases, the `aggregation` function is the same and provides all options available for the `AggregatingMessageHandler`.
Actually the `ScatterGatherHandler` just requires an `AggregatingMessageHandler` as a constructor argument.
See <<aggregator>> for more information.
_Auction_
The _Auction_`Scatter-Gather` variant uses `publish-subscribe` logic for the request message, where the `scatter` channel is a `PublishSubscribeChannel` with `apply-sequence="true"`.
However, this channel can be any `MessageChannel` implementation as is the case with the `request-channel` in the `ContentEnricher` (see <<content-enricher>>) but, in this case, the end-user should support his own custom `correlationStrategy` for the `aggregation` function.
_Distribution_
The _Distribution_`Scatter-Gather` variant is based on the `RecipientListRouter` (see <<router-implementations-recipientlistrouter>>) with all available options for the `RecipientListRouter`.
This is the second `ScatterGatherHandler` constructor argument.
If you want to rely just on the default `correlationStrategy` for the `recipient-list-router` and the `aggregator`, you should specify `apply-sequence="true"`.
Otherwise, a custom `correlationStrategy` should be supplied for the `aggregator`.
Unlike the `PublishSubscribeChannel` (_Auction_) variant, having a `recipient-list-router` `selector` option, we can _filter_ target suppliers based on the message.
With `apply-sequence="true"` the default `sequenceSize` will be supplied and the `aggregator` will be able to release the group correctly.
The _Distribution_ option is mutually exclusive with the _Auction_ option.
In both cases, the request (_scatter_) message is enriched with the `gatherResultChannel` `QueueChannel` header, to wait for a reply message from the `aggregator`.
By default, all suppliers should send their result to the `replyChannel` header (usually by omitting the `output-channel` from the ultimate endpoint).
However, the `gatherChannel` option is also provided, allowing suppliers to send their reply to that channel for the aggregation.
[[scatter-gather-namespace]]
==== Configuring a Scatter-Gather Endpoint
For Java and Annotation configuration, the bean definition for the `Scatter-Gather` is:
[source,java]
----
@Bean
public MessageHandler distributor() {
RecipientListRouter router = new RecipientListRouter();
router.setApplySequence(true);
router.setChannels(Arrays.asList(distributionChannel1(), distributionChannel2(),
distributionChannel3()));
return router;
}
@Bean
public MessageHandler gatherer() {
return new AggregatingMessageHandler(
new ExpressionEvaluatingMessageGroupProcessor("^[payload gt 5] ?: -1D"),
new SimpleMessageStore(),
new HeaderAttributeCorrelationStrategy(
IntegrationMessageHeaderAccessor.CORRELATION_ID),
new ExpressionEvaluatingReleaseStrategy("size() == 2"));
}
@Bean
@ServiceActivator(inputChannel = "distributionChannel")
public MessageHandler scatterGatherDistribution() {
ScatterGatherHandler handler = new ScatterGatherHandler(distributor(), gatherer());
handler.setOutputChannel(output());
return handler;
}
----
Here, we configure the `RecipientListRouter` `distributor` bean, with `applySequence="true"` and the list of recipient channels.
The next bean is for an `AggregatingMessageHandler`.
Finally, we inject both those beans into the `ScatterGatherHandler` bean definition and mark it as a `@ServiceActivator` to wire the Scatter-Gather component into the integration flow.
Configuring the `<scatter-gather>` endpoint using the XML namespace:
[source,xml]
----
<scatter-gather
id="" <1>
auto-startup="" <2>
input-channel="" <3>
output-channel="" <4>
scatter-channel="" <5>
gather-channel="" <6>
order="" <7>
phase="" <8>
send-timeout="" <9>
gather-timeout="" <10>
requires-reply="" > <11>
<scatterer/> <12>
<gatherer/> <13>
</scatter-gather>
----
<1> The id of the Endpoint.
The `ScatterGatherHandler` bean is registered with `id + '.handler'` alias.
The `RecipientListRouter` - with `id + '.scatterer'`.
And the `AggregatingMessageHandler` with `id + '.gatherer'`.
_Optional_ (a default id is generated value by `BeanFactory`).
<2> Lifecycle attribute signaling if the Endpoint should be started during Application Context initialization.
In addition, the `ScatterGatherHandler` also implements `Lifecycle` and starts/stops the `gatherEndpoint`, which is created internally if a `gather-channel` is provided.
_Optional_ (default is `true`).
<3> The channel to receive request messages to handle them in the `ScatterGatherHandler`.
_Required_.
<4> The channel to which the Scatter-Gather will send the aggregation results.
_Optional (because incoming messages can specify a
reply channel themselves via `replyChannel` Message Header)_.
<5> The channel to send the scatter message for the _Auction_ scenario.
_Optional_.
Mutually exclusive with `<scatterer>` sub -element.
<6> The channel to receive replies from each supplier for the aggregation.
is used as the `replyChannel` header in the scatter message.
_Optional_.
By default the `FixedSubscriberChannel` is created.
<7> Order of this component when more than one handler is subscribed to the same DirectChannel (use for load balancing purposes)._Optional_.
<8> Specify the phase in which the endpoint should be started and stopped.
The startup order proceeds from lowest to highest, and the shutdown order is the reverse of that.
By default this value is Integer.MAX_VALUE meaning that this container starts as late as possible and stops as soon as possible._Optional_.
<9> The timeout interval to wait when sending a reply `Message` to the `output-channel`.
By default the send will block for one second.
It applies only if the output channel has some 'sending' limitations, e.g.
a `QueueChannel` with a fixed 'capacity' and is full.
In this case, a `MessageDeliveryException` is thrown.
The `send-timeout` is ignored in case of `AbstractSubscribableChannel` implementations.
In case of `group-timeout(-expression)` the `MessageDeliveryException` from the scheduled expire task leads this task to be rescheduled.
_Optional_.
<10> Allows you to specify how long the Scatter-Gather will wait for the reply message before returning.
By default it will wait indefinitely.
'null' is returned if the reply times out.
_Optional_.
Defaults to `-1` - indefinitely.
<11> Specify whether the Scatter-Gather must return a non-null value.
This value is `true` by default, hence a `ReplyRequiredException` will be thrown when the underlying aggregator returns a null value after `gather-timeout`.
Note, if `null` is a possibility, the `gather-timeout` should be specified to avoid an indefinite wait.
<12> The `<recipient-list-router>` options.
_Optional_.
Mutually exclusive with `scatter-channel` attribute.
<13> The `<aggregator>` options.
_Required_.

146
src/reference/asciidoc/scripting.adoc Normal file
View File

@@ -0,0 +1,146 @@
[[scripting]]
=== Scripting support
With Spring Integration 2.1 we've added support for the http://jcp.org/aboutJava/communityprocess/pr/jsr223/[JSR223 Scripting for Java specification], introduced in Java version 6.
This allows you to use scripts written in any supported language including Ruby/JRuby, Javascript and Groovy to provide the logic for various integration components similar to the way the Spring Expression Language (SpEL) is used in Spring Integration.
For more information about JSR223 please refer to the http://java.sun.com/developer/technicalArticles/J2SE/Desktop/scripting/[documentation]
IMPORTANT: Note that this feature requires Java 6 or higher.
Sun developed a JSR223 reference implementation which works with Java 5 but it is not officially supported and we have not tested it with Spring Integration.
In order to use a JVM scripting language, a JSR223 implementation for that language must be included in your class path.
Java 6 natively supports Javascript.
The http://groovy.codehaus.org[Groovy] and http://jruby.org/[JRuby] projects provide JSR233 support in their standard distribution.
Other language implementations may be available or under development.
Please refer to the appropriate project website for more information.
IMPORTANT: Various JSR223 language implementations have been developed by third parties.
A particular implementation's compatibility with Spring Integration depends on how well it conforms to the specification and/or the implementer's interpretation of the specification.
TIP: If you plan to use Groovy as your scripting language, we recommended you use <<groovy,Spring-Integration's Groovy Support>> as it offers additional features specific to Groovy.
_However you will find this section relevant as well_.
[[scripting-config]]
==== Script configuration
Depending on the complexity of your integration requirements scripts may be provided inline as CDATA in XML configuration or as a reference to a Spring resource containing the script.
To enable scripting support Spring Integration defines a `ScriptExecutingMessageProcessor` which will bind the Message Payload to a variable named `payload` and the Message Headers to a `headers` variable, both accessible within the script execution context.
All that is left for you to do is write a script that uses these variables.
Below are a couple of sample configurations:
_Filter_
[source,xml]
----
<int:filter input-channel="referencedScriptInput">
<int-script:script lang="ruby" location="some/path/to/ruby/script/RubyFilterTests.rb"/>
</int:filter>
<int:filter input-channel="inlineScriptInput">
<int-script:script lang="groovy">
<![CDATA[
return payload == 'good'
]]>
</int-script:script>
</int:filter>
----
Here, you see that the script can be included inline or can reference a resource location via the `location` attribute.
Additionally the `lang` attribute corresponds to the language name (or JSR223 alias)
Other Spring Integration endpoint elements which support scripting include _router_, _service-activator_, _transformer_, and _splitter_.
The scripting configuration in each case would be identical to the above (besides the endpoint element).
Another useful feature of Scripting support is the ability to update (reload) scripts without having to restart the Application Context.
To accomplish this, specify the `refresh-check-delay` attribute on the _script_ element:
[source,xml]
----
<int-script:script location="..." refresh-check-delay="5000"/>
----
In the above example, the script location will be checked for updates every 5 seconds.
If the script is updated, any invocation that occurs later than 5 seconds since the update will result in execution of the new script.
[source,xml]
----
<int-script:script location="..." refresh-check-delay="0"/>
----
In the above example the context will be updated with any script modifications as soon as such modification occurs, providing a simple mechanism for 'real-time' configuration.
Any negative number value means the script will not be reloaded after initialization of the application context.
This is the default behavior.
IMPORTANT: Inline scripts can not be reloaded.
[source,xml]
----
<int-script:script location="..." refresh-check-delay="-1"/>
----
_Script variable bindings_
Variable bindings are required to enable the script to reference variables externally provided to the script's execution context.
As we have seen, `payload` and `headers` are used as binding variables by default.
You can bind additional variables to a script via `<variable>` sub-elements:
[source,xml]
----
<script:script lang="js" location="foo/bar/MyScript.js">
<script:variable name="foo" value="foo"/>
<script:variable name="bar" value="bar"/>
<script:variable name="date" ref="date"/>
</script:script>
----
As shown in the above example, you can bind a script variable either to a scalar value or a Spring bean reference.
Note that `payload` and `headers` will still be included as binding variables.
With _Spring Integration 3.0_, in addition to the `variable` sub-element, the `variables` attribute has been introduced.
This attribute and `variable` sub-elements aren't mutually exclusive and you can combine them within one `script` component.
However variables must be unique, regardless of where they are defined.
Also, since _Spring Integration 3.0_, variable bindings are allowed for inline scripts too:
[source,xml]
----
<service-activator input-channel="input">
<script:script lang="ruby" variables="foo=FOO, date-ref=dateBean">
<script:variable name="bar" ref="barBean"/>
<script:variable name="baz" value="bar"/>
<![CDATA[
payload.foo = foo
payload.date = date
payload.bar = bar
payload.baz = baz
payload
]]>
</script:script>
</service-activator>
----
The example above shows a combination of an inline script, a `variable` sub-element and a `variables` attribute.
The `variables` attribute is a comma-separated value, where each segment contains an '=' separated pair of the variable and its value.
The variable name can be suffixed with `-ref`, as in the `date-ref` variable above.
That means that the binding variable will have the name `date`, but the value will be a reference to the `dateBean` bean from the application context.
This may be useful when using _Property Placeholder Configuration_ or command line arguments.
If you need more control over how variables are generated, you can implement your own Java class using the `ScriptVariableGenerator` strategy:
[source,java]
----
public interface ScriptVariableGenerator {
Map<String, Object> generateScriptVariables(Message<?> message);
}
----
This interface requires you to implement the method `generateScriptVariables(Message)`.
The Message argument allows you to access any data available in the Message payload and headers and the return value is the Map of bound variables.
This method will be called every time the script is executed for a Message.
All you need to do is provide an implementation of `ScriptVariableGenerator` and reference it with the `script-variable-generator` attribute:
[source,xml]
----
<int-script:script location="foo/bar/MyScript.groovy"
script-variable-generator="variableGenerator"/>
<bean id="variableGenerator" class="foo.bar.MyScriptVariableGenerator"/>
----
If a `script-variable-generator` is not provided, script components use `org.springframework.integration.scripting.DefaultScriptVariableGenerator`, which merges any provided `<variable>` s with _payload_ and _headers_ variables from the `Message` in its `generateScriptVariables(Message)` method.
IMPORTANT: You cannot provide both the `script-variable-generator` attribute and `<variable>` sub-element(s) as they are mutually exclusive.

85
src/reference/asciidoc/security.adoc Normal file
View File

@@ -0,0 +1,85 @@
[[security]]
== Security in Spring Integration
[[security-intro]]
=== Introduction
Spring Integration builds upon the http://static.springframework.org/spring-security/site/[Spring Security project] to enable role based security checks to be applied to channel send and receive invocations.
[[securing-channels]]
=== Securing channels
Spring Integration provides the interceptor `ChannelSecurityInterceptor`, which extends `AbstractSecurityInterceptor` and intercepts send and receive calls on the channel.
Access decisions are then made with reference to a `ChannelSecurityMetadataSource` which provides the metadata describing the send and receive access policies for certain channels.
The interceptor requires that a valid `SecurityContext` has been established by authenticating with Spring Security.
See the Spring Security reference documentation for details.
Namespace support is provided to allow easy configuration of security constraints.
This consists of the secured channels tag which allows definition of one or more channel name patterns in conjunction with a definition of the security configuration for send and receive.
The pattern is a `java.util.regexp.Pattern`.
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns:int="http://www.springframework.org/schema/integration"
xmlns:int-security="http://www.springframework.org/schema/integration/security"
xmlns:beans="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:security="http://www.springframework.org/schema/security"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/security
http://www.springframework.org/schema/security/spring-security.xsd
http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration.xsd
http://www.springframework.org/schema/integration/security
http://www.springframework.org/schema/integration/security/spring-integration-security.xsd">
<int-security:secured-channels>
<int-security:access-policy pattern="admin.*" send-access="ROLE_ADMIN"/>
<int-security:access-policy pattern="user.*" receive-access="ROLE_USER"/>
</int-security:secured-channels>
----
By default the secured-channels namespace element expects a bean named _authenticationManager_ which implements `AuthenticationManager` and a bean named _accessDecisionManager_ which implements `AccessDecisionManager`.
Where this is not the case references to the appropriate beans can be configured as attributes of the _secured-channels_ element as below.
[source,xml]
----
<int-security:secured-channels access-decision-manager="customAccessDecisionManager"
authentication-manager="customAuthenticationManager">
<int-security:access-policy pattern="admin.*" send-access="ROLE_ADMIN"/>
<int-security:access-policy pattern="user.*" receive-access="ROLE_USER"/>
</int-security:secured-channels>
----
Starting with _version 4.0_, the same configuration is available when using `@Configuration` classes, by declaring a `ChannelSecurityInterceptorFactoryBean`.
This class delegates all options for the `ChannelSecurityInterceptor` with a _builder_ pattern:
[source,java]
----
@Configuration
@EnableIntegration
public class ContextConfiguration {
@Autowired
private AuthenticationManager authenticationManager;
@Autowired
private AccessDecisionManager accessDecisionManager;
@Bean
public ChannelSecurityInterceptorFactoryBean channelSecurityInterceptor() {
return new ChannelSecurityInterceptorFactoryBean()
.authenticationManager(this.authenticationManager)
.accessDecisionManager(this.accessDecisionManager)
.accessPolicy("admin.*", "ROLE_ADMIN")
.accessPolicy("user.*", null, "ROLE_USER");
}
}
----
NOTE: The `@EnableIntegration` annotation is required to provide the Spring Integration infrastructure (including Security) to the Application Context.
In addition this `FactoryBean` falls back to `AuthenticationManager` and `AccessDecisionManager` beans with names `authenticationManager` and `accessDecisionManager` respectively, if they aren't provided in the `ChannelSecurityInterceptorFactoryBean` bean definition.

108
src/reference/asciidoc/service-activator.adoc Normal file
View File

@@ -0,0 +1,108 @@
[[service-activator]]
=== Service Activator
[[service-activator-introduction]]
==== Introduction
The Service Activator is the endpoint type for connecting any Spring-managed Object to an input channel so that it may play the role of a service.
If the service produces output, it may also be connected to an output channel.
Alternatively, an output producing service may be located at the end of a processing pipeline or message flow in which case, the inbound Message's "replyChannel" header can be used.
This is the default behavior if no output channel is defined, and as with most of the configuration options you'll see here, the same behavior actually applies for most of the other components we have seen.
[[service-activator-namespace]]
==== Configuring Service Activator
To create a Service Activator, use the 'service-activator' element with the 'input-channel' and 'ref' attributes:
[source,xml]
----
<int:service-activator input-channel="exampleChannel" ref="exampleHandler"/>
----
The configuration above assumes that "exampleHandler" either contains a single method annotated with the @ServiceActivator annotation or that it contains only one public method at all.
To delegate to an explicitly defined method of any object, simply add the "method" attribute.
[source,xml]
----
<int:service-activator input-channel="exampleChannel" ref="somePojo" method="someMethod"/>
----
In either case, when the service method returns a non-null value, the endpoint will attempt to send the reply message to an appropriate reply channel.
To determine the reply channel, it will first check if an "output-channel" was provided in the endpoint configuration:
[source,xml]
----
<int:service-activator input-channel="exampleChannel" output-channel="replyChannel"
ref="somePojo" method="someMethod"/>
----
If no "output-channel" is available, it will then check the Message's `replyChannel` header value.
If that value is available, it will then check its type.
If it is a`MessageChannel`, the reply message will be sent to that channel.
If it is a `String`, then the endpoint will attempt to resolve the channel name to a channel instance.
If the channel cannot be resolved, then a `DestinationResolutionException` will be thrown.
It it can be resolved, the Message will be sent there.
This is the technique used for Request Reply messaging in Spring Integration, and it is also an example of the Return Address pattern.
The argument in the service method could be either a Message or an arbitrary type.
If the latter, then it will be assumed that it is a Message payload, which will be extracted from the message and injected into such service method.
This is generally the recommended approach as it follows and promotes a POJO model when working with Spring Integration.
Arguments may also have @Header or @Headers annotations as described in <<annotations>>
NOTE: The service method is not required to have any arguments at all, which means you can implement event-style Service Activators, where all you care about is an invocation of the service method, not worrying about the contents of the message.
Think of it as a NULL JMS message.
An example use-case for such an implementation could be a simple counter/monitor of messages deposited on the input channel.
Starting with _version 4.1_ the framework correct converts Message properties (`payload` and `headers`) to the Java 8 `Optional` POJO method parameters:
[source,java]
----
public class MyBean {
public String computeValue(Optional<String> payload,
@Header(value="foo", required=false) String foo1,
@Header(value="foo") Optional<String> foo2) {
if (payload.isPresent()) {
String value = payload.get();
...
}
else {
...
}
}
}
----
Using a "ref" attribute is generally recommended if the custom Service Activator handler implementation can be reused in other `<service-activator>` definitions.
However if the custom Service Activator handler implementation is only used within a single definition of the `<service-activator>`, you can provide an inner bean definition:
[source,xml]
----
<int:service-activator id="exampleServiceActivator" input-channel="inChannel"
output-channel = "outChannel" method="foo">
<beans:bean class="org.foo.ExampleServiceActivator"/>
</int:service-activator>
----
NOTE: Using both the "ref" attribute and an inner handler definition in the same `<service-activator>` configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
_Service Activators and the Spring Expression Language (SpEL)_
Since Spring Integration 2.0, Service Activators can also benefit from SpEL (http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html).
For example, you may now invoke any bean method without pointing to the bean via a `ref` attribute or including it as an inner bean definition.
For example:
[source,xml]
----
<int:service-activator input-channel="in" output-channel="out"
expression="@accountService.processAccount(payload, headers.accountId)"/>
<bean id="accountService" class="foo.bar.Account"/>
----
In the above configuration instead of injecting 'accountService' using a `ref` or as an inner bean, we are simply using SpEL's `@beanId` notation and invoking a method which takes a type compatible with Message payload.
We are also passing a header value.
As you can see, any valid SpEL expression can be evaluated against any content in the Message.
For simple scenarios your _Service Activators_ do not even have to reference a bean if all logic can be encapsulated by such an expression.
[source,xml]
----
<int:service-activator input-channel="in" output-channel="out" expression="payload * 2"/>
----
In the above configuration our service logic is to simply multiply the payload value by 2, and SpEL lets us handle it relatively easy.

511
src/reference/asciidoc/sftp.adoc Normal file
View File

@@ -0,0 +1,511 @@
[[sftp]]
== SFTP Adapters
Spring Integration provides support for file transfer operations via SFTP.
[[sftp-intro]]
=== Introduction
The Secure File Transfer Protocol (SFTP) is a network protocol which allows you to transfer files between two computers on the Internet over any reliable stream.
The SFTP protocol requires a secure channel, such as SSH, as well as visibility to a client's identity throughout the SFTP session.
Spring Integration supports sending and receiving files over SFTP by providing three _client_ side endpoints: _Inbound Channel Adapter_, _Outbound Channel Adapter_, and _Outbound Gateway_ It also provides convenient namespace configuration to define these _client_ components.
[source,xml]
----
xmlns:int-sftp="http://www.springframework.org/schema/integration/sftp"
xsi:schemaLocation="http://www.springframework.org/schema/integration/sftp
http://www.springframework.org/schema/integration/sftp/spring-integration-sftp.xsd"
----
[[sftp-session-factory]]
=== SFTP Session Factory
IMPORTANT: Starting with version 3.0, sessions are no longer cached by default.
See <<sftp-session-caching>>.
Before configuring SFTP adapters, you must configure an _SFTP Session
Factory_.
You can configure the _SFTP Session
Factory_ via a regular bean definition:
[source,xml]
----
<beans:bean id="sftpSessionFactory"
class="org.springframework.integration.sftp.session.DefaultSftpSessionFactory">
<beans:property name="host" value="localhost"/>
<beans:property name="privateKey" value="classpath:META-INF/keys/sftpTest"/>
<beans:property name="privateKeyPassphrase" value="springIntegration"/>
<beans:property name="port" value="22"/>
<beans:property name="user" value="kermit"/>
</beans:bean>
----
Every time an adapter requests a session object from its `SessionFactory`, a new SFTP session is being created.
Under the covers, the SFTP Session Factory relies on thehttp://www.jcraft.com/jsch/[JSch] library to provide the SFTP capabilities.
However, Spring Integration also supports the caching of SFTP sessions, please see <<sftp-session-caching>> for more information.
[IMPORTANT]
=====
JSch supports multiple channels (operations) over a connection to the server.
By default, the Spring Integration session factory uses a separate physical connection for each channel.
Since _Spring Integration 3.0_, you can configure the session factory (using a boolean constructor arg - default `false`) to use a single connection to the server and create multiple `JSch` channels on that single connection.
When using this feature, you must wrap the session factory in a caching session factory, as described below, so that the connection is not physically closed when an operation completes.
If the cache is reset, the session is disconnected only when the last channel is closed.
The connection will be refreshed if it is found to be disconnected when a new operation obtains a session.
=====
NOTE: If you experience connectivity problems and would like to trace Session creation as well as see which Sessions are polled you may enable it by setting the logger to TRACE level (e.g., log4j.category.org.springframework.integration.file=TRACE).
Please also see <<sftp-jsch-logging>>.
Now all you need to do is inject this _SFTP Session Factory_ into your adapters.
NOTE: A more practical way to provide values for the _SFTP Session Factory_ would be via Spring's http://static.springsource.org/spring/docs/current/spring-framework-reference/html/beans.html#beans-factory-placeholderconfigurer[property placeholder support].
[[sftp-session-factory-properties]]
==== Configuration Properties
Below you will find all properties that are exposed by the http://static.springsource.org/spring-integration/api/org/springframework/integration/sftp/session/DefaultSftpSessionFactory.html[DefaultSftpSessionFactory].
*isSharedSession (constructor argument)*
When true, a single connection will be used and `JSch Channels` will be multiplexed.
Defaults to false.
*clientVersion*
Allows you to set the client version property.
It's default depends on the underlying JSch version but it will look like:_SSH-2.0-JSCH-0.1.45_
*enableDaemonThread*
If `true`, all threads will be daemon threads.
If set to `false`, normal non-daemon threads will be used instead.
This property will be set on the underlyinghttp://www.jcraft.com/jsch/[JSch]`Session`.
There, this property will default to `false`, if not explicitly set.
*host*
The url of the host you want connect to.
_Mandatory_.
*hostKeyAlias*
Sets the host key alias, used when comparing the host key to the known hosts list.
*knownHosts*
Specifies the filename that will be used to create a host key repository.
The resulting file has the same format as OpenSSH's_known_hosts_ file.
*password*
The password to authenticate against the remote host.
If a _password_ is not provided, then the _privateKey_ property is mandatory.
*port*
The port over which the SFTP connection shall be established.
If not specified, this value defaults to `22`.
If specified, this properties must be a positive number.
*privateKey*
Allows you to set a http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/core/io/Resource.html[Resource], which represents the location of the private key used for authenticating against the remote host.
If the _privateKey_ is not provided, then the _password_ property is mandatory.
*privateKeyPassphrase*
The password for the private key.
Optional.
*proxy*
Allows for specifying a JSch-based http://epaul.github.com/jsch-documentation/javadoc/com/jcraft/jsch/Proxy.html[Proxy].
If set, then the proxy object is used to create the connection to the remote host.
*serverAliveCountMax*
Specifies the number of server-alive messages, which will be sent without any reply from the server before disconnecting.
If not set, this property defaults to `1`.
*serverAliveInterval*
Sets the timeout interval (milliseconds) before a server alive message is sent, in case no message is received from the server.
*sessionConfig*
Using `Properties`, you can set additional configuration setting on the underlying JSch Session.
*socketFactory*
Allows you to pass in a http://epaul.github.com/jsch-documentation/javadoc/com/jcraft/jsch/SocketFactory.html[SocketFactory].
The socket factory is used to create a socket to the target host.
When a proxy is used, the socket factory is passed to the proxy.
By default plain TCP sockets are used.
*timeout*
The timeout property is used as the socket timeout parameter, as well as the default connection timeout.
Defaults to `0`, which means, that no timeout will occur.
*user*
The remote user to use.
_Mandatory_.
[[sftp-session-caching]]
=== SFTP Session Caching
IMPORTANT: Starting with _Spring Integration version 3.0_, sessions are no longer cached by default; the `cache-sessions` attribute is no longer supported on endpoints.
You must use a `CachingSessionFactory` (see below) if you wish to cache sessions.
In versions prior to 3.0, the sessions were cached automatically by default.
A `cache-sessions` attribute was available for disabling the auto caching, but that solution did not provide a way to configure other session caching attributes.
For example, you could not limit on the number of sessions created.
To support that requirement and other configuration options, a `CachingSessionFactory` was provided.
It provides `sessionCacheSize` and `sessionWaitTimeout` properties.
As its name suggests, the `sessionCacheSize` property controls how many active sessions the factory will maintain in its cache (the DEFAULT is unbounded).
If the `sessionCacheSize` threshold has been reached, any attempt to acquire another session will block until either one of the cached sessions becomes available or until the wait time for a Session expires (the DEFAULT wait time is Integer.MAX_VALUE).
The `sessionWaitTimeout` property enables configuration of that value.
If you want your Sessions to be cached, simply configure your default Session Factory as described above and then wrap it in an instance of `CachingSessionFactory` where you may provide those additional properties.
[source,xml]
----
<bean id="sftpSessionFactory"
class="org.springframework.integration.sftp.session.DefaultSftpSessionFactory">
<property name="host" value="localhost"/>
</bean>
<bean id="cachingSessionFactory"
class="org.springframework.integration.file.remote.session.CachingSessionFactory">
<constructor-arg ref="sftpSessionFactory"/>
<property name="sessionCacheSize" value="10"/>
<property name="sessionWaitTimeout" value="1000"/>
</bean>
----
In the above example you see a `CachingSessionFactory` created with the `sessionCacheSize` set to 10 and the `sessionWaitTimeout` set to 1 second (its value is in millliseconds).
Starting with _Spring Integration version 3.0_, the `CachingConnectionFactory` provides a `resetCache()` method.
When invoked, all idle sessions are immediately closed and in-use sessions are closed when they are returned to the cache.
When using `isSharedSession=true`, the channel is closed, and the shared session is closed only when the last channel is closed.
New requests for sessions will establish new sessions as necessary.
[[sftp-rft]]
=== RemoteFileTemplate
Starting with _Spring Integration version 3.0_, a new abstraction is provided over the `SftpSession` object.
The template provides methods to send, retrieve (as an `InputStream`), remove, and rename files.
In addition an `execute` method is provided allowing the caller to execute multiple operations on the session.
In all cases, the template takes care of reliably closing the session.
For more information, refer to the http://docs.spring.io/spring-integration/api/org/springframework/integration/file/remote/RemoteFileTemplate.html[javadocs for `RemoteFileTemplate`] There is a subclass for SFTP: `SftpRemoteFileTemplate`.
Additional methods were added in _version 4.1_ including `getClientInstance()` which provides access to the underlying `ChannelSftp` enabling access to low-level APIs.
[[sftp-inbound]]
=== SFTP Inbound Channel Adapter
The _SFTP Inbound Channel Adapter_ is a special listener that will connect to the server and listen for the remote directory events (e.g., new file created) at which point it will initiate a file transfer.
[source,xml]
----
<int-sftp:inbound-channel-adapter id="sftpAdapterAutoCreate"
session-factory="sftpSessionFactory"
channel="requestChannel"
filename-pattern="*.txt"
remote-directory="/foo/bar"
preserve-timestamp="true"
local-directory="file:target/foo"
auto-create-local-directory="true"
local-filename-generator-expression="#this.toUpperCase() + '.a'"
local-filter="myFilter"
temporary-file-suffix=".writing"
delete-remote-files="false">
<int:poller fixed-rate="1000"/>
</int-sftp:inbound-channel-adapter>
----
As you can see from the configuration above you can configure the _SFTP Inbound Channel Adapter_ via the `inbound-channel-adapter` element while also providing values for various attributes such as `local-directory` - where files are going to be transferred TO and `remote-directory` - the remote source directory where files are going to be transferred FROM - as well as other attributes including a `session-factory` reference to the bean we configured earlier.
By default the transferred file will carry the same name as the original file.
If you want to override this behavior you can set the `local-filename-generator-expression` attribute which allows you to provide a SpEL Expression to generate the name of the local file.
Unlike outbound gateways and adapters where the root object of the SpEL Evaluation Context is a `Message`, this inbound adapter does not yet have the Message at the time of evaluation since that's what it ultimately generates with the transferred file as its payload.
So, the root object of the SpEL Evaluation Context is the original name of the remote file (String).
Starting with _Spring Integration 3.0_, you can specify the `preserve-timestamp` attribute (default `false`); when `true`, the local file's modified timestamp will be set to the value retrieved from the server; otherwise it will be set to the current time.
Sometimes file filtering based on the simple pattern specified via `filename-pattern` attribute might not be sufficient.
If this is the case, you can use the `filename-regex` attribute to specify a Regular Expression (e.g.
`filename-regex=".*\.test$"`).
And of course if you need complete control you can use the `filter` attribute to provide a reference to a custom implementation of the `org.springframework.integration.file.filters.FileListFilter` - a strategy interface for filtering a list of files.
This filter determines which remote files are retrieved.
You can also combine a pattern based filter with other filters, such as an `AcceptOnceFileListFilter` to avoid synchronizing files that have previously been fetched, by using a `CompositeFileListFilter`.
The `AcceptOnceFileListFilter` stores its state in memory.
If you wish the state to survive a system restart, consider using the`SftpPersistentAcceptOnceFileListFilter` instead.
This filter stores the accepted file names in an instance of the`MetadataStore` strategy (<<metadata-store>>).
This filter matches on the filename and the remote modified time.
Since _version 4.0_, this filter requires a `ConcurrentMetadataStore`.
When used with a shared data store (such as `Redis` with the `RedisMetadataStore`) this allows filter keys to be shared across multiple application or server instances.
The above discussion refers to filtering the files before retrieving them.
Once the files have been retrieved, an additional filter is applied to the files on the file system.
By default, this is an`AcceptOnceFileListFilter` which, as discussed, retains state in memory and does not consider the file's modified time.
Unless your application removes files after processing, the adapter will re-process the files on disk by default after an application restart.
Also, if you configure the `filter` to use a `FtpPersistentAcceptOnceFileListFilter`, and the remote file timestamp changes (causing it to be re-fetched), the default local filter will not allow this new file to be processed.
Use the `local-filter` attribute to configure the behavior of the local file system filter.
To solve these particular use cases, you can use a`FileSystemPersistentAcceptOnceFileListFilter` as a local filter instead.
This filter also stores the accepted file names and modified timestamp in an instance of the`MetadataStore` strategy (<<metadata-store>>), and will detect the change in the local file modified time.
IMPORTANT: Further, if you use a distributed `MetadataStore` (such as <<redis-metadata-store>> or <<gemfire-metadata-store>>) you can have multiple instances of the same adapter/application and be sure that one and only one will process a file.
The actual local filter is a `CompositeFileListFilter` containing the supplied filter and a pattern filter that prevents processing files that are in the process of being downloaded (based on the `temporary-file-suffix`); files are downloaded with this suffix (default: `.writing`) and the file is renamed to its final name when the transfer is complete, making it 'visible' to the filter.
Please refer to the schema for more detail on these attributes.
It is also important to understand that _SFTP Inbound Channel Adapter_ is a Polling Consumer and therefore you must configure a poller (either a global default or a local sub-element).
Once the file has been transferred to a local directory, a Message with `java.io.File` as its payload type will be generated and sent to the channel identified by the `channel` attribute.
_More on File Filtering and Large Files_
Sometimes a file that just appeared in the monitored (remote) directory is not complete.
Typically such a file will be written with some temporary extension (e.g., foo.txt.writing) and then renamed after the writing process completes.
As a user in most cases you are only interested in files that are complete and would like to filter only those files.
To handle these scenarios, use filtering support provided via the `filename-pattern`, `filename-regex` and `filter` attributes.
If you need a custom filter implementation simply include a reference in your adapter via the `filter` attribute.
[source,xml]
----
<int-sftp:inbound-channel-adapter id="sftpInbondAdapter"
channel="receiveChannel"
session-factory="sftpSessionFactory"
filter="customFilter"
local-directory="file:/local-test-dir"
remote-directory="/remote-test-dir">
<int:poller fixed-rate="1000" max-messages-per-poll="10" task-executor="executor"/>
</int-sftp:inbound-channel-adapter>
<bean id="customFilter" class="org.foo.CustomFilter"/>
----
[[sftp-outbound]]
=== SFTP Outbound Channel Adapter
The _SFTP Outbound Channel Adapter_is a special `MessageHandler` that will connect to the remote directory and will initiate a file transfer for every file it will receive as the payload of an incoming `Message`.
It also supports several representations of the File so you are not limited to the File object.
Similar to the FTP outbound adapter, the _SFTP Outbound Channel Adapter_ supports the following payloads: 1) `java.io.File` - the actual file object; 2) `byte[]` - byte array that represents the file contents; 3) `java.lang.String` - text that represents the file contents.
[source,xml]
----
<int-sftp:outbound-channel-adapter id="sftpOutboundAdapter"
session-factory="sftpSessionFactory"
channel="inputChannel"
charset="UTF-8"
remote-file-separator="/"
remote-directory="foo/bar"
remote-filename-generator-expression="payload.getName() + '-foo'"
filename-generator="fileNameGenerator"
use-temporary-filename="true"
mode="REPLACE"/>
----
As you can see from the configuration above you can configure the _SFTP Outbound Channel Adapter_ via the `outbound-channel-adapter` element.
Please refer to the schema for more detail on these attributes.
_SpEL and the SFTP Outbound Adapter_
As with many other components in Spring Integration, you can benefit from the Spring Expression Language (SpEL) support when configuring an _SFTP Outbound Channel Adapter_, by specifying two attributes `remote-directory-expression` and `remote-filename-generator-expression` (see above).
The expression evaluation context will have the Message as its root object, thus allowing you to provide expressions which can dynamically compute the _file name_ or the existing _directory path_ based on the data in the Message (either from 'payload' or 'headers').
In the example above we are defining the `remote-filename-generator-expression` attribute with an expression value that computes the _file name_ based on its original name while also appending a suffix: '-foo'.
Starting with _version 4.1_, you can specify the `mode` when transferring the file.
By default, an existing file will be overwritten; the modes are defined on `enum` `FileExistsMode`, having values `REPLACE` (default), `APPEND`, `IGNORE`, and `FAIL`.
With `IGNORE` and `FAIL`, the file is not transferred; `FAIL` causes an exception to be thrown whereas `IGNORE` silently ignores the transfer (although a `DEBUG` log entry is produced).
_Avoiding Partially Written Files_
One of the common problems, when dealing with file transfers, is the possibility of processing a _partial file_ - a file might appear in the file system before its transfer is actually complete.
To deal with this issue, Spring Integration SFTP adapters use a very common algorithm where files are transferred under a temporary name and than renamed once they are fully transferred.
By default, every file that is in the process of being transferred will appear in the file system with an additional suffix which, by default, is `.writing`; this can be changed using the `temporary-file-suffix` attribute.
However, there may be situations where you don't want to use this technique (for example, if the server does not permit renaming files).
For situations like this, you can disable this feature by setting `use-temporary-file-name` to `false` (default is `true`).
When this attribute is `false`, the file is written with its final name and the consuming application will need some other mechanism to detect that the file is completely uploaded before accessing it.
[[sftp-outbound-gateway]]
=== SFTP Outbound Gateway
The _SFTP Outbound Gateway_ provides a limited set of commands to interact with a remote SFTP server.
Commands supported are:
* ls (list files)
* get (retrieve file)
* mget (retrieve file(s))
* rm (remove file(s))
* mv (move/rename file)
* put (send file)
* mput (send multiple files)
*ls*
ls lists remote file(s) and supports the following options:
* -1 - just retrieve a list of filenames, default is to retrieve a list of `FileInfo` objects.
* -a - include all files (including those starting with '.')
* -f - do not sort the list
* -dirs - include directories (excluded by default)
* -links - include symbolic links (excluded by default)
* -R - list the remote directory recursively
In addition, filename filtering is provided, in the same manner as the `inbound-channel-adapter`.
The message payload resulting from an _ls_ operation is a list of file names, or a list of `FileInfo` objects.
These objects provide information such as modified time, permissions etc.
The remote directory that the _ls_ command acted on is provided in the `file_remoteDirectory` header.
When using the recursive option (`-R`), the `fileName` includes any subdirectory elements, representing a relative path to the file (relative to the remote directory).
If the `-dirs` option is included, each recursive directory is also returned as an element in the list.
In this case, it is recommended that the `-1` is not used because you would not be able to determine files Vs.
directories, which is achievable using the `FileInfo` objects.
*get*
_get_ retrieves a remote file and supports the following option:
* -P - preserve the timestamp of the remote file
The message payload resulting from a _get_ operation is a `File` object representing the retrieved file.
The remote directory is provided in the `file_remoteDirectory` header, and the filename is provided in the `file_remoteFile` header.
*mget*
_mget_ retrieves multiple remote files based on a pattern and supports the following option:
* -P - preserve the timestamps of the remote files
* -x - Throw an exception if no files match the pattern (otherwise an empty list is returned)
The message payload resulting from an _mget_ operation is a `List<File>` object - a List of File objects, each representing a retrieved file.
The remote directory is provided in the `file_remoteDirectory` header, and the pattern for the filenames is provided in the `file_remoteFile` header.
[NOTE]
.Notes for when using recursion (`-R`)
=====
The pattern is ignored, and `*` is assumed.
By default, the entire remote tree is retrieved.
However, files in the tree can be filtered, by providing a`FileListFilter`; directories in the tree can also be filtered this way.
A `FileListFilter` can be provided by reference or by `filename-pattern` or `filename-regex` attributes.
For example, `filename-regex="(subDir|.*1.txt)"` will retrieve all files ending with `1.txt` in the remote directory and the subdirectory `subDir`.
If a subdirectory is filtered, no additional traversal of that subdirectory is performed.
The `-dirs` option is not allowed (the recursive mget uses the recursive `ls` to obtain the directory tree and the directories themselves cannot be included in the list).
Typically, you would use the `#remoteDirectory` variable in the `local-directory-expression` so that the remote directory structure is retained locally.
=====
*put*
_put_ sends a file to the remote server; the payload of the message can be a `java.io.File`, a `byte[]` or a `String`.
A `remote-filename-generator` (or expression) is used to name the remote file.
Other available attributes include `remote-directory`, `temporary-remote-directory` (and their `*-expression`) equivalents, `use-temporary-file-name`, and `auto-create-directory`.
Refer to the schema documentation for more information.
The message payload resulting from a _put_ operation is a `String` representing the full path of the file on the server after transfer.
*mput*
_mput_ sends multiple files to the server and supports the following option:
* -R - Recursive - send all files (possibly filtered) in the directory and subdirectories
The message payload must be a `java.io.File` representing a local directory.
The same attributes as the `put` command are supported.
In addition, files in the local directory can be filtered with one of `mput-pattern`, `mput-regex` or `mput-filter`.
The filter works with recursion, as long as the subdirectories themselves pass the filter.
Subdirectories that do not pass the filter are not recursed.
The message payload resulting from an _mget_ operation is a `List<String>` object - a List of remote file paths resulting from the transfer.
*rm*
The _rm_ command has no options.
The message payload resulting from an _rm_ operation is Boolean.TRUE if the remove was successful, Boolean.FALSE otherwise.
The remote directory is provided in the `file_remoteDirectory` header, and the filename is provided in the `file_remoteFile` header.
*mv*
The _mv_ command has no options.
The _expression_ attribute defines the "from" path and the _rename-expression_ attribute defines the "to" path.
By default, the _rename-expression_ is `headers['file_renameTo']`.
This expression must not evaluate to null, or an empty `String`.
If necessary, any remote directories needed will be created.
The payload of the result message is `Boolean.TRUE`.
The original remote directory is provided in the `file_remoteDirectory` header, and the filename is provided in the `file_remoteFile` header.
The new path is in the `file_renameTo` header.
*Additional Information*
The _get_ and _mget_ commands support the _local-filename-generator-expression_ attribute.
It defines a SpEL expression to generate the name of local file(s) during the transfer.
The root object of the evaluation context is the request Message but, in addition, the `remoteFileName` variable is also available, which is particularly useful for _mget_, for example: `local-filename-generator-expression="#remoteFileName.toUpperCase() + headers.foo"`
The _get_ and _mget_ commands support the _local-directory-expression_ attribute.
It defines a SpEL expression to generate the name of local directory(ies) during the transfer.
The root object of the evaluation context is the request Message but, in addition, the `remoteDirectory` variable is also available, which is particularly useful for _mget_, for example: `local-directory-expression="'/tmp/local/' + #remoteDirectory.toUpperCase() + headers.foo"`.
This attribute is mutually exclusive with _local-directory_ attribute.
For all commands, the PATH that the command acts on is provided by the 'expression' property of the gateway.
For the mget command, the expression might evaluate to '*', meaning retrieve all files, or 'somedirectory/*' etc.
Here is an example of a gateway configured for an ls command...
[source,xml]
----
<int-ftp:outbound-gateway id="gateway1"
session-factory="ftpSessionFactory"
request-channel="inbound1"
command="ls"
command-options="-1"
expression="payload"
reply-channel="toSplitter"/>
----
The payload of the message sent to the toSplitter channel is a list of String objects containing the filename of each file.
If the `command-options` was omitted, it would be a list of `FileInfo` objects.
Options are provided space-delimited, e.g.
`command-options="-1 -dirs -links"`.
[[sftp-jsch-logging]]
=== SFTP/JSCH Logging
Since we use JSch libraries (http://www.jcraft.com/jsch/) to provide SFTP support, at times you may require more information from the JSch API itself, especially if something is not working properly (e.g., Authentication exceptions).
Unfortunately JSch does not use commons-logging but instead relies on custom implementations of their `com.jcraft.jsch.Logger` interface.
As of Spring Integration 2.0.1, we have implemented this interface.
So, now all you need to do to enable JSch logging is to configure your logger the way you usually do.
For example, here is valid configuration of a logger using Log4J.
[source,java]
----
log4j.category.com.jcraft.jsch=DEBUG
----

38
src/reference/asciidoc/shutdown.adoc Normal file
View File

@@ -0,0 +1,38 @@
[[jmx-shutdown]]
=== Orderly Shutdown
As described in <<jmx-mbean-exporter>>, the MBean exporter provides a JMX operation _stopActiveComponents_, which is used to stop the application in an orderly manner.
The operation has a single long parameter.
The parameter indicates how long (in milliseconds) the operation will wait to allow in-flight messages to complete.
The operation works as follows:
The first step calls `beforeShutdown()` on all beans that implement `OrderlyShutdownCapable`.
This allows such components to prepare for shutdown.
Examples of components that implement this interface, and what they do with this call include: JMS and AMQP message-driven adapters stop their listener containers; TCP server connection factories stop accepting new connections (while keeping existing connections open); TCP inbound endpoints drop (log) any new messages received; http inbound endpoints return _503 - Service Unavailable_ for any new requests.
The second step stops any active channels, such as JMS- or AMQP-backed channels.
The third step stops all `MessageSource` s.
The fourth step stops all inbound `MessageProducer` s (that are not `OrderlyShutdownCapable`).
The fifth step waits for any remaining time left, as defined by the value of the long parameter passed in to the operation.
This is intended to allow any in-flight messages to complete their journeys.
It is therefore important to select an appropriate timeout when invoking this operation.
The sixth step calls `afterShutdown()` on all OrderlyShutdownCapable components.
This allows such components to perform final shutdown tasks (closing all open sockets, for example).
As discussed in <<jmx-mbean-shutdown>> this operation can be invoked using JMX.
If you wish to programmatically invoke the method, you will need to inject, or otherwise get a reference to, the `IntegrationMBeanExporter`.
If no `id` attribute is provided on the `<int-jmx:mbean-export/>` definition, the bean will have a generated name.
This name contains a random component to avoid `ObjectName` collisions if multiple Spring Integration contexts exist in the same JVM (MBeanServer).
For this reason, if you wish to invoke the method programmatically, it is recommended that you provide the exporter with an `id` attribute so it can easily be accessed in the application context.
Finally, the operation can be invoked using the `<control-bus>`; see the https://github.com/spring-projects/spring-integration-samples/tree/master/intermediate/monitoring[monitoring Spring Integration sample application] for details.
IMPORTANT: The above algorithm was improved in _version 4.1_.
Previously, all task executors and schedulers were stopped.
This could cause mid-flow messages in `QueueChannel` s to remain.
Now, the shutdown leaves pollers running in order to allow these messages to be drained and processed.

164
src/reference/asciidoc/spel.adoc Normal file
View File

@@ -0,0 +1,164 @@
[[spel]]
== Spring Expression Language (SpEL)
[[spel-intro]]
=== Introduction
Many Spring Integration components can be configured using expressions.
These expressions are written in the http://static.springsource.org/spring-framework/docs/current/spring-framework-reference/html/expressions.html[Spring Expression Language].
In most cases, the _#root_ object is the `Message` which, of course, has two properties - `headers` and `payload` - allowing such expressions as `payload`, `payload.foo`, `headers['my.header']` etc.
In some cases, additional variables are provided, for example the `<int-http:inbound-gateway/>` provides `#requestParams` (parameters from the HTTP request) and `#pathVariables` (values from path placeholders in the URI).
For all SpEL expressions, a `BeanResolver` is available, enabling references to any bean in the application context.
For example `@myBean.foo(payload)`.
In addition, two `PropertyAccessors` are available; a `MapAccessor` enables accessing values in a `Map` using a key, and a `ReflectivePropertyAccessor` which allows access to fields and or JavaBean compliant properties (using getters and setters).
This is how the `Message` headers and payload properties are accessible.
[[spel-customization]]
=== SpEL Evaluation Context Customization
Starting with Spring Integration 3.0, it is possible to add additional `PropertyAccessor` s to the SpEL evaluation contexts used by the framework.
The framework provides the `JsonPropertyAccessor` which can be used (read-only) to access fields from a `JsonNode`, or JSON in a `String`.
Or you can create your own `PropertyAccessor` if you have specific needs.
In addition, custom functions can be added.
Custom functions are `static` methods declared on a class.
Functions and property accessors are available in any SpEL expression used throughout the framework.
The following configuration shows how to directly configure the `IntegrationEvaluationContextFactoryBean` with custom property accessors and functions.
However, for convenience, namespace support is provided for both, as described in the following sections, and the framework will automatically configure the factory bean on your behalf.
[source,xml]
----
<bean id="integrationEvaluationContext"
class="org.springframework.integration.config.IntegrationEvaluationContextFactoryBean">
<property name="propertyAccessors">
<util:map>
<entry key="foo">
<bean class="foo.MyCustomPropertyAccessor"/>
</entry>
</util:map>
</property>
<property name="functions">
<map>
<entry key="barcalc" value="#{T(foo.MyFunctions).getMethod('calc', T(foo.MyBar))}"/>
</map>
</property>
</bean>
----
This factory bean definition will override the default `integrationEvaluationContext` bean definition, adding the custom accessor to the list (which also includes the standard accessors mentioned above), and one custom function.
Note that custom functions are static methods.
In the above example, the custom function is a static method `calc` on class `MyFunctions` and takes a single parameter of type `MyBar`.
Say you have a `Message` with a payload that has a type `MyFoo` on which you need to perform some action to create a `MyBar` object from it, and you then want to invoke a custom function `calc` on that object.
The standard property accessors wouldn't know how to get a `MyBar` from a `MyFoo` so you could write and configure a custom property accessor to do so.
So, your final expression might be`"#barcalc(payload.myBar)"`.
The factory bean has another property `typeLocator` which allows you to customize the `TypeLocator` used during SpEL evaluation.
This might be necessary when running in some environments that use a non-standard `ClassLoader`.
In the following example, SpEL expressions will always use the bean factory's class loader:
[source,xml]
----
<bean id="integrationEvaluationContext"
class="org.springframework.integration.config.IntegrationEvaluationContextFactoryBean">
<property name="typeLocator">
<bean class="org.springframework.expression.spel.support.StandardTypeLocator">
<constructor-arg value="#{beanFactory.beanClassLoader}"/>
</bean>
</property>
</bean>
----
[[spel-functions]]
=== SpEL Functions
Namespace support is provided for easy addition of SpEL custom functions.
You can specify `<spel-function/>` components to provide http://static.springsource.org/spring-framework/docs/current/spring-framework-reference/html/expressions.html#expressions-ref-functions[custom SpEL functions] to the `EvaluationContext` used throughout the framework.
Instead of configuring the factory bean above, simply add one or more of these components and the framework will automatically add them to the default _integrationEvaluationContext_ factory bean.
For example, assuming we have a useful static method to evaluate XPath:
[source,xml]
----
<int:spel-function id="xpath"
class="com.foo.test.XPathUtils" method="evaluate(java.lang.String, java.lang.Object)"/>
<int:transformer input-channel="in" output-channel="out"
expression="#xpath('//foo/@bar', payload)" />
----
With this sample:
* The default `IntegrationEvaluationContextFactoryBean` bean with id _integrationEvaluationContext_ is registered with the application context.
* The `<spel-function/>` is parsed and added to the `functions` Map of _integrationEvaluationContext_ as map entry with `id` as the key and the static `Method` as the value.
* The _integrationEvaluationContext_ factory bean creates a new `StandardEvaluationContext` instance, and it is configured with the default `PropertyAccessor` s, `BeanResolver` and the custom functions.
* That `EvaluationContext` instance is injected into the `ExpressionEvaluatingTransformer` bean.
NOTE: SpEL functions declared in a parent context are also made available in any child context(s).
Each context has its own instance of the _integrationEvaluationContext_ factory bean because each needs a different `BeanResolver`, but the function declarations are inherited and can be overridden if needed by declaring a SpEL function with the same name.
*Built-in SpEL Functions*
Spring Integration provides some standard functions, which are registered with the application context automatically on start up:
*#jsonPath* - to evaluate a 'jsonPath' on some provided object.
This function invokes `JsonPathUtils.evaluate(...)`.
This static method delegates to the http://code.google.com/p/json-path[Jayway JsonPath library].
The following shows some usage examples:
[source,xml]
----
<transformer expression="#jsonPath(payload, '$.store.book[0].author')"/>
<filter expression="#jsonPath(payload,'$..book[2].isbn') matches '\d-\d{3}-\d{5}-\d'"/>
<splitter expression="#jsonPath(payload, '$.store.book')"/>
<router expression="#jsonPath(payload, headers.jsonPath)">
<mapping channel="output1" value="reference"/>
<mapping channel="output2" value="fiction"/>
</router>
----
#jsonPath also supports the third optional parameter - an array of https://github.com/jayway/JsonPath/blob/master/json-path/src/main/java/com/jayway/jsonpath/Filter.java[`com.jayway.jsonpath.Filter`], which could be provided by a reference to a bean or bean method, for example.
NOTE: Using this function requires the Jayway JsonPath library (json-path.jar) to be on the classpath; otherwise the _#jsonPath_ SpEL function won't be registered.
For more information regarding JSON see 'JSON Transformers' in <<transformer>>.
*#xpath* - to evaluate an 'xpath' on some provided object.
For more information regarding xml and xpath see <<xml>>.
[[spel-property-accessors]]
=== PropertyAccessors
Namespace support is provided for the easy addition of SpEL custom http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/expression/PropertyAccessor.html[`PropertyAccessor`] implementations.
You can specify the `<spel-property-accessors/>` component to provide a list of custom `PropertyAccessor` s to the `EvaluationContext` used throughout the framework.
Instead of configuring the factory bean above, simply add one or more of these components, and the framework will automatically add the accessors to the default_integrationEvaluationContext_ factory bean:
[source,xml]
----
<int:spel-property-accessors>
<bean id="jsonPA" class="org.springframework.integration.json.JsonPropertyAccessor"/>
<ref bean="fooPropertyAccessor"/>
</int:spel-property-accessors>
----
With this sample, two custom `PropertyAccessor` s will be injected to the `EvaluationContext` in the order that they are declared.
NOTE: Custom `PropertyAccessor` s declared in a parent context are also made available in any child context(s).
They are placed at the end of result list (but before the default `org.springframework.context.expression.MapAccessor` and `org.springframework.expression.spel.support.ReflectivePropertyAccessor`).
If a `PropertyAccessor` with the same bean id is declared in a child context(s), it will override the parent accessor.
Beans declared within a `<spel-property-accessors/>` must have an 'id' attribute.
The final order of usage is: the accessors in the current context, in the order in which they are declared, followed by any from parent contexts, in order, followed by the `MapAccessor` and finally the `ReflectivePropertyAccessor`.

128
src/reference/asciidoc/splitter.adoc Normal file
View File

@@ -0,0 +1,128 @@
[[splitter]]
=== Splitter
[[splitter-annotation]]
==== Introduction
The Splitter is a component whose role is to partition a message in several parts, and send the resulting messages to be processed independently.
Very often, they are upstream producers in a pipeline that includes an Aggregator.
==== Programming model
The API for performing splitting consists of one base class, `AbstractMessageSplitter`, which is a `MessageHandler` implementation, encapsulating features which are common to splitters, such as filling in the appropriate message headers CORRELATION_ID, SEQUENCE_SIZE, and SEQUENCE_NUMBER on the messages that are produced.
This enables tracking down the messages and the results of their processing (in a typical scenario, these headers would be copied over to the messages that are produced by the various transforming endpoints), and use them, for example, in ahttp://www.eaipatterns.com/DistributionAggregate.html[Composed Message Processor] scenario.
An excerpt from `AbstractMessageSplitter` can be seen below:
[source,java]
----
public abstract class AbstractMessageSplitter
extends AbstractReplyProducingMessageConsumer {
...
protected abstract Object splitMessage(Message<?> message);
}
----
To implement a specific Splitter in an application, extend `AbstractMessageSplitter` and implement the `splitMessage` method, which contains logic for splitting the messages.
The return value may be one of the following:
* A `Collection` or an array of Messages, or an `Iterable` (or `Iterator`) that iterates over Messages - in this case the messages will be sent as such (after the CORRELATION_ID, SEQUENCE_SIZE and SEQUENCE_NUMBER are populated).
Using this approach gives more control to the developer, for example for populating custom message headers as part of the splitting process.
* A `Collection` or an array of non-Message objects, or an `Iterable` (or `Iterator`) that iterates over non-Message objects - works like the prior case, except that each collection element will be used as a Message payload.
Using this approach allows developers to focus on the domain objects without having to consider the Messaging system and produces code that is easier to test.
* a `Message` or non-Message object (but not a Collection or an Array) - it works like the previous cases, except a single message will be sent out.
In Spring Integration, any POJO can implement the splitting algorithm, provided that it defines a method that accepts a single argument and has a return value.
In this case, the return value of the method will be interpreted as described above.
The input argument might either be a `Message` or a simple POJO.
In the latter case, the splitter will receive the payload of the incoming message.
Since this decouples the code from the Spring Integration API and will typically be easier to test, it is the recommended approach.
*Splitter and Iterators*
Starting with _version 4.1_, the `AbstractMessageSplitter` supports the `Iterator` type for the `value` to split.
Note, in the case of an `Iterator` (or `Iterable`), we don't have access to the number of underlying items and the `SEQUENCE_SIZE` header is set to `0`.
This means that the default `SequenceSizeReleaseStrategy` of an `<aggregator>` won't work and the group for the `CORRELATION_ID` from the `splitter` won't be released; it will remain as `incomplete`.
In this case you should use an appropriate custom `ReleaseStrategy` or rely on `send-partial-result-on-expiry` together with `group-timeout` or a `MessageGroupStoreReaper`.
An `Iterator` object is useful to avoid the need for building an entire collection in the memory before splitting.
For example, when underlying items are populated from some external system (e.g.
DataBase or FTP `MGET`) using iterations or streams.
[[splitter-config]]
==== Configuring Splitter
===== Configuring a Splitter using XML
A splitter can be configured through XML as follows:
[source,xml]
----
<int:channel id="inputChannel"/>
<int:splitter id="splitter" <1>
ref="splitterBean" <2>
method="split" <3>
input-channel="inputChannel" <4>
output-channel="outputChannel" /> <5>
<int:channel id="outputChannel"/>
<beans:bean id="splitterBean" class="sample.PojoSplitter"/>
----
<1> The id of the splitter is _optional_.
<2> A reference to a bean defined in the application context.
The bean must implement the splitting logic as described in the section above ._Optional_.
If reference to a bean is not provided, then it is assumed that the _payload_ of the Message that arrived on the `input-channel` is an implementation of `java.util.Collection` and the default splitting logic will be applied to the Collection, incorporating each individual element into a Message and sending it to the `output-channel`.
<3> The method (defined on the bean specified above) that implements the splitting logic._Optional_.
<4> The input channel of the splitter.
_Required_.
<5> The channel to which the splitter will send the results of splitting the incoming message.
_Optional (because incoming
messages can specify a reply channel themselves)_.
Using a `ref` attribute is generally recommended if the custom splitter implementation may be referenced in other `<splitter>` definitions.
However if the custom splitter handler implementation should be scoped to a single definition of the `<splitter>`, configure an inner bean definition:
[source,xml]
----
<int:splitter id="testSplitter" input-channel="inChannel" method="split"
output-channel="outChannel">
<beans:bean class="org.foo.TestSplitter"/>
</int:spliter>
----
NOTE: Using both a `ref` attribute and an inner handler definition in the same `<int:splitter>` configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
===== Configuring a Splitter with Annotations
The `@Splitter` annotation is applicable to methods that expect either the`Message` type or the message payload type, and the return values of the method should be a `Collection` of any type.
If the returned values are not actual `Message` objects, then each item will be wrapped in a Message as its payload.
Each message will be sent to the designated output channel for the endpoint on which the `@Splitter` is defined.
[source,java]
----
@Splitter
List<LineItem> extractItems(Order order) {
return order.getItems()
}
----
Also see <<advising-with-annotations>>.

95
src/reference/asciidoc/stream.adoc Normal file
View File

@@ -0,0 +1,95 @@
[[stream]]
== Stream Support
[[stream-intro]]
=== Introduction
In many cases application data is obtained from a stream.
It is _not_ recommended to send a reference to a Stream as a message payload to a consumer.
Instead messages are created from data that is read from an input stream and message payloads are written to an output stream one by one.
[[stream-reading]]
=== Reading from streams
Spring Integration provides two adapters for streams.
Both `ByteStreamReadingMessageSource` and `CharacterStreamReadingMessageSource` implement `MessageSource`.
By configuring one of these within a channel-adapter element, the polling period can be configured, and the Message Bus can automatically detect and schedule them.
The byte stream version requires an `InputStream`, and the character stream version requires a `Reader` as the single constructor argument.
The `ByteStreamReadingMessageSource` also accepts the 'bytesPerMessage' property to determine how many bytes it will attempt to read into each `Message`.
The default value is 1024
[source,xml]
----
<bean class="org.springframework.integration.stream.ByteStreamReadingMessageSource">
<constructor-arg ref="someInputStream"/>
<property name="bytesPerMessage" value="2048"/>
</bean>
<bean class="org.springframework.integration.stream.CharacterStreamReadingMessageSource">
<constructor-arg ref="someReader"/>
</bean>
----
[[stream-writing]]
=== Writing to streams
For target streams, there are also two implementations: `ByteStreamWritingMessageHandler` and `CharacterStreamWritingMessageHandler`.
Each requires a single constructor argument - `OutputStream` for byte streams or `Writer` for character streams, and each provides a second constructor that adds the optional 'bufferSize'.
Since both of these ultimately implement the `MessageHandler` interface, they can be referenced from a _channel-adapter_ configuration as described in more detail in <<channel-adapter>>.
[source,xml]
----
<bean class="org.springframework.integration.stream.ByteStreamWritingMessageHandler">
<constructor-arg ref="someOutputStream"/>
<constructor-arg value="1024"/>
</bean>
<bean class="org.springframework.integration.stream.CharacterStreamWritingMessageHandler">
<constructor-arg ref="someWriter"/>
</bean>
----
[[stream-namespace]]
=== Stream namespace support
To reduce the configuration needed for stream related channel adapters there is a namespace defined.
The following schema locations are needed to use it.
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns:int-stream="http://www.springframework.org/schema/integration/stream"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:beans="http://www.springframework.org/schema/beans"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/integration/stream
http://www.springframework.org/schema/integration/stream/spring-integration-stream.xsd">
----
To configure the inbound channel adapter the following code snippet shows the different configuration options that are supported.
[source,xml]
----
<int-stream:stdin-channel-adapter id="adapterWithDefaultCharset"/>
<int-stream:stdin-channel-adapter id="adapterWithProvidedCharset" charset="UTF-8"/>
----
To configure the outbound channel adapter you can use the namespace support as well.
The following code snippet shows the different configuration for an outbound channel adapters.
[source,xml]
----
<int-stream:stdout-channel-adapter id="stdoutAdapterWithDefaultCharset"
channel="testChannel"/>
<int-stream:stdout-channel-adapter id="stdoutAdapterWithProvidedCharset" charset="UTF-8"
channel="testChannel"/>
<int-stream:stderr-channel-adapter id="stderrAdapter" channel="testChannel"/>
<int-stream:stdout-channel-adapter id="newlineAdapter" append-newline="true"
channel="testChannel"/>
----

677
src/reference/asciidoc/stylesheets/golo.css Normal file
View File

@@ -0,0 +1,677 @@
@import url(http://fonts.googleapis.com/css?family=Varela+Round|Open+Sans:400italic,700italic,400,700);
/*! normalize.css v2.1.2 | MIT License | git.io/normalize */
/* ========================================================================== HTML5 display definitions ========================================================================== */
/** Correct `block` display not defined in IE 8/9. */
@import url(http://cdnjs.cloudflare.com/ajax/libs/font-awesome/3.2.1/css/font-awesome.css);
article, aside, details, figcaption, figure, footer, header, hgroup, main, nav, section, summary { display: block; }
/** Correct `inline-block` display not defined in IE 8/9. */
audio, canvas, video { display: inline-block; }
/** Prevent modern browsers from displaying `audio` without controls. Remove excess height in iOS 5 devices. */
audio:not([controls]) { display: none; height: 0; }
/** Address `[hidden]` styling not present in IE 8/9. Hide the `template` element in IE, Safari, and Firefox < 22. */
[hidden], template { display: none; }
script { display: none !important; }
/* ========================================================================== Base ========================================================================== */
/** 1. Set default font family to sans-serif. 2. Prevent iOS text size adjust after orientation change, without disabling user zoom. */
html { font-family: sans-serif; /* 1 */ -ms-text-size-adjust: 100%; /* 2 */ -webkit-text-size-adjust: 100%; /* 2 */ }
/** Remove default margin. */
body { margin: 0; }
/* ========================================================================== Links ========================================================================== */
/** Remove the gray background color from active links in IE 10. */
a { background: transparent; }
/** Address `outline` inconsistency between Chrome and other browsers. */
a:focus { outline: thin dotted; }
/** Improve readability when focused and also mouse hovered in all browsers. */
a:active, a:hover { outline: 0; }
/* ========================================================================== Typography ========================================================================== */
/** Address variable `h1` font-size and margin within `section` and `article` contexts in Firefox 4+, Safari 5, and Chrome. */
h1 { font-size: 2em; margin: 0.67em 0; }
/** Address styling not present in IE 8/9, Safari 5, and Chrome. */
abbr[title] { border-bottom: 1px dotted; }
/** Address style set to `bolder` in Firefox 4+, Safari 5, and Chrome. */
b, strong { font-weight: bold; }
/** Address styling not present in Safari 5 and Chrome. */
dfn { font-style: italic; }
/** Address differences between Firefox and other browsers. */
hr { -moz-box-sizing: content-box; box-sizing: content-box; height: 0; }
/** Address styling not present in IE 8/9. */
mark { background: #ff0; color: #000; }
/** Correct font family set oddly in Safari 5 and Chrome. */
code, kbd, pre, samp { font-family: monospace, serif; font-size: 1em; }
/** Improve readability of pre-formatted text in all browsers. */
pre { white-space: pre-wrap; }
/** Set consistent quote types. */
q { quotes: "\201C" "\201D" "\2018" "\2019"; }
/** Address inconsistent and variable font size in all browsers. */
small { font-size: 80%; }
/** Prevent `sub` and `sup` affecting `line-height` in all browsers. */
sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; }
sup { top: -0.5em; }
sub { bottom: -0.25em; }
/* ========================================================================== Embedded content ========================================================================== */
/** Remove border when inside `a` element in IE 8/9. */
img { border: 0; }
/** Correct overflow displayed oddly in IE 9. */
svg:not(:root) { overflow: hidden; }
/* ========================================================================== Figures ========================================================================== */
/** Address margin not present in IE 8/9 and Safari 5. */
figure { margin: 0; }
/* ========================================================================== Forms ========================================================================== */
/** Define consistent border, margin, and padding. */
fieldset { border: 1px solid #c0c0c0; margin: 0 2px; padding: 0.35em 0.625em 0.75em; }
/** 1. Correct `color` not being inherited in IE 8/9. 2. Remove padding so people aren't caught out if they zero out fieldsets. */
legend { border: 0; /* 1 */ padding: 0; /* 2 */ }
/** 1. Correct font family not being inherited in all browsers. 2. Correct font size not being inherited in all browsers. 3. Address margins set differently in Firefox 4+, Safari 5, and Chrome. */
button, input, select, textarea { font-family: inherit; /* 1 */ font-size: 100%; /* 2 */ margin: 0; /* 3 */ }
/** Address Firefox 4+ setting `line-height` on `input` using `!important` in the UA stylesheet. */
button, input { line-height: normal; }
/** Address inconsistent `text-transform` inheritance for `button` and `select`. All other form control elements do not inherit `text-transform` values. Correct `button` style inheritance in Chrome, Safari 5+, and IE 8+. Correct `select` style inheritance in Firefox 4+ and Opera. */
button, select { text-transform: none; }
/** 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio` and `video` controls. 2. Correct inability to style clickable `input` types in iOS. 3. Improve usability and consistency of cursor style between image-type `input` and others. */
button, html input[type="button"], input[type="reset"], input[type="submit"] { -webkit-appearance: button; /* 2 */ cursor: pointer; /* 3 */ }
/** Re-set default cursor for disabled elements. */
button[disabled], html input[disabled] { cursor: default; }
/** 1. Address box sizing set to `content-box` in IE 8/9. 2. Remove excess padding in IE 8/9. */
input[type="checkbox"], input[type="radio"] { box-sizing: border-box; /* 1 */ padding: 0; /* 2 */ }
/** 1. Address `appearance` set to `searchfield` in Safari 5 and Chrome. 2. Address `box-sizing` set to `border-box` in Safari 5 and Chrome (include `-moz` to future-proof). */
input[type="search"] { -webkit-appearance: textfield; /* 1 */ -moz-box-sizing: content-box; -webkit-box-sizing: content-box; /* 2 */ box-sizing: content-box; }
/** Remove inner padding and search cancel button in Safari 5 and Chrome on OS X. */
input[type="search"]::-webkit-search-cancel-button, input[type="search"]::-webkit-search-decoration { -webkit-appearance: none; }
/** Remove inner padding and border in Firefox 4+. */
button::-moz-focus-inner, input::-moz-focus-inner { border: 0; padding: 0; }
/** 1. Remove default vertical scrollbar in IE 8/9. 2. Improve readability and alignment in all browsers. */
textarea { overflow: auto; /* 1 */ vertical-align: top; /* 2 */ }
/* ========================================================================== Tables ========================================================================== */
/** Remove most spacing between table cells. */
table { border-collapse: collapse; border-spacing: 0; }
meta.foundation-mq-small { font-family: "only screen and (min-width: 768px)"; width: 768px; }
meta.foundation-mq-medium { font-family: "only screen and (min-width:1280px)"; width: 1280px; }
meta.foundation-mq-large { font-family: "only screen and (min-width:1440px)"; width: 1440px; }
*, *:before, *:after { -moz-box-sizing: border-box; -webkit-box-sizing: border-box; box-sizing: border-box; }
html, body { font-size: 100%; }
body { background: white; color: #222222; padding: 0; margin: 0; font-family: "Helvetica Neue", "Helvetica", Helvetica, Arial, sans-serif; font-weight: normal; font-style: normal; line-height: 1; position: relative; cursor: auto; }
a:hover { cursor: pointer; }
img, object, embed { max-width: 100%; height: auto; }
object, embed { height: 100%; }
img { -ms-interpolation-mode: bicubic; }
#map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { max-width: none !important; }
.left { float: left !important; }
.right { float: right !important; }
.text-left { text-align: left !important; }
.text-right { text-align: right !important; }
.text-center { text-align: center !important; }
.text-justify { text-align: justify !important; }
.hide { display: none; }
.antialiased, body { -webkit-font-smoothing: antialiased; }
img { display: inline-block; vertical-align: middle; }
textarea { height: auto; min-height: 50px; }
select { width: 100%; }
p.lead, .paragraph.lead > p, #preamble > .sectionbody > .paragraph:first-of-type p { font-size: 1.21875em; line-height: 1.6; }
.subheader, #content #toctitle, .admonitionblock td.content > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .mathblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, .sidebarblock > .title, .tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title, .tableblock > caption { line-height: 1.4; color: #385dbd; font-weight: 300; margin-top: 0.2em; margin-bottom: 0.5em; }
/* Typography resets */
div, dl, dt, dd, ul, ol, li, h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6, pre, form, p, blockquote, th, td { margin: 0; padding: 0; direction: ltr; }
/* Default Link Styles */
a { color: #095557; text-decoration: underline; line-height: inherit; }
a:hover, a:focus { color: #042829; }
a img { border: none; }
/* Default paragraph styles */
p { font-family: inherit; font-weight: normal; font-size: 1em; line-height: 1.6; margin-bottom: 1.25em; text-rendering: optimizeLegibility; }
p aside { font-size: 0.875em; line-height: 1.35; font-style: italic; }
/* Default header styles */
h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { font-family: "Varela Round", Arial, sans-serif; font-weight: normal; font-style: normal; color: #152347; text-rendering: optimizeLegibility; margin-top: 0.8em; margin-bottom: 0.5em; line-height: 1.2125em; }
h1 small, h2 small, h3 small, #toctitle small, .sidebarblock > .content > .title small, h4 small, h5 small, h6 small { font-size: 60%; color: #385dbd; line-height: 0; }
h1 { font-size: 2.125em; }
h2 { font-size: 1.6875em; }
h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.375em; }
h4 { font-size: 1.125em; }
h5 { font-size: 1.125em; }
h6 { font-size: 1em; }
hr { border: solid #dcd2c9; border-width: 1px 0 0; clear: both; margin: 1.25em 0 1.1875em; height: 0; }
/* Helpful Typography Defaults */
em, i { font-style: italic; line-height: inherit; }
strong, b { font-weight: bold; line-height: inherit; }
small { font-size: 60%; line-height: inherit; }
code { font-family: Consolas, "Liberation Mono", Courier, monospace; font-weight: bold; color: #691816; }
/* Lists */
ul, ol, dl { font-size: 1em; line-height: 1.6; margin-bottom: 1.25em; list-style-position: outside; font-family: inherit; }
ul, ol { margin-left: 1.5em; }
ul.no-bullet, ol.no-bullet { margin-left: 1.5em; }
/* Unordered Lists */
ul li ul, ul li ol { margin-left: 1.25em; margin-bottom: 0; font-size: 1em; /* Override nested font-size change */ }
ul.square li ul, ul.circle li ul, ul.disc li ul { list-style: inherit; }
ul.square { list-style-type: square; }
ul.circle { list-style-type: circle; }
ul.disc { list-style-type: disc; }
ul.no-bullet { list-style: none; }
/* Ordered Lists */
ol li ul, ol li ol { margin-left: 1.25em; margin-bottom: 0; }
/* Definition Lists */
dl dt { margin-bottom: 0.3125em; font-weight: bold; }
dl dd { margin-bottom: 1.25em; }
/* Abbreviations */
abbr, acronym { text-transform: uppercase; font-size: 90%; color: #211306; border-bottom: 1px dotted #dddddd; cursor: help; }
abbr { text-transform: none; }
/* Blockquotes */
blockquote { margin: 0 0 1.25em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 1px solid #dddddd; }
blockquote cite { display: block; font-size: 0.8125em; color: #655241; }
blockquote cite:before { content: "\2014 \0020"; }
blockquote cite a, blockquote cite a:visited { color: #655241; }
blockquote, blockquote p { line-height: 1.6; color: #846b55; }
/* Microformats */
.vcard { display: inline-block; margin: 0 0 1.25em 0; border: 1px solid #dddddd; padding: 0.625em 0.75em; }
.vcard li { margin: 0; display: block; }
.vcard .fn { font-weight: bold; font-size: 0.9375em; }
.vevent .summary { font-weight: bold; }
.vevent abbr { cursor: auto; text-decoration: none; font-weight: bold; border: none; padding: 0 0.0625em; }
@media only screen and (min-width: 768px) { h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; }
h1 { font-size: 2.75em; }
h2 { font-size: 2.3125em; }
h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.6875em; }
h4 { font-size: 1.4375em; } }
/* Print styles. Inlined to avoid required HTTP connection: www.phpied.com/delay-loading-your-print-css/ Credit to Paul Irish and HTML5 Boilerplate (html5boilerplate.com)
*/
.print-only { display: none !important; }
@media print { * { background: transparent !important; color: #000 !important; /* Black prints faster: h5bp.com/s */ box-shadow: none !important; text-shadow: none !important; }
a, a:visited { text-decoration: underline; }
a[href]:after { content: " (" attr(href) ")"; }
abbr[title]:after { content: " (" attr(title) ")"; }
.ir a:after, a[href^="javascript:"]:after, a[href^="#"]:after { content: ""; }
pre, blockquote { border: 1px solid #999; page-break-inside: avoid; }
thead { display: table-header-group; /* h5bp.com/t */ }
tr, img { page-break-inside: avoid; }
img { max-width: 100% !important; }
@page { margin: 0.5cm; }
p, h2, h3, #toctitle, .sidebarblock > .content > .title { orphans: 3; widows: 3; }
h2, h3, #toctitle, .sidebarblock > .content > .title { page-break-after: avoid; }
.hide-on-print { display: none !important; }
.print-only { display: block !important; }
.hide-for-print { display: none !important; }
.show-for-print { display: inherit !important; } }
/* Tables */
table { background: white; margin-bottom: 1.25em; border: solid 1px #e4e7ef; }
table thead, table tfoot { background: rgba(105, 60, 22, 0.25); font-weight: bold; }
table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { padding: 0.5em 0.625em 0.625em; font-size: inherit; color: #211306; text-align: left; }
table tr th, table tr td { padding: 0.5625em 0.625em; font-size: inherit; color: #211306; }
table tr.even, table tr.alt, table tr:nth-of-type(even) { background: #f4f5f8; }
table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { display: table-cell; line-height: 1.6; }
.clearfix:before, .clearfix:after, .float-group:before, .float-group:after { content: " "; display: table; }
.clearfix:after, .float-group:after { clear: both; }
*:not(pre) > code { font-size: inherit; padding: 0; white-space: nowrap; background-color: inherit; border: 0 solid #dddddd; -webkit-border-radius: 6px; border-radius: 6px; text-shadow: none; }
pre, pre > code { line-height: 1.4; color: black; font-family: monospace, serif; font-weight: normal; }
.keyseq { color: #774417; }
kbd:not(.keyseq) { display: inline-block; color: #211306; font-size: 0.75em; line-height: 1.4; background-color: #F7F7F7; border: 1px solid #ccc; -webkit-border-radius: 3px; border-radius: 3px; -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px white inset; box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px white inset; margin: -0.15em 0.15em 0 0.15em; padding: 0.2em 0.6em 0.2em 0.5em; vertical-align: middle; white-space: nowrap; }
.keyseq kbd:first-child { margin-left: 0; }
.keyseq kbd:last-child { margin-right: 0; }
.menuseq, .menu { color: black; }
b.button:before, b.button:after { position: relative; top: -1px; font-weight: normal; }
b.button:before { content: "["; padding: 0 3px 0 2px; }
b.button:after { content: "]"; padding: 0 2px 0 3px; }
p a > code:hover { color: #541312; }
#header, #content, #footnotes, #footer { width: 100%; margin-left: auto; margin-right: auto; margin-top: 0; margin-bottom: 0; max-width: 62.5em; *zoom: 1; position: relative; padding-left: 0.9375em; padding-right: 0.9375em; }
#header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { content: " "; display: table; }
#header:after, #content:after, #footnotes:after, #footer:after { clear: both; }
#header { margin-bottom: 2.5em; }
#header > h1 { color: #693c16; font-weight: normal; border-bottom: 1px solid #dcd2c9;}
#header span { color: #846b55; }
#header #revnumber { text-transform: capitalize; }
#header br { display: none; }
#header br + span { padding-left: 3px; }
#header br + span.author { padding-left: 0; }
#header br + span.author:before { content: ", "; }
#revdate {
display: block;
margin-top: 2.5em;
}
#toc { border-bottom: 1px solid #e6dfd8; padding-bottom: 1.25em; }
#toc > ul { margin-left: 0.25em; }
#toc ul.sectlevel0 > li > a { font-style: italic; }
#toc ul.sectlevel0 ul.sectlevel1 { margin-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; }
#toc ul { list-style-type: none; }
#toctitle { color: #385dbd; }
@media only screen and (min-width: 768px) { body.toc2 { padding-left: 15em; padding-right: 0; }
#toc.toc2 { position: fixed; width: 15em; left: 0; top: 0; border-right: 1px solid #e6dfd8; border-bottom: 0; z-index: 1000; padding: 1em; height: 100%; overflow: auto; }
#toc.toc2 #toctitle { margin-top: 0; font-size: 1.2em; }
#toc.toc2 > ul { font-size: .90em; }
#toc.toc2 ul ul { margin-left: 0; padding-left: 1em; }
#toc.toc2 ul.sectlevel0 ul.sectlevel1 { padding-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; }
body.toc2.toc-right { padding-left: 0; padding-right: 15em; }
body.toc2.toc-right #toc.toc2 { border-right: 0; border-left: 1px solid #e6dfd8; left: auto; right: 0; } }
@media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; padding-right: 0; }
#toc.toc2 { width: 20em; }
#toc.toc2 #toctitle { font-size: 1.375em; }
#toc.toc2 > ul { font-size: 0.95em; }
#toc.toc2 ul ul { padding-left: 1.25em; }
body.toc2.toc-right { padding-left: 0; padding-right: 20em; } }
#content #toc { border-style: solid; border-width: 1px; border-color: #d9d9d9; margin-bottom: 1.25em; padding: 1.25em; background: #f2f2f2; border-width: 0; -webkit-border-radius: 6px; border-radius: 6px; }
#content #toc > :first-child { margin-top: 0; }
#content #toc > :last-child { margin-bottom: 0; }
#content #toc a { text-decoration: none; }
#content #toctitle { font-weight: bold; font-family: "Open Sans", Arial, sans-serif; font-size: 1em; padding-left: 0.125em; }
#footer { max-width: 100%; background-color: #23160c; padding: 1.25em; }
#footer-text { color: #deecf9; line-height: 1.44; }
.sect1 { padding-bottom: 1.25em; }
.sect1 + .sect1 { border-top: 1px solid #e6dfd8; }
#content h1 > a.anchor, h2 > a.anchor, h3 > a.anchor, #toctitle > a.anchor, .sidebarblock > .content > .title > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { position: absolute; width: 1em; margin-left: -1em; display: block; text-decoration: none; visibility: hidden; text-align: center; font-weight: normal; }
#content h1 > a.anchor:before, h2 > a.anchor:before, h3 > a.anchor:before, #toctitle > a.anchor:before, .sidebarblock > .content > .title > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { content: '\00A7'; font-size: .85em; vertical-align: text-top; display: block; margin-top: 0.05em; }
#content h1:hover > a.anchor, #content h1 > a.anchor:hover, h2:hover > a.anchor, h2 > a.anchor:hover, h3:hover > a.anchor, #toctitle:hover > a.anchor, .sidebarblock > .content > .title:hover > a.anchor, h3 > a.anchor:hover, #toctitle > a.anchor:hover, .sidebarblock > .content > .title > a.anchor:hover, h4:hover > a.anchor, h4 > a.anchor:hover, h5:hover > a.anchor, h5 > a.anchor:hover, h6:hover > a.anchor, h6 > a.anchor:hover { visibility: visible; }
#content h1 > a.link, h2 > a.link, h3 > a.link, #toctitle > a.link, .sidebarblock > .content > .title > a.link, h4 > a.link, h5 > a.link, h6 > a.link { color: #152347; text-decoration: none; }
#content h1 > a.link:hover, h2 > a.link:hover, h3 > a.link:hover, #toctitle > a.link:hover, .sidebarblock > .content > .title > a.link:hover, h4 > a.link:hover, h5 > a.link:hover, h6 > a.link:hover { color: #0f1933; }
.imageblock, .literalblock, .listingblock, .mathblock, .verseblock, .videoblock { margin-bottom: 1.25em; }
.admonitionblock td.content > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .mathblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, .sidebarblock > .title, .tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { text-align: left; font-weight: bold; }
.tableblock > caption { text-align: left; font-weight: bold; white-space: nowrap; overflow: visible; max-width: 0; }
table.tableblock #preamble > .sectionbody > .paragraph:first-of-type p { font-size: inherit; }
.admonitionblock > table { border: 0; background: none; width: 100%; }
.admonitionblock > table td.icon { text-align: center; width: 80px; }
.admonitionblock > table td.icon img { max-width: none; }
.admonitionblock > table td.icon .title { font-weight: bold; text-transform: uppercase; }
.admonitionblock > table td.content { padding-left: 1.125em; padding-right: 1.25em; border-left: 1px solid #dcd2c9; color: #846b55; }
.admonitionblock > table td.content > :last-child > :last-child { margin-bottom: 0; }
.exampleblock > .content { border-style: solid; border-width: 1px; border-color: #f3e0ce; margin-bottom: 1.25em; padding: 1.25em; background: #fdfaf7; -webkit-border-radius: 6px; border-radius: 6px; }
.exampleblock > .content > :first-child { margin-top: 0; }
.exampleblock > .content > :last-child { margin-bottom: 0; }
.exampleblock > .content h1, .exampleblock > .content h2, .exampleblock > .content h3, .exampleblock > .content #toctitle, .sidebarblock.exampleblock > .content > .title, .exampleblock > .content h4, .exampleblock > .content h5, .exampleblock > .content h6, .exampleblock > .content p { color: #333333; }
.exampleblock > .content h1, .exampleblock > .content h2, .exampleblock > .content h3, .exampleblock > .content #toctitle, .sidebarblock.exampleblock > .content > .title, .exampleblock > .content h4, .exampleblock > .content h5, .exampleblock > .content h6 { line-height: 1; margin-bottom: 0.625em; }
.exampleblock > .content h1.subheader, .exampleblock > .content h2.subheader, .exampleblock > .content h3.subheader, .exampleblock > .content .subheader#toctitle, .sidebarblock.exampleblock > .content > .subheader.title, .exampleblock > .content h4.subheader, .exampleblock > .content h5.subheader, .exampleblock > .content h6.subheader { line-height: 1.4; }
.exampleblock.result > .content { -webkit-box-shadow: 0 1px 8px #d9d9d9; box-shadow: 0 1px 8px #d9d9d9; }
.sidebarblock { border-style: solid; border-width: 1px; border-color: #d9d9d9; margin-bottom: 1.25em; padding: 1.25em; background: #f2f2f2; -webkit-border-radius: 6px; border-radius: 6px; }
.sidebarblock > :first-child { margin-top: 0; }
.sidebarblock > :last-child { margin-bottom: 0; }
.sidebarblock h1, .sidebarblock h2, .sidebarblock h3, .sidebarblock #toctitle, .sidebarblock > .content > .title, .sidebarblock h4, .sidebarblock h5, .sidebarblock h6, .sidebarblock p { color: #333333; }
.sidebarblock h1, .sidebarblock h2, .sidebarblock h3, .sidebarblock #toctitle, .sidebarblock > .content > .title, .sidebarblock h4, .sidebarblock h5, .sidebarblock h6 { line-height: 1; margin-bottom: 0.625em; }
.sidebarblock h1.subheader, .sidebarblock h2.subheader, .sidebarblock h3.subheader, .sidebarblock .subheader#toctitle, .sidebarblock > .content > .subheader.title, .sidebarblock h4.subheader, .sidebarblock h5.subheader, .sidebarblock h6.subheader { line-height: 1.4; }
.sidebarblock > .content > .title { color: #385dbd; margin-top: 0; line-height: 1.6; }
.exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { margin-bottom: 0; }
.literalblock pre:not([class]), .listingblock pre:not([class]) { background: url('../images/golo/pre-bg.png?1370460826'); }
.literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { border-width: 1px; border-style: solid; border-color: rgba(21, 35, 71, 0.1); -webkit-border-radius: 6px; border-radius: 6px; padding: 0.8em; word-wrap: break-word; }
.literalblock pre.nowrap, .literalblock pre[class].nowrap, .listingblock pre.nowrap, .listingblock pre[class].nowrap { overflow-x: auto; white-space: pre; word-wrap: normal; }
.literalblock pre > code, .literalblock pre[class] > code, .listingblock pre > code, .listingblock pre[class] > code { display: block; }
@media only screen { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 0.72em; } }
@media only screen and (min-width: 768px) { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 0.81em; } }
@media only screen and (min-width: 1280px) { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 0.9em; } }
.listingblock pre.highlight { padding: 0; }
.listingblock pre.highlight > code { padding: 0.8em; }
.listingblock > .content { position: relative; }
.listingblock:hover code[class*=" language-"]:before { text-transform: uppercase; font-size: 0.9em; color: #999; position: absolute; top: 0.375em; right: 0.375em; }
.listingblock:hover code.asciidoc:before { content: "asciidoc"; }
.listingblock:hover code.clojure:before { content: "clojure"; }
.listingblock:hover code.css:before { content: "css"; }
.listingblock:hover code.groovy:before { content: "groovy"; }
.listingblock:hover code.html:before { content: "html"; }
.listingblock:hover code.java:before { content: "java"; }
.listingblock:hover code.javascript:before { content: "javascript"; }
.listingblock:hover code.python:before { content: "python"; }
.listingblock:hover code.ruby:before { content: "ruby"; }
.listingblock:hover code.sass:before { content: "sass"; }
.listingblock:hover code.scss:before { content: "scss"; }
.listingblock:hover code.xml:before { content: "xml"; }
.listingblock:hover code.yaml:before { content: "yaml"; }
.listingblock.terminal pre .command:before { content: attr(data-prompt); padding-right: 0.5em; color: #999; }
.listingblock.terminal pre .command:not([data-prompt]):before { content: '$'; }
table.pyhltable { border: 0; margin-bottom: 0; }
table.pyhltable td { vertical-align: top; padding-top: 0; padding-bottom: 0; }
table.pyhltable td.code { padding-left: .75em; padding-right: 0; }
.highlight.pygments .lineno, table.pyhltable td:not(.code) { color: #999; padding-left: 0; padding-right: .5em; border-right: 1px solid #dcd2c9; }
.highlight.pygments .lineno { display: inline-block; margin-right: .25em; }
table.pyhltable .linenodiv { background-color: transparent !important; padding-right: 0 !important; }
.quoteblock { margin: 0 0 1.25em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 1px solid #dddddd; }
.quoteblock blockquote { margin: 0 0 1.25em 0; padding: 0 0 0.5625em 0; border: 0; }
.quoteblock blockquote > .paragraph:last-child p { margin-bottom: 0; }
.quoteblock .attribution { margin-top: -.25em; padding-bottom: 0.5625em; font-size: 0.8125em; color: #655241; }
.quoteblock .attribution br { display: none; }
.quoteblock .attribution cite { display: block; margin-bottom: 0.625em; }
table thead th, table tfoot th { font-weight: bold; }
table.tableblock.grid-all { border-collapse: separate; border-spacing: 1px; -webkit-border-radius: 6px; border-radius: 6px; border-top: 1px solid #e4e7ef; border-bottom: 1px solid #e4e7ef; }
table.tableblock.frame-topbot, table.tableblock.frame-none { border-left: 0; border-right: 0; }
table.tableblock.frame-sides, table.tableblock.frame-none { border-top: 0; border-bottom: 0; }
table.tableblock td .paragraph:last-child p > p:last-child, table.tableblock th > p:last-child, table.tableblock td > p:last-child { margin-bottom: 0; }
th.tableblock.halign-left, td.tableblock.halign-left { text-align: left; }
th.tableblock.halign-right, td.tableblock.halign-right { text-align: right; }
th.tableblock.halign-center, td.tableblock.halign-center { text-align: center; }
th.tableblock.valign-top, td.tableblock.valign-top { vertical-align: top; }
th.tableblock.valign-bottom, td.tableblock.valign-bottom { vertical-align: bottom; }
th.tableblock.valign-middle, td.tableblock.valign-middle { vertical-align: middle; }
tbody tr th { display: table-cell; line-height: 1.6; background: rgba(105, 60, 22, 0.25); }
tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { color: #211306; font-weight: bold; }
td > div.verse { white-space: pre; }
ol { margin-left: 1.75em; }
ul li ol { margin-left: 1.5em; }
dl dd { margin-left: 1.125em; }
dl dd:last-child, dl dd:last-child > :last-child { margin-bottom: 0; }
ol > li p, ul > li p, ul dd, ol dd, .olist .olist, .ulist .ulist, .ulist .olist, .olist .ulist { margin-bottom: 0.625em; }
ul.unstyled, ol.unnumbered, ul.checklist, ul.none { list-style-type: none; }
ul.unstyled, ol.unnumbered, ul.checklist { margin-left: 0.625em; }
ul.checklist li > p:first-child > i[class^="icon-check"]:first-child, ul.checklist li > p:first-child > input[type="checkbox"]:first-child { margin-right: 0.25em; }
ul.checklist li > p:first-child > input[type="checkbox"]:first-child { position: relative; top: 1px; }
ul.inline { margin: 0 auto 0.625em auto; margin-left: -1.375em; margin-right: 0; padding: 0; list-style: none; overflow: hidden; }
ul.inline > li { list-style: none; float: left; margin-left: 1.375em; display: block; }
ul.inline > li > * { display: block; }
.unstyled dl dt { font-weight: normal; font-style: normal; }
ol.arabic { list-style-type: decimal; }
ol.decimal { list-style-type: decimal-leading-zero; }
ol.loweralpha { list-style-type: lower-alpha; }
ol.upperalpha { list-style-type: upper-alpha; }
ol.lowerroman { list-style-type: lower-roman; }
ol.upperroman { list-style-type: upper-roman; }
ol.lowergreek { list-style-type: lower-greek; }
.hdlist > table, .colist > table { border: 0; background: none; }
.hdlist > table > tbody > tr, .colist > table > tbody > tr { background: none; }
td.hdlist1 { padding-right: .75em; font-weight: bold; }
td.hdlist1, td.hdlist2 { vertical-align: top; }
.literalblock + .colist, .listingblock + .colist { margin-top: -0.5em; }
.colist > table tr > td:first-of-type { padding: 0 .75em; line-height: 1; }
.colist > table tr > td:last-of-type { padding: 0.25em 0; }
.qanda > ol > li > p > em:only-child { color: #063f40; }
.thumb, .th { line-height: 0; display: inline-block; border: solid 4px white; -webkit-box-shadow: 0 0 0 1px #dddddd; box-shadow: 0 0 0 1px #dddddd; }
.imageblock.left, .imageblock[style*="float: left"] { margin: 0.25em 0.625em 1.25em 0; }
.imageblock.right, .imageblock[style*="float: right"] { margin: 0.25em 0 1.25em 0.625em; }
.imageblock > .title { margin-bottom: 0; }
.imageblock.thumb, .imageblock.th { border-width: 6px; }
.imageblock.thumb > .title, .imageblock.th > .title { padding: 0 0.125em; }
.image.left, .image.right { margin-top: 0.25em; margin-bottom: 0.25em; display: inline-block; line-height: 0; }
.image.left { margin-right: 0.625em; }
.image.right { margin-left: 0.625em; }
a.image { text-decoration: none; }
span.footnote, span.footnoteref { vertical-align: super; font-size: 0.875em; }
span.footnote a, span.footnoteref a { text-decoration: none; }
#footnotes { padding-top: 0.75em; padding-bottom: 0.75em; margin-bottom: 0.625em; }
#footnotes hr { width: 20%; min-width: 6.25em; margin: -.25em 0 .75em 0; border-width: 1px 0 0 0; }
#footnotes .footnote { padding: 0 0.375em; line-height: 1.3; font-size: 0.875em; margin-left: 1.2em; text-indent: -1.2em; margin-bottom: .2em; }
#footnotes .footnote a:first-of-type { font-weight: bold; text-decoration: none; }
#footnotes .footnote:last-of-type { margin-bottom: 0; }
#content #footnotes { margin-top: -0.625em; margin-bottom: 0; padding: 0.75em 0; }
.gist .file-data > table { border: none; background: #fff; width: 100%; margin-bottom: 0; }
.gist .file-data > table td.line-data { width: 99%; }
div.unbreakable { page-break-inside: avoid; }
.big { font-size: larger; }
.small { font-size: smaller; }
.underline { text-decoration: underline; }
.overline { text-decoration: overline; }
.line-through { text-decoration: line-through; }
.aqua { color: #00bfbf; }
.aqua-background { background-color: #00fafa; }
.black { color: black; }
.black-background { background-color: black; }
.blue { color: #0000bf; }
.blue-background { background-color: #0000fa; }
.fuchsia { color: #bf00bf; }
.fuchsia-background { background-color: #fa00fa; }
.gray { color: #606060; }
.gray-background { background-color: #7d7d7d; }
.green { color: #006000; }
.green-background { background-color: #007d00; }
.lime { color: #00bf00; }
.lime-background { background-color: #00fa00; }
.maroon { color: #600000; }
.maroon-background { background-color: #7d0000; }
.navy { color: #000060; }
.navy-background { background-color: #00007d; }
.olive { color: #606000; }
.olive-background { background-color: #7d7d00; }
.purple { color: #600060; }
.purple-background { background-color: #7d007d; }
.red { color: #bf0000; }
.red-background { background-color: #fa0000; }
.silver { color: #909090; }
.silver-background { background-color: #bcbcbc; }
.teal { color: #006060; }
.teal-background { background-color: #007d7d; }
.white { color: #bfbfbf; }
.white-background { background-color: #fafafa; }
.yellow { color: #bfbf00; }
.yellow-background { background-color: #fafa00; }
span.icon > [class^="icon-"], span.icon > [class*=" icon-"] { cursor: default; }
.admonitionblock td.icon [class^="icon-"]:before { font-size: 2.5em; text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5); cursor: default; }
.admonitionblock td.icon .icon-note:before { content: "\f05a"; color: #095557; color: #064042; }
.admonitionblock td.icon .icon-tip:before { content: "\f0eb"; text-shadow: 1px 1px 2px rgba(155, 155, 0, 0.8); color: #111; }
.admonitionblock td.icon .icon-warning:before { content: "\f071"; color: #bf6900; }
.admonitionblock td.icon .icon-caution:before { content: "\f06d"; color: #bf3400; }
.admonitionblock td.icon .icon-important:before { content: "\f06a"; color: #bf0000; }
.conum { display: inline-block; color: white !important; background-color: #211306; -webkit-border-radius: 100px; border-radius: 100px; text-align: center; width: 20px; height: 20px; font-size: 12px; font-weight: bold; line-height: 20px; font-family: Arial, sans-serif; font-style: normal; position: relative; top: -2px; letter-spacing: -1px; }
.conum * { color: white !important; }
.conum + b { display: none; }
.conum:after { content: attr(data-value); }
.conum:not([data-value]):empty { display: none; }
body { background: url('../images/golo/body-bg.png?1370460826') #fdfaf7 repeat; }
#toc.toc2 ul ul { padding-left: 1.75em; }
#toctitle { color: #152347; }
#header h1 { font-weight: bold; position: relative; left: -0.0625em; }
#header h1 span.lo { color: #dc9424; }
#content h2, #content h3, #content #toctitle, #content .sidebarblock > .content > .title, #content h4, #content h5, #content #toctitle { font-weight: normal; position: relative; left: -0.0625em; }
#content h2 { font-weight: bold; }
.literalblock .content pre.highlight, .listingblock .content pre.highlight { background: url('../images/golo/pre-bg.png?1370460826'); }
.admonitionblock > table td.content { border-color: #e6dfd8; }
table.tableblock.grid-all { -webkit-border-radius: 0; border-radius: 0; }
#footer { background-color: #23160c; }

123
src/reference/asciidoc/syslog.adoc Normal file
View File

@@ -0,0 +1,123 @@
[[syslog]]
== Syslog Support
[[syslog-intro]]
=== Introduction
Spring Integration 2.2 introduced the Syslog transformer `SyslogToMapTransformer`.
This transformer, together with a `UDP` or `TCP` inbound adapter could be used to receive and analyze syslog records from other hosts.
The transformer creates a message payload containing a map of the elements from the syslog message.
Spring Integration 3.0 introduced convenient namespace support for configuring a Syslog inbound adapter in a single element.
Starting with _version 4.1.1_, the framework now supports the extended Syslog format, as specified in https://tools.ietf.org/html/rfc5424[RFC 5424>].
In addition, when using TCP and RFC5424, both `octet counting` and `non-transparent framing` described in https://tools.ietf.org/html/rfc6587[RFC 6587] are supported.
[[syslog-inbound-adapter]]
=== Syslog <inbound-channel-adapter>
This element encompasses a `UDP` or `TCP` inbound channel adapter and a `MessageConverter` to convert the Syslog message to a Spring Integration message.
The `DefaultMessageConverter` delegates to the `SyslogToMapTransformer`, creating a message with its payload being the `Map` of Syslog fields.
In addition, all fields except the message are also made available as headers in the message, prefixed with `syslog_`.
In this mode, only https://tools.ietf.org/html/rfc3164[RFC 3164] (BSD) syslogs are supported.
Since _version 4.1_, the `DefaultMessageConverter` has a property `asMap` (default `true`); when it is `false`, the converter will leave the message payload as the original complete syslog message, in a `byte[]`, while still setting the headers.
Since _version 4.1.1_, RFC 5424 is also supported, using the `RFC5424MessageConverter`; in this case the fields are not copied as headers, unless `asMap` is set to `false`, in which case the original message is the payload and the decoded fields are headers.
IMPORTANT: To use RFC 5424 with a TCP transport, additional configuration is required, to enable the different framing techniques described in RFC 6587.
The adapter needs a TCP connection factory configured with a `RFC6587SyslogDeserializer`.
By default, this deserializer will handle `octet counting` and `non-transparent framing`, using a linefeed (LF) to delimit syslog messages; it uses a `ByteArrayLfSerializer` when `octet counting` is not detected.
To use different `non-transparent` framing, you can provide it with some other deserializer.
While the deserializer can support both `octet counting` and `non-transparent framing`, only one form of the latter is supported.
If `asMap` is `false` on the converter, you must set the `retainOriginal` constructor argument in the `RFC6587SyslogDeserializer`.
[[syslog-inbound-examplers]]
==== Example Configuration
[source,xml]
----
<int-syslog:inbound-channel-adapter id="syslogIn" port="1514" />
----
A `UDP` adapter that sends messages to channel `syslogIn` (the adapter bean name is `syslogIn.adapter`).
The adapter listens on port `1514`.
[source,xml]
----
<int-syslog:inbound-channel-adapter id="syslogIn"
channel="fromSyslog" port="1514" />
----
A `UDP` adapter that sends message to channel `fromSyslog` (the adapter bean name is `syslogIn`).
The adapter listens on port `1514`.
[source,xml]
----
<int-syslog:inbound-channel-adapter id="bar" protocol="tcp" port="1514" />
----
A `TCP` adapter that sends messages to channel `syslogIn` (the adapter bean name is `syslogIn.adapter`).
The adapter listens on port `1514`.
Note the addition of the `protocol` attribute.
This attribute can contain `udp` or `tcp`; it defaults to `udp`.
[source,xml]
----
<int-syslog:inbound-channel-adapter id="udpSyslog"
channel="fromSyslog"
auto-startup="false"
phase="10000"
converter="converter"
send-timeout="1000"
error-channel="errors">
<int-syslog:udp-attributes port="1514" lookup-host="false" />
</int-syslog:inbound-channel-adapter>
----
A `UDP` adapter that sends messages to channel `fromSyslog`.
It also shows the `SmartLifecyle` attributes `auto-startup` and `phase`.
It has a reference to a custom `org.springframework.integration.syslog.MessageConverter` with id `converter` and an `error-channel`.
Also notice the `udp-attributes` child element.
You can set various UDP attributes here, as defined in <<ip-ib-adapter-attributes>>.
NOTE: When using the `udp-attributes` element, the `port` attribute must be provided there rather than on the `inbound-channel-adapter` element itself.
[source,xml]
----
<int-syslog:inbound-channel-adapter id="TcpSyslog"
protocol="tcp"
channel="fromSyslog"
connection-factory="cf" />
<int-ip:tcp-connection-factory id="cf" type="server" port="1514" />
----
A `TCP` adapter that sends messages to channel `fromSyslog`.
It also shows how to reference an externally defined connection factory, which can be used for advanced configuration (socket keep alive etc).
For more information, see <<connection-factories>>.
NOTE: The externally configured `connection-factory` must be of type `server` and, the port is defined there rather than on the `inbound-channel-adapter` element itself.
[source,xml]
----
<int-syslog:inbound-channel-adapter id="rfc5424Tcp"
protocol="tcp"
channel="fromSyslog"
connection-factory="cf"
converter="rfc5424" />
<int-ip:tcp-connection-factory id="cf"
using-nio="true"
type="server"
port="1514"
deserializer="rfc6587" />
<bean id="rfc5424" class="org.springframework.integration.syslog.RFC5424MessageConverter" />
<bean id="rfc6587" class="org.springframework.integration.syslog.inbound.RFC6587SyslogDeserializer" />
----
A `TCP` adapter that sends messages to channel `fromSyslog`.
It is configured to use the `RFC 5424` converter and is configured with a reference to an externally defined connection factory with the `RFC 6587` deserializer (required for RFC 5424).

16
src/reference/asciidoc/system-management.adoc Normal file
View File

@@ -0,0 +1,16 @@
[[system-management-chapter]]
== System Management
// BE SURE TO PRECEDE ALL include:: with a blank line - see https://github.com/asciidoctor/asciidoctor/issues/1297
include::./jmx.adoc[]
include::./message-history.adoc[]
include::./message-store.adoc[]
include::./meta-data-store.adoc[]
include::./control-bus.adoc[]
include::./shutdown.adoc[]
// BE SURE TO PRECEDE ALL include:: with a blank line - see https://github.com/asciidoctor/asciidoctor/issues/1297

222
src/reference/asciidoc/transactions.adoc Normal file
View File

@@ -0,0 +1,222 @@
[[transactions]]
== Transaction Support
[[transaction-support]]
=== Understanding Transactions in Message flows
Spring Integration exposes several hooks to address transactional needs of you message flows.
But to better understand these hooks and how you can benefit from them we must first revisit the 6 mechanisms that could be used to initiate Message flows and see how transactional needs of these flows could be addressed within each of these mechanisms.
Here are the 6 mechanisms to initiate a Message flow and their short summary (details for each are provided throughout this manual):
* _Gateway Proxy_ - Your basic Messaging Gateway
* _MessageChannel_ - Direct interactions with MessageChannel methods (e.g., channel.send(message))
* _Message Publisher_ - the way to initiate message flow as the by-product of method invocations on Spring beans
* _Inbound Channel Adapters/Gateways_ - the way to initiate message flow based on connecting third-party system with Spring Integration messaging system(e.g., [JmsMessage] -> Jms Inbound Adapter[SI Message] -> SI Channel)
* _Scheduler_ - the way to initiate message flow based on scheduling events distributed by a pre-configured Scheduler
* _Poller_ - similar to the Scheduler and is the way to initiate message flow based on scheduling or interval-based events distributed by a pre-configured Poller
These 6 could be split in 2 general categories:
* _Message flows initiated by a USER process_ - Example scenarios in this category would be invoking a Gateway method or explicitly sending a Message to a MessageChannel.
In other words, these message flows depend on a third party process (e.g., some code that we wrote) to be initiated.
* _Message flows initiated by a DAEMON process_ - Example scenarios in this category would be a Poller polling a Message queue to initiate a new Message flow with the polled Message or a Scheduler scheduling the process by creating a new Message and initiating a message flow at a predefined time.
Clearly the _Gateway Proxy_, _MessageChannel.send(..)_ and _MessagePublisher_ all belong to the 1st category and _Inbound Adapters/Gateways_, _Scheduler_ and _Poller_ belong to the 2nd.
So, how do we address transactional needs in various scenarios within each category and is there a need for Spring Integration to provide something explicitly with regard to transactions for a particular scenario? Or, can Spring's Transaction Support be leveraged instead?.
The first and most obvious goal is NOT to re-invent something that has already been invented unless you can provide a better solution.
In our case Spring itself provides first class support for transaction management.
So our goal here is not to provide something new but rather delegate/use Spring to benefit from the existing support for transactions.
In other words as a framework we must expose hooks to the Transaction management functionality provided by Spring.
But since Spring Integration configuration is based on Spring Configuration it is not always necessary to expose these hooks as they are already exposed via Spring natively.
Remember every Spring Integration component is a Spring Bean after all.
With this goal in mind let's look at the two scenarios. 
If you think about it, Message flows that are initiated by the _USER process_ (Category 1) and obviously configured in a Spring Application Context, are subject to transactional configuration of such processes and therefore don't need to be explicitly configured by Spring Integration to support transactions.
The transaction could and should be initiated through standard Transaction support provided by Spring.
The Spring Integration message flow will honor the transactional semantics of the components naturally because it is Spring configured.
For example, a Gateway or ServiceActivator method could be annotated with `@Transactional` or `TransactionInterceptor` could be defined in an XML configuration with a point-cut expression pointing to specific methods that should be transactional.
The bottom line is that you have full control over transaction configuration and boundaries in these scenarios.
However, things are a bit different when it comes to Message flows initiated by the _DAEMON process_ (Category 2).
Although configured by the developer these flows do not directly involve a human or some other process to be initiated.
These are trigger-based flows that are initiated by a trigger process (DAEMON process) based on the configuration of such process.
For example, we could have a Scheduler initiating a message flow every Friday night of every week.
We can also configure a trigger that initiates a Message flow every second, etc.
So, we obviously need a way to let these trigger-based processes know of our intention to make the resulting Message flows transactional so that a Transaction context could be created whenever a new Message flow is initiated.
In other words we need to expose some Transaction configuration, but ONLY enough to delegate to Transaction support already provided by Spring (as we do in other scenarios).
Spring Integration provides transactional support for Pollers.
Pollers are a special type of component because we can call receive() within that poller task against a resource that is itself transactional thus including _receive()_ call in the the boundaries of the Transaction allowing it to be rolled back in case of a task failure.
If we were to add the same support for channels, the added transactions would affect all downstream components starting with that _send()_ call.
That is providing a rather wide scope for transaction demarcation without any strong reason especially when Spring already provides several ways to address the transactional needs of any component downstream.
However the _receive()_ method being included in a transaction boundary is the "strong reason" for pollers.
[[transaction-poller]]
==== Poller Transaction Support
Any time you configure a Poller you can provide transactional configuration via the _transactional_ sub-element and its attributes:
[source,xml]
----
<int:poller max-messages-per-poll="1" fixed-rate="1000">
<transactional transaction-manager="txManager" 
isolation="DEFAULT"
propagation="REQUIRED" 
read-only="true" 
timeout="1000"/>
</poller>
----
As you can see this configuration looks very similar to native Spring transaction configuration.
You must still provide a reference to a Transaction manager and specify transaction attributes or rely on defaults (e.g., if the 'transaction-manager' attribute is not specified, it will default to the bean with the name 'transactionManager').
Internally the process would be wrapped in Spring's native Transaction where `TransactionInterceptor` is responsible for handling transactions.
For more information on how to configure a Transaction Manager, the types of Transaction Managers (e.g., JTA, Datasource etc.) and other details related to transaction configuration please refer to Spring's Reference manual (Chapter 10 - Transaction Management).
With the above configuration all Message flows initiated by this poller will be transactional.
For more information and details on a Poller's transactional configuration please refer to section - _21.1.1.
Polling and Transactions_.
Along with transactions, several more cross cutting concerns might need to be addressed when running a Poller.
To help with that, the Poller element accepts an _<advice-chain> _ sub-element which allows you to define a custom chain of Advice instances to be applied on the Poller.
(see section 4.4 for more details) In Spring Integration 2.0, the Poller went through the a refactoring effort and is now using a proxy mechanism to address transactional concerns as well as other cross cutting concerns.
One of the significant changes evolving from this effort is that we made _<transactional>_ and _<advice-chain>_ elements mutually exclusive.
The rationale behind this is that if you need more than one advice, and one of them is Transaction advice, then you can simply include it in the _<advice-chain>_ with the same convenience as before but with much more control since you now have an option to position any advice in the desired order.
[source,xml]
----
<int:poller max-messages-per-poll="1" fixed-rate="10000">
<advice-chain>
<ref bean="txAdvice"/>
<ref bean="someAotherAdviceBean" />
<beans:bean class="foo.bar.SampleAdvice"/>
</advice-chain>
</poller>
<tx:advice id="txAdvice" transaction-manager="txManager">
<tx:attributes>
<tx:method name="get*" read-only="true"/>
<tx:method name="*"/>
</tx:attributes>
</tx:advice>
----
As you can see from the example above, we have provided a very basic XML-based configuration of Spring Transaction advice  - "txAdvice" and included it within the _<advice-chain>_ defined by the Poller.
If you only need to address transactional concerns of the Poller, then you can still use the _<transactional>_ element as a convenience.
[[transaction-boundaries]]
=== Transaction Boundaries
Another important factor is the boundaries of Transactions within a Message flow.
When a transaction is started, the transaction context is bound to the current thread.
So regardless of how many endpoints and channels you have in your Message flow your transaction context will be preserved as long as you are ensuring that the flow continues on the same thread.
As soon as you break it by introducing a _Pollable Channel_ or _Executor Channel_ or initiate a new thread manually in some service, the Transactional boundary will be broken as well.
Essentially the Transaction will END right there, and if a successful handoff has transpired between the threads, the flow would be considered a success and a COMMIT signal would be sent even though the flow will continue and might still result in an Exception somewhere downstream.
If such a flow were synchronous, that Exception could be thrown back to the initiator of the Message flow who is also the initiator of the transactional context and the transaction would result in a ROLLBACK.
The middle ground is to use transactional channels at any point where a thread boundary is being broken.
For example, you can use a Queue-backed Channel that delegates to a transactional MessageStore strategy, or you could use a JMS-backed channel.
[[transaction-synchronization]]
=== Transaction Synchronization
In some environments, it is advantageous to synchronize operations with a transaction that encompasses the entire flow.
For example, consider a <file:inbound-channel-adapter/> at the start of a flow, that performs a number of database updates.
If the transaction commits, we might want to move the file to a _success_ directory, while we might want to move it to a _failures_ directory if the transaction rolls back.
Spring Integration 2.2 introduces the capability of synchronizing these operations with a transaction.
In addition, you can configure a `PseudoTransactionManager` if you don't have a 'real' transaction, but still want to perform different actions on success, or failure.
For more information, see <<pseudo-transactions>>.
Key strategy interfaces for this feature are
[source,java]
----
public interface TransactionSynchronizationFactory {
TransactionSynchronization create(Object key);
}
public interface TransactionSynchronizationProcessor {
void processBeforeCommit(IntegrationResourceHolder holder);
void processAfterCommit(IntegrationResourceHolder holder);
void processAfterRollback(IntegrationResourceHolder holder);
}
----
The factory is responsible for creating a http://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/transaction/support/TransactionSynchronization.html[TransactionSynchronization] object.
You can implement your own, or use the one provided by the framework: `DefaultTransactionSynchronizationFactory`.
This implementation returns a `TransactionSynchronization` that delegates to a default implementation of `TransactionSynchronizationProcessor`, the `ExpressionEvaluatingTransactionSynchronizationProcessor`.
This processor supports three SpEL expressions, _beforeCommitExpression_, _afterCommitExpression_, and _afterRollbackExpression_.
These actions should be self-explanatory to those familiar with transactions.
In each case, the _#root_ variable is the original `Message`; in some cases, other SpEL variables are made available, depending on the `MessageSource` being polled by the poller.
For example, the `MongoDbMessageSource` provides the _#mongoTemplate_ variable which references the message source's `MongoTemplate`; the `RedisStoreMessageSource` provides the _#store_ variable which references the `RedisStore` created by the poll.
To enable the feature for a particular poller, you provide a reference to the `TransactionSynchronizationFactory` on the poller's <transactional/> element using the _synchronization-factory_ attribute.
To simplify configuration of these components, namespace support for the default factory has been provided.
Configuration is best described using an example:
[source,xml]
----
<int-file:inbound-channel-adapter id="inputDirPoller"
channel="someChannel"
directory="/foo/bar"
filter="filter"
comparator="testComparator">
<int:poller fixed-rate="5000">
<int:transactional transaction-manager="transactionManager" synchronization-factory="syncFactory" />
</int:poller>
</int-file:inbound-channel-adapter>
<int:transaction-synchronization-factory id="syncFactory">
<int:after-commit expression="payload.renameTo('/success/' + payload.name)" channel="committedChannel" />
<int:after-rollback expression="payload.renameTo('/failed/' + payload.name)" channel="rolledBackChannel" />
</int:transaction-synchronization-factory>
----
The result of the SpEL evaluation is sent as the payload to either the _committedChannel_ or _rolledBackChannel_ (in this case, this would be `Boolean.TRUE` or `Boolean.FALSE` - the result of the `java.io.File.renameTo()` method call).
If you wish to send the entire payload for further Spring Integration processing, simply use the expression 'payload'.
[IMPORTANT]
=====
It is important to understand that this is simply synchronizing the actions with a transaction, it does not make a resource that is not inherently transactional actually transactional.
Instead, the transaction (be it JDBC or otherwise) is started before the poll, and committed/rolled back when the flow completes, followed by the synchronized action.
It is also important to understand that if you provide a custom `TransactionSynchronizationFactory`, it is responsible for creating a resource synchronization that will cause the bound resource to be unbound automatically, when the transaction completes.
The default `TransactionSynchronizationFactory` does this by returning a subclass of `ResourceHolderSynchronization`, with the default _shouldUnbindAtCompletion()_ returning `true`.
=====
In addition to the _after-commit_ and _after-rollback_ expressions, _before-commit_ is also supported.
In that case, if the evaluation (or downstream processing) throws an exception, the transaction will be rolled back instead of being committed.
[[pseudo-transactions]]
=== Pseudo Transactions
Referring to the above section, you may be thinking it would be useful to take these 'success' or 'failure' actions when a flow completes, even if there is no 'real' transactional resources (such as JDBC) downstream of the poller.
For example, consider a <file:inbound-channel-adapter/> followed by an <ftp:outbout-channel-adapter/>.
Neither of these components is transactional but we might want to move the input file to different directories, based on the success or failure of the ftp transfer.
To provide this functionality, the framework provides a `PseudoTransactionManager`, enabling the above configuration even when there is no real transactional resource involved.
If the flow completes normally, the _beforeCommit_ and _afterCommit_ synchronizations will be called, on failure the _afterRollback_ will be called.
Of course, because it is not a real transaction there will be no actual commit or rollback.
The pseudo transaction is simply a vehicle used to enable the synchronization features.
To use a `PseudoTransactionManager`, simply define it as a <bean/>, in the same way you would configure a real transaction manager:
[source,xml]
----
<bean id="transactionManager" class="o.s.i.transaction.PseudoTransactionManager" />
----

384
src/reference/asciidoc/transformer.adoc Normal file
View File

@@ -0,0 +1,384 @@
[[transformer]]
=== Transformer
[[transformer-introduction]]
==== Introduction
Message Transformers play a very important role in enabling the loose-coupling of Message Producers and Message Consumers.
Rather than requiring every Message-producing component to know what type is expected by the next consumer, Transformers can be added between those components.
Generic transformers, such as one that converts a String to an XML Document, are also highly reusable.
For some systems, it may be best to provide a http://www.eaipatterns.com/CanonicalDataModel.html[Canonical Data Model], but Spring Integration's general philosophy is not to require any particular format.
Rather, for maximum flexibility, Spring Integration aims to provide the simplest possible model for extension.
As with the other endpoint types, the use of declarative configuration in XML and/or Annotations enables simple POJOs to be adapted for the role of Message Transformers.
These configuration options will be described below.
NOTE: For the same reason of maximizing flexibility, Spring does not require XML-based Message payloads.
Nevertheless, the framework does provide some convenient Transformers for dealing with XML-based payloads if that is indeed the right choice for your application.
For more information on those transformers, see <<xml>>.
[[transformer-config]]
==== Configuring Transformer
[[transformer-namespace]]
===== Configuring Transformer with XML
The <transformer> element is used to create a Message-transforming endpoint.
In addition to "input-channel" and "output-channel" attributes, it requires a "ref".
The "ref" may either point to an Object that contains the @Transformer annotation on a single method (see below) or it may be combined with an explicit method name value provided via the "method" attribute.
[source,xml]
----
<int:transformer id="testTransformer" ref="testTransformerBean" input-channel="inChannel"
method="transform" output-channel="outChannel"/>
<beans:bean id="testTransformerBean" class="org.foo.TestTransformer" />
----
Using a "ref" attribute is generally recommended if the custom transformer handler implementation can be reused in other `<transformer>` definitions.
However if the custom transformer handler implementation should be scoped to a single definition of the `<transformer>`, you can define an inner bean definition:
[source,xml]
----
<int:transformer id="testTransformer" input-channel="inChannel" method="transform"
output-channel="outChannel">
<beans:bean class="org.foo.TestTransformer"/>
</transformer>
----
NOTE: Using both the "ref" attribute and an inner handler definition in the same `<transformer>` configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
The method that is used for transformation may expect either the `Message` type or the payload type of inbound Messages.
It may also accept Message header values either individually or as a full map by using the `@Header` and `@Headers` parameter annotations respectively.
The return value of the method can be any type.
If the return value is itself a `Message`, that will be passed along to the transformer's output channel.
As of Spring Integration 2.0, a Message Transformer's transformation method can no longer return `null`.
Returning `null` will result in an exception since a Message Transformer should always be expected to transform each source Message into a valid target Message.
In other words, a Message Transformer should not be used as a Message Filter since there is a dedicated <filter> option for that.
However, if you do need this type of behavior (where a component might return NULL and that should not be considered an error), a_service-activator_ could be used.
Its `requires-reply` value is FALSE by default, but that can be set to TRUE in order to have Exceptions thrown for NULL return values as with the transformer.
_Transformers and Spring Expression Language (SpEL)_
Just like Routers, Aggregators and other components, as of Spring Integration 2.0 Transformers can also benefit from SpEL support (http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html) whenever transformation logic is relatively simple.
[source,xml]
----
<int:transformer input-channel="inChannel"
output-channel="outChannel"
expression="payload.toUpperCase() + '- [' + T(java.lang.System).currentTimeMillis() + ']'"/>
----
In the above configuration we are achieving a simple transformation of the _payload_ with a simple SpEL expression and without writing a custom transformer.
Our _payload_ (assuming String) will be upper-cased and concatenated with the current timestamp with some simple formatting.
_Common Transformers_
There are also a few Transformer implementations available out of the box.
Because, it is fairly common to use the `toString()` representation of an Object, Spring Integration provides an `ObjectToStringTransformer` whose output is a Message with a String payload.
That String is the result of invoking the toString() operation on the inbound Message's payload.
[source,xml]
----
<int:object-to-string-transformer input-channel="in" output-channel="out"/>
----
A potential example for this would be sending some arbitrary object to the 'outbound-channel-adapter' in the _file_ namespace.
Whereas that Channel Adapter only supports String, byte-array, or `java.io.File` payloads by default, adding this transformer immediately before the adapter will handle the necessary conversion.
Of course, that works fine as long as the result of the `toString()` call is what you want to be written to the File.
Otherwise, you can just provide a custom POJO-based Transformer via the generic 'transformer' element shown previously.
TIP: When debugging, this transformer is not typically necessary since the 'logging-channel-adapter' is capable of logging the Message payload.
Refer to <<channel-wiretap>> for more detail.
[NOTE]
=====
The _object-to-string-transformer_ is very simple; it invokes `toString()` on the inbound payload.
There are two exceptions to this (since 3.0): if the payload is a `char[]`, it invokes `new String(payload)`; if the payload is a `byte[]`, it invokes `new String(payload, charset)`, where `charset` is "UTF-8" by default.
The `charset` can be modified by supplying the _charset_ attribute on the transformer.
For more sophistication (such as selection of the charset dynamically, at runtime), you can use a SpEL expression-based transformer instead; for example:
[source,xml]
----
<int:transformer input-channel="in" output-channel="out"
expression="new java.lang.String(payload, headers['myCharset']" />
----
=====
If you need to serialize an Object to a byte array or deserialize a byte array back into an Object, Spring Integration provides symmetrical serialization transformers.
These will use standard Java serialization by default, but you can provide an implementation of Spring 3.0's Serializer or Deserializer strategies via the 'serializer' and 'deserializer' attributes, respectively.
[source,xml]
----
<int:payload-serializing-transformer input-channel="objectsIn" output-channel="bytesOut"/>
<int:payload-deserializing-transformer input-channel="bytesIn" output-channel="objectsOut"/>
----
_Object-to-Map Transformer_
Spring Integration also provides _Object-to-Map_ and _Map-to-Object_ transformers which utilize the Spring Expression Language (SpEL) to serialize and de-serialize the object graphs.
The object hierarchy is introspected to the most primitive types (String, int, etc.).
The path to this type is described via SpEL, which becomes the _key_ in the transformed Map.
The primitive type becomes the value.
For example:
[source,java]
----
public class Parent{
    private Child child;
    private String name; 
    // setters and getters are omitted
}
public class Child{
   private String name; 
   private List<String> nickNames;
   // setters and getters are omitted
}
----
\...will be transformed to a Map which looks like this: `{person.name=George, person.child.name=Jenna, person.child.nickNames[0]=Bimbo ... etc}`
The SpEL-based Map allows you to describe the object structure without sharing the actual types allowing you to restore/rebuild the object graph into a differently typed Object graph as long as you maintain the structure.
For example: The above structure could be easily restored back to the following Object graph via the Map-to-Object transformer:
[source,java]
----
public class Father {
    private Kid child;
    private String name; 
    // setters and getters are omitted
}
public class Kid {
   private String name; 
   private List<String> nickNames;
   // setters and getters are omitted
}
----
If you need to create a "structured" map, you can provide the 'flatten' attribute.
The default value for this attribute is 'true' meaning the default behavior; if you provide a 'false' value, then the structure will be a map of maps.
For example:
[source,java]
----
public class Parent {
private Child child;
private String name;
// setters and getters are omitted
}
public class Child {
private String name;
private List<String> nickNames;
// setters and getters are omitted
}
----
\...will be transformed to a Map which looks like this: `{name=George, child={name=Jenna, nickNames=[Bimbo, ...]}}`
To configure these transformers, Spring Integration provides namespace support Object-to-Map:
[source,xml]
----
<int:object-to-map-transformer input-channel="directInput" output-channel="output"/>
----
or
[source,xml]
----
<int:object-to-map-transformer input-channel="directInput" output-channel="output" flatten="false"/>
----
Map-to-Object
[source,xml]
----
<int:map-to-object-transformer input-channel="input" 
                       output-channel="output" 
                        type="org.foo.Person"/>
----
or
[source,xml]
----
<int:map-to-object-transformer input-channel="inputA" 
                              output-channel="outputA" 
                              ref="person"/>
<bean id="person" class="org.foo.Person" scope="prototype"/>
----
NOTE: NOTE: 'ref' and 'type' attributes are mutually exclusive.
You can only use one.
Also, if using the 'ref' attribute, you must point to a 'prototype' scoped bean, otherwise a BeanCreationException will be thrown. 
*JSON Transformers*
_Object to JSON_ and _JSON to Object_ transformers are provided.
[source,xml]
----
<int:object-to-json-transformer input-channel="objectMapperInput"/>
----
[source,xml]
----
<int:json-to-object-transformer input-channel="objectMapperInput"
type="foo.MyDomainObject"/>
----
These use a vanilla `JsonObjectMapper` by default based on implementation from classpath.
You can provide your own custom `JsonObjectMapper` implementation with appropriate options or based on required library (e.g.
GSON).
[source,xml]
----
<int:json-to-object-transformer input-channel="objectMapperInput"
type="foo.MyDomainObject" object-mapper="customObjectMapper"/>
----
[NOTE]
=====
Beginning with version 3.0, the `object-mapper` attribute references an instance of a new strategy interface `JsonObjectMapper`.
This abstraction allows multiple implementations of json mappers to be used.
Implementations that wraphttps://github.com/RichardHightower/boon[Boon] and https://github.com/FasterXML[Jackson 2] are provided, with the version being detected on the classpath.
These classes are `BoonJsonObjectMapper` and `Jackson2JsonObjectMapper`.
Note, `BoonJsonObjectMapper` is provided since _version 4.1_.
=====
[IMPORTANT]
=====
If there are requirements to use both Jackson libraries and/or Boon in the same application, keep in mind that before version 3.0, the JSON transformers used only Jackson 1.x.
From _4.1_ on, the framework will select Jackson 2 by default ahead of the Boon implementation if both are on the classpath.
Jackson 1.x is no longer supported by the framework internally but, of course, you can still use it within your code.
To avoid unexpected issues with JSON mapping features, when using annotations, there may be a need to apply annotations from both Jacksons and/or Boon on domain classes:
[source,java]
----
@org.codehaus.jackson.annotate.JsonIgnoreProperties(ignoreUnknown=true)
@com.fasterxml.jackson.annotation.JsonIgnoreProperties(ignoreUnknown=true)
@org.boon.json.annotations.JsonIgnoreProperties("foo")
public class Foo {
@org.codehaus.jackson.annotate.JsonProperty("fooBar")
@com.fasterxml.jackson.annotation.JsonProperty("fooBar")
@org.boon.json.annotations.JsonProperty("fooBar")
public Object bar;
}
----
=====
You may wish to consider using a `FactoryBean` or simple factory method to create the `JsonObjectMapper` with the required characteristics.
[source,java]
----
public class ObjectMapperFactory {
public static Jackson2JsonObjectMapper getMapper() {
ObjectMapper mapper = new ObjectMapper();
mapper.configure(JsonParser.Feature.ALLOW_COMMENTS, true);
return new Jackson2JsonObjectMapper(mapper);
}
}
----
[source,xml]
----
<bean id="customObjectMapper" class="foo.ObjectMapperFactory"
factory-method="getMapper"/>
----
[IMPORTANT]
=====
Beginning with _version 2.2_, the `object-to-json-transformer` sets the _content-type_ header to `application/json`, by default, if the input message does not already have that header present.
It you wish to set the _content type_ header to some other value, or explicitly overwrite any existing header with some value (including `application/json`), use the `content-type` attribute.
If you wish to suppress the setting of the header, set the `content-type` attribute to an empty string (`""`).
This will result in a message with no `content-type` header, unless such a header was present on the input message.
=====
Beginning with _version 3.0_, the `ObjectToJsonTransformer` adds headers, reflecting the source type, to the message.
Similarly, the `JsonToObjectTransformer` can use those type headers when converting the JSON to an object.
These headers are mapped in the AMQP adapters so that they are entirely compatible with the Spring-AMQP http://docs.spring.io/spring-amqp/api/[JsonMessageConverter].
This enables the following flows to work without any special configuration...
`...->amqp-outbound-adapter---->`
`---->amqp-inbound-adapter->json-to-object-transformer->...`
Where the outbound adapter is configured with a `JsonMessageConverter` and the inbound adapter uses the default `SimpleMessageConverter`.
`...->object-to-json-transformer->amqp-outbound-adapter---->`
`---->amqp-inbound-adapter->...`
Where the outbound adapter is configured with a `SimpleMessageConverter` and the inbound adapter uses the default `JsonMessageConverter`.
`...->object-to-json-transformer->amqp-outbound-adapter---->`
`---->amqp-inbound-adapter->json-to-object-transformer->`
Where both adapters are configured with a `SimpleMessageConverter`.
NOTE: When using the headers to determine the type, you should *not* provide a `class` attribute, because it takes precedence over the headers.
In addition to JSON Transformers, Spring Integration provides a built-in _#jsonPath_ SpEL function for use in expressions.
For more information see <<spel>>.
*#xpath SpEL Function*
Since version _3.0_, Spring Integration also provides a built-in _#xpath_ SpEL function for use in expressions.
For more information see <<xpath-spel-function>>.
Beginning with _version 4.0_, the `ObjectToJsonTransformer` supports the `resultType` property, to specify the _node_ JSON representation.
The result node tree representation depends on the implementation of the provided `JsonObjectMapper`.
By default, the `ObjectToJsonTransformer` uses a `Jackson2JsonObjectMapper` and delegates the conversion of the object to the node tree to the `ObjectMapper#valueToTree` method.
The node JSON representation provides efficiency for using the `JsonPropertyAccessor`, when the downstream message flow uses SpEL expressions with access to the properties of the JSON data.
See <<spel-property-accessors>>.
When using Boon, the `NODE` representation is a `Map<String, Object>`
[[transformer-annotation]]
===== Configuring a Transformer with Annotations
The `@Transformer` annotation can also be added to methods that expect either the `Message` type or the message payload type.
The return value will be handled in the exact same way as described above in the section describing the <transformer> element.
[source,java]
----
@Transformer
Order generateOrder(String productId) {
return new Order(productId);
}
----
Transformer methods may also accept the @Header and @Headers annotations that is documented in <<annotations>>
[source,java]
----
@Transformer
Order generateOrder(String productId, @Header("customerName") String customer) {
return new Order(productId, customer);
}
----
Also see <<advising-with-annotations>>.
[[header-filter]]
==== Header Filter
Some times your transformation use case might be as simple as removing a few headers.
For such a use case, Spring Integration provides a _Header Filter_which allows you to specify certain header names
that should be removed from the output Message (e.g.
for security reasons or a value that was only needed temporarily).Basically the _Header Filter_is the opposite of the _Header Enricher_.
The latter is discussed in <<header-enricher>>[source,xml]
----
<int:header-filter input-channel="inputChannel"
output-channel="outputChannel" header-names="lastName, state"/>
----
As you can see, configuration of a _Header Filter_is quite simple.
It is a typical endpoint with input/output channels
and a `header-names` attribute.
That attribute accepts the names of the header(s) (delimited by commas if there are multiple)
that need to be removed.
So, in the above example the headers named 'lastName' and 'state' will not be present on the outbound Message.

330
src/reference/asciidoc/twitter.adoc Normal file
View File

@@ -0,0 +1,330 @@
[[twitter]]
== Twitter Support
Spring Integration provides support for interacting with Twitter.
With the Twitter adapters you can both receive and send Twitter messages.
You can also perform a Twitter search based on a schedule and publish the search results within Messages.
Since _version 4.0_, a search outbound gateway is provided to perform dynamic searches.
[[twitter-intro]]
=== Introduction
Twitter is a social networking and micro-blogging service that enables its users to send and read messages known as tweets.
Tweets are text-based posts of up to 140 characters displayed on the author's profile page and delivered to the author's subscribers who are known as followers.
IMPORTANT: Versions of Spring Integration prior to 2.1 were dependent upon the http://twitter4j.org[Twitter4J API], but with the release of http://projects.spring.io/spring-social[Spring Social 1.0 GA], Spring Integration, as of version 2.1, now builds directly upon Spring Social's Twitter support, instead of Twitter4J.
All Twitter endpoints require the configuration of a `TwitterTemplate` because even search operations require an authenticated template.
Spring Integration provides a convenient namespace configuration to define Twitter artifacts.
You can enable it by adding the following within your XML header.
[source,xml]
----
xmlns:int-twitter="http://www.springframework.org/schema/integration/twitter"
xsi:schemaLocation="http://www.springframework.org/schema/integration/twitter
http://www.springframework.org/schema/integration/twitter/spring-integration-twitter.xsd"
----
[[twitter-oauth]]
=== Twitter OAuth Configuration
For authenticated operations, Twitter uses OAuth - an authentication protocol that allows users to approve an application to act on their behalf without sharing their password.
More information can be found at http://oauth.net[http://oauth.net] or in this article http://hueniverse.com/oauth[http://hueniverse.com/oauth] from Hueniverse.
Please also see http://dev.twitter.com/pages/oauth_faq[OAuth FAQ] for more information about OAuth and Twitter.
In order to use OAuth authentication/authorization with Twitter you must create a new Application on the Twitter Developers site.
Follow the directions below to create a new application and obtain consumer keys and an access token:
* Go to http://dev.twitter.com[http://dev.twitter.com]
* Click on the `Register an app` link and fill out all required fields on the form provided; set `Application Type` to `Client` and depending on the nature of your application select `Default Access Type` as _Read & Write_ or _Read-only_ and Submit the form.
If everything is successful you'll be presented with the `Consumer Key` and `Consumer Secret`.
Copy both values in a safe place.
* On the same page you should see a `My Access Token` button on the side bar (right).
Click on it and you'll be presented with two more values: `Access Token` and `Access Token Secret`.
Copy these values in a safe place as well.
=== Twitter Template
As mentioned above, Spring Integration relies upon Spring Social, and that library provides an implementation of the template pattern, `o.s.social.twitter.api.impl.TwitterTemplate` to interact with Twitter.
For anonymous operations (e.g., search), you don't have to define an instance of `TwitterTemplate` explicitly, since a default instance will be created and injected into the endpoint.
However, for authenticated operations (update status, send direct message, etc.), you must configure a `TwitterTemplate` as a bean and inject it explicitly into the endpoint, because the authentication configuration is required.
Below is a sample configuration of TwitterTemplate:
[source,xml]
----
<bean id="twitterTemplate" class="o.s.social.twitter.api.impl.TwitterTemplate">
<constructor-arg value="4XzBPacJQxyBzzzH"/>
<constructor-arg value="AbRxUAvyCtqQtvxFK8w5ZMtMj20KFhB6o"/>
<constructor-arg value="21691649-4YZY5iJEOfz2A9qCFd9SjBRGb3HLmIm4HNE"/>
<constructor-arg value="AbRxUAvyNCtqQtxFK8w5ZMtMj20KFhB6o"/>
</bean>
----
NOTE: The values above are not real.
As you can see from the configuration above, all we need to do is to provide OAuth `attributes` as constructor arguments.
The values would be those you obtained in the previous step.
The order of constructor arguments is: 1) `consumerKey`, 2) `consumerSecret`, 3) `accessToken`, and 4) `accessTokenSecret`.
A more practical way to manage OAuth connection attributes would be via Spring's property placeholder support by simply creating a property file (e.g., oauth.properties):
[source,java]
----
twitter.oauth.consumerKey=4XzBPacJQxyBzzzH
twitter.oauth.consumerSecret=AbRxUAvyCtqQtvxFK8w5ZMtMj20KFhB6o
twitter.oauth.accessToken=21691649-4YZY5iJEOfz2A9qCFd9SjBRGb3HLmIm4HNE
twitter.oauth.accessTokenSecret=AbRxUAvyNCtqQtxFK8w5ZMtMj20KFhB6o
----
Then, you can configure a `property-placeholder` to point to the above property file:
[source,xml]
----
<context:property-placeholder location="classpath:oauth.properties"/>
<bean id="twitterTemplate" class="o.s.social.twitter.api.impl.TwitterTemplate">
<constructor-arg value="${twitter.oauth.consumerKey}"/>
<constructor-arg value="${twitter.oauth.consumerSecret}"/>
<constructor-arg value="${twitter.oauth.accessToken}"/>
<constructor-arg value="${twitter.oauth.accessTokenSecret}"/>
</bean>
----
[[twitter-inbound]]
=== Twitter Inbound Adapters
Twitter inbound adapters allow you to receive Twitter Messages.
There are several types of http://support.twitter.com/articles/119138-types-of-tweets-and-where-they-appear[twitter messages, or tweets]
_Spring Integration version 2.0 and above_ provides support for receiving tweets as _Timeline Updates_, _Direct Messages_, _Mention Messages_ as well as Search Results.
[IMPORTANT]
=====
Every Inbound Twitter Channel Adapter is a _Polling Consumer_ which means you have to provide a poller configuration.
Twitter defines a concept of Rate Limiting.
You can read more about it here: https://dev.twitter.com/docs/rate-limiting/1.1[Rate Limiting].
In a nutshell, Rate Limiting is a mechanism that Twitter uses to manage how often an application can poll for updates.
You should consider this when setting your poller intervals so that the adapter polls in compliance with the Twitter policies.
With Spring Integration prior to _version 3.0_, a hard-coded limit within the adapters was used to ensure the polling interval could not be less than 15 seconds.
This is no longer the case and the poller configuration is applied directly.
=====
Another issue that we need to worry about is handling duplicate Tweets.
The same adapter (e.g., Search or Timeline Update) while polling on Twitter may receive the same values more than once.
For example if you keep searching on Twitter with the same search criteria you'll end up with the same set of tweets unless some other new tweet that matches your search criteria was posted in between your searches.
In that situation you'll get all the tweets you had before plus the new one.
But what you really want is only the new tweet(s).
Spring Integration provides an elegant mechanism for handling these situations.
The latest Tweet id will be stored in an instance of the `org.springframework.integration.metadata.MetadataStore` strategy (e.g.
last retrieved tweet in this case).
For more information see <<metadata-store>>.
NOTE: The key used to persist the latest _twitter id_ is the value of the (required) `id` attribute of the Twitter Inbound Channel Adapter component plus the `profileId` of the Twitter user.
Prior to _version 4.0_, the page size was hard-coded to 20.
This is now configurable using the `page-size` attribute (defaults to 20).
[[inbound-twitter-update]]
==== Inbound Message Channel Adapter
This adapter allows you to receive updates from everyone you follow.
It's essentially the "Timeline Update" adapter.
[source,xml]
----
<int-twitter:inbound-channel-adapter
twitter-template="twitterTemplate"
channel="inChannel">
<int:poller fixed-rate="5000" max-messages-per-poll="3"/>
</int-twitter:inbound-channel-adapter>
----
[[inbound-twitter-direct]]
==== Direct Inbound Message Channel Adapter
This adapter allows you to receive Direct Messages that were sent to you from other Twitter users.
[source,xml]
----
<int-twitter:dm-inbound-channel-adapter
twitter-template="twiterTemplate"
channel="inboundDmChannel">
<int-poller fixed-rate="5000" max-messages-per-poll="3"/>
</int-twitter:dm-inbound-channel-adapter>
----
[[inbound-twitter-mention]]
==== Mentions Inbound Message Channel Adapter
This adapter allows you to receive Twitter Messages that Mention you via @user syntax.
[source,xml]
----
<int-twitter:mentions-inbound-channel-adapter
twitter-template="twiterTemplate"
channel="inboundMentionsChannel">
<int:poller fixed-rate="5000" max-messages-per-poll="3"/>
</int-twitter:mentions-inbound-channel-adapter>
----
[[inbound-twitter-search]]
==== Search Inbound Message Channel Adapter
This adapter allows you to perform searches.
As you can see it is not necessary to define twitter-template since a search can be performed anonymously, however you must define a search query.
[source,xml]
----
<int-twitter:search-inbound-channel-adapter
query="#springintegration"
channel="inboundMentionsChannel">
<int:poller fixed-rate="5000" max-messages-per-poll="3"/>
</int-twitter:search-inbound-channel-adapter>
----
Refer to https://dev.twitter.com/docs/using-search to learn more about Twitter queries.
As you can see the configuration of all of these adapters is very similar to other inbound adapters with one exception.
Some may need to be injected with the `twitter-template`.
Once received each Twitter Message would be encapsulated in a Spring Integration Message and sent to the channel specified by the `channel` attribute.
Currently the Payload type of any Message is `org.springframework.integration.twitter.core.Tweet` which is very similar to the object with the same name in Spring Social.
As we migrate to Spring Social we'll be depending on their API and some of the artifacts that are currently in use will be obsolete, however we've already made sure that the impact of such migration is minimal by aligning our API with the current state (at the time of writing) of Spring Social.
To get the text from the `org.springframework.social.twitter.api.Tweet` simply invoke the `getText()` method.
[[twitter-outbound]]
=== Twitter Outbound Adapter
Twitter outbound channel adapters allow you to send Twitter Messages, or tweets.
_Spring Integration version 2.0 and above_ supports sending _Status Update Messages_ and _Direct Messages_.
Twitter outbound channel adapters will take the Message payload and send it as a Twitter message.
Currently the only supported payload type is`String`, so consider adding a _transformer_ if the payload of the incoming message is not a String.
[[outbound-twitter-update]]
==== Twitter Outbound Update Channel Adapter
This adapter allows you to send regular status updates by simply sending a Message to the channel identified by the `channel` attribute.
[source,xml]
----
<int-twitter:outbound-channel-adapter
twitter-template="twitterTemplate"
channel="twitterChannel"/>
----
The only extra configuration that is required for this adapter is the `twitter-template` reference.
Starting with _version 4.0_ the `<int-twitter:outbound-channel-adapter>` supports a `tweet-data-expression` to populate the `TweetData` argument (http://projects.spring.io/spring-social-twitter/[Spring Social Twitter]) using the message as the root object of the expression evaluation context.
The result can be a `String`, which will be used for the `TweetData` message; a `Tweet` object, the `text` of which will be used for the `TweetData` message; or an entire `TweetData` object.
For convenience, the `TweetData` can be built from the expression directly without needing a fully qualified class name:
[source,xml]
----
<int-twitter:outbound-channel-adapter
twitter-template="twitterTemplate"
channel="twitterChannel"
tweet-data-expression="new TweetData(payload).withMedia(headers.media).displayCoordinates(true)/>
----
This allows, for example, attaching an image to the tweet.
[[outbound-twitter-direct]]
==== Twitter Outbound Direct Message Channel Adapter
This adapter allows you to send Direct Twitter Messages (i.e., @user) by simply sending a Message to the channel identified by the `channel` attribute.
[source,xml]
----
<int-twitter:dm-outbound-channel-adapter
twitter-template="twitterTemplate"
channel="twitterChannel"/>
----
The only extra configuration that is required for this adapter is the `twitter-template` reference.
When it comes to Twitter Direct Messages, you must specify who you are sending the message to - the _target userid_.
The Twitter Outbound Direct Message Channel Adapter will look for a target userid in the Message headers under the name `twitter_dmTargetUserId` which is also identified by the following constant: `TwitterHeaders.DM_TARGET_USER_ID`.
So when creating a Message all you need to do is add a value for that header.
[source,java]
----
Message message = MessageBuilder.withPayload("hello")
.setHeader(TwitterHeaders.DM_TARGET_USER_ID, "z_oleg").build();
----
The above approach works well if you are creating the Message programmatically.
However it's more common to provide the header value within a messaging flow.
The value can be provided by an upstream <header-enricher>.
[source,xml]
----
<int:header-enricher input-channel="in" output-channel="out">
<int:header name="twitter_dmTargetUserId" value="z_oleg"/>
</int:header-enricher>
----
It's quite common that the value must be determined dynamically.
For those cases you can take advantage of SpEL support within the <header-enricher>.
[source,xml]
----
<int:header-enricher input-channel="in" output-channel="out">
<int:header name="twitter_dmTargetUserId"
expression="@twitterIdService.lookup(headers.username)"/>
</int:header-enricher>
----
IMPORTANT: Twitter does not allow you to post duplicate Messages.
This is a common problem during testing when the same code works the first time but does not work the second time.
So, make sure to change the content of the Message each time.
Another thing that works well for testing is to append a timestamp to the end of each message.
[[twitter-sog]]
=== Twitter Search Outbound Gateway
In Spring Integration, an outbound gateway is used for two-way request/response communication with an external service.
The Twitter Search Outbound Gateway allows you to issue dynamic twitter searches.
The reply message payload is a collection of `Tweet` objects.
If the search returns no results, the payload is an empty collection.
You can limit the number of tweets and you can page through a larger set of tweets by making multiple calls.
To facilitate this, search reply messages contain a header `twitter_searchMetadata` with its value being a `SearchMetadata` object.
For more information on the `Tweet`, `SearchParameters` and `SearchMetadata` classes, refer to the http://projects.spring.io/spring-social-twitter/[Spring Social Twitter] documentation.
*Configuring the Outbound Gateway*
[source,xml]
----
<int-twitter:search-outbound-gateway id="twitter"
request-channel="in" <1>
twitter-template="twitterTemplate" <2>
search-args-expression="payload" <3>
reply-channel="out" <4>
reply-timeout="123" <5>
order="1" <6>
auto-startup="false" <7>
phase="100" /> <8>
----
<1> The channel used to send search requests to this gateway.
<2> A reference to a `TwitterTemplate` with authentication configuration.
<3> A SpEL expression that evaluates to argument(s) for the search.
Default: *"payload"* - in which case the payload can be a `String` (e.g "#springintegration") and the gateway limits the query to 20 tweets, or the payload can be a `SearchParameters` object. +
The expression can also be specified as a http://docs.spring.io/spring/docs/current/spring-framework-reference/html/expressions.html#expressions-inline-lists[SpEL List].
The first element (String) is the query, the remaining elements (Numbers) are `pageSize, sinceId, maxId` respectively - refer to the Spring Social Twitter documentation for more information about these parameters.
When specifying a `SearchParameters` object directly in the SpEL expression, you do not have to fully qualify the class name.
Some examples: +
`new SearchParameters(payload).count(5).sinceId(headers.sinceId)` +
`{payload, 30}` +
`{payload, headers.pageSize, headers.sinceId, headers.maxId}`
<4> The channel to which to send the reply; if omitted, the `replyChannel` header is used.
<5> The timeout when sending the reply message to the reply channel; only applies if the reply channel can block, for example a bounded queue channel that is full.
<6> When subscribed to a publish/subscribe channel, the order in which this endpoint will be invoked.
<7> `SmartLifecycle` method.
<8> `SmartLifecycle` method.

408
src/reference/asciidoc/web-sockets.adoc Normal file
View File

@@ -0,0 +1,408 @@
[[web-sockets]]
== WebSockets Support
[[web-socket-introduction]]
=== Introduction
Starting with _version 4.1_ Spring Integration has introduced _WebSocket_ support.
It is based on architecture, infrastructure and API from the Spring Framework's _web-socket_ module.
Therefore, many of Spring WebSocket's components (e.g.
`SubProtocolHandler` or `WebSocketClient`) and configuration options (e.g.
`@EnableWebSocketMessageBroker`) can be reused within Spring Integration.
For more information, please, refer to thehttp://docs.spring.io/spring/docs/current/spring-framework-reference/html/#websocket[Spring Framework WebSocket Support] chapter in the Spring Framework reference manual.
NOTE: Since the Spring Framework WebSocket infrastructure is based on the _Spring Messaging_ foundation and provides a basic Messaging framework based on the same `MessageChannel` s, `MessageHandler` s that Spring Integration uses, and some POJO-method annotation mappings, Spring Integration can be directly involved in a WebSocket flow, even without WebSocket adapters.
For this purpose you can simply configure a Spring Integration `@MessagingGateway` with appropriate annotations:
[source,java]
----
@MessagingGateway
@Controller
public interface WebSocketGateway {
@MessageMapping("/greeting")
@SendToUser("/queue/answer")
@Gateway(requestChannel = "greetingChannel")
String greeting(String payload);
}
----
[[web-socket-overview]]
=== Overview
Since the WebSocket protocol is _streaming_ by definition and we can _send_ and _receive_ messages to/from a WebSocket at the same time, we can simply deal with an appropriate `WebSocketSession`, regardless of being on the client or server side.
To encapsulate the connection management and `WebSocketSession` registry, the `IntegrationWebSocketContainer` is provided with `ClientWebSocketContainer` and `ServerWebSocketContainer` implementations.
Thanks to the https://www.jcp.org/en/jsr/detail?id=356[WebSocket API] and its implementation in the Spring Framework, with many extensions, the same classes are used on the server side as well as the client side (from a Java perspective, of course).
Hence most connection and `WebSocketSession` registry options are the same on both sides.
That allows us to reuse many configuration items and infrastructure hooks to build WebSocket applications on the server side as well as on the client side:
[source,java]
----
//Client side
@Bean
public WebSocketClient webSocketClient() {
return new SockJsClient(Collections.<Transport>singletonList(new WebSocketTransport(new JettyWebSocketClient())));
}
@Bean
public IntegrationWebSocketContainer clientWebSocketContainer() {
return new ClientWebSocketContainer(webSocketClient(), "ws://my.server.com/endpoint");
}
//Server side
@Bean
public IntegrationWebSocketContainer serverWebSocketContainer() {
return new ServerWebSocketContainer("/endpoint").withSockJs();
}
----
The `IntegrationWebSocketContainer` is designed to achieve _bidirectional_ messaging and can be shared between Inbound and Outbound Channel Adapters (see below), can be referenced only from one of them (when using one-way - sending or receiving - WebSocket messaging).
It can be used without any Channel Adapter, but in this case, `IntegrationWebSocketContainer` only plays a role as the `WebSocketSession` registry.
NOTE: The `ServerWebSocketContainer` implements `WebSocketConfigurer` to register an internal `IntegrationWebSocketContainer.IntegrationWebSocketHandler` as an `Endpoint` under the provided `paths` and other server WebSocket options (such as `HandshakeHandler` or `SockJS fallback`) within the `ServletWebSocketHandlerRegistry` for the target vendor WebSocket Container.
This registration is achieved with an infrastructural `WebSocketIntegrationConfigurationInitializer` component, which does the same as the `@EnableWebSocket` annotation.
This means that using just `@EnableIntegration` (or any Spring Integration Namespace in the application context) you can omit the `@EnableWebSocket` declaration, because all WebSocket Endpoints are detected by the Spring Integration infrastructure.
[[web-socket-inbound-adapter]]
=== WebSocket Inbound Channel Adapter
The `WebSocketInboundChannelAdapter` implements the receiving part of `WebSocketSession` interaction.
It must be supplied with a `IntegrationWebSocketContainer`, and the adapter registers itself as a `WebSocketListener` to handle incoming messages and `WebSocketSession` events.
NOTE: Only one `WebSocketListener` can be registered in the `IntegrationWebSocketContainer`.
For WebSocket _sub-protocol_s, the `WebSocketInboundChannelAdapter` can be configured with `SubProtocolHandlerRegistry` as the second constructor argument.
The adapter delegates to the `SubProtocolHandlerRegistry` to determine the appropriate `SubProtocolHandler` for the accepted `WebSocketSession` and to convert `WebSocketMessage` to a `Message` according to the sub-protocol implementation.
NOTE: By default, the `WebSocketInboundChannelAdapter` relies just only on the raw `PassThruSubProtocolHandler` implementation, which simply converts the `WebSocketMessage` to a `Message`.
The `WebSocketInboundChannelAdapter` accepts and sends to the underlying integration flow only `Message` s with `SimpMessageType.MESSAGE` or an empty `simpMessageType` header.
All other `Message` types are handled through the `ApplicationEvent` s emitted from a `SubProtocolHandler` implementation (e.g.
`StompSubProtocolHandler`).
On the server side `WebSocketInboundChannelAdapter` can be configured with the `useBroker = true` option, if the `@EnableWebSocketMessageBroker` configuration is present.
In this case all `non-MESSAGE` `Message` types are delegated to the provided `AbstractBrokerMessageHandler`.
In addition, if the Broker Relay is configured with destination prefixes, those Messages, which match to the Broker destinations, are routed to the `AbstractBrokerMessageHandler`, instead of to the `outputChannel` of the `WebSocketInboundChannelAdapter`.
If `useBroker = false` and received message is of `SimpMessageType.CONNECT` type, the `WebSocketInboundChannelAdapter` sends `SimpMessageType.CONNECT_ACK` message to the `WebSocketSession` immediately without sending it to the channel.
NOTE: Spring's WebSocket Support allows the configuration of only one Broker Relay, hence we don't require an `AbstractBrokerMessageHandler` reference, it is detected in the Application Context.
For more configuration option see <<web-sockets-namespace>>.
[[web-socket-outbound-adapter]]
=== WebSocket Outbound Channel Adapter
The `WebSocketOutboundChannelAdapter` accepts Spring Integration messages from its `MessageChannel`, determines the `WebSocketSession` `id` from the `MessageHeaders`, retrieves the `WebSocketSession` from the provided `IntegrationWebSocketContainer` and delegates the conversion and sending `WebSocketMessage` work to the appropriate `SubProtocolHandler` from the provided `SubProtocolHandlerRegistry`.
On the client side, the `WebSocketSession` `id` message header isn't required, because `ClientWebSocketContainer` deals only with a single connection and its `WebSocketSession` respectively.
To use the STOMP sub-protocol, this adapter should be configured with a `StompSubProtocolHandler`.
Then you can send any STOMP message type to this adapter, using `StompHeaderAccessor.create(StompCommand...)` and a `MessageBuilder`, or just using a `HeaderEnricher` (see <<header-enricher>>).
For more configuration option see below.
[[web-sockets-namespace]]
=== WebSockets Namespace Support
Spring Integration _WebSocket_ namespace includes several components described below.
To include it in your configuration, simply provide the following namespace declaration in your application context configuration file:
[source,xml]
----
<?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:int="http://www.springframework.org/schema/integration"
xmlns:int-websocket="http://www.springframework.org/schema/integration/websocket"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration.xsd
http://www.springframework.org/schema/integration/websocket
http://www.springframework.org/schema/integration/websocket/spring-integration-websocket.xsd">
...
</beans>
----
*<int-websocket:client-container>*
[source,xml]
----
<int-websocket:client-container
id="" <1>
client="" <2>
uri="" <3>
uri-variables="" <4>
origin="" <5>
send-time-limit="" <6>
send-buffer-size-limit="" <7>
auto-startup="" <8>
phase=""> <9>
<int-websocket:http-headers>
<entry key="" value=""/>
</int-websocket:http-headers> <10>
</int-websocket:client-container>
----
<1> The component bean name.
<2> The `WebSocketClient` bean reference.
<3> The `uri` or `uriTemplate` to the target WebSocket service.
If it is used as a `uriTemplate` with URI variable placeholders, the `uri-variables` attribute is required.
<4> Comma-separated values for the URI variable placeholders within the `uri` attribute value.
The values are replaced into the placeholders according to the order in the `uri`.
See `UriComponents.expand(Object...
uriVariableValues)`.
<5> The `Origin` Handshake HTTP header value.
<6> The WebSocket session 'send' timeout limit.
Defaults to `10000`.
<7> The WebSocket session 'send' message size limit.
Defaults to `524288`.
<8> Boolean value indicating whether this endpoint should start automatically.
Defaults to `false`, assuming that this container will be started from the <<web-socket-inbound-adapter>>.
<9> The lifecycle phase within which this endpoint should start and stop.
The lower the value the earlier this endpoint will start and the later it will stop.
The default is `Integer.MAX_VALUE`.
Values can be negative.
See `SmartLifeCycle`.
<10> A `Map` of `HttpHeaders` to be used with the Handshake request.
*<int-websocket:server-container>*
[source,xml]
----
<int-websocket:server-container
id="" <1>
path="" <2>
handshake-handler="" <3>
handshake-interceptors="" <4>
send-time-limit="" <5>
send-buffer-size-limit=""> <6>
<int-websocket:sockjs
client-library-url="" <7>
stream-bytes-limit="" <8>
session-cookie-needed="" <9>
heartbeat-time="" <10>
disconnect-delay="" <11>
message-cache-size="" <12>
websocket-enabled="" <13>
scheduler="" <14>
message-codec="" <15>
transport-handlers="" /> <16>
</int-websocket:server-container>
----
<1> The component bean name.
<2> A path (or comma-separated paths) that maps a particular request to a `WebSocketHandler`.
Exact path mapping URIs (such as `"/myPath"`) are supported as well as ant-style path patterns (such as `/myPath/**`).
<3> The `HandshakeHandler` bean reference.
Default to `DefaultHandshakeHandler`.
<4> List of `HandshakeInterceptor` bean references.
<5> See the same option on the `<int-websocket:client-container>`.
<6> See the same option on the `<int-websocket:client-container>`.
<7> Transports with no native cross-domain communication (e.g.
"eventsource", "htmlfile") must get a simple page from the "foreign" domain in an invisible iframe so that code in the iframe can run from a domain local to the SockJS server.
Since the iframe needs to load the SockJS javascript client library, this property allows specifying where to load it from.
By default this is set to point to `https://d1fxtkz8shb9d2.cloudfront.net/sockjs-0.3.4.min.js`.
However it can also be set to point to a URL served by the application.
Note that it's possible to specify a relative URL in which case the URL must be relative to the iframe URL.
For example assuming a SockJS endpoint mapped to "/sockjs", and resulting iframe URL "/sockjs/iframe.html", then the The relative URL must start with "../../" to traverse up to the location above the SockJS mapping.
In case of a prefix-based Servlet mapping one more traversal may be needed.
<8> Minimum number of bytes that can be send over a single HTTP streaming request before it will be closed.
Defaults to `128K` (i.e.
128*1024 bytes).
<9> The "cookie_needed" value in the response from the SockJs `"/info"` endpoint.
This property indicates whether the use of a JSESSIONID cookie is required for the application to function correctly, e.g.
for load balancing or in Java Servlet containers for the use of an HTTP session.
<10> The amount of time in milliseconds when the server has not sent any messages and after which the server should send a heartbeat frame to the client in order to keep the connection from breaking.
The default value is `25,000` (25 seconds).
<11> The amount of time in milliseconds before a client is considered disconnected after not having a receiving connection, i.e.
an active connection over which the server can send data to the client.
The default value is `5000`.
<12> The number of server-to-client messages that a session can cache while waiting for the next HTTP polling request from the client.
The default size is `100`.
<13> Some load balancers don't support websockets.
Set this option to `false` to disable the WebSocket transport on the server side.
The default value is `true`.
<14> The `TaskScheduler` bean reference; a new `ThreadPoolTaskScheduler` instance will be created if no value is provided.
This scheduler instance will be used for scheduling heart-beat messages.
<15> The `SockJsMessageCodec` bean reference to use for encoding and decoding SockJS messages.
By default `Jackson2SockJsMessageCodec` is used requiring the Jackson library to be present on the classpath.
<16> List of `TransportHandler` bean references.
*<int-websocket:outbound-channel-adapter>*
[source,xml]
----
<int-websocket:outbound-channel-adapter
id="" <1>
channel="" <2>
container="" <3>
default-protocol-handler="" <4>
protocol-handlers="" <5>
message-converters="" <6>
merge-with-default-converters="" <7>
auto-startup="" <8>
phase=""/> <9>
----
<1> The component bean name.
If the `channel` attribute isn't provided, a `DirectChannel` is created and registered with the application context with this `id` attribute as the bean name.
In this case, the endpoint is registered with the bean name `id + '.adapter'`.
And the `MessageHandler` is registered with the bean alias `id +'.adapter'`.
<2> Identifies the channel attached to this adapter.
<3> The reference to the `IntegrationWebSocketContainer` bean, which encapsulates the low-level connection and WebSocketSession handling operations.
Required.
<4> Optional reference to a `SubProtocolHandler` instance.
It is used when the client did not request a sub-protocol or it is a single protocol-handler.
If this reference or `protocol-handlers` list aren't provided the `PassThruSubProtocolHandler` is used by default.
<5> List of `SubProtocolHandler` bean references for this Channel Adapter.
If only a single bean reference is provided and a `default-protocol-handler` isn't provided, that single `SubProtocolHandler` will be used as the `default-protocol-handler`.
If this attribute or `default-protocol-handler` aren't provided, the `PassThruSubProtocolHandler` is used by default.
<6> List of `MessageConverter` bean references for this Channel Adapter.
<7> Flag to indicate if the default converters should be registered after any custom converters.
This flag is used only if `message-converters` are provided, otherwise all default converters will be registered.
Defaults to `false`.
The default converters are (in the order): `StringMessageConverter`, `ByteArrayMessageConverter` and `MappingJackson2MessageConverter` if the Jackson library is present on the classpath.
<8> Boolean value indicating whether this endpoint should start automatically.
Default to `true`.
<9> The lifecycle phase within which this endpoint should start and stop.
The lower the value the earlier this endpoint will start and the later it will stop.
The default is `Integer.MIN_VALUE`.
Values can be negative.
See `SmartLifeCycle`.
*<int-websocket:inbound-channel-adapter>*
[source,xml]
----
<int-websocket:inbound-channel-adapter
id="" <1>
channel="" <2>
error-channel="" <3>
container="" <4>
default-protocol-handler="" <5>
protocol-handlers="" <6>
message-converters="" <7>
merge-with-default-converters="" <8>
send-timeout="" <9>
payload-type="" <10>
use-broker="" <11>
auto-startup="" <12>
phase=""/> <13>
----
<1> The component bean name.
If the `channel` attribute isn't provided, a `DirectChannel` is created and registered with the application context with this `id` attribute as the bean name.
In this case, the endpoint is registered with the bean name `id + '.adapter'`.
<2> Identifies the channel attached to this adapter.
<3> The `MessageChannel` bean reference to which the `ErrorMessages` should be sent.
<4> See the same option on the `<int-websocket:outbound-channel-adapter>`.
<5> See the same option on the `<int-websocket:outbound-channel-adapter>`.
<6> See the same option on the `<int-websocket:outbound-channel-adapter>`.
<7> See the same option on the `<int-websocket:outbound-channel-adapter>`.
<8> See the same option on the `<int-websocket:outbound-channel-adapter>`.
<9> Maximum amount of time in milliseconds to wait when sending a message to the channel if the channel may block.
For example, a `QueueChannel` can block until space is available if its maximum capacity has been reached.
<10> Fully qualified name of the java type for the target `payload` to convert from the incoming `WebSocketMessage`.
Default to `String`.
<11> Flag to indicate if this adapter will send `non-MESSAGE` `WebSocketMessage` s and messages with broker destinations to the `AbstractBrokerMessageHandler` from the application context.
The `Broker Relay` configuration is required when this attribute is `true`.
This attribute is used only on the server side.
On the client side, it is ignored.
Defaults to `false`.
<12> See the same option on the `<int-websocket:outbound-channel-adapter>`.
<13> See the same option on the `<int-websocket:outbound-channel-adapter>`.

89
src/reference/asciidoc/whats-new.adoc Normal file
View File

@@ -0,0 +1,89 @@
[[whats-new]]
== What's new in Spring Integration 4.2?
This chapter provides an overview of the new features and improvements that have been introduced with Spring Integration 4.1.
If you are interested in more details, please see the Issue Tracker tickets that were resolved as part of the 4.1 development process.
[[x4.2-new-components]]
=== New Components
[[x4.2-JMX]]
==== Major JMX Rework
A new `MetricsFactory` strategy interface has been introduced.
This, together with other changes in the JMX infrastructure provides much more control over JMX configuration and runtime performance.
However, this has some important implications for (some) user environments.
For complete details, see <<jmx-42-improvements>>.
[[x4.2-general]]
=== General Changes
[[x4.2-wire-tap]]
==== Wire Tap
As an alternative to the existing `selector` attribute, the `<wire-tap/>` now supports the `selector-expression` attribute.
[[x4.2-file-outbound-channel-adapter]]
==== File Outbound Channel Adapter
The `<int-file:outbound-channel-adapter>` and `<int-file:outbound-gateway>` now support an `append-new-line` attribute.
If set to `true`, a new line is appended to the file after a message is written.
The default attribute value is `false`.
[[x4.2-class-package-change]]
==== Class Package Change
The `ScatterGatherHandler` class has been moved from the `org.springframework.integration.handler` to the `org.springframework.integration.scattergather`.
[[x4.2-tcp-serializers]]
==== TCP Serializers
The TCP `Serializers` no longer `flush()` the `OutputStream`; this is now done by the `TcpNxxConnection` classes.
If you are using the serializers directly within user code, you may have to `flush()` the `OutputStream`.
[[x4.2-tcp-server-exceptions]]
==== Server Socket Exceptions
`TcpConnectionServerExceptionEvent` s are now published whenever an unexpected exception occurs on a TCP server socket (also added to 4.1.3, 4.0.7).
See <<tcp-events>> for more information.
[[x4.2-tcp-gw-rto]]
==== TCP Gateway Remote Timeout
The `TcpOutboundGateway` now supports `remote-timeout-expression` as an alternative to the existing `remote-timeout` attribute.
This allows setting the timeout based on each message.
Also, the `remote-timeout` no longer defaults to the same value as `reply-timeout` which has a completely different meaning.
See <<tcp-ob-gateway-attributes>> for more information.
[[x4.2-inbound-channel-adapter-annotation]]
==== @InboundChannelAdapter
Previously, the `@Poller` on an inbound channel adapter defaulted the `maxMessagesPerPoll` attribute to `-1` (infinity).
This was inconsistent with the XML configuration of `<inbound-channel-adapter/>` s, which defaults to 1.
The annotation now defaults this attribute to 1.
[[x4.2-api-changes]]
==== API Changes
`o.s.integtation.util.FunctionIterator` now requires a `o.s.integration.util.Function` instead of a `reactor.function.Function`.
This was done to remove an unnecessary hard dependency on Reactor.
Any uses of this iterator will need to change the import.
Of course, Reactor is still supported for functionality such as the `Promise` gateway; the dependency was removed for those users who don't need it.
[[x4.2-jms-changes]]
==== JMS Changes
The `error-channel` now is used for the conversion errors, which have caused a transaction rollback and message redelivery previously.
See <<jms-message-driven-channel-adapter>> for more information.
[[x4.2-conditional-pollers]]
==== Conditional Pollers
Much more flexibility is now provided for dynamic polling.
See <<conditional-pollers>> for more information.

149
src/reference/asciidoc/ws.adoc Normal file
View File

@@ -0,0 +1,149 @@
[[ws]]
== Web Services Support
[[webservices-outbound]]
=== Outbound Web Service Gateways
To invoke a Web Service upon sending a message to a channel, there are two options - both of which build upon the http://static.springsource.org/spring-ws/site/[Spring Web Services] project: `SimpleWebServiceOutboundGateway` and `MarshallingWebServiceOutboundGateway`.
The former will accept either a `String` or `javax.xml.transform.Source` as the message payload.
The latter provides support for any implementation of the `Marshaller` and `Unmarshaller` interfaces.
Both require a Spring Web Services `DestinationProvider` for determining the URI of the Web Service to be called.
[source,java]
----
simpleGateway = new SimpleWebServiceOutboundGateway(destinationProvider);
marshallingGateway = new MarshallingWebServiceOutboundGateway(destinationProvider, marshaller);
----
NOTE: When using the namespace support described below, you will only need to set a URI.
Internally, the parser will configure a fixed URI DestinationProvider implementation.
If you do need dynamic resolution of the URI at runtime, however, then the DestinationProvider can provide such behavior as looking up the URI from a registry.
See the Spring Web Serviceshttp://static.springsource.org/spring-ws/site/apidocs/org/springframework/ws/client/support/destination/DestinationProvider.html[DestinationProvider] JavaDoc for more information about this strategy.
For more detail on the inner workings, see the Spring Web Services reference guide's chapter covering http://static.springframework.org/spring-ws/site/reference/html/client.html[client access] as well as the chapter covering http://static.springframework.org/spring-ws/site/reference/html/oxm.html[Object/XML mapping].
[[webservices-inbound]]
=== Inbound Web Service Gateways
To send a message to a channel upon receiving a Web Service invocation, there are two options again: `SimpleWebServiceInboundGateway` and `MarshallingWebServiceInboundGateway`.
The former will extract a `javax.xml.transform.Source` from the `WebServiceMessage` and set it as the message payload.
The latter provides support for implementation of the `Marshaller` and `Unmarshaller` interfaces.
If the incoming web service message is a SOAP message the SOAP Action header will be added to the headers of the`Message` that is forwarded onto the request channel.
[source,java]
----
simpleGateway = new SimpleWebServiceInboundGateway();
simpleGateway.setRequestChannel(forwardOntoThisChannel);
simpleGateway.setReplyChannel(listenForResponseHere); //Optional
marshallingGateway = new MarshallingWebServiceInboundGateway(marshaller);
//set request and optionally reply channel
----
Both gateways implement the Spring Web Services `MessageEndpoint` interface, so they can be configured with a `MessageDispatcherServlet` as per standard Spring Web Services configuration.
For more detail on how to use these components, see the Spring Web Services reference guide's chapter covering http://static.springframework.org/spring-ws/site/reference/html/server.html[creating a Web Service].
The chapter coveringhttp://static.springframework.org/spring-ws/site/reference/html/oxm.html[Object/XML mapping] is also applicable again.
[[webservices-namespace]]
=== Web Service Namespace Support
To configure an outbound Web Service Gateway, use the "outbound-gateway" element from the "ws" namespace:
[source,xml]
----
<int-ws:outbound-gateway id="simpleGateway"
request-channel="inputChannel"
uri="http://example.org"/>
----
NOTE: Notice that this example does not provide a 'reply-channel'.
If the Web Service were to return a non-empty response, the Message containing that response would be sent to the reply channel provided in the request Message's REPLY_CHANNEL header, and if that were not available a channel resolution Exception would be thrown.
If you want to send the reply to another channel instead, then provide a 'reply-channel' attribute on the 'outbound-gateway' element.
TIP: When invoking a Web Service that returns an empty response after using a String payload for the request Message, _no reply Message will be sent by default_.
Therefore you don't need to set a 'reply-channel' or have a REPLY_CHANNEL header in the request Message.
If for any reason you actually _do_ want to receive the empty response as a Message, then provide the 'ignore-empty-responses' attribute with a value of _false_ (this only applies for Strings, because using a Source or Document object simply leads to a NULL response and will therefore_never_ generate a reply Message).
To set up an inbound Web Service Gateway, use the "inbound-gateway":
[source,xml]
----
<int-ws:inbound-gateway id="simpleGateway"
request-channel="inputChannel"/>
----
To use Spring OXM Marshallers and/or Unmarshallers, provide bean references.
For outbound:
[source,xml]
----
<int-ws:outbound-gateway id="marshallingGateway"
request-channel="requestChannel"
uri="http://example.org"
marshaller="someMarshaller"
unmarshaller="someUnmarshaller"/>
----
And for inbound:
[source,xml]
----
<int-ws:inbound-gateway id="marshallingGateway"
request-channel="requestChannel"
marshaller="someMarshaller"
unmarshaller="someUnmarshaller"/>
----
NOTE: Most `Marshaller` implementations also implement the `Unmarshaller` interface.
When using such a `Marshaller`, only the "marshaller" attribute is necessary.
Even when using a `Marshaller`, you may also provide a reference for the "request-callback" on the outbound gateways.
For either outbound gateway type, a "destination-provider" attribute can be specified instead of the "uri" (exactly one of them is required).
You can then reference any Spring Web Services DestinationProvider implementation (e.g.
to lookup the URI at runtime from a registry).
For either outbound gateway type, the "message-factory" attribute can also be configured with a reference to any Spring Web Services `WebServiceMessageFactory` implementation.
For the simple inbound gateway type, the "extract-payload" attribute can be set to false to forward the entire `WebServiceMessage` instead of just its payload as a `Message` to the request channel.
This might be useful, for example, when a custom Transformer works against the `WebServiceMessage` directly.
[[outbound-uri]]
=== Outbound URI Configuration
For all URI-schemes supported by Spring Web Services (http://static.springsource.org/spring-ws/site/reference/html/client.html#client-transports[URIs and Transports]) `<uri-variable/>` substitution is provided:
[source,xml]
----
<ws:outbound-gateway id="gateway" request-channel="input"
uri="http://springsource.org/{foo}-{bar}">
<ws:uri-variable name="foo" expression="payload.substring(1,7)"/>
<ws:uri-variable name="bar" expression="headers.x"/>
</ws:outbound-gateway>
<ws:outbound-gateway request-channel="inputJms"
uri="jms:{destination}?deliveryMode={deliveryMode}&amp;priority={priority}"
message-sender="jmsMessageSender">
<ws:uri-variable name="destination" expression="headers.jmsQueue"/>
<ws:uri-variable name="deliveryMode" expression="headers.deliveryMode"/>
<ws:uri-variable name="priority" expression="headers.jms_priority"/>
</ws:outbound-gateway>
----
If a `DestinationProvider` is supplied, variable substitution is not supported and a configuration error will result if variables are provided.
_Controlling URI Encoding_
By default, the URL string is encoded (see http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/web/util/UriComponentsBuilder.html[UriComponentsBuilder]) to the URI object before sending the request.
In some scenarios with a non-standard URI it is undesirable to perform the encoding.
Since _version 4.1 _ the `<ws:outbound-gateway/>` provides an `encode-uri` attribute.
To disable encoding the URL, this attribute should be set to `false` (by default it is `true`).
If you wish to partially encode some of the URL, this can be achieved using an `expression` within a `<uri-variable/>`:
[source,xml]
----
<ws:outbound-gateway url="http://somehost/%2f/fooApps?bar={param}" encode-uri="false">
<http:uri-variable name="param"
expression="T(org.apache.commons.httpclient.util.URIUtil)
.encodeWithinQuery('Hellow World!')"/>
</ws:outbound-gateway>
----
Note, `encode-uri` is ignored, if `DestinationProvider` is supplied.

1054
src/reference/asciidoc/xml.adoc Normal file
View File

File diff suppressed because it is too large Load Diff

Some files were not shown because too many files have changed in this diff Show More