Spring Integration Reference Manual
		Next

Spring Integration Reference Manual

Authors

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

4.1.4.RELEASE

Copyright © 2009, 2010, 2011, 2012, 2013, 2014, 2015 Pivotal, Inc. All Rights Reserved.

Table of Contents

1. Requirements

1.1. Compatible Java Versions
1.2. Compatible Versions of the Spring Framework

2. Code Conventions

I. What's new?

1. What's new in Spring Integration 4.1?

1.1. New Components

1.1.1. Promise<?> Gateway
1.1.2. WebSocket support
1.1.3. Scatter-Gather EIP pattern
1.1.4. Routing Slip Pattern
1.1.5. Idempotent Receiver Pattern
1.1.6. BoonJsonObjectMapper
1.1.7. Redis Queue Gateways
1.1.8. PollSkipAdvice

1.2. General Changes

1.2.1. AMQP Inbound Endpoints, Channel
1.2.2. AMQP Outbound Endpoints
1.2.3. SimpleMessageStore
1.2.4. Web Service Outbound Gateway: encode-uri
1.2.5. Http Inbound Channel Adapter and StatusCode
1.2.6. MQTT Adapter Changes
1.2.7. FTP/SFTP Adapter Changes
1.2.8. Splitter and Iterator
1.2.9. Aggregator
1.2.10. Content Enricher Improvements
1.2.11. Header Channel Registry
1.2.12. Orderly Shutdown
1.2.13. Management for RecipientListRouter
1.2.14. AbstractHeaderMapper: NON_STANDARD_HEADERS token
1.2.15. AMQP Channels: template-channel-transacted
1.2.16. Syslog Adapter
1.2.17. Async Gateway
1.2.18. Aggregator Advice Chain
1.2.19. Outbound Channel Adapter and Scripts
1.2.20. Resequencer Changes
1.2.21. Optional POJO method parameter
1.2.22. QueueChannel: backed Queue type
1.2.23. ChannelInterceptor Changes
1.2.24. IMAP PEEK

II. Overview of Spring Integration Framework

2. Spring Integration Overview

2.1. Background

2.2. Goals and Principles

2.3. Main Components

2.3.1. Message
2.3.2. Message Channel
2.3.3. Message Endpoint

2.4. Message Endpoints

2.4.1. Transformer
2.4.2. Filter
2.4.3. Router
2.4.4. Splitter
2.4.5. Aggregator
2.4.6. Service Activator
2.4.7. Channel Adapter

2.5. Configuration

2.6. Programming Considerations

III. Core Messaging

3. Messaging Channels

3.1. Message Channels

3.1.1. The MessageChannel Interface

PollableChannel
SubscribableChannel

3.1.2. Message Channel Implementations

PublishSubscribeChannel
QueueChannel
PriorityChannel
RendezvousChannel
DirectChannel
ExecutorChannel
Scoped Channel

3.1.3. Channel Interceptors

3.1.4. MessagingTemplate

3.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
Wire Tap
Global Wire Tap Configuration

3.1.6. Special Channels

3.2. Poller (Polling Consumer)

3.3. Channel Adapter

3.3.1. Configuring An Inbound Channel Adapter
3.3.2. Configuring An Outbound Channel Adapter
3.3.3. Channel Adapter Expressions and Scripts

3.4. Messaging Bridge

3.4.1. Introduction
3.4.2. Configuring Bridge

4. Message Construction

4.1. Message

4.1.1. The Message Interface

4.1.2. Message Headers

MessageHeaderAccessor API
Message ID Generation

4.1.3. Message Implementations

4.1.4. The MessageBuilder Helper Class

5. Message Routing

5.1. Routers

5.1.1. Overview

5.1.2. Common Router Parameters

Inside and Outside of a Chain
Top-Level (Outside of a Chain)

5.1.3. Router Implementations

PayloadTypeRouter
HeaderValueRouter
RecipientListRouter
RecipientListRouterManagement
XPath Router
Routing and Error handling

5.1.4. Configuring (Generic) Router

Configuring a Content Based Router with XML
Configuring a Router with Annotations

5.1.5. Dynamic Routers

Manage Router Mappings using the Control Bus
Manage Router Mappings using JMX
Routing Slip
Process Manager Enterprise Integration Pattern

5.2. Filter

5.2.1. Introduction

5.2.2. Configuring Filter

Configuring a Filter with XML
Configuring a Filter with Annotations

5.3. Splitter

5.3.1. Introduction

5.3.2. Programming model

5.3.3. Configuring Splitter

Configuring a Splitter using XML
Configuring a Splitter with Annotations

5.4. Aggregator

