Spring Integration Reference Manual

Authors

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

5.1.2.RELEASE

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.


Table of Contents

I. Preface
1. Requirements
1.1. Compatible Java Versions
1.2. Compatible Versions of the Spring Framework
2. Code Conventions
3. Conventions in This Guide
II. What’s New?
4. What’s New in Spring Integration 5.1?
4.1. New Components
4.1.1. AmqpDedicatedChannelAdvice
4.1.2. Improved Function Support
4.1.3. @LongRunningTest
4.2. General Changes
4.2.1. Java DSL
4.2.2. Dispatcher Exceptions
4.2.3. Global Channel Interceptors
4.2.4. Channel Interceptors
4.2.5. ObjectToJsonTransformer
4.2.6. Integration Flows: Generated Bean Names
4.2.7. Aggregator Changes
4.2.8. @Publisher annotation changes
4.3. Files Changes
4.4. AMQP Changes
4.5. JDBC Changes
4.6. FTP and SFTP Changes
4.7. TCP Support
4.8. Twitter Support
4.9. JMS Support
4.10. HTTP/WebFlux Support
4.11. JMX Changes
4.12. Micrometer Support Changes
4.13. Integration Graph Customization
4.14. Integration Global Properties
4.15. The receiveTimeout for @Poller
III. Overview of Spring Integration Framework
5. Spring Integration Overview
5.1. Background
5.2. Goals and Principles
5.3. Main Components
5.3.1. Message
5.3.2. Message Channel
5.3.3. Message Endpoint
5.4. Message Endpoints
5.4.1. Message Transformer
5.4.2. Message Filter
5.4.3. Message Router
5.4.4. Splitter
5.4.5. Aggregator
5.4.6. Service Activator
5.4.7. Channel Adapter
5.4.8. Endpoint Bean Names
5.5. Configuration and @EnableIntegration
5.6. Programming Considerations
5.6.1. Considerations When Using Packaged (for example, Shaded) Jars
5.7. Programming Tips and Tricks
5.7.1. XML Schemas
5.7.2. Finding Class Names for Java and DSL Configuration
5.8. POJO Method invocation
IV. Core Messaging
6. Messaging Channels
6.1. Message Channels
6.1.1. The MessageChannel Interface
PollableChannel
SubscribableChannel
6.1.2. Message Channel Implementations
PublishSubscribeChannel
QueueChannel
PriorityChannel
RendezvousChannel
DirectChannel
ExecutorChannel
Scoped Channel
6.1.3. Channel Interceptors
6.1.4. MessagingTemplate
6.1.5. Configuring Message Channels
DirectChannel Configuration
Datatype Channel Configuration
QueueChannel Configuration
PublishSubscribeChannel Configuration
ExecutorChannel
PriorityChannel Configuration
RendezvousChannel Configuration
Scoped Channel Configuration
Channel Interceptor Configuration
Global Channel Interceptor Configuration
Wire Tap
Conditional Wire Taps
Global Wire Tap Configuration
6.1.6. Special Channels
6.2. Poller
6.2.1. Polling Consumer
6.2.2. Pollable Message Source
6.2.3. Deferred Acknowledgment Pollable Message Source
6.2.4. Conditional Pollers for Message Sources
Background
"Smart" Polling
SimpleActiveIdleMessageSourceAdvice
CompoundTriggerAdvice
6.3. Channel Adapter
6.3.1. Configuring An Inbound Channel Adapter
6.3.2. Configuring An Outbound Channel Adapter
6.3.3. Channel Adapter Expressions and Scripts
6.4. Messaging Bridge
6.4.1. Configuring a Bridge with XML
6.4.2. Configuring a Bridge with Java Configuration
6.4.3. Configuring a Bridge with the Java DSL
7. Message
7.1. The Message Interface
7.2. Message Headers
7.2.1. MessageHeaderAccessor API
7.2.2. Message ID Generation
7.2.3. Read-only Headers
7.2.4. Header Propagation
7.3. Message Implementations
7.4. The MessageBuilder Helper Class
8. Message Routing
8.1. Routers
8.1.1. Overview
8.1.2. Common Router Parameters
Inside and Outside of a Chain
Top-Level (Outside of a Chain)
8.1.3. Router Implementations
PayloadTypeRouter
HeaderValueRouter
RecipientListRouter
RecipientListRouterManagement
XPath Router
Routing and Error Handling
8.1.4. Configuring a Generic Router
Configuring a Content-based Router with XML
8.1.5. Routers and the Spring Expression Language (SpEL)
Configuring a Router with Annotations
8.1.6. Dynamic Routers
Manage Router Mappings using the Control Bus
Manage Router Mappings by Using JMX
Routing Slip
Process Manager Enterprise Integration Pattern
8.2. Filter
8.2.1. Configuring a Filter with XML
8.2.2. Configuring a Filter with Annotations
8.3. Splitter
8.3.1. Programming Model
Iterators
Stream and Flux
8.3.2. Configuring a Splitter with XML
8.3.3. Configuring a Splitter with Annotations
8.4. Aggregator
8.4.1. Functionality
8.4.2. Programming Model
AggregatingMessageHandler
ReleaseStrategy
Aggregating Large Groups
Correlation Strategy
Lock Registry
Avoiding Deadlocks
8.4.3. Configuring an Aggregator in Java DSL
Configuring an Aggregator with XML
Configuring an Aggregator with Annotations
8.4.4. Managing State in an Aggregator: MessageGroupStore
8.5. Resequencer
8.5.1. Functionality
8.5.2. Configuring a Resequencer
8.6. Message Handler Chain
8.6.1. Configuring a Chain
8.6.2. Using the id Attribute
8.6.3. Calling a Chain from within a Chain
8.7. Scatter-Gather
8.7.1. Functionality
Auction
Distribution
8.7.2. Configuring a Scatter-Gather Endpoint
8.8. Thread Barrier
9. Message Transformation
9.1. Transformer
9.1.1. Configuring a Transformer with XML
9.1.2. Transformers and Spring Expression Language (SpEL)
9.1.3. Common Transformers
Object-to-String Transformer
Object-to-Map and Map-to-Object Transformers
Stream Transformer
JSON Transformers
9.1.4. Configuring a Transformer with Annotations
9.1.5. Header Filter
9.1.6. Codec-Based Transformers
9.2. Content Enricher
9.2.1. Header Enricher
POJO Support
SpEL Support
Configuring a Header Enricher with Java Configuration
Configuring a Header Enricher with the Java DSL
Header Channel Registry
9.2.2. Payload Enricher
Configuration
Examples
How Do I Pass Only a Subset of Data to the Request Channel?
How Can I Enrich Payloads with Static Information without Using a Request Channel?
9.3. Claim Check
9.3.1. Incoming Claim Check Transformer
9.3.2. Outgoing Claim Check Transformer
9.3.3. Claim Once
9.3.4. A Word on Message Store
9.4. Codec
9.4.1. EncodingPayloadTransformer
9.4.2. DecodingTransformer
9.4.3. CodecMessageConverter
9.4.4. Kryo
Customizing Kryo
10. Messaging Endpoints
10.1. Message Endpoints
10.1.1. Message Handler
10.1.2. Event-driven Consumer
10.1.3. Polling Consumer
10.1.4. Endpoint Namespace Support
Examples
AOP Advice chains
10.1.5. Changing Polling Rate at Runtime
10.1.6. Payload Type Conversion
10.1.7. Content Type Conversion
10.1.8. Asynchronous Polling
10.1.9. Endpoint Inner Beans
10.2. Endpoint Roles
10.3. Leadership Event Handling
10.4. Messaging Gateways
10.4.1. Enter the GatewayProxyFactoryBean
10.4.2. Gateway XML Namespace Support
10.4.3. Setting the Default Reply Channel
10.4.4. Gateway Configuration with Annotations and XML
Expressions and "Global" Headers
10.4.5. Mapping Method Arguments to a Message
Mapping Method Arguments
10.4.6. @MessagingGateway Annotation
10.4.7. Invoking No-Argument Methods
10.4.8. Error Handling
10.4.9. Gateway Timeouts
10.4.10. Asynchronous Gateway
ListenableFuture
AsyncTaskExecutor
CompletableFuture
Reactor Mono
Downstream Flows Returning an Asynchronous Type
void Return Type
10.4.11. Gateway Behavior When No response Arrives
Long-running Process Downstream
Downstream Component Returns null
Downstream Component Return Signature is void While Gateway Method Signature Is Non-void
Downstream Component Results in Runtime Exception
10.5. Service Activator
10.5.1. Configuring Service Activator
Service Activators and the Spring Expression Language (SpEL)
10.5.2. Asynchronous Service Activator
10.5.3. Service Activator and Method Return Type
10.6. Delayer
10.6.1. Configuring a Delayer
10.6.2. Delayer and a Message Store
10.6.3. Release Failures
10.7. Scripting Support
10.7.1. Script Configuration
Script Variable Bindings
10.8. Groovy support
10.8.1. Groovy Configuration
10.8.2. Groovy Object Customization
10.8.3. Groovy Script Compiler Customization
10.8.4. Control Bus
10.9. Adding Behavior to Endpoints
10.9.1. Provided Advice Classes
Retry Advice
Circuit Breaker Advice
Expression Evaluating Advice
10.9.2. Custom Advice Classes
10.9.3. Other Advice Chain Elements
10.9.4. Handling Message Advice
10.9.5. Transaction Support
10.9.6. Advising Filters
10.9.7. Advising Endpoints Using Annotations
10.9.8. Ordering Advices within an Advice Chain
10.9.9. Advised Handler Properties
10.9.10. Idempotent Receiver Enterprise Integration Pattern
10.10. Logging Channel Adapter
10.10.1. Using Java Configuration
10.10.2. Configuring with the Java DSL
10.11. java.util.function Interfaces Support
10.11.1. Kotlin Lambdas
11. Java DSL
11.1. DSL Basics
11.2. Message Channels
11.3. Pollers
11.4. DSL and Endpoint Configuration
11.5. Transformers
11.6. Inbound Channel Adapters
11.7. Message Routers
11.8. Splitters
11.9. Aggregators and Resequencers
11.10. Service Activators and the .handle() method
11.11. Operator log()
11.12. MessageChannelSpec.wireTap()
11.13. Working With Message Flows
11.14. FunctionExpression
11.15. Sub-flows support
11.16. Using Protocol Adapters
11.17. IntegrationFlowAdapter
11.18. Dynamic and Runtime Integration Flows
11.19. IntegrationFlow as Gateway
12. System Management
12.1. Metrics and Management
12.1.1. Configuring Metrics Capture
12.1.2. Micrometer Integration
12.1.3. MessageChannel Metric Features
12.1.4. MessageHandler Metric Features
12.1.5. Time-Based Average Estimates
12.1.6. Metrics Factory
Customizing the Default Channel and Handler Statistics
Advanced Customization
Performance Improvement
12.2. JMX Support
12.2.1. Notification-listening Channel Adapter
12.2.2. Notification-publishing Channel Adapter
12.2.3. Attribute-polling Channel Adapter
12.2.4. Tree-polling Channel Adapter
12.2.5. Operation-invoking Channel Adapter
12.2.6. Operation-invoking Outbound Gateway
12.2.7. MBean Exporter
MBean Object Names
JMX Improvements
Orderly Shutdown Managed Operation
12.3. Message History
12.3.1. Message History Configuration
12.4. Message Store
12.4.1. Using MessageGroupFactory
12.4.2. Persistent MessageGroupStore and Lazy-load
12.5. Metadata Store
12.5.1. Idempotent Receiver and Metadata Store
12.5.2. MetadataStoreListener
12.6. Control Bus
12.7. Orderly Shutdown
12.8. Integration Graph
12.8.1. Graph Runtime Model
12.9. Integration Graph Controller
V. Integration Endpoints
13. Endpoint Quick Reference Table
14. AMQP Support
14.1. Inbound Channel Adapter
14.1.1. Configuring with Java Configuration
14.1.2. Configuring with the Java DSL
14.2. Polled Inbound Channel Adapter
14.3. Inbound Gateway
14.3.1. Configuring with Java Configuration
14.3.2. Configuring with the Java DSL
14.4. Inbound Endpoint Acknowledge Mode
14.5. Outbound Channel Adapter
14.5.1. Configuring with Java Configuration
14.5.2. Configuring with the Java DSL
14.6. Outbound Gateway
14.6.1. Configuring with Java Configuration
14.6.2. Configuring with the Java DSL
14.7. Asynchronous Outbound Gateway
14.7.1. Configuring with Java Configuration
14.7.2. Configuring with the Java DSL
14.8. Outbound Message Conversion
14.9. Outbound User ID
14.10. Delayed Message Exchange
14.11. AMQP-backed Message Channels
14.11.1. Configuring with Java Configuration
14.11.2. Configuring with the Java DSL
14.12. AMQP Message Headers
14.12.1. Overview
14.12.2. contentType Header
14.13. Strict Message Ordering
14.13.1. Inbound
14.13.2. Outbound
14.14. AMQP Samples
15. Spring ApplicationEvent Support
15.1. Receiving Spring Application Events
15.2. Sending Spring Application Events
16. Feed Adapter
16.1. Feed Inbound Channel Adapter
16.2. Duplicate Entries
16.3. Other Options
16.4. Java DSL Configuration
17. File Support
17.1. Reading Files
17.1.1. Message Headers
17.1.2. Directory Scanning and Polling
17.1.3. Namespace Support
17.1.4. WatchServiceDirectoryScanner
17.1.5. Limiting Memory Consumption
17.1.6. Configuring with Java Configuration
17.1.7. Configuring with the Java DSL
17.1.8. 'tail’ing Files
17.1.9. Dealing With Incomplete Data
17.2. Writing files
17.2.1. Generating File Names
17.2.2. Specifying the Output Directory
Using the directory Attribute
Using the directory-expression Attribute
Using the auto-create-directory Attribute
17.2.3. Dealing with Existing Destination Files
17.2.4. Flushing Files When Using APPEND_NO_FLUSH
17.2.5. File Timestamps
17.2.6. File Permissions
17.2.7. File Outbound Channel Adapter
17.2.8. Outbound Gateway
17.2.9. Configuring with Java Configuration
17.2.10. Configuring with the Java DSL
17.3. File Transformers
17.4. File Splitter
17.4.1. Configuring with Java Configuration
17.4.2. Configuring with the Java DSL
18. FTP/FTPS Adapters
18.1. FTP Session Factory
18.1.1. Default Factories
18.2. Advanced Configuration
18.2.1. FTPS and Shared SSLSession
18.3. Delegating Session Factory
18.4. FTP Inbound Channel Adapter
18.4.1. More on File Filtering and Incomplete Files
18.4.2. Poller Configuration Notes for the Inbound FTP Adapter
18.4.3. Recovering from Failures
18.4.4. Configuring with Java Configuration
18.4.5. Configuring with the Java DSL
18.4.6. Dealing With Incomplete Data
18.5. FTP Streaming Inbound Channel Adapter
18.5.1. Configuring with Java Configuration
18.6. Inbound Channel Adapters: Polling Multiple Servers and Directories
18.7. Inbound Channel Adapters: Controlling Remote File Fetching
18.8. FTP Outbound Channel Adapter
18.8.1. Avoiding Partially Written Files
18.8.2. Configuring with Java Configuration
18.8.3. Configuring with the Java DSL
18.9. FTP Outbound Gateway
18.9.1. Using the ls Command
18.9.2. Using the nlst Command
18.9.3. Using the get Command
18.9.4. Using the mget Command
18.9.5. Using the put Command
18.9.6. Using the rm Command
18.9.7. Using the mv Command
18.9.8. Additional Information about FTP Outbound Gateway Commands
18.9.9. Configuring with Java Configuration
18.9.10. Configuring with the Java DSL
18.9.11. Outbound Gateway Partial Success (mget and mput)
18.10. FTP Session Caching
18.11. Using RemoteFileTemplate
18.12. Using MessageSessionCallback
19. Pivotal GemFire and Apache Geode Support
19.1. Inbound Channel Adapter
19.2. Continuous Query Inbound Channel Adapter
19.3. Outbound Channel Adapter
19.4. Gemfire Message Store
19.5. Gemfire Lock Registry
19.6. Gemfire Metadata Store
20. HTTP Support
20.1. Http Inbound Components
20.2. HTTP Outbound Components
20.2.1. Using HttpRequestExecutingMessageHandler
20.2.2. Using Cookies
20.3. HTTP Namespace Support
20.3.1. Inbound
20.3.2. Request Mapping Support
20.3.3. Cross-origin Resource Sharing (CORS) Support
20.3.4. Response Status Code
20.3.5. URI Template Variables and Expressions
20.3.6. Outbound
20.3.7. Mapping URI Variables
20.3.8. Controlling URI Encoding
20.4. Configuring HTTP Endpoints with Java
20.5. Timeout Handling
20.5.1. HTTP Inbound Gateway
20.6. HTTP Proxy configuration
20.6.1. Standard Java Proxy configuration
20.6.2. Spring’s SimpleClientHttpRequestFactory
20.7. HTTP Header Mappings
20.8. Integration Graph Controller
20.9. HTTP Samples
20.9.1. Multipart HTTP Request — RestTemplate (Client) and Http Inbound Gateway (Server)
21. JDBC Support
21.1. Inbound Channel Adapter
21.1.1. Polling and Transactions
21.1.2. max-rows Versus max-messages-per-poll
21.2. Outbound Channel Adapter
21.2.1. Passing Parameters by Using SpEL Expressions
21.2.2. Using the PreparedStatement Callback
21.2.3. Batch Update
21.3. Outbound Gateway
21.4. JDBC Message Store
21.4.1. Initializing the Database
21.4.2. The Generic JDBC Message Store
21.4.3. Backing Message Channels
Supported Databases
Custom Message Insertion
Concurrent Polling
Priority Channel
21.4.4. Partitioning a Message Store
21.5. Stored Procedures
21.5.1. Supported Databases
21.5.2. Configuration
21.5.3. Common Configuration Attributes
21.5.4. Common Configuration Sub-Elements
21.5.5. Defining Parameter Sources
21.5.6. Stored Procedure Inbound Channel Adapter
21.5.7. Stored Procedure Outbound Channel Adapter
21.5.8. Stored Procedure Outbound Gateway
21.5.9. Examples
21.6. JDBC Lock Registry
21.7. JDBC Metadata Store
22. JPA Support
22.1. Functionality
22.2. Supported Persistence Providers
22.3. Java Implementation
22.4. Namespace Support
22.4.1. Common XML Namespace Configuration Attributes
22.4.2. Providing JPA Query Parameters
22.4.3. Transaction Handling
22.5. Inbound Channel Adapter
22.5.1. Configuration Parameter Reference
22.5.2. Configuring with Java Configuration
22.5.3. Configuring with the Java DSL
22.6. Outbound Channel Adapter
22.6.1. Using an Entity Class
22.6.2. Using JPA Query Language (JPA QL)
22.6.3. Using Native Queries
22.6.4. Using Named Queries
22.6.5. Configuration Parameter Reference
22.6.6. Configuring with Java Configuration
22.6.7. Configuring with the Java DSL
22.7. Outbound Gateways
22.7.1. Common Configuration Parameters
22.7.2. Updating Outbound Gateway
22.7.3. Configuring with Java Configuration
22.7.4. Configuring with the Java DSL
22.7.5. Retrieving Outbound Gateway
22.7.6. Configuring with Java Configuration
22.7.7. Configuring with the Java DSL
22.7.8. JPA Outbound Gateway Samples
Update by Using an Entity Class
Update using JPQL
Retrieving an Entity using JPQL
Retrieving an Entity by Using id-expression
Update using a Named Query
23. JMS Support
23.1. Inbound Channel Adapter
23.1.1. Transactions
23.2. Message-driven Channel Adapter
23.2.1. Inbound Conversion Errors
23.3. Outbound Channel Adapter
23.3.1. Transactions
23.4. Inbound Gateway
23.5. Outbound Gateway
23.5.1. Using a <reply-listener/>
23.5.2. Idle Reply Listeners
23.5.3. Gateway Reply Correlation
23.5.4. Async Gateway
23.5.5. Attribute Reference
23.6. Mapping Message Headers to and from JMS Message
23.7. Message Conversion, Marshalling, and Unmarshalling
23.8. JMS-backed Message Channels
23.9. Using JMS Message Selectors
23.10. JMS Samples
24. Mail Support
24.1. Mail-sending Channel Adapter
24.2. Mail-receiving Channel Adapter
24.3. Inbound Mail Message Mapping
24.4. Mail Namespace Support
24.4.1. IMAP idle and Lost Connections
24.5. Marking IMAP Messages When \Recent Is Not Supported
24.6. Email Message Filtering
24.7. Transaction Synchronization
25. MongoDb Support
25.1. Connecting to MongoDb
25.1.1. Using MongoDbFactory
25.2. MongoDB Message Store
25.2.1. MongoDB Channel Message Store
25.2.2. MongoDB Metadata Store
25.3. MongoDB Inbound Channel Adapter
25.4. MongoDB Outbound Channel Adapter
25.5. MongoDB Outbound Gateway
25.5.1. Configuring with Java Configuration
25.5.2. Configuring with the Java DSL
26. MQTT Support
26.1. Inbound (Message-driven) Channel Adapter
26.1.1. Adding and Removing Topics at Runtime
26.1.2. Configuring with Java Configuration
26.1.3. Configuring with the Java DSL
26.2. Outbound Channel Adapter
26.2.1. Configuring with Java Configuration
26.2.2. Configuring with the Java DSL
27. Redis Support
27.1. Connecting to Redis
27.1.1. Using RedisConnectionFactory
27.1.2. Using RedisTemplate
27.2. Messaging with Redis
27.2.1. Redis Publish/Subscribe channel
27.2.2. Redis Inbound Channel Adapter
27.2.3. Redis Outbound Channel Adapter
27.2.4. Redis Queue Inbound Channel Adapter
27.2.5. Redis Queue Outbound Channel Adapter
27.2.6. Redis Application Events
27.3. Redis Message Store
27.3.1. Redis Channel Message Stores
27.4. Redis Metadata Store
27.5. Redis Store Inbound Channel Adapter
27.6. RedisStore Outbound Channel Adapter
27.7. Redis Outbound Command Gateway
27.8. Redis Queue Outbound Gateway
27.9. Redis Queue Inbound Gateway
27.10. Redis Lock Registry
28. Resource Support
28.1. Resource Inbound Channel Adapter
29. RMI Support
29.1. Outbound RMI
29.2. Inbound RMI
29.3. RMI namespace support
29.4. Configuring with Java Configuration
30. SFTP Adapters
30.1. SFTP Session Factory
30.1.1. Configuration Properties
30.2. Proxy Factory Bean
30.3. Delegating Session Factory
30.4. SFTP Session Caching
30.5. Using RemoteFileTemplate
30.6. SFTP Inbound Channel Adapter
30.6.1. More on File Filtering and Large Files
30.6.2. Recovering from Failures
30.6.3. Configuring with Java Configuration
30.6.4. Configuring with the Java DSL
30.6.5. Dealing With Incomplete Data
30.7. SFTP Streaming Inbound Channel Adapter
30.7.1. Configuring with Java Configuration
30.8. Inbound Channel Adapters: Polling Multiple Servers and Directories
30.9. Inbound Channel Adapters: Controlling Remote File Fetching
30.10. SFTP Outbound Channel Adapter
30.10.1. SpEL and the SFTP Outbound Adapter
30.10.2. Avoiding Partially Written Files
30.10.3. Configuring with Java Configuration
30.10.4. Configuring with the Java DSL
30.11. SFTP Outbound Gateway
30.11.1. Using the ls Command
30.11.2. Using the get Command
30.11.3. Using the mget Command
30.11.4. Using the put Command
30.11.5. Using the mput Command
30.11.6. Using the mv Command
30.11.7. Additional Command Information
30.11.8. Configuring with Java Configuration
30.11.9. Configuring with the Java DSL
30.11.10. Outbound Gateway Partial Success (mget and mput)
30.12. SFTP/JSCH Logging
30.13. MessageSessionCallback
31. STOMP Support
31.1. Overview
31.2. STOMP Inbound Channel Adapter
31.3. STOMP Outbound Channel Adapter
31.4. STOMP Headers Mapping
31.5. STOMP Integration Events
31.6. STOMP Adapters Java Configuration
31.7. STOMP Namespace Support
31.7.1. Understanding the <int-stomp:outbound-channel-adapter> Element
31.7.2. Understanding the <int-stomp:inbound-channel-adapter> Element
32. Stream Support
32.1. Reading from Streams
32.2. Writing to Streams
32.3. Stream Namespace Support
33. Syslog Support
33.1. Syslog Inbound Channel Adapter
33.1.1. Example Configuration
34. TCP and UDP Support
34.1. Introduction
34.2. UDP Adapters
34.2.1. Outbound UDP Adapters (XML Configuration)
34.2.2. Outbound UDP Adapters (Java Configuration)
34.2.3. Outbound UDP Adapters (Java DSL Configuration)
34.2.4. Inbound UDP Adapters (XML Configuration)
34.2.5. Inbound UDP Adapters (Java Configuration)
34.2.6. Inbound UDP Adapters (Java DSL Configuration)
34.2.7. Server Listening Events
34.2.8. Advanced Outbound Configuration
34.3. TCP Connection Factories
34.3.1. TCP Caching Client Connection Factory
34.3.2. TCP Failover Client Connection Factory
34.3.3. TCP Thread Affinity Connection Factory
34.4. TCP Connection Interceptors
34.5. TCP Connection Events
34.6. TCP Adapters
34.7. TCP Gateways
34.8. TCP Message Correlation
34.8.1. Gateways
34.8.2. Collaborating Outbound and Inbound Channel Adapters
34.8.3. Transferring Headers
34.9. About Non-blocking I/O (NIO)
34.9.1. Pool Size
34.9.2. Thread Pool Task Executor with CALLER_RUNS Policy
34.10. SSL/TLS Support
34.10.1. Getting Started
34.10.2. Host Verification
34.11. Advanced Techniques
34.11.1. Strategy Interfaces
The TcpSSLContextSupport Strategy Interface
The TcpSocketFactorySupport Strategy Interface
The TcpSocketSupport Strategy Interface
The TcpNetConnectionSupport Strategy Interface
The TcpNioConnectionSupport Strategy Interface
34.11.2. Example: Enabling SSL Client Authentication
34.12. IP Configuration Attributes
34.13. IP Message Headers
34.14. Annotation-Based Configuration
35. WebFlux Support
35.1. WebFlux Inbound Components
35.2. WebFlux Outbound Components
35.3. WebFlux Namespace Support
35.3.1. Inbound
35.3.2. Outbound
35.4. Configuring WebFlux Endpoints with Java
35.5. WebFlux Header Mappings
36. WebSockets Support
36.1. Overview
36.2. WebSocket Inbound Channel Adapter
36.3. WebSocket Outbound Channel Adapter
36.4. WebSockets Namespace Support
36.4.1. <int-websocket:client-container> Attributes
36.4.2. <int-websocket:server-container> Attributes
36.4.3. <int-websocket:outbound-channel-adapter> Attributes
36.4.4. <int-websocket:inbound-channel-adapter> Attributes
36.5. Using ClientStompEncoder
37. Web Services Support
37.1. Outbound Web Service Gateways
37.2. Inbound Web Service Gateways
37.3. Web Service Namespace Support
37.4. Outbound URI Configuration
37.4.1. Controlling URI Encoding
37.5. WS Message Headers
37.6. MTOM Support
38. XML Support - Dealing with XML Payloads
38.1. Namespace Support
38.1.1. XPath Expressions
Providing Namespaces (Optional) to XPath Expressions
Using XPath Expressions with Default Namespaces
38.2. Transforming XML Payloads
38.2.1. Configuring Transformers as Beans
UnmarshallingTransformer
Using MarshallingTransformer
XsltPayloadTransformer
Using ResultTransformer Implementations
38.2.2. Namespace Support for XML Transformers
Using an UnmarshallingTransformer
Using a MarshallingTransformer
Using an XsltPayloadTransformer
38.2.3. Namespace Configuration and Result Transformers
XsltPayloadTransformer and <xsl:output method="text"/>
38.3. Transforming XML Messages with XPath
38.3.1. Simple XPath Transformation
38.3.2. Node Mappers
38.3.3. XML Payload Converter
38.4. Splitting XML Messages
38.5. Routing XML Messages with XPath
38.5.1. XML Payload Converter
38.6. XPath Header Enricher
38.7. Using the XPath Filter
38.8. #xpath SpEL Function
38.9. XML Validating Filter
39. XMPP Support
39.1. XMPP Connection
39.2. XMPP Messages
39.2.1. Inbound Message Channel Adapter
39.2.2. Outbound Message Channel Adapter
39.3. XMPP Presence
39.3.1. Inbound Presence Message Channel Adapter
39.3.2. Outbound Presence Message Channel Adapter
39.4. Advanced Configuration
39.5. XMPP Message Headers
39.6. XMPP Extensions
40. Zookeeper Support
40.1. Zookeeper Metadata Store
40.2. Zookeeper Lock Registry
40.3. Zookeeper Leadership Event Handling
VI. Appendices
A. Spring Expression Language (SpEL)
A.1. SpEL Evaluation Context Customization
A.2. SpEL Functions
A.2.1. Built-in SpEL Functions
A.3. Property Accessors
B. Message Publishing
B.1. Message Publishing Configuration
B.1.1. Annotation-driven Configuration with the @Publisher Annotation
B.1.2. XML-based Approach with the <publishing-interceptor> element
Asynchronous Publishing
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. Securing channels
D.2. Security Context Propagation
E. Configuration
E.1. Namespace Support
E.2. Configuring the Task Scheduler
E.3. Error Handling
E.4. Global Properties
E.5. Annotation Support
E.5.1. Using the @Poller Annotation
E.5.2. Using the @InboundChannelAdapter Annotation
E.5.3. Using the @IntegrationComponentScan Annotation
E.6. Messaging Meta-Annotations
E.6.1. Annotations on @Bean Methods
E.6.2. Creating a Bridge with Annotations
E.6.3. Advising Annotated Endpoints
E.7. Message Mapping Rules and Conventions
E.7.1. Sample Scenarios
E.7.2. Annotation-based Mapping
E.7.3. Complex Scenarios
F. Testing support
F.1. Testing Utilities
F.1.1. TestUtils
F.1.2. Using the SocketUtils Class
F.1.3. Using OnlyOnceTrigger
F.1.4. Support Components
F.1.5. JUnit Rules and Conditions
F.1.6. Hamcrest and Mockito Matchers
F.2. Spring Integration and the Test Context
F.3. Integration Mocks
F.3.1. MockIntegration
F.4. Other Resources
G. Spring Integration Samples
G.1. Where to Get Samples
G.2. Submitting Samples or Sample Requests
G.2.1. How Can I Contribute My Own Samples?
G.2.2. Code Contribution Process
G.2.3. Sample Requests
G.3. Samples Structure
G.4. Samples
G.4.1. Loan Broker
Design
Composed Message Processor
G.4.2. The Cafe Sample
G.4.3. The XML Messaging Sample
H. Additional Resources
I. Change History
I.1. Changes between 4.3 and 5.0
I.2. New Components
I.2.1. Java DSL
I.2.2. Testing Support
I.2.3. MongoDB Outbound Gateway
I.2.4. WebFlux Gateways and Channel Adapters
I.2.5. Content Type Conversion
I.2.6. ErrorMessagePublisher and ErrorMessageStrategy
I.2.7. JDBC Metadata Store
I.3. General Changes
I.3.1. Core Changes
I.3.2. Gateway Changes
I.3.3. Aggregator Performance Changes
I.3.4. Splitter Changes
I.3.5. JMS Changes
I.3.6. Mail Changes
I.3.7. Feed Changes
I.3.8. File Changes
I.3.9. FTP and SFTP Changes
I.3.10. Integration Properties
I.3.11. Stream Changes
I.3.12. Barrier Changes
I.3.13. AMQP Changes
I.3.14. HTTP Changes
I.3.15. MQTT Changes
I.3.16. STOMP Changes
I.3.17. Web Services Changes
I.3.18. Redis Changes
I.3.19. TCP Changes
I.3.20. Gemfire Changes
I.3.21. JDBC Changes
I.3.22. Metrics Changes
I.3.23. @EndpointId Annotations
I.4. Changes between 4.2 and 4.3
I.5. New Components
I.5.1. AMQP Async Outbound Gateway
I.5.2. MessageGroupFactory
I.5.3. PersistentMessageGroup
I.5.4. FTP and SFTP Streaming Inbound Channel Adapters
I.5.5. StreamTransformer
I.5.6. Integration Graph
I.5.7. JDBC Lock Registry
I.5.8. LeaderInitiator for LockRegistry
I.6. General Changes
I.6.1. Core Changes
Outbound Gateway within a Chain
Asynchronous Service Activator
Messaging Annotation Support changes
I.6.2. Mail Changes
Customizable User Flag
Mail Message Mapping
I.6.3. JMS Changes
Header Mapper
Asynchronous Gateway
I.6.4. Aggregator Changes
I.6.5. TCP/UDP Changes
Events
Stream Deserializers
TCP Message Mapper
I.6.6. File Changes
Destination Directory Creation
Buffer Size
Appending and Flushing
Preserving Timestamps
Splitter Changes
File Filters
I.6.7. AMQP Changes
Content Type Message Converter
Headers for Delayed Message Handling
AMQP-Backed Channels
I.6.8. Redis Changes
List Push/Pop Direction
Queue Inbound Gateway Default Serializer
I.6.9. HTTP Changes
I.6.10. SFTP Changes
Factory Bean
chmod Changes
I.6.11. FTP Changes
Session Changes
I.6.12. Router Changes
I.6.13. Header Mapping
General
AMQP Header Mapping
I.6.14. Groovy Scripts
I.6.15. @InboundChannelAdapter Changes
I.6.16. XMPP Changes
I.6.17. WireTap Late Binding
I.6.18. ChannelMessageStoreQueryProvider Changes
I.6.19. WebSocket Changes
I.7. Changes between 4.1 and 4.2
I.8. New Components
I.8.1. Major Management/JMX Rework
I.8.2. MongoDB Metadata Store
I.8.3. SecuredChannel Annotation
I.8.4. SecurityContext Propagation
I.8.5. FileSplitter
I.8.6. Zookeeper Support
I.8.7. Thread Barrier
I.8.8. STOMP Support
I.8.9. Codec
I.8.10. Message PreparedStatement Setter
I.9. General Changes
I.9.1. WireTap
I.9.2. File Changes
Appending New Lines
Ignoring Hidden Files
Writing InputStream Payloads
HeadDirectoryScanner
Last Modified Filter
Watch Service Directory Scanner
Persistent File List Filter Changes
I.9.3. Class Package Change
I.9.4. TCP Changes
TCP Serializers
Server Socket Exceptions
TCP Server Port
TCP Gateway Remote Timeout
TCP SSLSession Available for Header Mapping
TCP Events
I.9.5. @InboundChannelAdapter Changes
I.9.6. API Changes
I.9.7. JMS Changes
Reply Listener Lazy Initialization
Conversion Errors in Message-Driven Endpoints
Default Acknowledge Mode
Shared Subscriptions
I.9.8. Conditional Pollers
I.9.9. AMQP Changes
Publisher Confirmations
Correlation Data
Inbound Gateway Properties
I.9.10. XPath Splitter Improvements
I.9.11. HTTP Changes
CORS
Inbound Gateway Timeout
Form Data
I.9.12. Gateway Changes
Gateway Methods can Return CompletableFuture<?>
MessagingGateway Annotation
I.9.13. Aggregator Changes
Aggregator Performance
Output Message Group Processor
I.9.14. FTP and SFTP Changes
Inbound Channel Adapters
Gateway Partial Results
Delegating Session Factory
Default Sftp Session Factory
Message Session Callback
I.9.15. Websocket Changes
I.9.16. Application Event Adapters changes
I.10. Changes between 4.0 and 4.1
I.10.1. New Components
Promise<?> Gateway
WebSocket support
Scatter-Gather Enterprise Integration Pattern
Routing Slip Pattern
Idempotent Receiver Pattern
Boon JsonObjectMapper
Redis Queue Gateways
PollSkipAdvice
I.10.2. General Changes
AMQP Inbound Endpoints, Channel
AMQP Outbound Endpoints
SimpleMessageStore
Web Service Outbound Gateway: encode-uri
Http Inbound Channel Adapter and Status Code
MQTT Adapter Changes
FTP and SFTP Adapter Changes
Splitter and Iterator
Aggregator
Content Enricher Improvements
Header Channel Registry
Orderly Shutdown
Management for RecipientListRouter
AbstractHeaderMapper: NON_STANDARD_HEADERS token
AMQP Channels: template-channel-transacted
Syslog Adapter
Asynchronous Gateway
Aggregator Advice Chain
Outbound Channel Adapter and Scripts
Resequencer Changes
Optional POJO method parameter
QueueChannel backed Queue type
ChannelInterceptor Changes
IMAP PEEK
I.11. Changes between 3.0 and 4.0
I.11.1. New Components
MQTT Channel Adapters
@EnableIntegration
@IntegrationComponentScan
"@EnableMessageHistory"
@MessagingGateway
Spring Boot @EnableAutoConfiguration
@GlobalChannelInterceptor
@IntegrationConverter
@EnablePublisher
Redis Channel Message Stores
MongodDB Channel Message Store
@EnableIntegrationMBeanExport
ChannelSecurityInterceptorFactoryBean
Redis Command Gateway
RedisLockRegistry and GemfireLockRegistry
@Poller
@InboundChannelAdapter and SmartLifecycle for Annotated Endpoints
Twitter Search Outbound Gateway
Gemfire Metadata Store
@BridgeFrom and @BridgeTo Annotations
Meta-messaging Annotations
I.11.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
I.12. Changes Between 2.2 and 3.0
I.12.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
I.12.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
XsltPayloadTransformer
I.13. Changes between 2.1 and 2.2
I.13.1. New Components
RedisStore Inbound and Outbound Channel Adapters
MongoDB Inbound and Outbound Channel Adapters
JPA Endpoints
I.13.2. General Changes
Spring 3.1 Used by Default
Adding Behavior to Endpoints
Transaction Synchronization and Pseudo Transactions
File Adapter: Improved File Overwrite and 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 Outbound Gateway Improvements
ObjectToJsonTransformer
HTTP Support
I.14. Changes between 2.0 and 2.1
I.14.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
I.14.2. Framework Refactoring
Standardizing Router Configuration
XML Schemas updated to 2.1
I.14.3. Source Control Management and Build Infrastructure
Source Code Now Hosted on Github
Improved Source Code Visibility with Sonar
I.14.4. New Samples
I.15. Changes between Versions 1.0 and 2.0
I.15.1. Spring 3 support
Support for the Spring Expression Language (SpEL)
Conversion Service and Converter
TaskScheduler and Trigger
RestTemplate and HttpMessageConverter
I.15.2. Enterprise Integration Pattern Additions
Message History
Message Store
Claim Check
Control Bus
I.15.3. New Channel Adapters and Gateways
TCP and UDP Adapters
Twitter Adapters
XMPP Adapters
FTP and FTPS Adapters
SFTP Adapters
Feed Adapters
I.15.4. Other Additions
Groovy Support
Map Transformers
JSON Transformers
Serialization Transformers
I.15.5. Framework Refactoring
I.15.6. New Source Control Management and Build Infrastructure
I.15.7. New Spring Integration Samples
I.15.8. Spring Tool Suite Visual Editor for Spring Integration

