Spring Integration Reference Manual


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


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
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
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
2.2.11. FTP Changes
Session Changes
Inbound Channel Adapter
2.2.12. Router Changes
2.2.13. Header Mapping
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. Programming Tips and Tricks
IV. Core Messaging
4. Messaging Channels
4.1. Message Channels
4.1.1. The MessageChannel Interface
4.1.2. Message Channel Implementations
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
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
"Smart" Polling
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
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
Aggregating Large Groups
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
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
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
31.4. TCP Connection Interceptors
31.5. TCP Connection Events
31.6. TCP Adapters
31.7. TCP Gateways
31.8. TCP Message Correlation
31.8.1. Overview
31.8.2. Gateways
31.8.3. Collaborating Outbound and Inbound Channel Adapters
31.8.4. Transferring Headers
31.9. A Note About NIO
31.9.1. Thread Pool Task Executor with CALLER_RUNS Policy
31.10. SSL/TLS Support
31.10.1. Overview
31.10.2. Getting Started
31.11. Advanced Techniques
31.11.1. Strategy Interfaces
31.11.2. Example: Enabling SSL Client Authentication
31.12. IP Configuration Attributes
31.13. IP Message Headers
31.14. Annotation-Based Configuration
32. Twitter Support
32.1. Introduction
32.2. Twitter OAuth Configuration
32.3. Twitter Template
32.4. Twitter Inbound Adapters
32.4.1. Inbound Message Channel Adapter
32.4.2. Direct Inbound Message Channel Adapter
32.4.3. Mentions Inbound Message Channel Adapter
32.4.4. Search Inbound Message Channel Adapter
32.5. Twitter Outbound Adapter
32.5.1. Twitter Outbound Update Channel Adapter
32.5.2. Twitter Outbound Direct Message Channel Adapter
32.6. Twitter Search Outbound Gateway
33. WebSockets Support
33.1. Introduction
33.2. Overview
33.3. WebSocket Inbound Channel Adapter
33.4. WebSocket Outbound Channel Adapter
33.5. WebSockets Namespace Support
34. Web Services Support
34.1. Outbound Web Service Gateways
34.2. Inbound Web Service Gateways
34.3. Web Service Namespace Support
34.4. Outbound URI Configuration
34.5. WS Message Headers
35. XML Support - Dealing with XML Payloads
35.1. Introduction
35.2. Namespace Support
35.2.1. XPath Expressions
Providing Namespaces (Optional) to XPath Expressions
Using XPath Expressions with Default Namespaces
35.3. Transforming XML Payloads
35.3.1. Configuring Transformers as Beans
35.3.2. Namespace Support for XML Transformers
35.3.3. Namespace Configuration and ResultTransformers
35.4. Transforming XML Messages Using XPath
35.5. Splitting XML Messages
35.6. Routing XML Messages Using XPath
35.6.1. XML Payload Converter
35.7. XPath Header Enricher
35.8. Using the XPath Filter
35.9. #xpath SpEL Function
35.10. XML Validating Filter
36. XMPP Support
36.1. Introduction
36.2. XMPP Connection
36.3. XMPP Messages
36.3.1. Inbound Message Channel Adapter
36.3.2. Outbound Message Channel Adapter
36.4. XMPP Presence
36.4.1. Inbound Presence Message Channel Adapter
36.4.2. Outbound Presence Message Channel Adapter
36.5. Advanced Configuration
36.6. XMPP Message Headers
36.7. XMPP Extensions
37. Zookeeper Support
37.1. Introduction
37.2. Zookeeper Metadata Store
37.3. Zookeeper Lock Registry
37.4. Zookeeper Leadership Event Handling
VI. Appendices
A. Spring Expression Language (SpEL)
A.1. Introduction
A.2. SpEL Evaluation Context Customization
A.3. SpEL Functions
A.4. PropertyAccessors
B. Message Publishing
B.1. Message Publishing Configuration
B.1.1. Annotation-driven approach via @Publisher annotation
B.1.2. XML-based approach via the <publishing-interceptor> element
B.1.3. Producing and publishing messages based on a scheduled trigger
C. Transaction Support
C.1. Understanding Transactions in Message flows
C.1.1. Poller Transaction Support
C.2. Transaction Boundaries
C.3. Transaction Synchronization
C.4. Pseudo Transactions
D. Security in Spring Integration
D.1. Introduction
D.2. Securing channels
D.3. SecurityContext Propagation
E. Spring Integration Samples
E.1. Introduction
E.2. Where to get Samples
E.3. Submitting Samples or Sample Requests
E.4. Samples Structure
E.5. Samples
E.5.1. Loan Broker
E.5.2. The Cafe Sample
E.5.3. The XML Messaging Sample
F. Configuration
F.1. Introduction
F.2. Namespace Support
F.3. Configuring the Task Scheduler
F.4. Error Handling
F.5. Global Properties
F.6. Annotation Support
F.6.1. Messaging Meta-Annotations
F.6.2. Annotations on @Beans
F.6.3. Creating a Bridge with Annotations
F.6.4. Advising Annotated Endpoints
F.7. Message Mapping rules and conventions
F.7.1. Simple Scenarios
F.7.2. Complex Scenarios
G. Additional Resources
G.1. Spring Integration Home
H. Change History
H.1. Changes between 4.1 and 4.2
H.2. New Components
H.2.1. Major Management/JMX Rework
H.2.2. MongoDB Metadata Store
H.2.3. SecuredChannel Annotation
H.2.4. SecurityContext Propagation
H.2.5. FileSplitter
H.2.6. Zookeeper Support
H.2.7. Thread Barrier
H.2.8. STOMP Support
H.2.9. Codec
H.2.10. Message PreparedStatement Setter
H.3. General Changes
H.3.1. Wire Tap
H.3.2. File Changes
Appending New Lines
Ignoring Hidden Files
Writing InputStream Payloads
Last Modified Filter
WatchService Directory Scanner
Persistent File List Filter Changes
H.3.3. Class Package Change
H.3.4. TCP Changes
TCP Serializers
Server Socket Exceptions
TCP Server Port
TCP Gateway Remote Timeout
TCP SSLSession Available for Header Mapping
TCP Events
H.3.5. @InboundChannelAdapter
H.3.6. API Changes
H.3.7. JMS Changes
Reply Listener Lazy Initialization
Conversion Errors in Message-Driven Endpoints
Default Acknowledge Mode
Shared Subscriptions
H.3.8. Conditional Pollers
H.3.9. AMQP Changes
Publisher Confirms
Correlation Data
The Inbound Gateway properties
H.3.10. XPath Splitter Improvements
H.3.11. HTTP Changes
Inbound Gateway Timeout
Form Data
H.3.12. Gateway Changes
Gateway Methods can Return CompletableFuture<?>
MessagingGateway Annotation
H.3.13. Aggregator Changes
Aggregator Performance
Output Message Group Processor
H.3.14. (S)FTP Changes
Inbound channel adapters
Gateway Partial Results
Delegating Session Factory
Default Sftp Session Factory
Message Session Callback
H.3.15. Websocket Changes
H.3.16. Application Event Adapters changes
H.4. Changes between 4.0 and 4.1
H.4.1. New Components
Promise<?> Gateway
WebSocket support
Scatter-Gather EIP pattern
Routing Slip Pattern
Idempotent Receiver Pattern
Redis Queue Gateways
H.4.2. General Changes
AMQP Inbound Endpoints, Channel
AMQP Outbound Endpoints
Web Service Outbound Gateway: encode-uri
Http Inbound Channel Adapter and StatusCode
MQTT Adapter Changes
FTP/SFTP Adapter Changes
Splitter and Iterator
Content Enricher Improvements
Header Channel Registry
Orderly Shutdown
Management for RecipientListRouter
AbstractHeaderMapper: NON_STANDARD_HEADERS token
AMQP Channels: template-channel-transacted
Syslog Adapter
Async Gateway
Aggregator Advice Chain
Outbound Channel Adapter and Scripts
Resequencer Changes
Optional POJO method parameter
QueueChannel: backed Queue type
ChannelInterceptor Changes
H.5. Changes between 3.0 and 4.0
H.5.1. New Components
MQTT Channel Adapters
Spring Boot @EnableAutoConfiguration
Redis Channel Message Stores
MongodDB Channel Message Store
Redis Command Gateway
RedisLockRegistry and GemfireLockRegistry
@InboundChannelAdapter and SmartLifecycle for Annotated Endpoints
Twitter Search Outbound Gateway
Gemfire Metadata Store
@BridgeFrom and @BridgeTo Annotations
Meta Messaging Annotations
H.5.2. General Changes
Requires Spring Framework 4.0
Header Type for XPath Header Enricher
Object To Json Transformer: Node Result
JMS Header Mapping
JMS Outbound Channel Adapter
JMS Inbound Channel Adapter
Datatype Channels
Simpler Retry Advice Configuration
Correlation Endpoint: Time-based Release Strategy
Redis Metadata Store
JdbcChannelMessageStore and PriorityChannel
AMQP Endpoints Delivery Mode
FTP Timeouts
Twitter: StatusUpdatingMessageHandler
JPA Retrieving Gateway: id-expression
TCP Deserialization Events
Messaging Annotations on @Bean Definitions
H.6. Changes Between 2.2 and 3.0
H.6.1. New Components
HTTP Request Mapping
Spring Expression Language (SpEL) Configuration
SpEL Functions Support
SpEL PropertyAccessors Support
Redis: New Components
Header Channel Registry
MongoDB support: New ConfigurableMongoDbMessageStore
Syslog Support
Tail Support
JMX Support
TCP/IP Connection Events and Connection Management
Inbound Channel Adapter Script Support
Content Enricher: Headers Enrichment Support
H.6.2. General Changes
Message ID Generation
<gateway> Changes
HTTP Endpoint Changes
Jackson Support (JSON)
Chain Elements id Attribute
Aggregator empty-group-min-timeout property
Persistent File List Filters (file, (S)FTP)
Scripting Support: Variables Changes
Direct Channel Load Balancing configuration
PublishSubscribeChannel Behavior
FTP, SFTP and FTPS Changes
requires-reply Attribute for Outbound Gateways
AMQP Outbound Gateway Header Mapping
Stored Procedure Components Improvements
Web Service Outbound URI Configuration
Redis Adapter Changes
Advising Filters
Advising Endpoints using Annotations
ObjectToStringTransformer Improvements
JPA Support Changes
Delayer: delay expression
JDBC Message Store Improvements
IMAP Idle Connection Exceptions
Message Headers and TCP
JMS Message Driven Channel Adapter
RMI Inbound Gateway
H.7. Changes between 2.1 and 2.2
H.7.1. New Components
RedisStore Inbound and Outbound Channel Adapters
MongoDB Inbound and Outbound Channel Adapters
JPA Endpoints
H.7.2. General Changes
Spring 3.1 Used by Default
Adding Behavior to Endpoints
Transaction Synchronization and Pseudo Transactions
File Adapter - Improved File Overwrite/Append Handling
Reply-Timeout added to more Outbound Gateways
Spring-AMQP 1.1
JDBC Support - Stored Procedures Components
JDBC Support - Outbound Gateway
JDBC Support - Channel-specific Message Store Implementation
Orderly Shutdown
JMS Oubound Gateway Improvements
HTTP Support
H.8. Changes between 2.0 and 2.1
H.8.1. New Components
JSR-223 Scripting Support
GemFire Support
AMQP Support
MongoDB Support
Redis Support
Support for Spring’s Resource abstraction
Stored Procedure Components
XPath and XML Validating Filter
Payload Enricher
FTP and SFTP Outbound Gateways
FTP Session Caching
H.8.2. Framework Refactoring
Standardizing Router Configuration
XML Schemas updated to 2.1
H.8.3. Source Control Management and Build Infrastructure
Source Code now hosted on Github
Improved Source Code Visibility with Sonar
H.8.4. New Samples
H.9. Changes between 1.0 and 2.0
H.9.1. Spring 3 support
Support for the Spring Expression Language (SpEL)
ConversionService and Converter
TaskScheduler and Trigger
RestTemplate and HttpMessageConverter
H.9.2. Enterprise Integration Pattern Additions
Message History
Message Store
Claim Check
Control Bus
H.9.3. New Channel Adapters and Gateways
TCP/UDP Adapters
Twitter Adapters
XMPP Adapters
FTP/FTPS Adapters
SFTP Adapters
Feed Adapters
H.9.4. Other Additions
Groovy Support
Map Transformers
JSON Transformers
Serialization Transformers
H.9.5. Framework Refactoring
H.9.6. New Source Control Management and Build Infrastructure
H.9.7. New Spring Integration Samples
H.9.8. Spring Tool Suite Visual Editor for Spring Integration

Part I. Preface


This section details the compatible Java and Spring Framework versions.

1 Compatible Java Versions

For Spring Integration 4.3.x, the minimum compatible Java version is Java SE 6. Older versions of Java are not supported.

Spring Integration 4.3.x is also compatible with Java SE 7 as well as Java SE 8.

Certain features (such as Optional<?> payloads and CompletableFuture gateway method return types) require Java 8.

While the jars are compatible with Java 6, Java 8 is required to build the project. see Checking out and Building.

2 Compatible Versions of the Spring Framework

Spring Integration 4.3.x requires Spring Framework 4.3 or later.

3 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, …

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"

For a detailed explanation regarding Spring Integration’s namespace support see Section F.2, “Namespace Support”.


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.

1. Conventions in this Book

In some cases, to aid formatting, when specifying long fully-qualified class names, we shorten the package org.springframework to o.s and org.springframework.integration to o.s.i, such as with o.s.i.transaction.TransactionSynchronizationFactory.

Part II. What’s new?

For those who are already familiar with Spring Integration, this chapter provides a brief overview of the new features of version 4.3. If you are interested in the changes and features, that were introduced in earlier versions, please see chapter: Appendix H, Change History

2. What’s new in Spring Integration 4.3?

This chapter provides an overview of the new features and improvements that have been introduced with Spring Integration 4.3. If you are interested in more details, please see the Issue Tracker tickets that were resolved as part of the 4.3 development process.

2.1 New Components

2.1.1 AMQP Async Outbound Gateway

See Section 11.7, “Async Outbound Gateway”.

2.1.2 MessageGroupFactory

The new MessageGroupFactory strategy has been introduced to allow a control over MessageGroup instances in MessageGroupStore logic. The SimpleMessageGroupFactory is provided for the SimpleMessageGroup with the GroupType.HASH_SET as the default factory for the standard MessageGroupStore implementations. See Section 9.4, “Message Store” for more information.

2.1.3 PersistentMessageGroup

The PersistentMessageGroup, - lazy-load proxy, - implementation is provided for persistent MessageGroupStore s, which return this instance for the getMessageGroup() when their lazyLoadMessageGroups is true (defaults). See Section 9.4, “Message Store” for more information.

2.1.4 FTP/SFTP Streaming Inbound Channel Adapters

New inbound channel adapters are provided that return an InputStream for each file allowing you to retrieve remote files without writing them to the local file system See Section 15.5, “FTP Streaming Inbound Channel Adapter” and Section 27.8, “SFTP Streaming Inbound Channel Adapter” for more information.

2.1.5 Stream Transformer

A new StreamTransformer is provided to transform an InputStream payload to either a byte[] or String. See the section called “Stream Transformer” for more information.

2.1.6 Integration Graph

A new IntegrationGraphServer together with the IntegrationGraphController REST service are provided to expose the runtime model of a Spring Integration application as a graph. See Section 9.8, “Integration Graph” for more information.

2.1.7 JDBC Lock Registry

A new JdbcLockRegistry is provided for distributed locks shared through the data base table. See Section 18.6, “JDBC Lock Registry” for more information.

2.1.8 Leader Initiator for Lock Registry

A new LeaderInitiator implementation is provided based on the LockRegistry strategy. See Section 8.3, “Leadership Event Handling” for more information.

2.2 General Changes

2.2.1 Core Changes

Outbound Gateway within Chain

Previously, it was possible to specify a reply-channel on an outbound gateway within a chain. It was completely ignored; the gateway’s reply goes to the next chain element, or to the chain’s output channel if the gateway is the last element. This condition is now detected and disallowed. If you have such configuration, simply remove the reply-channel.

Async Service Activator

An option to make the Service Asynchronous has been added. See Section 8.5.3, “Asynchronous Service Activator” for more information.

Messaging Annotation Support changes

The Messaging Annotation Support doesn’t require any more @MessageEndpoint (or any other @Component) annotation declaration on the class level. To restore the previous behaviour specify the spring.integration.messagingAnnotations.require.componentAnnotation of spring.integration.properties as true. See Section F.5, “Global Properties” and Section F.6, “Annotation Support” for more information.

Lifecycle Role Controller

The SmartLifecycleRoleController now provides methods to obtain status of endpoints in roles. See Section 8.2, “Endpoint Roles” for more information.

2.2.2 Mail Changes

Customizable User Flag

The customizable userFlag added in 4.2.2 to provide customization of the flag used to denote that the mail has been seen is now available using the XML namespace. See Section 21.5, “Marking IMAP Messages When \Recent is Not Supported” for more information.

Mail Message Mapping

There is now an option to map inbound mail messages with the MessageHeaders containing the mail headers and the payload containing the email content. Previously, the payload was always the raw MimeMessage. See Section 21.3, “Inbound Mail Message Mapping” for more information.

2.2.3 JMS Changes

Header Mapper

The DefaultJmsHeaderMapper now maps the standard correlationId header as a message property by invoking its toString() method. See Section 20.6, “Mapping Message Headers to/from JMS Message” for more information.

Async Gateway

The JMS Outbound gateway now has an async property. See Section 20.5.2, “Async Gateway” for more information.

2.2.4 Aggregator Changes

There is a change in behavior when a POJO aggregator releases a collection of Message<?> objects; this is rare but if your application does that, you will need to make a small change to your POJO. See this Important note for more information.

2.2.5 TCP/UDP Changes


A new TcpConnectionServerListeningEvent is emitted when a server connection factory is started. See Section 31.5, “TCP Connection Events” for more information.

The destination-expression and socket-expression are now available for the <int-ip:udp-outbound-channel-adapter>. See Section 31.2, “UDP Adapters” for more information.

Stream Deserializers

The various deserializers that can’t allocate the final buffer until the whole message has been assembled now support pooling of the raw buffer into which the data is received, rather than creating and discarding a buffer for each message. See Section 31.3, “TCP Connection Factories” for more information.