5.4.1. Introduction

5.4.2. Functionality

5.4.3. Programming model

AggregatingMessageHandler
ReleaseStrategy
CorrelationStrategy

5.4.4. Configuring an Aggregator

Configuring an Aggregator with XML
Configuring an Aggregator with Annotations

5.4.5. Managing State in an Aggregator: MessageGroupStore

5.5. Resequencer

5.5.1. Introduction
5.5.2. Functionality
5.5.3. Configuring a Resequencer

5.6. Message Handler Chain

5.6.1. Introduction
5.6.2. Configuring a Chain

5.7. Scatter-Gather

5.7.1. Introduction
5.7.2. Functionality
5.7.3. Configuring a Scatter-Gather Endpoint

6. Message Transformation

6.1. Transformer

6.1.1. Introduction

6.1.2. Configuring Transformer

Configuring Transformer with XML
Configuring a Transformer with Annotations

6.1.3. Header Filter

6.2. Content Enricher

6.2.1. Introduction

6.2.2. Header Enricher

Header Channel Registry

6.2.3. Payload Enricher

Configuration
Examples

6.3. Claim Check

6.3.1. Introduction
6.3.2. Incoming Claim Check Transformer
6.3.3. Outgoing Claim Check Transformer
6.3.4. A word on Message Store

7. Messaging Endpoints

7.1. Message Endpoints

7.1.1. Message Handler
7.1.2. Event Driven Consumer
7.1.3. Polling Consumer
7.1.4. Namespace Support
7.1.5. Change Polling Rate at Runtime
7.1.6. Payload Type Conversion
7.1.7. Asynchronous polling
7.1.8. Endpoint Inner Beans

7.2. Messaging Gateways

7.2.1. Enter the GatewayProxyFactoryBean
7.2.2. Gateway XML Namespace Support
7.2.3. Setting the Default Reply Channel
7.2.4. Gateway Configuration with Annotations and/or XML
7.2.5. Mapping Method Arguments to a Message
7.2.6. @MessagingGateway Annotation
7.2.7. Invoking No-Argument Methods
7.2.8. Error Handling
7.2.9. Asynchronous Gateway
7.2.10. Gateway behavior when no response arrives

7.3. Service Activator

7.3.1. Introduction
7.3.2. Configuring Service Activator

7.4. Delayer

7.4.1. Introduction
7.4.2. Configuring Delayer
7.4.3. Delayer and Message Store

7.5. Scripting support

7.5.1. Script configuration

7.6. Groovy support

7.6.1. Groovy configuration
7.6.2. Control Bus

7.7. Adding Behavior to Endpoints

7.7.1. Provided Advice Classes

Retry Advice
Circuit Breaker Advice
Expression Evaluating Advice

7.7.2. Custom Advice Classes

7.7.3. Other Advice Chain Elements

7.7.4. Advising Filters

7.7.5. Advising Endpoints Using Annotations

7.7.6. Ordering Advices within an Advice Chain

7.7.7. Idempotent Receiver Enterprise Integration Pattern

7.8. Logging Channel Adapter

8. System Management

8.1. JMX Support

8.1.1. Notification Listening Channel Adapter

8.1.2. Notification Publishing Channel Adapter

8.1.3. Attribute Polling Channel Adapter

8.1.4. Tree Polling Channel Adapter

8.1.5. Operation Invoking Channel Adapter

8.1.6. Operation Invoking Outbound Gateway

8.1.7. MBean Exporter

MBean ObjectNames
MessageChannel MBean Features
Orderly Shutdown Managed Operation

8.2. Message History

8.2.1. Message History Configuration

8.3. Message Store

8.4. Metadata Store

8.4.1. Idempotent Receiver and Metadata Store

8.5. Control Bus

8.6. Orderly Shutdown

IV. Integration Endpoints

9. Endpoint Quick Reference Table

10. AMQP Support

10.1. Introduction
10.2. Inbound Channel Adapter
10.3. Inbound Gateway
10.4. Inbound Endpoint Acknowledge Mode
10.5. Outbound Channel Adapter
10.6. Outbound Gateway
10.7. AMQP Backed Message Channels
10.8. AMQP Message Headers
10.9. AMQP Samples

11. Spring ApplicationEvent Support

11.1. Receiving Spring ApplicationEvents
11.2. Sending Spring ApplicationEvents

12. Feed Adapter

12.1. Introduction
12.2. Feed Inbound Channel Adapter

13. File Support

13.1. Introduction

13.2. Reading Files

13.2.1. 'Tail'ing Files

13.3. Writing files