© 2009-2018 Pivotal Software, Inc. All rights reserved.

[Note]Note

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.

Part I. Preface

1. Requirements

This section details the compatible Java and Spring Framework versions.

1.1 Compatible Java Versions

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

1.2 Compatible Versions of the Spring Framework

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

2. Code Conventions

Spring Framework 2.0 introduced support for namespaces, which simplifies the XML configuration of the application context and lets Spring Integration provide broad namespace support.

In this reference guide, the int namespace prefix is used for Spring Integration’s core namespace support. Each Spring Integration adapter type (also called a module) provides its own namespace, which is configured by using the following convention:

The following example shows the int, int-event, and int-stream namespaces in use:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:int="http://www.springframework.org/schema/integration"
  xmlns:int-webflux="http://www.springframework.org/schema/integration/webflux"
  xmlns:int-stream="http://www.springframework.org/schema/integration/stream"
  xsi:schemaLocation="
   http://www.springframework.org/schema/beans
   http://www.springframework.org/schema/beans/spring-beans.xsd
   http://www.springframework.org/schema/integration
   http://www.springframework.org/schema/integration/spring-integration.xsd
   http://www.springframework.org/schema/integration/webflux
   http://www.springframework.org/schema/integration/webflux/spring-integration-webflux.xsd
   http://www.springframework.org/schema/integration/stream
   http://www.springframework.org/schema/integration/stream/spring-integration-stream.xsd"></beans>

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

[Note]Note

The namespace prefix can be freely chosen. You may even choose not to use any namespace prefixes at all. Therefore, you should apply the convention that best suits your application. Be aware, though, that SpringSource Tool Suite™ (STS) uses the same namespace conventions for Spring Integration as used in this reference guide.

3. Conventions in This Guide

In some cases, to aid formatting when specifying long fully qualified class names, we shorten 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 5.1. If you are interested in the changes and features that were introduced in earlier versions, see the Appendix I, Change History.

4. What’s New in Spring Integration 5.1?

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

4.1 New Components

The following components are new in 5.1:

4.1.1 AmqpDedicatedChannelAdvice

See Section 14.13, “Strict Message Ordering”.

4.1.2 Improved Function Support

The java.util.function interfaces now have improved integration support in the Framework components. Also Kotlin lambdas now can be used for handler and source methods.

See Section 10.11, “java.util.function Interfaces Support”.

4.1.3 @LongRunningTest

A JUnit 5 @LongRunningTest conditional annotation is provided to check the environment or system properties for the RUN_LONG_INTEGRATION_TESTS entry with the value of true to determine if test should be run or skipped.

See Section F.1.5, “JUnit Rules and Conditions”.

4.2 General Changes

The following changes have been made in version 5.1:

4.2.1 Java DSL

The IntegrationFlowContext is now an interface and IntegrationFlowRegistration is an inner interface of IntegrationFlowContext.

A new logAndReply() operator has been introduced for convenience when you wish to log at the end of a flow for request-reply configurations. This avoid confusion with log() which is treated as a one-way end flow component.

A generated bean name for any NamedComponent within an integration flow is now based on the component type for better readability from visual tools, logs analyzers and metrics collectors.

The GenericHandler.handle() now excepts a MessageHeaders type for the second argument.

4.2.2 Dispatcher Exceptions

Exceptions caught and re-thrown by AbstractDispatcher are now more consistent:

  • A MessagingException of any kind that has a failedMessage property is re-thrown unchanged.
  • All other exceptions are wrapped in a MessageDeliveryException with the failedMessage property set.

Previously:

  • A MessagingException of any kind that has a failedMessage property was re-thrown unchanged
  • A MessagingException that had no failedMessage property was wrapped in a MessagingException with the failedMessage property set.
  • Other RuntimeException instances were re-thrown unchanged.
  • Checked exceptions were wrapped in a MessageDeliveryException with the failedMessage property set.

4.2.3 Global Channel Interceptors

Global channel interceptors now apply to dynamically registered channels, such as through the IntegrationFlowContext when using the Java DSL or beans that are initialized using beanFactory.initializeBean(). Previously, when beans were created after the application context was refreshed, interceptors were not applied.

4.2.4 Channel Interceptors

ChannelInterceptor.postReceive() is no longer called when no message is received; it is no longer necessary to check for a null Message<?>. Previously, the method was called. If you have an interceptor that relies on the previous behavior, implement afterReceiveCompleted() instead, since that method is invoked, regardless of whether a message is received or not. Furthermore, the PolledAmqpChannel and PolledJmsChannel previously did not invoke afterReceiveCompleted() with null; they now do.

4.2.5 ObjectToJsonTransformer

A new ResultType.BYTES mode is introduced for the ObjectToJsonTransformer.

See the section called “JSON Transformers” for more information.

4.2.6 Integration Flows: Generated Bean Names

Starting with version 5.0.5, generated bean names for the components in an IntegrationFlow include the flow bean name, followed by a dot, as a prefix. For example, if a flow bean were named flowBean, a generated bean might be named flowBean.generatedBean.

See Section 11.13, “Working With Message Flows” for more information.

4.2.7 Aggregator Changes

If the groupTimeout is evaluated to a negative value, an aggregator now expires the group immediately. Only null is considered as a signal to do nothing for the current message.

A new popSequence property has been introduced to allow (by default) to call a MessageBuilder.popSequenceDetails() for the output message. Also an AbstractAggregatingMessageGroupProcessor returns now an AbstractIntegrationMessageBuilder instead of the whole Message for optimization.

See Section 8.4, “Aggregator” for more information.

4.2.8 @Publisher annotation changes

Starting with version 5.1, you must explicitly turn on the @Publisher AOP functionality by using @EnablePublisher or by using the <int:enable-publisher> child element on <int:annotation-config>.

See Section B.1.1, “Annotation-driven Configuration with the @Publisher Annotation” for more information.

4.3 Files Changes

If you are using FileExistsMode.APPEND or FileExistsMode.APPEND_NO_FLUSH you can provide a newFileCallback that will be called when creating a new file. This callback receives the newly created file and the message that triggered the callback. This could be used to write a CSV header, for an example.

The FileReadingMessageSource now doesn’t check and create a directory until its start() is called. So, if an Inbound Channel Adapter for the FileReadingMessageSource has autoStartup = false, there are no failures against the file system during application start up.

See Chapter 17, File Support for more information.

4.4 AMQP Changes

We have made ID and Timestamp header mapping changes in the DefaultAmqpHeaderMapper. See the note near the bottom of Section 14.12, “AMQP Message Headers” for more information.

The contentType header is now correctly mapped as an entry in the general headers map. See Section 14.12.2, “contentType Header” for more information.

4.5 JDBC Changes

A confusing max-rows-per-poll property on the JDBC Inbound Channel Adapter and JDBC Outbound Gateway has been deprecated in favor of the newly introduced max-rows property.

The JdbcMessageHandler supports now a batchUpdate functionality when the payload of the request message is an instance of an Iterable type.

The indexes for the INT_CHANNEL_MESSAGE table (for the JdbcChannelMessageStore) have been optimized. If you have large message groups in such a store, you may wish to alter the indexes.

See Chapter 21, JDBC Support for more information.

4.6 FTP and SFTP Changes

A RotatingServerAdvice is now available to poll multiple servers and directories with the inbound channel adapters. See Section 18.6, “Inbound Channel Adapters: Polling Multiple Servers and Directories” and Section 30.8, “Inbound Channel Adapters: Polling Multiple Servers and Directories” for more information.

Also, inbound adapter localFilenameExpression instances can contain the #remoteDirectory variable, which contains the remote directory being polled. The generic type of the comparators (used to sort the fetched file list for the streaming adapters) has changed from Comparator<AbstractFileInfo<F>> to Comparator<F>. See Section 18.5, “FTP Streaming Inbound Channel Adapter” and Section 30.7, “SFTP Streaming Inbound Channel Adapter” for more information.

In addition, the synchronizers for inbound channel adapters can now be provided with a Comparator. This is useful when using maxFetchSize to limit the files retrieved.

The CachingSessionFactory has a new property testSession which, when true, causes the factory to perform a test() operation on the Session when checking out an existing session from the cache.

See Section 30.4, “SFTP Session Caching” and Section 18.10, “FTP Session Caching” for more information.

The outbound gateway MPUT command now supports a message payload with a collection of files or strings. See Section 30.11, “SFTP Outbound Gateway” and Section 18.9, “FTP Outbound Gateway” for more information.

4.7 TCP Support

When using SSL, host verification is now enabled, by default, to prevent man-in-the-middle attacks with a trusted certificate. See Section 34.10.2, “Host Verification” for more information.

In addition the key and trust store types can now be configured on the DefaultTcpSSLContextSupport.

4.8 Twitter Support

Since the Spring Social project has moved to end of life status, Twitter support in Spring Integration has been moved to the Extensions project. See Spring Integration Social Twitter for more information.

4.9 JMS Support

The JmsSendingMessageHandler now provides deliveryModeExpression and timeToLiveExpression options to determine respective QoS options for JMS message to send at runtime. The DefaultJmsHeaderMapper now allows to map inbound JMSDeliveryMode and JMSExpiration properties via setting to true respective setMapInboundDeliveryMode() and setMapInboundExpiration() options. When a JmsMessageDrivenEndpoint or JmsInboundGateway is stopped, the associated listener container is now shut down; this closes its shared connection and any consumers. You can configure the endpoints to revert to the previous behavior.

See Chapter 23, JMS Support for more information.

4.10 HTTP/WebFlux Support

The statusCodeExpression (and Function) is now supplied with the RequestEntity<?> as a root object for evaluation context, so request headers, method, URI and body are available for target status code calculation.

See Chapter 20, HTTP Support and Chapter 35, WebFlux Support for more information.

4.11 JMX Changes

Object name key values are now quoted if they contain any characters other than those allowed in a Java identifier (or period .). e.g. org.springframework.integration:type=MessageChannel, name="input:foo.myGroup.errors". This has the side effect that previously "allowed" names, with such characters, will now be quoted. e.g. org.springframework.integration:type=MessageChannel, name="input#foo.myGroup.errors".

4.12 Micrometer Support Changes

It is now simpler to customize the standard Micrometer meters created by the framework. See Section 12.1.2, “Micrometer Integration” for more information.

4.13 Integration Graph Customization

It is now possible to add additional properties to the IntegrationNode s via Function<NamedComponent, Map<String, Object>> additionalPropertiesCallback on the IntegrationGraphServer. See Section 12.8, “Integration Graph” for more information.

4.14 Integration Global Properties

The Integration global properties (including defaults) can now be printed in the logs, when a DEBUG logic level is turned on for the org.springframework.integration category. See Section E.4, “Global Properties” for more information.

4.15 The receiveTimeout for @Poller

The @Poller annotation now provides a receiveTimeout option for convenience. See Section E.5.1, “Using the @Poller Annotation” 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 through 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.

5. Spring Integration Overview

This chapter provides a high-level introduction to Spring Integration’s core concepts and components. It includes some programming tips to help you make the most of Spring Integration.

5.1 Background

One of the key themes of the Spring Framework is Inversion of Control (IoC). 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, because 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 from 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 run 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. 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 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 patterns described in Enterprise Integration Patterns, 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.

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

5.3 Main Components

From a 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 components capable of producing 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 should be managed within a layer that is logically above the application’s service layer, interacting with those services through interfaces in much the same way that a web tier would.

5.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, and others) may be configured as message header values by an upstream component. Developers can also store any arbitrary key-value pairs in the headers.

Figure 5.1. Message

Message

5.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 5.2. Message Channel

Message Channel

A message channel may follow either point-to-point or publish-subscribe semantics. With a point-to-point channel, no more than one consumer can receive each message sent to the channel. Publish-subscribe channels, on the other hand, attempt to broadcast each message to all subscribers on the channel. Spring Integration supports both of these models.

Whereas "point-to-point" and "publish-subscribe" define the two options for how many consumers 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. Section 6.1.2, “Message Channel Implementations” has a detailed discussion of the variety of channel implementations available in Spring Integration.

5.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 should necessarily connect your existing application code directly. Any real-world enterprise integration solution requires some amount of code focused upon integration concerns such as routing and transformation. The important thing is to achieve separation of concerns between the integration logic and the business logic. In other words, as with the Model-View-Controller (MVC) 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 provides an overview of the message endpoint types that handle these responsibilities, and, in upcoming chapters, you can see how Spring Integration’s declarative configuration options provide a non-invasive way to use each of these.

5.4 Message Endpoints

A Message Endpoint represents the "filter" of a pipes-and-filters architecture. As mentioned earlier, 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 and all of the patterns that follow are discussed at length in the Enterprise Integration Patterns book. Here, we provide only a high-level description of the main endpoint types supported by Spring Integration and the roles associated with those types. The chapters that follow elaborate and provide sample code as well as configuration examples.

5.4.1 Message 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 (such as from XML to java.lang.String). Similarly, a transformer can add, remove, or modify the message’s header values.

5.4.2 Message 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, or other conditions. If the message is accepted, it is sent to the output channel. If not, it is 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 criteria of the filter to narrow down the set of messages to be processed.

[Note]Note

Be careful not to confuse the generic use of "filter" within the pipes-and-filters architectural pattern with this specific endpoint type that selectively narrows down the messages flowing between two channels. The pipes-and-filters concept of a "filter" matches more closely with Spring Integration’s message endpoint: any component that can be connected to a message channel in order to send or receive messages.

5.4.3 Message Router

A message router is responsible for deciding what channel or channels (if any) should receive the message next. Typically, the decision is based upon the message’s content or the 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 earlier.

Figure 5.3. Message Router

Router

5.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 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 subdivided payloads.

5.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, discard them, or send 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.

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

[Note]Note

The output channel is optional, since each message may also provide its own Return Address header. This same rule applies for all consumer endpoints.

The service activator invokes an operation on some service object to process the request message, extracting the request message’s payload and converting (if the method does not expect a message-typed parameter). Whenever the service object’s method returns a value, that return value is likewise converted to a reply message if necessary (if it is not already a message type). That reply message is sent to the output channel. If no output channel has been configured, the reply is 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 5.4. Service Activator

handler endpoint

[Note]Note

As discussed earlier, in Message Channel, channels can be pollable or subscribable. In the preceding diagram, this is depicted by the "clock" symbol and the solid arrow (poll) and the dotted arrow (subscribe).

5.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 does some mapping between the message and whatever object or resource is received from or sent to the other system (file, HTTP Request, JMS message, and others). Depending on the transport, the channel adapter may also populate or extract message header values. Spring Integration provides a number of channel adapters, which are described in upcoming chapters.

Figure 5.5. An inbound channel adapter endpoint connects a source system to a MessageChannel.

source endpoint

[Note]Note

Message sources can be pollable (for example, POP3) or message-driven_ (for example, IMAP Idle). In the preceding diagram, this is depicted by the "clock" symbol and the solid arrow (poll) and the dotted arrow (message-driven).

Figure 5.6. An outbound channel adapter endpoint connects a MessageChannel to a target system.

target endpoint

[Note]Note

As discussed earlier in Message Channel, channels can be pollable or subscribable. In the preceding diagram, this is depicted by the "clock" symbol and the solid arrow (poll) and the dotted arrow (subscribe).

5.4.8 Endpoint Bean Names

Consuming endpoints (anything with an inputChannel) consist of two beans, the consumer and the message handler. The consumer has a reference to the message handler and invokes it as messages arrive.

Consider the following XML example:

<int:service-activator id = "someService" ... />

Given the preceding example, the bean names are as follows:

  • Consumer: someService (the id)
  • Handler: someService.handler

When using Enterprise Integration Pattern (EIP) annotations, the names depend on several factors. Consider the following example of an annotated POJO:

@Component
public class SomeComponent {

    @ServiceActivator(inputChannel = ...)
    public String someMethod(...) {
        ...
    }

}

Given the preceding example, the bean names are as follows:

  • Consumer: someComponent.someMethod.serviceActivator
  • Handler: someComponent.someMethod.serviceActivator.handler

Starting with version 5.0.4, you can modify these names by using the @EndpointId annotation, as the following example shows:

@Component
public class SomeComponent {

    @EndpointId("someService")
    @ServiceActivator(inputChannel = ...)
    public String someMethod(...) {
        ...
    }

}

Given the preceding example, the bean names are as follows:

  • Consumer: someService
  • Handler: someService.handler

The @EndpointId creates names as created by the id attribute with XML configuration. Consider the following example of an annotated bean:

@Configuratiom
public class SomeConfiguration {

    @Bean
    @ServiceActivator(inputChannel = ...)
    public MessageHandler someHandler() {
        ...
    }

}

Given the preceding example, the bean names are as follows:

  • Consumer: someConfiguration.someHandler.serviceActivator
  • Handler: someHandler (the @Bean name)

Starting with version 5.0.4, you can modify these names by using the @EndpointId annotation, as the following example shows:

@Configuratiom
public class SomeConfiguration {

    @Bean("someService.handler")             1
    @EndpointId("someService")               2
    @ServiceActivator(inputChannel = ...)
    public MessageHandler someHandler() {
        ...
    }

}

1

Handler: someService.handler (the bean name)

2

Consumer: someService (the endpoint ID)

The @EndpointId annotation creates names as created by the id attribute with XML configuration, as long as you use the convention of appending .handler to the @Bean name.

There is one special case where a third bean is created: For architectural reasons, if a MessageHandler @Bean does not define an AbstractReplyProducingMessageHandler, the framework wraps the provided bean in a ReplyProducingMessageHandlerWrapper. This wrapper supports request handler advice handling and emits the normal produced no reply debug log messages. Its bean name is the handler bean name plus .wrapper (when there is an @EndpointId — otherwise, it is the normal generated handler name).

Similarly Pollable Message Sources create two beans, a SourcePollingChannelAdapter (SPCA) and a MessageSource.

Consider the following XML configuration:

<int:inbound-channel-adapter id = "someAdapter" ... />

Given the preceding XML configuration, the bean names are as follows:

  • SPCA: someAdapter (the id)
  • Handler: someAdapter.source

Consider the following Java configuration of a POJO to define an @EndpointId:

@EndpointId("someAdapter")
@InboundChannelAdapter(channel = "channel3", poller = @Poller(fixedDelay = "5000"))
public String pojoSource() {
    ...
}

Given the preceding Java configuration example, the bean names are as follows:

  • SPCA: someAdapter
  • Handler: someAdapter.source

Consider the following Java configuration of a bean to define an @EndpointID:

@Bean("someAdapter.source")
@EndpointId("someAdapter")
@InboundChannelAdapter(channel = "channel3", poller = @Poller(fixedDelay = "5000"))
public MessageSource<?> source() {
    return () -> {
        ...
    };
}

Given the preceding example, the bean names are as follows:

  • SPCA: someAdapter
  • Handler: someAdapter.source (as long as you use the convention of appending .source to the @Bean name)

5.5 Configuration and @EnableIntegration

Throughout this document, you can 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 (a task scheduler, an implicit channel creator, and others) that are used to support the runtime environment.

[Important]Important

Version 4.0 introduced the @EnableIntegration annotation, to allow the registration of Spring Integration infrastructure beans (see the Javadoc). This annotation is required when only Java configuration is used — for example with Spring Boot 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 two or more child contexts that use Spring Integration. It lets these common components be declared once only, in the parent context.

The @EnableIntegration annotation registers many infrastructure components with the application context. In particular, it:

  • Registers some built-in beans, such as errorChannel and its LoggingHandler, taskScheduler for pollers, jsonPath SpEL-function, and others.
  • Adds several BeanFactoryPostProcessor instances to enhance the BeanFactory for global and default integration environment.
  • Adds several BeanPostProcessor instances to enhance or convert and wrap particular beans for integration purposes.
  • Adds annotation processors to parse messaging annotations and registers components for them with the application context.

The @IntegrationComponentScan annotation also permits classpath scanning. This annotation plays a similar role as the standard Spring Framework @ComponentScan annotation, but it is restricted to components and annotations that are specific to Spring Integration, which the standard Spring Framework component scan mechanism cannot reach. For an example, see Section 10.4.6, “@MessagingGateway Annotation”.

The @EnablePublisher annotation registers a PublisherAnnotationBeanPostProcessor bean and configures the default-publisher-channel for those @Publisher annotations that 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 Configuration with the @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 implement ChannelInterceptor.

Starting with version 5.1, global channel interceptors apply to dynamically registered channels — such as beans that are initialized by using beanFactory.initializeBean() or through the IntegrationFlowContext when using the Java DSL. Previously, interceptors were not applied when beans were created after the application context was refreshed.

The @IntegrationConverter annotation marks Converter, GenericConverter, or ConverterFactory beans as candidate converters for integrationConversionService. This annotation is an analogue of the <int:converter> XML element (see Section 10.1.6, “Payload Type Conversion”). You can place @IntegrationConverter annotations at the class level (with a @Component stereotype annotation) or on @Bean methods within @Configuration classes.

See Section E.5, “Annotation Support” for more information about messaging mnnotations.

5.6 Programming Considerations

You should use plain old java objects (POJOs) whenever possible and only expose the framework in your code when absolutely necessary. See Section 5.8, “POJO Method invocation” for more information.

If you do expose the framework to your classes, there are some considerations that need to be taken into account, especially during application startup:

  • If your component is ApplicationContextAware, you should generally not use the ApplicationContext in the setApplicationContext() method. Instead, 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 is likely to 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.

5.6.1 Considerations When Using Packaged (for example, Shaded) Jars

Spring Integration bootstraps certain features by using Spring Framework’s SpringFactories mechanism to load several IntegrationConfigurationInitializer classes. This includes the -core jar as well as certain others, including -http and -jmx. The information for this process is stored in a META-INF/spring.factories file in each jar.

Some developers prefer to repackage their application and all dependencies into a single jar by using well known tools, such as the Apache Maven Shade Plugin.

By default, the shade plugin does not merge the spring.factories files when producing the shaded jar.

In addition to spring.factories, other META-INF files (spring.handlers and spring.schemas) are used for XML configuration. These files also need to be merged.

[Important]Important

Spring Boot’s executable jar mechanism takes a different approach, in that it nests the jars, thus retaining each spring.factories file on the class path. So, with a Spring Boot application, nothing more is needed if you use its default executable jar format.

Even if you do not use Spring Boot, you can still use the tooling provided by Boot to enhance the shade plugin by adding transformers for the above mentioned files.

You may wish to consult the current spring-boot-starter-parent pom to see the current settings that boot uses. The following example shows how to configure the plugin:

Example 5.1. pom.xml

...
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <configuration>
                <keepDependenciesWithProvidedScope>true</keepDependenciesWithProvidedScope>
                <createDependencyReducedPom>true</createDependencyReducedPom>
            </configuration>
            <dependencies>
                <dependency> 1
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                    <version>${spring.boot.version}</version>
                </dependency>
            </dependencies>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                    <configuration>
                        <transformers> 2
                            <transformer
                                implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
                                <resource>META-INF/spring.handlers</resource>
                            </transformer>
                            <transformer
                                implementation="org.springframework.boot.maven.PropertiesMergingResourceTransformer">
                                <resource>META-INF/spring.factories</resource>
                            </transformer>
                            <transformer
                                implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
                                <resource>META-INF/spring.schemas</resource>
                            </transformer>
                            <transformer
                                implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer" />
                        </transformers>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
...

Specifically,

1

Add the spring-boot-maven-plugin as a dependency.

2

Configure the transformers.


You can add a property for ${spring.boot.version} or use an explicit version.

5.7 Programming Tips and Tricks

This section documents some of the ways to get the most from Spring Integration.

5.7.1 XML Schemas

When using XML configuration, to avoid getting false schema validation errors, you should use a "Spring-aware" IDE, such as the Spring Tool Suite (STS), Eclipse with the Spring IDE plugins, or IntelliJ IDEA. These IDEs know how to resolve the correct XML schema from the classpath (by using the META-INF/spring.schemas file in the jars). When using STS or Eclipse with the plugin, you must enable Spring Project Nature on the project.

The schemas hosted on the internet for certain legacy modules (those that existed in version 1.0) are the 1.0 versions for compatibility reasons. If your IDE uses these schemas, you are likely to see false errors.

Each of these online schemas has a warning similar to the following:

[Important]Important

This schema is for the 1.0 version of Spring Integration Core. We cannot update it to the current schema because that will break any applications using 1.0.3 or lower. For subsequent versions, the unversioned schema is resolved from the classpath and obtained from the jar. Please refer to github:

https://github.com/spring-projects/spring-integration/tree/master/spring-integration-core/src/main/resources/org/springframework/integration/config

The affected modules are

  • core (spring-integration.xsd)
  • file
  • http
  • jms
  • mail
  • rmi
  • security
  • stream
  • ws
  • xml

5.7.2 Finding Class Names for Java and DSL Configuration

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

The first-class citizens for EIP implementation are Message, Channel, and Endpoint (see Section 5.3, “Main Components”, earlier in this chapter). Their implementations (contracts) are:

The first two are simple enough to understand how to implement, configure, and use. The last one deserves more attention

The AbstractEndpoint is widely used throughout the Spring Framework for different component implementations. Its main implementations are:

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

When you use messaging annotations or the Java DSL, you need ot worry about these components, because the Framework automatically produces them with appropriate annotations and BeanPostProcessor implementations. When building components manually, you should use the ConsumerEndpointFactoryBean to help determine the target AbstractEndpoint consumer implementation to create, based on the provided inputChannel property.

On the other hand, the ConsumerEndpointFactoryBean delegates to an another first class citizen in the Framework: org.springframework.messaging.MessageHandler. The goal of the implementation of this interface is to handle the message consumed by the endpoint from the channel. All EIP components in Spring Integration are MessageHandler implementations (for example, AggregatingMessageHandler, MessageTransformingHandler, AbstractMessageSplitter, and others). The target protocol outbound adapters (FileWritingMessageHandler, HttpRequestExecutingMessageHandler, AbstractMqttMessageHandler, and others) are also MessageHandler implementations. When you develop Spring Integration applications with Java configuration, you should look into the Spring Integration module to find an appropriate MessageHandler implementation to use for the @ServiceActivator\ configuration. For example, to send an XMPP message (see Chapter 39, XMPP Support) you should configure something like the following:

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

    DefaultXmppHeaderMapper xmppHeaderMapper = new DefaultXmppHeaderMapper();
    xmppHeaderMapper.setRequestHeaderNames("*");
    handler.setHeaderMapper(xmppHeaderMapper);

    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 into polling and listening behaviors. The listening (message-driven) components are simple and typically require only one target class implementation to be ready to produce messages. Listening components can be one-way MessageProducerSupport implementations, (such as AbstractMqttMessageDrivenChannelAdapter and ImapIdleChannelAdapter) or request-reply MessagingGatewaySupport implementations (such as AmqpInboundGateway and AbstractWebServiceInboundGateway).

Polling inbound endpoints are for those protocols that do not provide a listener API or are not intended for such a behavior, including any file based protocol (such as FTP), any data bases (RDBMS or NoSQL), and others.

These inbound endpoints consist of two components: the poller configuration, to initiate the polling task periodically, and a message source class to read data from the target protocol and produce a message for the downstream integration flow. The first class for the poller configuration is a SourcePollingChannelAdapter. It is one more AbstractEndpoint implementation, but especially for polling to initiate an integration flow. Typically, with the messaging annotations or Java DSL, you should not worry about this class. The Framework produces a bean for it, based on the @InboundChannelAdapter configuration or a Java DSL builder spec.

Message source components are more important for the target application development, and they all implement the MessageSource interface (for example, MongoDbMessageSource and AbstractTwitterMessageSource). With that in mind, our config for reading data from an RDBMS table with JDBC could resemble the following:

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

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

  • o.s.i.websocket.inbound.WebSocketInboundChannelAdapter: Implements MessageProducerSupport to listen for 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, starting with version 4.3, we provide information in the XSD element definitions about which target classes are used to declare beans for the adapter or gateway, as the following example shows:

<xsd:element name="outbound-async-gateway">
    <xsd:annotation>
		<xsd:documentation>
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()'.
       </xsd:documentation>
	</xsd:annotation>

5.8 POJO Method invocation

As discussed in Section 5.6, “Programming Considerations”, we recommend using a POJO programming style, as the following example shows:

@ServiceActivator
public String myService(String payload) { ... }

In this case, the framework extracts a String payload, invokes your method, and wraps the result in a message to send to the next component in the flow (the original headers are copied to the new message). In fact, if you use XML configuration, you do not even need the @ServiceActivator annotation, as the following paired examples show:

<int:service-activator ... ref="myPojo" method="myService" />
public String myService(String payload) { ... }

You can omit the method attribute as long as there is no ambiguity in the public methods on the class.