TCP Message Mapper

The message mapper now, optionally, sets a configured content type header. See Section 31.13, “IP Message Headers” for more information.

2.2.6 File Changes

Destination Directory Creation

The generated file name for the FileWritingMessageHandler can represent sub-path to save the desired directory structure for file in the target directory. See Section 14.3.1, “Generating File Names” for more information.

The FileReadingMessageSource now hides the WatchService directory scanning logic in the inner class. The use-watch-service and watch-events options are provided to enable such a behaviour. The top level WatchServiceDirectoryScanner has been deprecated because of inconsistency around API. See Section 14.2.2, “WatchServiceDirectoryScanner” for more information.

Buffer Size

When writing files, you can now specify the buffer size to use.

Appending and Flushing

You can now avoid flushing files when appending and use a number of strategies to flush the data during idle periods. See Section 14.3.4, “Flushing Files When using APPEND_NO_FLUSH” for more information.

Preserving Timestamps

The outbound channel adapter can now be configured to set the destination file’s lastmodified timestamp. See Section 14.3.5, “File Timestamps” for more information.

Splitter Changes

The FileSplitter will now automatically close an (S)FTP session when the file is completely read. This applies when the outbound gateway returns an InputStream or the new (S)FTP streaming channel adapters are being used. Also a new markers-json options has been introduced to convert FileSplitter.FileMarker to JSON String for relaxed downstream network interaction. See Section 14.5, “File Splitter” for more information.

File Filters

A new ChainFileListFilter is provided as an alternative to CompositeFileListFilter. See Section 14.2, “Reading Files” for more information.

2.2.7 AMQP Changes

Content Type Message Converter

The outbound endpoints now support a RabbitTemplate configured with a ContentTypeDelegatingMessageConverter such that the converter can be chosen based on the message content type. See Section 11.8, “Outbound Message Conversion” for more information.

Headers for Delayed Message Handling

Spring AMQP 1.6 adds support for Delayed Message Exchanges. Header mapping now supports the headers (amqp_delay and amqp_receivedDelay) used by this feature.

AMQP-Backed Channels

AMQP-backed channels now support message mapping. See Section 11.11, “AMQP Backed Message Channels” for more information.

2.2.8 Redis Changes

List Push/Pop Direction

Previously, the queue channel adapters always used the Redis List in a fixed direction, pushing to the left end and reading from the right end. It is now possible to configure the reading and writing direction using rightPop and leftPush options for the RedisQueueMessageDrivenEndpoint and RedisQueueOutboundChannelAdapter respectively. See Section 24.3.4, “Redis Queue Inbound Channel Adapter” and Section 24.3.5, “Redis Queue Outbound Channel Adapter” for more information.

Queue Inbound Gateway Default Serializer

The default serializer in the inbound gateway has been changed to a JdkSerializationRedisSerializer for compatibility with the outbound gateway. See Section 24.10, “Redis Queue Inbound Gateway” for more information.

2.2.9 HTTP Changes

Previously, with requests that had a body (such as POST) that had no content-type header, the body was ignored. With this release, the content type of such requests is considered to be application/octet-stream as recommended by RFC 2616. See Section 17.2, “Http Inbound Components” for more information.

2.2.10 SFTP Changes

Factory Bean

A new factory bean is provided to simplify the configuration of Jsch proxies for SFTP. See Section 27.3, “Proxy Factory Bean” for more information.

Inbound Channel Adapter

The inbound channel adapter is now configured with a FileSystemPersistentAcceptOnceFileListFilter in the local-filter by default. See Section 27.7, “SFTP Inbound Channel Adapter” for more information.


The SFTP outbound gateway (for put and mput commands) and the SFTP outbound channel adapter now support the chmod attribute to change the remote file permissions after uploading. See Section 27.9, “SFTP Outbound Channel Adapter” and Section 27.10, “SFTP Outbound Gateway” for more information.

2.2.11 FTP Changes

Session Changes

The FtpSession now supports null for the list() and listNames() method, since it is possible by the underlying FTP Client. With that the FtpOutboundGateway can now be configured without remoteDirectory expression. And the <int-ftp:inbound-channel-adapter> can be configured without remote-directory/remote-directory-expression. See Chapter 15, FTP/FTPS Adapters for more information.

Inbound Channel Adapter

The inbound channel adapter is now configured with a FileSystemPersistentAcceptOnceFileListFilter in the local-filter by default. See Section 15.4, “FTP Inbound Channel Adapter” for more information.

2.2.12 Router Changes

The ErrorMessageExceptionTypeRouter supports now the Exception superclass mappings to avoid duplication for the same channel in case of several inheritors. For this purpose the ErrorMessageExceptionTypeRouter loads mapping classes during initialization to fail-fast for a ClassNotFoundException.

See Section 6.1, “Routers” for more information.

2.2.13 Header Mapping


AMQP, WS and XMPP header mappings (e.g. request-header-mapping, reply-header-mapping) now support negated patterns. See Section 11.12, “AMQP Message Headers”, Section 34.5, “WS Message Headers”, and Section 36.6, “XMPP Message Headers” for more information.

AMQP Header Mapping

Previously, only standard AMQP headers were mapped by default; users had to explicitly enable mapping of user-defined headers. With this release all headers are mapped by default. In addition, the inbound amqp_deliveryMode header is no longer mapped by default. See Section 11.12, “AMQP Message Headers” for more information.

2.2.14 Groovy Scripts

Groovy scripts can now be configured with the compile-static hint or any other CompilerConfiguration options. See Section 8.8.1, “Groovy configuration” for more information.

2.2.15 @InboundChannelAdapter

The @InboundChannelAdapter has now an alias channel attribute for regular value. In addition the target SourcePollingChannelAdapter components can now resolve the target outputChannel bean from its provided name (outputChannelName options) in late-binding manner. See Section F.6, “Annotation Support” for more information.

2.2.16 XMPP changes

The XMPP Extensions (XEP) are now supported by the XMPP channel adapters. See Section 36.7, “XMPP Extensions” for more information.

2.2.17 WireTap Late Binding

The WireTap ChannelInterceptor now can accept a channelName which is resolved to the target MessageChannel later, during the first active interceptor operation. See the section called “Wire Tap” for more information.

2.2.18 ChannelMessageStoreQueryProvider

The ChannelMessageStoreQueryProvider now supports H2 database. See Section 18.4.2, “Backing Message Channels” for more information.

2.2.19 WebSocket Changes

The ServerWebSocketContainer now exposes allowedOrigins option and SockJsServiceOptions a suppressCors option. See Chapter 33, WebSockets Support for more information.

2.2.20 Barrier Changes

The BarrierMessageHandler now supports a discard channel to which late-arriving trigger messages are sent. See Section 6.8, “Thread Barrier” for more information.

2.2.21 AMQP Changes

The AMQP outbound endpoints now support setting a delay expression for when using the RabbitMQ Delayed Message Exchange plugin. See Section 11.10, “Delayed Message Exchange” for more information.

Part III. Overview of Spring Integration Framework

Spring Integration provides an extension of the Spring programming model to support the well-known 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.

3. Spring Integration Overview

3.1 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 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.

3.2 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.

3.3 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.

3.3.1 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.

Figure 3.1. Message


3.3.2 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.

Figure 3.2. Message Channel

Message Channel

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 Section 4.1.2, “Message Channel Implementations”.

3.3.3 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.

3.4 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 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.

3.4.1 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.

3.4.2 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.


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.

3.4.3 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.

Figure 3.3. Router


3.4.4 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.

3.4.5 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 CorrelationStrategy, a ReleaseStrategy and configurable settings for: timeout, whether to send partial results upon timeout, and a discard channel.

3.4.6 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.


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.

Figure 3.4. Service Activator

handler endpoint


As discussed in Message Channel above, channels can be Pollable or Subscribable; in this diagram, this is depicted by the "clock" symbol and the solid arrow (poll) and the dotted arrow (subscribe).

3.4.7 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.

Figure 3.5. An inbound "Channel Adapter" endpoint connects a source system to a MessageChannel.

source endpoint


Message sources can be Pollable (e.g. POP3) or Message-Driven (e.g. IMAP Idle); in this diagram, this is depicted by the "clock" symbol and the solid arrow (poll) and the dotted arrow (message-driven).

Figure 3.6. An outbound "Channel Adapter" endpoint connects a MessageChannel to a target system.

target endpoint


As discussed in Message Channel above, channels can be Pollable or Subscribable; in this diagram, this is depicted by the "clock" symbol and the solid arrow (poll) and the dotted arrow (subscribe).

3.5 Configuration and @EnableIntegration

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, the @EnableIntegration annotation has been introduced, to allow the registration of Spring Integration infrastructure beans (see JavaDocs). This annotation is required when only Java & Annotation configuration is used, e.g. with Spring Boot and/or Spring Integration Messaging Annotation support and Spring Integration Java DSL with no XML integration configuration.

The @EnableIntegration annotation is also useful when you have a parent context with no Spring Integration components and 2 or more child contexts that use Spring Integration. It enables these common components to be declared once only, in the parent context.

The @EnableIntegration annotation registers many infrastructure components with the application context:

  • Registers some built-in beans, e.g. errorChannel and its LoggingHandler, taskScheduler for pollers, jsonPath SpEL-function etc.;
  • Adds several BeanFactoryPostProcessor s to enhance the BeanFactory for global and default integration environment;
  • Adds several BeanPostProcessor s to enhance and/or convert and wrap particular beans for integration purposes;
  • Adds annotations processors to parse Messaging Annotations and registers components for them with the application 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 Section 8.4.6, “@MessagingGateway 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 Section B.1.1, “Annotation-driven approach via @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 the section called “Global Channel Interceptor Configuration”). @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 Section 8.1.6, “Payload Type Conversion”). @IntegrationConverter annotations can be placed at the class level (with a @Component stereotype annotation), or on @Bean methods within @Configuration classes.

Also see Section F.6, “Annotation Support” for more information about Messaging Annotations.

3.6 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.

3.7 Programming Tips and Tricks

With XML configuration and Spring Integration Namespace support, the XML Parsers hide how target beans are built and wired together. For Java & Annotation Configuration, it is important to understand the Framework API for the target end-user applications.

The first class citizens for EIP implementation are Message, Channel and Endpoint (see Section 3.3, “Main Components” above). Their implementations (contracts) are:

The first two are simple enough to understand how to implement, configure and use, respectively; the last one deserves more review.

The AbstractEndpoint is widely used throughout the Framework for different component implementations; its main implementations are:

  • EventDrivenConsumer, when we subscribe to a SubscribableChannel to listen for messages;
  • PollingConsumer, when we poll for messages from a PollableChannel.

Using Messaging Annotations and/or Java DSL, you shouldn’t worry about these components, because the Framework produces them automatically via appropriate annotations and BeanPostProcessor s. When building components manually, the ConsumerEndpointFactoryBean should be used to help to determine the target AbstractEndpoint implementation based on the provided inputChannel property.

On the other hand, the ConsumerEndpointFactoryBean exhibits an another first class citizens in the Framework - org.springframework.messaging.MessageHandler. The goal of the implementation of this class is to handle the message consumed by the endpoint from the channel. All EIP components in Spring Integration are MessageHandler implementations, e.g. AggregatingMessageHandler, MessageTransformingHandler, AbstractMessageSplitter etc.; as well as the target protocol outbound adapters are implementations, too, e.g. FileWritingMessageHandler, HttpRequestExecutingMessageHandler, AbstractMqttMessageHandler etc. When you develop Spring Integration applications with Java & Annotation Configuration, you should take a look into the Spring Integration module to find an appropriate MessageHandler implementation to be used for the @ServiceActivator configuration. For example to send an XMPP message (see Chapter 36, XMPP Support) we should configure something like this:

@ServiceActivator(inputChannel = "input")
public MessageHandler sendChatMessageHandler(XMPPConnection xmppConnection) {
    ChatMessageSendingMessageHandler handler = new ChatMessageSendingMessageHandler(xmppConnection);

    DefaultXmppHeaderMapper xmppHeaderMapper = new DefaultXmppHeaderMapper();

    return handler;

The MessageHandler implementations represent the outbound and processing part of the message flow.

The inbound message flow side has its own components, which are divided to the polling and listening behavior. The listening components are pretty simple and typically requires only one target class implementation to be ready to produce messages. Listening components can be one-way MessageProducerSupport implementations, e.g. AbstractMqttMessageDrivenChannelAdapter and ImapIdleChannelAdapter; and request-reply - MessagingGatewaySupport implementations, e.g. AmqpInboundGateway and AbstractWebServiceInboundGateway.

Polling inbound endpoints are for those protocols which don’t provide a listener API or aren’t intended for such a behavior. For example any File based protocol, as an FTP, any data bases (RDBMS or NoSQL) etc.

These inbound endpoints consist with two components: the poller configuration, to initiate the polling task periodically, and message source class to read data from the target protocol and produce a message for the downstream integration flow. The first class, for poller configuration, is SourcePollingChannelAdapter. It is one more AbstractEndpoint implementation, but especially for the polling purpose for initiating an integration flow. Typically, with the Messaging Annotations or Java DSL, you shouldn’t worry about this class, the Framework produces a bean for it, based on the @InboundChannelAdapter configuration or Java DSL particular Builder.

The message source components are more important for the target application development and they all implement the MessageSource interface, e.g. MongoDbMessageSource and AbstractTwitterMessageSource. With that in mind, our config for reading data from an RDBMS table with JDBC may look like:

@InboundChannelAdapter(value = "fooChannel", poller = @Poller(fixedDelay="5000"))
public MessageSource<?> storedProc(DataSource dataSource) {
    return new JdbcPollingChannelAdapter(dataSource, "SELECT * FROM foo where status = 0");

All the required inbound and outbound classes for the target protocols you can find in the particular Spring Integration module, in most cases in the respective package. For example spring-integration-websocket adapters are:

  • o.s.i.websocket.inbound.WebSocketInboundChannelAdapter - implements MessageProducerSupport implementation to listen frames on the socket and produce message to the channel;
  • o.s.i.websocket.outbound.WebSocketOutboundMessageHandler - the one-way AbstractMessageHandler implementation to convert incoming messages to the appropriate frame and send over websocket.

If you are familiar with Spring Integration XML configuration already, starting with version 4.3, we provide in the XSD elements definitions the description with the pointer which target classes are used to produce beans for the adapter or gateway, for example:

<xsd:element name="outbound-async-gateway">
Configures a Consumer Endpoint for the 'o.s.i.amqp.outbound.AsyncAmqpOutboundGateway'
that will publish an AMQP Message to the provided Exchange and expect a reply Message.
The sending thread returns immediately; the reply is sent asynchronously; uses 'AsyncRabbitTemplate.sendAndReceive()'.

Part IV. Core Messaging

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.

4. Messaging Channels

4.1 Message Channels

While the Message plays the crucial role of encapsulating data, it is the MessageChannel that decouples message producers from message consumers.

4.1.1 The MessageChannel Interface

Spring Integration’s top-level MessageChannel interface is defined as follows.

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.


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.

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.


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:

public interface SubscribableChannel extends MessageChannel {

    boolean subscribe(MessageHandler handler);

    boolean unsubscribe(MessageHandler handler);


4.1.2 Message Channel Implementations

Spring Integration provides several different Message Channel implementations. Each is briefly described in the sections below.


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.


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.


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:

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.


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.


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.


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 Chapter 20, JMS Support. 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.


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).


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 convenience 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.

<int:channel id="lbRefChannel">
  <int:dispatcher load-balancer-ref="lb"/>

<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.


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.


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.


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.

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.

<int:channel id="threadScopedChannel" scope="thread">
     <int:queue />

<bean class="org.springframework.beans.factory.config.CustomScopeConfigurer">
    <property name="scopes">
            <entry key="thread" value="org.springframework.context.support.SimpleThreadScope" />

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.

4.1.3 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:

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:


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.


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(..), postReceive(..) and afterReceiveCompletion(..) interceptor methods are only invoked when the interceptor is applied to a PollableChannel.

Spring Integration also provides an implementation of the 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 the section called “Wire Tap”.

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.

public class CountingChannelInterceptor extends ChannelInterceptorAdapter {

    private final AtomicInteger sendCount = new AtomicInteger();

    public Message<?> preSend(Message<?> message, MessageChannel channel) {
        return message;

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.

4.1.4 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.

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.

public boolean send(final MessageChannel channel, final Message<?> message) { ...

public Message<?> sendAndReceive(final MessageChannel channel, final Message<?> request) { ..

public Message<?> receive(final PollableChannel<?> channel) { ...

A less invasive approach that allows you to invoke simple interfaces with payload and/or header values instead of Message instances is described in Section 8.4.1, “Enter the GatewayProxyFactoryBean”.

4.1.5 Configuring Message Channels

To create a Message Channel instance, you can use the <channel/> element:

<int:channel id="exampleChannel"/>

The default channel type is Point to Point. To create a Publish Subscribe channel, use the <publish-subscribe-channel/> element:

<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 Section 4.1.2, “Message Channel Implementations”). Examples of each are shown below.

DirectChannel Configuration

As mentioned above, DirectChannel is the default type.

<int:channel id="directChannel"/>

A default channel will have a round-robin load-balancer and will also have failover enabled (See the discussion in the section called “DirectChannel” for more detail). To disable one or both of these, add a <dispatcher/> sub-element and configure the attributes:

<int:channel id="failFastChannel">
    <int:dispatcher failover="false"/>

<int:channel id="channelWithFixedOrderSequenceFailover">
    <int:dispatcher load-balancer="none"/>

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 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:

<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:

<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 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.

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:

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.

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:

<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.


For more information regarding Payload Type Conversion, please read Section 8.1.6, “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.

QueueChannel Configuration

To create a QueueChannel, use the <queue/> sub-element. You may specify the channel’s capacity:

<int:channel id="queueChannel">
    <queue capacity="25"/>

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 Section 9.4, “Message Store”.


The capacity attribute is not allowed when the message-store attribute is used.

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 JdbcChannelMessageStore.

You can configure a Message Store for any QueueChannel by adding the message-store attribute as shown in the next example.

<int:channel id="dbBackedChannel">
    <int:queue message-store="channelStore"/>

<bean id="channelStore" class="o.s.i.jdbc.store.JdbcChannelMessageStore">
    <property name="dataSource" ref="dataSource"/>
    <property name="channelMessageStoreQueryProvider" ref="queryProvider"/>

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).


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. For example the Java Configuration for the Section 22.3.1, “MongoDB Channel Message Store”:

public BasicMessageGroupStore mongoDbChannelMessageStore(MongoDbFactory mongoDbFactory) {
    MongoDbChannelMessageStore store = new MongoDbChannelMessageStore(mongoDbFactory);
    return store;

public PollableChannel priorityQueue(BasicMessageGroupStore mongoDbChannelMessageStore) {
    return new QueueChannel(new MessageGroupQueue(mongoDbChannelMessageStore, "priorityQueue"));

Pay attention to the MessageGroupQueue class. That is a BlockingQueue implementation to utilize the MessageGroupStore operations.

The same with Java DSL may look like:

public IntegrationFlow priorityFlow(PriorityCapableChannelMessageStore mongoDbChannelMessageStore) {
    return IntegrationFlows.from((Channels c) ->
            c.priority("priorityChannel", mongoDbChannelMessageStore, "priorityGroup"))

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 Project Reactor and its reactor.queue.PersistentQueue implementation for the IndexedChronicle:

public QueueChannel reactorQueue() {
    return new QueueChannel(new PersistentQueueSpec<Message<?>>()
                    .codec(new JavaSerializationCodec<Message<?>>())
                    .basePath(System.getProperty("java.io.tmpdir") + "/reactor-queue")

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):

<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.

<int:publish-subscribe-channel id="pubsubChannel" apply-sequence="true"/>

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.


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).

<int:channel id="executorChannel">
    <int:dispatcher task-executor="someExecutor"/>

The load-balancer and failover options are also both available on the <dispatcher/> sub-element as described above in the section called “DirectChannel Configuration”. 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.

<int:channel id="executorChannelWithoutFailover">
    <int:dispatcher task-executor="someExecutor" failover="false"/>

PriorityChannel Configuration

To create a PriorityChannel, use the <priority-queue/> sub-element:

<int:channel id="priorityChannel">
    <int:priority-queue capacity="20"/>

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:

<int:channel id="priorityChannel" datatype="example.Widget">
    <int:priority-queue comparator="widgetComparator"

Since version 4.0, the priority-channel child element supports the message-store option (comparator and capacity are 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 the section called “QueueChannel Configuration” and Section 9.4, “Message Store” for more information. You can find sample configuration in Section 18.4.2, “Backing Message Channels”.

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.

<int:channel id="rendezvousChannel"/>

Scoped Channel Configuration

Any channel can be configured with a "scope" attribute.

<int:channel id="threadLocalChannel" scope="thread"/>

Channel Interceptor Configuration

Message channels may also have interceptors as described in Section 4.1.3, “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:

<int:channel id="exampleChannel">
        <ref bean="trafficMonitoringInterceptor"/>

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 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:

<int:channel-interceptor pattern="input*, bar*, foo" order="3">
    <bean class="foo.barSampleInterceptor"/>


<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):

<int:channel id="inputChannel"> 
    <int:wire-tap channel="logger"/> 

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 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).

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:

<int:channel id="in">
        <int:wire-tap channel="logger"/>

<int:logging-channel-adapter id="logger" level="DEBUG"/>

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 (Section B.1, “Message Publishing Configuration”) 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 by 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.


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.

Starting with version 4.3, the WireTap has additional constructors that take a channelName instead of a MessageChannel instance. This can be convenient for Java Configuration and when channel auto-creation logic is being used. The target MessageChannel bean is resolved from the provided channelName later, on the first interaction with the interceptor.


Channel resolution requires a BeanFactory so the wire tap instance must be a Spring-managed bean.

This late-binding approach also allows simplification of typical wire-tapping patterns with Java DSL configuration:

public PollableChannel myChannel() {
    return MessageChannels.queue()

public IntegrationFlow loggingFlow() {
    return f -> f.log();

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.

Global Wire Tap Configuration

It is possible to configure a global wire tap as a special case of the the section called “Global Channel Interceptor Configuration”. 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

<int:wire-tap pattern="input*, bar*, foo" order="3" channel="wiretapChannel"/>

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.

4.1.6 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 Section F.4, “Error Handling”.

4.2 Poller

4.2.1 Polling Consumer

When Message Endpoints (Channel Adapters) are connected to channels and instantiated, they produce one of the following 2 instances:

The actual implementation depends on which type of channel these Endpoints are connected to. A channel adapter connected to a channel that implements the 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 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:


4.2.2 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 Section 15.4, “FTP Inbound Channel Adapter” 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:

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)

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. Startng with version 4.2.5, a SimplePollSkipStrategy is provided. Add an instance as a bean to the application context, inject it into a PollSkipAdvice and add that to the poller’s advice chain. To skip polling, call skipPolls(), to resume polling, call reset(). Version 4.2 added more flexibility in this area - see Section 4.2.3, “Conditional Pollers for Message Sources”.

This chapter is meant to only give a high-level overview regarding Polling Consumers and how they fit into the concept of message channels - Section 4.1, “Message Channels” and channel adapters - Section 4.3, “Channel Adapter”. For more in-depth information regarding Messaging Endpoints in general and Polling Consumers in particular, please seeSection 8.1, “Message Endpoints”.

4.2.3 Conditional Pollers for Message Sources


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:

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).

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!

[Important]Advice Chain Ordering

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.


This advice is a simple implementation of AbstractMessageSourceAdvice, when used in conjunction with a DynamicPeriodicTrigger, it adjusts the 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]Important: Async Handoff

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.


This advice allows the selection of one of two triggers based on whether a poll returns a message or not. Consider a poller that uses a CronTrigger; CronTrigger s are immutable so cannot be altered once constructed. Consider a use case where we want to use a cron expression to trigger a poll once each hour but, if no message is received, poll once per minute and, when a message is retrieved, revert to using the cron expression.

The advice (and poller) use a CompoundTrigger for this purpose. The trigger’s primary trigger can be a CronTrigger. When the advice detects that no message is received, it adds the secondary trigger to the CompoundTrigger. When the CompoundTrigger 's nextExecutionTime method is invoked, it will delegate to the secondary trigger, if present; otherwise the primary trigger.

The poller must also have a reference to the same CompoundTrigger.

The following shows the configuration for the hourly cron expression with fall-back to every minute…​

<int:inbound-channel-adapter channel="nullChannel" auto-startup="false">
    <bean class="org.springframework.integration.endpoint.PollerAdviceTests.Source" />
    <int:poller trigger="compoundTrigger">
            <bean class="org.springframework.integration.aop.CompoundTriggerAdvice">
                <constructor-arg ref="compoundTrigger"/>
                <constructor-arg ref="secondary"/>

<bean id="compoundTrigger" class="org.springframework.integration.util.CompoundTrigger">
    <constructor-arg ref="primary" />

<bean id="primary" class="org.springframework.scheduling.support.CronTrigger">
    <constructor-arg value="0 0 * * * *" /> <!-- top of every hour -->

<bean id="secondary" class="org.springframework.scheduling.support.PeriodicTrigger">
    <constructor-arg value="60000" />
[Important]Important: Async Handoff

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.

4.3 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.

4.3.1 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.

<int:inbound-channel-adapter ref="source1" method="method1" channel="channel1">
    <int:poller fixed-rate="5000"/>

<int:inbound-channel-adapter ref="source2" method="method2" channel="channel2">
    <int:poller cron="30 * 9-17 * * MON-FRI"/>

Also see Section 4.3.3, “Channel Adapter Expressions and Scripts”.


If no poller is provided, then a single default poller must be registered within the context. See Section 8.1.4, “Namespace Support” 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:

<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:

<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.

<int:poller max-messages-per-poll="-1" fixed-rate="1000"/>

4.3.2 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.

<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:

<int:outbound-channel-adapter channel="channel2" ref="target" method="handle">
    <int:poller fixed-rate="3000" />

<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:

<int:outbound-channel-adapter channel="channel" method="handle">
    <beans:bean class="org.Foo"/>

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.

4.3.3 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:

<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"/>

Also see the cacheSeconds property on the ReloadableResourceBundleExpressionSource when using the <expression/> sub-element. For more information regarding expressions see Appendix A, Spring Expression Language (SpEL), and for scripts - Section 8.8, “Groovy support” and Section 8.7, “Scripting support”.


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.

4.4 Messaging Bridge

4.4.1 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.

4.4.2 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:

<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:

<int:bridge input-channel="pollable" output-channel="subscribable">
     <int:poller max-messages-per-poll="10" fixed-rate="5000"/>

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.

<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.


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.

5. Message Construction

5.1 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.

5.1.1 The Message Interface

Here is the definition of the Message interface:

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.

5.1.2 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:

public final class MessageHeaders implements Map<String, Object>, Serializable {

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:

 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:

Table 5.1. Pre-defined Message Headers

Header NameHeader TypeUsage

An identifier for this message instance. Changes each time a message is mutated.


The time the message was created. Changes each time a message is mutated.

(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.

(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.

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:

Table 5.2. Pre-defined Message Headers

Header NameHeader TypeUsage

Used to correlate two or more messages.


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.


The number of messages within a group of correlated messages.


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.


Message priority; for example within a PriorityChannel


True if a message was detected as a duplicate by an idempotent receiver interceptor. See Section 8.9.10, “Idempotent Receiver Enterprise Integration Pattern”.

Convenient typed getters for some of these headers are provided on the IntegrationMessageHeaderAccessor class:

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:

Table 5.3. Pre-defined Message Headers

Header NameHeader TypeUsage

A stack of correlation data used when nested correlation is needed (e.g. splitter->...->splitter->...->aggregator->...->aggregator).

List<Object>, Integer>

See the section called “Routing Slip”.

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.


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.

Read-only Headers

The MessageHeaders.ID and MessageHeaders.TIMESTAMP are read-only headers and they cannot be overridden.

Since version 4.3.2, the MessageBuilder provides the readOnlyHeaders(String... readOnlyHeaders) API to customize a list of headers which should not be copied from an upstream Message. Just the MessageHeaders.ID and MessageHeaders.TIMESTAMP are read only by default. The global spring.integration.readOnly.headers property (see Section F.5, “Global Properties”) is provided to customize DefaultMessageBuilderFactory for Framework components. This can be useful when you would like do not populate some out-of-the-box headers, like contentType by the ObjectToJsonTransformer (see ???).

When you try to build a new message using MessageBuilder, this kind of headers are ignored and particular INFO message is emitted to logs.

Header Propagation

When messages are processed (and modified) by message-producing endpoints (such as a service activator), in general, inbound headers are propagated to the outbound message. One exception to this is a transformer, when a complete message is returned to the framework; in that case, the user code is responsible for the entire outbound message. When a transformer just returns the payload; the inbound headers are propagated. Also, a header is only propagated if it does not already exist in the outbound message, allowing user code to change header values as needed.

Starting with version 4.3.10, you can configure message handlers (that modify messages and produce output) to suppress the propagation of specific headers. Call the setNotPropagatedHeaders() or addNotPropagatedHeaders() methods on the MessageProducingMessageHandler abstract class, to configure the header(s) you don’t want to be copied. You can also globally suppress propagation of specific message headers by setting the readOnlyHeaders property in META-INF/spring.integration.properties to a comma-delimited list of headers.


Header propagation suppression does not apply to those endpoints that don’t modify the message, e.g. bridges and routers

5.1.3 Message Implementations

The base implementation of the Message interface is GenericMessage<T>, and it provides two constructors:

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:

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.

5.1.4 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:

Message<String> message1 = MessageBuilder.withPayload("test")
        .setHeader("foo", "bar")

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.

Message<String> message3 = MessageBuilder.withPayload("test3")

Message<String> message4 = MessageBuilder.withPayload("test4")
        .setHeader("foo", 123)

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).

Message<Integer> importantMessage = MessageBuilder.withPayload(99)

assertEquals(5, importantMessage.getHeaders().getPriority());

Message<Integer> lessImportantMessage = MessageBuilder.fromMessage(importantMessage)
        .setHeaderIfAbsent(IntegrationMessageHeaderAccessor.PRIORITY, 2)

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.

6. Message Routing

6.1 Routers

6.1.1 Overview

Routers are a crucial element in many messaging architectures. They consume Messages from a Message Channel and forward each consumed message to one or more different Message Channel depending on a set of conditions.

Spring Integration provides the following routers out-of-the-box:

Router implementations share many configuration parameters. Yet, certain differences exist between routers. Furthermore, the availability of configuration parameters depends on whether Routers are used inside or outside of a chain. In order to provide a quick overview, all available attributes are listed in the 2 tables below.

Table 6.1. Routers Outside of a Chain

Attributerouterheader value routerxpath routerpayload type routerrecipient list routerexception type router

































Table 6.2. Routers Inside of a Chain

Attributerouterheader value routerxpath routerpayload type routerrecipient list routerexception type router


































Router parameters have been more standardized across all router implementations with Spring Integration 2.1. Consequently, there are a few minor changes that leave the possibility of breaking older Spring Integration based applications.

Since Spring Integration 2.1 the ignore-channel-name-resolution-failures attribute is removed in favor of consolidating its behavior with the resolution-required attribute. Also, the resolution-required attribute now defaults to true.

Prior to these changes, the resolution-required attribute defaulted to false causing messages to be silently dropped when no channel was resolved and no default-output-channel was set. The new behavior will require at least one resolved channel and by default will throw an MessageDeliveryException if no channel was determined (or an attempt to send was not successful).

If you do desire to drop messages silently simply set default-output-channel="nullChannel".

6.1.2 Common Router Parameters

Inside and Outside of a Chain

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

This attribute specifies whether sequence number and size headers should be added to each Message. This optional attribute defaults to false.
If set, this attribute provides a reference to the channel, where Messages should be sent, if channel resolution fails to return any channels. If no default output channel is provided, the router will throw an Exception. If you would like to silently drop those messages instead, add the nullChannel as the default output channel attribute value.

A Message will only be sent to the default-output-channel if resolution-required is false and the channel is not resolved.

If true this attribute specifies that channel names must always be successfully resolved to channel instances that exist. If set to true, a MessagingException will be raised, in case the channel cannot be resolved. Setting this attribute to false, will cause any unresovable channels to be ignored. This optional attribute will, if not explicitly set, default to true.

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

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

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


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

This attribute defaults to false.

The timeout attribute specifies the maximum amount of time in milliseconds to wait, when sending Messages to the target Message Channels. By default the send operation will block indefinitely.

Top-Level (Outside of a Chain)

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

Identifies the underlying Spring bean definition which in case of Routers is an instance of EventDrivenConsumer or PollingConsumer depending on whether the Router’s input-channel is a SubscribableChannel or PollableChannel, respectively. This is an optional attribute.
This Lifecycle attribute signaled if this component should be started during startup of the Application Context. This optional attribute defaults to true.
The receiving Message channel of this endpoint.
This attribute defines the order for invocation when this endpoint is connected as a subscriber to a channel. This is particularly relevant when that channel is using a failover dispatching strategy. It has no effect when this endpoint itself is a Polling Consumer for a channel with a queue.

6.1.3 Router Implementations

Since content-based routing often requires some domain-specific logic, most use-cases will require Spring Integration’s options for delegating to POJOs using the XML namespace support and/or Annotations. Both of these are discussed below, but first we present a couple implementations that are available out-of-the-box since they fulfill common requirements.


A PayloadTypeRouter will send Messages to the channel as defined by payload-type mappings.

<bean id="payloadTypeRouter"
    <property name="channelMapping">
            <entry key="java.lang.String" value-ref="stringChannel"/>
            <entry key="java.lang.Integer" value-ref="integerChannel"/>

Configuration of the PayloadTypeRouter is also supported via the namespace provided by Spring Integration (see Section F.2, “Namespace Support”), which essentially simplifies configuration by combining the <router/> configuration and its corresponding implementation defined using a <bean/> element into a single and more concise configuration element. The example below demonstrates a PayloadTypeRouter configuration which is equivalent to the one above using the namespace support:

<int:payload-type-router input-channel="routingChannel">
    <int:mapping type="java.lang.String" channel="stringChannel" />
    <int:mapping type="java.lang.Integer" channel="integerChannel" />


A HeaderValueRouter will send Messages to the channel based on the individual header value mappings. When a HeaderValueRouter is created it is initialized with the name of the header to be evaluated. The value of the header could be one of two things:

1. Arbitrary value

2. Channel name

If arbitrary then additional mappings for these header values to channel names is required, otherwise no additional configuration is needed.

Spring Integration provides a simple namespace-based XML configuration to configure a HeaderValueRouter. The example below demonstrates two types of namespace-based configuration for the HeaderValueRouter.

1. Configuration where mapping of header values to channels is required

<int:header-value-router input-channel="routingChannel" header-name="testHeader">
    <int:mapping value="someHeaderValue" channel="channelA" />
    <int:mapping value="someOtherHeaderValue" channel="channelB" />

During the resolution process this router may encounter channel resolution failures, causing an exception. If you want to suppress such exceptions and send unresolved messages to the default output channel (identified with the default-output-channel attribute) set resolution-required to false.

Normally, messages for which the header value is not explicitly mapped to a channel will be sent to the default-output-channel. However, in cases where the header value is mapped to a channel name but the channel cannot be resolved, setting the resolution-required attribute to false will result in routing such messages to the default-output-channel.


With Spring Integration 2.1 the attribute was changed from ignore-channel-name-resolution-failures to resolution-required. Attribute resolution-required will default to true.

2. Configuration where mapping of header values to channel names is not required since header values themselves represent channel names

<int:header-value-router input-channel="routingChannel" header-name="testHeader"/>

Since Spring Integration 2.1 the behavior of resolving channels is more explicit. For example, if you ommit the default-output-channel attribute and the Router was unable to resolve at least one valid channel, and any channel name resolution failures were ignored by setting resolution-required to false, then a MessageDeliveryException is thrown.

Basically, by default the Router must be able to route messages successfully to at least one channel. If you really want to drop messages, you must also have default-output-channel set to nullChannel.


A RecipientListRouter will send each received Message to a statically defined list of Message Channels:

<bean id="recipientListRouter"
    <property name="channels">
            <ref bean="channel1"/>
            <ref bean="channel2"/>
            <ref bean="channel3"/>

Spring Integration also provides namespace support for the RecipientListRouter configuration (see Section F.2, “Namespace Support”) as the example below demonstrates.

<int:recipient-list-router id="customRouter" input-channel="routingChannel"
  <int:recipient channel="channel1"/>
  <int:recipient channel="channel2"/>

The apply-sequence flag here has the same effect as it does for a publish-subscribe-channel, and like a publish-subscribe-channel, it is disabled by default on the recipient-list-router. Refer tothe section called “PublishSubscribeChannel Configuration” for more information.

Another convenient option when configuring a RecipientListRouter is to use Spring Expression Language (SpEL) support as selectors for individual recipient channels. This is similar to using a Filter at the beginning of chain to act as a "Selective Consumer". However, in this case, it’s all combined rather concisely into the router’s configuration.

<int:recipient-list-router id="customRouter" input-channel="routingChannel">
    <int:recipient channel="channel1" selector-expression="payload.equals('foo')"/>
    <int:recipient channel="channel2" selector-expression="headers.containsKey('bar')"/>

In the above configuration a SpEL expression identified by the selector-expression attribute will be evaluated to determine if this recipient should be included in the recipient list for a given input Message. The evaluation result of the expression must be a boolean. If this attribute is not defined, the channel will always be among the list of recipients.


Starting with version 4.1, the RecipientListRouter provides several operation to manipulate with recipients dynamically at runtime. These management operations are presented by RecipientListRouterManagement @ManagedResource. They are available using Section 9.6, “Control Bus” as well as via JMX:

<control-bus input-channel="controlBus"/>

<recipient-list-router id="simpleRouter" input-channel="routingChannelA">
   <recipient channel="channel1"/>

<channel id="channel2"/>
messagingTemplate.convertAndSend(controlBus, "@'simpleRouter.handler'.addRecipient('channel2')");

From the application start up the simpleRouter will have only one channel1 recipient. But after the addRecipient command above the new channel2 recipient will be added. It is a "registering an interest in something that is part of the Message" use case, when we may be interested in messages from the router at some time period, so we are subscribing to the the recipient-list-router and in some point decide to unsubscribe our interest.

Having the runtime management operation for the <recipient-list-router>, it can be configured without any <recipient> from the start. In this case the behaviour of RecipientListRouter is the same, when there is no one matching recipient for the message: if defaultOutputChannel is configured, the message will be sent there, otherwise the MessageDeliveryException is thrown.

XPath Router

The XPath Router is part of the XML Module. As such, please read chapter Section 35.6, “Routing XML Messages Using XPath”

Routing and Error handling

Spring Integration also provides a special type-based router called ErrorMessageExceptionTypeRouter for routing Error Messages (Messages whose payload is a Throwable instance). ErrorMessageExceptionTypeRouter is very similar to the PayloadTypeRouter. In fact they are almost identical. The only difference is that while PayloadTypeRouter navigates the instance hierarchy of a payload instance (e.g., payload.getClass().getSuperclass()) to find the most specific type/channel mappings, the ErrorMessageExceptionTypeRouter navigates the hierarchy of exception causes (e.g., payload.getCause()) to find the most specific Throwable type/channel mappings and uses mappingClass.isInstance(cause) to match the cause to the class or any super class.


Since version 4.3 the ErrorMessageExceptionTypeRouter loads all mapping classes during the initialization phase to fail-fast for a ClassNotFoundException.

Below is a sample configuration for ErrorMessageExceptionTypeRouter.

<int:exception-type-router input-channel="inputChannel"
    <int:mapping exception-type="java.lang.IllegalArgumentException"
    <int:mapping exception-type="java.lang.NullPointerException"

<int:channel id="illegalChannel" />
<int:channel id="npeChannel" />

6.1.4 Configuring (Generic) Router

Configuring a Content Based Router with XML

The "router" element provides a simple way to connect a router to an input channel and also accepts the optional default-output-channel attribute. The ref attribute references the bean name of a custom Router implementation (extending AbstractMessageRouter):

<int:router ref="payloadTypeRouter" input-channel="input1"

<int:router ref="recipientListRouter" input-channel="input2"

<int:router ref="customRouter" input-channel="input3"

<beans:bean id="customRouterBean" class="org.foo.MyCustomRouter"/>

Alternatively, ref may point to a simple POJO that contains the @Router annotation (see below), or the ref may be combined with an explicit method name. Specifying a method applies the same behavior described in the @Router annotation section below.

<int:router input-channel="input" ref="somePojo" method="someMethod"/>

Using a ref attribute is generally recommended if the custom router implementation is referenced in other <router> definitions. However if the custom router implementation should be scoped to a single definition of the <router>, you may provide an inner bean definition:

<int:router method="someMethod" input-channel="input3"
    <beans:bean class="org.foo.MyCustomRouter"/>

Using both the ref attribute and an inner handler definition in the same <router> configuration is not allowed, as it creates an ambiguous condition, and an Exception will be thrown.


If the "ref" attribute references a bean that extends AbstractMessageProducingHandler (such as routers provided by the framework itself), the configuration is optimized referencing the router directly. In this case, each "ref" must be to a separate bean instance (or a prototype-scoped bean), or use the inner <bean/> configuration type. However, this optimization only applies if you don’t provide any router-specific attributes in the router XML definition. If you inadvertently reference the same message handler from multiple beans, you will get a configuration exception.

Routers and the Spring Expression Language (SpEL)

Sometimes the routing logic may be simple and writing a separate class for it and configuring it as a bean may seem like overkill. As of Spring Integration 2.0 we offer an alternative where you can now use SpEL to implement simple computations that previously required a custom POJO router.


For more information about the Spring Expression Language, please refer to the respective chapter in the Spring Framework Reference Documentation at:


Generally a SpEL expression is evaluated and the result is mapped to a channel:

<int:router input-channel="inChannel" expression="payload.paymentType">
    <int:mapping value="CASH" channel="cashPaymentChannel"/>
    <int:mapping value="CREDIT" channel="authorizePaymentChannel"/>
    <int:mapping value="DEBIT" channel="authorizePaymentChannel"/>

To simplify things even more, the SpEL expression may evaluate to a channel name:

<int:router input-channel="inChannel" expression="payload + 'Channel'"/>

In the above configuration the result channel will be computed by the SpEL expression which simply concatenates the value of the payload with the literal String Channel.

Another value of SpEL for configuring routers is that an expression can actually return a Collection, effectively making every <router> a Recipient List Router. Whenever the expression returns multiple channel values the Message will be forwarded to each channel.

<int:router input-channel="inChannel" expression="headers.channels"/>

In the above configuration, if the Message includes a header with the name channels the value of which is a List of channel names then the Message will be sent to each channel in the list. You may also find Collection Projection and Collection Selection expressions useful to select multiple channels. For further information, please see:

Configuring a Router with Annotations

When using @Router to annotate a method, the method may return either a MessageChannel or String type. In the latter case, the endpoint will resolve the channel name as it does for the default output channel. Additionally, the method may return either a single value or a collection. If a collection is returned, the reply message will be sent to multiple channels. To summarize, the following method signatures are all valid.

public MessageChannel route(Message message) {...}

public List<MessageChannel> route(Message message) {...}

public String route(Foo payload) {...}

public List<String> route(Foo payload) {...}

In addition to payload-based routing, a Message may be routed based on metadata available within the message header as either a property or attribute. In this case, a method annotated with @Router may include a parameter annotated with @Header which is mapped to a header value as illustrated below and documented in Section F.6, “Annotation Support”.

public List<String> route(@Header("orderStatus") OrderStatus status)

For routing of XML-based Messages, including XPath support, see Chapter 35, XML Support - Dealing with XML Payloads.

6.1.5 Dynamic Routers

So as you can see, Spring Integration provides quite a few different router configurations for common content-based routing use cases as well as the option of implementing custom routers as POJOs. For example PayloadTypeRouter provides a simple way to configure a router which computes channels based on the payload type of the incoming Message while HeaderValueRouter provides the same convenience in configuring a router which computes channels by evaluating the value of a particular Message Header. There are also expression-based (SpEL) routers where the channel is determined based on evaluating an expression. Thus, these type of routers exhibit some dynamic characteristics.

However these routers all require static configuration. Even in the case of expression-based routers, the expression itself is defined as part of the router configuration which means that_the same expression operating on the same value will always result in the computation of the same channel_. This is acceptable in most cases since such routes are well defined and therefore predictable. But there are times when we need to change router configurations dynamically so message flows may be routed to a different channel.


You might want to bring down some part of your system for maintenance and temporarily re-reroute messages to a different message flow. Or you may want to introduce more granularity to your message flow by adding another route to handle a more concrete type of java.lang.Number (in the case of PayloadTypeRouter).

Unfortunately with static router configuration to accomplish this, you would have to bring down your entire application, change the configuration of the router (change routes) and bring it back up. This is obviously not the solution.

The Dynamic Router pattern describes the mechanisms by which one can change/configure routers dynamically without bringing down the system or individual routers. 

Before we get into the specifics of how this is accomplished in Spring Integration, let’s quickly summarize the typical flow of the router, which consists of 3 simple steps:

  • Step 1 - Compute channel identifier which is a value calculated by the router once it receives the Message. Typically it is a String or and instance of the actual MessageChannel.
  • Step 2 - Resolve channel identifier to channel name. We’ll describe specifics of this process in a moment.
  • Step 3 - Resolve channel name to the actual MessageChannel

There is not much that can be done with regard to dynamic routing if Step 1 results in the actual instance of the MessageChannel, simply because the MessageChannel is the final product of any router’s job. However, if Step 1 results in a channel identifier that is not an instance of MessageChannel, then there are quite a few possibilities to influence the process of deriving the Message Channel. Lets look at couple of the examples in the context of the 3 steps mentioned above: 

Payload Type Router

<int:payload-type-router input-channel="routingChannel">
    <int:mapping type="java.lang.String"  channel="channel1" />
    <int:mapping type="java.lang.Integer" channel="channel2" />

Within the context of the Payload Type Router the 3 steps mentioned above would be realized as:

  • Step 1 - Compute channel identifier which is the fully qualified name of the payload type (e.g., java.lang.String).
  • Step 2 - Resolve channel identifier to channel name where the result of the previous step is used to select the appropriate value from the payload type mapping defined via mapping element.
  • Step 3 - Resolve channel name to the actual instance of the MessageChannel as a reference to a bean within the Application Context (which is hopefully a MessageChannel) identified by the result of the previous step.

In other words, each step feeds the next step until the process completes.

Header Value Router

<int:header-value-router input-channel="inputChannel" header-name="testHeader">
    <int:mapping value="foo" channel="fooChannel" />
    <int:mapping value="bar" channel="barChannel" />

Similar to the PayloadTypeRouter:

  • Step 1 - Compute channel identifier which is the value of the header identified by the header-name attribute.
  • Step 2 - Resolve channel identifier to channel name where the result of the previous step is used to select the appropriate value from the general mapping defined via mapping element.
  • Step 3 - Resolve channel name to the actual instance of the MessageChannel as a reference to a bean within the Application Context (which is hopefully a MessageChannel) identified by the result of the previous step.

The above two configurations of two different router types look almost identical. However if we look at the alternate configuration of the HeaderValueRouter we clearly see that there is no mapping sub element:

<int:header-value-router input-channel="inputChannel" header-name="testHeader">

But the configuration is still perfectly valid. So the natural question is what about the mapping in the Step 2?

What this means is that Step 2 is now an optional step. If mapping is not defined then the channel identifier value computed in Step 1 will automatically be treated as the channel name, which will now be resolved to the actual MessageChannel as in Step 3.  What it also means is that Step 2 is one of the key steps to provide dynamic characteristics to the routers, since it introduces a process which allows you to change the way channel identifier resolves to 'channel name', thus influencing the process of determining the final instance of the MessageChannel from the initial channel identifier

For Example:

In the above configuration let’s assume that the testHeader value is kermit which is now a channel identifier (Step 1). Since there is no mapping in this router, resolving this channel identifier to a channel name (Step 2) is impossible and this channel identifier is now treated as channel name. However what if there was a mapping but for a different value? The end result would still be the same and that is: if a new value cannot be determined through the process of resolving the channel identifier to a channel name, such channel identifier becomes channel name.

So all that is left is for Step 3 to resolve the channel name (kermit) to an actual instance of the MessageChannel identified by this name. That basically involves a bean lookup for the name provided. So now all messages which contain the header/value pair as testHeader=kermit are going to be routed to a MessageChannel whose bean name (id) is kermit.

But what if you want to route these messages to the simpson channel? Obviously changing a static configuration will work, but will also require bringing your system down. However if you had access to the channel identifier map, then you could just introduce a new mapping where the header/value pair is now kermit=simpson, thus allowing Step 2 to treat kermit as a channel identifier while resolving it to simpson as the channel name .

The same obviously applies for PayloadTypeRouter, where you can now remap or remove a particular payload type mapping. In fact, it applies to every other router, including expression-based routers, since their computed values will now have a chance to go through Step 2 to be additionally resolved to the actual channel name.

Any router that is a subclass of the AbstractMappingMessageRouter (which includes most framework defined routers) is a Dynamic Router simply because the channelMapping is defined at the AbstractMappingMessageRouter level. That map’s setter method is exposed as a public method along with setChannelMapping and removeChannelMapping methods. These allow you to change/add/remove router mappings at runtime as long as you have a reference to the router itself. It also means that you could expose these same configuration options via JMX (see Section 9.2, “JMX Support”) or the Spring Integration ControlBus (see Section 9.6, “Control Bus”) functionality. 

Manage Router Mappings using the Control Bus

One way to manage the router mappings is through the Control Bus pattern which exposes a Control Channel where you can send control messages to manage and monitor Spring Integration components, including routers.


For more information about the Control Bus, please see chapter Section 9.6, “Control Bus”.

Typically you would send a control message asking to invoke a particular operation on a particular managed component (e.g. router). Two managed operations (methods) that are specific to changing the router resolution process are:

  • public void setChannelMapping(String key, String channelName) - will allow you to add a new or modify an existing mapping between channel identifier and channel name
  • public void removeChannelMapping(String key) - will allow you to remove a particular channel mapping, thus disconnecting the relationship between channel identifier and channel name

Note that these methods can be used for simple changes (updating a single route or adding/removing a route). However, if you want to remove one route and add another, the updates are not atomic. This means the routing table may be in an indeterminate state between the updates. Starting with version 4.0, you can now use the control bus to update the entire routing table atomically.

  • public Map<String, String>getChannelMappings() returns the current mappings.
  • public void replaceChannelMappings(Properties channelMappings) updates the mappings. Notice that the parameter is a properties object; this allows the use of the inbuilt StringToPropertiesConverter by a control bus command, for example:
"@'router.handler'.replaceChannelMappings('foo=qux \n baz=bar')"
  • note that each mapping is separated by a newline character (\n). For programmatic changes to the map, it is recommended that the setChannelMappings method is used instead, for type-safety. Any non-String keys or values passed into replaceChannelMappings are ignored.

Manage Router Mappings using JMX

You can also expose a router instance with Spring’s JMX support, and then use your favorite JMX client (e.g., JConsole) to manage those operations (methods) for changing the router’s configuration.


For more information about Spring Integration’s JMX support, please see chapter Section 9.2, “JMX Support”.

Routing Slip

Starting with version 4.1, Spring Integration provides an implementation of the Routing Slip Enterprise Integration Pattern. It is implemented as a routingSlip message header which is used to determine the next channel in AbstractMessageProducingHandler s, when an outputChannel isn’t specified for the endpoint. This pattern is useful in complex, dynamic, cases when it can become difficult to configure multiple routers to determine message flow. When a message arrives at an endpoint that has no output-channel, the routingSlip is consulted to determine the next channel to which the message will be sent. When the routing slip is exhausted, normal replyChannel processing resumes.

Configuration for the Routing Slip is presented as a HeaderEnricher option - a semicolon-separated Routing Slip path entries:

<util:properties id="properties">
    <beans:prop key="myRoutePath1">channel1</beans:prop>
    <beans:prop key="myRoutePath2">request.headers[myRoutingSlipChannel]</beans:prop>

<context:property-placeholder properties-ref="properties"/>

<header-enricher input-channel="input" output-channel="process">
        value="${myRoutePath1}; @routingSlipRoutingPojo.get(request, reply);
               routingSlipRoutingStrategy; ${myRoutePath2}; finishChannel"/>

In this sample we have:

  • A <context:property-placeholder> configuration to demonstrate that the entries in the Routing Slip path can be specified as resolvable keys.
  • The <header-enricher> <routing-slip> sub-element is used to populate the RoutingSlipHeaderValueMessageProcessor to the HeaderEnricher handler.
  • The RoutingSlipHeaderValueMessageProcessor accepts a String array of resolved Routing Slip path entries and returns (from processMessage()) a singletonMap with the path as key and 0 as initial routingSlipIndex.

Routing Slip path entries can contain MessageChannel bean names, RoutingSlipRouteStrategy bean names and also Spring expressions (SpEL). The RoutingSlipHeaderValueMessageProcessor checks each Routing Slip path entry against the BeanFactory on the first processMessage invocation. It converts entries, which aren’t bean names in the application context, to ExpressionEvaluatingRoutingSlipRouteStrategy instances. RoutingSlipRouteStrategy entries are invoked multiple times, until they return null, or an empty String.

Since the Routing Slip is involved in the getOutputChannel process we have a request-reply context. The RoutingSlipRouteStrategy has been introduced to determine the next outputChannel using the requestMessage, as well as the reply object. An implementation of this strategy should be registered as a bean in the application context and its bean name is used in the Routing Slip path. The ExpressionEvaluatingRoutingSlipRouteStrategy implementation is provided. It accepts a SpEL expression, and an internal ExpressionEvaluatingRoutingSlipRouteStrategy.RequestAndReply object is used as the root object of the evaluation context. This is to avoid the overhead of EvaluationContext creation for each ExpressionEvaluatingRoutingSlipRouteStrategy.getNextPath() invocation. It is a simple Java Bean with two properties - Message<?> request and Object reply. With this expression implementation, we can specify Routing Slip path entries using SpEL (@routingSlipRoutingPojo.get(request, reply), request.headers[myRoutingSlipChannel]) avoiding a bean definition for the RoutingSlipRouteStrategy.


The requestMessage argument is always a Message<?>; depending on context, the reply object may be a Message<?>, an AbstractIntegrationMessageBuilder or an arbitrary application domain object (if, for example, it is returned by a POJO method invoked by a service activator). In the first two cases, the usual "message" properties are available (payload and headers) when using SpEL (or a Java implementation). When an arbitrary domain object, these properties are, obviously, not available. Care should be taken when using routing slips in conjunction with POJO methods if the result is used to determine the next path.


If a Routing Slip is involved in a distributed environment - cross-JVM application, request-reply through a Message Broker (e.g. Chapter 11, AMQP Support, Chapter 20, JMS Support), or persistence MessageStore (Section 9.4, “Message Store”) is used in the integration flow, etc., - it is recommended to not use inline expressions for the Routing Slip path. The framework (RoutingSlipHeaderValueMessageProcessor) converts them to ExpressionEvaluatingRoutingSlipRouteStrategy objects and they are used in the routingSlip message header. Since this class isn’t Serializable (and it can’t be, because it depends on the BeanFactory) the entire Message becomes non-serializable and in any distributed operation we end up with NotSerializableException. To overcome this limitation, register an ExpressionEvaluatingRoutingSlipRouteStrategy bean with the desired SpEL and use its bean name in the Routing Slip path configuration.

For Java configuration, simply add a RoutingSlipHeaderValueMessageProcessor instance to the HeaderEnricher bean definition:

@Transformer(inputChannel = "routingSlipHeaderChannel")
public HeaderEnricher headerEnricher() {
    return new HeaderEnricher(Collections.singletonMap(IntegrationMessageHeaderAccessor.ROUTING_SLIP,
            new RoutingSlipHeaderValueMessageProcessor("myRoutePath1",
                                                       "@routingSlipRoutingPojo.get(request, reply)",

The Routing Slip algorithm works as follows when an endpoint produces a reply and there is no outputChannel defined:

  • The routingSlipIndex is used to get a value from the Routing Slip path list.
  • If the value by routingSlipIndex is String, it is used to get a bean from BeanFactory.
  • If a returned bean is an instance of MessageChannel, it is used as the next outputChannel and the routingSlipIndex is incremented in the reply message header (the Routing Slip path entries remain unchanged).
  • If a returned bean is an instance of RoutingSlipRouteStrategy and its getNextPath doesn’t return an empty String, that result is used a bean name for the next outputChannel. The routingSlipIndex remains unchanged.
  • If RoutingSlipRouteStrategy.getNextPath returns an empty String, the routingSlipIndex is incremented and the getOutputChannelFromRoutingSlip is invoked recursively for the next Routing Slip path item;
  • If the next Routing Slip path entry isn’t a String it must be an instance of RoutingSlipRouteStrategy;
  • When the routingSlipIndex exceeds the size of the Routing Slip path list, the algorithm moves to the default behavior for the standard replyChannel header.

Process Manager Enterprise Integration Pattern

The EIP also defines the Process Manager pattern. This pattern can now easily be implemented using custom Process Manager logic encapsulated in a RoutingSlipRouteStrategy within the routing slip. In addition to a bean name, the RoutingSlipRouteStrategy can return any MessageChannel object; and there is no requirement that this MessageChannel instance is a bean in the application context. This way, we can provide powerful dynamic routing logic, when there is no prediction which channel should be used; a MessageChannel can be created within the RoutingSlipRouteStrategy and returned. A FixedSubscriberChannel with an associated MessageHandler implementation is good combination for such cases. For example we can route to a Reactor Stream:

public PollableChannel resultsChannel() {
    return new QueueChannel();
public RoutingSlipRouteStrategy routeStrategy() {
    return (requestMessage, reply) -> requestMessage.getPayload() instanceof String
            ? new FixedSubscriberChannel(m ->
            Streams.defer((String) m.getPayload())
                    .consume(v -> messagingTemplate().convertAndSend(resultsChannel(), v))
            : new FixedSubscriberChannel(m ->
            Streams.defer((Integer) m.getPayload())
                    .map(v -> v * 2)
                    .consume(v -> messagingTemplate().convertAndSend(resultsChannel(), v))

6.2 Filter

6.2.1 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.


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:

public interface MessageSelector {

    boolean accept(Message<?> message);


The MessageFilter constructor accepts a selector instance:

MessageFilter filter = new MessageFilter(someSelector);

In combination with the namespace and SpEL, very powerful filters can be configured with very little java code.

6.2.2 Configuring Filter

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:

<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.

<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:

<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:

<int:filter input-channel="input" ref="selector"
    output-channel="output" discard-channel="rejectedMessages"/>

Also see Section 8.9.6, “Advising Filters”.


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:

<int:filter method="someMethod" input-channel="inChannel" output-channel="outChannel">
  <beans:bean class="org.foo.MyCustomFilter"/>

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.


If the "ref" attribute references a bean that extends MessageFilter (such as filters provided by the framework itself), the configuration is optimized by injecting the output channel into the filter bean directly. In this case, each "ref" must be to a separate bean instance (or a prototype-scoped bean), or use the inner <bean/> configuration type. However, this optimization only applies if you don’t provide any filter-specific attributes in the filter XML definition. If you inadvertently reference the same message handler from multiple beans, you will get a configuration exception.

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.

<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 the SpEL reference documentation.

<int:filter input-channel="input"

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.

<int:filter input-channel="input" output-channel="output">
    <int:expression key="filterPatterns.example" source="myExpressions"/>

<beans:bean id="myExpressions" id="myExpressions"
    <beans:property name="basename" value="config/integration/expressions"/>
    <beans:property name="cacheSeconds" value="60"/>

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:

filterPatterns.example=payload > 100

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.

Configuring a Filter with Annotations

A filter configured using annotations would look like this.

public class PetFilter {
    @Filter  1
    public boolean dogsOnly(String input) {


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 Section 8.9.7, “Advising Endpoints Using Annotations”.

6.3 Splitter

6.3.1 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.

6.3.2 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 a Composed Message Processor scenario.

An excerpt from AbstractMessageSplitter can be seen below:

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.

6.3.3 Configuring Splitter

Configuring a Splitter using XML

A splitter can be configured through XML as follows:

<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"/>


The id of the splitter is optional.


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.


The method (defined on the bean specified above) that implements the splitting logic.Optional.


The input channel of the splitter. Required.


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:

<int:splitter id="testSplitter" input-channel="inChannel" method="split"
  <beans:bean class="org.foo.TestSplitter"/>

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.


If the "ref" attribute references a bean that extends AbstractMessageProducingHandler (such as splitters provided by the framework itself), the configuration is optimized by injecting the output channel into the handler directly. In this case, each "ref" must be to a separate bean instance (or a prototype-scoped bean), or use the inner <bean/> configuration type. However, this optimization only applies if you don’t provide any splitter-specific attributes in the splitter XML definition. If you inadvertently reference the same message handler from multiple beans, you will get a configuration exception.

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.

List<LineItem> extractItems(Order order) {
    return order.getItems()

Also see Section 8.9.7, “Advising Endpoints Using Annotations”.

6.4 Aggregator

6.4.1 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.

6.4.2 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.

6.4.3 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


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):

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:

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.


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.Collection<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.Collection 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.

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.


The SimpleMessageGroup.getMessages() method returns an unmodifiableCollection, therefore, if your aggregating POJO method has a Collection<Message> parameter, the argument passed in will be exactly that Collection instance and, when a SimpleMessageStore is used for the Aggregator, that original Collection<Message> will be cleared after releasing the group. Hence the Collection<Message> variable in the POJO will be cleared too, if passed out of the aggregator. If you wish to simply release that collection as-is for further processing, it is required that you build a new Collection (e.g. new ArrayList<Message>(messages)) Starting with _version 4.3, the Framework no longer copies the messages to a new collection, to avoid undesired extra object creation.

If the MessageGroupProcessor 's processMessageGroup method returns a collection, it must be a collection of Message<?> s. In this case, the messages are released individually. Prior to version 4.2, it was not possible to provide a MessageGroupProcessor using XML configuration, only POJO methods could be used for aggregation. Now, if the framework detects that the referenced (or inner) bean implements MessageProcessor, it is used as the aggregator’s output processor.

If you wish to release a collection of objects from a custom MessageGroupProcessor as the payload of a message, your class should extend AbstractAggregatingMessageGroupProcessor and implement aggregatePayloads().

Also, since version 4.2, a SimpleMessageGroupProcessor is provided; which simply returns the collection of messages from the group, which, as indicated above, causes the released messages to be sent individually.

This allows the aggregator to work as a message barrier where arriving messages are held until the release strategy fires, and the group is released, as a sequence of individual messages.


The ReleaseStrategy interface is defined as follows:

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:

public class MyReleaseStrategy {

    public boolean canMessagesBeReleased(List<Message<?>>) {...}
public class MyReleaseStrategy {

    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.


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.


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 Section 6.4.5, “Managing State in an Aggregator: MessageGroupStore”.

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.

If you are aggregating large groups, you don’t need to release partial groups, and you don’t need to detect/reject duplicate sequences, consider using the SimpleSequenceSizeReleaseStrategy instead - it is much more efficient for these use cases, and will be the default in future releases when partial group release is not specified.

Aggregating Large Groups

The 4.3 release changed the default Collection for messages in a SimpleMessageGroup to HashSet (it was previously a BlockingQueue). This was expensive when removing individual messages from large groups (an O(n) linear scan was required). Although the hash set is generally much faster for removing, it can be expensive for large messages because the hash has to be calculated (on both inserts and removes). If you have messages that are expensive to hash, consider using some other collection type. As discussed in Section 9.4.1, “MessageGroupFactory”, a SimpleMessageGroupFactory is provided so you can select the Collection that best suits your needs. You can also provide your own factory implementation to create some other Collection<Message<?>>.

Here is an example of how to configure an aggregator with the previous implementation and a SimpleSequenceSizeReleaseStrategy.

<int:aggregator input-channel="aggregate"
    output-channel="out" message-store="store" release-strategy="releaser" />

<bean id="store" class="org.springframework.integration.store.SimpleMessageStore">
    <property name="messageGroupFactory">
        <bean class="org.springframework.integration.store.SimpleMessageGroupFactory">
            <constructor-arg value="BLOCKING_QUEUE"/>

<bean id="releaser" class="SimpleSequenceSizeReleaseStrategy" />


The CorrelationStrategy interface is defined as follows:

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.


Changes to groups are thread safe; a LockRegistry is used to obtain a lock for the resolved correlation id. A DefaultLockRegistry is used by default (in-memory). For synchronizing updates across servers, where a shared MessageGroupStore is being used, a shared lock registry must be configured. See Section 6.4.4, “Configuring an Aggregator” below for more information.

6.4.4 Configuring an Aggregator

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.

<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-upon-timeout="true"  (23)

        scheduler="taskScheduler" >  (24)
            <expire-transactional/>  (25)
            <expire-advice-chain/>  (26)

<int:channel id="outputChannel"/>

<int:channel id="throwAwayChannel"/>

<bean id="persistentMessageStore" class="org.springframework.integration.jdbc.JdbcMessageStore">
    <constructor-arg ref="dataSource"/>

<bean id="aggregatorBean" class="sample.PojoAggregator"/>

<bean id="releaseStrategyBean" class="sample.PojoReleaseStrategy"/>

<bean id="correlationStrategyBean" class="sample.PojoCorrelationStrategy"/>


The id of the aggregator is Optional.


Lifecycle attribute signaling if aggregator should be started during Application Context startup. Optional (default is true).


The channel from which where aggregator will receive messages. Required.


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).


The channel to which the aggregator will send the messages that timed out (if send-partial-result-on-expiry is false). Optional.


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.


Order of this aggregator when more than one handle is subscribed to the same DirectChannel (use for load balancing purposes). Optional.


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.expireMessageGroups(timeout). 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-upon-timeout is set to false.


The timeout interval to wait when sending a reply Message to the output-channel or discard-channel. Defaults to -1 - blocking indefinitely. 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.


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).


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).


A SpEL expression representing the correlation strategy. Example: "headers['foo']". Only one of correlation-strategy or correlation-strategy-expression is allowed.


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).


A method defined on the bean referenced by ref, that implements the message aggregation algorithm. Optional, depends on ref attribute being defined.


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).


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).


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.


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.


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.


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 ZookeeperLockRegistry, ensures only one instance of the aggregator will operate on a group concurrently. See Section 24.11, “Redis Lock Registry”, Section 16.6, “Gemfire Lock Registry”, Section 37.3, “Zookeeper Lock Registry” for more information.


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 the section called “Aggregator and Group Timeout” for more information. Mutually exclusive with group-timeout-expression attribute.


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.


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.


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.


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.


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.


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:

<aggregator input-channel="input" method="sum" output-channel="output">
    <beans:bean class="org.foo.PojoAggregator"/>

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:

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:

public class PojoReleaseStrategy {
  public boolean canRelease(List<Long> numbers) {
    int sum = 0;
    for (long number: numbers) {
      sum += number;
    return sum >= maxValue;

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:

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.


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 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).

public String[] processRelease(List<Message<String>> messages){
    List<String> stringList = new ArrayList<String>();
    for (Message<String> message : messages) {
    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.

<int:aggregator input-channel="aggChannel"

In the above configuration we are using a 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:


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:

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.

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:

<aggregator input-channel="input" output-channel="output"
        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 Section 6.4.4, “Configuring an Aggregator”). 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).

Configuring an Aggregator with Annotations

An aggregator configured using annotations would look like this.

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) {


An annotation indicating that this method shall be used as an aggregator. Must be specified if this class will be used as an aggregator.


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.


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.

Annotation configuration (@Aggregator and others) for the Aggregator component covers only simple use cases, where most default options are sufficient. If you need more control over those options using Annotation configuration, consider using a @Bean definition for the AggregatingMessageHandler and mark its @Bean method with @ServiceActivator:

@ServiceActivator(inputChannel = "aggregatorChannel")
public MessageHandler aggregator(MessageGroupStore jdbcMessageGroupStore) {
     AggregatingMessageHandler aggregator =
                       new AggregatingMessageHandler(new DefaultAggregatingMessageGroupProcessor(),
     aggregator.setGroupTimeoutExpression(new ValueExpression<>(500L));
     return aggregator;

See Section 6.4.3, “Programming model” and Section F.6.2, “Annotations on @Beans” for more information.


Starting with the version 4.2 the AggregatorFactoryBean is available, to simplify Java configuration for the AggregatingMessageHandler.

6.4.5 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.

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 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:

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:

<bean id="reaper" class="org...MessageGroupStoreReaper">
    <property name="messageGroupStore" ref="messageStore"/>
    <property name="timeout" value="30000"/>

<task:scheduled-tasks scheduler="scheduler">
    <task:scheduled ref="reaper" method="run" fixed-rate="10000"/>

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.


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.


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 Section 9.4, “Message Store”.

6.5 Resequencer

6.5.1 Introduction

Related to the Aggregator, albeit different from a functional standpoint, is the Resequencer.

6.5.2 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.

6.5.3 Configuring a Resequencer

Configuring a resequencer requires only including the appropriate element in XML.

A sample resequencer configuration is shown below.

<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)


The id of the resequencer is optional.


The input channel of the resequencer. Required.


The channel to which the resequencer will send the reordered messages. Optional.


The channel to which the resequencer will send the messages that timed out (if send-partial-result-on-timeout is false). Optional.


Whether to send out ordered sequences as soon as they are available, or only after the whole message group arrives. Optional (false by default).


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.


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 Section 6.4.5, “Managing State in an Aggregator: MessageGroupStore”.


The timeout interval to wait when sending a reply Message to the output-channel or discard-channel. Defaults to -1 - blocking indefinitely. 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.


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).


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).


A SpEL expression representing the correlation strategy. Example: "headers['foo']". Only one of correlation-strategy or correlation-strategy-expression is allowed.


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).


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).


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.


Only applies if a MessageGroupStoreReaper is configured for the <resequcencer> 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.


See the section called “Configuring an Aggregator with XML”.


See the section called “Configuring an Aggregator with XML”.


See the section called “Configuring an Aggregator with XML”.


See the section called “Configuring an Aggregator with XML”.


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.


Since there is no custom behavior to be implemented in Java classes for resequencers, there is no annotation support for it.

6.6 Message Handler Chain

6.6.1 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 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.


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.


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.

6.6.2 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.

<int:chain input-channel="input" output-channel="output">
    <int:filter ref="someSelector" throw-exception-on-rejection="true"/>
        <int:header name="foo" value="bar"/>
    <int:service-activator ref="someService" method="someMethod"/>

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>:

<int:chain input-channel="input">
    <int-xml:marshalling-transformer marshaller="marshaller" result-type="StringResult" />
    <int:service-activator ref="someService" method="someMethod"/>
        <int:header name="foo" value="bar"/>
    <int:logging-channel-adapter level="INFO" log-full-message="true"/>

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.


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:

<int:chain id="fooChain" input-channel="input">
    <int:service-activator id="fooService" ref="someService" method="someMethod"/>
  • 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 export and they are trackable via Message History. They can also be accessed from the BeanFactory using the appropriate bean name as discussed above.


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:

<int:chain id="main-chain" input-channel="in" output-channel="out">
      <int:header name="name" value="Many" />
      <bean class="org.foo.SampleService" />
    <int:gateway request-channel="inputA"/>  

<int:chain id="nested-chain-a" input-channel="inputA">
        <int:header name="name" value="Moe" />
    <int:gateway request-channel="inputB"/> 
        <bean class="org.foo.SampleService" />

<int:chain id="nested-chain-b" input-channel="inputB">
        <int:header name="name" value="Jack" />
        <bean class="org.foo.SampleService" />

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.

6.7 Scatter-Gather

6.7.1 Introduction

Starting with version 4.1, Spring Integration provides an implementation of the 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.

6.7.2 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 Section 6.4, “Aggregator” for more information.


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 Section 7.2, “Content Enricher”) but, in this case, the end-user should support his own custom correlationStrategy for the aggregation function.


The Distribution Scatter-Gather variant is based on the RecipientListRouter (see the section called “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.

6.7.3 Configuring a Scatter-Gather Endpoint

For Java and Annotation configuration, the bean definition for the Scatter-Gather is:

public MessageHandler distributor() {
    RecipientListRouter router = new RecipientListRouter();
    router.setChannels(Arrays.asList(distributionChannel1(), distributionChannel2(),
    return router;

public MessageHandler gatherer() {
	return new AggregatingMessageHandler(
			new ExpressionEvaluatingMessageGroupProcessor("^[payload gt 5] ?: -1D"),
			new SimpleMessageStore(),
			new HeaderAttributeCorrelationStrategy(
			new ExpressionEvaluatingReleaseStrategy("size() == 2"));

@ServiceActivator(inputChannel = "distributionChannel")
public MessageHandler scatterGatherDistribution() {
	ScatterGatherHandler handler = new ScatterGatherHandler(distributor(), gatherer());
	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:

		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


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).


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).


The channel to receive request messages to handle them in the ScatterGatherHandler. Required.


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).


The channel to send the scatter message for the Auction scenario. Optional. Mutually exclusive with <scatterer> sub-element.


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.


Order of this component when more than one handler is subscribed to the same DirectChannel (use for load balancing purposes). Optional.


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.


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.


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.


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.


The <recipient-list-router> options. Optional. Mutually exclusive with scatter-channel attribute.


The <aggregator> options. Required.

6.8 Thread Barrier

Sometimes, we need to suspend a message flow thread until some other asynchronous event occurs. For example, consider an HTTP request that publishes a message to RabbitMQ. We might wish to not reply to the user until the RabbitMQ broker has issued an acknowledgment that the message was received.

Spring Integration version 4.2 introduced the <barrier/> component for this purpose. The underlying MessageHandler is the BarrierMessageHandler; this class also implements MessageTriggerAction where a message passed to the trigger() method releases a corresponding thread in the handleRequestMessage() method (if present).

The suspended thread and trigger thread are correlated by invoking a CorrelationStrategy on the messages. When a message is sent to the input-channel, the thread is suspended for up to timeout milliseconds, waiting for a corresponding trigger message. The default correlation strategy uses the IntegrationMessageHeaderAccessor.CORRELATION_ID header. When a trigger message arrives with the same correlation, the thread is released. The message sent to the output-channel after release is constructed using a MessageGroupProcessor. By default, the message is a Collection<?> of the two payloads and the headers are merged, using a DefaultAggregatingMessageGroupProcessor.


If the trigger() method is invoked first (or after the main thread times out), it will be suspended for up to timeout waiting for the suspending message to arrive. If you do not want to suspend the trigger thread, consider handing off to a TaskExecutor instead so its thread will be suspended instead.

The requires-reply property determines the action if the suspended thread times out before the trigger message arrives. By default, it is false which means the endpoint simply returns null, the flow ends and the thread returns to the caller. When true, a ReplyRequiredException is thrown.

You can call the trigger() method programmatically (obtain the bean reference using the name barrier.handler - where barrier is the bean name of the barrier endpoint) or you can configure an <outbound-channel-adapter/> to trigger the release.


Only one thread can be suspended with the same correlation; the same correlation can be used multiple times but only once concurrently. An exception is thrown if a second thread arrives with the same correlation.

<int:barrier id="barrier1" input-channel="in" output-channel="out"

<int:outbound-channel-adapter channel="release" ref="barrier1.handler" method="trigger" />

In this example, a custom header is used for correlation. Either the thread sending a message to in or the one sending a message to release will wait for up to 10 seconds until the other arrives. When the message is released, the out channel will be sent a message combining the result of invoking the custom MessageGroupProcessor bean myOutputProcessor. If the main thread times out and a trigger arrives later, you can configure a discard channel to which the late trigger will be sent. Java configuration is shown below.

public class Config {

    public BarrierMessageHandler barrier() {
        BarrierMessageHandler barrier = new BarrierMessageHandler(10000);
        return barrier;

    @ServiceActivator (inputChannel="release")
    public MessageHandler releaser() {
        return new MessageHandler() {

            public void handleMessage(Message<?> message) throws MessagingException {



See the barrier sample application for an example of this component.

7. Message Transformation

7.1 Transformer

7.1.1 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 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.


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 Chapter 35, XML Support - Dealing with XML Payloads.

7.1.2 Configuring Transformer

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.

<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:

<int:transformer id="testTransformer" input-channel="inChannel" method="transform"
  <beans:bean class="org.foo.TestTransformer"/>

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.


If the "ref" attribute references a bean that extends AbstractMessageProducingHandler (such as transformers provided by the framework itself), the configuration is optimized by injecting the output channel into the handler directly. In this case, each "ref" must be to a separate bean instance (or a prototype-scoped bean), or use the inner <bean/> configuration type. If you inadvertently reference the same message handler from multiple beans, you will get a configuration exception.

When using a POJO, 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://docs.spring.io/spring/docs/current/spring-framework-reference/html/expressions.html) whenever transformation logic is relatively simple.

<int:transformer input-channel="inChannel"
	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.

Object-to-String Transformer

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.

<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.


When debugging, this transformer is not typically necessary since the logging-channel-adapter is capable of logging the Message payload. Refer to the section called “Wire Tap” for more detail.


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:

<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.

<int:payload-serializing-transformer input-channel="objectsIn" output-channel="bytesOut"/>

<int:payload-deserializing-transformer input-channel="bytesIn" output-channel="objectsOut"/>
Object-to-Map and Map-to-Object Transformers

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:

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:

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:

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:

<int:object-to-map-transformer input-channel="directInput" output-channel="output"/>


<int:object-to-map-transformer input-channel="directInput" output-channel="output" flatten="false"/>


<int:map-to-object-transformer input-channel="input" 


<int:map-to-object-transformer input-channel="inputA" 
<bean id="person" class="org.foo.Person" scope="prototype"/>

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. 

Stream Transformer

The StreamTransformer transforms InputStream payloads to a byte[] or a String if a charset is provided.

<int:stream-transformer input-channel="directInput" output-channel="output"/> <!-- byte[] -->

<int:stream-transformer id="withCharset" charset="UTF-8"
    input-channel="charsetChannel" output-channel="output"/> <!-- String -->
@Transformer(inputChannel = "stream", outputChannel = "data")
public StreamTransformer streamToBytes() {
    return new StreamTransformer(); // transforms to byte[]

@Transformer(inputChannel = "stream", outputChannel = "data")
public StreamTransformer streamToString() {
    return new StreamTransformer("UTF-8"); // transforms to String
JSON Transformers

Object to JSON and JSON to Object transformers are provided.

<int:object-to-json-transformer input-channel="objectMapperInput"/>
<int:json-to-object-transformer input-channel="objectMapperInput"

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).

<int:json-to-object-transformer input-channel="objectMapperInput"
    type="foo.MyDomainObject" object-mapper="customObjectMapper"/>

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 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.


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:

public class Foo {

        public Object bar;


You may wish to consider using a FactoryBean or simple factory method to create the JsonObjectMapper with the required characteristics.

public class ObjectMapperFactory {

    public static Jackson2JsonObjectMapper getMapper() {
        ObjectMapper mapper = new ObjectMapper();
        mapper.configure(JsonParser.Feature.ALLOW_COMMENTS, true);
        return new Jackson2JsonObjectMapper(mapper);
<bean id="customObjectMapper" class="foo.ObjectMapperFactory"

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 JsonMessageConverter.

This enables the following flows to work without any special configuration…​



Where the outbound adapter is configured with a JsonMessageConverter and the inbound adapter uses the default SimpleMessageConverter.



Where the outbound adapter is configured with a SimpleMessageConverter and the inbound adapter uses the default JsonMessageConverter.



Where both adapters are configured with a SimpleMessageConverter.


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 Appendix A, Spring Expression Language (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 Section 35.9, “#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 Section A.4, “PropertyAccessors”. When using Boon, the NODE representation is a Map<String, Object>

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.

Order generateOrder(String productId) {
    return new Order(productId);

Transformer methods may also accept the @Header and @Headers annotations that is documented in Section F.6, “Annotation Support”

Order generateOrder(String productId, @Header("customerName") String customer) {
    return new Order(productId, customer);

Also see Section 8.9.7, “Advising Endpoints Using Annotations”.

7.1.3 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 Section 7.2.2, “Header Enricher”.

<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.

7.1.4 Codec-Based Transformers

See Section 7.4, “Codec”.

7.2 Content Enricher

7.2.1 Introduction

At times you may have a requirement to enhance a request with more information than was provided by the target system. The 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:

Furthermore, several Adapter specific Header Enrichers are included as well:

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 Appendix A, Spring Expression Language (SpEL).

7.2.2 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.

<int:header-enricher input-channel="in" output-channel="out">
    <int:header name="foo" value="123"/>
    <int:header name="bar" ref="someBean"/>

The Header Enricher also provides helpful sub-elements to set well-known header names.

<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"/>

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 the section called “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:

<int:header-enricher input-channel="in" output-channel="out">
    <int:header name="foo" method="computeValue" ref="myBean"/>

<bean id="myBean" class="foo.bar.MyBean"/>
public class MyBean {

    public String computeValue(String payload){
        return payload.toUpperCase() + "_US";

You can also configure your POJO as inner bean:

<int:header-enricher  input-channel="inputChannel" output-channel="outputChannel">
    <int:header name="some_header">
        <bean class="org.MyEnricher"/>

as well as point to a Groovy script:

<int:header-enricher  input-channel="inputChannel" output-channel="outputChannel">
    <int:header name="some_header">
        <int-groovy:script location="org/SampleGroovyHeaderEnricher.groovy"/>

SpEL Support

In Spring Integration 2.0 we have introduced the convenience of the 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.

<int:header-enricher input-channel="in" output-channel="out">
    <int:header name="foo" expression="payload.toUpperCase() + '_US'"/>

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.

Configuring a Header Enricher with Java Configuration

The following are some examples of Java Configuration for header enrichers:

@Transformer(inputChannel = "enrichHeadersChannel", outputChannel = "emailChannel")
public HeaderEnricher enrichHeaders() {
    Map<String, ? extends HeaderValueMessageProcessor<?>> headersToAdd =
                      new StaticHeaderValueMessageProcessor<>(this.imapUrl));
    HeaderEnricher enricher = new HeaderEnricher(headersToAdd);
    return enricher;

@Transformer(inputChannel="enrichHeadersChannel", outputChannel="emailChannel")
public HeaderEnricher enrichHeaders() {
    Map<String, HeaderValueMessageProcessor<?>> headersToAdd = new HashMap<>();
    headersToAdd.put("emailUrl", new StaticHeaderValueMessageProcessor<String>(this.imapUrl));
    Expression expression = new SpelExpressionParser().parseExpression("payload.from[0].toString()");
               new ExpressionEvaluatingHeaderValueMessageProcessor<>(expression, String.class));
    HeaderEnricher enricher = new HeaderEnricher(headersToAdd);
    return enricher;

The first adds a single literal header. The second adds two headers - a literal header and one based on a SpEL expression.

Configuring a Header Enricher with the Java DSL

The following is an example of Java DSL Configuration for a header enricher:

public IntegrationFlow enrichHeadersInFlow() {
    return f -> f
                .enrichHeaders(h -> h.header("emailUrl", this.emailUrl)
                                     .headerExpression("from", "payload.from[0].toString()"))

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:


This sub-element is a convenience only, and is the equivalent of specifying:

    overwrite="true" />
    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:

<int:header-enricher input-channel="inputTtl" output-channel="next">
    <int:header-channels-to-string time-to-live-expression="120000" />

<int:header-enricher input-channel="inputCustomTtl" output-channel="next">
        time-to-live-expression="headers['channelTTL'] ?: 120000" />

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.

7.2.3 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.


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.


Below, please find an overview of all available configuration options that are available for the payload enricher:

<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=""/>


Channel to which a Message will be sent to get the data to use for enrichment. Optional.


Lifecycle attribute signaling if this component should be started during Application Context startup. Defaults to true.Optional.


Id of the underlying bean definition, which is either an EventDrivenConsumer or a PollingConsumer. Optional.


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.


Identifies the Message channel where a Message will be sent after it is being processed by this endpoint.Optional.


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'.


Channel where a reply Message is expected. This is optional; typically the auto-generated temporary reply channel is sufficient. Optional.


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.


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.


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.


Allows you to configure a Message Poller if this endpoint is a Polling Consumer. Optional.


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.


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.


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.

<int:enricher id="findUserEnricher"
    <int:property name="email"    expression="payload.email"/>
    <int:property name="password" expression="payload.password"/>

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 although only the username is passed on, the resulting message send to the request channel will contain the full set of MessageHeaders.

<int:enricher id="findUserByUsernameEnricher"
    <int:property name="email"    expression="payload.email"/>
    <int:property name="password" expression="payload.password"/>

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.

<int:enricher id="findUserWithMapEnricher"
    <int:property name="user" expression="payload"/>

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 loosely here. You can still use SpEL expressions for setting those values.

<int:enricher id="userEnricher"
    <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"/>

7.3 Claim Check

7.3.1 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 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.

7.3.2 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.

<int:claim-check-in id="checkin"

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:

<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


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.


Id identifying the underlying bean definition (MessageTransformingHandler). Attribute is not available inside a Chain element. Optional.


The receiving Message channel of this endpoint. Attribute is not available inside a Chain element. Optional.


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.


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.


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.


Specify the maximum amount of time in milliseconds to wait when sending a reply Message to the output channel. Defaults to -1 - blocking indefinitely. Attribute is not available inside a Chain element. Optional.


Defines a poller. Element is not available inside a Chain element. Optional.

7.3.3 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.

<int:claim-check-out id="checkout"

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:

<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


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.


Id identifying the underlying bean definition (MessageTransformingHandler). Attribute is not available inside a Chain element. Optional.


The receiving Message channel of this endpoint. Attribute is not available inside a Chain element. Optional.


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.


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.


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.


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.


Specify the maximum amount of time in milliseconds to wait when sending a reply Message to the output channel. Defaults to -1 - blocking indefinitely. Attribute is not available inside a Chain element. Optional.


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.

<int:claim-check-out id="checkout"

7.3.4 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.

7.4 Codec

7.4.1 Introduction

Spring Integration version 4.2 introduces the Codec abstraction. Codecs are used to encode/decode objects to/from byte[]. They are an alternative to Java Serialization. One advantage is, typically, objects do not have to implement Serializable. One implementation, using Kryo for serialization, is provided but you can provide your own implementation for use in any of these components:

  • EncodingPayloadTransformer
  • DecodingTransformer
  • CodecMessageConverter

See their JavaDocs for more information.

7.4.2 EncodingPayloadTransformer

This transformer encodes the payload to a byte[] using the codec. It does not affect message headers.

7.4.3 DecodingTransformer

This transformer decodes a byte[] using the codec; it needs to be configured with the Class to which the object should be decoded (or an expression that resolves to a Class). If the resulting object is a Message<?>, inbound headers will not be retained.

7.4.4 CodecMessageConverter

Certain endpoints (e.g. TCP, Redis) have no concept of message headers; they support the use of a MessageConverter and the CodecMessageConverter can be used to convert a message to/from a byte[] for transmission.

7.4.5 Kryo

Currently, this is the only implementation of Codec. There are two Codec s - PojoCodec which can be used in the transformers and MessageCodec which can be used in the CodecMessageConverter.

Several custom serializers are provided by the framework:

  • FileSerializer
  • MessageHeadersSerializer
  • MutableMessageHeadersSerializer

The first can be used with the PojoCodec, by initializing it with the FileKryoRegistrar. The second and third are used with the MessageCodec, which is initialized with the MessageKryoRegistrar.

Customizing Kryo

By default, Kryo delegates unknown Java types to its FieldSerializer. Kryo also registers default serializers for each primitive type along with String, Collection and Map serializers. FieldSerializer uses reflection to navigate the object graph. A more efficient approach is to implement a custom serializer that is aware of the object’s structure and can directly serialize selected primitive fields:

public class AddressSerializer extends Serializer<Address> {

    public void write(Kryo kryo, Output output, Address address) {

    public Address read(Kryo kryo, Input input, Class<Address> type) {
        return new Address(input.readString(), input.readString(), input.readString());

The Serializer interface exposes Kryo, Input, and Output which provide complete control over which fields are included and other internal settings as described in the documentation.


When registering your custom serializer, you need a registration ID. The registration IDs are arbitrary but in our case must be explicitly defined because each Kryo instance across the distributed application must use the same IDs. Kryo recommends small positive integers, and reserves a few ids (value < 10). Spring Integration currently defaults to using 40, 41 and 42 (for the file and message header serializers mentioned above); we recommend you start at, say 60, to allow for expansion in the framework. These framework defaults can be overridden by configuring the registrars mentioned above.

Using a Custom Kryo Serializer

If custom serialization is indicated, please consult the Kryo documentation since you will be using the native API. For an example, see the MessageCodec.

Implementing KryoSerializable

If you have write access to the domain object source code it may implement KryoSerializable as described here. In this case the class provides the serialization methods itself and no further configuration is required. This has the advantage of being much simpler to use with XD, however benchmarks have shown this is not quite as efficient as registering a custom serializer explicitly:

public class Address implements KryoSerializable {

    public void write(Kryo kryo, Output output) {

    public void read(Kryo kryo, Input input) {
        this.street = input.readString();
        this.city = input.readString();
        this.country = input.readString();

Note that this technique can also be used to wrap a serialization library other than Kryo.

Using DefaultSerializer Annotation

Kryo also provides an annotation as described here.

public class SomeClass {
       // ...

If you have write access to the domain object this may be a simpler alternative to specify a custom serializer. Note this does not register the class with an ID, so your mileage may vary.

8. Messaging Endpoints

8.1 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 toSection 8.1.4, “Namespace Support” 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 Section 4.1, “Message Channels”, 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: Polling Consumers and 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.

8.1.1 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:

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.

8.1.2 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 the section called “SubscribableChannel”):


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:

SubscribableChannel channel = context.getBean("subscribableChannel", SubscribableChannel.class);

EventDrivenConsumer consumer = new EventDrivenConsumer(channel, exampleHandler);

8.1.3 Polling Consumer

Spring Integration also provides a PollingConsumer, and it can be instantiated in the same way except that the channel must implement PollableChannel:

PollableChannel channel = context.getBean("pollableChannel", PollableChannel.class);

PollingConsumer consumer = new PollingConsumer(channel, exampleHandler);

For more information regarding Polling Consumers, please also read Section 4.2, “Poller” as well as Section 4.3, “Channel Adapter”.

There are many other configuration options for the Polling Consumer. For example, the trigger is a required property:

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):

IntervalTrigger trigger = new IntervalTrigger(1000);

The CronTrigger simply requires a valid cron expression (see the Javadoc for details):

CronTrigger trigger = new CronTrigger("*/10 * * * * MON-FRI");

In addition to the trigger, several other polling-related configuration properties may be specified:

PollingConsumer consumer = new PollingConsumer(channel, handler);


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:

PollingConsumer consumer = new PollingConsumer(channel, handler);

TaskExecutor taskExecutor = context.getBean("exampleExecutor", TaskExecutor.class);

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 Section 8.1.4, “Namespace Support”.

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.


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.

8.1.4 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:

<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


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.


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.


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.


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.


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.


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").


Please see Section 4.3.1, “Configuring An Inbound Channel Adapter” 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.


Value is set on the underlying class `PollerMetadata`Optional. If not specified it defaults to 1000 (milliseconds).


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-delay.


Provides the ability to reference a custom task executor. Please see the section below titled TaskExecutor Support for further information. Optional.


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.


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.


Allows to specify extra AOP Advices to handle additional cross cutting concerns. Please see the section below titled Transaction Support for further information. Optional.


Pollers can be made transactional. Please see the section below titled AOP Advice chains for further information. Optional.


For example, a simple interval-based poller with a 1-second interval would be configured like this:

<int:transformer input-channel="pollable"
    <int:poller fixed-rate="1000"/>

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:

<int:transformer input-channel="pollable"
    <int:poller cron="*/10 * * * * MON-FRI"/>

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:

<int:poller id="weekdayPoller" cron="*/10 * * * * MON-FRI"/>

<int:transformer input-channel="pollable"
    <int:poller ref="weekdayPoller"/>

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.

<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"

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:

<int:poller fixed-delay="1000">
    <int:transactional transaction-manager="txManager"

For more information please refer to Section C.1.1, “Poller Transaction Support”.

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…​

<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">
			<ref bean="adviceA" />
			<beans:bean class="org.bar.SampleAdvice" />
			<ref bean="txAdvice" />

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.


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 Section C.1.1, “Poller Transaction Support” 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:

<int:poller task-executor="pool" fixed-rate="1000"/>

<task:executor id="pool"

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 Section F.3, “Configuring the Task Scheduler”). 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.

<int:service-activator input-channel="someQueueChannel"
    <int:poller receive-timeout="30000" fixed-rate="10"/>


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.

8.1.5 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 definition 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.


The sample provides a custom Trigger which implements the org.springframework.scheduling.Trigger interface. The sample’s Trigger is based on Spring’s 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.


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.

8.1.6 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:

<int:converter ref="sampleConverter"/>

<bean id="sampleConverter" class="foo.bar.TestConverter"/>

or as an inner bean:

    <bean class="o.s.i.config.xml.ConverterParserTests$TestConverter3"/>

Starting with Spring Integration 4.0, the above configuration is available using annotations:

public class TestConverter implements Converter<Boolean, Number> {

	public Number convert(Boolean source) {
		return source ? 1 : 0;


or as a @Configuration part:

public class ContextConfiguration {

	public SerializingConverter serializingConverter() {
		return new SerializingConverter();


When configuring an Application Context, the Spring Framework allows you to add a conversionService bean (see 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:

<alias name="conversionService" alias="integrationConversionService"/>

In this case the conversionService's Converters will be available for Spring Integration runtime conversion.

8.1.7 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:

<int:channel id="publishChannel">
    <int:queue />

<int:service-activator input-channel="publishChannel" ref="myService">
	<int:poller receive-timeout="5000" task-executor="taskExecutor" fixed-rate="50" />

<task:executor id="taskExecutor" pool-size="20" />

The above configuration demonstrates one of those out of tune configurations.

By default, the task executor has an unbounded task queue. 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; and even 0 is a reasonable value. 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 Task Execution and Scheduling of the Spring reference manual for more detail on the subject.

8.1.8 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:

<int:service-activator id="exampleServiceActivator" input-channel="inChannel"
            output-channel = "outChannel" method="foo">
    <beans:bean class="org.foo.ExampleServiceActivator"/>

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 Spring Documentation for more information.

8.2 Endpoint Roles

Starting with version 4.2, endpoints can be assigned to roles. Roles allow endpoints to be started and stopped as a group; this is particularly useful when using leadership election where a set of endpoints can be started or stopped when leadership is granted or revoked respectively.

You can assign endpoints to roles using XML, Java configuration, or programmatically:

<int:inbound-channel-adapter id="ica" channel="someChannel" expression="'foo'" role="cluster">
    <int:poller fixed-rate="60000" />
@ServiceActivator(inputChannel = "sendAsyncChannel")
public MessageHandler sendAsyncHandler() {
    return // some MessageHandler
public String handle(String payload) {
    return payload.toUpperCase();
private SmartLifecycleRoleController roleController;


    this.roleController.addSmartLifeCycleToRole("cluster", someEndpoint);

Each of these adds the endpoint to the role cluster.

Invoking roleController.startLifecyclesInRole("cluster") (and the corresponding stop... method) will start/stop the endpoints.


Any object implementing SmartLifecycle can be programmatically added, not just endpoints.

The SmartLifecycleRoleController implements ApplicationListener<AbstractLeaderEvent> and it will automatically start/stop its configured SmartLifecycle objects when leadership is granted/revoked (when some bean publishes OnGrantedEvent or OnRevokedEvent respectively).


When using leadership election to start/stop components, it is important to set the auto-startup XML attribute (autoStartup bean property) to false so the application context does not start the components during context intialization.

Starting with _version 4.3.8, the SmartLifecycleRoleController provides several status methods:

public Collection<String> getRoles() 1

public boolean allEndpointsRunning(String role) 2

public boolean noEndpointsRunning(String role) 3

public Map<String, Boolean> getEndpointsRunningStatus(String role) 4


Returns a list of the roles being managed.


Returns true if all endpoints in the role are running.


Returns true if none of the endpoints in the role are running.


Returns a map of component name : running status - the component name is usually the bean name.

8.3 Leadership Event Handling

Groups of endpoints can be started/stopped based on leadership being granted or revoked respectively. This is useful in clustered scenarios where shared resources must only be consumed by a single instance. An example of this is a file inbound channel adapter that is polling a shared directory. (See Section 14.2, “Reading Files”).

To participate in a leader election and be notified when elected leader or when leadership is revoked, an application creates a component in the application context called a "leader initiator". Normally a leader initiator is a SmartLifecycle so it starts up (optionally) automatically when the context starts, and then publishes notifications when leadership changes. By convention the user provides a Candidate that receives the callbacks and also can revoke the leadership through a Context object provided by the framework. User code can also listen for AbstractLeaderEvents, and respond accordingly, for instance using a SmartLifecycleRoleController.

There is a basic implementation of a leader initiator based on the LockRegistry abstraction. To use it you just need to create an instance as a bean, for example:

public LockRegistryLeaderInitiator leaderInitiator(LockRegistry locks) {
    return new LockRegistryLeaderInitiator(locks);

If the lock registry is implemented correctly, there will only ever be at most one leader. If the lock registry also provides locks which throw exceptions (ideally InterruptedException) when they expire or are broken, then the duration of the leaderless periods can be as short as is allowed by the inherent latency in the lock implementation. By default there is a busyWaitMillis property that adds some additional latency to prevent CPU starvation in the (more usual) case that the locks are imperfect and you only know they expired by trying to obtain one again.

See Section 37.4, “Zookeeper Leadership Event Handling” for more information about leadership election and events using Zookeeper.

8.4 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.

8.4.1 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:

package org.cafeteria;

public interface Cafe {

    void placeOrder(Order order);


8.4.2 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.

<int:gateway id="cafeService"

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).

The defaults in the configuration above are applied to all methods on the gateway interface; if a reply timeout is not specified, the calling thread will wait indefinitely for a reply. See Section 8.4.10, “Gateway behavior when no response arrives”.

The defaults can be overridden for individual methods; see Section 8.4.4, “Gateway Configuration with Annotations and/or XML”.

8.4.3 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.

8.4.4 Gateway Configuration with Annotations and/or XML

public interface Cafe {

    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:

public interface FileWriter {

    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.

<int:gateway id="myGateway" service-interface="org.foo.bar.TestGateway"
  <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"/>

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.

<int:gateway id="loanBrokerGateway"
  <int:method name="getLoanQuote" request-channel="loanBrokerPreProcessingChannel">
    <int:header name="RESPONSE_TYPE" value="BEST"/>
  <int:method name="getAllLoanQuotes" request-channel="loanBrokerPreProcessingChannel">
    <int:header name="RESPONSE_TYPE" value="ALL"/>

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.


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.


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).

8.4.5 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.

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):

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);

    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);



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:

<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()"/>

8.4.6 @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:

<int:gateway id="myGateway" service-interface="org.foo.bar.TestGateway"
  <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 name="echoViaDefault"/>
@MessagingGateway(name = "myGateway", defaultRequestChannel = "inputC",
		  defaultHeaders = @GatewayHeader(name = "calledMethod",
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. The standard @ComponentScan infrastructure doesn’t deal with interfaces, therefore the custom @IntegrationComponentScan logic has been introduced to determine @MessagingGateway annotation on the interfaces and register GatewayProxyFactoryBean s for them. See also Section F.6, “Annotation Support”


If you have no XML configuration, the @EnableIntegration annotation is required on at least one @Configuration class. See Section 3.5, “Configuration and @EnableIntegration” for more information.

8.4.7 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:

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.

8.4.8 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, the 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.

<int:gateway id="sampleGateway"

<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.


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.


If the downstream flow returns an ErrorMessage, its payload (a Throwable) is treated as a regular downstream error: if there is an error-channel configured, it will be sent there, to the error flow; otherwise the payload is thrown to the caller of gateway. Similarly, if the error flow on the error-channel returns an ErrorMessage its payload is thrown to the caller. The same applies to any message with a Throwable payload. This can be useful in async situations when when there is a need propagate an Exception directly to the caller. To achieve this you can either return an Exception as the reply from some service, or simply throw it. Generally, even with an async flow, the framework will take care of propagating an exception thrown by the downstream flow back to the gateway. The TCP Client-Server Multiplex sample demonstrates both techniques to return the exception to the caller. It emulates a Socket IO error to the waiting thread using an aggregator with group-timeout (see the section called “Aggregator and Group Timeout”) and MessagingTimeoutException reply on the discard flow.

8.4.9 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.

<int:gateway id="mathService" 

However the Gateway Interface (service-interface) is a little different:

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.

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 async-gateway sample distributed within the Spring Integration samples.


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.

ListenableFuture<String> result = this.asyncGateway.async("foo");
result.addCallback(new ListenableFutureCallback<String>() {

    public void onSuccess(String result) {

    public void onFailure(Throwable t) {


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. Also see the section called “CompletableFuture” below. 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):

public AsyncTaskExecutor exec() {
    SimpleAsyncTaskExecutor simpleAsyncTaskExecutor = new SimpleAsyncTaskExecutor();
    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:

@MessagingGateway(asyncExecutor = AnnotationConstants.NULL)
public interface NoExecGateway {

    @Gateway(requestChannel = "gatewayChannel")
    Future<?> doAsync(String foo);


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.


Starting with version 4.2, gateway methods can now return CompletableFuture<?>. There are several modes of operation when returning this type:

When an async executor is provided and the return type is exactly CompletableFuture (not a subclass), the framework will run the task on the executor and immediately return a CompletableFuture to the caller. CompletableFuture.supplyAsync(Supplier<U> supplier, Executor executor) is used to create the future.

When the async executor is explicitly set to null and the return type is CompletableFuture or the return type is a subclass of CompletableFuture, the flow is invoked on the caller’s thread. In this scenario, it is expected that the downstream flow will return a CompletableFuture of the appropriate type.

Usage Scenarios

CompletableFuture<Invoice> order(Order order);
<int:gateway service-interface="foo.Service" default-request-channel="orders" />

In this scenario, the caller thread returns immediately with a CompletableFuture<Invoice> which will be completed when the downstream flow replies to the gateway (with an Invoice object).

CompletableFuture<Invoice> order(Order order);
<int:gateway service-interface="foo.Service" default-request-channel="orders"
    async-executor="" />

In this scenario, the caller thread will return with a CompletableFuture<Invoice> when the downstream flow provides it as the payload of the reply to the gateway. Some other process must complete the future when the invoice is ready.

MyCompletableFuture<Invoice> order(Order order);
<int:gateway service-interface="foo.Service" default-request-channel="orders" />

In this scenario, the caller thread will return with a CompletableFuture<Invoice> when the downstream flow provides it as the payload of the reply to the gateway. Some other process must complete the future when the invoice is ready. If DEBUG logging is enabled, a log is emitted indicating that the async executor cannot be used for this scenario.

CompletableFuture s can be used to perform additional manipulation on the reply, such as:

CompletableFuture<String> process(String data);


CompletableFuture result = process("foo")
    .thenApply(t -> t.toUpperCase());


String out = result.get(10, TimeUnit.SECONDS);

Reactor Promise

Starting with version 4.1, the GatewayProxyFactoryBean allows the use of a Reactor with gateway interface methods, utilizing a Promise<?> return type. The internal AsyncInvocationTask is wrapped in a reactor.function.Supplier, using a default RingBufferDispatcher for the Promise consumption. Only methods with the Promise<?> return type are 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.


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:

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"))
			.mapMany(integer -> testGateway.multiply(integer))
			.consume(integers -> ...)

Another example is a simple callback scenario:

Promise<Invoice> promise = service.process(myOrder);

promise.consume(new Consumer<Invoice>() {
	public void accept(Invoice invoice) {

The calling thread continues, with handleInvoice() being called when the flow completes.

8.4.10 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 (at the method level or default-reply-timeout at the gateway level). 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.


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.


* 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.


It is important to understand that the timer starts when the thread returns to the gateway, i.e. when the flow completes or a message is handed off to another thread. At that time, the calling thread starts waiting for the reply. If the flow was completely synchronous, the reply will be immediately available; for asynchronous flows, the thread will wait for up to this time.

8.5 Service Activator

8.5.1 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.

8.5.2 Configuring Service Activator

To create a Service Activator, use the service-activator element with the input-channel and ref attributes:

<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.

<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:

<int:service-activator input-channel="exampleChannel" output-channel="replyChannel"
                       ref="somePojo" method="someMethod"/>

If the method returns a result and no "output-channel" is defined, the framework 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.

If your method returns a result, and you want to discard it and end the flow, you should configure the output-channel to send to a NullChannel. For convenience, the framework registers one with the name nullChannel. See Section 4.1.6, “Special Channels” for more information.

The Service Activator is one of those components that is not required to produce a reply message. If your method returns null or has a void return type, the Service Activator exits after the method invocation, without any signals. This behavior can be controlled by the AbstractReplyProducingMessageHandler.requiresReply option, also exposed as requires-reply when configuring with the XML namespace. If the flag is set to true and the method returns null, a ReplyRequiredException is thrown.

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 Section F.6, “Annotation Support”


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:

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:

<int:service-activator id="exampleServiceActivator" input-channel="inChannel"
            output-channel = "outChannel" method="foo">
    <beans:bean class="org.foo.ExampleServiceActivator"/>

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.


If the "ref" attribute references a bean that extends AbstractMessageProducingHandler (such as handlers provided by the framework itself), the configuration is optimized by injecting the output channel into the handler directly. In this case, each "ref" must be to a separate bean instance (or a prototype-scoped bean), or use the inner <bean/> configuration type. If you inadvertently reference the same message handler from multiple beans, you will get a configuration exception.

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:

<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.

<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.

8.5.3 Asynchronous Service Activator

The service activator is invoked by the calling thread; this would be some upstream thread if the input channel is a SubscribableChannel, or a poller thread for a PollableChannel. If the service returns a ListenableFuture<?> the default action is to send that as the payload of the message sent to the output (or reply) channel. Starting with version 4.3, you can now set the async attribute to true (setAsync(true) when using Java configuration). If the service returns a ListenableFuture<?> when this is true, the calling thread is released immediately, and the reply message is sent on the thread (from within your service) that completes the future. This is particularly advantageous for long-running services using a PollableChannel because the poller thread is freed up to perform other services within the framework.

If the service completes the future with an Exception, normal error processing will occur - an ErrorMessage is sent to the errorChannel message header, if present or otherwise to the default errorChannel (if available).

8.6 Delayer

8.6.1 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.

8.6.2 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:

<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:

<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.


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.


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.


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:

 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: Section F.3, “Configuring the Task Scheduler”. If you want to delegate to a different scheduler, you can provide a reference through the delayer element’s scheduler attribute:

<int:delayer id="delayer" input-channel="input" output-channel="output"

<task:scheduler id="exampleTaskScheduler" pool-size="3"/>

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.


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.

8.6.3 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:

<int:delayer id="delayer" input-channel="input" output-channel="output"
        <beans:ref bean="customAdviceBean"/>
                <tx:method name="*" read-only="true"/>

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:

Message<String> delayerReschedulingMessage =

For more information regarding the Message Store, JMX and the Control Bus, please read Chapter 9, System Management.

8.7 Scripting support

With Spring Integration 2.1 we’ve added support for the 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 documentation


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 Groovy and 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.


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.


If you plan to use Groovy as your scripting language, we recommended you use Spring-Integration’s Groovy Support as it offers additional features specific to Groovy. However you will find this section relevant as well.

8.7.1 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:


<int:filter input-channel="referencedScriptInput">
   <int-script:script lang="ruby" location="some/path/to/ruby/script/RubyFilterTests.rb"/>

<int:filter input-channel="inlineScriptInput">
     <int-script:script lang="groovy">
     return payload == 'good'

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:

<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.

<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.


Inline scripts can not be reloaded.

<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:

<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"/>

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:

<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"/>
            payload.foo = foo
            payload.date = date
            payload.bar = bar
            payload.baz = baz

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:

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:

<int-script:script location="foo/bar/MyScript.groovy"

<bean id="variableGenerator" class="foo.bar.MyScriptVariableGenerator"/>

If a script-variable-generator is not provided, script components use DefaultScriptVariableGenerator, which merges any provided <variable> s with payload and headers variables from the Message in its generateScriptVariables(Message) method.


You cannot provide both the script-variable-generator attribute and <variable> sub-element(s) as they are mutually exclusive.

8.8 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 project website.

8.8.1 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 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:


<int:filter input-channel="referencedScriptInput">
   <int-groovy:script location="some/path/to/groovy/file/GroovyFilterTests.groovy"/>

<int:filter input-channel="inlineScriptInput">
     return payload == 'good'

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 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:

<int:service-activator input-channel="groovyChannel">
    <int-groovy:script location="foo/SomeScript.groovy" customizer="groovyCustomizer"/>

<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:


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 Section 8.7.1, “Script configuration”.

Groovy Script Compiler Customization

The @CompileStatic hint is the most popular Groovy compiler customization option, which can be used on the class or method level. See more information in the Groovy Reference Manual and, specifically, @CompileStatic. To utilize this feature for short scripts (in integration scenarios), we are forced to change a simple script like this (a <filter> script):

headers.type == 'good'

to more Java-like code:

String filter(Map headers) {
	headers.type == 'good'


With that, the filter() method will be transformed and compiled to static Java code, bypassing the Groovy dynamic phases of invocation, like getProperty() factories and CallSite proxies.

Starting with version 4.3, Spring Integration Groovy components can be configured with the compile-static boolean option, specifying that ASTTransformationCustomizer for @CompileStatic should be added to the internal CompilerConfiguration. With that in place, we can omit the method declaration with @CompileStatic in our script code and still get compiled plain Java code. In this case our script can still be short but still needs to be a little more verbose than interpreted script:

binding.variables.headers.type == 'good'

Where we can access the headers and payload (or any other) variables only through the groovy.lang.Script binding property since, with @CompileStatic, we don’t have the dynamic GroovyObject.getProperty() capability.

In addition, the compiler-configuration bean reference has been introduced. With this attribute, you can provide any other required Groovy compiler customizations, e.g. ImportCustomizer. For more information about this feature, please, refer to the Groovy Documentation: Advanced compiler configuration.


Using compilerConfiguration does not automatically add a ASTTransformationCustomizer for @CompileStatic and overrides the compileStatic option. If CompileStatic is still requirement, a new ASTTransformationCustomizer(CompileStatic.class) should be manually added into the CompilationCustomizers of that custom compilerConfiguration.


The Groovy compiler customization does not have any effect to the refresh-check-delay option and reloadable scripts can be statically compiled, too.

8.8.2 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. One option for those operations is Groovy scripts.

<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).


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 GroovyObjectCustomizer via the customizer attribute.

<int-groovy:control-bus input-channel="input"

<beans:bean id="groovyCustomizer" class="org.foo.MyGroovyObjectCustomizer"/>

8.9 Adding Behavior to Endpoints

8.9.1 Introduction

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:


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:

<int-http:outbound-gateway id="withAdvice"
        <ref bean="myRetryAdvice" />

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.


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.

8.9.2 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

The retry advice (o.s.i.handler.advice.RequestHandlerRetryAdvice) leverages the rich retry mechanisms provided by the 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 Spring Batch, where spring-retry originated.


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.

Configuring the Retry Advice

The following examples use a simple <service-activator/> that always throws an exception:

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.

<int:service-activator input-channel="input" ref="failer" method="service">
        <bean class="o.s.i.handler.advice.RequestHandlerRetryAdvice"/>

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.

<int:service-activator input-channel="input" ref="failer" method="service">
        <bean class="o.s.i.handler.advice.RequestHandlerRetryAdvice">
            <property name="recoveryCallback">
                <bean class="o.s.i.handler.advice.ErrorMessageSendingRecoverer">
                    <constructor-arg ref="myErrorChannel" />

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).

<int:service-activator input-channel="input" ref="failer" method="service">
        <bean class="o.s.i.handler.advice.RequestHandlerRetryAdvice">
            <property name="recoveryCallback">
                <bean class="o.s.i.handler.advice.ErrorMessageSendingRecoverer">
                    <constructor-arg ref="myErrorChannel" />
            <property name="retryTemplate" ref="retryTemplate" />

<bean id="retryTemplate" class="org.springframework.retry.support.RetryTemplate">
    <property name="retryPolicy">
        <bean class="org.springframework.retry.policy.SimpleRetryPolicy">
            <property name="maxAttempts" value="4" />
    <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" />

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:

<int:service-activator input-channel="input" ref="failer" method="service">
        <bean ref="retrier" />

<int:handler-retry-advice id="retrier" max-attempts="4" recovery-channel="myErrorChannel">
    <int:exponential-back-off initial="1000" multiplier="5.0" maximum="60000" />

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:

<int:service-activator input-channel="input" ref="failer" method="service">
        <int:retry-advice id="retrier" max-attempts="4" recovery-channel="myErrorChannel">
            <int:exponential-back-off initial="1000" multiplier="5.0" maximum="60000" />

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.

<int:service-activator input-channel="input" ref="failer" method="service">
        <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']" />
            <property name="recoveryCallback">
                <bean class="o.s.i.handler.advice.ErrorMessageSendingRecoverer">
                    <constructor-arg ref="myErrorChannel" />

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

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.


<int:service-activator input-channel="input" ref="failer" method="service">
        <bean class="o.s.i.handler.advice.RequestHandlerCircuitBreakerAdvice">
            <property name="threshold" value="2" />
            <property name="halfOpenAfter" value="12000" />

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 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 exception) 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.

When an exception is thrown in the scope of the advice, by default, that exception is thrown to caller after any failureExpression is evaluated. If you wish to suppress throwing the exception, set the trapException property to true.

Example - Configuring the Advice with Java DSL. 

public class EerhaApplication {

    public static void main(String[] args) {
        ConfigurableApplicationContext context = SpringApplication.run(EerhaApplication.class, args);
        MessageChannel in = context.getBean("advised.input", MessageChannel.class);
        in.send(new GenericMessage<>("good"));
        in.send(new GenericMessage<>("bad"));

    public IntegrationFlow advised() {
        return f -> f.handle((GenericHandler<String>) (payload, headers) -> {
            if (payload.equals("good")) {
                return null;
            else {
                throw new RuntimeException("some failure");
        }, c -> c.advice(expressionAdvice()));

    public Advice expressionAdvice() {
        ExpressionEvaluatingRequestHandlerAdvice advice = new ExpressionEvaluatingRequestHandlerAdvice();
        advice.setOnSuccessExpressionString("payload + ' was successful'");
                "payload + ' was bad, with reason: ' + #exception.cause.message");
        return advice;

    public IntegrationFlow success() {
        return f -> f.handle(System.out::println);

    public IntegrationFlow failure() {
        return f -> f.handle(System.out::println);


8.9.3 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 (usually org.aopalliance.intercept.MethodInterceptor), 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:

 * 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.

public class MyAdvice extends AbstractRequestHandlerAdvice {

    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;

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 ReflectiveMethodInvocation JavaDocs.

8.9.4 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.

8.9.5 Handle Message Advice

As discussed in the introduction to this section, advice objects in a request handler advice chain are applied to just the current endpoint, not the downstream flow (if any). For MessageHandler s that produce a reply (AbstractReplyProducingMessageHandler), the advice is applied to an internal method handleRequestMessage() (called from MessageHandler.handleMessage()). For other message handlers, the advice is applied to MessageHandler.handleMessage().

There are some circumstances where, even if a message handler is an AbstractReplyProducingMessageHandler, the advice must be applied to the handleMessage method - for example, the Idempotent Receiver might return null and this would cause an exception if the handler’s replyRequired property is true.

Starting with version 4.3.1, a new HandleMessageAdvice and the AbstractHandleMessageAdvice base implementation have been introduced. Advice s that implement HandleMessageAdvice will always be applied to the handleMessage() method, regardless of the handler type.

It is important to understand that HandleMessageAdvice implementations (such as Idempotent Receiver), when applied to a handler that returns a response, are dissociated from the adviceChain and properly applied to the MessageHandler.handleMessage() method. Bear in mind, however, that this means the advice chain order is not complied with; and, with configuration such as:

<some-reply-producing-endpoint ... >
        <tx:advice ... />
        <bean ref="myHandleMessageAdvice" />

The <tx:advice> is applied to the AbstractReplyProducingMessageHandler.handleRequestMessage(), but myHandleMessageAdvice is applied for to MessageHandler.handleMessage() and, therefore, invoked before the <tx:advice>. To retain the order, you should follow with standard Spring AOP configuration approach and use endpoint id together with the .handler suffix to obtain the target MessageHandler bean. Note, however, that in that case, the entire downstream flow would be within the transaction scope.

In the case of a MessageHandler that does not return a response, the advice chain order is retained.

8.9.6 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.

8.9.7 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 Section 8.9.6, “Advising Filters”. An example with the discard being performed after the advice is shown below.

public class MyAdvisedFilter {

    @Filter(inputChannel="input", outputChannel="output",
            adviceChain="adviceChain", discardWithinAdvice="false")
    public boolean filter(String s) {
        return s.contains("good");

8.9.8 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.

8.9.9 Advised Handler Properties

Sometimes, it is useful to access handler properties from within the advice. For example, most handlers implement NamedComponent and you can access the component name.

The target object can be accessed via the target argument when subclassing AbstractRequestHandlerAdvice or invocation.getThis() when implementing org.aopalliance.intercept.MethodInterceptor.

When the entire handler is advised (such as when the handler does not produce replies, or the advice implements HandleMessageAdvice), you can simply cast the target object to the desired implemented interface, such as NamedComponent.

String componentName = ((NamedComponent) target).getComponentName();


String componentName = ((NamedComponent) invocation.getThis()).getComponentName();

when implementing MethodInterceptor directly.

When only the handleRequestMessage() method is advised (in a reply-producing handler), you need to access the full handler, which is an AbstractReplyProducingMessageHandler…​

AbstractReplyProducingMessageHandler handler =
    ((AbstractReplyProducingMessageHandler.RequestHandler) target).getAdvisedHandler();

String componentName = handler.getComponentName();

8.9.10 Idempotent Receiver Enterprise Integration Pattern

Starting with version 4.1, Spring Integration provides an implementation of the 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/> (Section 6.2, “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 (Section 9.5, “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:

        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


The id of the IdempotentReceiverInterceptor bean. Optional.


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.


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.


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.


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.


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.


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.


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.


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.


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:

public IdempotentReceiverInterceptor idempotentReceiverInterceptor() {
   return new IdempotentReceiverInterceptor(new MetadataStoreSelector(m ->

@ServiceActivator(inputChannel = "input", outputChannel = "output")
public MessageHandler myService() {

The IdempotentReceiverInterceptor is designed only for the MessageHandler.handleMessage(Message<?>) method and starting with version 4.3.1 it implements HandleMessageAdvice, with the AbstractHandleMessageAdvice as a base class, for better dissociation. See Section 8.9.5, “Handle Message Advice” for more information.

8.10 Logging Channel Adapter

The <logging-channel-adapter/> is often used in conjunction with a Wire Tap, as discussed in the section called “Wire Tap”. 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.

    channel="" 1
    level="INFO" 2
    expression="" 3
    log-full-message="false" 4
    logger-name="" /> 5


The channel connecting the logging adapter to an upstream component.


The logging level at which messages sent to this adapter will be logged. Default: INFO.


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.


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.


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.

8.10.1 Configuring with Java Configuration

The following Spring Boot application provides an example of configuring the LoggingHandler using Java configuration:

public class LoggingJavaApplication {

    public static void main(String[] args) {
        ConfigurableApplicationContext context =
             new SpringApplicationBuilder(LoggingJavaApplication.class)
         MyGateway gateway = context.getBean(MyGateway.class);

    public MessageChannel logInputChannel() {
        return new DirectChannel();

    @ServiceActivator(inputChannel = "logChannel")
    public LoggingHandler logging() {
        LoggingHandler adapter = new LoggingHandler(LoggingHandler.Level.DEBUG);
        adapter.setLogExpressionString("headers.id + ': ' + payload");
        return adapter;

    @MessagingGateway(defaultRequestChannel = "logChannel")
    public interface MyGateway {

        void sendToLogger(String data);



9. System Management

9.1 Metrics and Management

9.1.1 Configuring Metrics Capture


Prior to version 4.2 metrics were only available when JMX was enabled. See Section 9.2, “JMX Support”.

To enable MessageSource, MessageChannel and MessageHandler metrics, add an <int:management/> bean to the application context, or annotate one of your @Configuration classes with @EnableIntegrationManagement. MessageSource s only maintain counts, MessageChannel s and MessageHandler s maintain duration statistics in addition to counts. See Section 9.1.2, “MessageChannel Metric Features” and Section 9.1.3, “MessageHandler Metric Features” below.

This causes the automatic registration of the IntegrationManagementConfigurer bean in the application context. Only one such bean can exist in the context and it must have the bean name integrationManagementConfigurer if registered manually via a <bean/> definition.

In addition to metrics, you can control debug logging in the main message flow. It has been found that in very high volume applications, even calls to isDebugEnabled() can be quite expensive with some logging subsystems. You can disable all such logging to avoid this overhead; exception logging (debug or otherwise) are not affected by this setting.

A number of options are available:

    default-logging-enabled="false" 1
    default-counts-enabled="false" 2
    default-stats-enabled="false" 3
    counts-enabled-patterns="foo, !baz, ba*" 4
    stats-enabled-patterns="fiz, buz" 5
    metrics-factory="myMetricsFactory" /> 6
    defaultLoggingEnabled = "false", 1
    defaultCountsEnabled = "false", 2
    defaultStatsEnabled = "false", 3
    countsEnabled = { "foo", "${count.patterns}" }, 4
    statsEnabled = { "qux", "!*" }, 5
    MetricsFactory = "myMetricsFactory") 6
public static class ContextConfiguration {

1 1

Set to false to disable all logging in the main message flow, regardless of the log system category settings. Set to true to enable debug logging (if also enabled by the logging subsystem).

2 2

Enable or disable count metrics for components not matching one of the patterns in <4>.

3 3

Enable or disable statistical metrics for components not matching one of the patterns in <5>.

4 4

A comma-delimited list of patterns for beans for which counts should be enabled; negate the pattern with !. First match wins (positive or negative). In the unlikely event that you have a bean name starting with !, escape the ! in the pattern: \!foo positively matches a bean named !foo.

5 5

A comma-delimited list of patterns for beans for which statistical metrics should be enabled; negate the pattern with !. First match wins (positive or negative). In the unlikely event that you have a bean name starting with !, escape the ! in the pattern: \!foo positively matches a bean named !foo. Stats implies counts.

6 6

A reference to a MetricsFactory. See Section 9.1.5, “Metrics Factory”.

At runtime, counts and statistics can be obtained by calling IntegrationManagementConfigurer getChannelMetrics, getHandlerMetrics and getSourceMetrics, returning MessageChannelMetrics, MessageHandlerMetrics and MessageSourceMetrics respectively.

See the javadocs for complete information about these classes.

When JMX is enabled (see Section 9.2, “JMX Support”), these metrics are also exposed by the IntegrationMBeanExporter.

9.1.2 MessageChannel Metric 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.

Table 9.1. MessageChannel Metrics

Metric TypeExampleAlgorithm


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.


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.


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).


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.

9.1.3 MessageHandler Metric 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:

Table 9.2. MessageHandlerMetrics

Metric TypeExampleAlgorithm


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).


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.

9.1.4 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).

9.1.5 Metrics Factory

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 configure it as described above, by providing 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 extending AbstractMessageChannelMetrics and/or AbstractMessageHandlerMetrics.

In addition to the default metrics factory described above, the framework provides the AggregatingMetricsFactory. This factory creates AggregatingMessageChannelMetrics and AggregatingMessageHandlerMetrics. In very high volume scenarios, the cost of capturing statistics can be prohibitive (2 calls to the system time and storing the data for each message). The aggregating metrics aggregate the response time over a sample of messages. This can save significant CPU time.


The statistics will be skewed if messages arrive in bursts. These metrics are intended for use with high, constant-volume, message rates.

<bean id="aggregatingMetricsFactory"
    <constructor-arg value="1000" /> <!-- sample size -->

The above configuration aggregates the duration over 1000 messages. Counts (send, error) are maintained per-message but the statistics are per 1000 messages.

  • Customizing the Default Channel/Handler Statistics

See Section 9.1.4, “Time-Based Average Estimates” 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.


public static class CustomMetrics implements MetricsFactory {

    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));

    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 Section 9.1.4, “Time-Based Average Estimates”) 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.

9.2 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.

9.2.1 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:

<int-jmx:notification-listening-channel-adapter id="adapter"

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:

<int-jmx:notification-listening-channel-adapter id="adapter"

The Notification-listening Channel Adapter is event-driven and registered with the MBeanServer directly. It does not require any poller configuration.


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:

<jmx:notification-listening-channel-adapter id="manyNotificationsAdapter"

<util:list id="patterns">

The names of the located MBean(s) will be logged when DEBUG level logging is enabled.

9.2.2 Notification Publishing Channel Adapter

The Notification-publishing Channel Adapter is relatively simple. It only requires a JMX ObjectName in its configuration as shown below.


<int-jmx:notification-publishing-channel-adapter id="adapter"

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.


<int-jmx:notification-publishing-channel-adapter id="adapter"

9.2.3 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.

<int-jmx:attribute-polling-channel-adapter id="adapter"
        <int:poller max-messages-per-poll="1" fixed-rate="5000"/>

9.2.4 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:

<int-jmx:tree-polling-channel-adapter id="adapter"
        <int:poller max-messages-per-poll="1" fixed-rate="5000"/>

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

9.2.5 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:

<int-jmx:operation-invoking-channel-adapter id="adapter"

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.

9.2.6 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.

<int-jmx:operation-invoking-outbound-gateway request-channel="requestChannel"

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.

9.2.7 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.

<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"/>

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 the section called “Orderly Shutdown Managed Operation”.

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:

@EnableIntegrationMBeanExport(server = "mbeanServer", managedComponents = "input")
public class ContextConfiguration {

	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.

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:

Table 9.3. MBean ObjectNames

Component TypeObjectName







The bean attribute in the object names for sources and handlers takes one of the values in the table below:

Table 9.4. bean ObjectName Part

Bean ValueDescription


The bean name of the enclosing endpoint (e.g. <service-activator>) if there is one


An indication that the enclosing endpoint didn’t have a user-specified bean name, so the JMX name is the input channel name


For well-known Spring Integration default components


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 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:

public class Namer implements ObjectNamingStrategy {

	private final ObjectNamingStrategy realNamer = new KeyNamingStrategy();
	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