13.3.1. Generating Filenames
13.3.2. Specifying the Output Directory
13.3.3. Dealing with Existing Destination Files
13.3.4. File Outbound Channel Adapter
13.3.5. Outbound Gateway

13.4. File Transformers

14. FTP/FTPS Adapters

14.1. Introduction
14.2. FTP Session Factory
14.3. FTP Inbound Channel Adapter
14.4. FTP Outbound Channel Adapter
14.5. FTP Outbound Gateway
14.6. FTP Session Caching
14.7. RemoteFileTemplate

15. GemFire Support

15.1. Introduction
15.2. Inbound Channel Adapter
15.3. Continuous Query Inbound Channel Adapter
15.4. Outbound Channel Adapter
15.5. Gemfire Message Store
15.6. Gemfire Lock Registry
15.7. Gemfire Metadata Store

16. HTTP Support

16.1. Introduction

16.2. Http Inbound Gateway

16.3. Http Outbound Gateway

16.4. HTTP Namespace Support

16.5. Timeout Handling

16.6. HTTP Proxy configuration

16.7. HTTP Header Mappings

16.8. HTTP Samples

16.8.1. Multipart HTTP request - RestTemplate (client) and Http Inbound Gateway (server)

17. JDBC Support

17.1. Inbound Channel Adapter

17.1.1. Polling and Transactions
17.1.2. Max-rows-per-poll versus Max-messages-per-poll

17.2. Outbound Channel Adapter

17.3. Outbound Gateway

17.4. JDBC Message Store

17.4.1. The Generic JDBC Message Store
17.4.2. Backing Message Channels
17.4.3. Initializing the Database
17.4.4. Partitioning a Message Store

17.5. Stored Procedures

17.5.1. Supported Databases
17.5.2. Configuration
17.5.3. Common Configuration Attributes
17.5.4. Common Configuration Sub-Elements
17.5.5. Defining Parameter Sources
17.5.6. Stored Procedure Inbound Channel Adapter
17.5.7. Stored Procedure Outbound Channel Adapter
17.5.8. Stored Procedure Outbound Gateway
17.5.9. Examples

18. JPA Support

18.1. Supported Persistence Providers

18.2. Java Implementation

18.3. Namespace Support

18.3.1. Common XML Namespace Configuration Attributes
18.3.2. Providing JPA Query Parameters
18.3.3. Transaction Handling

18.4. Inbound Channel Adapter

18.4.1. Configuration Parameter Reference

18.5. Outbound Channel Adapter

18.5.1. Using an Entity Class
18.5.2. Using JPA Query Language (JPA QL)
18.5.3. Using Native Queries
18.5.4. Using Named Queries
18.5.5. Configuration Parameter Reference

18.6. Outbound Gateways

18.6.1. Common Configuration Parameters
18.6.2. Updating Outbound Gateway
18.6.3. Retrieving Outbound Gateway
18.6.4. JPA Outbound Gateway Samples

19. JMS Support

19.1. Inbound Channel Adapter

19.1.1. Transactions

19.2. Message-Driven Channel Adapter

19.3. Outbound Channel Adapter

19.3.1. Transactions

19.4. Inbound Gateway

19.5. Outbound Gateway

19.5.1. Attribute Reference

19.6. Mapping Message Headers to/from JMS Message

19.7. Message Conversion, Marshalling and Unmarshalling

19.8. JMS Backed Message Channels

19.9. Using JMS Message Selectors

19.10. JMS Samples

20. Mail Support

20.1. Mail-Sending Channel Adapter
20.2. Mail-Receiving Channel Adapter
20.3. Mail Namespace Support
20.4. Email Message Filtering
20.5. Transaction Synchronization

21. MongoDb Support

21.1. Introduction

21.2. Connecting to MongoDb

21.3. MongoDB Message Store

21.3.1. MongodDB Channel Message Store

21.4. MongoDB Inbound Channel Adapter

21.5. MongoDB Outbound Channel Adapter

22. MQTT Support

22.1. Introduction

22.2. Inbound (message-driven) Channel Adapter

22.2.1. Adding/Removing Topics at Runtime

22.3. Outbound Channel Adapter

23. Redis Support

23.1. Introduction

23.2. Connecting to Redis

23.3. Messaging with Redis

23.3.1. Redis Publish/Subscribe channel
23.3.2. Redis Inbound Channel Adapter
23.3.3. Redis Outbound Channel Adapter
23.3.4. Redis Queue Inbound Channel Adapter
23.3.5. Redis Queue Outbound Channel Adapter
23.3.6. Redis Application Events

23.4. Redis Message Store

23.4.1. Redis Channel Message Stores

23.5. Redis Metadata Store

23.6. RedisStore Inbound Channel Adapter