You can also obtain header information in your POJO methods, as the following example shows:

@ServiceActivator
public String myService(@Payload String payload, @Header("foo") String fooHeader) { ... }

You can also dereference properties on the message, as the following example shows:

@ServiceActivator
public String myService(@Payload("payload.foo") String foo, @Header("bar.baz") String barbaz) { ... }

Because various POJO method invocations are available, versions prior to 5.0 used SpEL (Spring Expression Language) to invoke the POJO methods. SpEL (even interpreted) is usually "fast enough" for these operations, when compared to the actual work usually done in the methods. However, starting with version 5.0, the org.springframework.messaging.handler.invocation.InvocableHandlerMethod is used by default whenever possible. This technique is usually faster to execute than interpreted SpEL and is consistent with other Spring messaging projects. The InvocableHandlerMethod is similar to the technique used to invoke controller methods in Spring MVC. There are certain methods that are still always invoked when using SpEL. Examples include annotated parameters with dereferenced properties, as discussed earlier. This is because SpEL has the capability to navigate a property path.

There may be some other corner cases that we have not considered that also do not work with InvocableHandlerMethod instances. For this reason, we automatically fall back to using SpEL in those cases.

If you wish, you can also set up your POJO method such that it always uses SpEL, with the UseSpelInvoker annotation, as the following example shows:

@UseSpelInvoker(compilerMode = "IMMEDIATE")
public void bar(String bar) { ... }

If the compilerMode property is omitted, the spring.expression.compiler.mode system property determines the compiler mode. See SpEL compilation for more information about compiled SpEL.

Part IV. Core Messaging

This section covers all aspects of the core messaging API in Spring Integration. It covers messages, message channels, and message endpoints. It also covers many of the enterprise integration patterns, such as filter, router, transformer, service activator , splitter, and aggregator. The section also contains material about system management, including the control bus and message history support.

6. Messaging Channels

6.1 Message Channels

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

6.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 is true if the message is sent successfully. If the send call times out or is interrupted, it returns false.

PollableChannel

Since message channels may or may not buffer messages (as discussed in the Chapter 5, Spring Integration Overview), two sub-interfaces define the buffering (pollable) and non-buffering (subscribable) channel behavior. The following listing shows the definition of the PollableChannel interface:

public interface PollableChannel extends MessageChannel {

    Message<?> receive();

    Message<?> receive(long timeout);

}

As with the send methods, when receiving a message, the return value is null in the case of a timeout or interrupt.

SubscribableChannel

The SubscribableChannel base interface is implemented by channels that send messages directly to their subscribed MessageHandler instances. Therefore, they do not provide receive methods for polling. Instead, they define methods for managing those subscribers. The following listing shows the definition of the SubscribableChannel interface:

public interface SubscribableChannel extends MessageChannel {

    boolean subscribe(MessageHandler handler);

    boolean unsubscribe(MessageHandler handler);

}

6.1.2 Message Channel Implementations

Spring Integration provides several different message channel implementations. The following sections briefly describe each one.

PublishSubscribeChannel

The PublishSubscribeChannel implementation broadcasts any Message sent to it to all of its subscribed handlers. This is most often used for sending event messages, whose primary role is notification (as opposed to document messages, which are generally intended to be processed by a single handler). Note that the PublishSubscribeChannel is intended for sending only. Since it broadcasts to its subscribers directly when its send(Message) method is invoked, consumers cannot poll for messages (it does not implement PollableChannel and therefore has no receive() method). Instead, any subscriber must itself be a MessageHandler, and the subscriber’s handleMessage(Message) method is invoked in turn.

Prior to version 3.0, invoking the send method on a PublishSubscribeChannel that had no subscribers returned false. When used in conjunction with a MessagingTemplate, a MessageDeliveryException was thrown. Starting with version 3.0, the behavior has changed such that a send is always considered successful if at least the minimum subscribers are present (and successfully handle the message). This behavior can be modified by setting the minSubscribers property, which defaults to 0.

[Note]Note

If you use a TaskExecutor, only the presence of the correct number of subscribers is used for this determination, because the actual handling of the message is performed asynchronously.

QueueChannel

The QueueChannel implementation wraps a queue. Unlike the PublishSubscribeChannel, the QueueChannel has point-to-point semantics. In other words, even if the channel has multiple consumers, only one of them should receive any Message sent to that channel. It provides a default no-argument constructor (providing an essentially unbounded capacity of Integer.MAX_VALUE) as well as a constructor that accepts the queue capacity, as the following listing shows:

public QueueChannel(int capacity)

A channel that has not reached its capacity limit storeS messages in its internal queue, and the send() method returns immediately, even if no receiver is ready to handle the message. If the queue has reached capacity, the sender blocks until room is available. Alternatively, if you use the send call that accepts a timeout, the queue blocks until either room is available or the timeout period elapses, whichever occurs first. Similarly, a receive call returns 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() block indefinitely.

PriorityChannel

Whereas the QueueChannel enforces first-in-first-out (FIFO) ordering, the PriorityChannel is an alternative implementation that allows for messages to be ordered within the channel based upon a priority. By default, the priority is determined by the priority header within each message. However, for custom priority determination logic, a comparator of type Comparator<Message<?>> can be provided to the PriorityChannel constructor.

RendezvousChannel

The RendezvousChannel enables a "direct-handoff" scenario, wherein a sender blocks until another party invokes the channel’s receive() method. The other party blocks until the sender sends the message. 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 operate in different threads, but asynchronously dropping the message in a queue is not appropriate. In other words, with a RendezvousChannel, the sender knows that some receiver has accepted the message, whereas with a QueueChannel, the message would have been stored to the internal queue and potentially never received.

[Tip]Tip

Keep in mind that all of these queue-based channels are storing messages in-memory only by default. When persistence is required, you can either provide a message-store attribute within the queue element to reference a persistent MessageStore implementation or you can replace the local channel with one that is backed by a persistent broker, such as a JMS-backed channel or channel adapter. The latter option lets you take advantage of any JMS provider’s implementation for message persistence, as discussed in Chapter 23, JMS Support. However, when buffering in a queue is not necessary, the simplest approach is to rely upon the DirectChannel, discussed in the next section.

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.

DirectChannel

The DirectChannel has point-to-point semantics but otherwise is more similar to the PublishSubscribeChannel than any of the queue-based channel implementations described earlier. 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 sends 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 subscribes to a DirectChannel, then sending a Message to that channel triggers 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, the outcome of the handler’s invocation (for example, updating a database record) plays a role in determining the ultimate result of that transaction (commit or rollback).

[Note]Note

Since the DirectChannel is the simplest option and does not add any additional overhead that would be required for scheduling and managing the threads of a poller, it is the default channel type within Spring Integration. The general idea is to define the channels for an application, consider which of those need to provide buffering or to throttle input, and 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. Later, we show how each of these channels 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 by 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 when multiple message handlers subscribe to the same channel. As a convenience, the load-balancer attribute exposes an enumeration of values pointing to pre-existing implementations of LoadBalancingStrategy. round-robin (load-balances across the handlers in rotation) and none (for the cases where one wants to explicitly 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 by using the load-balancer-ref attribute, which should point to a bean that implements LoadBalancingStrategy, as the following example shows:

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

<bean id="lb" class="foo.bar.SampleLoadBalancingStrategy"/>

Note that the load-balancer and load-balancer-ref attributes are mutually exclusive.

The load-balancing also works in conjunction with a boolean failover property. If the "failover" value is true (the default), the dispatcher falls 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 subscribed.

If a certain situation requires that the dispatcher always try to invoke the first handler and then fall back 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 always begins 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 determines the order.

[Note]Note

Keep in mind that load-balancing and failover apply only 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 defined in the input-channel attribute.

ExecutorChannel

The ExecutorChannel is a point-to-point channel that supports the same dispatcher configuration as DirectChannel (load-balancing strategy and the failover boolean property). The key difference between these two dispatching channel types is that the ExecutorChannel delegates to an instance of TaskExecutor to perform the dispatch. This means that the send method typically does not block, but it also means that the handler invocation may not occur in the sender’s thread. It therefore does not support transactions that span the sender and receiving handler.

[Caution]Caution

The sender can sometimes block. For example, when using a TaskExecutor with a rejection policy that throttles the client (such as the ThreadPoolExecutor.CallerRunsPolicy), the sender’s thread can execute the method any time 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, you should not rely upon it for transactions.

Scoped Channel

Spring Integration 1.0 provided a ThreadLocalChannel implementation, but that has been removed as of 2.0. Now the more general way to handle the same requirement is to add a scope attribute to a channel. The value of the attribute can be the 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. The following example shows a thread-local scope being applied to a channel, including the registration of the scope itself:

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

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

The channel defined in the previous example also delegates to a queue internally, but the channel is bound to the current thread, so the contents of the queue are similarly bound. That way, the thread that sends to the channel can later 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 DirectChannel instances 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 the terminal channel.

Now, since any channel can be scoped, you can define your own scopes in addition to thread-Local.

6.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 instances are sent to and received from MessageChannel instances, those channels provide an opportunity for intercepting the send and receive operations. The ChannelInterceptor strategy interface, shown in the following listing, 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 making the following call:

channel.addInterceptor(someChannelInterceptor);

The methods that return a Message instance can be used for transforming the Message or can return null to prevent further processing (of course, any of the methods can throw a RuntimeException). Also, the preReceive method can return false to prevent the receive operation from proceeding.

[Note]Note

Keep in mind that receive() calls are only relevant for PollableChannels. In fact, the SubscribableChannel interface does not even define a receive() method. The reason for this is that when a Message is sent to a SubscribableChannel, it is sent directly to zero or more subscribers, depending on the type of channel (for example, a PublishSubscribeChannel sends to all of its subscribers). Therefore, the preReceive(...), postReceive(...), and afterReceiveCompletion(...) interceptor methods are invoked only 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, the interface provides no-op methods (methods returning void method have no code, the Message-returning methods return the Message as-is, and the boolean method returns true).

[Tip]Tip

The order of invocation for the interceptor methods depends on the type of channel. As described earlier, 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 the separate sender and receiver threads. For example, if a receiver is already blocked while waiting for a message, the order could be as follows: preSend, preReceive, postReceive, postSend. However, if a receiver polls after the sender has placed a message on the channel and has already returned, the order would be as follows: 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). The type of queue also plays a role (for example, rendezvous versus priority). In short, you cannot rely on the order beyond the fact that preSend precedes postSend and preReceive precedes 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()' and 'receive() calls, regardless of any exception that is raised, which allow for resource cleanup. Note that the channel invokes these methods on the ChannelInterceptor list in the reverse order of the initial preSend() and preReceive() calls.

Starting with version 5.1, global channel interceptors now apply to dynamically registered channels - such as through beans that are initialized by using beanFactory.initializeBean() or IntegrationFlowContext when using the Java DSL. Previously, interceptors were not applied when beans were created after the application context was refreshed.

Also, starting with version 5.1, ChannelInterceptor.postReceive() is no longer called when no message is received; it is no longer necessary to check for a null Message<?>. Previously, the method was called. If you have an interceptor that relies on the previous behavior, implement afterReceiveCompleted() instead, since that method is invoked, regardless of whether a message is received or not.

6.1.4 MessagingTemplate

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, it is sometimes 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 and reply scenarios. For example, it is possible to send a request and wait for a reply, as follows:

MessagingTemplate template = new MessagingTemplate();

Message reply = template.sendAndReceive(someChannel, new GenericMessage("test"));

In the preceding 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. The following listing shows the signatures for such methods:

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

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

public Message<?> receive(final PollableChannel<?> channel) { ...
}
[Note]Note

A less invasive approach that lets you invoke simple interfaces with payload or header values instead of Message instances is described in Section 10.4.1, “Enter the GatewayProxyFactoryBean.

6.1.5 Configuring Message Channels

To create a message channel instance, you can use the <channel/> element, as follows:

<int:channel id="exampleChannel"/>

The default channel type is point-to-point. To create a publish-subscribe channel, use the <publish-subscribe-channel/> element, as follows:

<int:publish-subscribe-channel id="exampleChannel"/>

When you use the <channel/> element without any sub-elements, it creates 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 6.1.2, “Message Channel Implementations”). The following sections shows examples of each channel type.

DirectChannel Configuration

As mentioned earlier, DirectChannel is the default type. The following listing shows who to define one in XML:

<int:channel id="directChannel"/>

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

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

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

Datatype Channel Configuration

Sometimes, a consumer can process only a particular type of payload, forcing you to ensure the payload type of the input messages. The first thing that comes to mind may be to use a message filter. However, all that message filter can 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 and conversion to the required data type. This would work, but a simpler way to accomplish 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 accepts only messages that contain a certain payload type, provide the data type’s fully-qualified class name in the channel element’s datatype attribute, as the following example shows:

<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 in the preceding example would accept messages whose payload is java.lang.Integer or java.lang.Double. Multiple types can be provided as a comma-delimited list, as the following example shows:

<int:channel id="stringOrNumberChannel" datatype="java.lang.String,java.lang.Number"/>

So the numberChannel in the preceding example accepts only 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. However, if you have defined an integrationConversionService bean, it is used in an attempt to convert the message’s payload to the acceptable type.

You can even register custom converters. For example, suppose you send a message with a String payload to the numberChannel we configured above. You might handle the message as follows:

MessageChannel inChannel = context.getBean("numberChannel", MessageChannel.class);
inChannel.send(new GenericMessage<String>("5"));

Typically this would be a perfectly legal operation. However, since we use Datatype Channel, the result of such operation would generate an exception similar to the following:

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

The exception happens because we require the payload type to be a Number, but we sent a String. So we need something to convert a String to a Number. For that, we can implement a converter similar to the following example:

public static class StringToIntegerConverter implements Converter<String, Integer> {
    public Integer convert(String source) {
        return Integer.parseInt(source);
    }
}

Then we can register it as a converter with the Integration Conversion Service, as the following example shows:

<int:converter ref="strToInt"/>

<bean id="strToInt" class="org.springframework.integration.util.Demo.StringToIntegerConverter"/>

When the converter element is parsed, it creates the integrationConversionService bean if one is not already defined. With that converter in place, the send operation would now be successful, because the datatype channel uses that converter to convert the String payload to an Integer.

For more information regarding payload type conversion, see Section 10.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. It provides the converter with access to the message headers (in case the conversion might need information from the headers, such as content-type). The method can return only 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, you can declare a <bean/> of type MessageConverter with an ID of datatypeChannelMessageConverter, and that converter is 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 as follows:

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

If you do not provide a value for the capacity attribute on this <queue/> sub-element, the resulting queue is unbounded. To avoid issues such as running out of memory, we highly recommend that you 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 12.4, “Message Store”.

[Important]Important

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

When a QueueChannel receives a Message, it adds the message to the message store. 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, which can lead to the lost message scenario mentioned earlier. 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 the following example shows:

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

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

The Spring Integration JDBC module also provides a schema Data Definition Language (DDL) for a number of popular databases. These schemas are located in the org.springframework.integration.jdbc.store.channel package of that module (spring-integration-jdbc).

[Important]Important

One important feature is that, with any transactional persistent store (such as JdbcChannelMessageStore), as long as the poller has a transaction configured, a message removed from the store can be permanently removed only if the transaction completes successfully. Otherwise the transaction rolls back, and the Message is not lost.

Many other implementations of the message store are available as the growing number of Spring projects related to "NoSQL" data stores come to provide underlying support for these stores. You can also provide your own implementation of the MessageGroupStore interface if you cannot find one that meets your particular needs.

Since version 4.0, we recommend that QueueChannel instances be configured to use a ChannelMessageStore, if possible. These are generally optimized for this use, as compared to a general message store. If the ChannelMessageStore is a ChannelPriorityMessageStore, the messages are received in FIFO within priority order. The notion of priority is determined by the message store implementation. For example, the following example shows the Java configuration for the Section 25.2.1, “MongoDB Channel Message Store”:

@Bean
public BasicMessageGroupStore mongoDbChannelMessageStore(MongoDbFactory mongoDbFactory) {
    MongoDbChannelMessageStore store = new MongoDbChannelMessageStore(mongoDbFactory);
    store.setPriorityEnabled(true);
    return store;
}

@Bean
public PollableChannel priorityQueue(BasicMessageGroupStore mongoDbChannelMessageStore) {
    return new PriorityChannel(new MessageGroupQueue(mongoDbChannelMessageStore, "priorityQueue"));
}
[Note]Note

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

The same implementation with Java DSL might look like the following example:

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

Another option to customize the QueueChannel environment is provided by the ref attribute of the <int:queue> sub-element or its particular constructor. This attribute supplies the reference to any java.util.Queue implementation. For example, a Hazelcast distributed IQueue can be configured as follows:

@Bean
public HazelcastInstance hazelcastInstance() {
    return Hazelcast.newHazelcastInstance(new Config()
                                           .setProperty("hazelcast.logging.type", "log4j"));
}

@Bean
public PollableChannel distributedQueue() {
    return new QueueChannel(hazelcastInstance()
                              .getQueue("springIntegrationQueue"));
}

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 publishes in the sender’s thread), as follows:

<int:publish-subscribe-channel id="pubsubChannel" task-executor="someExecutor"/>

If you provide a resequencer or aggregator downstream from a PublishSubscribeChannel, you can set the apply-sequence property on the channel to true. Doing so indicates that the channel should set the sequence-size and sequence-number message headers as well as the correlation ID prior to passing along the messages. For example, if there are five subscribers, the sequence-size would be set to 5, and the messages would have sequence-number header values ranging from 1 to 5.

Along with the Executor, you can also configure an ErrorHandler. By default, the PublishSubscribeChannel uses a MessagePublishingErrorHandler implementation to send an error to the MessageChannel from the errorChannel header or into the global errorChannel instance. If an Executor is not configured, the ErrorHandler is ignored and exceptions are thrown directly to the caller’s thread.

If you provide a Resequencer or Aggregator downstream from a PublishSubscribeChannel, you can set the apply-sequence property on the channel to true. Doing so indicates that the channel should set the sequence-size and sequence-number message headers as well as the correlation ID prior to passing along the messages. For example, if there are five subscribers, the sequence-size would be set to 5, and the messages would have sequence-number header values ranging from 1 to 5.

The following example shows how to set the apply-sequence header to true:

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

The apply-sequence value is false by default so that a publish-subscribe channel can send the exact same message instances to multiple outbound channels. Since Spring Integration enforces immutability of the payload and header references, when the flag is set to true, the channel creates new Message instances with the same payload reference but different header values.

ExecutorChannel

To create an ExecutorChannel, add the <dispatcher> sub-element with a task-executor attribute. The attribute’s value can reference any TaskExecutor within the context. For example, doing so enables configuration of a thread pool for dispatching messages to subscribed handlers. As mentioned earlier, doing so breaks the single-threaded execution context between sender and receiver so that any active transaction context is not shared by the invocation of the handler (that is, the handler may throw an Exception, but the send invocation has already returned successfully). The following example shows how to use the dispatcher element and specify an executor in the task-executor attribute:

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

The load-balancer and failover options are also both available on the <dispatcher/> sub-element, as described earlier in the section called “DirectChannel Configuration”. The same defaults apply. Consequently, the channel has a round-robin load-balancing strategy with failover enabled unless explicit configuration is provided for one or both of those attributes, as the following example shows:

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

PriorityChannel Configuration

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

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

By default, the channel consults the priority header of the message. However, you can instead provide a custom Comparator reference. 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"
                    capacity="10"/>
</int:channel>

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. Implementations of the PriorityCapableChannelMessageStore are currently provided for Redis, JDBC, and MongoDB. See the section called “QueueChannel Configuration” and Section 12.4, “Message Store” for more information. You can find sample configuration in Section 21.4.3, “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 earlier, and its queue does not accept any capacity value, since it is a zero-capacity direct handoff queue. The following example shows how to declare a RendezvousChannel:

<int:channel id="rendezvousChannel"/>
    <int:rendezvous-queue/>
</int:channel>

Scoped Channel Configuration

Any channel can be configured with a scope attribute, as the following example shows:

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

Channel Interceptor Configuration

Message channels may also have interceptors, as described in Section 6.1.3, “Channel Interceptors”. The <interceptors/> sub-element can be added to a <channel/> (or the more specific element types). You can provide the ref attribute to reference any Spring-managed object that implements the ChannelInterceptor interface, as the following example shows:

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

In general, we recommend defining 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. Consider the following pair of examples:

<int:channel-interceptor pattern="input*, thing2*, thing1, !cat*" order="3">
    <bean class="thing1.thing2SampleInterceptor"/>
</int:channel-interceptor>
<int:channel-interceptor ref="myInterceptor" pattern="input*, thing2*, thing1, !cat*" order="3"/>

<bean id="myInterceptor" class="thing1.thing2SampleInterceptor"/>

Each <channel-interceptor/> element lets you define a global interceptor, which is applied on all channels that match any patterns defined by the pattern attribute. In the preceding case, the global interceptor is applied on the thing1 channel and all other channels that begin with thing2 or input but not to channels starting with thing3 (since version 5.0).

[Warning]Warning

The addition of this syntax to the pattern causes one possible (though perhaps unlikely) problem. If you have a bean named !thing1 and you included a pattern of !thing1 in your channel interceptor’s pattern patterns, it no longer matches. The pattern now matches all beans not named thing1. In this case, you can escape the ! in the pattern with \. The pattern \!thing1 matches a bean named !thing1.

The order attribute lets you manage where this interceptor is injected when there are multiple interceptors on a given channel. For example, channel inputChannel could have individual interceptors configured locally (see below), as the following example shows:

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

A reasonable question is "how is a global interceptor injected in relation to other interceptors configured locally or through other global interceptor definitions?" The current implementation provides a simple mechanism for defining the order of interceptor execution. A positive number in the order attribute ensures interceptor injection after any existing interceptors, while a negative number ensures that the interceptor is injected before existing interceptors. This means that, in the preceding example, the global interceptor is 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 both interceptors' order attributes. To inject a global interceptor before the existing interceptors, use a negative value for the order attribute.

[Note]Note

Note that both the order and pattern attributes are optional. The default value for order will be 0 and for pattern, the default is * (to match all channels).

Starting with version 4.3.15, you can configure the spring.integration.postProcessDynamicBeans = true property to apply any global interceptors to dynamically created MessageChannel beans. See Section E.4, “Global Properties” for more information.

Wire Tap

As mentioned earlier, Spring Integration provides a simple wire tap interceptor. You can configure a wire tap on any channel within an <interceptors/> element. Doing so 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:interceptors>
        <int:wire-tap channel="logger"/>
    </int:interceptors>
</int:channel>

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

The logging-channel-adapter also accepts an expression attribute so that you can evaluate a SpEL expression against the payload and headers variables. Alternatively, to log the full message toString() result, provide a value of true for the log-full-message attribute. By default, it is false so that only the payload is logged. Setting it to true enables logging of all headers in addition to the payload. The expression option provides the most flexibility (for example, expression="payload.user.name").

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. By default, wire tap as a component is not invoked asynchronously. Instead, Spring Integration focuses on a single unified approach to configuring asynchronous behavior: the message channel. What makes certain parts of the message flow synchronous or asynchronous 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 tasks:

  • Intercept a message flow by tapping into a channel (for example, channelA)
  • Grab each message
  • Send the message to another channel (for example, channelB)

It is essentially a variation of the bridge pattern, 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 depends on the type of message channel that channelB is. We have the following options: direct channel, pollable channel, and executor channel. The last two break the thread boundary, making communication over such channels asynchronous, 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 synchronous or asynchronous. It is consistent with other components within the framework (such as message publisher) and adds a level of consistency and simplicity by sparing you from worrying in advance (other than writing thread-safe code) about whether a particular piece of code should be implemented as synchronous or asynchronous. The actual wiring of two pieces of code (say, component A and component B) over a message channel is what makes their collaboration synchronous or asynchronous. You may even want to change from synchronous to asynchronous in the future, and message channel lets 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 asynchronous by default, you should keep in mind that 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. However we doe not enforce asynchronous behavior by default. There are a number of use cases that would break if we did, including that you might not want to break a transactional boundary. Perhaps you use the wire tap pattern for auditing purposes, and you do want the audit messages to be sent within the original transaction. As an example, you might connect the wire tap to a JMS outbound channel adapter. That way, you get the best of both worlds: 1) the sending of a JMS Message can occur within the transaction while 2) it is still a "fire-and-forget" action, thereby preventing any noticeable delay in the main message flow.

[Important]Important

Starting with version 4.0, it is important to avoid circular references when an interceptor (such as the WireTap class) references a channel. 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 asks the interceptor if it is OK to intercept each channel that is a candidate, based on the supplied pattern. You can also add runtime protection in the interceptor methods to ensure 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.

[Important]Important

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, as the following example shows:

@Bean
public PollableChannel myChannel() {
    return MessageChannels.queue()
            .wireTap("loggingFlow.input")
            .get();
}

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

Conditional Wire Taps

Wire taps can be made conditional by 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 is 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”. To do so, 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 they do for the channel-interceptor. The following examlpe shows how to configure a global wire tap:

<int:wire-tap pattern="input*, thing2*, thing1" order="3" channel="wiretapChannel"/>
[Tip]Tip

A global wire tap provides a convenient way to configure a single-channel wire tap externally without modifying the existing channel configuration. To do so, set the pattern attribute to the target channel name. For example, you can use this technique to configure a test case to verify messages on a channel.

6.1.6 Special Channels

If namespace support is enabled, two special channels are defined within the application context by default: errorChannel and nullChannel. The nullChannel acts like /dev/null, logging any message sent to it at the DEBUG level and returning immediately. Any time you face channel resolution errors for a reply that you do not 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 E.3, “Error Handling”.

See also Section 11.2, “Message Channels” in the Java DSL chapter for more information about message channel and interceptors.

6.2 Poller

This section describes how polling works in Spring Integration.

6.2.1 Polling Consumer

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

The actual implementation depends on the type of channel to which these endpoints connect. A channel adapter connected to a channel that implements the org.springframework.messaging.SubscribableChannel interface produces an instance of EventDrivenConsumer. On the other hand, a channel adapter connected to a channel that implements the org.springframework.messaging.PollableChannel interface (such as a QueueChannel) produces an instance of PollingConsumer.

Polling consumers let Spring Integration components actively poll for Messages rather than 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.

6.2.2 Pollable Message Source

Spring Integration offers a second variation of the polling consumer pattern. When inbound channel adapters are 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 18.4, “FTP Inbound Channel Adapter” is configured with a poller to periodically retrieve messages. So, when components are configured with pollers, the resulting instances are of one of the following types:

This means that pollers are used in both inbound and outbound messaging scenarios. Here are some use cases in which pollers are used:

  • Polling certain external systems, such as FTP Servers, Databases, and Web Services
  • Polling internal (pollable) message channels
  • Polling internal services (such as repeatedly executing methods on a Java class)
[Note]Note

AOP advice classes can be applied to pollers, in an advice-chain, such as 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 being processed. To use this advice, you have to provide it with an implementation of a PollSkipStrategy. Starting with version 4.2.5, a SimplePollSkipStrategy is provided. To use it, you can 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 6.2.4, “Conditional Pollers for Message Sources”.

This chapter is meant to only give a high-level overview of polling consumers and how they fit into the concept of message channels (see Section 6.1, “Message Channels”) and channel adapters (see Section 6.3, “Channel Adapter”). For more information regarding messaging endpoints in general and polling consumers in particular, see Section 10.1, “Message Endpoints”.

6.2.3 Deferred Acknowledgment Pollable Message Source

Starting with version 5.0.1, certain modules provide MessageSource implementations that support deferring acknowledgment until the downstream flow completes (or hands off the message to another thread). This is currently limited to the AmqpMessageSource and the KafkaMessageSource provided by the spring-kafka-integration extension project, version 3.0.1 or higher.

With these message sources, the IntegrationMessageHeaderAccessor.ACKNOWLEDGMENT_CALLBACK header (see Section 7.2.1, “MessageHeaderAccessor API”) is added to the message. The value of the header is an instance of AcknowledgmentCallback, as the following example shows:

@FunctionalInterface
public interface AcknowledgmentCallback {

    void acknlowledge(Status status);

    boolean isAcknowledged();

    void noAutoAck();

    default boolean isAutoAck();

    enum Status {

        /**
         * Mark the message as accepted.
         */
        ACCEPT,

        /**
         * Mark the message as rejected.
         */
        REJECT,

        /**
         * Reject the message and requeue so that it will be redelivered.
         */
        REQUEUE

    }

}

Not all message sources (for example, Kafka) support the REJECT status. It is treated the same as ACCEPT.

Applications can acknowledge a message at any time, as the following example shows:

Message<?> received = source.receive();

...

StaticMessageHeaderAccessor.getAcknowledgmentCallback(received)
        .acknowledge(Status.ACCEPT);

If the MessageSource is wired into a SourcePollingChannelAdapter, when the poller thread returns to the adapter after the downstream flow completes, the adapter checks whether the acknowledgment has already been acknowledged and, if not, sets its status to ACCEPT it (or REJECT if the flow throws an exception). The status values are defined in the AcknowledgmentCallback.Status enumeration.

Spring Integration provides MessageSourcePollingTemplate to perform ad-hoc polling of a MessageSource. This, too, takes care of setting ACCEPT or REJECT on the AcknowledgmentCallback when the MessageHandler callback returns (or throws an exception). The following example shows how to poll with the MessageSourcePollingTemplate:

MessageSourcePollingTemplate template =
    new MessageSourcePollingTemplate(this.source);
template.poll(h -> {
    ...
});

In both cases (SourcePollingChannelAdapter and MessageSourcePollingTemplate), you can disable auto ack/nack by calling noAutoAck() on the callback. You might do this if you hand off the message to another thread and wish to acknowledge later. Not all implementations support this (for example, Apache Kafka does not, because the offset commit has to be performed on the same thread).

6.2.4 Conditional Pollers for Message Sources

This section covers how to use conditional pollers.

Background

Advice objects, in an advice-chain on a poller, advise the whole polling task (both message retrieval and processing). These "around advice" methods do not have access to any context for the poll — only 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 earlier. 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? For those instances, Spring Integration offers "Smart" Polling.

"Smart" Polling

Version 4.2 introduced the AbstractMessageSourceAdvice. Any Advice objects in the advice-chain that subclass this class are applied only to the receive operation. Such classes implement the following methods:

  • beforeReceive(MessageSource<?> source) This method is called before the MessageSource.receive() method. It lets you examine and reconfigure the source. Returning false cancels this poll (similar to the PollSkipAdvice mentioned earlier).
  • 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]Thread safety

If an advice mutates the MessageSource, you should not configure the poller with a TaskExecutor. If an advice mutates the source, such mutations are not thread safe and could cause unexpected results, especially with high frequency pollers. If you need to process poll results concurrently, consider using a downstream ExecutorChannel instead of adding an executor to the poller.

[Important]Advice Chain Ordering

You should 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, for example, Advice objects a, b, c, d, where b and d are AbstractMessageSourceAdvice, the objects are applied in the following order: a, c, b, d. Also, if a MessageSource is already a Proxy, the AbstractMessageSourceAdvice is invoked after any existing Advice objects. If you wish to change the order, you must wire up the proxy yourself.

SimpleActiveIdleMessageSourceAdvice

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

SimpleActiveIdleMessageSourceAdvice modifies the trigger based on the receive() result. This works only if the advice is called on the poller thread. It does 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.

CompoundTriggerAdvice

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 instances are immutable, so they 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 instance’s nextExecutionTime method is invoked, it delegates to the secondary trigger, if present. Otherwise, it delegates to the primary trigger.

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

The following example shows the configuration for the hourly cron expression with a fallback to every minute:

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

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

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

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

CompoundTriggerAdvice modifies the trigger based on the receive() result. This works only if the advice is called on the poller thread. It does 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.

6.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 to support various transports, such as JMS, file, HTTP, web services, mail, and more. Upcoming chapters of this reference guide discuss each adapter. 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 a destination.

6.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 the method’s output to a Message. When the adapter’s subscription is activated, a poller tries to receive messages from the source. The poller is scheduled with the TaskScheduler according to the provided configuration. To configure the polling interval or cron expression for an individual channel adapter, you can provide a poller element with one of the scheduling attributes, such as fixed-rate or cron. The following example defines two inbound-channel-adapter instances:

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

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

See also Section 6.3.3, “Channel Adapter Expressions and Scripts”.

[Note]Note

If no poller is provided, then a single default poller must be registered within the context. See Section 10.1.4, “Endpoint Namespace Support” for more detail.

[Important]Important: Poller Configuration

Some inbound-channel-adapter types are backed by a SourcePollingChannelAdapter, which means they contain a poller configuration that polls the MessageSource (to invoke a custom method that produces the value that becomes a Message payload) based on the configuration specified in the Poller. The following example shows the configuration of two pollers:

<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 is invoked once per poll, and, during each task (poll), the method (which results in the production of the message) is invoked once, based on the max-messages-per-poll attribute value. In the second configuration, the polling task is invoked 10 times per poll or until it returns null, thus possibly producing ten messages per poll while each poll happens at one-second intervals. However, what happens if the configuration looks like the following example:

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

Note that there is no max-messages-per-poll specified. As we cover later, the identical poller configuration in the PollingConsumer (for example, service-activator, filter, router, and others) would have a default value of -1 for max-messages-per-poll, which means "execute the polling task non-stop unless the polling method returns null (perhaps because there are no more messages in the `QueueChannel)`" and then sleep for one second.

However, in the SourcePollingChannelAdapter, it is a bit different. The default value for max-messages-per-poll is 1, unless you explicitly set it to a negative value (such as -1). This makes sure that the poller can react to lifecycle events (such as start and stop) and prevents it from potentially spinning in an infinite loop if the implementation of the custom method of the MessageSource has a potential to never return null and happens to be non-interruptible.

However, if you are sure that your method can return null and you need to poll for as many sources as available per each poll, you should explicitly set max-messages-per-poll to a negative value, as the following example shows:

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

6.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. The following example shows how to define an outbound channel adapter:

<int:outbound-channel-adapter channel="channel1" ref="target" method="handle"/>

<beans:bean id="target" class="org.MyPojo"/>

