Spring Integration Reference Manual

Authors

Mark Fisher, Marius Bogoevici, Iwein Fuld, Jonas Partner, Oleg Zhurakousky, Gary Russell, Dave Syer, Josh Long, David Turanski, Gunnar Hillert, Artem Bilan, Amol Nayak

4.3.22.RELEASE

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.


Table of Contents

I. Preface
Requirements
1. Compatible Java Versions
2. Compatible Versions of the Spring Framework
3. Code Conventions
1. Conventions in this Book
II. What’s new?
2. What’s new in Spring Integration 4.3?
2.1. New Components
2.1.1. AMQP Async Outbound Gateway
2.1.2. MessageGroupFactory
2.1.3. PersistentMessageGroup
2.1.4. FTP/SFTP Streaming Inbound Channel Adapters
2.1.5. Stream Transformer
2.1.6. Integration Graph
2.1.7. JDBC Lock Registry
2.1.8. Leader Initiator for Lock Registry
2.2. General Changes
2.2.1. Core Changes
Outbound Gateway within Chain
Async Service Activator
Messaging Annotation Support changes
Lifecycle Role Controller
2.2.2. Mail Changes
Customizable User Flag
Mail Message Mapping
2.2.3. JMS Changes
Header Mapper
Async Gateway
2.2.4. Aggregator Changes
2.2.5. TCP/UDP Changes
Events
Stream Deserializers
TCP Message Mapper
2.2.6. File Changes
Destination Directory Creation
Buffer Size
Appending and Flushing
Preserving Timestamps
Splitter Changes
File Filters
2.2.7. AMQP Changes
Content Type Message Converter
Headers for Delayed Message Handling
AMQP-Backed Channels
2.2.8. Redis Changes
List Push/Pop Direction
Queue Inbound Gateway Default Serializer
2.2.9. HTTP Changes
2.2.10. SFTP Changes
Factory Bean
Inbound Channel Adapter
chmod
2.2.11. FTP Changes
Session Changes
Inbound Channel Adapter
2.2.12. Router Changes
2.2.13. Header Mapping
General
AMQP Header Mapping
2.2.14. Groovy Scripts
2.2.15. @InboundChannelAdapter
2.2.16. XMPP changes
2.2.17. WireTap Late Binding
2.2.18. ChannelMessageStoreQueryProvider
2.2.19. WebSocket Changes
2.2.20. Barrier Changes
2.2.21. AMQP Changes
III. Overview of Spring Integration Framework
3. Spring Integration Overview
3.1. Background
3.2. Goals and Principles
3.3. Main Components
3.3.1. Message
3.3.2. Message Channel
3.3.3. Message Endpoint
3.4. Message Endpoints
3.4.1. Transformer
3.4.2. Filter
3.4.3. Router
3.4.4. Splitter
3.4.5. Aggregator
3.4.6. Service Activator
3.4.7. Channel Adapter
3.5. Configuration and @EnableIntegration
3.6. Programming Considerations
3.7. Considerations When using Packaged (e.g. Shaded) Jars
3.8. Programming Tips and Tricks
IV. Core Messaging
4. Messaging Channels
4.1. Message Channels
4.1.1. The MessageChannel Interface
PollableChannel
SubscribableChannel
4.1.2. Message Channel Implementations
PublishSubscribeChannel
QueueChannel
PriorityChannel
RendezvousChannel
DirectChannel
ExecutorChannel
Scoped Channel
4.1.3. Channel Interceptors
4.1.4. MessagingTemplate
4.1.5. Configuring Message Channels
DirectChannel Configuration
Datatype Channel Configuration
QueueChannel Configuration
PublishSubscribeChannel Configuration
ExecutorChannel
PriorityChannel Configuration
RendezvousChannel Configuration
Scoped Channel Configuration
Channel Interceptor Configuration
Global Channel Interceptor Configuration
Wire Tap
Conditional Wire Taps
Global Wire Tap Configuration
4.1.6. Special Channels
4.2. Poller
4.2.1. Polling Consumer
4.2.2. Pollable Message Source
4.2.3. Conditional Pollers for Message Sources
Background
"Smart" Polling
SimpleActiveIdleMessageSourceAdvice
CompoundTriggerAdvice
4.3. Channel Adapter
4.3.1. Configuring An Inbound Channel Adapter
4.3.2. Configuring An Outbound Channel Adapter
4.3.3. Channel Adapter Expressions and Scripts
4.4. Messaging Bridge
4.4.1. Introduction
4.4.2. Configuring Bridge
5. Message Construction
5.1. Message
5.1.1. The Message Interface
5.1.2. Message Headers
MessageHeaderAccessor API
Message ID Generation
Read-only Headers
Header Propagation
5.1.3. Message Implementations
5.1.4. The MessageBuilder Helper Class
6. Message Routing
6.1. Routers
6.1.1. Overview
6.1.2. Common Router Parameters
Inside and Outside of a Chain
Top-Level (Outside of a Chain)
6.1.3. Router Implementations
PayloadTypeRouter
HeaderValueRouter
RecipientListRouter
RecipientListRouterManagement
XPath Router
Routing and Error handling
6.1.4. Configuring (Generic) Router
Configuring a Content Based Router with XML
Configuring a Router with Annotations
6.1.5. Dynamic Routers
Manage Router Mappings using the Control Bus
Manage Router Mappings using JMX
Routing Slip
Process Manager Enterprise Integration Pattern
6.2. Filter
6.2.1. Introduction
6.2.2. Configuring Filter
Configuring a Filter with XML
Configuring a Filter with Annotations
6.3. Splitter
6.3.1. Introduction
6.3.2. Programming model
6.3.3. Configuring Splitter
Configuring a Splitter using XML
Configuring a Splitter with Annotations
6.4. Aggregator
6.4.1. Introduction
6.4.2. Functionality
6.4.3. Programming model
AggregatingMessageHandler
ReleaseStrategy
Aggregating Large Groups
CorrelationStrategy
LockRegistry
6.4.4. Configuring an Aggregator
Configuring an Aggregator with XML
Configuring an Aggregator with Annotations
6.4.5. Managing State in an Aggregator: MessageGroupStore
6.5. Resequencer
6.5.1. Introduction
6.5.2. Functionality
6.5.3. Configuring a Resequencer
6.6. Message Handler Chain
6.6.1. Introduction
6.6.2. Configuring a Chain
6.7. Scatter-Gather
6.7.1. Introduction
6.7.2. Functionality
6.7.3. Configuring a Scatter-Gather Endpoint
6.8. Thread Barrier
7. Message Transformation
7.1. Transformer
7.1.1. Introduction
7.1.2. Configuring Transformer
Configuring Transformer with XML
Common Transformers
Configuring a Transformer with Annotations
7.1.3. Header Filter
7.1.4. Codec-Based Transformers
7.2. Content Enricher
7.2.1. Introduction
7.2.2. Header Enricher
Configuring a Header Enricher with Java Configuration
Configuring a Header Enricher with the Java DSL
Header Channel Registry
7.2.3. Payload Enricher
Configuration
Examples
7.3. Claim Check
7.3.1. Introduction
7.3.2. Incoming Claim Check Transformer
7.3.3. Outgoing Claim Check Transformer
7.3.4. A word on Message Store
7.4. Codec
7.4.1. Introduction
7.4.2. EncodingPayloadTransformer
7.4.3. DecodingTransformer
7.4.4. CodecMessageConverter
7.4.5. Kryo
Customizing Kryo
8. Messaging Endpoints
8.1. Message Endpoints
8.1.1. Message Handler
8.1.2. Event Driven Consumer
8.1.3. Polling Consumer
8.1.4. Namespace Support
8.1.5. Change Polling Rate at Runtime
8.1.6. Payload Type Conversion
8.1.7. Asynchronous polling
8.1.8. Endpoint Inner Beans
8.2. Endpoint Roles
8.3. Leadership Event Handling
8.4. Messaging Gateways
8.4.1. Enter the GatewayProxyFactoryBean
8.4.2. Gateway XML Namespace Support
8.4.3. Setting the Default Reply Channel
8.4.4. Gateway Configuration with Annotations and/or XML
8.4.5. Mapping Method Arguments to a Message
8.4.6. @MessagingGateway Annotation
8.4.7. Invoking No-Argument Methods
8.4.8. Error Handling
8.4.9. Asynchronous Gateway
Introduction
ListenableFuture
AsyncTaskExecutor
CompletableFuture
Reactor Promise
8.4.10. Gateway behavior when no response arrives
8.5. Service Activator
8.5.1. Introduction
8.5.2. Configuring Service Activator
8.5.3. Asynchronous Service Activator
8.6. Delayer
8.6.1. Introduction
8.6.2. Configuring Delayer
8.6.3. Delayer and Message Store
8.7. Scripting support
8.7.1. Script configuration
8.8. Groovy support
8.8.1. Groovy configuration
8.8.2. Control Bus
8.9. Adding Behavior to Endpoints
8.9.1. Introduction
8.9.2. Provided Advice Classes
Retry Advice
Circuit Breaker Advice
Expression Evaluating Advice
8.9.3. Custom Advice Classes
8.9.4. Other Advice Chain Elements
8.9.5. Handle Message Advice
8.9.6. Advising Filters
8.9.7. Advising Endpoints Using Annotations
8.9.8. Ordering Advices within an Advice Chain
8.9.9. Advised Handler Properties
8.9.10. Idempotent Receiver Enterprise Integration Pattern
8.10. Logging Channel Adapter
8.10.1. Configuring with Java Configuration
9. System Management
9.1. Metrics and Management
9.1.1. Configuring Metrics Capture
9.1.2. MessageChannel Metric Features
9.1.3. MessageHandler Metric Features
9.1.4. Time-Based Average Estimates
9.1.5. Metrics Factory
9.2. JMX Support
9.2.1. Notification Listening Channel Adapter
9.2.2. Notification Publishing Channel Adapter
9.2.3. Attribute Polling Channel Adapter
9.2.4. Tree Polling Channel Adapter
9.2.5. Operation Invoking Channel Adapter
9.2.6. Operation Invoking Outbound Gateway
9.2.7. MBean Exporter
MBean ObjectNames
JMX Improvements
Orderly Shutdown Managed Operation
9.3. Message History
9.3.1. Message History Configuration
9.4. Message Store
9.4.1. MessageGroupFactory
9.4.2. Persistence MessageGroupStore and Lazy-Load
9.5. Metadata Store
9.5.1. Idempotent Receiver and Metadata Store
9.5.2. MetadataStoreListener
9.6. Control Bus
9.7. Orderly Shutdown
9.8. Integration Graph
9.8.1. Graph Runtime Model
9.9. Integration Graph Controller
V. Integration Endpoints
10. Endpoint Quick Reference Table
11. AMQP Support
11.1. Introduction
11.2. Inbound Channel Adapter
11.2.1. Configuring with Java Configuration
11.2.2. Configuring with the Java DSL
11.3. Inbound Gateway
11.3.1. Configuring with Java Configuration
11.3.2. Configuring with the Java DSL
11.4. Inbound Endpoint Acknowledge Mode
11.5. Outbound Channel Adapter
11.5.1. Configuring with Java Configuration
11.5.2. Configuring with the Java DSL
11.6. Outbound Gateway
11.6.1. Configuring with Java Configuration
11.6.2. Configuring with the Java DSL
11.7. Async Outbound Gateway
11.7.1. Configuring with Java Configuration
11.7.2. Configuring with the Java DSL
11.8. Outbound Message Conversion
11.9. Outbound User Id
11.10. Delayed Message Exchange
11.11. AMQP Backed Message Channels
11.11.1. Configuring with Java Configuration
11.11.2. Configuring with the Java DSL
11.12. AMQP Message Headers
11.13. AMQP Samples
12. Spring ApplicationEvent Support
12.1. Receiving Spring Application Events
12.2. Sending Spring Application Events
13. Feed Adapter
13.1. Introduction
13.2. Feed Inbound Channel Adapter
14. File Support
14.1. Introduction
14.2. Reading Files
14.2.1. Namespace Support
14.2.2. WatchServiceDirectoryScanner
14.2.3. Limiting Memory Consumption
14.2.4. Configuring with Java Configuration
14.2.5. Configuring with the Java DSL
14.2.6. 'Tail’ing Files
14.3. Writing files
14.3.1. Generating File Names
14.3.2. Specifying the Output Directory
14.3.3. Dealing with Existing Destination Files
14.3.4. Flushing Files When using APPEND_NO_FLUSH
14.3.5. File Timestamps
14.3.6. File Outbound Channel Adapter
14.3.7. Outbound Gateway
14.3.8. Configuring with Java Configuration
14.3.9. Configuring with the Java DSL
14.4. File Transformers
14.5. File Splitter
15. FTP/FTPS Adapters
15.1. Introduction
15.2. FTP Session Factory
15.3. Delegating Session Factory
15.4. FTP Inbound Channel Adapter
15.4.1. Recovering from Failures
15.4.2. Configuring with Java Configuration
15.4.3. Configuring with the Java DSL
15.5. FTP Streaming Inbound Channel Adapter
15.5.1. Configuring with Java Configuration
15.6. FTP Outbound Channel Adapter
15.6.1. Configuring with Java Configuration
15.6.2. Configuring with the Java DSL
15.7. FTP Outbound Gateway
15.7.1. Configuring with Java Configuration
15.7.2. Configuring with the Java DSL
15.7.3. Outbound Gateway Partial Success (mget and mput)
15.8. FTP Session Caching
15.9. RemoteFileTemplate
15.10. MessageSessionCallback
16. GemFire Support
16.1. Introduction
16.2. Inbound Channel Adapter
16.3. Continuous Query Inbound Channel Adapter
16.4. Outbound Channel Adapter
16.5. Gemfire Message Store
16.6. Gemfire Lock Registry
16.7. Gemfire Metadata Store
17. HTTP Support
17.1. Introduction
17.2. Http Inbound Components
17.3. Http Outbound Components
17.4. HTTP Namespace Support
17.4.1. Introduction
17.4.2. Inbound
17.4.3. Request Mapping Support
17.4.4. Cross-Origin Resource Sharing (CORS) Support
17.4.5. Response StatusCode
17.4.6. URI Template Variables and Expressions
17.4.7. Outbound
17.4.8. Mapping URI Variables
17.4.9. Controlling URI Encoding
17.5. Timeout Handling
17.6. HTTP Proxy configuration
17.7. HTTP Header Mappings
17.8. Integration Graph Controller
17.9. HTTP Samples
17.9.1. Multipart HTTP request - RestTemplate (client) and Http Inbound Gateway (server)
18. JDBC Support
18.1. Inbound Channel Adapter
18.1.1. Polling and Transactions
18.1.2. Max-rows-per-poll versus Max-messages-per-poll
18.2. Outbound Channel Adapter
18.3. Outbound Gateway
18.4. JDBC Message Store
18.4.1. The Generic JDBC Message Store
18.4.2. Backing Message Channels
18.4.3. Initializing the Database
18.4.4. Partitioning a Message Store
18.5. Stored Procedures
18.5.1. Supported Databases
18.5.2. Configuration
18.5.3. Common Configuration Attributes
18.5.4. Common Configuration Sub-Elements
18.5.5. Defining Parameter Sources
18.5.6. Stored Procedure Inbound Channel Adapter
18.5.7. Stored Procedure Outbound Channel Adapter
18.5.8. Stored Procedure Outbound Gateway
18.5.9. Examples
18.6. JDBC Lock Registry
19. JPA Support
19.1. Supported Persistence Providers
19.2. Java Implementation
19.3. Namespace Support
19.3.1. Common XML Namespace Configuration Attributes
19.3.2. Providing JPA Query Parameters
19.3.3. Transaction Handling
19.4. Inbound Channel Adapter
19.4.1. Configuration Parameter Reference
19.5. Outbound Channel Adapter
19.5.1. Using an Entity Class
19.5.2. Using JPA Query Language (JPA QL)
19.5.3. Using Native Queries
19.5.4. Using Named Queries
19.5.5. Configuration Parameter Reference
19.6. Outbound Gateways
19.6.1. Common Configuration Parameters
19.6.2. Updating Outbound Gateway
19.6.3. Retrieving Outbound Gateway
19.6.4. JPA Outbound Gateway Samples
20. JMS Support
20.1. Inbound Channel Adapter
20.1.1. Transactions
20.2. Message-Driven Channel Adapter
20.2.1. Inbound Conversion Errors
20.3. Outbound Channel Adapter
20.3.1. Transactions
20.4. Inbound Gateway
20.5. Outbound Gateway
20.5.1. Gateway Reply Correlation
20.5.2. Async Gateway
20.5.3. Attribute Reference
20.6. Mapping Message Headers to/from JMS Message
20.7. Message Conversion, Marshalling and Unmarshalling
20.8. JMS Backed Message Channels
20.9. Using JMS Message Selectors
20.10. JMS Samples
21. Mail Support
21.1. Mail-Sending Channel Adapter
21.2. Mail-Receiving Channel Adapter
21.3. Inbound Mail Message Mapping
21.4. Mail Namespace Support
21.5. Marking IMAP Messages When \Recent is Not Supported
21.6. Email Message Filtering
21.7. Transaction Synchronization
22. MongoDb Support
22.1. Introduction
22.2. Connecting to MongoDb
22.3. MongoDB Message Store
22.3.1. MongoDB Channel Message Store
22.3.2. MongoDB Metadata Store
22.4. MongoDB Inbound Channel Adapter
22.5. MongoDB Outbound Channel Adapter
23. MQTT Support
23.1. Introduction
23.2. Inbound (message-driven) Channel Adapter
23.2.1. Adding/Removing Topics at Runtime
23.2.2. Configuring with Java Configuration
23.3. Outbound Channel Adapter
23.3.1. Configuring with Java Configuration
24. Redis Support
24.1. Introduction
24.2. Connecting to Redis
24.3. Messaging with Redis
24.3.1. Redis Publish/Subscribe channel
24.3.2. Redis Inbound Channel Adapter
24.3.3. Redis Outbound Channel Adapter
24.3.4. Redis Queue Inbound Channel Adapter
24.3.5. Redis Queue Outbound Channel Adapter
24.3.6. Redis Application Events
24.4. Redis Message Store
24.4.1. Redis Channel Message Stores
24.5. Redis Metadata Store
24.6. RedisStore Inbound Channel Adapter
24.7. RedisStore Outbound Channel Adapter
24.8. Redis Outbound Command Gateway
24.9. Redis Queue Outbound Gateway
24.10. Redis Queue Inbound Gateway
24.11. Redis Lock Registry
25. Resource Support
25.1. Introduction
25.2. Resource Inbound Channel Adapter
26. RMI Support
26.1. Introduction
26.2. Outbound RMI
26.3. Inbound RMI
26.4. RMI namespace support
26.5. Configuring with Java Configuration
27. SFTP Adapters
27.1. Introduction
27.2. SFTP Session Factory
27.2.1. Configuration Properties
27.3. Proxy Factory Bean
27.4. Delegating Session Factory
27.5. SFTP Session Caching
27.6. RemoteFileTemplate
27.7. SFTP Inbound Channel Adapter
27.7.1. Recovering from Failures
27.7.2. Configuring with Java Configuration
27.7.3. Configuring with the Java DSL
27.8. SFTP Streaming Inbound Channel Adapter
27.8.1. Configuring with Java Configuration
27.9. SFTP Outbound Channel Adapter
27.9.1. Configuring with Java Configuration
27.9.2. Configuring with the Java DSL
27.10. SFTP Outbound Gateway
27.10.1. Configuring with Java Configuration
27.10.2. Configuring with the Java DSL
27.10.3. Outbound Gateway Partial Success (mget and mput)
27.11. SFTP/JSCH Logging
27.12. MessageSessionCallback
28. STOMP Support
28.1. Introduction
28.2. Overview
28.3. STOMP Inbound Channel Adapter
28.4. STOMP Outbound Channel Adapter
28.5. STOMP Headers Mapping
28.6. STOMP Integration Events
28.7. STOMP Adapters Java Configuration
28.8. STOMP Namespace Support
29. Stream Support
29.1. Introduction
29.2. Reading from streams
29.3. Writing to streams
29.4. Stream namespace support
30. Syslog Support
30.1. Introduction
30.2. Syslog <inbound-channel-adapter>
30.2.1. Example Configuration
31. TCP and UDP Support
31.1. Introduction
31.2. UDP Adapters
31.3. TCP Connection Factories
31.3.1. TCP Caching Client Connection Factory
31.3.2. TCP Failover Client Connection Factory