23.7. RedisStore Outbound Channel Adapter

23.8. Redis Outbound Command Gateway

23.9. Redis Queue Outbound Gateway

23.10. Redis Queue Inbound Gateway

23.11. Redis Lock Registry

24. Resource Support

24.1. Introduction
24.2. Resource Inbound Channel Adapter

25. RMI Support

25.1. Introduction
25.2. Outbound RMI
25.3. Inbound RMI
25.4. RMI namespace support

26. SFTP Adapters

26.1. Introduction

26.2. SFTP Session Factory

26.2.1. Configuration Properties

26.3. SFTP Session Caching

26.4. RemoteFileTemplate

26.5. SFTP Inbound Channel Adapter

26.6. SFTP Outbound Channel Adapter

26.7. SFTP Outbound Gateway

26.8. SFTP/JSCH Logging

27. Stream Support

27.1. Introduction
27.2. Reading from streams
27.3. Writing to streams
27.4. Stream namespace support

28. Syslog Support

28.1. Introduction

28.2. Syslog <inbound-channel-adapter>

28.2.1. Example Configuration

29. TCP and UDP Support

29.1. Introduction

29.2. UDP Adapters

29.3. TCP Connection Factories

29.3.1. TCP Caching Client Connection Factory
29.3.2. TCP Failover Client Connection Factory

29.4. TCP Connection Interceptors

29.5. TCP Connection Events

29.6. TCP Adapters

29.7. TCP Gateways

29.8. TCP Message Correlation

29.8.1. Overview
29.8.2. Gateways
29.8.3. Collaborating Outbound and Inbound Channel Adapters
29.8.4. Transferring Headers

29.9. A Note About NIO

29.9.1. Thread Pool Task Executor with CALLER_RUNS Policy

29.10. SSL/TLS Support

29.10.1. Overview
29.10.2. Getting Started
29.10.3. Advanced Techniques

29.11. IP Configuration Attributes

29.12. IP Message Headers

30. Twitter Support

30.1. Introduction

30.2. Twitter OAuth Configuration

30.3. Twitter Template

30.4. Twitter Inbound Adapters

30.4.1. Inbound Message Channel Adapter
30.4.2. Direct Inbound Message Channel Adapter
30.4.3. Mentions Inbound Message Channel Adapter
30.4.4. Search Inbound Message Channel Adapter

30.5. Twitter Outbound Adapter

30.5.1. Twitter Outbound Update Channel Adapter
30.5.2. Twitter Outbound Direct Message Channel Adapter

30.6. Twitter Search Outbound Gateway

31. WebSockets Support

31.1. Introduction
31.2. Overview
31.3. WebSocket Inbound Channel Adapter
31.4. WebSocket Outbound Channel Adapter
31.5. WebSockets Namespace Support

32. Web Services Support

32.1. Outbound Web Service Gateways
32.2. Inbound Web Service Gateways
32.3. Web Service Namespace Support
32.4. Outbound URI Configuration

33. XML Support - Dealing with XML Payloads

33.1. Introduction

33.2. Namespace Support

33.2.1. XPath Expressions

Providing Namespaces (Optional) to XPath Expressions
Using XPath Expressions with Default Namespaces

33.3. Transforming XML Payloads

33.3.1. Configuring Transformers as Beans

UnmarshallingTransformer
MarshallingTransformer
XsltPayloadTransformer
ResultTransformers

33.3.2. Namespace Support for XML Transformers

33.3.3. Namespace Configuration and ResultTransformers

33.4. Transforming XML Messages Using XPath

33.5. Splitting XML Messages

33.6. Routing XML Messages Using XPath

33.6.1. XML Payload Converter

33.7. XPath Header Enricher

33.8. Using the XPath Filter

33.9. #xpath SpEL Function

33.10. XML Validating Filter

34. XMPP Support

34.1. Introduction

34.2. XMPP Connection

34.3. XMPP Messages

34.3.1. Inbound Message Channel Adapter
34.3.2. Outbound Message Channel Adapter

34.4. XMPP Presence

34.4.1. Inbound Presence Message Channel Adapter
34.4.2. Outbound Presence Message Channel Adapter

34.5. Advanced Configuration

V. Appendices

A. Spring Expression Language (SpEL)

A.1. Introduction
A.2. SpEL Evaluation Context Customization
A.3. SpEL Functions
A.4. PropertyAccessors

B. Message Publishing

B.1. Message Publishing Configuration

B.1.1. Annotation-driven approach via @Publisher annotation
B.1.2. XML-based approach via the <publishing-interceptor> element
B.1.3. Producing and publishing messages based on a scheduled trigger