If the channel being adapted is a PollableChannel, you must provide a poller sub-element, as the following example shows:

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

<beans:bean id="target" class="org.MyPojo"/>

You should use a ref attribute if the POJO consumer implementation can be reused in other <outbound-channel-adapter> definitions. However, if the consumer implementation is referenced by only a single definition of the <outbound-channel-adapter>, you can define it as an inner bean, as the following example shows:

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

Using both the ref attribute and an inner handler definition in the same <outbound-channel-adapter> configuration is not allowed, as it creates an ambiguous condition. Such a configuration results in an exception being thrown.

Any channel adapter can be created without a channel reference, in which case it implicitly creates an instance of DirectChannel. The created channel’s name matches the id attribute of the <inbound-channel-adapter> or <outbound-channel-adapter> element. Therefore, if channel is not provided, id is required.

6.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 in 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> generates a message any time 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 a <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 by using the location attribute, you can also set refresh-check-delay, which allows the resource to be periodically refreshed. If you want the script to be checked on each poll, you would need to coordinate this setting with the poller’s trigger, as the following example shows:

<int:inbound-channel-adapter ref="source1" method="method1" channel="channel1">
    <int:poller max-messages-per-poll="1" fixed-delay="5000"/>
    <script:script lang="ruby" location="Foo.rb" refresh-check-delay="5000"/>
</int:inbound-channel-adapter>

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

[Important]Important

The <int:inbound-channel-adapter/> is endpoint starts a message flow by periodically triggering to poll some underlying MessageSource. Since, at the time of polling, there is no message object, expressions and scripts do not have access to a root Message, so there are no payload or headers properties that are available in most other messaging SpEL expressions. The script can generate and return a complete Message object with headers and payload or only a payload, which is added to a message with basic headers.

6.4 Messaging Bridge

A messaging bridge is a relatively trivial endpoint that 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, you can use a messaging bridge to throttle inbound messages. The poller’s trigger determines the rate at which messages arrive on the second channel, and the poller’s maxMessagesPerPoll property enforces 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 is 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. In that case, the channels can 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.

6.4.1 Configuring a Bridge with XML

You can use the <bridge> element is used to create a messaging bridge between two message channels or channel adapters. To do so, provide the input-channel and output-channel attributes, as the following example shows:

<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. 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"/>
 </int:bridge>

You can use a similar mechanism to connecting channel adapters. The following example shows a simple "echo" 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"/>

Similar configurations work for other (potentially more useful) Channel Adapter bridges, such as file-to-JMS or mail-to-file. Upcoming chapters cover the various channel adapters.

[Note]Note

If no output-channel is defined on a bridge, the reply channel provided by the inbound message is used, if available. If neither an output nor a reply channel is available, an exception is thrown.

6.4.2 Configuring a Bridge with Java Configuration

The following example shows how to configure a bridge in Java by using the @BridgeFrom annotation:

@Bean
public PollableChannel polled() {
    return new QueueChannel();
}

@Bean
@BridgeFrom(value = "polled", poller = @Poller(fixedDelay = "5000", maxMessagesPerPoll = "10"))
public SubscribableChannel direct() {
    return new DirectChannel();
}

The following example shows how to configure a bridge in Java by using the @BridgeTo annotation:

@Bean
@BridgeTo(value = "direct", poller = @Poller(fixedDelay = "5000", maxMessagesPerPoll = "10"))
public PollableChannel polled() {
    return new QueueChannel();
}

@Bean
public SubscribableChannel direct() {
    return new DirectChannel();
}

Alternately, you can use a BridgeHandler, as the following example shows:

@Bean
@ServiceActivator(inputChannel = "polled",
        poller = @Poller(fixedRate = "5000", maxMessagesPerPoll = "10"))
public BridgeHandler bridge() {
    BridgeHandler bridge = new BridgeHandler();
    bridge.setOutputChannelName("direct");
    return bridge;
}

6.4.3 Configuring a Bridge with the Java DSL

You can use the Java Domain Specific Language (DSL) to configure a bridge, as the following example shows:

@Bean
public IntegrationFlow bridgeFlow() {
    return IntegrationFlows.from("polled")
            .bridge(e -> e.poller(Pollers.fixedDelay(5000).maxMessagesPerPoll(10)))
            .channel("direct")
            .get();
}

7. Message

The Spring Integration Message is a generic container for data. Any object can be provided as the payload, and each Message instance includes headers containing user-extensible properties as key-value pairs.

7.1 The Message Interface

The following listing shows the definition of the Message interface:

public interface Message<T> {

    T getPayload();

    MessageHeaders getHeaders();

}

The Message interface is a core 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 or extended, the messaging system is not affected. 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.

7.2 Message Headers

Just as Spring Integration lets any Object 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, as the following class definition shows:

public final class MessageHeaders implements Map<String, Object>, Serializable {
  ...
}
[Note]Note

Even though the MessageHeaders class implements Map, it is effectively a read-only implementation. Any attempt to put a value in the Map results 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 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. The following example shows 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 table describes the pre-defined message headers:

Table 7.1. Pre-defined Message Headers

Header NameHeader TypeUsage
 MessageHeaders.ID
 java.util.UUID

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

 MessageHeaders.
TIMESTAMP
 java.lang.Long

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

 MessageHeaders.
REPLY_CHANNEL
 java.lang.Object
(String or
MessageChannel)

A channel to which a reply (if any) is sent when no explicit output channel is configured and there is no ROUTING_SLIP or the ROUTING_SLIP is exhausted. If the value is a String, it must represent a bean name or have been generated by a ChannelRegistry.

 MessageHeaders.
ERROR_CHANNEL
 java.lang.Object
(String or
MessageChannel)

A channel to which errors are 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 also provide or expect certain headers, and you can configure additional user-defined headers. Constants for these headers can be found in those modules where such headers exist — for example. AmqpHeaders, JmsHeaders, and so on.

7.2.1 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 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. The following table describes the pre-defined message headers:

Table 7.2. Pre-defined Message Headers

Header NameHeader TypeUsage
 IntegrationMessageHeaderAccessor.
CORRELATION_ID
 java.lang.Object

Used to correlate two or more messages.

 IntegrationMessageHeaderAccessor.
SEQUENCE_NUMBER
 java.lang.Integer

Usually a sequence number with a group of messages with a SEQUENCE_SIZE but can also be used in a <resequencer/> to resequence an unbounded group of messages.

 IntegrationMessageHeaderAccessor.
SEQUENCE_SIZE
 java.lang.Integer

The number of messages within a group of correlated messages.

 IntegrationMessageHeaderAccessor.
EXPIRATION_DATE
 java.lang.Long

Indicates when a message is expired. Not used by the framework directly but can be set with a header enricher and used in a <filter/> that is configured with an UnexpiredMessageSelector.

 IntegrationMessageHeaderAccessor.
PRIORITY
 java.lang.Integer

Message priority — for example, within a PriorityChannel.

 IntegrationMessageHeaderAccessor.
DUPLICATE_MESSAGE
 java.lang.Boolean

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

 IntegrationMessageHeaderAccessor.
CLOSEABLE_RESOURCE
 java.io.Closeable

This header is present if the message is associated with a Closeable that should be closed when message processing is complete. An example is the Session associated with a streamed file transfer using FTP, SFTP, and so on.

 IntegrationMessageHeaderAccessor.
DELIVERY_ATTEMPT
 java.lang.
AtomicInteger

If a message-driven channel adapter supports the configuration of a RetryTemplate, this header contains the current delivery attempt.

 IntegrationMessageHeaderAccessor.
ACKNOWLEDGMENT_CALLBACK
 o.s.i.support.
Acknowledgment
Callback

If a message source supports it, a call back to accept, reject, or requeue a message. See Section 6.2.3, “Deferred Acknowledgment Pollable Message Source”.


Convenient typed getters for some of these headers are provided on the IntegrationMessageHeaderAccessor class, as the following example shows:

IntegrationMessageHeaderAccessor accessor = new IntegrationMessageHeaderAccessor(message);
int sequenceNumber = accessor.getSequenceNumber();
Object correlationId = accessor.getCorrelationId();
...

The following table describes headers that also appear in the IntegrationMessageHeaderAccessor but are generally not used by user code (that is, they are generally used by internal parts of Spring Integration — their inclusion here is for completeness):

Table 7.3. Pre-defined Message Headers

Header NameHeader TypeUsage
 `IntegrationMessageHeaderAccessor.
SEQUENCE_DETAILS`
 `java.util.`
`List<List<Object>>`

A stack of correlation data used when nested correlation is needed (for example, splitter->...->splitter->...->aggregator->...->aggregator).

 `IntegrationMessageHeaderAccessor.
ROUTING_SLIP`
 `java.util.`
`Map<List<Object>, Integer>`

See the section called “Routing Slip”.


7.2.2 Message ID Generation

When a message transitions through an application, each time it is mutated (for example, 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 IS generation is more efficient than the previous java.util.UUID.randomUUID() implementation. It uses simple random numbers based on a secure random seed instead of creating a secure random number each time.

A different UUID generation strategy can be selected by declaring a bean that implements org.springframework.util.IdGenerator in the application context.

[Important]Important

Only one UUID generation strategy can be used in a classloader. This means that, if two or more application contexts run in the same classloader, they share the same strategy. If one of the contexts changes the strategy, it is 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 fails to initialize. If the strategy is the same, but parameterized, the strategy in the first context to be initialized is used.

In addition to the default strategy, two additional IdGenerators are provided. org.springframework.util.JdkIdGenerator uses the previous UUID.randomUUID() mechanism. You can use o.s.i.support.IdGenerators.SimpleIncrementingIdGenerator when a UUID is not really needed and a simple incrementing value is sufficient.

7.2.3 Read-only Headers

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

Since version 4.3.2, the MessageBuilder provides the readOnlyHeaders(String... readOnlyHeaders) API to customize a list of headers that should not be copied from an upstream Message. Only the MessageHeaders.ID and MessageHeaders.TIMESTAMP are read only by default. The global spring.integration.readOnly.headers property (see Section E.4, “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, such as contentType by the ObjectToJsonTransformer (see the section called “JSON Transformers”).

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

Starting with version 5.0, Messaging Gateway, Header Enricher, Content Enricher and Header Filter do not let you configure the MessageHeaders.ID and MessageHeaders.TIMESTAMP header names when DefaultMessageBuilderFactory is used, and they throw BeanInitializationException.

7.2.4 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, letting you 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. To configure the header(s) you do not want to be copied, call the setNotPropagatedHeaders() or addNotPropagatedHeaders() methods on the MessageProducingMessageHandler abstract class.

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.

Starting with version 5.0, the setNotPropagatedHeaders() implementation on the AbstractMessageProducingHandler applies simple patterns (xxx*, *xxx, *xxx*, or xxx*yyy) to allow filtering headers with a common suffix or prefix. See PatternMatchUtils Javadoc for more information. When one of the patterns is * (asterisk), no headers are propagated. All other patterns are ignored. In that case, the service activator behaves the same way as a transformer and any required headers must be supplied in the Message returned from the service method. The notPropagatedHeaders() option is available in the ConsumerEndpointSpec for the Java DSL It is also available for XML configuration of the <service-activator> component as a not-propagated-headers attribute.

[Important]Important

Header propagation suppression does not apply to those endpoints that do not modify the message, such as bridges and routers.

7.3 Message Implementations

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

new GenericMessage<T>(T payload);

new GenericMessage<T>(T payload, Map<String, Object> headers)

When a Message is created, a random unique ID is generated. The constructor that accepts a Map of headers copies the provided headers to the newly created Message.

There is also a convenient implementation of Message designed to communicate error conditions. This implementation takes a Throwable object as its payload, as the following example shows:

ErrorMessage message = new ErrorMessage(someThrowable);

Throwable t = message.getPayload();

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

7.4 The MessageBuilder Helper Class

You may notice that the Message interface defines retrieval methods for its payload and headers but provides 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 (for example, through a publish-subscribe Channel), if one of those consumers needs to send a reply with a different payload type, it must 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 you. In other words, the contract for Message instances 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 a MessageHeaders instance results 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 Message instances from either an existing Message or with a payload Object. When building from an existing Message, the headers and payload of that Message are copied to the new Message, as the following example shows:

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

Message<String> message2 = MessageBuilder.fromMessage(message1).build();

assertEquals("test", message2.getPayload());
assertEquals("bar", message2.getHeaders().get("foo"));

If you need to create a Message with a new payload but still want to copy the headers from an existing Message, you can use one of the copy methods, as the following example shows:

Message<String> message3 = MessageBuilder.withPayload("test3")
        .copyHeaders(message1.getHeaders())
        .build();

Message<String> message4 = MessageBuilder.withPayload("test4")
        .setHeader("foo", 123)
        .copyHeadersIfAbsent(message1.getHeaders())
        .build();

assertEquals("bar", message3.getHeaders().get("foo"));
assertEquals(123, message4.getHeaders().get("foo"));

Note that the copyHeadersIfAbsent method does not overwrite existing values. Also, in the preceding example, 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).

You can also use MessageBuilder to set the priority of messages, as the following example shows:

Message<Integer> importantMessage = MessageBuilder.withPayload(99)
        .setPriority(5)
        .build();

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

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

assertEquals(2, lessImportantMessage.getHeaders().getPriority());

The priority header is considered only when using a PriorityChannel (as described in the next chapter). It is defined as a java.lang.Integer.

8. Message Routing

This chapter covers the details of using Spring Integration to route messages.

8.1 Routers

This section covers how routers work. It includes the following topics:

8.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 channels depending on a set of conditions.

Spring Integration provides the following routers:

Router implementations share many configuration parameters. However, 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 two following tables .

The following table shows the configuration parameters available for a router outside of a chain:

Table 8.1. Routers Outside of a Chain

Attributerouterheader value routerxpath routerpayload type routerrecipient list routeexception type router

apply-sequence

tickmark
tickmark
tickmark
tickmark
tickmark
tickmark

default-output-channel

tickmark
tickmark
tickmark
tickmark
tickmark
tickmark

resolution-required

tickmark
tickmark
tickmark
tickmark
tickmark
tickmark

ignore-send-failures

tickmark
tickmark
tickmark
tickmark
tickmark
tickmark

timeout

tickmark
tickmark
tickmark
tickmark
tickmark
tickmark

id

tickmark
tickmark
tickmark
tickmark
tickmark
tickmark

auto-startup

tickmark
tickmark
tickmark
tickmark
tickmark
tickmark

input-channel

tickmark
tickmark
tickmark
tickmark
tickmark
tickmark

order

tickmark
tickmark
tickmark
tickmark
tickmark
tickmark

method

tickmark
     

ref

tickmark
     

expression

tickmark
     

header-name

 
tickmark
    

evaluate-as-string

  
tickmark
   

xpath-expression-ref

  
tickmark
   

converter

  
tickmark
   

The following table shows the configuration parameters available for a router inside of a chain:

Table 8.2. Routers Inside of a Chain

Attributerouterheader value routerxpath routerpayload type routerrecipient list routerexception type router

apply-sequence

tickmark
tickmark
tickmark
tickmark
tickmark
tickmark

default-output-channel

tickmark
tickmark
tickmark
tickmark
tickmark
tickmark

resolution-required

tickmark
tickmark
tickmark
tickmark
tickmark
tickmark

ignore-send-failures

tickmark
tickmark
tickmark
tickmark
tickmark
tickmark

timeout

tickmark
tickmark
tickmark
tickmark
tickmark
tickmark

id

      

auto-startup

      

input-channel

      

order

      

method

tickmark
     

ref

tickmark
     

expression

tickmark
     

header-name

 
tickmark
    

evaluate-as-string

  
tickmark
   

xpath-expression-ref

  
tickmark
   

converter

  
tickmark
   

[Important]Important

As of Spring Integration 2.1, router parameters have been more standardized across all router implementations. Consequently, a few minor changes may break 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 requires at least one resolved channel and, by default, throws a MessageDeliveryException if no channel was determined (or an attempt to send was not successful).

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

8.1.2 Common Router Parameters

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

Inside and Outside of a Chain

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

apply-sequence
This attribute specifies whether sequence number and size headers should be added to each message. This optional attribute defaults to false.
default-output-channel

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

[Note]Note

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

resolution-required

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

[Note]Note

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

ignore-send-failures

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

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

[Note]Note

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

This attribute defaults to false.

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

Top-Level (Outside of a Chain)

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

id
Identifies the underlying Spring bean definition, which, in the case of routers, is an instance of EventDrivenConsumer or PollingConsumer, depending on whether the router’s input-channel is a SubscribableChannel or a PollableChannel, respectively. This is an optional attribute.
auto-startup
This "lifecycle" attribute signaled whether this component should be started during startup of the application context. This optional attribute defaults to true.
input-channel
The receiving message channel of this endpoint.
order
This attribute defines the order for invocation when this endpoint is connected as a subscriber to a channel. This is particularly relevant when that channel uses a failover dispatching strategy. It has no effect when this endpoint itself is a polling consumer for a channel with a queue.

8.1.3 Router Implementations

Since content-based routing often requires some domain-specific logic, most use cases require Spring Integration’s options for delegating to POJOs by using either the XML namespace support or annotations. Both of these are discussed later. However, we first present a couple of implementations that fulfill common requirements.

PayloadTypeRouter

A PayloadTypeRouter sends messages to the channel defined by payload-type mappings, as the following example shows:

<bean id="payloadTypeRouter"
      class="org.springframework.integration.router.PayloadTypeRouter">
    <property name="channelMapping">
        <map>
            <entry key="java.lang.String" value-ref="stringChannel"/>
            <entry key="java.lang.Integer" value-ref="integerChannel"/>
        </map>
    </property>
</bean>

Configuration of the PayloadTypeRouter is also supported by the namespace provided by Spring Integration (see <<configuration-namespace>>), which essentially simplifies configuration by combining the <router/> configuration and its corresponding implementation (defined by using a <bean/> element) into a single and more concise configuration element. The following example shows a PayloadTypeRouter configuration that is equivalent to the one above but uses 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" />
</int:payload-type-router>

The following example shows the equivalent router configured in Java:

@ServiceActivator(inputChannel = "routingChannel")
@Bean
public PayloadTypeRouter router() {
    PayloadTypeRouter router = new PayloadTypeRouter();
    router.setChannelMapping(String.class.getName(), "stringChannel");
    router.setChannelMapping(Integer.class.getName(), "integerChannel");
    return router;
}

When using the Java DSL, there are two options.

First, you can define the router object as shown in the preceding example:

@Bean
public IntegrationFlow routerFlow1() {
    return IntegrationFlows.from("routingChannel")
            .route(router())
            .get();
}

public PayloadTypeRouter router() {
    PayloadTypeRouter router = new PayloadTypeRouter();
    router.setChannelMapping(String.class.getName(), "stringChannel");
    router.setChannelMapping(Integer.class.getName(), "integerChannel");
    return router;
}

Note that the router can be, but does not have to be, a @Bean. The flow registers it if it is not a @Bean.

Second, you can define the routing function within the DSL flow itself, as the following example shows:

@Bean
public IntegrationFlow routerFlow2() {
    return IntegrationFlows.from("routingChannel")
            .<Object, Class<?>>route(Object::getClass, m -> m
                    .channelMapping(String.class, "stringChannel")
                    .channelMapping(Integer.class, "integerChannel"))
            .get();
}

HeaderValueRouter

A HeaderValueRouter sends 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:

  • An arbitrary value
  • A channel name

If it is an arbitrary value, additional mappings for these header values to channel names are required. Otherwise, no additional configuration is needed.

Spring Integration provides a simple namespace-based XML configuration to configure a HeaderValueRouter. The following example demonstrates configuration for the HeaderValueRouter when 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" />
</int:header-value-router>

During the resolution process, the router defined in the preceding example 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 are sent to the default-output-channel. However, when the header value is mapped to a channel name but the channel cannot be resolved, setting the resolution-required attribute to false results in routing such messages to the default-output-channel.

[Important]Important

As of Spring Integration 2.1, the attribute was changed from ignore-channel-name-resolution-failures to resolution-required. Attribute resolution-required defaults to true.

The following example shows the equivalent router configured in Java:

@ServiceActivator(inputChannel = "routingChannel")
@Bean
public HeaderValueRouter router() {
    HeaderValueRouter router = new HeaderValueRouter("testHeader");
    router.setChannelMapping("someHeaderValue", "channelA");
    router.setChannelMapping("someOtherHeaderValue", "channelB");
    return router;
}

When using the Java DSL, there are two options. First, you can define the router object as shown in the preceding example:

@Bean
public IntegrationFlow routerFlow1() {
    return IntegrationFlows.from("routingChannel")
            .route(router())
            .get();
}

public HeaderValueRouter router() {
    HeaderValueRouter router = new HeaderValueRouter("testHeader");
    router.setChannelMapping("someHeaderValue", "channelA");
    router.setChannelMapping("someOtherHeaderValue", "channelB");
    return router;
}

Note that the router can be, but does not have to be, a @Bean. The flow registers it if it is not a @Bean.

Second, you can define the routing function within the DSL flow itself, as the following example shows:

@Bean
public IntegrationFlow routerFlow2() {
    return IntegrationFlows.from("routingChannel")
            .<Message<?>, String>route(m -> m.getHeaders().get("testHeader", String.class), m -> m
                    .channelMapping("someHeaderValue", "channelA")
                    .channelMapping("someOtherHeaderValue", "channelB"),
                e -> e.id("headerValueRouter"))
            .get();
}

Configuration where mapping of header values to channel names is not required, because header values themselves represent channel names. The following example shows a router that does not require mapping of header values to channel names:

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

Since Spring Integration 2.1, the behavior of resolving channels is more explicit. For example, if you omit the default-output-channel attribute, 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.

RecipientListRouter

A RecipientListRouter sends each received message to a statically defined list of message channels. The following example creates a RecipientListRouter:

<bean id="recipientListRouter"
      class="org.springframework.integration.router.RecipientListRouter">
    <property name="channels">
        <list>
            <ref bean="channel1"/>
            <ref bean="channel2"/>
            <ref bean="channel3"/>
        </list>
    </property>
</bean>

Spring Integration also provides namespace support for the RecipientListRouter configuration (see Section E.1, “Namespace Support”) as the following example shows:

<int:recipient-list-router id="customRouter" input-channel="routingChannel"
        timeout="1234"
        ignore-send-failures="true"
        apply-sequence="true">
  <int:recipient channel="channel1"/>
  <int:recipient channel="channel2"/>
</int:recipient-list-router>

The following example shows the equivalent router configured in Java:

@ServiceActivator(inputChannel = "routingChannel")
@Bean
public RecipientListRouter router() {
    RecipientListRouter router = new RecipientListRouter();
    router.setSendTimeout(1_234L);
    router.setIgnoreSendFailures(true);
    router.setApplySequence(true);
    router.addRecipient("channel1");
    router.addRecipient("channel2");
    router.addRecipient("channel3");
    return router;
}

The following example shows the equivalent router configured by using the Java DSL:

@Bean
public IntegrationFlow routerFlow() {
    return IntegrationFlows.from("routingChannel")
            .routeToRecipients(r -> r
                    .applySequence(true)
                    .ignoreSendFailures(true)
                    .recipient("channel1")
                    .recipient("channel2")
                    .recipient("channel3")
                    .sendTimeout(1_234L))
            .get();
}
[Note]Note

The apply-sequence flag here has the same effect as it does for a publish-subscribe-channel, and, as with a publish-subscribe-channel, it is disabled by default on the recipient-list-router. See the 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. Doing so is similar to using a filter at the beginning of a chain to act as a "selective consumer". However, in this case, it is all combined rather concisely into the router’s configuration, as the following example shows:

<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')"/>
</int:recipient-list-router>

In the preceding configuration, a SpEL expression identified by the selector-expression attribute is evaluated to determine whether 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 is always among the list of recipients.

RecipientListRouterManagement

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

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

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

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

From the application start up the simpleRouter, has only one channel1 recipient. But after the addRecipient command, channel2 recipient is 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, at some point, decide to unsubscribe.

Because of the runtime management operation for the <recipient-list-router>, it can be configured without any <recipient> from the start. In this case, the behavior of RecipientListRouter is the same when there is no one matching recipient for the message. If defaultOutputChannel is configured, the message is sent there. Otherwise the MessageDeliveryException is thrown.

XPath Router

The XPath Router is part of the XML Module. See Section 38.5, “Routing XML Messages with XPath”.

Routing and Error Handling

Spring Integration also provides a special type-based router called ErrorMessageExceptionTypeRouter for routing error messages (defined as messages whose payload is a Throwable instance). ErrorMessageExceptionTypeRouter is 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 (for example, payload.getClass().getSuperclass()) to find the most specific type and channel mappings, the ErrorMessageExceptionTypeRouter navigates the hierarchy of exception causes (for example, payload.getCause()) to find the most specific Throwable type or channel mappings and uses mappingClass.isInstance(cause) to match the cause to the class or any super class.

[Note]Note

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

The following example shows a sample configuration for ErrorMessageExceptionTypeRouter:

<int:exception-type-router input-channel="inputChannel"
                           default-output-channel="defaultChannel">
    <int:mapping exception-type="java.lang.IllegalArgumentException"
                 channel="illegalChannel"/>
    <int:mapping exception-type="java.lang.NullPointerException"
                 channel="npeChannel"/>
</int:exception-type-router>

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

8.1.4 Configuring a Generic Router

Spring Integration provides a generic router. You can use it for general-purpose routing (as opposed to the other routers provided by Spring Integration, each of which has some form of specialization).

Configuring a Content-based Router with XML

The router element provides a 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 (which must extend AbstractMessageRouter). The following example shows three generic routers:

<int:router ref="payloadTypeRouter" input-channel="input1"
            default-output-channel="defaultOutput1"/>

<int:router ref="recipientListRouter" input-channel="input2"
            default-output-channel="defaultOutput2"/>

<int:router ref="customRouter" input-channel="input3"
            default-output-channel="defaultOutput3"/>

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

Alternatively, ref may point to a POJO that contains the @Router annotation (shown later), or you can combine the ref with an explicit method name. Specifying a method applies the same behavior described in the @Router annotation section, later in this document. The following example defines a router that points to a POJO in its ref attribute:

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

We generally recommend using a ref attribute 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 can provide an inner bean definition, as the following example shows:

<int:router method="someMethod" input-channel="input3"
            default-output-channel="defaultOutput3">
    <beans:bean class="org.foo.MyCustomRouter"/>
</int:router>
[Note]Note

Using both the ref attribute and an inner handler definition in the same <router> configuration is not allowed. Doing so creates an ambiguous condition and throws an exception.

[Important]Important

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

The following example shows the equivalent router configured in Java:

@Bean
@Router(inputChannel = "routingChannel")
public AbstractMessageRouter myCustomRouter() {
    return new AbstractMessageRouter() {

        @Override
        protected Collection<MessageChannel> determineTargetChannels(Message<?> message) {
            return // determine channel(s) for message
        }

    };
}

The following example shows the equivalent router configured by using the Java DSL:

@Bean
public IntegrationFlow routerFlow() {
    return IntegrationFlows.from("routingChannel")
            .route(myCustomRouter())
            .get();
}

public AbstractMessageRouter myCustomRouter() {
    return new AbstractMessageRouter() {

        @Override
        protected Collection<MessageChannel> determineTargetChannels(Message<?> message) {
            return // determine channel(s) for message
        }

    };
}

Alternately, you can route on data from the message payload, as the following example shows:

@Bean
public IntegrationFlow routerFlow() {
    return IntegrationFlows.from("routingChannel")
            .route(String.class, p -> p.contains("foo") ? "fooChannel" : "barChannel")
            .get();
}

8.1.5 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 that lets you use SpEL to implement simple computations that previously required a custom POJO router.

[Note]Note

For more information about the Spring Expression Language, see the relevant chapter in the Spring Framework Reference Guide:

Generally, a SpEL expression is evaluated and its result is mapped to a channel, as the following example shows:

<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"/>
</int:router>

The following example shows the equivalent router configured in Java:

@Router(inputChannel = "routingChannel")
@Bean
public ExpressionEvaluatingRouter router() {
    ExpressionEvaluatingRouter router = new ExpressionEvaluatingRouter("payload.paymentType");
    router.setChannelMapping("CASH", "cashPaymentChannel");
    router.setChannelMapping("CREDIT", "authorizePaymentChannel");
    router.setChannelMapping("DEBIT", "authorizePaymentChannel");
    return router;
}

The following example shows the equivalent router configured in the Java DSL:

@Bean
public IntegrationFlow routerFlow() {
    return IntegrationFlows.from("routingChannel")
        .route("payload.paymentType", r -> r
            .channelMapping("CASH", "cashPaymentChannel")
            .channelMapping("CREDIT", "authorizePaymentChannel")
            .channelMapping("DEBIT", "authorizePaymentChannel"))
        .get();
}

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

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

In the preceding configuration, the result channel is computed by the SpEL expression, which concatenates the value of the payload with the literal String, Channel.

Another virtue of SpEL for configuring routers is that an expression can return a Collection, effectively making every <router> a recipient list router. Whenever the expression returns multiple channel values, the message is forwarded to each channel. The following example shows such an expression:

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

In the above configuration, if the message includes a header with a name of channels and the value of that header is a List of channel names, the message is sent to each channel in the list. You may also find collection projection and collection selection expressions useful when you need to select multiple channels. For further information, see:

Configuring a Router with Annotations

When using @Router to annotate a method, the method may return either a MessageChannel or a String type. In the latter case, the endpoint resolves 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 is sent to multiple channels. To summarize, the following method signatures are all valid:

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

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

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

@Router
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 an attribute. In this case, a method annotated with @Router may include a parameter annotated with @Header, which is mapped to a header value as the following example shows and documented in Section E.5, “Annotation Support”:

@Router
public List<String> route(@Header("orderStatus") OrderStatus status)
[Note]Note

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

See also Section 11.7, “Message Routers” in the Java DSL chapter for more information about router configuration.

8.1.6 Dynamic Routers

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 that computes channels based on the payload type of the incoming message while HeaderValueRouter provides the same convenience in configuring a router that computes channels by evaluating the value of a particular message Header. There are also expression-based (SpEL) routers, in which the channel is determined based on evaluating an expression. All of 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 always results 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 that message flows may be routed to a different channel.

For example, you might want to bring down some part of your system for maintenance and temporarily re-reroute messages to a different message flow. As another example, 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 either of those goals, you would have to bring down your entire application, change the configuration of the router (change routes), and bring the application back up. This is obviously not a solution anyone wants.

The dynamic router pattern describes the mechanisms by which you can change or configure routers dynamically without bringing down the system or individual routers. 

Before we get into the specifics of how Spring Integration supports dynamic routing, we need to consider the typical flow of a router:

  1. Compute a channel identifier, which is a value calculated by the router once it receives the message. Typically, it is a String or an instance of the actual MessageChannel.
  2. Resolve the channel identifier to a channel name. We describe specifics of this process later in this section.
  3. Resolve the 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, because the MessageChannel is the final product of any router’s job. However, if the first step results in a channel identifier that is not an instance of MessageChannel, you have quite a few possible ways to influence the process of deriving the MessageChannel. Consider the following example of a 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" />
</int:payload-type-router>

Within the context of a payload type router, the three steps mentioned earlier would be realized as follows:

  1. Compute a channel identifier that is the fully qualified name of the payload type (for example, java.lang.String).
  2. Resolve the channel identifier to a channel name, where the result of the previous step is used to select the appropriate value from the payload type mapping defined in the mapping element.
  3. Resolve the 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.

Now consider an example of a 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" />
</int:header-value-router>

Now we can consider how the three steps work for a header value router:

  1. Compute a channel identifier that is the value of the header identified by the header-name attribute.
  2. Resolve the channel identifier a to channel name, where the result of the previous step is used to select the appropriate value from the general mapping defined in the mapping element.
  3. Resolve the 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 preceding two configurations of two different router types look almost identical. However, if you look at the alternate configuration of the HeaderValueRouter we clearly see that there is no mapping sub element, as the following listing shows:

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

However, the configuration is still perfectly valid. So the natural question is what about the mapping in the second step?

The second step is now optional. If mapping is not defined, then the channel identifier value computed in the first step is automatically treated as the channel name, which is now resolved to the actual MessageChannel, as in the third step.  What it also means is that the second step is one of the key steps to providing dynamic characteristics to the routers, since it introduces a process that lets you change the way channel identifier resolves to the channel name, thus influencing the process of determining the final instance of the MessageChannel from the initial channel identifier. 

For example, in the preceding configuration, assume that the testHeader value is kermit, which is now a channel identifier (the first step). Since there is no mapping in this router, resolving this channel identifier to a channel name (the second step) is impossible and this channel identifier is now treated as the channel name. However, what if there was a mapping but for a different value? The end result would still be the same, because, if a new value cannot be determined through the process of resolving the channel identifier to a channel name, the channel identifier becomes the channel name.

All that is left is for the third step 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 provided name. Now all messages that contain the header-value pair as testHeader=kermit are going to be routed to a MessageChannel whose bean name (its id) is kermit.

But what if you want to route these messages to the simpson channel? Obviously changing a static configuration works, but doing so also requires bringing your system down. However, if you had access to the channel identifier map, you could introduce a new mapping where the header-value pair is now kermit=simpson, thus letting the second step 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 now have a chance to go through the second step to be 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, because the channelMapping is defined at the AbstractMappingMessageRouter level. That map’s setter method is exposed as a public method along with the setChannelMapping and removeChannelMapping methods. These let you change, add, and 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 through JMX (see Section 12.2, “JMX Support”) or the Spring Integration control bus (see Section 12.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 to which you can send control messages to manage and monitor Spring Integration components, including routers.

[Note]Note

For more information about the control bus, see Section 12.6, “Control Bus”.

Typically, you would send a control message asking to invoke a particular operation on a particular managed component (such as a router). The following managed operations (methods) are specific to changing the router resolution process:

  • public void setChannelMapping(String key, String channelName): Lets you add a new or modify an existing mapping between channel identifier and channel name
  • public void removeChannelMapping(String key): Lets you 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 (such as updating a single route or adding or removing a route). However, if you want to remove one route and add another, the updates are not atomic. This means that 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. The following methods let you do so:

  • public Map<String, String>getChannelMappings(): Returns the current mappings.
  • public void replaceChannelMappings(Properties channelMappings): Updates the mappings. Note that the channelMappings parameter is a Properties object. This arrangement lets a control bus command use the built-in StringToPropertiesConverter, as the following example shows:
"@'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, we recommend that you use the setChannelMappings method, due to type-safety concerns. replaceChannelMappings ignores keys or values that are not String objects.

Manage Router Mappings by Using JMX

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

[Note]Note

For more information about Spring Integration’s JMX support, see Section 12.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 instances, when an outputChannel is not 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 is 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 that contains path entries, as the following example shows:

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

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

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

The preceding example has:

  • 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 Spring expressions (SpEL). The RoutingSlipHeaderValueMessageProcessor checks each routing slip path entry against the BeanFactory on the first processMessage invocation. It converts entries (which are not 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 that uses the requestMessage and 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 by using SpEL (for example, @routingSlipRoutingPojo.get(request, reply) and request.headers[myRoutingSlipChannel]) and avoid defining a bean for the RoutingSlipRouteStrategy.

[Note]Note

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 (when, for example, it is returned by a POJO method invoked by a service activator). In the first two cases, the usual Message properties (payload and headers) are available when using SpEL (or a Java implementation). For an arbitrary domain object, these properties are not available. For this reason, be careful when you use routing slips in conjunction with POJO methods if the result is used to determine the next path.

[Important]Important

If a routing slip is involved in a distributed environment, we recommend not using inline expressions for the Routing Slip path. This recommendation applies to distributed environments such as cross-JVM applications, using a request-reply through a message broker (such asChapter 14, AMQP Support or Chapter 23, JMS Support), or using a persistent MessageStore (Section 12.4, “Message Store”) in the integration flow. The framework uses RoutingSlipHeaderValueMessageProcessor to convert them to ExpressionEvaluatingRoutingSlipRouteStrategy objects, and they are used in the routingSlip message header. Since this class is not Serializable (it cannot be, because it depends on the BeanFactory), the entire Message becomes non-serializable and, in any distributed operation, we end up with a 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, you can add a RoutingSlipHeaderValueMessageProcessor instance to the HeaderEnricher bean definition, as the following example shows:

@Bean
@Transformer(inputChannel = "routingSlipHeaderChannel")
public HeaderEnricher headerEnricher() {
    return new HeaderEnricher(Collections.singletonMap(IntegrationMessageHeaderAccessor.ROUTING_SLIP,
            new RoutingSlipHeaderValueMessageProcessor("myRoutePath1",
                                                       "@routingSlipRoutingPojo.get(request, reply)",
                                                       "routingSlipRoutingStrategy",
                                                       "request.headers[myRoutingSlipChannel]",
                                                       "finishChannel")));
}

The routing slip algorithm works as follows when an endpoint produces a reply and no outputChannel has been defined:

  • The routingSlipIndex is used to get a value from the routing slip path list.
  • If the value from 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 does not return an empty String, that result is used as 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 is not 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

Enterprise integration patterns include the process manager pattern. You can now easily implement this pattern by 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 be a bean in the application context. This way, we can provide powerful dynamic routing logic when there is no way to predict which channel should be used. A MessageChannel can be created within the RoutingSlipRouteStrategy and returned. A FixedSubscriberChannel with an associated MessageHandler implementation is a good combination for such cases. For example, you can route to a reactor stream, as the following example shows:

@Bean
public PollableChannel resultsChannel() {
    return new QueueChannel();
}
@Bean
public RoutingSlipRouteStrategy routeStrategy() {
    return (requestMessage, reply) -> requestMessage.getPayload() instanceof String
            ? new FixedSubscriberChannel(m ->
            Mono.just((String) m.getPayload())
                    .map(String::toUpperCase)
                    .subscribe(v -> messagingTemplate().convertAndSend(resultsChannel(), v)))
            : new FixedSubscriberChannel(m ->
            Mono.just((Integer) m.getPayload())
                    .map(v -> v * 2)
                    .subscribe(v -> messagingTemplate().convertAndSend(resultsChannel(), v)));
}

8.2 Filter

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 decides only whether to send the message at all.

[Note]Note

As we describe later in this section, the filter also supports a discard channel. In certain cases, it can play the role of a very simple router (or "switch"), based on a boolean condition.

In Spring Integration, you can configure a message filter as a message endpoint that delegates to an implementation of the MessageSelector interface. That interface is itself quite simple, as the following listing shows:

public interface MessageSelector {

    boolean accept(Message<?> message);

}

The MessageFilter constructor accepts a selector instance, as the following example shows:

MessageFilter filter = new MessageFilter(someSelector);

In combination with the namespace and SpEL, you can configure powerful filters with very little Java code.

8.2.1 Configuring a Filter with XML

You can use the <filter> element is used to create a message-selecting endpoint. In addition to input-channel and output-channel attributes, it requires a ref attribute. The ref can point to a MessageSelector implementation, as the following example shows:

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

<bean id="selector" class="example.MessageSelectorImpl"/>

Alternatively, you can add the method attribute. In that case, the ref attribute 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 is sent to the output channel. The following example shows how to configure a filter that uses the method attribute:

<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, a few settings control the handling of the rejected message. By default (if configured as in the preceding example), rejected messages are silently dropped. If rejection should instead result in an error condition, set the throw-exception-on-rejection attribute to true, as the following example shows:

<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, as the following example shows:

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

See also Section 10.9.6, “Advising Filters”.

[Note]Note

Message filters are commonly used in conjunction with a publish-subscribe channel. Many filter endpoints may be subscribed to the same channel, and they decide whether or not to pass the message to the next endpoint, which could be any of the supported types (such as a 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.

We recommend using a ref attribute if the custom filter implementation is referenced in other <filter> definitions. However, if the custom filter implementation is scoped to a single <filter> element, you should provide an inner bean definition, as the following example shows:

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

Using both the ref attribute and an inner handler definition in the same <filter> configuration is not allowed, as it creates an ambiguous condition and throws an exception.

[Important]Important

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 applies only if you do not provide any filter-specific attributes in the filter XML definition. If you inadvertently reference the same message handler from multiple beans, you 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, as the following example shows:

<int:filter input-channel="input" expression="payload.equals('nonsense')"/>

The string passed as the value of the expression attribute is evaluated as a SpEL expression with the message available in the evaluation context. If you must 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, as the following example shows:

<int:filter input-channel="input"
            expression="payload.matches(#{filterPatterns.nonsensePattern})"/>

If the expression itself needs to be dynamic, you can use an expression sub-element. 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 example, where the expression could be reloaded within one minute if the underlying file had been modified:

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

<beans:bean id="myExpressions" id="myExpressions"
    class="o.s.i.expression.ReloadableResourceBundleExpressionSource">
    <beans:property name="basename" value="config/integration/expressions"/>
    <beans:property name="cacheSeconds" value="60"/>
</beans:bean>

If the ExpressionSource bean is named expressionSource, you need not provide the` source` attribute on the <expression> element. However, in the preceding example, we show it for completeness.

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) can contain a key/value pair, as the following example shows:

filterPatterns.example=payload > 100
[Note]Note

All of these examples that use expression as an attribute or sub-element can also be applied within transformer, router, splitter, service-activator, and header-enricher elements. The semantics and 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.

8.2.2 Configuring a Filter with Annotations

The following example shows how to configure a filter by using annotations:

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

1

An annotation indicating that this method is to be used as a filter. It must be specified if this class is to 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.

See also Section 10.9.7, “Advising Endpoints Using Annotations”.

8.3 Splitter

The splitter is a component whose role is to partition a message into several parts and send the resulting messages to be processed independently. Very often, they are upstream producers in a pipeline that includes an aggregator.

8.3.1 Programming Model

The API for performing splitting consists of one base class, AbstractMessageSplitter. It is a MessageHandler implementation that encapsulates features 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 filling enables tracking down the messages and the results of their processing (in a typical scenario, these headers get copied to the messages that are produced by the various transforming endpoints). The values can then be used, for example, by a composed message processor.

The following example shows an excerpt from AbstractMessageSplitter:

public abstract class AbstractMessageSplitter
    extends AbstractReplyProducingMessageConsumer {
    ...
    protected abstract Object splitMessage(Message<?> message);

}

To implement a specific splitter in an application, you can extend AbstractMessageSplitter and implement the splitMessage method, which contains logic for splitting the messages. The return value can 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 are sent as messages (after the CORRELATION_ID, SEQUENCE_SIZE and SEQUENCE_NUMBER are populated). Using this approach gives you more control — for example, to populate 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. It works like the prior case, except that each collection element is used as a message payload. Using this approach lets you 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 that a single message is 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 is interpreted as described earlier. The input argument might either be a Message or a simple POJO. In the latter case, the splitter receives the payload of the incoming message. We recommend this approach, because it decouples the code from the Spring Integration API and is typically easier to test.

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.

Starting with version 5.0, the AbstractMessageSplitter provides protected obtainSizeIfPossible() methods to allow the determination of the size of the Iterable and Iterator objects if that is possible. For example XPathMessageSplitter can determine the size of the underlying NodeList object. And starting with version 5.0.9, this method also properly returns a size of the com.fasterxml.jackson.core.TreeNode.

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.

Stream and Flux

Starting with version 5.0, the AbstractMessageSplitter supports the Java Stream and Reactive Streams Publisher types for the value to split. In this case, the target Iterator is built on their iteration functionality.

In addition, if the splitter’s output channel is an instance of a ReactiveStreamsSubscribableChannel, the AbstractMessageSplitter produces a Flux result instead of an Iterator, and the output channel is subscribed to this Flux for back-pressure-based splitting on downstream flow demand.

8.3.2 Configuring a Splitter with 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"/>

1

The ID of the splitter is optional.

2

A reference to a bean defined in the application context. The bean must implement the splitting logic, as described in the earlier section. Optional. If a reference to a bean is not provided, 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 is applied to the collection, incorporating each individual element into a message and sending it to the output-channel.

3

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

4

The input channel of the splitter. Required.

5

The channel to which the splitter sends the results of splitting the incoming message. Optional (because incoming messages can specify a reply channel themselves).

We recommend using a ref attribute if the custom splitter implementation can be referenced in other <splitter> definitions. However if the custom splitter handler implementation should be scoped to a single definition of the <splitter>, you can configure an inner bean definition, as the following example follows:

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

Using both a ref attribute and an inner handler definition in the same <int:splitter> configuration is not allowed, as it creates an ambiguous condition and results in an exception being thrown.

[Important]Important

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 a separate bean instance (or a prototype-scoped bean) or use the inner <bean/> configuration type. However, this optimization applies only if you do not provide any splitter-specific attributes in the splitter XML definition. If you inadvertently reference the same message handler from multiple beans, you get a configuration exception.

8.3.3 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, each item is wrapped in a Message as the payload of the Message. Each resulting Message is sent to the designated output channel for the endpoint on which the @Splitter is defined.

The following example shows how to configure a splitter by using the @Splitter annotation:

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

See also Section 10.9.7, “Advising Endpoints Using Annotations”.

See also Section 11.8, “Splitters” in the Java DSL chapter.

8.4 Aggregator

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. 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 so, it requires a MessageStore.

8.4.1 Functionality

The Aggregator combines a group of related messages, by correlating and storing them, until the group is deemed to be complete. At that point, the aggregator creates a single message by processing the whole group and sends the aggregated message as output.

Implementing an aggregator requires providing the logic to perform the aggregation (that is, 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 are grouped together. However, you can customize the correlation strategy to allow other ways of specifying how the messages should be grouped together. To do so, you can implement a CorrelationStrategy (covered later in this chapter).

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 releases a group when all messages included in a sequence are present, based on the IntegrationMessageHeaderAccessor.SEQUENCE_SIZE header. You can override this default strategy by providing a reference to a custom ReleaseStrategy implementation.

8.4.2 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: SimpleSequenceSizeReleaseStrategy
  • The CorrelationStrategy interface and its default implementation: HeaderAttributeCorrelationStrategy

AggregatingMessageHandler

The AggregatingMessageHandler (a subclass of AbstractCorrelatingMessageHandler) is a MessageHandler implementation, encapsulating the common functionality of an aggregator (and other correlating use cases), which are as follows:

  • 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 for deciding how the messages should be grouped together is delegated to a CorrelationStrategy instance. The responsibility for deciding whether the message group can be released is delegated to a ReleaseStrategy instance.

The following listing shows a brief highlight of the base AbstractAggregatingMessageGroupProcessor (the responsibility for 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 has a default value based on the IntegrationMessageHeaderAccessor.CORRELATION_ID message header, as the following example shows:

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 SimpleSequenceSizeReleaseStrategy() : releaseStrategy;
    ...
}

As for the 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 a splitter, a publish-subscribe channel, or a recipient list router upstream.

[Note]Note

When using a publish-subscribe channel or a recipient list router in this type of scenario, be sure to enable the apply-sequence flag. Doing so adds 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 publish-subscribe channels or for recipient list routers 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, you 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 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 is invoked for aggregating messages as follows:

  • If the argument is a java.util.Collection<T> and the parameter type T is assignable to Message, the whole list of messages accumulated for aggregation is sent to the aggregator.
  • If the argument is a non-parameterized java.util.Collection or the parameter type is not assignable to Message, the method receives the payloads of the accumulated messages.
  • If the return type is not assignable to Message, it is treated as the payload for a Message that is automatically created by the framework.
[Note]Note

In the interest of code simplicity and promoting best practices such as low coupling, testability, and others, 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.

Starting with version 5.1, after processing message group, an AbstractCorrelatingMessageHandler performs a MessageBuilder.popSequenceDetails() message headers modification for the proper splitter-aggregator scenario with several nested levels. It is done only if the message group release result is not a message or collection of messages. In that case a target MessageGroupProcessor is responsible for the MessageBuilder.popSequenceDetails() call while building those messages. This functionality can be controlled by a new popSequence boolean property, so the MessageBuilder.popSequenceDetails() can be disabled in some scenarios when correlation details have not been populated by the standard splitter. This property, essentially, undoes what has been done by the nearest upstream applySequence = true in the AbstractMessageSplitter. See Section 8.3, “Splitter” for more information.

[Important]Important

The SimpleMessageGroup.getMessages() method returns an unmodifiableCollection. Therefore, if your aggregating POJO method has a Collection<Message> parameter, the argument passed in is exactly that Collection instance and, when you use a SimpleMessageStore for the aggregator, that original Collection<Message> is cleared after releasing the group. Consequently, the Collection<Message> variable in the POJO is cleared too, if it is passed out of the aggregator. If you wish to simply release that collection as-is for further processing, you must build a new Collection (for example, 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 processMessageGroup method of the MessageGroupProcessor returns a collection, it must be a collection of Message<?> objects. In this case, the messages are individually released. Prior to version 4.2, it was not possible to provide a MessageGroupProcessor by 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. It returns the collection of messages from the group, which, as indicated earlier, causes the released messages to be sent individually.

This lets the aggregator 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.

ReleaseStrategy

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 is 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, the whole list of messages accumulated in the group is sent to the method.
  • If the argument is a non-parametrized java.util.List or the parameter type is not assignable to Message, the method receives the payloads of the accumulated messages.
  • The method must return true if the message group is ready for aggregation or false otherwise.

The following example shows how to use the @ReleaseStrategy annotation for a List of type Message:

public class MyReleaseStrategy {

    @ReleaseStrategy
    public boolean canMessagesBeReleased(List<Message<?>>) {...}
}

The following example shows how to use the @ReleaseStrategy annotation for a List of type String:

public class MyReleaseStrategy {

    @ReleaseStrategy
    public boolean canMessagesBeReleased(List<String>) {...}
}

Based on the signatures in the preceding two examples, the POJO-based release strategy is 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). This satisfies the majority of use cases. However if, for some reason, you need to access the full MessageGroup, you should provide an implementation of the ReleaseStrategy interface.

[Warning]Warning

When handling potentially large groups, you should 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<Something> 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 Something) every time the release strategy is called. Using Collection<?> avoids the conversion but still requires creating the new Collection.

For these reasons, for large groups, we 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 (that is, 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 are sent to the discard channel (if defined). Setting expire-groups-upon-completion to true (the default is false) removes the entire group, and any new messages (with the same correlation ID as the removed group) form a new group. You can release partial sequences by using a MessageGroupStoreReaper together with send-partial-result-on-expiry being set to true.

[Important]Important

To facilitate discarding of late-arriving messages, the aggregator must maintain state about the group after it has been released. This can eventually cause out-of-memory conditions. To avoid such situations, you should consider configuring a MessageGroupStoreReaper to remove the group metadata. The expiry parameters should be set to expire groups once a point has been reach after after which late messages are not expected to arrive. For information about configuring a reaper, see Section 8.4.4, “Managing State in an Aggregator: MessageGroupStore.

Spring Integration provides an implementation for ReleaseStrategy: SimpleSequenceSizeReleaseStrategy. 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 earlier, it is also the default strategy.

[Note]Note

Before version 5.0, the default release strategy was SequenceSizeReleaseStrategy, which does not perform well with large groups. With that strategy, duplicate sequence numbers are detected and rejected. This operation can be expensive.

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 is the default since version 5.0 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 to remove, 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 12.4.1, “Using MessageGroupFactory, a SimpleMessageGroupFactory is provided so that you can select the Collection that best suits your needs. You can also provide your own factory implementation to create some other Collection<Message<?>>.

The following example shows 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>
    </property>
</bean>

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

Correlation Strategy

The CorrelationStrategy interface is defined as follows:

public interface CorrelationStrategy {

  Object getCorrelationKey(Message<?> message);

}

The method returns an Object that 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 implementation for CorrelationStrategy: 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 that returns the value of the CORRELATION_ID header attribute. If you have a custom header name you would like to use for correlation, you can configure it on an instance of HeaderAttributeCorrelationStrategy and provide that as a reference for the aggregator’s correlation strategy.

Lock Registry

Changes to groups are thread safe. So, when you send messages for the same correlation ID concurrently, only one of them will be processed in the aggregator, making it effectively as a single-threaded per message group. 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, you must configure a shared lock registry.

Avoiding Deadlocks

As discussed above, when message groups are mutated (messages added or released) a lock is held.

Consider the following flow:

...->aggregator1-> ... ->aggregator2-> ...

If there are multiple threads, and the aggregators share a common lock registry, it is possible to get a deadlock. This will cause hung threads and jstack <pid> might present a result such as:

Found one Java-level deadlock:
=============================
"t2":
  waiting for ownable synchronizer 0x000000076c1cbfa0, (a java.util.concurrent.locks.ReentrantLock$NonfairSync),
  which is held by "t1"
"t1":
  waiting for ownable synchronizer 0x000000076c1ccc00, (a java.util.concurrent.locks.ReentrantLock$NonfairSync),
  which is held by "t2"

There are several ways to avoid this problem:

  • ensure each aggregator has its own lock registry (this can be a shared registry across application instances but two or more aggregators in the flow must each have a distinct registry)
  • use an ExecutorChannel or QueueChannel as the output channel of the aggregator so that the downstream flow runs on a new thread
  • starting with version 5.1.1, set the releaseLockBeforeSend aggregator property to true
[Note]Note

This problem can also be caused if, for some reason, the output of a single aggregator is eventually routed back to the same aggregator. Of course, the first solution above does not apply in this case.

8.4.3 Configuring an Aggregator in Java DSL

See Section 11.9, “Aggregators and Resequencers” for how to configure an aggregator in Java DSL.

Configuring an Aggregator with XML

Spring Integration supports the configuration of an aggregator with XML through the <aggregator/> element. The following example shows 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)
</aggregator>

<int:channel id="outputChannel"/>

<int:channel id="throwAwayChannel"/>

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

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

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

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

1

The id of the aggregator is optional.

2

Lifecycle attribute signaling whether the aggregator should be started during application context startup. Optional (the default is true).

3

The channel from which where aggregator receives messages. Required.

4

The channel to which the aggregator sends the aggregation results. Optional (because incoming messages can themselves specify a reply channel in the replyChannel message header).

5

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

6

A reference to a MessageGroupStore used to store groups of messages under their correlation key until they are complete. Optional. By default, it is a volatile in-memory store. See Section 12.4, “Message Store” for more information.

7

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

8

Indicates that expired messages should be aggregated and sent to the output-channel or replyChannel once their containing MessageGroup is expired (see MessageGroupStore.expireMessageGroups(long)). One way of expiring a MessageGroup is by configuring a MessageGroupStoreReaper. However you can alternatively expire MessageGroup by calling MessageGroupStore.expireMessageGroups(timeout). You can accomplish that through a Control Bus operation or, if you have a reference to the MessageGroupStore instance, by invoking expireMessageGroups(timeout). Otherwise, by itself, this attribute does nothing. It serves only as an indicator of whether to discard or send to the output or reply channel any messages that are still in the MessageGroup that is about to be expired. Optional (the default is false). NOTE: This attribute might more properly be called send-partial-result-on-timeout, because the group may not actually expire if expire-groups-upon-timeout is set to false.

9

The timeout interval to wait when sending a reply Message to the output-channel or discard-channel. Defaults to -1, which results in blocking indefinitely. It is applied only if the output channel has some sending limitations, such as a QueueChannel with a fixed capacity. In this case, a MessageDeliveryException is thrown. For AbstractSubscribableChannel implementations, the send-timeout is ignored . For group-timeout(-expression), the MessageDeliveryException from the scheduled expire task leads this task to be rescheduled. Optional.

10

A reference to a bean that implements the message correlation (grouping) algorithm. The bean can be an implementation of the CorrelationStrategy interface or a POJO. In the latter case, the correlation-strategy-method attribute must be defined as well. Optional (by default, the aggregator uses the IntegrationMessageHeaderAccessor.CORRELATION_ID header).

11

A method defined on the bean referenced by correlation-strategy. It implements the correlation decision algorithm. Optional, with restrictions (correlation-strategy must be present).

12

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

13

A reference to a bean defined in the application context. The bean must implement the aggregation logic, as described earlier. Optional (by default, the list of aggregated messages becomes a payload of the output message).

14

A method defined on the bean referenced by the ref attribute. It implements the message aggregation algorithm. Optional (it depends on ref attribute being defined).

15

A reference to a bean that implements the release strategy. The bean can be an implementation of the ReleaseStrategy interface or a POJO. In the latter case, the release-strategy-method attribute must be defined as well. Optional (by default, the aggregator uses the IntegrationMessageHeaderAccessor.SEQUENCE_SIZE header attribute).

(16)

A method defined on the bean referenced by the release-strategy attribute. It implements the completion decision algorithm. Optional, with restrictions (release-strategy must be present).

(17)

A SpEL expression representing the release strategy. The root object for the expression is a MessageGroup. Example: "size() == 5". Only one of release-strategy or release-strategy-expression is allowed.

(18)

When set to true (the default is false), completed groups are removed from the message store, letting subsequent messages with the same correlation form a new group. The default behavior is to send messages with the same correlation as a completed group to the discard-channel.

(19)

Applies only if a MessageGroupStoreReaper is configured for the MessageStore of the <aggregator>. By default, when a MessageGroupStoreReaper is configured to expire partial groups, empty groups are also removed. Empty groups exist after a group is normally released. The empty groups 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 are then not 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 is also affected by the reaper’s timeout property, and it could be as much as this value plus the timeout.

(20)

A reference to a org.springframework.integration.util.LockRegistry bean. It 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 can operate on a group concurrently. See Section 27.10, “Redis Lock Registry”, Section 19.5, “Gemfire Lock Registry”, and Section 40.2, “Zookeeper Lock Registry” for more information.

(21)

A timeout (in milliseconds) to force the MessageGroup complete when the ReleaseStrategy does not release the group when the current message arrives. This attribute provides a built-in time-based 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 (meaning do not release) and groupTimeout > 0, a new task is scheduled to expire the group. We do not advise setting this attribute to zero (or a negative value). Doing so effectively disables the aggregator, because every message group is immediately completed. You can, however, conditionally set it to zero (or a negative value) by 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. It is mutually exclusive with group-timeout-expression attribute.

(22)

The SpEL expression that evaluates to a groupTimeout with the MessageGroup as the #root evaluation context object. Used for scheduling the MessageGroup to be forced complete. If the expression evaluates to null, the completion is not scheduled. If it evaluates to zero, the group is completed immediately on the current thread. In effect, this provides a dynamic group-timeout property. See group-timeout for more information. Mutually exclusive with group-timeout attribute.

(23)

When a group is completed due to a timeout (or by a MessageGroupStoreReaper), the group is expired (completely removed) by default. Late arriving messages start a new group. You can set this to false to complete the group but have its metadata remain so that late arriving messages are discarded. Empty groups can be expired later using a MessageGroupStoreReaper together with the empty-group-min-timeout attribute. It defaults to true.

(24)

A TaskScheduler bean reference to schedule the MessageGroup to be forced complete if no new message arrives for the MessageGroup within the groupTimeout. If not provided, the default scheduler (taskScheduler) registered in the ApplicationContext (ThreadPoolTaskScheduler) is used. This attribute does not apply if group-timeout or group-timeout-expression is not specified.

(25)

Since version 4.1. It lets a transaction 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, and discard operations. Only this sub-element or <expire-advice-chain/> is allowed.

(26)

Since version 4.1. It 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, and discard operations. Only this sub-element or <expire-transactional/> is allowed. A transaction Advice can also be configured here by 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 by 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 control this behavior by using expire-groups-upon-timeout. It defaults to true for backwards compatibility.

[Note]Note

When a group is timed out, the ReleaseStrategy is given one more opportunity to release the group. If it does so and expire-groups-upon-timeout is false, 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).

Since version 5.0, empty groups are also scheduled for removal after empty-group-min-timeout. If expireGroupsUponCompletion == false and minimumTimeoutForEmptyGroups > 0, the task to remove the group is scheduled when normal or partial sequences release happens.

We generally recommend using a ref attribute 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, as the following example shows:

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

Using both a ref attribute and an inner bean definition in the same <aggregator> configuration is not allowed, as it creates an ambiguous condition. In such cases, an Exception is thrown.

The following example shows an implementation of the aggregator bean:

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 preceding example might be as follows:

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

Wherever it makes sense to do so, the release strategy method and the aggregator method can be combined into a single bean.

An implementation of the correlation strategy bean for the example above might be as follows:

public class PojoCorrelationStrategy {
...
  public Long groupNumbersByLastDigit(Long number) {
    return number % 10;
  }
}

The aggregator in the preceding example would group numbers by some criterion (in this case, the remainder after dividing by ten) and hold the group until the sum of the numbers provided by the payloads exceeds a certain value.

[Note]Note

Wherever it makes sense to do so, the release strategy method, the correlation strategy method, and the aggregator method can be combined in a single bean. (Actually, all of them or any two of them can be combined.)

Aggregators and Spring Expression Language (SpEL)

Since Spring Integration 2.0, you can handle the various strategies (correlation, release, and aggregation) with SpEL, which we recommend if the logic behind such a release strategy is relatively simple. Suppose you have a legacy component that was designed to receive an array of objects. We know that the default release strategy assembles all aggregated messages in the List. Now we have two problems. First, we need to extract individual messages from the list. Second, we need to extract the payload of each message and assemble the array of objects. The following example solves both problems:

public String[] processRelease(List<Message<String>> messages){
    List<String> stringList = new ArrayList<String>();
    for (Message<String> message : messages) {
        stringList.add(message.getPayload());
    }
    return stringList.toArray(new String[]{});
}

However, with SpEL, such a requirement could actually be handled relatively easily with a one-line expression, thus sparing you from writing a custom class and configuring it as a bean. The following example shows how to do so:

<int:aggregator input-channel="aggChannel"
    output-channel="replyChannel"
    expression="#this.![payload].toArray()"/>

In the preceding configuration, we use a collection projection expression to assemble a new collection from the payloads of all the messages in the list and then transform it to an array, thus achieving the same result as the earlier Java code.

You can apply the same expression-based approach when dealing with custom release and correlation strategies.

Instead of defining a bean for a custom CorrelationStrategy in the correlation-strategy attribute, you can implement your simple correlation logic as a SpEL expression and configure it in the correlation-strategy-expression attribute, as the following example shows:

correlation-strategy-expression="payload.person.id"

In the preceding example, we assume that the payload has a person attribute 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 in the release-strategy-expression attribute. The root object for evaluation context is the MessageGroup itself. The List of messages can be referenced by using the message property of the group within the expression.

[Note]Note

In releases prior to version 5.0, the root object was the collection of Message<?>, as the previous example shows:

release-strategy-expression="!messages.?[payload==5].empty"

In the preceding example, the root object of the SpEL evaluation context is the MessageGroup itself, and you are stating that, as soon as there is a message with payload of 5 in this group, the group 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 earlier description). See the section called “Configuring an Aggregator with XML”. In some cases, you may need to emit the aggregator result (or discard the group) after a timeout if the ReleaseStrategy does not release when the current message arrives. For this purpose, the groupTimeout option lets scheduling the MessageGroup be forced to complete, as the following example shows:

<aggregator input-channel="input" output-channel="output"
        send-partial-result-on-expiry="true"
        group-timeout-expression="size() ge 2 ? 10000 : -1"
        release-strategy-expression="messages[0].headers.sequenceNumber == messages[0].headers.sequenceSize"/>

With this example, the normal release is 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 forces the group to complete after ten seconds, as long as the group contains at least two Messages.

The results of forcing the group to 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 has not changed, the ReleaseStrategy can decide to release the group at this time. If the release strategy still does not release the group, it is expired. If send-partial-result-on-expiry is true, existing messages in the (partial) MessageGroup are released as a normal aggregator reply message to the output-channel. Otherwise, it is discarded.

There is a difference between groupTimeout behavior and MessageGroupStoreReaper (see the section called “Configuring an Aggregator with XML”). 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 does not 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

The following example shows an aggregator configured with annotations:

public class Waiter {
  ...

  @Aggregator  1
  public Delivery aggregatingMethod(List<OrderItem> items) {
    ...
  }

  @ReleaseStrategy  2
  public boolean releaseChecker(List<Message<?>> messages) {
    ...
  }

  @CorrelationStrategy  3
  public String correlateBy(OrderItem item) {
    ...
  }
}

1

An annotation indicating that this method should be used as an aggregator. It must be specified if this class is used as an aggregator.

2

An annotation indicating that this method is used as the release strategy of an aggregator. If not present on any method, the aggregator uses the SimpleSequenceSizeReleaseStrategy.

3

An annotation indicating that this method should be used as the correlation strategy of an aggregator. If no correlation strategy is indicated, the aggregator uses 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 when using annotation configuration, consider using a @Bean definition for the AggregatingMessageHandler and mark its @Bean method with @ServiceActivator, as the following example shows:

@ServiceActivator(inputChannel = "aggregatorChannel")
@Bean
public MessageHandler aggregator(MessageGroupStore jdbcMessageGroupStore) {
     AggregatingMessageHandler aggregator =
                       new AggregatingMessageHandler(new DefaultAggregatingMessageGroupProcessor(),
                                                 jdbcMessageGroupStore);
     aggregator.setOutputChannel(resultsChannel());
     aggregator.setGroupTimeoutExpression(new ValueExpression<>(500L));
     aggregator.setTaskScheduler(this.taskScheduler);
     return aggregator;
}

See Section 8.4.2, “Programming Model” and Section E.6.1, “Annotations on @Bean Methods” for more information.

[Note]Note

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

8.4.4 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 (such as ReleaseStrategy) is driven by the principle that the components (whether defined by the framework or by a user) should be able to remain stateless. All state is carried by the MessageGroup and its management is delegated to the MessageGroupStore. The MessageGroupStore interface is defined as follows:

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, see 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 lets you register callbacks to apply to its MessageGroups when they expire. The interface is very straightforward, as the following listing shows:

public interface MessageGroupCallback {

    void execute(MessageGroupStore messageGroupStore, MessageGroup group);

}

The callback has direct access to the store and the message group so that it can manage the persistent state (for example, by entirely removing the group from the store).

The MessageGroupStore maintains a list of these callbacks, which it applies, on demand, to all messages whose timestamps are earlier than a time supplied as a parameter (see the registerMessageGroupExpiryCallback(..) and expireMessageGroups(..) methods, described earlier). For more detail, see Section 8.4.4, “Managing State in an Aggregator: MessageGroupStore.

[Important]Important

It is important not to use the same MessageGroupStore instance in different aggregator components, when you intend to rely on the expireMessageGroups functionality. Every AbstractCorrelatingMessageHandler registers its own MessageGroupCallback based on the forceComplete() callback. This way each group for expiration may be completed or discarded by the wrong aggregator. Starting with version 5.0.10, a UniqueExpiryCallback is used from the AbstractCorrelatingMessageHandler for the registration callback in the MessageGroupStore. The MessageGroupStore, in turn, checks for presence an instance of this class and logs an error with an appropriate message if one is already present in the callbacks set. This way the Framework disallows usage of the MessageGroupStore instance in different aggregators/resequencers to avoid the mentioned side effect of expiration the groups not created by the particular correlation handler.

You can call the expireMessageGroups method with a timeout value. Any message older than the current time minus this value is expired and has 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, as the following example shows:

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

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

The reaper is a Runnable. In the preceding example, the message group store’s expire method is called every ten seconds. The timeout itself is 30 seconds.

[Note]Note

It is important to understand that the timeout property of MessageGroupStoreReaper is an approximate value and is impacted by the the rate of the task scheduler, since this property is only checked on the next scheduled execution of the MessageGroupStoreReaper task. For example, if the timeout is set for ten minutes but the MessageGroupStoreReaper task is scheduled to run every hour and the last execution of the MessageGroupStoreReaper task happened one minute before the timeout, the MessageGroup does not expire for the next 59 minutes. Consequently, we recommend setting the rate to be 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 through a lifecycle callback in the AbstractCorrelatingMessageHandler.

The AbstractCorrelatingMessageHandler registers its own expiry callback, and this is the link with the boolean flag send-partial-result-on-expiry in the XML configuration of the aggregator. If the flag is set to true, then, when the expiry callback is invoked, any unmarked messages in groups that are not yet released can be sent on to the output channel.

[Important]Important

When a shared MessageStore is used for different correlation endpoints, you must configure a proper CorrelationStrategy to ensure uniqueness for group IDs. Otherwise, unexpected behavior may happen when one correlation endpoint releases or expire messages from others. Messages with the same correlation key are stored in the same message group.

Some MessageStore implementations allow using the same physical resources, by partitioning the data. For example, the JdbcMessageStore has a region property, and the MongoDbMessageStore has a collectionName property.

For more information about the MessageStore interface and its implementations, see Section 12.4, “Message Store”.

8.5 Resequencer

The resequencer is related to the aggregator but serves a different purpose. While the aggregator combines messages, the resequencer passes messages through without changing them.

8.5.1 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. he difference is that the Resequencer does not process the messages in any way. Instead, it releases them in the order of their SEQUENCE_NUMBER header values.

With respect to that, you can opt to release all messages at once (after the whole sequence, according to the SEQUENCE_SIZE, and other possibilities) or as soon as a valid sequence is available. (We cover what we mean by "a valid sequence" later in this chapter.)

[Important]Important

The resequencer is intended to resequence relatively short sequences of messages with small gaps. If you have a large number of disjoint sequences with many gaps, you may experience performance issues.

8.5.2 Configuring a Resequencer

See Section 11.9, “Aggregators and Resequencers” for configuring a resequencer in Java DSL.

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

The following example shows a resequencer configuration:

<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['something']"  11
  release-strategy="releaseStrategyBean"  12
  release-strategy-method="release"  13
  release-strategy-expression="size() == 10"  14
  empty-group-min-timeout="60000"  15

  lock-registry="lockRegistry"  (16)

  group-timeout="60000"  (17)
  group-timeout-expression="size() ge 2 ? 100 : -1"  (18)
  scheduler="taskScheduler" />  (19)
  expire-group-upon-timeout="false" />  (20)

1

The id of the resequencer is optional.

2

The input channel of the resequencer. Required.

3

The channel to which the resequencer sends the reordered messages. Optional.

4

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

5

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

6

A reference to a MessageGroupStore that can be used to store groups of messages under their correlation key until they are complete. Optional. (The default is a volatile in-memory store.)

7

Whether, upon the expiration of the group, the ordered group should be sent out (even if some of the messages are missing). Optional. (The default is false.) See Section 8.4.4, “Managing State in an Aggregator: MessageGroupStore.

8

The timeout interval to wait when sending a reply Message to the output-channel or discard-channel. Defaults to -1, which blocks indefinitely. It is applied only if the output channel has some sending limitations, such as a QueueChannel with a fixed capacity. In this case, a MessageDeliveryException is thrown. The send-timeout is ignored for AbstractSubscribableChannel implementations. For group-timeout(-expression), the MessageDeliveryException from the scheduled expire task leads this task to be rescheduled. Optional.

9

A reference to a bean that implements the message correlation (grouping) algorithm. The bean can be an implementation of the CorrelationStrategy interface or a POJO. In the latter case, the correlation-strategy-method attribute must also be defined. Optional. (By default, the aggregator uses the IntegrationMessageHeaderAccessor.CORRELATION_ID header.)

10

A method that is defined on the bean referenced by correlation-strategy and that implements the correlation decision algorithm. Optional, with restrictions (requires correlation-strategy to be present).

11

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

12

A reference to a bean that implements the release strategy. The bean can be an implementation of the ReleaseStrategy interface or a POJO. In the latter case, the release-strategy-method attribute must also be defined. Optional (by default, the aggregator will use the IntegrationMessageHeaderAccessor.SEQUENCE_SIZE header attribute).

13

A method that is defined on the bean referenced by release-strategy and that implements the completion decision algorithm. Optional, with restrictions (requires release-strategy to be present).

14

A SpEL expression representing the release strategy. The root object for the expression is a MessageGroup. Example: "size() == 5". Only one of release-strategy or release-strategy-expression is allowed.

15

Only applies if a MessageGroupStoreReaper is configured for the <resequencer> 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 are then not 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 is also affected by the reaper’s timeout property, and it could be as much as this value plus the timeout.

(16)

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

(17)

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

(18)

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

(19)

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

(20)

By default, when a group is completed due to a timeout (or by a MessageGroupStoreReaper), the empty group’s metadata is retained. Late arriving messages are immediately discarded. Set this to true to remove the group completely. Then, late arriving messages start a new group and are not be discarded until the group again times out. The new group is never released normally because of the "hole" in the sequence range that caused the timeout. Empty groups can be expired (completely removed) later by using a MessageGroupStoreReaper together with the empty-group-min-timeout attribute. Starting with version 5.0, empty groups are also scheduled for removal after the empty-group-min-timeout elapses. The default is false.

[Note]Note

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

8.6 Message Handler Chain

The MessageHandlerChain is an implementation of MessageHandler that can be configured as a single message endpoint while actually delegating to a chain of other handlers, such as filters, transformers, splitters, and so on. When several handlers need to be connected in a fixed, linear progression, this can lead to a much simpler configuration. For example, it is fairly common to provide a transformer before other components. Similarly, when you provide a filter before some other component in a chain, you essentially create a selective consumer. In either case, the chain requires only a single input-channel and a single output-channel, eliminating the need to define channels for each individual component.

[Tip]Tip

Spring Integration’s Filter provides a boolean property: throwExceptionOnRejection. When you provide multiple selective consumers on the same point-to-point channel with different acceptance criteria, you should set this value true (the default is false) so that the dispatcher knows that the message was rejected and, as a result, tries to pass the message on to other subscribers. If the exception were not thrown, it would appear to the dispatcher that the message had been passed on successfully even though the filter had dropped the message to prevent further processing. If you do indeed want to "drop" the messages, the filter’s discard-channel might be useful, since it does give you a chance to perform some operation with the dropped message (such as sending it to a JMS queue or writing it to a log).

The handler chain simplifies configuration while internally maintaining the same degree of loose coupling between components, and it is trivial to modify the configuration if at some point a non-linear arrangement is required.

Internally, the chain is expanded into a linear setup of the listed endpoints, separated by anonymous channels. The reply channel header is not taken into account within the chain. Only after the last handler is invoked is the resulting message forwarded to the reply channel or the chain’s output channel. Because of this setup, all handlers except the last must implement the MessageProducer interface (which provides a setOutputChannel() method). If the outputChannel on the MessageHandlerChain is set, the last handler needs only an output channel.

[Note]Note

As with other endpoints, the output-channel is optional. If there is a reply message at the end of the chain, the output-channel takes precedence. However, if it is not available, the chain handler checks for a reply channel header on the inbound message as a fallback.

In most cases, you need not implement MessageHandler yourself. The next section focuses on namespace support for the chain element. Most Spring Integration endpoints, such as service activators and transformers, are suitable for use within a MessageHandlerChain.

8.6.1 Configuring a Chain

The <chain> element provides an input-channel attribute. If the last element in the chain is capable of producing reply messages (optional), it also supports an output-channel attribute. The sub-elements are then filters, transformers, splitters, and service-activators. The last element may also be a router or an outbound channel adapter. The following example shows a chain definition:

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

The <header-enricher> element used in the preceding example sets a message header named thing1 with a value of thing2 on the message. A header enricher is a specialization of Transformer that touches only header values. You could obtain the same result by implementing a MessageHandler that did the header modifications and wiring that as a bean, but the header-enricher is a simpler option.

The <chain> can be configured as the last black-box consumer of the message flow. For this solution, you can to put it at the end of the <chain> some <outbound-channel-adapter>, as the following example shows:

<int:chain input-channel="input">
    <int-xml:marshalling-transformer marshaller="marshaller" result-type="StringResult" />
    <int:service-activator ref="someService" method="someMethod"/>
    <int:header-enricher>
        <int:header name="thing1" value="thing2"/>
    </int:header-enricher>
    <int:logging-channel-adapter level="INFO" log-full-message="true"/>
</int:chain>
[Important]Disallowed Attributes and Elements

Certain attributes, such as order and input-channel are not allowed to be specified on components used within a chain. The same is true for the poller sub-element.

For the Spring Integration core components, the XML schema itself enforces some of these constraints. However, for non-core components or your own custom components, these constraints are enforced by the XML namespace parser, not by the XML schema.

These XML namespace parser constraints were added with Spring Integration 2.2. If you try to use disallowed attributes and elements, the XML namespace parser throws a BeanDefinitionParsingException.

8.6.2 Using the id Attribute

Beginning with Spring Integration 3.0, if a chain element is given an id attribute, the bean name for the element is a combination of the chain’s id and the id of the element itself. Elements without id attributes are not registered as beans, but each one is given a componentName that includes the chain id. Consider the following example:

<int:chain id="somethingChain" input-channel="input">
    <int:service-activator id="somethingService" ref="someService" method="someMethod"/>
    <int:object-to-json-transformer/>
</int:chain>

In the preceding example:

  • The <chain> root element has an id of somethingChain. Consequently, the AbstractEndpoint implementation (PollingConsumer or EventDrivenConsumer, depending on the input-channel type) bean takes this value as its bean name.
  • The MessageHandlerChain bean acquires a bean alias (somethingChain.handler), which allows direct access to this bean from the BeanFactory.
  • The <service-activator> is not a fully fledged messaging endpoint (it is not a PollingConsumer or EventDrivenConsumer). It is a MessageHandler within the <chain>. In this case, the bean name registered with the BeanFactory is somethingChain$child.somethingService.handler.
  • The componentName of this ServiceActivatingHandler takes the same value but without the .handler suffix. It becomes somethingChain$child.somethingService.
  • The last <chain> sub-component, <object-to-json-transformer>, does not have an id attribute. Its componentName is based on its position in the <chain>. In this case, it is somethingChain$child#1. (The final element of the name is the order within the chain, beginning with #0). Note, this transformer is not registered as a bean within the application context, so it does not get a beanName. However its componentName has a value that is useful for logging and other purposes.

The id attribute for <chain> elements lets them be eligible for JMX export, and they are trackable in the message history. You can access them from the BeanFactory by using the appropriate bean name, as discussed earlier.

[Tip]Tip

It is useful to provide an explicit id attribute on <chain> elements to simplify the identification of sub-components in logs and to provide access to them from the BeanFactory etc.

8.6.3 Calling a Chain from within a Chain

Sometimes, you need to make a nested call to another chain from within a chain and then come back and continue execution within the original chain. To accomplish this, you can use a messaging gateway by including a <gateway> element, as the following example shows:

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

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

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

In the preceding example, nested-chain-a is called at the end of main-chain processing by the gateway element configured there. While in nested-chain-a, a call to a nested-chain-b is made after header enrichment. Then the flow comes back to finish execution in nested-chain-b. Finally, the flow returns to main-chain. When the nested version of a <gateway> element is defined in the chain, it does not require the service-interface attribute. Instead, it takes the message in its current state and places it on the channel defined in the request-channel attribute. When the downstream flow initiated by that gateway completes, a Message is returned to the gateway and continues its journey within the current chain.

8.7 Scatter-Gather

Starting with version 4.1, Spring Integration provides an implementation of the scatter-gather enterprise integration pattern. It is a compound endpoint for which the goal is to send a message to the recipients and aggregate the results. As noted in Enterprise Integration Patterns, it is a component for scenarios such as "best quote", where 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 by using discrete components. This enhancement brings more convenient configuration.

The ScatterGatherHandler is a request-reply endpoint that combines a PublishSubscribeChannel (or a RecipientListRouter) and an AggregatingMessageHandler. The request message is sent to the scatter channel, and the ScatterGatherHandler waits for the reply that the aggregator sends to the outputChannel.

8.7.1 Functionality

The Scatter-Gather pattern suggests two scenarios: "auction" and "distribution". In both cases, the aggregation function is the same and provides all the options available for the AggregatingMessageHandler. (Actually, the ScatterGatherHandler requires only an AggregatingMessageHandler as a constructor argument.) See Section 8.4, “Aggregator” for more information.

Auction

The auction Scatter-Gather variant uses "publish-subscribe" logic for the request message, where the "scatter" channel is a PublishSubscribeChannel with apply-sequence="true". However, this channel can be any MessageChannel implementation (as is the case with the request-channel in the ContentEnricher — see Section 9.2, “Content Enricher”). However, in this case, you should create your own custom correlationStrategy for the aggregation function.

Distribution

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 on only the default correlationStrategy for the recipient-list-router and the aggregator, you should specify apply-sequence="true". Otherwise, you should supply a custom correlationStrategy for the aggregator. Unlike the PublishSubscribeChannel variant (the auction variant), having a recipient-list-router selector option lets filter target suppliers based on the message. With apply-sequence="true", the default sequenceSize is supplied, and the aggregator can release the group correctly. The distribution option is mutually exclusive with the auction option.

For both the auction and the distribution variants, the request (scatter) message is enriched with the gatherResultChannel 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, letting suppliers send their reply to that channel for the aggregation.

8.7.2 Configuring a Scatter-Gather Endpoint

The following example shows Java configuration for the bean definition for Scatter-Gather:

@Bean
public MessageHandler distributor() {
    RecipientListRouter router = new RecipientListRouter();
    router.setApplySequence(true);
    router.setChannels(Arrays.asList(distributionChannel1(), distributionChannel2(),
            distributionChannel3()));
    return router;
}

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

@Bean
@ServiceActivator(inputChannel = "distributionChannel")
public MessageHandler scatterGatherDistribution() {
	ScatterGatherHandler handler = new ScatterGatherHandler(distributor(), gatherer());
	handler.setOutputChannel(output());
	return handler;
}

In the preceding example, 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.

The following example shows how to configure the <scatter-gather> endpoint by using the XML namespace:

<scatter-gather
		id=""  1
		auto-startup=""  2
		input-channel=""  3
		output-channel=""  4
		scatter-channel=""  5
		gather-channel=""  6
		order=""  7
		phase=""  8
		send-timeout=""  9
		gather-timeout=""  10
		requires-reply="" > 11
			<scatterer/>  12
			<gatherer/>  13
</scatter-gather>

1

The id of the endpoint. The ScatterGatherHandler bean is registered with an alias of id + '.handler'. The RecipientListRouter bean is registered with an alias of id + '.scatterer'. The AggregatingMessageHandler`bean is registered with an alias of `id + '.gatherer'. Optional. (The BeanFactory generates a default id value.)

2

Lifecycle attribute signaling whether the endpoint should be started during application context initialization. In addition, the ScatterGatherHandler also implements Lifecycle and starts and stops gatherEndpoint, which is created internally if a gather-channel is provided. Optional. (The default is true.)

3

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

4

The channel to which the ScatterGatherHandler sends the aggregation results. Optional. (Incoming messages can specify a reply channel themselves in the replyChannel message header).

5

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

6

The channel on which to receive replies from each supplier for the aggregation. It is used as the replyChannel header in the scatter message. Optional. By default, the FixedSubscriberChannel is created.

7

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

8

Specifies the phase in which the endpoint should be started and stopped. The startup order proceeds from lowest to highest, and the shutdown order is from highest to lowest. By default, this value is Integer.MAX_VALUE, meaning that this container starts as late as possible and stops as soon as possible. Optional.

9

The timeout interval to wait when sending a reply Message to the output-channel. By default, the send blocks for one second. It applies only if the output channel has some sending limitations — for example, a QueueChannel with a fixed capacity that is full. In this case, a MessageDeliveryException is thrown. The send-timeout is ignored for AbstractSubscribableChannel implementations. For group-timeout(-expression), the MessageDeliveryException from the scheduled expire task leads this task to be rescheduled. Optional.

10

Lets you specify how long the scatter-gather waits for the reply message before returning. By default, it waits indefinitely. null is returned if the reply times out. Optional. It defaults to -1, meaning to wait indefinitely.

11

Specifies whether the scatter-gather must return a non-null value. This value is true by default. Consequently, a ReplyRequiredException is thrown when the underlying aggregator returns a null value after gather-timeout. Note, if null is a possibility, the gather-timeout should be specified to avoid an indefinite wait.

12

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

13

The <aggregator> options. Required.

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

In version 4.2, Spring Integration introduced the <barrier/> component for this purpose. The underlying MessageHandler is the BarrierMessageHandler. This class also implements MessageTriggerAction, in which 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 by using a MessageGroupProcessor. By default, the message is a Collection<?> of the two payloads, and the headers are merged by using a DefaultAggregatingMessageGroupProcessor.

[Caution]Caution

If the trigger() method is invoked first (or after the main thread times out), it is 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 that its thread is suspended instead.

The requires-reply property determines the action to take if the suspended thread times out before the trigger message arrives. By default, it is false, which means the endpoint 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 by using the name, barrier.handler — where barrier is the bean name of the barrier endpoint). Alternatively, you can configure an <outbound-channel-adapter/> to trigger the release.