C. Transaction Support

C.1. Understanding Transactions in Message flows

C.1.1. Poller Transaction Support

C.2. Transaction Boundaries

C.3. Transaction Synchronization

C.4. Pseudo Transactions

D. Security in Spring Integration

D.1. Introduction
D.2. Securing channels

E. Spring Integration Samples

E.1. Introduction

E.2. Where to get Samples

E.3. Submitting Samples or Sample Requests

E.4. Samples Structure

E.5. Samples

E.5.1. Loan Broker
E.5.2. The Cafe Sample
E.5.3. The XML Messaging Sample

F. Configuration

F.1. Introduction

F.2. Namespace Support

F.3. Configuring the Task Scheduler

F.4. Error Handling

F.5. Annotation Support

F.5.1. Messaging Meta-Annotations
F.5.2. Annotations on @Beans
F.5.3. Creating a Bridge with Annotations
F.5.4. Advising Annotated Endpoints

F.6. Message Mapping rules and conventions

F.6.1. Simple Scenarios
F.6.2. Complex Scenarios

G. Additional Resources

G.1. Spring Integration Home

H. Change History

H.1. Changes between 4.0 and 4.1

H.2. Changes between 3.0 and 4.0

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

H.2.2. General Changes

Requires Spring Framework 4.0
Header Type for XPath Header Enricher
Object To Json Transformer: Node Result
JMS Header Mapping
JMS Outbound Channel Adapter
JMS Inbound Channel Adapter
Datatype Channels
Simpler Retry Advice Configuration
Correlation Endpoint: Time-based Release Strategy
Redis Metadata Store
JdbcChannelMessageStore and PriorityChannel
AMQP Endpoints Delivery Mode
FTP Timeouts
Twitter: StatusUpdatingMessageHandler
JPA Retrieving Gateway: id-expression
TCP Deserialization Events
Messaging Annotations on @Bean Definitions

H.3. Changes Between 2.2 and 3.0

H.3.1. New Components

HTTP Request Mapping
Spring Expression Language (SpEL) Configuration
SpEL Functions Support
SpEL PropertyAccessors Support
Redis: New Components
Header Channel Registry
MongoDB support: New ConfigurableMongoDbMessageStore
Syslog Support
'Tail' Support
JMX Support
TCP/IP Connection Events and Connection Management
Inbound Channel Adapter Script Support
Content Enricher: Headers Enrichment Support

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

H.4. Changes between 2.1 and 2.2

H.4.1. New Components

RedisStore Inbound and Outbound Channel Adapters
MongoDB Inbound and Outbound Channel Adapters
JPA Endpoints

H.4.2. General Changes

Spring 3.1 Used by Default
Adding Behavior to Endpoints
Transaction Synchronization and Pseudo Transactions
File Adapter - Improved File Overwrite/Append Handling
Reply-Timeout added to more Outbound Gateways
Spring-AMQP 1.1
JDBC Support - Stored Procedures Components
JDBC Support - Outbound Gateway
JDBC Support - Channel-specific Message Store Implementation
Orderly Shutdown
JMS Oubound Gateway Improvements
object-to-json-transformer
HTTP Support

H.5. Changes between 2.0 and 2.1

H.5.1. New Components

JSR-223 Scripting Support
GemFire Support
AMQP Support
MongoDB Support
Redis Support
Support for Spring's Resource abstraction
Stored Procedure Components
XPath and XML Validating Filter
Payload Enricher
FTP and SFTP Outbound Gateways
FTP Session Caching

H.5.2. Framework Refactoring

Standardizing Router Configuration
XML Schemas updated to 2.1

H.5.3. Source Control Management and Build Infrastructure

Source Code now hosted on Github
Improved Source Code Visibility with Sonar

H.5.4. New Samples

H.6. Changes between 1.0 and 2.0

H.6.1. Spring 3 support

Support for the Spring Expression Language (SpEL)
ConversionService and Converter
TaskScheduler and Trigger
RestTemplate and HttpMessageConverter

H.6.2. Enterprise Integration Pattern Additions

Message History
Message Store
Claim Check
Control Bus

H.6.3. New Channel Adapters and Gateways

TCP/UDP Adapters
Twitter Adapters
XMPP Adapters
FTP/FTPS Adapters
SFTP Adapters
Feed Adapters

H.6.4. Other Additions

Groovy Support
Map Transformers
JSON Transformers
Serialization Transformers

H.6.5. Framework Refactoring

H.6.6. New Source Control Management and Build Infrastructure

H.6.7. New Spring Integration Samples

H.6.8. SpringSource Tool Suite Visual Editor for Spring Integration

		Next
		Preface