[Important]Important

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.

The following example shows how to use a custom header for correlation:

<int:barrier id="barrier1" input-channel="in" output-channel="out"
        correlation-strategy-expression="headers['myHeader']"
        output-processor="myOutputProcessor"
        discard-channel="lateTriggerChannel"
        timeout="10000">
</int:barrier>

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

Depending on which one has a message arrive first, either the thread sending a message to in or the thread sending a message to release waits for up to ten seconds until the other message arrives. When the message is released, the out channel is sent a message that combines the result of invoking the custom MessageGroupProcessor bean, named myOutputProcessor. If the main thread times out and a trigger arrives later, you can configure a discard channel to which the late trigger is sent. The following example shows the Java configuration to do so:

@Configuration
@EnableIntegration
public class Config {

    @ServiceActivator(inputChannel="in")
    @Bean
    public BarrierMessageHandler barrier() {
        BarrierMessageHandler barrier = new BarrierMessageHandler(10000);
        barrier.setOutputChannel(out());
        barrier.setDiscardChannel(lateTriggers());
        return barrier;
    }

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

            @Override
            public void handleMessage(Message<?> message) throws MessagingException {
                barrier().trigger(message);
            }

        };
    }

}

For an example of this component, see the barrier sample application.

9. Message Transformation

9.1 Transformer

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, you can add transformers 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 or Java annotations enables simple POJOs to be adapted for the role of message transformers. The rest of this chapter describes these configuration options.

[Note]Note

For the sake 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 38, XML Support - Dealing with XML Payloads.

9.1.1 Configuring a 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 ` attribute`. The ref may either point to an object that contains the @Transformer annotation on a single method (see Section 9.1.4, “Configuring a Transformer with Annotations”), or it may be combined with an explicit method name value provided in 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, as the following example shows:

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

Using both the ref attribute and an inner handler definition in the same <transformer> configuration is not allowed, as it creates an ambiguous condition and results in an exception being thrown.

[Important]Important

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 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 is 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 results in an exception, because 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, because 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), you could use a service activator. 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.

9.1.2 Transformers and Spring Expression Language (SpEL)

Like routers, aggregators, and other components, as of Spring Integration 2.0, transformers can also benefit from SpEL support whenever transformation logic is relatively simple. The following example shows how to use a SpEL expression:

<int:transformer input-channel="inChannel"
	output-channel="outChannel"
	expression="payload.toUpperCase() + '- [' + T(java.lang.System).currentTimeMillis() + ']'"/>

The preceding example transforms the payload without writing a custom transformer. Our payload (assumed to be a String) is upper-cased, concatenated with the current timestamp, and has some formatting applied.

9.1.3 Common Transformers

Spring Integration provides a few transformer implementations.

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. The following example shows how to declare an instance of the object-to-string transformer:

<int:object-to-string-transformer input-channel="in" output-channel="out"/>

A potential use for this transformer 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 handles the necessary conversion. 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 provide a custom POJO-based transformer by using the generic transformer element shown previously.

[Tip]Tip

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

[Note]Note

The object-to-string transformer is very simple. It invokes toString() on the inbound payload. Since Spring Integration 3.0, there are two exceptions to this rule:

  • 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, as the following example shows:

<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 use standard Java serialization by default, but you can provide an implementation of Spring 3.0’s serializer or seserializer strategies by using the serializer and deserializer attributes, respectively. The following example shows to use Spring’s serializer and deserializer:

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

<int:payload-deserializing-transformer input-channel="bytesIn" output-channel="objectsOut"
    white-list="com.mycom.*,com.yourcom.*"/>
[Important]Important

When deserializing data from untrusted sources, you should consider adding a white-list of package and class patterns. By default, all classes are deserialized.

Object-to-Map and Map-to-Object Transformers

Spring Integration also provides Object-to-Map and Map-to-Object transformers, which use the JSON to serialize and de-serialize the object graphs. The object hierarchy is introspected to the most primitive types (String, int, and so on). The path to this type is described with SpEL, which becomes the key in the transformed Map. The primitive type becomes the value.

Consider the following 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
}

The two classes in the preceding example are transformed to the following Map:

{person.name=George, person.child.name=Jenna, person.child.nickNames[0]=Jen ...}

The JSON-based Map lets you describe the object structure without sharing the actual types, which lets you restore and rebuild the object graph into a differently typed object graph, as long as you maintain the structure.

For example, the preceding structure could be restored back to the following object graph by using 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 is true. If you set it to false, the structure is a Map of Map objects.

Consider the following 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
}

The two classes in the preceding example are transformed to the following Map:

{name=George, child={name=Jenna, nickNames=[Bimbo, ...]}}

To configure these transformers, Spring Integration provides namespace support for Object-to-Map, as the following example shows:

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

You can also set the flatten attribute to false, as follows:

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

Spring Integration provides namespace support for Map-to-Object, as the following example shows:

<int:map-to-object-transformer input-channel="input" 
                         output-channel="output" 
                          type="org.something.Person"/>

Alterately, you could use a ref attribute and a prototype-scoped bean, as the following example shows:

<int:map-to-object-transformer input-channel="inputA" 
                                output-channel="outputA" 
                                ref="person"/>
<bean id="person" class="org.something.Person" scope="prototype"/>
[Note]Note

The ref and type attributes are mutually exclusive. Also, if you use the ref attribute, you must point to a prototype scoped bean. Otherwise, a BeanCreationException is thrown. 

Starting with version 5.0, you can supply the ObjectToMapTransformer with a customized JsonObjectMapper — for when you need special formats for dates or nulls for empty collections (and other uses). See the section called “JSON Transformers” for more information about JsonObjectMapper implementations.

Stream Transformer

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

The following example shows how to use the stream-tansformer element in XML:

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

The following example shows how to use the StreamTransformer class and the @Transformer annotation to configure a stream transformer in Java:

@Bean
@Transformer(inputChannel = "stream", outputChannel = "data")
public StreamTransformer streamToBytes() {
    return new StreamTransformer(); // transforms to byte[]
}

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

JSON Transformers

Spring Integration provides Object-to-JSON and JSON-to-Object transformers. The following pair of examples show how to declare them in XML:

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

By default, the transformers in the preceding listing use a vanilla JsonObjectMapper. It is based on an implementation from the classpath. You can provide your own custom JsonObjectMapper implementation with appropriate options or based on a required library (such as GSON), as the following example shows:

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

Beginning with version 3.0, the object-mapper attribute references an instance of a new strategy interface: JsonObjectMapper. This abstraction lets multiple implementations of JSON mappers be used. Implementations that wrap Boon and Jackson 2 are provided, with the version being detected on the classpath. These classes are BoonJsonObjectMapper and Jackson2JsonObjectMapper, respectively.

Note, BoonJsonObjectMapper was added in version 4.1.

[Important]Important

If you have requirements to use both Jackson and 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 selects Jackson 2 by default, preferring it to the Boon implementation if both are on the classpath. Jackson 1.x is no longer supported by the framework internally. However, you can still use it within your code by including the necessary library. To avoid unexpected issues with JSON mapping features when you use annotations, you may need to apply annotations from both Jackson and Boon on domain classes, as the following example shows:

@org.codehaus.jackson.annotate.JsonIgnoreProperties(ignoreUnknown=true)
@com.fasterxml.jackson.annotation.JsonIgnoreProperties(ignoreUnknown=true)
@org.boon.json.annotations.JsonIgnoreProperties("thing1")
public class Thing1 {

        @org.codehaus.jackson.annotate.JsonProperty("thing1Thing2")
        @com.fasterxml.jackson.annotation.JsonProperty("thing1Thing2")
        @org.boon.json.annotations.JsonProperty("thing1Thing2")
        public Object thing2;

}

You may wish to consider using a FactoryBean or a factory method to create the JsonObjectMapper with the required characteristics. The following example shows how to use such a factory:

public class ObjectMapperFactory {

    public static Jackson2JsonObjectMapper getMapper() {
        ObjectMapper mapper = new ObjectMapper();
        mapper.configure(JsonParser.Feature.ALLOW_COMMENTS, true);
        return new Jackson2JsonObjectMapper(mapper);
    }
}

The following example shows how to do the same thing in XML

<bean id="customObjectMapper" class="something.ObjectMapperFactory"
            factory-method="getMapper"/>
[Important]Important

Beginning with version 2.2, the object-to-json-transformer sets the content-type header to application/json, by default, if the input message does not already have that header.

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 (""). Doing so results 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:

  • ...->amqp-outbound-adapter---->
  • ---->amqp-inbound-adapter->json-to-object-transformer->...

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

  • ...->object-to-json-transformer->amqp-outbound-adapter---->
  • ---->amqp-inbound-adapter->...

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

  • ...->object-to-json-transformer->amqp-outbound-adapter---->
  • ---->amqp-inbound-adapter->json-to-object-transformer->

    Where both adapters are configured with a SimpleMessageConverter.

[Note]Note

When using the headers to determine the type, you should not provide a class attribute, because it takes precedence over the headers.

In addition to JSON Transformers, Spring Integration provides a built-in #jsonPath SpEL function for use in expressions. For more information see Appendix A, Spring Expression Language (SpEL).

Since version 3.0, Spring Integration also provides a built-in #xpath SpEL function for use in expressions. For more information see Section 38.8, “#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.3, “Property Accessors” for more information. When using Boon, the NODE representation is a Map<String, Object>

Beginning with version 5.1, the resultType can be configured as BYTES to produce a message with the byte[] payload for convenience when working with downstream handlers which operate with this data type.

9.1.4 Configuring a Transformer with Annotations

You can add the @Transformer annotation to methods that expect either the Message type or the message payload type. The return value is handled in the exact same way as described earlier in the section describing the <transformer> element. The following example shows how to use the @Transformer annotation to transform a String into an Order:

@Transformer
Order generateOrder(String productId) {
    return new Order(productId);
}

Transformer methods can also accept the @Header and @Headers annotations, as documented in <<annotations>>. The following examples shows how to use the @Header annotation:

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

See also Section 10.9.7, “Advising Endpoints Using Annotations”.

9.1.5 Header Filter

Sometimes, your transformation use case might be as simple as removing a few headers. For such a use case, Spring Integration provides a header filter that lets you specify certain header names that should be removed from the output message (for example, removing headers for security reasons or a value that was needed only temporarily). Basically, the header filter is the opposite of the header enricher. The latter is discussed in Section 9.2.1, “Header Enricher”. The following example defines a header filter:

<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 and output channels and a header-names attribute. That attribute accepts the names of the headers (delimited by commas if there are multiple) that need to be removed. So, in the preceding example, the headers named lastName and state are not present on the outbound message.

9.1.6 Codec-Based Transformers

See Section 9.4, “Codec”.

9.2 Content Enricher

At times, you may have a requirement to enhance a request with more information than was provided by the target system. The data enricher pattern describes various scenarios as well as the component (Enricher) that lets you address such requirements.

The Spring Integration Core module includes two enrichers:

It also includes three adapter-specific header enrichers:

See the adapter-specific sections of this reference manual to learn more about those adapters.

For more information regarding expressions support, see Appendix A, Spring Expression Language (SpEL).

9.2.1 Header Enricher

If you need do nothing more than add headers to a message and the headers are not dynamically determined by the message content, 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 through the <header-enricher> element. The following example shows how to use it:

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

The header enricher also provides helpful sub-elements to set well known header names, as the following example shows:

<int:header-enricher input-channel="in" output-channel="out">
    <int:error-channel ref="applicationErrorChannel"/>
    <int:reply-channel ref="quoteReplyChannel"/>
    <int:correlation-id value="123"/>
    <int:priority value="HIGHEST"/>
    <routing-slip value="channel1; routingSlipRoutingStrategy; request.headers[myRoutingSlipChannel]"/>
    <int:header name="bar" ref="someBean"/>
</int:header-enricher>

The preceding configuration shows that, for well known headers (such as errorChannel, correlationId, priority, replyChannel, routing-slip, and others), 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 a 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 the header enricher lets you also specify a bean reference by using the ref and method attributes. The specified method calculates the header value. Consider the following configuration and a bean with a method that modifies a String:

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

<bean id="myBean" class="thing1.thing2.MyBean"/>
public class MyBean {

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

You can also configure your POJO as an inner bean, as the following example shows:

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

You can similarly point to a Groovy script, as the following example shows:

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

SpEL Support

In Spring Integration 2.0, we introduced the convenience of the Spring Expression Language (SpEL) to help configure many different components. The header enricher is one of them. Look again at the POJO example shown earlier. You can see that the computation logic to determine the header value is pretty simple. A natural question would be: "Is there an even simpler way to accomplish this?". That is where SpEL shows its true power. Consider the following example:

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

By using SpEL for such simple cases, you no longer have to provide a separate class and configure it in the application context. All you need do is configured the expression attribute 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 two examples show how to use Java Configuration for header enrichers:

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

@Bean
@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()");
    headersToAdd.put("from",
               new ExpressionEvaluatingHeaderValueMessageProcessor<>(expression, String.class));
    HeaderEnricher enricher = new HeaderEnricher(headersToAdd);
    return enricher;
}

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

Configuring a Header Enricher with the Java DSL

The following example shows Java DSL Configuration for a header enricher:

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

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 new sub-element converts existing replyChannel and errorChannel headers (when they are a MessageChannel) to a String and stores the channels 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.

Using 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 behavior, define a bean with an id of integrationHeaderChannelRegistry and configure the required default delay by using a constructor argument (in milliseconds).

Since version 4.1, you can set a property called removeOnGet to true on the <bean/> definition, and the mapping entry is 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:

"@integrationHeaderChannelRegistry.runReaper()"

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

<int:reply-channel
    expression="@integrationHeaderChannelRegistry.channelToChannelName(headers.replyChannel)"
    overwrite="true" />
<int:error-channel
    expression="@integrationHeaderChannelRegistry.channelToChannelName(headers.errorChannel)"
    overwrite="true" />

Starting with version 4.1, you can now override the registry’s configured reaper delay so that the the channel mapping is retained for at least the specified time, regardless of the reaper delay. The following example shows how to do so:

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

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

In the first case, the time to live for every header channel mapping will be two minutes. In the second case, the time to live is specified in the message header and uses an Elvis operator to use two minutes if there is no header.

9.2.2 Payload Enricher

In certain situations, the header enricher, as discussed earlier, 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.

Spring Integration 2.1 introduced the payload enricher. The 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 through the enricher element. In order to send request messages, the payload enricher has a request-channel attribute that lets you dispatch messages to a request channel.

Basically, by defining the request channel, the payload enricher acts as a gateway, waiting for the message sent to the request channel to return. 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 send only a subset of the original payload by using the request-payload-expression attribute.

The enriching of payloads is configured through SpEL expressions, providing a maximum degree of flexibility. Therefore, you can not only enrich payloads with direct values from the reply channel’s Message, but you can use SpEL expressions to extract a subset from that message or to apply additional inline transformations, letting you further manipulate the data.

If you need only to enrich payloads with static values, you need not provide the request-channel attribute.

[Note]Note

Enrichers are a variant of transformers. In many cases, you could use a payload enricher or a generic transformer implementation to add additional data to your message payloads. You should 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.

Configuration

The following example shows all available configuration options 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=""/>
</int:enricher>

1

Channel to which a message is sent to get the data to use for enrichment. Optional.

2

Lifecycle attribute signaling whether this component should be started during the application context startup. Defaults to true. Optional.

3

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

4

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

5

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

6

By default, the original message’s payload is used as payload that is sent to the request-channel. By specifying a SpEL expression as the value for the request-payload-expression attribute, you can use a subset of the original payload, a header value, or any other resolvable SpEL expression as the basis for the payload that is 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.something
  • headers.something
  • new java.util.Date()
  • 'thing1' + 'thing2'

7

Channel where a reply message is expected. This is optional. Typically, the auto-generated temporary reply channel suffices. Optional.

8

The channel to which an ErrorMessage is sent if an Exception occurs downstream of the request-channel. This enables you to return an alternative object to use for enrichment. If it is not set, an Exception is thrown to the caller. Optional.

9

Maximum amount of time in milliseconds to wait when sending a message to the channel, if the channel might 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 can cause the send operation on the MessageChannel, depending on the implementation, to block indefinitely. Optional.

10

Boolean value indicating whether any payload that implements Cloneable should be cloned prior to sending the message to the request channel for acquiring the enriching data. The cloned version would be used as the target payload for the ultimate reply. The default is false. Optional.

11

Lets you configure a message poller if this endpoint is a polling consumer. Optional.

12

Each property sub-element provides the name of a property (through 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 version 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 coerces the value appropriately (as long as a PropertyEditor) exists to handle the conversion. If, however, the target payload is a Map, the entry is populated with the value without conversion. The type attribute lets you, for example, convert a String containing a number to an Integer value in the target payload. Starting with version 4.1, you can also specify an optional null-result-expression attribute. When the enricher returns null, it is evaluated, and the output of the evaluation is returned instead.

13

Each header sub-element provides the name of a message header (through the mandatory name attribute). Exactly one of the value or expression attributes must also be provided — 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 that, similarly to the <header-enricher>, the <enricher> element’s header element has type and overwrite attributes. However, a key difference is that, with the <enricher>, the overwrite attribute is true by default, to be consistent with the <enricher> element’s <property> sub-element. Starting with version 4.1, you can also specify an optional null-result-expression attribute. When the enricher returns null, it is evaluated, and the output of the evaluation is returned instead.

Examples

This section contains several examples of using a payload enricher in various situations.

[Tip]Tip

The code samples shown here are part of the Spring Integration Samples project. See Appendix G, Spring Integration Samples.

In the following example, a User object is passed as the payload of the Message:

<int:enricher id="findUserEnricher"
              input-channel="findUserEnricherChannel"
              request-channel="findUserServiceChannel">
    <int:property name="email"    expression="payload.email"/>
    <int:property name="password" expression="payload.password"/>
</int:enricher>

The User has several properties, but only the username is set initially. The enricher’s request-channel attribute is configured to pass the User to the findUserServiceChannel.

Through the implicitly set reply-channel, a User object is returned and, by using the property sub-element, properties from the reply are extracted and used to enrich the original payload.

How Do I Pass Only a Subset of Data to the Request Channel?

When using a request-payload-expression attribute, a single property of the payload instead of the full message can be passed on to the request channel. In the following example, the username property is passed on to the request channel:

<int:enricher id="findUserByUsernameEnricher"
              input-channel="findUserByUsernameEnricherChannel"
              request-channel="findUserByUsernameServiceChannel"
              request-payload-expression="payload.username">
    <int:property name="email"    expression="payload.email"/>
    <int:property name="password" expression="payload.password"/>
</int:enricher>

Keep in mind that, although only the username is passed, the resulting message to the request channel contains the full set of MessageHeaders.

How Can I Enrich Payloads that Consist of Collection Data?

In the following example, instead of a User object, a Map is passed in:

<int:enricher id="findUserWithMapEnricher"
              input-channel="findUserWithMapEnricherChannel"
              request-channel="findUserByUsernameServiceChannel"
              request-payload-expression="payload.username">
    <int:property name="user" expression="payload"/>
</int:enricher>

The Map contains the username under the username map key. 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.

How Can I Enrich Payloads with Static Information without Using a Request Channel?

The following example does not use a request channel at all but solely enriches the message’s payload with static values:

<int:enricher id="userEnricher"
              input-channel="input">
    <int:property name="user.updateDate" expression="new java.util.Date()"/>
    <int:property name="user.firstName" value="William"/>
    <int:property name="user.lastName"  value="Shakespeare"/>
    <int:property name="user.age"       value="42"/>
</int:enricher>

Note that the word, static, is used loosely here. You can still use SpEL expressions for setting those values.

9.3 Claim Check

In earlier sections, we covered several content enricher components that can 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 store in library (or claim check) pattern describes a mechanism that lets you store data in a well known place while maintaining only a pointer (a claim check) to where that data is located. You can pass that pointer around as the payload of a new message, thereby letting any component within the message flow get the actual data as soon as it needs it. This approach is very similar to the certified mail process, where you get a claim check in your mailbox and then have to go to the post office to claim your actual package. It is also the same idea as baggage claim after 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.

9.3.1 Incoming Claim Check Transformer

An incoming claim check transformer transforms an incoming message by storing it in the message store identified by its message-store attribute. The following example defines an incoming claim check transformer:

<int:claim-check-in id="checkin"
        input-channel="checkinChannel"
        message-store="testMessageStore"
        output-channel="output"/>

In the preceding configuration, the message that is received on the input-channel is persisted to the message store identified with the message-store attribute and indexed with a generated ID. That ID is the claim check for that message. The claim check also becomes the payload of the new (transformed) message that is sent to the output-channel.

Now, assume that at some point you do need access to the actual message. You can access the message store manually and get the contents of the message, or you can use the same approach (creating a transformer) except that now you transform the Claim Check to the actual message by using an outgoing claim check transformer.

The following listing provides 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
</int:claim-check-in>

1

Lifecycle attribute signaling whether this component should be started during application context startup. It defaults to true. This attribute is not available inside a Chain element. Optional.

2

ID identifying the underlying bean definition (MessageTransformingHandler). This attribute is not available inside a Chain element. Optional.

3

The receiving message channel of this endpoint. This attribute is not available inside a Chain element. Optional.

4

Reference to the MessageStore to be used by this claim check transformer. If not specified, the default reference is to a bean named messageStore. Optional.

5

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

6

Identifies the message channel where the message is sent after being processed by this endpoint. This attribute is not available inside a Chain element. Optional.

7

Specifies the maximum amount of time (in milliseconds) to wait when sending a reply message to the output channel. Defaults to -1 — blocking indefinitely. This attribute is not available inside a Chain element. Optional.

8

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

9.3.2 Outgoing Claim Check Transformer

An outgoing claim check transformer lets you transform a message with a claim check payload into a message with the original content as its payload.

<int:claim-check-out id="checkout"
        input-channel="checkoutChannel"
        message-store="testMessageStore"
        output-channel="output"/>

In the preceding configuration, the message received on the input-channel should have a claim check as its payload. The outgoing claim check transformer transforms it into a message with the original payload by 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.

The following listing provides 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
</int:claim-check-out>

1

Lifecycle attribute signaling whether this component should be started during application context startup. It defaults to true. This attribute is not available inside a Chain element. Optional.

2

ID identifying the underlying bean definition (MessageTransformingHandler). This attribute is not available inside a Chain element. Optional.

3

The receiving message channel of this endpoint. This attribute is not available inside a Chain element. Optional.

4

Reference to the MessageStore to be used by this claim check transformer. If not specified, the default reference is to a bean named messageStore. Optional.

5

Specifies the order for invocation when this endpoint is connected as a subscriber to a channel. This is particularly relevant when that channel is using a failover dispatching strategy. It has no effect when this endpoint is itself a polling consumer for a channel with a queue. This attribute is not available inside a Chain element. Optional.

6

Identifies the message channel where the message is sent after being processed by this endpoint. This attribute is not available inside a Chain element. Optional.

7

If set to true, the message is removed from the MessageStore by this transformer. This setting is useful when Message can be "claimed" only once. It defaults to false. Optional.

8

Specifies the maximum amount of time (in milliseconds) to wait when sending a reply message to the output channel. It defaults to -1 — blocking indefinitely. This attribute is not available inside a Chain element. Optional.

9

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

9.3.3 Claim Once

Sometimes, a particular message must be claimed only once. As an analogy, consider process of handling airplane luggage. You checking in your luggage on departure and claiming it on arrival. 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 is removed from the MessageStore so that it cannot be claimed again.

This feature has an impact in terms of storage space, especially in the case of the in-memory Map-based SimpleMessageStore, where failing to remove messages could ultimately lead to an OutOfMemoryException. Therefore, if you do not expect multiple claims to be made, we recommend that you set the remove-message attribute’s value to true. The following example show how to use the remove-message attribute:

<int:claim-check-out id="checkout"
        input-channel="checkoutChannel"
        message-store="testMessageStore"
        output-channel="output"
        remove-message="true"/>

9.3.4 A Word on Message Store

Although we rarely care about the details of the claim checks (as long as they work), you should know that the current implementation of the actual claim check (the pointer) in Spring Integration uses 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)
  • JdbcMessageStore: An implementation that uses a relational database over JDBC

9.4 Codec

Version 4.2 of Spring Integration introduced the Codec abstraction. Codecs encode and decode objects to and from byte[]. They offer an alternative to Java serialization. One advantage is that, typically, objects need not implement Serializable. We provide one implementation that uses Kryo for serialization, but you can provide your own implementation for use in any of the following components:

  • EncodingPayloadTransformer
  • DecodingTransformer
  • CodecMessageConverter

9.4.1 EncodingPayloadTransformer

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

See the Javadoc for more information.

9.4.2 DecodingTransformer

This transformer decodes a byte[] by 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 are not retained.

See the Javadoc for more information.

9.4.3 CodecMessageConverter

Certain endpoints (such as TCP and 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 or from a byte[] for transmission.

See the Javadoc for more information.

9.4.4 Kryo

Currently, this is the only implementation of Codec, and it provides two kinds of Codec:

  • PojoCodec: Used in the transformers
  • MessageCodec: Used in the CodecMessageConverter

The framework provides several custom serializers:

  • 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. 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. The following example shows such a serializer:

public class AddressSerializer extends Serializer<Address> {

    @Override
    public void write(Kryo kryo, Output output, Address address) {
        output.writeString(address.getStreet());
        output.writeString(address.getCity());
        output.writeString(address.getCountry());
    }

    @Override
    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 Kryo documentation.

[Note]Note

When registering your custom serializer, you need a registration ID. The registration IDs are arbitrary. However, in our case, the IDs 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 earlier). We recommend you start at 60, to allow for expansion in the framework. You can override these framework defaults by configuring the registrars mentioned earlier.

Using a Custom Kryo Serializer

If you need custom serialization, see the Kryo documentation, because you need to use the native API to do the customization. For an example, see the MessageCodec implementation.

Implementing KryoSerializable

If you have write access to the domain object source code, you can implement KryoSerializable as described here. In this case, the class provides the serialization methods itself and no further configuration is required. However benchmarks have shown this is not quite as efficient as registering a custom serializer explicitly. The following example shows a custom Kryo serializer:

public class Address implements KryoSerializable {
    ...

    @Override
    public void write(Kryo kryo, Output output) {
        output.writeString(this.street);
        output.writeString(this.city);
        output.writeString(this.country);
    }

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

You can also use this technique to wrap a serialization library other than Kryo.

Using the @DefaultSerializer Annotation

Kryo also provides a @DefaultSerializer annotation, as described here.

@DefaultSerializer(SomeClassSerializer.class)
public class SomeClass {
       // ...
}

If you have write access to the domain object, this may be a simpler way to specify a custom serializer. Note that this does not register the class with an ID, which may make the technique unhelpful for certain situations.

10. Messaging Endpoints

10.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 goes on behind the scenes. However, if you want to get up and running with the simplified namespace-based configuration of the various elements, feel free to skip ahead to Section 10.1.4, “Endpoint 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, we cover 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 earlier in Section 6.1, “Message Channels”, you can 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 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 threads. Spring Integration provides two different endpoint implementations to accommodate these two types of consumers. Therefore, the consumers themselves need only 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 Spring-managed objects running within an ApplicationContext, it more closely resembles Spring’s own MessageListener containers.

10.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 you would not typically implement MessageHandler directly. Nevertheless, it is used by a message consumer for actually handling the consumed messages, 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 interface provides the foundation for most of the components (routers, transformers, splitters, aggregators, service activators, and others) covered in the following chapters. 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 let them be connected to message channels.

10.1.2 Event-driven Consumer

Because it is the simpler of the two, we 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). The following listing shows the definition of the subscribe method:

subscribableChannel.subscribe(messageHandler);

Since a handler that is subscribed to a channel does not have to actively poll that channel, this is an event-driven consumer, and the implementation provided by Spring Integration accepts a SubscribableChannel and a MessageHandler, as the following example shows:

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

EventDrivenConsumer consumer = new EventDrivenConsumer(channel, exampleHandler);

10.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, as the following example shows:

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

PollingConsumer consumer = new PollingConsumer(channel, exampleHandler);
[Note]Note

For more information regarding polling consumers, see Section 6.2, “Poller” and Section 6.3, “Channel Adapter”.

There are many other configuration options for the polling consumer. For example, the trigger is a required property. The following example shows how to set the trigger:

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 — that is, no fixed delay). The following example sets both properties:

IntervalTrigger trigger = new IntervalTrigger(1000);
trigger.setInitialDelay(5000);
trigger.setFixedRate(true);

The result of the three settings in the preceding example is a trigger that waits five seconds and then triggers every second.

The CronTrigger requires a valid cron expression. See the Javadoc for details. The following example sets a new CronTrigger:

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

The result of the trigger defined in the previous example is a trigger that triggers every ten seconds, Monday through Friday.

In addition to the trigger, you can specify two other polling-related configuration properties: maxMessagesPerPoll and receiveTimeout. The following example shows how to set these two properties:

PollingConsumer consumer = new PollingConsumer(channel, handler);

consumer.setMaxMessagesPerPoll(10);
consumer.setReceiveTimeout(5000);

The maxMessagesPerPoll property specifies the maximum number of messages to receive within a given poll operation. This means that the poller continues calling receive() without waiting, until either null is returned or the maximum value is reached. For example, if a poller has a ten-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 ten 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 never misses a message by more than 50 milliseconds. The difference is that the second option requires a thread to wait. However, as a result, it can 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 can also delegate to a Spring TaskExecutor, as the following example shows:

PollingConsumer consumer = new PollingConsumer(channel, handler);

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

Furthermore, a PollingConsumer has a property called adviceChain. This property lets 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, see the sections on AOP advice chains and transaction support under Section 10.1.4, “Endpoint Namespace Support”.

The earlier examples show dependency lookups. However, keep in mind that these consumers are most often 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. Also, Spring Integration has full XML namespace support to even further hide those details. The namespace-based configuration is in this guide featured as each component type is introduced.

[Note]Note

Many of the MessageHandler implementations can generate reply messages. As mentioned earlier, sending messages is trivial when compared to receiving messages. 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 can generate multiple replies for each message it handles. When using the namespace configuration, you do not strictly need to know all of the details. However, it still might be worth knowing that several of these components share a common base class, the AbstractReplyProducingMessageHandler, and that it provides a setOutputChannel(..) method.

10.1.4 Endpoint Namespace Support

Throughout this reference manual, you can find specific configuration examples for endpoint elements, such as router, transformer, service-activator, and so on. Most of these support an input-channel attribute and many 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, the polling behavior is based on the endpoint element’s poller sub-element and its attributes.

The following listing lists all of the available configuration options for a poller:

<int:poller cron=""                                  1
            default="false"                          2
            error-channel=""                         3
            fixed-delay=""                           4
            fixed-rate=""                            5
            id=""                                    6
            max-messages-per-poll=""                 7
            receive-timeout=""                       8
            ref=""                                   9
            task-executor=""                         10
            time-unit="MILLISECONDS"                 11
            trigger="">                              12
            <int:advice-chain />                     13
            <int:transactional />                    14
</int:poller>

1

Provides the ability to configure pollers by 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, and ref.

2

By setting this attribute to true, you can define exactly one 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 an explicitly configured poller then uses the global default poller. It defaults to false. Optional.

3

Identifies the channel to which error messages are sent if a failure occurs in this poller’s invocation. To completely suppress exceptions, you can provide a reference to the nullChannel. Optional.

4

The fixed delay trigger uses a PeriodicTrigger under the covers. If you do not use the time-unit attribute, the specified value is represented in milliseconds. If this attribute is set, none of the following attributes must be specified: fixed-rate, trigger, cron, and ref.

5

The fixed rate trigger uses a PeriodicTrigger under the covers. If you do not use the time-unit attribute, the specified value is represented in milliseconds. If this attribute is set, none of the following attributes must be specified: fixed-delay, trigger, cron, and ref.

6

The ID referring to the poller’s underlying bean-definition, which is of type org.springframework.integration.scheduling.PollerMetadata. The id attribute is required for a top-level poller element, unless it is the default poller (default="true").

7

See Section 6.3.1, “Configuring An Inbound Channel Adapter” for more information. If not specified, the default value depends on the context. If you use a PollingConsumer, this attribute defaults to -1. However, if you use a SourcePollingChannelAdapter, the max-messages-per-poll attribute defaults to 1. Optional.

8

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

9

Bean reference to another top-level poller. The ref attribute must not be present on the top-level poller element. However, if this attribute is set, none of the following attributes must be specified: fixed-rate, trigger, cron, and fixed-delay.

10

Provides the ability to reference a custom task executor. See the section called “TaskExecutor Support” for further information. Optional.

11

This attribute specifies the java.util.concurrent.TimeUnit enum value on the underlying org.springframework.scheduling.support.PeriodicTrigger. Therefore, this attribute can be used only in combination with the fixed-delay or fixed-rate attributes. If combined with either cron or a trigger reference attribute, it causes 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, any fixed-delay or fixed-rate value is interpreted as milliseconds. Basically, this enum provides a convenience for seconds-based interval trigger values. For hourly, daily, and monthly settings, we recommend using a cron trigger instead.

12

Reference to any Spring-configured bean that implements the org.springframework.scheduling.Trigger interface. However, if this attribute is set, none of the following attributes must be specified: fixed-delay, fixed-rate, cron, and ref. Optional.

13

Allows specifying extra AOP advices to handle additional cross-cutting concerns. See the section called “Transaction Support” for further information. Optional.

14

Pollers can be made transactional. See the section called “AOP Advice chains” for further information. Optional.

Examples

A simple interval-based poller with a 1-second interval can be configured as follows:

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

As an alternative to using the fixed-rate attribute, you can also use the fixed-delay attribute.

For a poller based on a Cron expression, use the cron attribute instead, as the following example shows:

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

If the input channel is a PollableChannel, the poller configuration is required. Specifically, as mentioned earlier, 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 may 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 attribute is required, as the following example shows:

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

<int:transformer input-channel="pollable"
    ref="transformer"
    output-channel="output">
    <int:poller ref="weekdayPoller"/>
</int:transformer>
[Note]Note

The ref attribute is allowed only on the inner poller definitions. Defining this attribute on a top-level poller results in a configuration exception being thrown during initialization of the application context.

Global Default Pollers

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 set to 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 uses that default. The following example shows such a poller and a transformer that uses it:

<int:poller id="defaultPoller" default="true" max-messages-per-poll="5" fixed-rate="3000"/>

<!-- No <poller/> sub-element is necessary, because there is a default -->
<int:transformer input-channel="pollable"
                 ref="transformer"
                 output-channel="output"/>
Transaction Support

Spring Integration also provides transaction support for the pollers so that each receive-and-forward operation can be performed as an atomic unit of work. To configure transactions for a poller, add the <transactional/> sub-element. The following example shows the available attributes:

<int:poller fixed-delay="1000">
    <int:transactional transaction-manager="txManager"
                       propagation="REQUIRED"
                       isolation="REPEATABLE_READ"
                       timeout="10000"
                       read-only="false"/>
</int:poller>

For more information, see 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, you must sometimes provide extra advices to handle other cross cutting behavior associated with the poller. For that, the poller defines an advice-chain element that lets you add more advices in a class that implements the MethodInterceptor interface. The following example shows how to define an advice-chain for a poller:

<int:service-activator id="advicedSa" input-channel="goodInputWithAdvice" ref="testBean"
		method="good" output-channel="output">
	<int:poller max-messages-per-poll="1" fixed-rate="10000">
		 <int:advice-chain>
			<ref bean="adviceA" />
			<beans:bean class="org.something.SampleAdvice" />
			<ref bean="txAdvice" />
		</int:advice-chain>
	</int:poller>
</int:service-activator>

For more information on how to implement the MethodInterceptor interface, see the AOP sections of the Spring Framework Reference Guide. An advice chain can also be applied on a poller that does not have any transaction configuration, letting you enhance the behavior of the message flow initiated by the poller.

[Important]Important

When using an advice chain, the <transactional/> child element cannot be specified. Instead, declare a <tx:advice/> bean and add it to the <advice-chain/>. See Section C.1.1, “Poller Transaction Support” for complete configuration details.

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, the core Spring Framework has a task namespace, 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 for each 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 in the following example:

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

<task:executor id="pool"
               pool-size="5-25"
               queue-capacity="20"
               keep-alive="120"/>

If you do not provide a task-executor, the consumer’s handler is invoked in the caller’s thread. Note that the caller is usually the default TaskScheduler (see Section E.2, “Configuring the Task Scheduler”). You should 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 shown earlier is provided for convenience.

As mentioned earlier in the background section for polling consumers, 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 applies only 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 used 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 shows how a polling consumer can receive messages nearly instantaneously:

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

</int:service-activator>

Using this approach does not carry much overhead, since, internally, it is nothing more then a timed-wait thread, which does not require nearly as much CPU resource usage as (for example) a thrashing, infinite while loop.

10.1.5 Changing Polling Rate at Runtime

When configuring a poller with a fixed-delay or a fixed-rate attribute, the default implementation uses a PeriodicTrigger instance. The PeriodicTrigger is part of the core Spring Framework. It accepts the interval only as a constructor argument. 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 can even embed your own throttling logic within the trigger itself. The period property is 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 by using the trigger attribute, which references the custom trigger bean instance. You can now obtain a reference to the trigger bean and change the polling interval between polls.

For an example, 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 that 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, letting you dynamically change the polling period at runtime.

[Note]Note

It is important to note, though, that because the Trigger method is nextExecutionTime(), any changes to a dynamic trigger do not take effect until the next poll, based on the existing configuration. It is not possible to force a trigger to fire before its currently configured next execution time.

10.1.6 Payload Type Conversion

Throughout this reference manual, you can also see specific configuration and implementation examples of various endpoints that accept a message or any arbitrary Object as an input parameter. In the case of an Object, such a parameter is mapped to a message payload or part of the payload or header (when using the Spring Expression Language). However, the type of input parameter of the endpoint method sometimes 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 (by using the Spring 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 by using the Spring Integration infrastructure. To register a converter, you can 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 can 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 called Something that is the target of your conversion (parameter type, channel data type, and so on), you have two concrete implementations called Thing1 and Thing, and you wish to convert to one or the other based on the input type, the GenericConverter would be a good fit. For more information, see the Javadoc for these interfaces:

When you have implemented your converter, you can register it with convenient namespace support, as the following example shows:

<int:converter ref="sampleConverter"/>

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

Alternately, you can use an inner bean, as the following example shows:

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

Starting with Spring Integration 4.0, you can use annotations to create the preceding configuration, as the following example shows:

@Component
@IntegrationConverter
public class TestConverter implements Converter<Boolean, Number> {

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

}

Alternately, you can use the @Configuration annotation, as the following example shows:

@Configuration
@EnableIntegration
public class ContextConfiguration {

	@Bean
	@IntegrationConverter
	public SerializingConverter serializingConverter() {
		return new SerializingConverter();
	}

}
[Important]Important

When configuring an application context, the Spring Framework lets you 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 arguments and properties may produce unintended results if used at runtime for Spring Integration expression evaluation against messages within data type channels, payload type transformers, and so on.

However, if you do want to use the Spring conversionService as the Spring Integration integrationConversionService, you can configure an alias in the application context, as the following example shows:

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

In this case, the converters provided by the conversionService are available for Spring Integration runtime conversion.

10.1.7 Content Type Conversion

Starting with version 5.0, by default, the method invocation mechanism is based on the org.springframework.messaging.handler.invocation.InvocableHandlerMethod infrastructure. Its HandlerMethodArgumentResolver implementations (such as PayloadArgumentResolver and MessageMethodArgumentResolver) can use the MessageConverter abstraction to convert an incoming payload to the target method argument type. The conversion can be based on the contentType message header. For this purpose, Spring Integration provides the ConfigurableCompositeMessageConverter, which delegates to a list of registered converters to be invoked until one of them returns a non-null result. By default, this converter provides (in strict order):

See the Javadoc (linked in the preceding list) for more information about their purpose and appropriate contentType values for conversion. The ConfigurableCompositeMessageConverter is used because it can be be supplied with any other MessageConverter implementations, including or excluding the previously mentioned default converters. It can also be registered as an appropriate bean in the application context, overriding the default converter, as the following example shows:

@Bean(name = IntegrationContextUtils.ARGUMENT_RESOLVER_MESSAGE_CONVERTER_BEAN_NAME)
public ConfigurableCompositeMessageConverter compositeMessageConverter() {
    List<MessageConverter> converters =
        Arrays.asList(new MarshallingMessageConverter(jaxb2Marshaller()),
                 new JavaSerializationMessageConverter());
    return new ConfigurableCompositeMessageConverter(converters);
}

Those two new converters are registered in the composite before the defaults. You can also not use a ConfigurableCompositeMessageConverter but provide your own MessageConverter by registering a bean with the name, integrationArgumentResolverMessageConverter (by setting the IntegrationContextUtils.ARGUMENT_RESOLVER_MESSAGE_CONVERTER_BEAN_NAME property).

[Note]Note

The MessageConverter-based (including contentType header) conversion is not available when using SpEL method invocation. In this case, only the regular class-to-class conversion mentioned above in the Section 10.1.6, “Payload Type Conversion” is available.

10.1.8 Asynchronous Polling

If you want the polling to be asynchronous, a poller can optionally specify a task-executor attribute that points to an existing instance of any TaskExecutor bean (Spring 3.0 provides a convenient namespace configuration through 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. They must be in tune with each other. Otherwise, you might end up creating an artificial memory leak.

Consider the following configuration:

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

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

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

The preceding configuration demonstrates an out-of-tune configuration.

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 five-second timeout, they aree executed at a rate of 4 per second. However, new tasks are being scheduled at a rate of 20 per second, so the internal queue in the task executor grows at a rate of 16 per second (while the process is idle), so we have a memory leak.

One of the ways to handle this is to set the queue-capacity attribute of the task executor. 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 (for example, to DISCARD). In other words, there are certain details you must understand when configuring TaskExecutor. See "Task Execution and Scheduling" in the Spring reference manual for more detail on the subject.

10.1.9 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 instances are registered with the application context with bean IDs similar to someConsumer.handler (where consumer is the value of the endpoint’s id attribute). MessageSource instances are registered with bean IDs similar to somePolledAdapter.source, where somePolledAdapter is the ID of the adapter.

The preceding only applies to the framework component itself. You can instead use an inner bean definition, as the following example shows:

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

The bean is treated like any inner bean declared 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.

10.2 Endpoint Roles

Starting with version 4.2, endpoints can be assigned to roles. Roles let endpoints 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. For this purpose the framework registers a SmartLifecycleRoleController bean in the application context with the name IntegrationContextUtils.INTEGRATION_LIFECYCLE_ROLE_CONTROLLER. Whenever it is necessary to control lifecycles, this bean can be injected or @Autowired:

<bean class="com.some.project.SomeLifecycleControl">
    <property name="roleController" ref="integrationLifecycleRoleController"/>
</bean>

You can assign endpoints to roles using XML, Java configuration, or programmatically. The following example shows how to configure endpoint roles with XML:

<int:inbound-channel-adapter id="ica" channel="someChannel" expression="'foo'" role="cluster"
        auto-startup="false">
    <int:poller fixed-rate="60000" />
</int:inbound-channel-adapter>

The following example shows how to configure endpoint roles for a bean created in Java:

@Bean
@ServiceActivator(inputChannel = "sendAsyncChannel", autoStartup="false")
@Role("cluster")
public MessageHandler sendAsyncHandler() {
    return // some MessageHandler
}

The following example shows how to configure endpoint roles on a method in Java:

@Payload("#args[0].toLowerCase()")
@Role("cluster")
public String handle(String payload) {
    return payload.toUpperCase();
}

The following example shows how to configure endpoint roles by using the SmartLifecycleRoleController in Java:

@Autowired
private SmartLifecycleRoleController roleController;
...
    this.roleController.addSmartLifeCycleToRole("cluster", someEndpoint);
...

The following example shows how to configure endpoint roles by using an IntegrationFlow in Java:

IntegrationFlow flow -> flow
        .handle(..., e -> e.role("cluster"));

Each of these adds the endpoint to the cluster role.

Invoking roleController.startLifecyclesInRole("cluster") and the corresponding stop... method starts and stops the endpoints.

[Note]Note

Any object that implements SmartLifecycle can be programmatically added — not just endpoints.

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

[Important]Important

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

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

1

Returns a list of the roles being managed.

2

Returns true if all endpoints in the role are running.

3

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

4

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

10.3 Leadership Event Handling

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

To participate in a leader election and be notified when elected leader, when leadership is revoked, or on failure to acquire the resources to become leader, an application creates a component in the application context called a "leader initiator". Normally, a leader initiator is a SmartLifecycle, so it starts (optionally) when the context starts and then publishes notifications when leadership changes. You can also receive failure notifications by setting the publishFailedEvents to true (starting with version 5.0), for cases when you want take a specific action if a failure occurs. By convention, you should provide a Candidate that receives the callbacks. You can also revoke the leadership through a Context object provided by the framework. Your code can also listen for o.s.i.leader.event.AbstractLeaderEvent instances (the super class of OnGrantedEvent and OnRevokedEvent) and respond accordingly (for instance, by using a SmartLifecycleRoleController). The events contain a reference to the Context object. The following listing shows the definition of the Context interface:

public interface Context {

	boolean isLeader();

	void yield();

	String getRole();

}

Starting with version 5.0.6, the context provides a reference to the candidate’s role.

Spring Integration provides a basic implementation of a leader initiator that is based on the LockRegistry abstraction. To use it, you need to create an instance as a bean, as the following example shows:

@Bean
public LockRegistryLeaderInitiator leaderInitiator(LockRegistry locks) {
    return new LockRegistryLeaderInitiator(locks);
}

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

See Section 40.3, “Zookeeper Leadership Event Handling” for more information about leadership election and events that use Zookeeper.

10.4 Messaging Gateways

A gateway hides the messaging API provided by Spring Integration. It lets your application’s business logic be unaware of the Spring Integration API. By using a generic Gateway, your code interacts with only a simple interface.

10.4.1 Enter the GatewayProxyFactoryBean

As mentioned earlier, it would be great to have no dependency on the Spring Integration API — including the gateway class. For that reason, Spring Integration provides the GatewayProxyFactoryBean, which generates a proxy for any interface and internally invokes the gateway methods shown below. By using dependency injection, you can then expose the interface to your business methods.

The following example shows an interface that can be used to interact with Spring Integration:

package org.cafeteria;

public interface Cafe {

    void placeOrder(Order order);

}

10.4.2 Gateway XML Namespace Support

Namespace support is also provided. It lets you configure an interface as a service, as the following example shows:

<int:gateway id="cafeService"
         service-interface="org.cafeteria.Cafe"
         default-request-channel="requestChannel"
         default-reply-timeout="10000"
         default-reply-channel="replyChannel"/>

With this configuration defined, the cafeService can now be injected into other beans, and the code that invokes the methods on that proxied instance of the Cafe interface has no awareness of the Spring Integration API. The general approach is similar to that of Spring Remoting (RMI, HttpInvoker, and so on). See the "Samples" Appendix for an example that uses the gateway element (in the Cafe demo).

The defaults in the preceding configuration are applied to all methods on the gateway interface. If a reply timeout is not specified, the calling thread waits indefinitely for a reply. See Section 10.4.11, “Gateway Behavior When No response Arrives”.

The defaults can be overridden for individual methods. See Section 10.4.4, “Gateway Configuration with Annotations and XML”.

10.4.3 Setting the Default Reply Channel

Typically, you need not specify the default-reply-channel, since a Gateway auto-creates a temporary, anonymous reply channel, where it listens for the reply. However, some cases may prompt you to define a default-reply-channel (or reply-channel with adapter gateways, such as HTTP, JMS, and others).

For some background, we briefly discuss some of the inner workings of the gateway. A gateway creates a temporary point-to-point reply channel. It 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 can point to a publish-subscribe channel, which is so named because you can add more than one subscriber to it. Internally, Spring Integration creates a bridge between the temporary replyChannel and the explicitly defined default-reply-channel.

Suppose you want your reply to go not only to the gateway but also to some other consumer. In this case, you want two things:

  • A named channel to which you can subscribe
  • That channel to be a publish-subscribe-channel

The default strategy used by the gateway does 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. By defining a default-reply-channel you can point to a channel of your choosing. In this case, that is a publish-subscribe-channel. The gateway creates a bridge from it to the temporary, anonymous reply channel that is stored in the header.

You might also want to explicitly provide a reply channel for monitoring or auditing through an interceptor (for example, wiretap). To configure a channel interceptor, you need a named channel.

10.4.4 Gateway Configuration with Annotations and XML

Consider the following example, which expands on the previous Cafe interface example by adding a @Gateway annotation:

public interface Cafe {

    @Gateway(requestChannel="orders")
    void placeOrder(Order order);

}

The @Header annotation lets you add values that are interpreted as message headers, as the following example shows:

public interface FileWriter {

    @Gateway(requestChannel="filesOut")
    void write(byte[] content, @Header(FileHeaders.FILENAME) String filename);

}

If you prefer the XML approach to configuring gateway methods, you can add method elements to the gateway configuration, as the following example shows:

<int:gateway id="myGateway" service-interface="org.foo.bar.TestGateway"
      default-request-channel="inputC">
  <int:default-header name="calledMethod" expression="#gatewayMethod.name"/>
  <int:method name="echo" request-channel="inputA" reply-timeout="2" request-timeout="200"/>
  <int:method name="echoUpperCase" request-channel="inputB"/>
  <int:method name="echoViaDefault"/>
</int:gateway>

You can also use XML to provide individual headers for each method invocation. This could be useful if the headers you want to set are static in nature and you do not want to embed them in the gateway’s method signature by using @Header annotations. For example, in the loan broker example, we want to influence how aggregation of the loan quotes is done, based on what type of request was initiated (single quote or all quotes). Determining the type of the request by evaluating which gateway method was invoked, although possible, would violate the separation of concerns paradigm (the method is a Java artifact). However, expressing your intention (meta information) in message headers is natural in a messaging architecture. The following example shows how to add a different message header for each of two methods:

<int:gateway id="loanBrokerGateway"
         service-interface="org.springframework.integration.loanbroker.LoanBrokerGateway">
  <int:method name="getLoanQuote" request-channel="loanBrokerPreProcessingChannel">
    <int:header name="RESPONSE_TYPE" value="BEST"/>
  </int:method>
  <int:method name="getAllLoanQuotes" request-channel="loanBrokerPreProcessingChannel">
    <int:header name="RESPONSE_TYPE" value="ALL"/>
  </int:method>
</int:gateway>

In the preceding example a different value is 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 object (derived from java.reflect.Method) that represents 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 the following expression: #gatewayMethod.name.
[Note]Note

The java.reflect.Method is not serializable. A header with an expression of #gatewayMethod is lost if you later serialize the message. Consequently, 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.

Since version 3.0, <default-header/> elements can be defined to add headers to all the 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 override any @Header annotations in the service interface. However, default headers do NOT override any @Header annotations in the service interface.

The gateway now also supports a default-payload-expression, which is applied for all methods (unless overridden).

10.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 headers). 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. Consider the following example:

public String send1(Object thing1, Map thing2);

public String send2(Map thing1, Map thing2);

In the first case, the convention is to map the first argument to the payload (as long as it is not a Map) and the contents of the second argument become headers.

In the second case (or the first when the argument for parameter thing1 is a Map), the framework cannot determine which argument should be the payload. Consequently, mapping fails. This can generally be resolved using a payload-expression, a @Payload annotation, 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 so, implement an MethodArgsMessageMapper and provide it to the <gateway/> by using the mapper attribute. The mapper maps a MethodArgsHolder, which is a simple class that wraps 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

The following examples show how method arguments can be mapped to the message and shows 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);

    @Payload("@someBean.exclaim(#args[0])")
    void payloadAnnotationAtMethodLevelUsingBeanResolver(String s);

    void payloadAnnotationWithExpression(@Payload("toUpperCase()") String s);

    void payloadAnnotationWithExpressionUsingBeanResolver(@Payload("@someBean.sum(#this)") String s); //  1

    // invalid
    void twoMapsWithoutAnnotations(Map<String, Object> m1, Map<String, Object> m2);

    // invalid
    void twoPayloads(@Payload String s1, @Payload String s2);

    // invalid
    void payloadAndHeaderAnnotationsOnSameParameter(@Payload @Header("x") String s);

    // invalid
    void payloadAndHeadersAnnotationsOnSameParameter(@Payload @Headers Map<String, Object> map);

}

1

Note that, in this example, the SpEL variable, #this, refers to the argument — in this case, the value of s.

The XML equivalent looks a little different, since there is no #this context for the method argument. However, expressions can refer to method arguments by using the #args variable, as the following example shows:

<int:gateway id="myGateway" service-interface="org.something.MyGateway">
  <int:method name="send1" payload-expression="#args[0] + 'thing2'"/>
  <int:method name="send2" payload-expression="@someBean.sum(#args[0])"/>
  <int:method name="send3" payload-expression="#method"/>
  <int:method name="send4">
    <int:header name="thing1" expression="#args[2].toUpperCase()"/>
  </int:method>
</int:gateway>

10.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 pair of examples compares the two approaches for configuring the same gateway:

<int:gateway id="myGateway" service-interface="org.something.TestGateway"
      default-request-channel="inputC">
  <int:default-header name="calledMethod" expression="#gatewayMethod.name"/>
  <int:method name="echo" request-channel="inputA" reply-timeout="2" request-timeout="200"/>
  <int:method name="echoUpperCase" request-channel="inputB">
    <int:header name="thing1" value="thing2"/>
  </int:method>
  <int:method name="echoViaDefault"/>
</int:gateway>
@MessagingGateway(name = "myGateway", defaultRequestChannel = "inputC",
		  defaultHeaders = @GatewayHeader(name = "calledMethod",
		                           expression="#gatewayMethod.name"))
public interface TestGateway {

   @Gateway(requestChannel = "inputA", replyTimeout = 2, requestTimeout = 200)
   String echo(String payload);

   @Gateway(requestChannel = "inputB", headers = @GatewayHeader(name = "thing1", value="thing2"))
   String echoUpperCase(String payload);

   String echoViaDefault(String payload);

}
[Important]Important

Similarly to the XML version, when Spring Integration discovers these annotations during a component scan, it creates the proxy implementation with its messaging infrastructure. To perform this scan and register the BeanDefinition in the application context, add the @IntegrationComponentScan annotation to a @Configuration class. The standard @ComponentScan infrastructure does not deal with interfaces. Consequently, we introduced the custom @IntegrationComponentScan logic to fine the @MessagingGateway annotation on the interfaces and register GatewayProxyFactoryBean instances for them. See also Section E.5, “Annotation Support”.

Along with the @MessagingGateway annotation you can mark a service interface with the @Profile annotation to avoid the bean creation, if such a profile is not active.

[Note]Note

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

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

Sometimes, however, you may want to trigger no-argument methods so that you can interact with other components downstream that do not require user-provided parameters, such as triggering no-argument SQL calls or stored procedures.

To achieve send-and-receive semantics, you must provide a payload. 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 element. The following list includes a few examples of what the payloads could be:

  • a literal string
  • #gatewayMethod.name
  • new java.util.Date()
  • @someBean.someMethod()'s return value

The following example shows how to use 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 is treated as a send-only operation.

10.4.8 Error Handling

The gateway invocation can result in errors. By default, any error that occurs downstream is re-thrown "as is" upon the gateway’s method invocation. For example, consider the following simple flow:

gateway -> service-activator

If the service invoked by the service activator throws a MyException (for example), the framework wraps it in a MessagingException and attaches the message passed to the service activator in the failedMessage property. Consequently, any logging performed by the framework has full the context of the failure. By default, when the exception is caught by the gateway, the MyException is unwrapped and thrown to the caller. You can configure a throws clause on the gateway method declaration to match the particular exception type in the cause chain. For example, if you want to catch a whole MessagingException with all the messaging information of the reason of downstream error, you should have a gateway method similar to the following:

public interface MyGateway {

    void performProcess() throws MessagingException;

}

Since we encourage POJO programming, you may not want to expose the caller to messaging infrastructure.

If your gateway method does not have a throws clause, the gateway traverses the cause tree, looking for a RuntimeException that is not a MessagingException. If none is found, the framework throws the MessagingException. If the MyException in the preceding discussion has a cause of SomeOtherException and your method throws SomeOtherException, the gateway further unwraps that and throws it to the caller.

When a gateway is declared with no service-interface, an internal framework interface RequestReplyExchanger is used.

Consider the following example:

public interface RequestReplyExchanger {

	Message<?> exchange(Message<?> request) throws MessagingException;

}

Before version 5.0, this exchange method did not have a throws clause and, as a result, the exception was unwrapped. If you use this interface and want to restore the previous unwrap behavior, use a custom service-interface instead or access the cause of the MessagingException yourself.

However, you may want to 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 conforms to some "error message" contract that the caller understands). To accomplish this, the gateway provides support for a message channel dedicated to the errors by including support for the error-channel attribute. In the following example, a transformer creates a reply Message from the Exception:

<int:gateway id="sampleGateway"
    default-request-channel="gatewayChannel"
    service-interface="foo.bar.SimpleGateway"
    error-channel="exceptionTransformationChannel"/>

<int:transformer input-channel="exceptionTransformationChannel"
        ref="exceptionTransformer" method="createErrorResponse"/>

The exceptionTransformer could be a simple POJO that knows how to create the expected error response objects. That becomes the payload that is sent back to the caller. 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, nothing would be sent back to the caller. If 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, then the exceptions propagate as usual.

When you use the @MessagingGateway annotation (see <<messaging-gateway-annotation>>), you can use use the errorChannel attribute.

Starting with version 5.0, when you use a gateway method with a void return type (one-way flow), the error-channel reference (if provided) is populated in the standard errorChannel header of each sent message. This feature allows a downstream asynchronous flow, based on the standard ExecutorChannel configuration (or a QueueChannel), to override a default global errorChannel exceptions sending behavior. Previously you had to manually specify an errorChannel header with the @GatewayHeader annotation or the <header> element. The error-channel property was ignored for void methods with an asynchronous flow. Instead, error messages were sent to the default errorChannel.

[Important]Important

Exposing the messaging system through simple POJI Gateways 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 (whether void, a 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 and never reach a component that is responsible for producing a reply. Some service activator method might result in an exception, thus providing no reply (as we do not generate null messages). In other words, multiple scenarios can cause a reply message to never come. 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 is always a reply message. Otherwise, your gateway method might never return and hang indefinitely. One way to handle this situation is by using 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 does not hang any longer than the time specified by the reply-timeout and returns 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 are discussed in more detail in the final section of this chapter.

[Note]Note

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 is sent to the error flow. Otherwise the payload is thrown to the caller of the 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 asynchronous situations when when you need to propagate an Exception directly to the caller. To do so, you can either return an Exception (as the reply from some service) or throw it. Generally, even with an asynchronous flow, the framework takes 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 by using an aggregator with group-timeout (see the section called “Aggregator and Group Timeout”) and a MessagingTimeoutException reply on the discard flow.

10.4.9 Gateway Timeouts

Gateways have two timeout properties: requestTimeout and replyTimeout. The request timeout applies only if the channel can block (for example, a bounded QueueChannel that is full). The replyTimeout value is how long the gateway waits for a reply or returns null. It defaults to infinity.

The timeouts can be set as defaults for all methods on the gateway (defaultRequestTimeout and defaultReplyTimeout) or on the MessagingGateway interface annotation. Individual methods can override these defaults (in <method/> child elements) or on the @Gateway annotation.

Starting with version 5.0, the timeouts can be defined as expressions, as the following example shows:

@Gateway(payloadExpression = "#args[0]", requestChannel = "someChannel",
        requestTimeoutExpression = "#args[1]", replyTimeoutExpression = "#args[2]")
String lateReply(String payload, long requestTimeout, long replyTimeout);

The evaluation context has a BeanResolver (use @someBean to reference other beans), and the #args array variable is available.

When configuring with XML, the timeout attributes can be a long value or a SpEL expression, as the following example shows:

<method name="someMethod" request-channel="someRequestChannel"
                      payload-expression="#args[0]"
                      request-timeout="1000"
                      reply-timeout="#args[1]">
</method>

10.4.10 Asynchronous Gateway

As a pattern, the messaging gateway offers a nice way to hide messaging-specific code while still exposing the full capabilities of the messaging system. As described earlier, the GatewayProxyFactoryBean provides a convenient way to expose a proxy over a service-interface giving you POJO-based access to a messaging system (based on objects in your own domain, primitives/Strings, or other objects). However, when a gateway is exposed through simple POJO methods that return values, it implies 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 are naturally asynchronous, you may not always be able to guarantee the contract where "for each request, there will always be be a reply". Spring Integration 2.0 introduced support for an asynchronous gateway, which offers a convenient way to initiate flows when you may not know if a reply is expected or how long it takes for replies to arrive.

To handle these types of scenarios, Spring Integration uses java.util.concurrent.Future instances to support an asynchronous gateway.

From the XML configuration, nothing changes, and you still define asynchronous gateway the same way as you define a regular gateway, as the following example shows:

<int:gateway id="mathService" 
     service-interface="org.springframework.integration.sample.gateway.futures.MathServiceGateway"
     default-request-channel="requestChannel"/>

However, the gateway interface (a service interface) is a little different, as follows:

public interface MathServiceGateway {

  Future<Integer> multiplyByTwo(int i);

}

As the preceding example shows, 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 asynchronous mode by using an AsyncTaskExecutor. That is the extent of the differences. 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, and so on. Also, as with any other use of Future instances, calling get() may reveal a timeout, an execution exception, and so on. The following example shows how to use a Future that returns from an asynchronous gateway:

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, see the async-gateway sample in the Spring Integration samples.

ListenableFuture

Starting with version 4.1, asynchronous gateway methods can also return ListenableFuture (introduced in Spring Framework 4.0). These return types let you 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 is an AsyncListenableTaskExecutor, the executor’s submitListenable() method is invoked. The following example shows how to use a ListenableFuture:

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

    @Override
    public void onSuccess(String result) {
        ...
    }

    @Override
    public void onFailure(Throwable t) {
        ...
    }
});

AsyncTaskExecutor

By default, the GatewayProxyFactoryBean uses org.springframework.core.task.SimpleAsyncTaskExecutor when submitting internal AsyncInvocationTask instances for any gateway method whose return type is a Future. However, the async-executor attribute in the <gateway/> element’s configuration lets you 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. See the section called “CompletableFuture. 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), as the following example shows:

@Bean
public AsyncTaskExecutor exec() {
    SimpleAsyncTaskExecutor simpleAsyncTaskExecutor = new SimpleAsyncTaskExecutor();
    simpleAsyncTaskExecutor.setThreadNamePrefix("exec-");
    return simpleAsyncTaskExecutor;
}

@MessagingGateway(asyncExecutor = "exec")
public interface ExecGateway {

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

}

If you wish to return a different Future implementation, you can provide a custom executor or disable the executor altogether and return the Future in the reply message payload from the downstream flow. To disable the executor, set it to null in the GatewayProxyFactoryBean (by using setAsyncTaskExecutor(null)). When configuring the gateway with XML, use async-executor="". When configuring by using the @MessagingGateway annotation, use code similar to the following:

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

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

}
[Important]Important

If the return type is a specific concrete Future implementation or some other sub-interface that is not supported by the configured executor, the flow runs on the caller’s thread and the flow must return the required type in the reply message payload.

CompletableFuture

Starting with version 4.2, gateway methods can now return CompletableFuture<?>. There are two 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 runs the task on the executor and immediately returns 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, the downstream flow is expected to return a CompletableFuture of the appropriate type.
Usage Scenarios

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

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

In the following scenario, the caller thread returns 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.

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

In the following scenario, the caller thread returns 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 entry is emitted, indicating that the async executor cannot be used for this scenario.

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

CompletableFuture instances can be used to perform additional manipulation on the reply, as the following example shows:

CompletableFuture<String> process(String data);

...

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

...

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

Reactor Mono

Starting with version 5.0, the GatewayProxyFactoryBean allows the use of Project Reactor with gateway interface methods, using a Mono<T> return type. The internal AsyncInvocationTask is wrapped in a Mono.fromCallable().

A Mono can be used to retrieve the result later (similar to a Future<?>), or you can consume from it with the dispatcher by invoking your Consumer when the result is returned to the gateway.

[Important]Important

The Mono is not immediately flushed by the framework. Consequently, the underlying message flow is not started before the gateway method returns (as it is with a Future<?> Executor task). The flow starts when the Mono is subscribed to. Alternatively, the Mono (being a Composable) might be a part of Reactor stream, when the subscribe() is related to the entire Flux. The following example shows how to create a gateway with Project Reactor:

@MessagingGateway
public static interface TestGateway {

	@Gateway(requestChannel = "promiseChannel")
	Mono<Integer> multiply(Integer value);

	}

	    ...

	@ServiceActivator(inputChannel = "promiseChannel")
	public Integer multiply(Integer value) {
			return value * 2;
	}

		...

    Flux.just("1", "2", "3", "4", "5")
            .map(Integer::parseInt)
            .flatMap(this.testGateway::multiply)
            .collectList()
            .subscribe(integers -> ...);

Another example that uses Project Reactor is a simple callback scenario, as the following example shows:

Mono<Invoice> mono = service.process(myOrder);

mono.subscribe(invoice -> handleInvoice(invoice));

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

Downstream Flows Returning an Asynchronous Type

As mentioned in the ListenableFuture section above, if you wish some downstream component to return a message with an async payload (Future, Mono, and others), you must explicitly set the async executor to null (or "" when using XML configuration). The flow is then invoked on the caller thread and the result can be retrieved later.

void Return Type

Unlike the return types mentioned earlier, when the method return type is void, the framework cannot implicitly determine that you wish the downstream flow to run asynchronously, with the caller thread returning immediately. In this case, you must annotate the interface method with @Async, as the following example shows:

@MessagingGateway
public interface MyGateway {

    @Gateway(requestChannel = "sendAsyncChannel")
    @Async
    void sendAsync(String payload);

}

Unlike the Future<?> return types, there is no way to inform the caller if some exception is thrown by the flow, unless some custom TaskExecutor (such as an ErrorHandlingTaskExecutor) is associated with the @Async annotation.

10.4.11 Gateway Behavior When No response Arrives

As explained earlier, the gateway provides a convenient way of interacting with a messaging system through POJO method invocations. However, 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 (for example, a reply message might not arrive — the equivalent to a method not returning).

The rest of this section covers various scenarios and how to make the gateway behave more predictably. Certain attributes can be configured to make synchronous gateway behavior more predictable, but some of them might not always work as you might expect. One of them is reply-timeout (at the method level or default-reply-timeout at the gateway level). We examine the reply-timeout attribute to see how it can and cannot influence the behavior of the synchronous gateway in various scenarios. We examine a single-threaded scenario (all components downstream are connected through a direct channel) and multi-threaded scenarios (for example, somewhere downstream you may have a pollable or executor channel that breaks the single-thread boundary).

Long-running Process Downstream

Sync Gateway, single-threaded
If a component downstream is still running (perhaps because of an infinite loop or a slow service), setting a reply-timeout has no effect, and the gateway method call does not return until the downstream service exits (by returning or throwing an exception).
Sync Gateway, multi-threaded
If a component downstream is still running (perhaps because of an infinite loop or a slow service) in a multi-threaded message flow, setting the reply-timeout has an effect by allowing gateway method invocation to return once the timeout has been reached, because the GatewayProxyFactoryBean  polls on the reply channel, waiting for a message until the timeout expires. However, if the timeout has been reached before the actual reply was produced, it could result in a null return from the gateway method.  You should understand that the reply message (if produced) is 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 it 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 hangs indefinitely, unless a reply-timeout has been configured or the requires-reply attribute has been set on the downstream component (for example, a service activator) that might return null. In this case, an exception would be thrown and propagated to the gateway.
Sync Gateway — multi-threaded
The behavior is the same as the previous case.

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 hangs indefinitely unless a reply-timeout has been configured.
Sync Gateway — multi-threaded
The behavior is the same as the previous case.

Downstream Component Results in Runtime Exception

Sync Gateway — single-threaded
If a component downstream throws a runtime exception, the exception is propagated through an error message back to the gateway and re-thrown.
Sync Gateway — multi-threaded
The behavior is the same as the previous case.
[Important]Important

You should understand that, by default, reply-timeout is unbounded. Consequently, if you do not explicitly set the reply-timeout, your gateway method invocation might hang indefinitely. So, to make sure you analyze your flow and if there is even a remote possibility of one of these scenarios to occur, you should set the reply-timeout attribute to a "safe" value. Even better, you can 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 returns null internally. However you should also realize that there are some scenarios (see the first one) where reply-timeout does not help. That means it is also important to analyze your message flow and decide when to use a synchronous gateway rather than an asynchrnous gateway. As described earlier, the latter case is a matter of defining gateway methods that return Future instances. Then you are guaranteed to receive that return value, and you 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 results 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 behaves like it contain a service activator with the requires-reply attribute. In other words, it helps to ensure a timely response from the gateway method invocation.

[Note]Note

reply-timeout is unbounded for <gateway/> elements (created by the GatewayProxyFactoryBean). Inbound gateways for external integration (WS, HTTP, and so on) share many characteristics and attributes with these gateways. However, for those inbound gateways, the default reply-timeout is 1000 milliseconds (one second). If a downstream asynchronous hand-off 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.

[Important]Important

You should understand that the timer starts when the thread returns to the gateway — that is, 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 is immediately available. For asynchronous flows, the thread waits for up to this time.

See Section 11.19, “IntegrationFlow as Gateway” in the Java DSL chapter for options to define gateways through IntegrationFlows.

10.5 Service Activator

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. As with most of the configuration options described here, the same behavior actually applies for most of the other components.

10.5.1 Configuring Service Activator

To create a service activator, use the service-activator element with the input-channel and ref attributes, as the following example shows:

<int:service-activator input-channel="exampleChannel" ref="exampleHandler"/>

The preceding configuration selects all the methods from the exampleHandler that meet one of the messaging requirements, which are as follows:

  • annotated with @ServiceActivator
  • is public
  • not return void if requiresReply == true

The target method for invocation at runtime is selected for each request message by their payload type or as a fallback to the Message<?> type if such a method is present on target class.

Starting with version 5.0, one service method can be marked with the @org.springframework.integration.annotation.Default as a fallback for all non-matching cases. This can be useful when using content-type conversion with the target method being invoked after conversion.

To delegate to an explicitly defined method of any object, you can add the method attribute, as the following example shows:

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

In either case, when the service method returns a non-null value, the endpoint tries to send the reply message to an appropriate reply channel. To determine the reply channel, it first checks whether an output-channel was provided in the endpoint configuration, as the following example shows:

<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 then checks the request message’s replyChannel header value. If that value is available, it then checks its type. If it is a MessageChannel, the reply message is sent to that channel. If it is a String, the endpoint tries to resolve the channel name to a channel instance. If the channel cannot be resolved, a DestinationResolutionException is thrown. It it can be resolved, the message is sent there. If the request message does not have a replyChannel header and the reply object is a Message, its replyChannel header is consulted for a target destination. 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 6.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, which is 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 is assumed to be a message payload, which is extracted from the message and injected into the service method. We generally recommend this 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 E.5, “Annotation Support”.

[Note]Note

The service method is not required to have any arguments, which means you can implement event-style service activators (where all you care about is an invocation of the service method) and not worry about the contents of the message. Think of it as a null JMS message. An example use case for such an implementation is a simple counter or monitor of messages deposited on the input channel.

Starting with version 4.1, the framework correctly converts message properties (payload and headers) to the Java 8 Optional POJO method parameters, as the following example shows:

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

}

We generally recommend using a ref attribute 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, as the following example shows:

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

Using both the ref attribute and an inner handler definition in the same <service-activator> configuration is not allowed, as it creates an ambiguous condition and results in an exception being thrown.

[Important]Important

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 get a configuration exception.

Service Activators and the Spring Expression Language (SpEL)

Since Spring Integration 2.0, service activators can also benefit from SpEL.

For example, you can invoke any bean method without pointing to the bean in a ref attribute or including it as an inner bean definition, as follows:

<int:service-activator input-channel="in" output-channel="out"
	expression="@accountService.processAccount(payload, headers.accountId)"/>

	<bean id="accountService" class="thing1.thing2.Account"/>

In the preceding configuration, instead of injecting accountService by using a ref or as an inner bean, we use SpEL’s @beanId notation and invoke a method that takes a type compatible with the message payload. We also pass a header value. Any valid SpEL expression can be evaluated against any content in the message. For simple scenarios, your service activators need not reference a bean if all logic can be encapsulated in such an expression, as the following example shows:

<int:service-activator input-channel="in" output-channel="out" expression="payload * 2"/>

In the preceding configuration, our service logic is to multiply the payload value by two. SpEL lets us handle it relatively easily.

See Section 11.10, “Service Activators and the .handle() method” in the Java DSL chapter for more information about configuring service activator.

10.5.2 Asynchronous Service Activator

The service activator is invoked by the calling thread. This is an 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 (by using setAsync(true) when using Java configuration). If the service returns a ListenableFuture<?> when this the async attribute is set to 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 that use a PollableChannel, because the poller thread is released to perform other services within the framework.

If the service completes the future with an Exception, normal error processing occurs. An ErrorMessage is sent to the errorChannel message header, if present. Otherwise, an ErrorMessage is sent to the default errorChannel (if available).

10.5.3 Service Activator and Method Return Type

The service method can return any type which becomes reply message payload. In this case a new Message<?> object is created and all the headers from a request message are copied. This works the same way for most Spring Integration MessageHandler implementations, when interaction is based on a POJO method invocation.

A complete Message<?> object can also be returned from the method. However keep in mind that, unlike transformers, for a Service Activator this message will be modified by copying the headers from the request message if they are not already present in the returned message. So, if your method parameter is a Message<?> and you copy some, but not all, existing headers in your service method, they will reappear in the reply message. It is not a Service Activator responsibility to remove headers from a reply message and, pursuing the loosely-coupled principle, it is better to add a HeaderFilter in the integration flow. Alternatively, a Transformer can be used instead of a Service Activator but, in that case, when returning a full Message<?> the method is completely responsible for the message, including copying request message headers (if needed). You must ensure that important framework headers (e.g. replyChannel, errorChannel), if present, have to be preserved.

10.6 Delayer

A delayer is a simple endpoint that lets a message flow be delayed by a certain interval. When a message is delayed, the original sender does not block. Instead, the delayed messages are 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 is used for the actual execution of releasing the messages. This section contains several examples of configuring a delayer.

10.6.1 Configuring a 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 the expression element) that determine the number of milliseconds by which each message should be delayed. The following example delays all messages by three seconds:

<int:delayer id="delayer" input-channel="input"
             default-delay="3000" output-channel="output"/>

If you need to determine the delay for each message, you can also provide the SpEL expression by using the expression attribute, as the following expression shows:

<int:delayer id="delayer" input-channel="input" output-channel="output"
             default-delay="3000" expression="headers['delay']"/>

In the preceding example, the three-second delay applies only when the expression evaluates to null for a given inbound message. If you want to apply a delay only to messages that have a valid result of the expression evaluation, you can use a default-delay of 0 (the default). For any message that has a delay of 0 (or less), the message is sent immediately, on the calling thread.

The following example shows the Java configuration equivalent of the preceding example:

@ServiceActivator(inputChannel = "input")
@Bean
public DelayHandler delayer() {
    DelayHandler handler = new DelayHandler("delayer.messageGroupId");
    handler.setDefaultDelay(3_000L);
    handler.setDelayExpressionString("headers['delay']");
    handler.setOutputChannelName("output");
    return handler;
}

The following example shows the Java DSL equivalent of the preceding example:

@Bean
public IntegrationFlow flow() {
    return IntegrationFlows.from("input")
            .delay("delayer.messageGroupId", d -> d
                    .defaultDelay(3_000L)
                    .delayExpression("headers['delay']"))
            .channel("output")
            .get();
}
[Note]Note

The XML parser uses a message group ID of <beanName>.messageGroupId.

[Tip]Tip

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 are counted from the current time (for example a value of 5000 would delay the message for at least five seconds from the time it is received by the delayer). With a Date instance, the message is not released until the time represented by that Date object. A value that equates to a non-positive delay or a Date in the past results in no delay. Instead, it is 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 — the default is 0) is applied.

[Important]Important

The expression evaluation may throw an evaluation exception for various reasons, including an invalid expression or other conditions. By default, such exceptions are ignored (though logged at the 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 earlier. However, if you wish to not ignore expression evaluation exceptions and throw them to the delayer’s caller, set the ignore-expression-failures attribute to false.

[Tip]Tip

In the preceding example, 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 header expression shown earlier can be specified as headers.delay. However, different results are achieved if the header is missing. In the first case, the expression evaluates to null. The second results in something similar to the following:

 org.springframework.expression.spel.SpelEvaluationException: EL1008E:(pos 8):
		   Field or property 'delay' cannot be found on object of type 'org.springframework.messaging.MessageHeaders'

Consequently, 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. See Section E.2, “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, as the following example shows:

<int:delayer id="delayer" input-channel="input" output-channel="output"
    expression="headers.delay"
    scheduler="exampleTaskScheduler"/>

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

If you configure an external ThreadPoolTaskScheduler, you can set waitForTasksToCompleteOnShutdown = true on this property. It allows successful completion of delay tasks that are 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, the delayer requires an external scheduler instance and waitForTasksToCompleteOnShutdown was deleted. You should use the scheduler’s own configuration.

[Tip]Tip

ThreadPoolTaskScheduler has a property errorHandler, which can be injected with some implementation of org.springframework.util.ErrorHandler. This handler allows processing 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 can 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. This error handling is performed after a transaction rolls back (if present). See Section 10.6.3, “Release Failures”.

10.6.2 Delayer and a Message Store

The DelayHandler persists delayed messages into the message group in the provided MessageStore. (The groupId is based on the required id attribute of the <delayer> element.) A delayed message is removed from the MessageStore by the scheduled task immediately before the DelayHandler sends the message to the output-channel. If the provided MessageStore is persistent (such as 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 Date is used when rescheduling. If a delayed message remains in the MessageStore more than its delay, it is sent immediately after startup.

The <delayer> can be enriched with either of two mutually exclusive elements: <transactional> and <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 transaction of the ReleaseMessageHandler is rolled back. In this case, the delayed message remains in the persistent MessageStore. You can use any custom org.aopalliance.aop.Advice implementation within the <advice-chain>. The <transactional> element defines a simple advice chain that has only the transactional advice. The following example shows an advice-chain within a <delayer>:

<int:delayer id="delayer" input-channel="input" output-channel="output"
    expression="headers.delay"
    message-store="jdbcMessageStore">
    <int:advice-chain>
        <beans:ref bean="customAdviceBean"/>
        <tx:advice>
            <tx:attributes>
                <tx:method name="*" read-only="true"/>
            </tx:attributes>
        </tx:advice>
    </int:advice-chain>
</int:delayer>

The DelayHandler can be exported as a JMX MBean with managed operations (getDelayedMessageCount and reschedulePersistedMessages), which allows the rescheduling of delayed persisted messages at runtime — for example, if the TaskScheduler has previously been stopped. These operations can be invoked through a Control Bus command, as the following example shows:

Message<String> delayerReschedulingMessage =
    MessageBuilder.withPayload("@'delayer.handler'.reschedulePersistedMessages()").build();
    controlBusChannel.send(delayerReschedulingMessage);
[Note]Note

For more information regarding the message store, JMX, and the control bus, see Chapter 12, System Management.

10.6.3 Release Failures

Starting with version 5.0.8, there are two new properties on the delayer:

  • maxAttempts (default 5)
  • retryDelay (default 1 second)

When a message is released, if the downstream flow fails, the release will be attempted after the retryDelay. If the maxAttempts is reached, the message is discarded (unless the release is transactional, in which case the message will remain in the store, but will no longer be scheduled for release, until the application is restarted, or the reschedulePersistedMessages() method is invoked, as discussed above).

In addition, you can configure a delayedMessageErrorChannel; when a release fails, an ErrorMessage is sent to that channel with the exception as the payload and has the originalMessage property. The ErrorMessage contains a header IntegrationMessageHeaderAccessor.DELIVERY_ATTEMPT containing the current count.

If the error flow consumes the error message and exits normally, no further action is taken; if the release is transactional, the transaction will commit and the message deleted from the store. If the error flow throws an exception, the release will be retried up to maxAttempts as discussed above.

10.7 Scripting Support

Spring Integration 2.1 added support for the JSR223 Scripting for Java specification, introduced in Java version 6. It lets you 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, see the documentation.

You need to include this dependency into your project:

Maven. 

<dependency>
    <groupId>org.springframework.integration</groupId>
    <artifactId>spring-integration-scripting</artifactId>
    <version>5.1.2.RELEASE</version>
</dependency>

Gradle. 

compile "org.springframework.integration:spring-integration-scripting:5.1.2.RELEASE"

In addition you need to add a script engine implementation, e.g. JRuby, Jython.

[Important]Important

Note that this feature requires Java 6 or higher.

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

[Important]Important

Various JSR223 language implementations have been developed by third parties. A particular implementation’s compatibility with Spring Integration depends on how well it conforms to the specification and the implementer’s interpretation of the specification.

[Tip]Tip

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, this section is relevant as well.

10.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 that contains the script. To enable scripting support, Spring Integration defines a ScriptExecutingMessageProcessor, which binds the message payload to a variable named payload and the message headers to a headers variable, both accessible within the script execution context. All you need to do is write a script that uses these variables. The following pair of examples show sample configurations that create filters:

Example 10.1. Filter

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

<int:filter input-channel="inlineScriptInput">
     <int-script:script lang="groovy">
     <![CDATA[
     return payload == 'good'
   ]]>
  </int-script:script>
</int:filter>

As the preceding examples show, the script can be included inline or can be included by reference to a resource location (by using the location attribute). Additionally, the lang attribute corresponds to the language name (or its JSR223 alias)

Other Spring Integration endpoint elements that 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 do so, specify the refresh-check-delay attribute on the script element, as the following example shows:

<int-script:script location="..." refresh-check-delay="5000"/>

In the preceding example, the script location is checked for updates every 5 seconds. If the script is updated, any invocation that occurs later than 5 seconds since the update results in running the new script.

Consider the following example:

<int-script:script location="..." refresh-check-delay="0"/>

In the preceding example, the context is updated with any script modifications as soon as such modification occurs, providing a simple mechanism for real-time configuration. Any negative value means the script is not reloaded after initialization of the application context. This is the default behavior. The following example shows a script that never updates:

<int-script:script location="..." refresh-check-delay="-1"/>
[Important]Important

Inline scripts can not be reloaded.

Script Variable Bindings

Variable bindings are required to enable the script to reference variables externally provided to the script’s execution context. By default, payload and headers are used as binding variables. You can bind additional variables to a script by using <variable> elements, as the following example shows:

<script:script lang="js" location="foo/bar/MyScript.js">
    <script:variable name="foo" value="thing1"/>
    <script:variable name="bar" value="thing2"/>
    <script:variable name="date" ref="date"/>
</script:script>

As shown in the preceding example, you can bind a script variable either to a scalar value or to a Spring bean reference. Note that payload and headers are still included as binding variables.

With Spring Integration 3.0, in addition to the variable element, the variables attribute has been introduced. This attribute and the variable elements are not 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, as the following example shows:

<service-activator input-channel="input">
    <script:script lang="ruby" variables="thing1=THING1, date-ref=dateBean">
        <script:variable name="thing2" ref="thing2Bean"/>
        <script:variable name="thing3" value="thing2"/>
        <![CDATA[
            payload.foo = thing1
            payload.date = date
            payload.bar = thing2
            payload.baz = thing3
            payload
        ]]>
    </script:script>
</service-activator>

The preceding example shows a combination of an inline script, a variable element, and a variables attribute. The variables attribute contains 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 in the preceding example. That means that the binding variable has the name, date, but the value is 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 that uses the ScriptVariableGenerator strategy, which is defined by the following interface:

public interface ScriptVariableGenerator {

    Map<String, Object> generateScriptVariables(Message<?> message);

}

This interface requires you to implement the generateScriptVariables(Message) method. The message argument lets you access any data available in the message payload and headers, and the return value is the Map of bound variables. This method is called every time the script is executed for a message. The following example shows how to provide an implementation of ScriptVariableGenerator and reference it with the script-variable-generator attribute:

<int-script:script location="foo/bar/MyScript.groovy"
        script-variable-generator="variableGenerator"/>

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

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

[Important]Important

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

10.8 Groovy support

In Spring Integration 2.0, we added Groovy support, letting you 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, see the Groovy documentation, which you can find on the project website.

You need to include this dependency into your project:

Maven. 

<dependency>
    <groupId>org.springframework.integration</groupId>
    <artifactId>spring-integration-groovy</artifactId>
    <version>5.1.2.RELEASE</version>
</dependency>

Gradle. 

compile "org.springframework.integration:spring-integration-groovy:5.1.2.RELEASE"

10.8.1 Groovy Configuration

With Spring Integration 2.1, the configuration namespace for the Groovy support is an extension of Spring Integration’s scripting support and shares the core configuration and behavior described in detail in the Section 10.7, “Scripting Support” section. Even though Groovy scripts are well supported by ge