Spring Integration Reference Manual

Mark Fisher

Marius Bogoevici

Iwein Fuld

Jonas Partner

Oleg Zhurakousky

Gary Russell

Dave Syer

Josh Long

David Turanski

Gunnar Hillert

Artem Bilan

Amol Nayak

2.2.0.M4


Table of Contents

Preface
1. Code Conventions
I. What's new?
1. What's new in Spring Integration 2.2?
1.1. General
1.1.1. Spring 3.1
1.1.2. Outbound Gateways
1.1.3. Spring-AMQP 1.1
1.1.4. JDBC Adapter - Stored Procedures Components
1.1.5. JDBC Adapter - Outbound Gateway
1.1.6. File Adapter - Improved File Overwrite/Append Handling
1.1.7. Transaction Synchronization
1.1.8. Orderly Shutdown
1.2. New Components
1.2.1. JPA Endpoints
1.3. Framework Refactoring
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
III. Core Messaging
3. Messaging Channels
3.1. Message Channels
3.1.1. The MessageChannel Interface
3.1.2. Message Channel Implementations
3.1.3. Channel Interceptors
3.1.4. MessagingTemplate
3.1.5. Configuring Message Channels
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 Outbound Channel Adapter
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
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
5.1.3. Router Implementations
5.1.4. Configuring (Generic) Router
5.1.5. Dynamic Routers
5.2. Filter
5.2.1. Introduction
5.2.2. Configuring Filter
5.3. Splitter
5.3.1. Introduction
5.3.2. Programming model
5.3.3. Configuring Splitter
5.4. Aggregator
5.4.1. Introduction
5.4.2. Functionality
5.4.3. Programming model
5.4.4. Configuring Aggregator
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 Chain
6. Message Transformation
6.1. Transformer
6.1.1. Introduction
6.1.2. Configuring Transformer
6.1.3. Header Filter
6.2. Content Enricher
6.2.1. Introduction
6.2.2. Header Enricher
6.2.3. Payload Enricher
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.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. Invoking No-Argument Methods
7.2.6. Error Handling
7.2.7. Asynchronous Gateway
7.2.8. 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
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. Operation Invoking Channel Adapter
8.1.5. Operation Invoking Outbound Gateway
8.1.6. MBean Exporter
8.2. Message History
8.2.1. Message History Configuration
8.3. Message Store
8.4. Control Bus
8.5. Orderly Shutdown
IV. Integration Adapters
9. AMQP Support
9.1. Introduction
9.2. Inbound Channel Adapter
9.3. Outbound Channel Adapter
9.4. Inbound Gateway
9.5. Outbound Gateway
9.6. AMQP Backed Message Channels
9.7. AMQP Message Headers
9.8. AMQP Samples
10. Spring ApplicationEvent Support
10.1. Receiving Spring ApplicationEvents
10.2. Sending Spring ApplicationEvents
11. Feed Adapter
11.1. Introduction
11.2. Feed Inbound Channel Adapter
12. File Support
12.1. Introduction
12.2. Reading Files
12.3. Writing files
12.3.1. Specifying the Output Directory
12.3.2. Dealing with Existing Destination Files
12.3.3. File Outbound Channel Adapter
12.3.4. Outbound Gateway
12.4. File Transformers
13. FTP/FTPS Adapters
13.1. Introduction
13.2. FTP Session Factory
13.3. FTP Inbound Channel Adapter
13.4. FTP Outbound Channel Adapter
13.5. FTP Outbound Gateway
13.6. FTP Session Caching
14. GemFire Support
14.1. Introduction
14.2. Inbound Channel Adapter
14.3. Continuous Query Inbound Channel Adapter
14.4. Outbound Channel Adapter
14.5. Gemfire Message Store
15. HTTP Support
15.1. Introduction
15.2. Http Inbound Gateway
15.3. Http Outbound Gateway
15.4. HTTP Namespace Support
15.5. Timeout Handling
15.6. HTTP Proxy configuration
15.7. HTTP Header Mappings
15.8. HTTP Samples
15.8.1. Multipart HTTP request - RestTemplate (client) and Http Inbound Gateway (server)
16. TCP and UDP Support
16.1. Introduction
16.2. UDP Adapters
16.3. TCP Connection Factories
16.3.1. TCP Caching Client Connection Factory
16.3.2. TCP Failover Client Connection Factory
16.4. TCP Connection Interceptors
16.5. TCP Adapters
16.6. TCP Gateways
16.7. TCP Message Correlation
16.7.1. Overview
16.7.2. Gateways
16.7.3. Collaborating Outbound and Inbound Channel Adapters
16.8. A Note About NIO
16.9. SSL/TLS Support
16.9.1. Overview
16.9.2. Getting Started
16.9.3. Advanced Techniques
16.10. IP Configuration Attributes
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. Initializing the Database
17.4.2. 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.2. Message-Driven Channel Adapter
19.3. Outbound Channel Adapter
19.4. Inbound Gateway
19.5. Outbound Gateway
19.6. Mapping Message Headers to/from JMS Message
19.7. Message Conversion, Marshalling and Unmarshalling
19.8. JMS Backed Message Channels
19.9. 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
21. MongoDb Support
21.1. Introduction
21.2. Connecting to MongoDb
21.3. MongoDB Message Store
22. Redis Support
22.1. Introduction
22.2. Connecting to Redis
22.3. Messaging with Redis
22.3.1. Redis Publish/Subscribe channel
22.3.2. Redis Inbound Channel Adapter
22.3.3. Redis Outbound Channel Adapter
22.4. Redis Message Store
23. Resource Support
23.1. Introduction
23.2. Resource Inbound Channel Adapter
24. RMI Support
24.1. Introduction
24.2. Outbound RMI
24.3. Inbound RMI
24.4. RMI namespace support
25. SFTP Adapters
25.1. Introduction
25.2. SFTP Session Factory
25.2.1. Configuration Properties
25.3. SFTP Session Caching
25.4. SFTP Inbound Channel Adapter
25.5. SFTP Outbound Channel Adapter
25.6. SFTP Outbound Gateway
25.7. SFTP/JSCH Logging
26. Stream Support
26.1. Introduction
26.2. Reading from streams
26.3. Writing to streams
26.4. Stream namespace support
27. Twitter Adapter
27.1. Introduction
27.2. Twitter OAuth Configuration
27.3. Twitter Template
27.4. Twitter Inbound Adapters
27.4.1. Inbound Message Channel Adapter
27.4.2. Direct Inbound Message Channel Adapter
27.4.3. Mentions Inbound Message Channel Adapter
27.4.4. Search Inbound Message Channel Adapter
27.5. Twitter Outbound Adapter
27.5.1. Twitter Outbound Update Channel Adapter
27.5.2. Twitter Outbound Direct Message Channel Adapter
28. Web Services Support
28.1. Outbound Web Service Gateways
28.2. Inbound Web Service Gateways
28.3. Web Service Namespace Support
29. XML Support - Dealing with XML Payloads
29.1. Introduction
29.2. Namespace Support
29.2.1. XPath Expressions
29.3. Transforming XML Payloads
29.3.1. Configuring Transformers as Beans
29.3.2. Namespace Support for XML Transformers
29.3.3. Namespace Configuration and ResultTransformers
29.4. Transforming XML Messages Using XPath
29.5. Splitting XML Messages
29.6. Routing XML Messages Using XPath
29.6.1. XML Payload Converter
29.7. XPath Header Enricher
29.8. Using the XPath Filter
29.9. XML Validating Filter
30. XMPP Support
30.1. Introduction
30.2. XMPP Connection
30.3. XMPP Messages
30.3.1. Inbound Message Channel Adapter
30.3.2. Outbound Message Channel Adapter
30.4. XMPP Presence
30.4.1. Inbound Presence Message Channel Adapter
30.4.2. Outbound Presence Message Channel Adapter
30.5. Appendices
V. Appendices
31. Message Publishing
31.1. Message Publishing Configuration
31.1.1. Annotation-driven approach via @Publisher annotation
31.1.2. XML-based approach via the <publishing-interceptor> element
31.1.3. Producing and publishing messages based on a scheduled trigger
32. Transaction Support
32.1. Understanding Transactions in Message flows
32.1.1. Poller Transaction Support
32.2. Transaction Boundaries
32.3. Pollers and Transaction Synchronization
33. Security in Spring Integration
33.1. Introduction
33.2. Securing channels
A. Spring Integration Samples
A.1. Introduction
A.2. Where to get Samples
A.3. Submitting Samples or Sample Requests
A.4. Samples Structure
A.5. Samples
A.5.1. Loan Broker
A.5.2. The Cafe Sample
A.5.3. The XML Messaging Sample
B. Configuration
B.1. Introduction
B.2. Namespace Support
B.3. Configuring the Task Scheduler
B.4. Error Handling
B.5. Annotation Support
B.6. Message Mapping rules and conventions
B.6.1. Simple Scenarios
B.6.2. Complex Scenarios
C. Additional Resources
C.1. Spring Integration Home
D. Change History
D.1. Changes between 1.0 and 2.0
D.1.1. Spring 3 support
D.1.2. Enterprise Integration Pattern Additions
D.1.3. New Channel Adapters and Gateways
D.1.4. Other Additions
D.1.5. Framework Refactoring
D.1.6. New Source Control Management and Build Infrastructure
D.1.7. New Spring Integration Samples
D.1.8. SpringSource Tool Suite Visual Editor for Spring Integration
D.2. Changes between 2.0 and 2.1
D.2.1. New Components
D.2.2. Framework Refactoring
D.2.3. Source Control Management and Build Infrastructure
D.2.4. New Samples
D.3. Changes between 2.1 and 2.2

Preface

1 Code Conventions

The Spring Framework 2.0 introduced support for namespaces, which simplifies the Xml configuration of the application context, and consequently Spring Integration provides broad namespace support. This reference guide applies the following conventions for all code examples that use namespace support:

The int namespace prefix will be used for Spring Integration's core namespace support. Each Spring Integration adapter type (module) will provide its own namespace, which is configured using the following convention:

int- followed by the name of the module, e.g. int-twitter, int-stream, …

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

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

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

Part I. What's new?

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

1. What's new in Spring Integration 2.2?

This chapter provides an overview of the new features and improvements that have been introduced with Spring Integration 2.2 If you are interested in even more detail, please take a look at the Issue Tracker tickets that were resolved as part of the 2.2 development process:

1.1 General

1.1.1 Spring 3.1

Spring Integration now uses Spring 3.1.

1.1.2 Outbound Gateways

The XML Namespace support adds the reply-timeout attribute to the following Outbound Gateways:

  • Amqp Outbound Gateway
  • File Outbound Gateway
  • Ftp Outbound Gateway
  • Sftp Outbound Gateway
  • Ws Outbound Gateway

1.1.3 Spring-AMQP 1.1

Spring Integration now uses Spring AMQP 1.1. This enables several features to be used within a Spring Integration application, including...

  • A fixed reply queue for the outbound gateway
  • HA (mirrored) queues
  • Publisher Confirms
  • Returned Messages
  • Support for Dead Letter Exchanges/Dead Letter Queues

1.1.4 JDBC Adapter - Stored Procedures Components

SpEL Support

When using the Stored Procedure components of the Spring Integration JDBC Adapter, you can now provide Stored Procedure Names or Stored Function Names using Spring Expression Language (SpEL).

This allows you to specify the Stored Procedures to be invoked at runtime. For example, you can provide Stored Procedure names that you would like to execute via Message Headers. For more information please see Section 17.5, “Stored Procedures”.

JMX Support

The Stored Procedure components now provide basic JMX support, exposing some of their properties as MBeans:

  • Stored Procedure Name
  • Stored Procedure Name Expression
  • JdbcCallOperations Cache Statistics

1.1.5 JDBC Adapter - Outbound Gateway

When using the JDBC Outbound Gateway, the update query is no longer mandatory. You can now provide solely a select query using the request message as a source of parameters.

1.1.6 File Adapter - Improved File Overwrite/Append Handling

When using the File Oubound Channel Adapter or the File Outbound Gateway, a new mode property was added. Prior to Spring Integration 2.2, target files were replaced when they existed. Now you can specify the following options:

  • REPLACE (Default)
  • APPEND
  • FAIL
  • IGNORE

For more information please see Section 12.3.2, “Dealing with Existing Destination Files”.

1.1.7 Transaction Synchronization

When running from a transactional poller, mail inbound adapters can be configured to update the mailbox only if the transaction commits.

1.1.8 Orderly Shutdown

A method stopActiveComponents() has been added to the IntegrationMBeanExporter. This allows a Spring Integration application to be shut down in an orderly manner, disallowing new inbound messages to certain adapters and waiting for some time to allow in-flight messages to complete.

1.2 New Components

1.2.1 JPA Endpoints

Spring Integration now includes components for the Java Persistence API (JPA) for retrieving and persisting JPA entity objects. The JPA Adapter includes the following components:

For more information please see Chapter 18, JPA Support

1.3 Framework Refactoring

Part II. Overview of Spring Integration Framework

Spring Integration provides an extension of the Spring programming model to support the well-known Enterprise Integration Patterns. It enables lightweight messaging within Spring-based applications and supports integration with external systems via declarative adapters. Those adapters provide a higher-level of abstraction over Spring's support for remoting, messaging, and scheduling. Spring Integration's primary goal is to provide a simple model for building enterprise integration solutions while maintaining the separation of concerns that is essential for producing maintainable, testable code.

2. Spring Integration Overview

2.1 Background

One of the key themes of the Spring Framework is inversion of control. In its broadest sense, this means that the framework handles responsibilities on behalf of the components that are managed within its context. The components themselves are simplified since they are relieved of those responsibilities. For example, dependency injection relieves the components of the responsibility of locating or creating their dependencies. Likewise, aspect-oriented programming relieves business components of generic cross-cutting concerns by modularizing them into reusable aspects. In each case, the end result is a system that is easier to test, understand, maintain, and extend.

Furthermore, the Spring framework and portfolio provide a comprehensive programming model for building enterprise applications. Developers benefit from the consistency of this model and especially the fact that it is based upon well-established best practices such as programming to interfaces and favoring composition over inheritance. Spring's simplified abstractions and powerful support libraries boost developer productivity while simultaneously increasing the level of testability and portability.

Spring Integration is motivated by these same goals and principles. It extends the Spring programming model into the messaging domain and builds upon Spring's existing enterprise integration support to provide an even higher level of abstraction. It supports message-driven architectures where inversion of control applies to runtime concerns, such as when certain business logic should execute and where the response should be sent. It supports routing and transformation of messages so that different transports and different data formats can be integrated without impacting testability. In other words, the messaging and integration concerns are handled by the framework, so business components are further isolated from the infrastructure and developers are relieved of complex integration responsibilities.

As an extension of the Spring programming model, Spring Integration provides a wide variety of configuration options including annotations, XML with namespace support, XML with generic "bean" elements, and of course direct usage of the underlying API. That API is based upon well-defined strategy interfaces and non-invasive, delegating adapters. Spring Integration's design is inspired by the recognition of a strong affinity between common patterns within Spring and the well-known Enterprise Integration Patterns as described in the book of the same name by Gregor Hohpe and Bobby Woolf (Addison Wesley, 2004). Developers who have read that book should be immediately comfortable with the Spring Integration concepts and terminology.

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

2.3 Main Components

From the vertical perspective, a layered architecture facilitates separation of concerns, and interface-based contracts between layers promote loose coupling. Spring-based applications are typically designed this way, and the Spring framework and portfolio provide a strong foundation for following this best practice for the full-stack of an enterprise application. Message-driven architectures add a horizontal perspective, yet these same goals are still relevant. Just as "layered architecture" is an extremely generic and abstract paradigm, messaging systems typically follow the similarly abstract "pipes-and-filters" model. The "filters" represent any component that is capable of producing and/or consuming messages, and the "pipes" transport the messages between filters so that the components themselves remain loosely-coupled. It is important to note that these two high-level paradigms are not mutually exclusive. The underlying messaging infrastructure that supports the "pipes" should still be encapsulated in a layer whose contracts are defined as interfaces. Likewise, the "filters" themselves would typically be managed within a layer that is logically above the application's service layer, interacting with those services through interfaces much in the same way that a web-tier would.

2.3.1 Message

In Spring Integration, a Message is a generic wrapper for any Java object combined with metadata used by the framework while handling that object. It consists of a payload and headers. The payload can be of any type and the headers hold commonly required information such as id, timestamp, correlation id, and return address. Headers are also used for passing values to and from connected transports. For example, when creating a Message from a received File, the file name may be stored in a header to be accessed by downstream components. Likewise, if a Message's content is ultimately going to be sent by an outbound Mail adapter, the various properties (to, from, cc, subject, etc.) may be configured as Message header values by an upstream component. Developers can also store any arbitrary key-value pairs in the headers.

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

A Message Channel may follow either Point-to-Point or Publish/Subscribe semantics. With a Point-to-Point channel, at most one consumer can receive each Message sent to the channel. Publish/Subscribe channels, on the other hand, will attempt to broadcast each Message to all of its subscribers. Spring Integration supports both of these.

Whereas "Point-to-Point" and "Publish/Subscribe" define the two options for how many consumers will ultimately receive each Message, there is another important consideration: should the channel buffer messages? In Spring Integration, Pollable Channels are capable of buffering Messages within a queue. The advantage of buffering is that it allows for throttling the inbound Messages and thereby prevents overloading a consumer. However, as the name suggests, this also adds some complexity, since a consumer can only receive the Messages from such a channel if a poller is configured. On the other hand, a consumer connected to a Subscribable Channel is simply Message-driven. The variety of channel implementations available in Spring Integration will be discussed in detail in Section 3.1.2, “Message Channel Implementations”.

2.3.3 Message Endpoint

One of the primary goals of Spring Integration is to simplify the development of enterprise integration solutions through inversion of control. This means that you should not have to implement consumers and producers directly, and you should not even have to build Messages and invoke send or receive operations on a Message Channel. Instead, you should be able to focus on your specific domain model with an implementation based on plain Objects. Then, by providing declarative configuration, you can "connect" your domain-specific code to the messaging infrastructure provided by Spring Integration. The components responsible for these connections are Message Endpoints. This does not mean that you will necessarily connect your existing application code directly. Any real-world enterprise integration solution will require some amount of code focused upon integration concerns such as routing and transformation. The important thing is to achieve separation of concerns between such integration logic and business logic. In other words, as with the Model-View-Controller paradigm for web applications, the goal should be to provide a thin but dedicated layer that translates inbound requests into service layer invocations, and then translates service layer return values into outbound replies. The next section will provide an overview of the Message Endpoint types that handle these responsibilities, and in upcoming chapters, you will see how Spring Integration's declarative configuration options provide a non-invasive way to use each of these.

2.4 Message Endpoints

A Message Endpoint represents the "filter" of a pipes-and-filters architecture. As mentioned above, the endpoint's primary role is to connect application code to the messaging framework and to do so in a non-invasive manner. In other words, the application code should ideally have no awareness of the Message objects or the Message Channels. This is similar to the role of a Controller in the MVC paradigm. Just as a Controller handles HTTP requests, the Message Endpoint handles Messages. Just as Controllers are mapped to URL patterns, Message Endpoints are mapped to Message Channels. The goal is the same in both cases: isolate application code from the infrastructure. These concepts are discussed at length along with all of the patterns that follow in the Enterprise Integration Patterns book. Here, we provide only a high-level description of the main endpoint types supported by Spring Integration and their roles. The chapters that follow will elaborate and provide sample code as well as configuration examples.

2.4.1 Transformer

A Message Transformer is responsible for converting a Message's content or structure and returning the modified Message. Probably the most common type of transformer is one that converts the payload of the Message from one format to another (e.g. from XML Document to java.lang.String). Similarly, a transformer may be used to add, remove, or modify the Message's header values.

2.4.2 Filter

A Message Filter determines whether a Message should be passed to an output channel at all. This simply requires a boolean test method that may check for a particular payload content type, a property value, the presence of a header, etc. If the Message is accepted, it is sent to the output channel, but if not it will be dropped (or for a more severe implementation, an Exception could be thrown). Message Filters are often used in conjunction with a Publish Subscribe channel, where multiple consumers may receive the same Message and use the filter to narrow down the set of Messages to be processed based on some criteria.

[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 "filter" matches more closely with Spring Integration's Message Endpoint: any component that can be connected to Message Channel(s) in order to send and/or receive Messages.

2.4.3 Router

A Message Router is responsible for deciding what channel or channels should receive the Message next (if any). Typically the decision is based upon the Message's content and/or metadata available in the Message Headers. A Message Router is often used as a dynamic alternative to a statically configured output channel on a Service Activator or other endpoint capable of sending reply Messages. Likewise, a Message Router provides a proactive alternative to the reactive Message Filters used by multiple subscribers as described above.

2.4.4 Splitter

A Splitter is another type of Message Endpoint whose responsibility is to accept a Message from its input channel, split that Message into multiple Messages, and then send each of those to its output channel. This is typically used for dividing a "composite" payload object into a group of Messages containing the sub-divided payloads.

2.4.5 Aggregator

Basically a mirror-image of the Splitter, the Aggregator is a type of Message Endpoint that receives multiple Messages and combines them into a single Message. In fact, Aggregators are often downstream consumers in a pipeline that includes a Splitter. Technically, the Aggregator is more complex than a Splitter, because it is required to maintain state (the Messages to-be-aggregated), to decide when the complete group of Messages is available, and to timeout if necessary. Furthermore, in case of a timeout, the Aggregator needs to know whether to send the partial results or to discard them to a separate channel. Spring Integration provides a CompletionStrategy as well as configurable settings for timeout, whether to send partial results upon timeout, and the discard channel.

2.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 necessary (if the method does not expect a Message-typed parameter). Whenever the service object's method returns a value, that return value will likewise be converted to a reply Message if necessary (if it's not already a Message). That reply Message is sent to the output channel. If no output channel has been configured, then the reply will be sent to the channel specified in the Message's "return address" if available.

A request-reply "Service Activator" endpoint connects a target object's method to input and output Message Channels.

2.4.7 Channel Adapter

A Channel Adapter is an endpoint that connects a Message Channel to some other system or transport. Channel Adapters may be either inbound or outbound. Typically, the Channel Adapter will do some mapping between the Message and whatever object or resource is received-from or sent-to the other system (File, HTTP Request, JMS Message, etc). Depending on the transport, the Channel Adapter may also populate or extract Message header values. Spring Integration provides a number of Channel Adapters, and they will be described in upcoming chapters.

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

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

Part III. Core Messaging

This section covers all aspects of the core messaging API in Spring Integration. Here you will learn about Messages, Message Channels, and Message Endpoints. Many of the Enterprise Integration Patterns are covered here as well, such as Filters, Routers, Transformers, Service-Activators, Splitters, and Aggregators. The section also contains material about System Management, including the Control Bus and Message History support.

3. Messaging Channels

3.1 Message Channels

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

3.1.1 The MessageChannel Interface

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

public interface MessageChannel {

    boolean send(Message message);

    boolean send(Message message, long timeout);
}

When sending a message, the return value will be true if the message is sent successfully. If the send call times out or is interrupted, then it will return false.

PollableChannel

Since Message Channels may or may not buffer Messages (as discussed in the overview), there are two sub-interfaces defining the buffering (pollable) and non-buffering (subscribable) channel behavior. Here is the definition of PollableChannel.

public interface PollableChannel extends MessageChannel {

    Message<?> receive();

    Message<?> receive(long timeout);

}

Similar to the send methods, when receiving a message, the return value will be null in the case of a timeout or interrupt.

SubscribableChannel

The SubscribableChannel base interface is implemented by channels that send Messages directly to their subscribed MessageHandlers. Therefore, they do not provide receive methods for polling, but instead define methods for managing those subscribers:

public interface SubscribableChannel extends MessageChannel {

    boolean subscribe(MessageHandler handler);

    boolean unsubscribe(MessageHandler handler);

}

3.1.2 Message Channel Implementations

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

PublishSubscribeChannel

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

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:

public QueueChannel(int capacity)

A channel that has not reached its capacity limit will store messages in its internal queue, and the send() method will return immediately even if no receiver is ready to handle the message. If the queue has reached capacity, then the sender will block until room is available. Or, if using the send call that accepts a timeout, it will block until either room is available or the timeout period elapses, whichever occurs first. Likewise, a receive call will return immediately if a message is available on the queue, but if the queue is empty, then a receive call may block until either a message is available or the timeout elapses. In either case, it is possible to force an immediate return regardless of the queue's state by passing a timeout value of 0. Note however, that calls to the no-arg versions of send() and receive() will block indefinitely.

PriorityChannel

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

RendezvousChannel

The RendezvousChannel enables a "direct-handoff" scenario where a sender will block until another party invokes the channel's receive() method or vice-versa. Internally, this implementation is quite similar to the QueueChannel except that it uses a SynchronousQueue (a zero-capacity implementation of BlockingQueue). This works well in situations where the sender and receiver are operating in different threads but simply dropping the message in a queue asynchronously is not appropriate. In other words, with a RendezvousChannel at least the sender knows that some receiver has accepted the message, whereas with a QueueChannel, the message would have been stored to the internal queue and potentially never received.

[Tip]Tip

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

The RendezvousChannel is also useful for implementing request-reply operations. The sender can create a temporary, anonymous instance of RendezvousChannel which it then sets as the 'replyChannel' header when building a Message. After sending that Message, the sender can immediately call receive (optionally providing a timeout value) in order to block while waiting for a reply Message. This is very similar to the implementation used internally by many of Spring Integration's request-reply components.

DirectChannel

The DirectChannel has point-to-point semantics but otherwise is more similar to the PublishSubscribeChannel than any of the queue-based channel implementations described above. It implements the SubscribableChannel interface instead of the PollableChannel interface, so it dispatches Messages directly to a subscriber. As a point-to-point channel, however, it differs from the PublishSubscribeChannel in that it will only send each Message to a single subscribed MessageHandler.

In addition to being the simplest point-to-point channel option, one of its most important features is that it enables a single thread to perform the operations on "both sides" of the channel. For example, if a handler is subscribed to a DirectChannel, then sending a Message to that channel will trigger invocation of that handler's handleMessage(Message) method directly in the sender's thread, before the send() method invocation can return.

The key motivation for providing a channel implementation with this behavior is to support transactions that must span across the channel while still benefiting from the abstraction and loose coupling that the channel provides. If the send call is invoked within the scope of a transaction, then the outcome of the handler's invocation (e.g. updating a database record) will play a role in determining the ultimate result of that transaction (commit or rollback).

[Note]Note
Since the DirectChannel is the simplest option and does not add any additional overhead that would be required for scheduling and managing the threads of a poller, it is the default channel type within Spring Integration. The general idea is to define the channels for an application and then to consider which of those need to provide buffering or to throttle input, and then modify those to be queue-based PollableChannels. Likewise, if a channel needs to broadcast messages, it should not be a DirectChannel but rather a PublishSubscribeChannel. Below you will see how each of these can be configured.

The DirectChannel internally delegates to a Message Dispatcher to invoke its subscribed Message Handlers, and that dispatcher can have a load-balancing strategy. The load-balancer determines how invocations will be ordered in the case that there are multiple handlers subscribed to the same channel. When using the namespace support described below, the default strategy is "round-robin" which essentially load-balances across the handlers in rotation.

[Note]Note
The "round-robin" strategy is currently the only implementation available out-of-the-box in Spring Integration. Other strategy implementations may be added in future versions.

The load-balancer also works in combination with a boolean failover property. If the "failover" value is true (the default), then the dispatcher will fall back to any subsequent handlers as necessary when preceding handlers throw Exceptions. The order is determined by an optional order value defined on the handlers themselves or, if no such value exists, the order in which the handlers are subscribed.

If a certain situation requires that the dispatcher always try to invoke the first handler, then fallback in the same fixed order sequence every time an error occurs, no load-balancing strategy should be provided. In other words, the dispatcher still supports the failover boolean property even when no load-balancing is enabled. Without load-balancing, however, the invocation of handlers will always begin with the first according to their order. For example, this approach works well when there is a clear definition of primary, secondary, tertiary, and so on. When using the namespace support, the "order" attribute on any endpoint will determine that order.

[Note]Note
Keep in mind that load-balancing and failover only apply when a channel has more than one subscribed Message Handler. When using the namespace support, this means that more than one endpoint shares the same channel reference in the "input-channel" attribute.

ExecutorChannel

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

[Tip]Tip
Note that there are occasions where the sender may block. For example, when using a TaskExecutor with a rejection-policy that throttles back on the client (such as the ThreadPoolExecutor.CallerRunsPolicy), the sender's thread will execute the method directly anytime the thread pool is at its maximum capacity and the executor's work queue is full. Since that situation would only occur in a non-predictable way, that obviously cannot be relied upon for transactions.

Scoped Channel

Spring Integration 1.0 provided a ThreadLocalChannel implementation, but that has been removed as of 2.0. Now, there is a more general way for handling the same requirement by simply adding a "scope" attribute to a channel. The value of the attribute can be any name of a Scope that is available within the context. For example, in a web environment, certain Scopes are available, and any custom Scope implementations can be registered with the context. Here's an example of a ThreadLocal-based scope being applied to a channel, including the registration of the Scope itself.

 <int:channel id="threadScopedChannel" scope="thread">
     <int:queue />
 </int:channel>
	
 <bean class="org.springframework.beans.factory.config.CustomScopeConfigurer">
    <property name="scopes">
         <map>
             <entry key="thread" value="org.springframework.context.support.SimpleThreadScope" />
         </map>
     </property>
 </bean>

The channel above also delegates to a queue internally, but the channel is bound to the current thread, so the contents of the queue are as well. That way the thread that sends to the channel will later be able to receive those same Messages, but no other thread would be able to access them. While thread-scoped channels are rarely needed, they can be useful in situations where DirectChannels are being used to enforce a single thread of operation but any reply Messages should be sent to a "terminal" channel. If that terminal channel is thread-scoped, the original sending thread can collect its replies from it.

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

3.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 Messages are being sent to and received from MessageChannels, those channels provide an opportunity for intercepting the send and receive operations. The ChannelInterceptor strategy interface provides methods for each of those operations:

public interface ChannelInterceptor {

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

    void postSend(Message<?> message, MessageChannel channel, boolean sent);

    boolean preReceive(MessageChannel channel);

    Message<?> postReceive(Message<?> message, MessageChannel channel);
}

After implementing the interface, registering the interceptor with a channel is just a matter of calling:

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 will be sent directly to one or more subscribers depending on the type of channel (e.g. a PublishSubscribeChannel sends to all of its subscribers). Therefore, the preReceive(..) and postReceive(..) interceptor methods are only invoked when the interceptor is applied to a PollableChannel.

Spring Integration also provides an implementation of the Wire Tap pattern. It is a simple interceptor that sends the Message to another channel without otherwise altering the existing flow. It can be very useful for debugging and monitoring. An example is shown in the section called “Wire Tap”.

Because it is rarely necessary to implement all of the interceptor methods, a ChannelInterceptorAdapter class is also available for sub-classing. It provides no-op methods (the void method is empty, the Message returning methods return the Message as-is, and the boolean method returns true). Therefore, it is often easiest to extend that class and just implement the method(s) that you need as in the following example.

public class CountingChannelInterceptor extends ChannelInterceptorAdapter {

    private final AtomicInteger sendCount = new AtomicInteger();

    @Override
    public Message<?> preSend(Message<?> message, MessageChannel channel) {
        sendCount.incrementAndGet();
        return message;
    }
}

[Tip]Tip
The order of invocation for the interceptor methods depends on the type of channel. As described above, the queue-based channels are the only ones where the receive method is intercepted in the first place. Additionally, the relationship between send and receive interception depends on the timing of separate sender and receiver threads. For example, if a receiver is already blocked while waiting for a message the order could be: preSend, preReceive, postReceive, postSend. However, if a receiver polls after the sender has placed a message on the channel and already returned, the order would be: preSend, postSend, (some-time-elapses) preReceive, postReceive. The time that elapses in such a case depends on a number of factors and is therefore generally unpredictable (in fact, the receive may never happen!). Obviously, the type of queue also plays a role (e.g. rendezvous vs. priority). The bottom line is that you cannot rely on the order beyond the fact that preSend will precede postSend and preReceive will precede postReceive.

3.1.4 MessagingTemplate

As you will see when the endpoints and their various configuration options are introduced, Spring Integration provides a foundation for messaging components that enables non-invasive invocation of your application code from the messaging system. However, sometimes it is necessary to invoke the messaging system from your application code. For convenience when implementing such use-cases, Spring Integration provides a MessagingTemplate that supports a variety of operations across the Message Channels, including request/reply scenarios. For example, it is possible to send a request and wait for a reply.

MessagingTemplate template = new MessagingTemplate();

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

In that example, a temporary anonymous channel would be created internally by the template. The 'sendTimeout' and 'receiveTimeout' properties may also be set on the template, and other exchange types are also supported.

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

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

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

[Note]Note

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

3.1.5 Configuring Message Channels

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

<int:channel id="exampleChannel"/>

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

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

When using the <channel/> element without any sub-elements, it will create a DirectChannel instance (a SubscribableChannel).

However, you can alternatively provide a variety of <queue/> sub-elements to create any of the pollable channel types (as described in Section 3.1.2, “Message Channel Implementations”). Examples of each are shown below.

DirectChannel Configuration

As mentioned above, DirectChannel is the default type.

<int:channel id="directChannel"/>

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

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

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

Datatype Channel Configuration

There are times when a consumer can only process a particular type of payload and you need to therefore ensure the payload type of input Messages. Of course the first thing that comes to mind is Message Filter. However all that Message Filter will do is filter out Messages that are not compliant with the requirements of the consumer. Another way would be to use a Content Based Router and route Messages with non-compliant data-types to specific Transformers to enforce transformation/conversion to the required data-type. This of course would work, but a simpler way of accomplishing the same thing is to apply the Datatype Channel pattern. You can use separate Datatype Channels for each specific payload data-type.

To create a Datatype Channel that only accepts messages containing a certain payload type, provide the fully-qualified class name in the channel element's datatype attribute:

<int:channel id="numberChannel" datatype="java.lang.Number"/>

Note that the type check passes for any type that is assignable to the channel's datatype. In other words, the "numberChannel" above would accept messages whose payload is java.lang.Integer or java.lang.Double. Multiple types can be provided as a comma-delimited list:

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

So the 'numberChannel' above will only accept Messages with a data-type of java.lang.Number. But what happens if the payload of the Message is not of the required type? It depends on whether you have defined a bean named "integrationConversionService" that is an instance of Spring's Conversion Service. If not, then an Exception would be thrown immediately, but if you do have an "integrationConversionService" bean defined, it will be used in an attempt to convert the Message's payload to the acceptable type.

You can even register custom converters. For example, let's say you are sending a Message with a String payload to the 'numberChannel' we configured above.

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

Typically this would be a perfectly legal operation, however since we are using Datatype Channel the result of such operation would generate an exception:

Exception in thread "main" org.springframework.integration.MessageDeliveryException: 
Channel 'numberChannel' 
expected one of the following datataypes [class java.lang.Number], 
but received [class java.lang.String]
…

And rightfully so since we are requiring the payload type to be a Number while sending a String. So we need something to convert String to a Number. All we need to do is implement a Converter.

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

Then, register it as a Converter with the Integration Conversion Service:

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

When the 'converter' element is parsed, it will create the "integrationConversionService" bean on-demand if one is not already defined. With that Converter in place, the send operation would now be successful since the Datatype Channel will use that Converter to convert the String payload to an Integer.

QueueChannel Configuration

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

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

[Note]Note
If you do not provide a value for the 'capacity' attribute on this <queue/> sub-element, the resulting queue will be unbounded. To avoid issues such as OutOfMemoryErrors, it is highly recommended to set an explicit value for a bounded queue.

Persistent QueueChannel Configuration

Since a QueueChannel provides the capability to buffer Messages, but does so in-memory only by default, it also introduces a possibility that Messages could be lost in the event of a system failure. To mitigate this risk, a QueueChannel may be backed by a persistent implementation of the MessageGroupStore strategy interface. For more details on MessageGroupStore and MessageStore see Section 8.3, “Message Store”.

When a QueueChannel receives a Message, it will add it to the Message Store, and when a Message is polled from a QueueChannel, it is removed from the Message Store.

By default any QueueChannel only stores its Messages in an in-memory Queue and can therefore lead to the lost message scenario mentioned above. However Spring Integration provides a JdbcMessageStore to allow a QueueChannel to be backed by an RDBMS.

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

<int:channel id="dbBackedChannel">
    <int:queue message-store="messageStore">
<int:channel id="myChannel">

<int-jdbc:message-store id="messageStore" data-source="someDataSource"/>

The above example also shows that JdbcMessageStore can be configured with the namespace support provided by the Spring Integration JDBC module. All you need to do is inject any javax.sql.DataSource instance. The Spring Integration JDBC module also provides schema DDL for most popular databases. These schemas are located in the org.springframework.integration.jdbc package of that module (spring-integration-jdbc).

[Important]Important
One important feature is that with any transactional persistent store (e.g., JdbcMessageStore), as long as the poller has a transaction configured, a Message removed from the store will only be permanently removed if the transaction completes successfully, otherwise the transaction will roll back and the Message will not be lost.

Many other implementations of the Message Store will be available as the growing number of Spring projects related to "NoSQL" data stores provide the underlying support. Of course, you can always provide your own implementation of the MessageGroupStore interface if you cannot find one that meets your particular needs.

PublishSubscribeChannel Configuration

To create a PublishSubscribeChannel, use the <publish-subscribe-channel/> element. When using this element, you can also specify the task-executor used for publishing Messages (if none is specified it simply publishes in the sender's thread):

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

If you are providing a Resequencer or Aggregator downstream from a PublishSubscribeChannel, then you can set the 'apply-sequence' property on the channel to true. That will indicate that the channel should set the sequence-size and sequence-number Message headers as well as the correlation id prior to passing the Messages along. For example, if there are 5 subscribers, the sequence-size would be set to 5, and the Messages would have sequence-number header values ranging from 1 to 5.

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

[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, the channel creates new Message instances with the same payload reference but different header values when the flag is set to true.

ExecutorChannel

To create an ExecutorChannel, add the <dispatcher> sub-element along with a task-executor attribute. Its value can reference any TaskExecutor within the context. For example, this enables configuration of a thread-pool for dispatching messages to subscribed handlers. As mentioned above, this does break the "single-threaded" execution context between sender and receiver so that any active transaction context will not be shared by the invocation of the handler (i.e. the handler may throw an Exception, but the send invocation has already returned successfully).

<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 above in the section called “DirectChannel Configuration”. The same defaults apply as well. So, the channel will have a round-robin load-balancing strategy with failover enabled unless explicit configuration is provided for one or both of those attributes.
<int:channel id="executorChannelWithoutFailover">
    <int:dispatcher task-executor="someExecutor" failover="false"/>
</int:channel>

PriorityChannel Configuration

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

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

By default, the channel will consult the priority header of the message. However, a custom Comparator reference may be provided instead. Also, note that the PriorityChannel (like the other types) does support the datatype attribute. As with the QueueChannel, it also supports a capacity attribute. The following example demonstrates all of these:

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

RendezvousChannel Configuration

A RendezvousChannel is created when the queue sub-element is a <rendezvous-queue>. It does not provide any additional configuration options to those described above, and its queue does not accept any capacity value since it is a 0-capacity direct handoff queue.

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

Scoped Channel Configuration

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

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

Channel Interceptor Configuration

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

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

In general, it is a good idea to define the interceptor implementations in a separate location since they usually provide common behavior that can be reused across multiple channels.

Global Channel Interceptor Configuration

Channel Interceptors provide a clean and concise way of applying cross-cutting behavior per individual channel. If the same behavior should be applied on multiple channels, configuring the same set of interceptors for each channel would not be the most efficient way. To avoid repeated configuration while also enabling interceptors to apply to multiple channels, Spring Integration provides Global Interceptors. Look at the example below:

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

or

<int:channel-interceptor ref="myInterceptor" pattern="input*, bar*, foo" order="3"/>

<bean id="myInterceptor" class="foo.barSampleInterceptor"/>

Each <channel-interceptor/> element allows you to define a global interceptor which will be applied on all channels that match any patterns defined via the pattern attribute. In the above case the global interceptor will be applied on the 'foo' channel and all other channels that begin with 'bar' or 'input'. The order attribute allows you to manage where this interceptor will be injected if there are multiple interceptors on a given channel. For example, channel 'inputChannel' could have individual interceptors configured locally (see below):

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

A reasonable question is how will a global interceptor be injected in relation to other interceptors configured locally or through other global interceptor definitions? The current implementation provides a very simple mechanism for defining the order of interceptor execution. A positive number in the order attribute will ensure interceptor injection after any existing interceptors and a negative number will ensure that the interceptor is injected before existing interceptors. This means that in the above example, the global interceptor will be injected AFTER (since its order is greater than 0) the 'wire-tap' interceptor configured locally. If there were another global interceptor with a matching pattern, its order would be determined by comparing the values of the order attribute. To inject a global interceptor BEFORE the existing interceptors, use a negative value for the order attribute.

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

Wire Tap

As mentioned above, Spring Integration provides a simple Wire Tap interceptor out of the box. You can configure a Wire Tap on any channel within an <interceptors/> element. This is especially useful for debugging, and can be used in conjunction with Spring Integration's logging Channel Adapter as follows:

 <int:channel id="in">
     <int: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 'payload' and/or 'headers' variables. Alternatively, to simply log the full Message toString() result, provide a value of "true" for the 'log-full-message' attribute. That is false by default so that only the payload is logged. Setting that to true enables logging of all headers in addition to the payload. The 'expression' option does provide the most flexibility, however (e.g. expression="payload.user.name").

A little more on Wire Tap

One of the common misconceptions about the wire tap and other similar components (Section 31.1, “Message Publishing Configuration”) is that they are automatically asynchronous in nature. Wire-tap as a component is not invoked asynchronously be default. Instead, Spring Integration focuses on a single unified approach to configuring asynchronous behavior: the Message Channel. What makes certain parts of the message flow sync or async is the type of Message Channel that has been configured within that flow. That is one of the primary benefits of the Message Channel abstraction. From the inception of the framework, we have always emphasized the need and the value of the Message Channel as a first-class citizen of the framework. It is not just an internal, implicit realization of the EIP pattern, it is fully exposed as a configurable component to the end user. So, the Wire-tap component is ONLY responsible for performing the following 3 tasks:

  • intercept a message flow by tapping into a channel (e.g., channelA)

  • grab each message

  • send the message to another channel (e.g., channelB)

It is essentially a variation of the Bridge, but it is encapsulated within a channel definition (and hence easier to enable and disable without disrupting a flow). Also, unlike the bridge, it basically forks another message flow. Is that flow synchronous or asynchronous? The answer simply depends on the type of Message Channel that 'channelB' is. And, now you know that we have: Direct Channel, Pollable Channel, and Executor Channel as options. The last two do break the thread boundary making communication via such channels asynchronous simply because the dispatching of the message from that channel to its subscribed handlers happens on a different thread than the one used to send the message to that channel. That is what is going to make your wire-tap flow sync or async. It is consistent with other components within the framework (e.g., Message Publisher) and actually brings a level of consistency and simplicity by sparing you from worrying in advance (other than writing thread safe code) whether a particular piece of code should be implemented as sync or async. The actual wiring of two pieces of code (component A and component B) via Message Channel is what makes their collaboration sync or async. You may even want to change from sync to async in the future and Message Channel is what's going to allow you to do it swiftly without ever touching the code.

One final point regarding the Wire Tap is that, despite the rationale provided above for not being async be default, one should keep in mind it is usually desirable to hand off the Message as soon as possible. Therefore, it would be quite common to use an asynchronous channel option as the wire-tap's outbound channel. Nonetheless, another reason that we do not enforce asynchronous behavior by default is that you might not want to break a transactional boundary. Perhaps you are using the Wire Tap for auditing purposes, and you DO want the audit Messages to be sent within the original transaction. As an example, you might connect the wire-tap to a JMS outbound-channel-adapter. That way, you get the best of both worlds: 1) the sending of a JMS Message can occur within the transaction while 2) it is still a "fire-and-forget" action thereby preventing any noticeable delay in the main message flow.

Global Wire Tap Configuration

It is possible to configure a global wire tap as a special case of the Global Channel Interceptor. Simply configure a top level wire-tap element. Now, in addition to the normal wire-tap namespace support, the pattern and order attributes are supported and work in exactly the same way as with the channel-interceptor

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

[Tip]Tip
A global wire tap provides a convenient way to configure a single channel wire tap externally without modifying the existing channel configuration. Simply set the pattern attribute to the target channel name. For example, This technique may be used to configure a test case to verify messages on a channel.

3.1.6 Special Channels

If namespace support is enabled, there are two special channels defined within the application context by default: errorChannel and nullChannel. The 'nullChannel' acts like /dev/null, simply logging any Message sent to it at DEBUG level and returning immediately. Any time you face channel resolution errors for a reply that you don't care about, you can set the affected component's output-channel attribute to 'nullChannel' (the name 'nullChannel' is reserved within the application context). The 'errorChannel' is used internally for sending error messages and may be overridden with a custom configuration. This is discussed in greater detail in Section B.4, “Error Handling”.

3.2 Poller (Polling Consumer)

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

The actual implementation depends on which type of channel these Endpoints are connected to. A channel adapter connected to a channel that implements the org.springframework.integration.core.SubscribableChannel interface will produce an instance of EventDrivenConsumer. On the other hand, a channel adapter connected to a channel that implements the org.springframework.integration.core.PollableChannel interface (e.g. a QueueChannel) will produce an instance of PollingConsumer.

Polling Consumers allow Spring Integration components to actively poll for Messages, rather than to process Messages in an event-driven manner.

They represent a critical cross cutting concern in many messaging scenarios. In Spring Integration, Polling Consumers are based on the pattern with the same name, which is described in the book "Enterprise Integration Patterns" by Gregor Hohpe and Bobby Woolf. You can find a description of the pattern on the book's website at:

Furthermore, in Spring Integration a second variation of the Polling Consumer pattern exists. When Inbound Channel Adapters are being used, these adapters are often wrapped by a SourcePollingChannelAdapter. For example, when retrieving messages from a remote FTP Server location, the adapter described in Section 13.3, “FTP Inbound Channel Adapter” is configured with a poller to retrieve messages periodically. So, when components are configured with Pollers, the resulting instances are of one of the following types:

This means, Pollers are used in both inbound and outbound messaging scenarios. Here are some use-cases that illustrate the scenarios in which Pollers are used:

  • Polling certain external systems such as FTP Servers, Databases, Web Services
  • Polling internal (pollable) Message Channels
  • Polling internal services (E.g. repeatedly execute methods on a Java class)

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

3.3 Channel Adapter

A Channel Adapter is a Message Endpoint that enables connecting a single sender or receiver to a Message Channel. Spring Integration provides a number of adapters out of the box to support various transports, such as JMS, File, HTTP, Web Services, Mail, and more. Those will be discussed in upcoming chapters of this reference guide. However, this chapter focuses on the simple but flexible Method-invoking Channel Adapter support. There are both inbound and outbound adapters, and each may be configured with XML elements provided in the core namespace. These provide an easy way to extend Spring Integration as long as you have a method that can be invoked as either a source or destination.

3.3.1 Configuring An Inbound Channel Adapter

An "inbound-channel-adapter" element can invoke any method on a Spring-managed Object and send a non-null return value to a MessageChannel after converting it to a Message. When the adapter's subscription is activated, a poller will attempt to receive messages from the source. The poller will be scheduled with the TaskScheduler according to the provided configuration. To configure the polling interval or cron expression for an individual channel-adapter, provide a 'poller' element with one of the scheduling attributes, such as 'fixed-rate' or 'cron'.

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

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

[Note]Note

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

[Important]Important

Poller Configuration

Some inbound-channel-adapter types are backed by a SourcePollingChannelAdapter which means they contain Poller configuration which will poll the MessageSource (invoke a custom method which produces the value that becomes a Message payload) based on the configuration specified in the Poller.

For example:

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

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

In the the first configuration the polling task will be invoked once per poll and during such task (poll) the method (which results in the production of the Message) will be invoked once based on the max-messages-per-poll attribute value. In the second configuration the polling task will be invoked 10 times per poll or until it returns 'null' thus possibly producing 10 Messages per poll while each poll happens at 1 second intervals. However what if the configuration looks like this:

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

Note there is no max-messages-per-poll specified. As you'll learn later the identical poller configuration in the PollingConsumer (e.g., service-activator, filter, router etc.) would have a default value of -1 for max-messages-per-poll which means "execute poling task non-stop unless polling method returns null (e.g., no more Messages in the QueueChannel)" and then sleep for 1 second.

However in the SourcePollingChannelAdapter it is a bit different. The default value for max-messages-per-poll will be set to 1 by default unless you explicitly set it to a negative value (e.g., -1). It is done so to make sure that poller can react to a LifeCycle events (e.g., start/stop) and prevent it from potentially spinning in the infinite loop if the implementation of the custom method of the MessageSource has a potential to never return null and happened to be non-interruptible.

However if you are sure that your method can return null and you need the behavior where you want to poll for as many sources as available per each poll, then you should explicitly set max-messages-per-poll to negative value.

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

3.3.2 Configuring Outbound Channel Adapter

An "outbound-channel-adapter" element can also connect a MessageChannel to any POJO consumer method that should be invoked with the payload of Messages sent to that channel.

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

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

If the channel being adapted is a PollableChannel, provide a poller sub-element:

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

</int:outbound-channel-adapter>

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

Using a "ref" attribute is generally recommended if the POJO consumer implementation can be reused in other <outbound-channel-adapter> definitions. However if the consumer implementation is only referenced by a single definition of the <outbound-channel-adapter>, you can define it as inner bean:

<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 will result in an Exception being thrown.

Any Channel Adapter can be created without a "channel" reference in which case it will implicitly create an instance of DirectChannel. The created channel's name will match the "id" attribute of the <inbound-channel-adapter> or <outbound-channel-adapter> element. Therefore, if the "channel" is not provided, the "id" is required.

Like many other Spring Integration components, the <inbound-channel-adapter> and <outbound-channel-adapter> also provide support for SpEL expression evaluation. To use SpEL, provide the expression string via the 'expression' attribute instead of providing the 'ref' and 'method' attributes that are used for method-invocation on a bean. When an Expression is evaluated, it follows the same contract as method-invocation where: the expression for an <inbound-channel-adapter> will generate a message anytime the evaluation result is a non-null value, while the expression for an <outbound-channel-adapter> must be the equivalent of a void returning method invocation.

3.4 Messaging Bridge

3.4.1 Introduction

A Messaging Bridge is a relatively trivial endpoint that simply connects two Message Channels or Channel Adapters. For example, you may want to connect a PollableChannel to a SubscribableChannel so that the subscribing endpoints do not have to worry about any polling configuration. Instead, the Messaging Bridge provides the polling configuration.

By providing an intermediary poller between two channels, a Messaging Bridge can be used to throttle inbound Messages. The poller's trigger will determine the rate at which messages arrive on the second channel, and the poller's "maxMessagesPerPoll" property will enforce a limit on the throughput.

Another valid use for a Messaging Bridge is to connect two different systems. In such a scenario, Spring Integration's role would be limited to making the connection between these systems and managing a poller if necessary. It is probably more common to have at least a Transformer between the two systems to translate between their formats, and in that case, the channels would be provided as the 'input-channel' and 'output-channel' of a Transformer endpoint. If data format translation is not required, the Messaging Bridge may indeed be sufficient.

3.4.2 Configuring Bridge

The <bridge> element is used to create a Messaging Bridge between two Message Channels or Channel Adapters. Simply provide the "input-channel" and "output-channel" attributes:

 <int:bridge input-channel="input" output-channel="output"/>

As mentioned above, a common use case for the Messaging Bridge is to connect a PollableChannel to a SubscribableChannel, and when performing this role, the Messaging Bridge may also serve as a throttler:

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

Connecting Channel Adapters is just as easy. Here is a simple echo example between the "stdin" and "stdout" adapters from Spring Integration's "stream" namespace.

 <int-stream:stdin-channel-adapter id="stdin"/>

 <int-stream:stdout-channel-adapter id="stdout"/>

 <int:bridge id="echo" input-channel="stdin" output-channel="stdout"/>

Of course, the configuration would be similar for other (potentially more useful) Channel Adapter bridges, such as File to JMS, or Mail to File. The various Channel Adapters will be discussed in upcoming chapters.

[Note]Note

If no 'output-channel' is defined on a bridge, the reply channel provided by the inbound Message will be used, if available. If neither output or reply channel is available, an Exception will be thrown.

4. Message Construction

4.1 Message

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

4.1.1 The Message Interface

Here is the definition of the Message interface:

public interface Message<T> {

    T getPayload();

    MessageHeaders getHeaders();

}

The Message is obviously a very important part of the API. By encapsulating the data in a generic wrapper, the messaging system can pass it around without any knowledge of the data's type. As an application evolves to support new types, or when the types themselves are modified and/or extended, the messaging system will not be affected by such changes. On the other hand, when some component in the messaging system does require access to information about the Message, such metadata can typically be stored to and retrieved from the metadata in the Message Headers.

4.1.2 Message Headers

Just as Spring Integration allows any Object to be used as the payload of a Message, it also supports any Object types as header values. In fact, the MessageHeaders class implements the java.util.Map interface:

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

[Note]Note
Even though the MessageHeaders implements Map, it is effectively a read-only implementation. Any attempt to put a value in the Map will result in an UnsupportedOperationException. The same applies for remove and clear. Since Messages may be passed to multiple consumers, the structure of the Map cannot be modified. Likewise, the Message's payload Object can not be set after the initial creation. However, the mutability of the header values themselves (or the payload Object) is intentionally left as a decision for the framework user.

As an implementation of Map, the headers can obviously be retrieved by calling get(..) with the name of the header. Alternatively, you can provide the expected Class as an additional parameter. Even better, when retrieving one of the pre-defined values, convenient getters are available. Here is an example of each of these three options:

 Object someValue = message.getHeaders().get("someKey");

 CustomerId customerId = message.getHeaders().get("customerId", CustomerId.class);

 Long timestamp = message.getHeaders().getTimestamp();
 

The following Message headers are pre-defined:

Table 4.1. Pre-defined Message Headers

Header NameHeader Type
IDjava.util.UUID
TIMESTAMPjava.lang.Long
CORRELATION_IDjava.lang.Object
REPLY_CHANNELjava.lang.Object (can be a String or MessageChannel)
ERROR_CHANNELjava.lang.Object (can be a String or MessageChannel)
SEQUENCE_NUMBERjava.lang.Integer
SEQUENCE_SIZEjava.lang.Integer
EXPIRATION_DATEjava.lang.Long
PRIORITYjava.lang.Integer


Many inbound and outbound adapter implementations will also provide and/or expect certain headers, and additional user-defined headers can also be configured.

4.1.3 Message Implementations

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

new GenericMessage<T>(T payload);

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

When a Message is created, a random unique id will be generated. The constructor that accepts a Map of headers will copy the provided headers to the newly created Message.

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

ErrorMessage message = new ErrorMessage(someThrowable);

Throwable t = message.getPayload();

Notice that this implementation takes advantage of the fact that the GenericMessage base class is parameterized. Therefore, as shown in both examples, no casting is necessary when retrieving the Message payload Object.

4.1.4 The MessageBuilder Helper Class

You may notice that the Message interface defines retrieval methods for its payload and headers but no setters. The reason for this is that a Message cannot be modified after its initial creation. Therefore, when a Message instance is sent to multiple consumers (e.g. through a Publish Subscribe Channel), if one of those consumers needs to send a reply with a different payload type, it will need to create a new Message. As a result, the other consumers are not affected by those changes. Keep in mind, that multiple consumers may access the same payload instance or header value, and whether such an instance is itself immutable is a decision left to the developer. In other words, the contract for Messages is similar to that of an unmodifiable Collection, and the MessageHeaders' map further exemplifies that; even though the MessageHeaders class implements java.util.Map, any attempt to invoke a put operation (or 'remove' or 'clear') on the MessageHeaders will result in an UnsupportedOperationException.

Rather than requiring the creation and population of a Map to pass into the GenericMessage constructor, Spring Integration does provide a far more convenient way to construct Messages: MessageBuilder. The MessageBuilder provides two factory methods for creating Messages from either an existing Message or with a payload Object. When building from an existing Message, the headers and payload of that Message will be copied to the new Message:

Message<String> message1 = MessageBuilder.withPayload("test")
        .setHeader("foo", "bar")
        .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.

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

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

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

Notice that the copyHeadersIfAbsent does not overwrite existing values. Also, in the second example above, you can see how to set any user-defined header with setHeader. Finally, there are set methods available for the predefined headers as well as a non-destructive method for setting any header (MessageHeaders also defines constants for the pre-defined header names).

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

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

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

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

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

5. Message Routing

5.1 Routers

5.1.1 Overview

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

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

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

Table 5.1. Routers Outside of a Chain

Attributerouterheader value routerxpath routerpayload type routerrecipient list routerexception type router
apply-sequence
default-output-channel
resolution-required
ignore-send-failures
timeout
id
auto-startup
input-channel
order
method     
ref     
expression     
header-name     
evaluate-as-string     
xpath-expression-ref     
converter     

Table 5.2. Routers Inside of a Chain

Attributerouterheader value routerxpath routerpayload type routerrecipient list routerexception type router
apply-sequence
default-output-channel
resolution-required
ignore-send-failures
timeout
id      
auto-startup      
input-channel      
order      
method     
ref     
expression     
header-name     
evaluate-as-string     
xpath-expression-ref     
converter     

[Important]Important

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

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

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

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

5.1.2 Common Router Parameters

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 will throw an Exception. If you would like to silently drop those messages instead, add the nullChannel as the default output channel attribute value.

resolution-required

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

ignore-send-failures

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

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

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

This attribute defaults to false.

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 will block indefinitely.

Top-Level (Outside of a Chain)

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

id

Identifies the underlying Spring bean definition which in case of Routers is an instance of EventDrivenConsumer or PollingConsumer depending on whether the Router's input-channel is a SubscribableChannel or PollableChannel, respectively. This is an optional attribute.

auto-startup

This Lifecycle attribute signaled if 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 is using a failover dispatching strategy. It has no effect when this endpoint itself is a Polling Consumer for a channel with a queue.

5.1.3 Router Implementations

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

PayloadTypeRouter

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

<bean id="payloadTypeRouter"
      class="org.springframework.integration.router.PayloadTypeRouter">
    <property name="channelIdentifierMap">
        <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 via the namespace provided by Spring Integration (see Section B.2, “Namespace Support”), which essentially simplifies configuration by combining the <router/> configuration and its corresponding implementation defined using a <bean/> element into a single and more concise configuration element. The example below demonstrates a PayloadTypeRouter configuration which is equivalent to the one above using the namespace support:

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

HeaderValueRouter

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

1. Arbitrary value

2. Channel name

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

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

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

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

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

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

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

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

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

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

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

RecipientListRouter

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

<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 B.2, “Namespace Support”) as the example below demonstrates.

<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>
[Note]Note
The 'apply-sequence' flag here has the same effect as it does for a publish-subscribe-channel, and like a publish-subscribe-channel, it is disabled by default on the recipient-list-router. Refer to 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. This is similar to using a Filter at the beginning of 'chain' to act as a "Selective Consumer". However, in this case, it's all combined rather concisely into the router's configuration.

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

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

XPath Router

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

Routing and Error handling

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

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

5.1.4 Configuring (Generic) Router

Configuring a Content Based Router with XML

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

<int:router ref="payloadTypeRouter" input-channel="input1"
            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 simple POJO that contains the @Router annotation (see below), or the ref may be combined with an explicit method name. Specifying a method applies the same behavior described in the @Router annotation section below.

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

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

<int:router method="someMethod" input-channel="input3"
            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, as it creates an ambiguous condition, and an Exception will be thrown.

Routers and the Spring Expression Language (SpEL)

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

[Note]Note

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

http://static.springsource.org/spring/docs/current/spring-framework-reference/html/expressions.html

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

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

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

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

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

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

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

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

Configuring a Router with Annotations

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

@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 attribute. In this case, a method annotated with @Router may include a parameter annotated with @Header which is mapped to a header value as illustrated below and documented in Section B.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 29, XML Support - Dealing with XML Payloads.

5.1.5 Dynamic Routers

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

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

Example:

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

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

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

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

  • Step 1 - Compute channel identifier which is a value calculated by the router once it receives the Message. Typically it is a String or and instance of the actual MessageChannel.

  • Step 2 - Resolve channel identifier to channel name. We'll describe specifics of this process in a moment.

  • Step 3 - Resolve channel name to the actual MessageChannel

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

Payload Type Router

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

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

  • Step 1 - Compute channel identifier which is the fully qualified name of the payload type (e.g., java.lang.String).

  • Step 2 - Resolve channel identifier to channel name where the result of the previous step is used to select the appropriate value from the payload type mapping defined via mapping element.

  • Step 3 - Resolve channel name to the actual instance of the MessageChannel as a reference to a bean within the Application Context (which is hopefully a MessageChannel) identified by the result of the previous step.

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

Header Value Router

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

Similar to the PayloadTypeRouter:

  • Step 1 - Compute channel identifier which is the value of the header identified by the header-name attribute.

  • Step 2 - Resolve channel identifier to channel name where the result of the previous step is used to select the appropriate value from the general mapping defined via mapping element.

  • Step 3 - Resolve channel name to the actual instance of the MessageChannel as a reference to a bean within the Application Context (which is hopefully a MessageChannel) identified by the result of the previous step.

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

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

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

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

For Example:

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

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

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

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

In Spring Integration 2.0 the router hierarchy underwent significant refactoring, so that now any router that is a subclass of the AbstractMessageRouter (which includes all framework defined routers) is a Dynamic Router simply because the channelIdentiferMap is defined at the AbstractMessageRouter level. That map's setter method is exposed as a public method along with 'setChannelMapping' and 'removeChannelMapping' methods. These allow you to change/add/remove router mappings at runtime as long as you have a reference to the router itself. It also means that you could expose these same configuration options via JMX (see Section 8.1, “JMX Support”) or the Spring Integration ControlBus (see Section 8.4, “Control Bus”) functionality. 

Manage Router Mappings using the Control Bus

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

[Note]Note

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

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

  • public void setChannelMapping(String channelIdentifier, String channelName) - will allow you to add a new or modify an existing mapping between channel identifier and channel name

  • public void removeChannelMapping(String channelIdentifier) - will allow you to remove a particular channel mapping, thus disconnecting the relationship between channel identifier and channel name

Manage Router Mappings using JMX

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

[Note]Note

For more information about Spring Integration's JMX suppor, please see chapter JMX Support.

5.2 Filter

5.2.1 Introduction

Message Filters are used to decide whether a Message should be passed along or dropped based on some criteria such as a Message Header value or Message content itself. Therefore, a Message Filter is similar to a router, except that for each Message received from the filter's input channel, that same Message may or may not be sent to the filter's output channel. Unlike the router, it makes no decision regarding which Message Channel to send the Message to but only decides whether to send.

[Note]Note
As you will see momentarily, the Filter also supports a discard channel, so in certain cases it can play the role of a very simple router (or "switch") based on a boolean condition.

In Spring Integration, a Message Filter may be configured as a Message Endpoint that delegates to an implementation of the MessageSelector interface. That interface is itself quite simple:

 public interface MessageSelector {

     boolean accept(Message<?> message);

 }

The MessageFilter constructor accepts a selector instance:

 MessageFilter filter = new MessageFilter(someSelector);

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

5.2.2 Configuring Filter

Configuring a Filter with XML

The <filter> element is used to create a Message-selecting endpoint. In addition to "input-channel and output-channel attributes, it requires a ref. The ref may point to a MessageSelector implementation:

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

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

Alternatively, the method attribute can be added at which point the ref may refer to any object. The referenced method may expect either the Message type or the payload type of inbound Messages. The method must return a boolean value. If the method returns 'true', the Message will be sent to the output-channel.

 <int:filter input-channel="input" output-channel="output"
         ref="exampleObject" method="someBooleanReturningMethod"/>

 <bean id="exampleObject" class="example.SomeObject"/>

If the selector or adapted POJO method returns false, there are a few settings that control the handling of the rejected Message. By default (if configured like the example above), rejected Messages will be silently dropped. If rejection should instead result in an error condition, then set the throw-exception-on-rejection attribute to true:

 <int:filter input-channel="input" ref="selector"
      output-channel="output" throw-exception-on-rejection="true"/> 

If you want rejected messages to be routed to a specific channel, provide that reference as the discard-channel:

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

[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 (e.g. Service Activator). This provides a reactive alternative to the more proactive approach of using a Message Router with a single Point-to-Point input channel and multiple output channels.

Using a ref attribute is generally recommended if the custom filter implementation is referenced in other <filter> definitions. However if the custom filter implementation is scoped to a single <filter> element, provide an inner bean definition:

<int:filter method="someMethod" input-channel="inChannel" output-channel="outChannel">
  <beans:bean class="org.foo.MyCustomFilter"/>
</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 an Exception will be thrown.

With the introduction of SpEL support, Spring Integration added the expression attribute to the filter element. It can be used to avoid Java entirely for simple filters.

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

The string passed as the expression attribute will be evaluated as a SpEL expression with the Message available in the evaluation context. If it is necessary to include the result of an expression in the scope of the application context you can use the #{} notation as defined in the SpEL reference documentation .

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

If the Expression itself needs to be dynamic, then an 'expression' sub-element may be used. That provides a level of indirection for resolving the Expression by its key from an ExpressionSource. That is a strategy interface that you can implement directly, or you can rely upon a version available in Spring Integration that loads Expressions from a "resource bundle" and can check for modifications after a given number of seconds. All of this is demonstrated in the following configuration sample where the Expression could be reloaded within one minute if the underlying file had been modified. If the ExpressionSource bean is named "expressionSource", then it is not necessary to provide the source attribute on the <expression> element, but in this case it's shown for completeness.

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

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

Then, the 'config/integration/expressions.properties' file (or any more specific version with a locale extension to be resolved in the typical way that resource-bundles are loaded) would contain a key/value pair:

  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. Of course, the semantics/role of the given component type would affect the interpretation of the evaluation result in the same way that the return value of a method-invocation would be interpreted. For example, an expression can return Strings that are to be treated as Message Channel names by a router component. However, the underlying functionality of evaluating the expression against the Message as the root object, and resolving bean names if prefixed with '@' is consistent across all of the core EIP components within Spring Integration.

Configuring a Filter with Annotations

A filter configured using annotations would look like this.

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

1

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

All of the configuration options provided by the xml element are also available for the @Filter annotation.

The filter can be either referenced explicitly from XML or, if the @MessageEndpoint annotation is defined on the class, detected automatically through classpath scanning.

5.3 Splitter

5.3.1 Introduction

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

5.3.2 Programming model

The API for performing splitting consists of one base class, AbstractMessageSplitter, which is a MessageHandler implementation, encapsulating features which are common to splitters, such as filling in the appropriate message headers CORRELATION_ID, SEQUENCE_SIZE, and SEQUENCE_NUMBER on the messages that are produced. This enables tracking down the messages and the results of their processing (in a typical scenario, these headers would be copied over to the messages that are produced by the various transforming endpoints), and use them, for example, in a Composed Message Processor scenario.

An excerpt from AbstractMessageSplitter can be seen below:

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

}

To implement a specific Splitter in an application, extend AbstractMessageSplitter and implement the splitMessage method, which contains logic for splitting the messages. The return value may be one of the following:

  • a Collection (or subclass thereof) or an array of Message objects - in this case the messages will be sent as such (after the CORRELATION_ID, SEQUENCE_SIZE and SEQUENCE_NUMBER are populated). Using this approach gives more control to the developer, for example for populating custom message headers as part of the splitting process.

  • a Collection (or subclass thereof) or an array of non-Message objects - works like the prior case, except that each collection element will be used as a Message payload. Using this approach allows developers to focus on the domain objects without having to consider the Messaging system and produces code that is easier to test.

  • a Message or non-Message object (but not a Collection or an Array) - it works like the previous cases, except a single message will be sent out.

In Spring Integration, any POJO can implement the splitting algorithm, provided that it defines a method that accepts a single argument and has a return value. In this case, the return value of the method will be interpreted as described above. The input argument might either be a Message or a simple POJO. In the latter case, the splitter will receive the payload of the incoming message. Since this decouples the code from the Spring Integration API and will typically be easier to test, it is the recommended approach.

5.3.3 Configuring Splitter

Configuring a Splitter using XML

A splitter can be configured through XML as follows:

<int:channel id="inputChannel"/>

<int:splitter id="splitter" 1
  ref="splitterBean" 2
  method="split" 3
  input-channel="inputChannel" 4
  output-channel="outputChannel" 5/>

<int:channel id="outputChannel"/>

<beans:bean id="splitterBean" class="sample.PojoSplitter"/>

1

The id of the splitter is optional.

2

A reference to a bean defined in the application context. The bean must implement the splitting logic as described in the section above .Optional. If reference to a bean is not provided, then it is assumed that the payload of the Message that arrived on the input-channel is an implementation of java.util.Collection and the default splitting logic will be applied to the Collection, incorporating each individual element into a Message and sending it to the output-channel.

3

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

4

The input channel of the splitter. Required.

5

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

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

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

[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 will result in an Exception being thrown.

Configuring a Splitter with Annotations

The @Splitter annotation is applicable to methods that expect either the Message type or the message payload type, and the return values of the method should be a Collection of any type. If the returned values are not actual Message objects, then each item will be wrapped in a Message as its payload. Each message will be sent to the designated output channel for the endpoint on which the @Splitter is defined.

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

5.4 Aggregator

5.4.1 Introduction

Basically a mirror-image of the Splitter, the Aggregator is a type of Message Handler that receives multiple Messages and combines them into a single Message. In fact, an Aggregator is often a downstream consumer in a pipeline that includes a Splitter.

Technically, the Aggregator is more complex than a Splitter, because it is stateful as it must hold the Messages to be aggregated and determine when the complete group of Messages is ready to be aggregated. In order to do this it requires a MessageStore.

5.4.2 Functionality

The Aggregator combines a group of related messages, by correlating and storing them, until the group is deemed complete. At that point, the Aggregator will create a single message by processing the whole group, and will send the aggregated message as output.

Implementing an Aggregator requires providing the logic to perform the aggregation (i.e., the creation of a single message from many). Two related concepts are correlation and release.

Correlation determines how messages are grouped for aggregation. In Spring Integration correlation is done by default based on the CORRELATION_ID message header. Messages with the same CORRELATION_ID will be grouped together. However, the correlation strategy may be customized to allow other ways of specifying how the messages should be grouped together by implementing a CorrelationStrategy (see below).

To determine the point at which a group of messages is ready to be processed, a ReleaseStrategy is consulted. The default release strategy for the Aggregator will release a group when all messages included in a sequence are present, based on the SEQUENCE_SIZE header. This default strategy may be overridden by providing a reference to a custom ReleaseStrategy implementation.

5.4.3 Programming model

The Aggregation API consists of a number of classes:

  • The interface MessageGroupProcessor, and its subclasses: MethodInvokingAggregatingMessageGroupProcessor and ExpressionEvaluatingMessageGroupProcessor

  • The ReleaseStrategy interface and its default implementation SequenceSizeReleaseStrategy

  • The CorrelationStrategy interface and its default implementation HeaderAttributeCorrelationStrategy

CorrelatingMessageHandler

The CorrelatingMessageHandler is a MessageHandler implementation, encapsulating the common functionalities of an Aggregator (and other correlating use cases), which are:

  • correlating messages into a group to be aggregated

  • maintaining those messages in a MessageStore until the group can be released

  • deciding when the group can be released

  • aggregating the released group into a single message

  • recognizing and responding to an expired group

The responsibility of deciding how the messages should be grouped together is delegated to a CorrelationStrategy instance. The responsibility of deciding whether the message group can be released is delegated to a ReleaseStrategy instance.

Here is a brief highlight of the base AbstractAggregatingMessageGroupProcessor (the responsibility of implementing the aggregatePayloads method is left to the developer):

public abstract class AbstractAggregatingMessageGroupProcessor
              implements MessageGroupProcessor {

    protected Map<String, Object> aggregateHeaders(MessageGroup group) {
        // default implementation exists
    }

  	protected abstract Object aggregatePayloads(MessageGroup group, Map<String, Object> defaultHeaders);

}
The CorrelationStrategy is owned by the CorrelatingMessageHandler and it has a default value based on the CORRELATION_ID message header:
    public CorrelatingMessageHandler(MessageGroupProcessor processor, MessageGroupStore store,
                   CorrelationStrategy correlationStrategy, ReleaseStrategy releaseStrategy) {
     ...
      this.correlationStrategy = correlationStrategy == null ?
        new HeaderAttributeCorrelationStrategy(MessageHeaders.CORRELATION_ID) : correlationStrategy;
      this.releaseStrategy = releaseStrategy == null ? new SequenceSizeReleaseStrategy() : releaseStrategy;
      ...
  }

As for actual processing of the message group, the default implementation is the DefaultAggregatingMessageGroupProcessor. It creates a single Message whose payload is a List of the payloads received for a given group. This works well for simple Scatter Gather implementations with either a Splitter, Publish Subscribe Channel, or Recipient List Router upstream.

[Note]Note

When using a Publish Subscribe Channel or Recipient List Router in this type of scenario, be sure to enable the flag to apply-sequence. That will add the necessary headers (CORRELATION_ID, SEQUENCE_NUMBER and SEQUENCE_SIZE). That behavior is enabled by default for Splitters in Spring Integration, but it is not enabled for the Publish Subscribe Channel or Recipient List Router because those components may be used in a variety of contexts in which these headers are not necessary.

When implementing a specific aggregator strategy for an application, a developer can extend AbstractAggregatingMessageGroupProcessor and implement the aggregatePayloads method. However, there are better solutions, less coupled to the API, for implementing the aggregation logic which can be configured easily either through XML or through annotations.

In general, any POJO can implement the aggregation algorithm if it provides a method that accepts a single java.util.List as an argument (parameterized lists are supported as well). This method will be invoked for aggregating messages as follows:

  • if the argument is a java.util.List<T>, and the parameter type T is assignable to Message, then the whole list of messages accumulated for aggregation will be sent to the aggregator

  • if the argument is a non-parameterized java.util.List or the parameter type is not assignable to Message, then the method will receive the payloads of the accumulated messages

  • if the return type is not assignable to Message, then it will be treated as the payload for a Message that will be created automatically by the framework.

[Note]Note

In the interest of code simplicity, and promoting best practices such as low coupling, testability, etc., the preferred way of implementing the aggregation logic is through a POJO, and using the XML or annotation support for configuring it in the application.

ReleaseStrategy

The ReleaseStrategy interface is defined as follows:

public interface ReleaseStrategy {

  boolean canRelease(MessageGroup group);

}

In general, any POJO can implement the completion decision logic if it provides a method that accepts a single java.util.List as an argument (parameterized lists are supported as well), and returns a boolean value. This method will be invoked after the arrival of each new message, to decide whether the group is complete or not, as follows:

  • if the argument is a java.util.List<T>, and the parameter type T is assignable to Message, then the whole list of messages accumulated in the group will be sent to the method

  • if the argument is a non-parametrized java.util.List or the parameter type is not assignable to Message, then the method will receive the payloads of the accumulated messages

  • the method must return true if the message group is ready for aggregation, and false otherwise.

For example:
public class MyReleaseStrategy {

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

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

As you can see based on the above signatures, the POJO-based Release Strategy will be passed a Collection of unmarked Messages if you need access to the whole Message or Collection of payload objects if the type parameter is anything other than Message. Typically this would satisfy the majority of use cases. However if for some reason you need to access the full MessageGroup - which contains unmarked and marked Messages - then you should simply provide an implementation of the ReleaseStrategy interface.

When the group is released for aggregation, all its unmarked messages are processed and then marked so they will not be processed again. If the group is also complete (i.e. if all messages from a sequence have arrived or if there is no sequence defined), then the group is removed from the message store. Partial sequences can be released, in which case the next time the ReleaseStrategy is called it will be presented with a group containing marked messages (already processed) and unmarked messages (potentially a new partial sequence).

Spring Integration provides an out-of-the box implementation for ReleaseStrategy, the SequenceSizeReleaseStrategy. This implementation consults the SEQUENCE_NUMBER and SEQUENCE_SIZE headers of each arriving message to decide when a message group is complete and ready to be aggregated. As shown above, it is also the default strategy.

CorrelationStrategy

The CorrelationStrategy interface is defined as follows:

public interface CorrelationStrategy {

  Object getCorrelationKey(Message<?> message);

}

The method returns an Object which represents the correlation key used for associating the message with a message group. The key must satisfy the criteria used for a key in a Map with respect to the implementation of equals() and hashCode().

In general, any POJO can implement the correlation logic, and the rules for mapping a message to a method's argument (or arguments) are the same as for a ServiceActivator (including support for @Header annotations). The method must return a value, and the value must not be null.

Spring Integration provides an out-of-the box implementation for CorrelationStrategy, the HeaderAttributeCorrelationStrategy. This implementation returns the value of one of the message headers (whose name is specified by a constructor argument) as the correlation key. By default, the correlation strategy is a HeaderAttributeCorrelationStrategy returning the value of the CORRELATION_ID header attribute. If you have a custom header name you would like to use for correlation, then simply configure that on an instance of HeaderAttributeCorrelationStrategy and provide that as a reference for the Aggregator's correlation-strategy.

5.4.4 Configuring Aggregator

Configuring an Aggregator with XML

Spring Integration supports the configuration of an aggregator via XML through the <aggregator/> element. Below you can see an example of an aggregator.

<channel id="inputChannel"/>


<int:aggregator id="myAggregator" 1
		auto-startup="true" 2
		input-channel="inputChannel" 3
		output-channel="outputChannel" 4
		discard-channel="throwAwayChannel" 5
		message-store="persistentMessageStore" 6
		order="1" 7
		send-partial-result-on-expiry="false" 8
		send-timeout="1000" 9
		
		correlation-strategy="correlationStrategyBean" 10
		correlation-strategy-method="correlate" 11
		
		ref="aggregatorBean" 12
		method="aggregate" 13
			
		release-strategy="releaseStrategyBean" 14
		release-strategy-method="release"/> 15


<int:channel id="outputChannel"/>

<int:channel id="throwAwayChannel"/>

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

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

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

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

1

The id of the aggregator is 0ptional.

2

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

3

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

4

The channel to which the aggregator will send the aggregation results. Optional (because incoming messages can specify a reply channel themselves via 'replyChannel' Message Header).

5

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

6

A reference to a MessageGroupStore used to store groups of messages under their correlation key until they are complete. Optional, by default a volatile in-memory store.

7

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

8

Indicates that expired messages should be aggregated and sent to the 'output-channel' or 'replyChannel' once their containing MessageGroup is expired (see MessageGroupStore.expireMessageGroups(long)). One way of expiring MessageGroups is by configuring a MessageGroupStoreReaper. However MessageGroups can alternatively be expired by simply calling MessageGroupStore.expireMessageGroup(groupId). That could be accomplished via a Control Bus operation or by simply invoking that method if you have a reference to the MessageGroupStore instance. Otherwise by itself this attribute has no behavior. It only serves as an indicator of what to do (discard or send to the output/reply channel) with Messages that are still in the MessageGroup that is about to be expired. Optional.

Default - 'false'.

9

The timeout interval for sending the aggregated messages to the output or reply channel. Optional.

10

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

11

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

12

A reference to a bean defined in the application context. The bean must implement the aggregation logic as described above. Optional (by default the list of aggregated Messages will become a payload of the output message).

13

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

14

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

15

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

Using a ref attribute is generally recommended if a custom aggregator handler implementation may be referenced in other <aggregator> definitions. However if a custom aggregator implementation is only being used by a single definition of the <aggregator>, you can use an inner bean definition (starting with version 1.0.3) to configure the aggregation POJO within the <aggregator> element:

<aggregator input-channel="input" method="sum" output-channel="output">
    <beans:bean class="org.foo.PojoAggregator"/>
</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 will be thrown.

An example implementation of the aggregator bean looks as follows:

public class PojoAggregator {

  public Long add(List<Long> results) {
    long total = 0l;
    for (long partialResult: results) {
      total += partialResult;
    }
    return total;
  }

}

An implementation of the completion strategy bean for the example above may be as follows:

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

[Note]Note

Wherever it makes sense, the release strategy method and the aggregator method can be combined in a single bean.

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

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

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

[Note]Note

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

Aggregators and Spring Expression Language (SpEL)

Since Spring Integration 2.0, the various strategies (correlation, release, and aggregation) may be handled with SpEL which is recommended if the logic behind such release strategy is relatively simple. Let's say you have a legacy component that was designed to receive an array of objects. We know that the default release strategy will assemble all aggregated messages in the List. So now we have two problems. First we need to extract individual messages from the list, and then we need to extract the payload of each message and assemble the array of objects (see code below).

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

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

In the above configuration we are using a Collection Projection expression to assemble a new collection from the payloads of all messages in the list and then transforming it to an Array, thus achieving the same result as the java code above.

The same expression-based approach can be applied when dealing with custom Release and Correlation strategies.

Instead of defining a bean for a custom CorrelationStrategy via the correlation-strategy attribute, you can implement your simple correlation logic via a SpEL expression and configure it via the correlation-strategy-expression attribute.

For example:

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

In the above example it is assumed that the payload has an attribute person with an id which is going to be used to correlate messages.

Likewise, for the ReleaseStrategy you can implement your release logic as a SpEL expression and configure it via the release-strategy-expression attribute. The only difference is that since ReleaseStrategy is passed the List of Messages, the root object in the SpEL evaluation context is the List itself. That List can be referenced as #this within the expression.

For example:

release-strategy-expression="#this.size() gt 5"

In this example the root object of the SpEL Evaluation Context is the MessageGroup itself, and you are simply stating that as soon as there are more than 5 messages in this group, it should be released.

Configuring an Aggregator with Annotations

An aggregator configured using annotations would look like this.

public class Waiter {
  ... 

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

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

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

}

1

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

2

An annotation indicating that this method shall be used as the release strategy of an aggregator. If not present on any method, the aggregator will use the SequenceSizeReleaseStrategy.

3

An annotation indicating that this method shall be used as the correlation strategy of an aggregator. If no correlation strategy is indicated, the aggregator will use the HeaderAttributeCorrelationStrategy based on CORRELATION_ID.

All of the configuration options provided by the xml element are also available for the @Aggregator annotation.

The aggregator can be either referenced explicitly from XML or, if the @MessageEndpoint is defined on the class, detected automatically through classpath scanning.

5.4.5 Managing State in an Aggregator: MessageGroupStore

Aggregator (and some other patterns in Spring Integration) is a stateful pattern that requires decisions to be made based on a group of messages that have arrived over a period of time, all with the same correlation key. The design of the interfaces in the stateful patterns (e.g. ReleaseStrategy) is driven by the principle that the components (whether defined by the framework or a user) should be able to remain stateless. All state is carried by the MessageGroup and its management is delegated to the MessageGroupStore.

public interface MessageGroupStore {
   int getMessageCountForAllMessageGroups();

   int getMarkedMessageCountForAllMessageGroups();

   int getMessageGroupCount();

   MessageGroup getMessageGroup(Object groupId);

   MessageGroup addMessageToGroup(Object groupId, Message<?> message);

   MessageGroup markMessageGroup(MessageGroup group);

   MessageGroup removeMessageFromGroup(Object key, Message<?> messageToRemove);

   MessageGroup markMessageFromGroup(Object key, Message<?> messageToMark);

   void removeMessageGroup(Object groupId);

   void registerMessageGroupExpiryCallback(MessageGroupCallback callback);

   int expireMessageGroups(long timeout);
}

For more information please refer to the JavaDoc.

The MessageGroupStore accumulates state information in MessageGroups while waiting for a release strategy to be triggered, and that event might not ever happen. So to prevent stale messages from lingering, and for volatile stores to provide a hook for cleaning up when the application shuts down, the MessageGroupStore allows the user to register callbacks to apply to its MessageGroups when they expire. The interface is very straightforward:

public interface MessageGroupCallback {

  void execute(MessageGroupStore messageGroupStore, MessageGroup group);

}

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

The MessageGroupStore maintains a list of these callbacks which it applies, on demand, to all messages whose timestamp is earlier than a time supplied as a parameter (see the registerMessageGroupExpiryCallback(..) and expireMessageGroups(..) methods above).

The expireMessageGroups method can be called with a timeout value. Any message older than the current time minus this value will be expired, and have the callbacks applied. Thus it is the user of the store that defines what is meant by message group "expiry".

As a convenience for users, Spring Integration provides a wrapper for the message expiry in the form of a MessageGroupStoreReaper:

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

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

The reaper is a Runnable, and all that is happening in the example above is that the message group store's expire method is being called once every 10 seconds. The timeout itself is 30 seconds.

[Note]Note
It is important to understand that the 'timeout' property of the MessageGroupStoreReaper is an approximate value and is impacted by the the rate of the task scheduler since this property will only be checked on the next scheduled execution of the MessageGroupStoreReaper task. For example if the timeout is set for 10 min, but the MessageGroupStoreReaper task is scheduled to run every 60 min and the last execution of the MessageGroupStoreReaper task happened 1 min before the timeout, the MessageGroup will not expire for the next 59 min. So it is recommended to set the rate at least equal to the value of the timeout or shorter.

In addition to the reaper, the expiry callbacks are invoked when the application shuts down via a lifecycle callback in the CorrelatingMessageHandler.

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

5.5 Resequencer

5.5.1 Introduction

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

5.5.2 Functionality

The Resequencer works in a similar way to the Aggregator, in the sense that it uses the CORRELATION_ID to store messages in groups, the difference being that the Resequencer does not process the messages in any way. It simply releases them in the order of their SEQUENCE_NUMBER header values.

With respect to that, the user might opt to release all messages at once (after the whole sequence, according to the SEQUENCE_SIZE, has been released), or as soon as a valid sequence is available.

5.5.3 Configuring a Resequencer

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

A sample resequencer configuration is shown below.

<int:channel id="inputChannel"/>

<int:channel id="outputChannel"/>

<int:resequencer id="completelyDefinedResequencer" 1
  input-channel="inputChannel" 2
  output-channel="outputChannel" 3
  discard-channel="discardChannel" 4
  release-partial-sequences="true" 5
  message-store="messageStore" 6
  send-partial-result-on-expiry="true" 7
  send-timeout="86420000" 8 /> 

1

The id of the resequencer is optional.

2

The input channel of the resequencer. Required.

3

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

4

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

5

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

If this flag is not specified (so a complete sequence is defined by the sequence headers) then it may make sense to provide a custom Comparator to be used to order the messages when sending (use the XML attribute comparator to point to a bean definition). If release-partial-sequences is true then there is no way with a custom comparator to define a partial sequence. To do that you would have to provide a release-strategy (also a reference to another bean definition, either a POJO or a ReleaseStrategy ).

6

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

7

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

8

The timeout for sending out messages. Optional.

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

5.6 Message Handler Chain

5.6.1 Introduction

The MessageHandlerChain is an implementation of MessageHandler that can be configured as a single Message Endpoint while actually delegating to a chain of other handlers, such as Filters, Transformers, Splitters, and so on. This can lead to a much simpler configuration when several handlers need to be connected in a fixed, linear progression. For example, it is fairly common to provide a Transformer before other components. Similarly, when providing a Filter before some other component in a chain, you are essentially creating a Selective Consumer. In either case, the chain only requires a single input-channel and a single output-channel eliminating the need to define channels for each individual component.

[Tip]Tip
Spring Integration's Filter provides a boolean property throwExceptionOnRejection. When providing multiple Selective Consumers on the same point-to-point channel with different acceptance criteria, this value should be set to 'true' (the default is false) so that the dispatcher will know that the Message was rejected and as a result will attempt to pass the Message on to other subscribers. If the Exception were not thrown, then it would appear to the dispatcher as if the Message had been passed on successfully even though the Filter had dropped the Message to prevent further processing. If you do indeed want to "drop" the Messages, then the Filter's 'discard-channel' might be useful since it does give you a chance to perform some operation with the dropped message (e.g. send to a JMS queue or simply write to a log).

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

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

[Note]Note

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

In most cases there is no need to implement MessageHandlers yourself. The next section will focus on namespace support for the chain element. Most Spring Integration endpoints, like Service Activators and Transformers, are suitable for use within a MessageHandlerChain.

5.6.2 Configuring Chain

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

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

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

The <chain> can be configured as the last 'black-box' consumer of the message flow. For this solution it is enough to put at the end of the <chain> some <outbound-channel-adapter>:

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

Sometimes you need to make a nested call to another chain from within a chain and then come back and continue execution within the original chain. To accomplish this you can utilize a Messaging Gateway by including a <gateway> element. For example:

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

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

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

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

6. Message Transformation

6.1 Transformer

6.1.1 Introduction

Message Transformers play a very important role in enabling the loose-coupling of Message Producers and Message Consumers. Rather than requiring every Message-producing component to know what type is expected by the next consumer, Transformers can be added between those components. Generic transformers, such as one that converts a String to an XML Document, are also highly reusable.

For some systems, it may be best to provide a Canonical Data Model, but Spring Integration's general philosophy is not to require any particular format. Rather, for maximum flexibility, Spring Integration aims to provide the simplest possible model for extension. As with the other endpoint types, the use of declarative configuration in XML and/or Annotations enables simple POJOs to be adapted for the role of Message Transformers. These configuration options will be described below.

[Note]Note
For the same reason of maximizing flexibility, Spring does not require XML-based Message payloads. Nevertheless, the framework does provide some convenient Transformers for dealing with XML-based payloads if that is indeed the right choice for your application. For more information on those transformers, see Chapter 29, XML Support - Dealing with XML Payloads.

6.1.2 Configuring Transformer

Configuring Transformer with XML

The <transformer> element is used to create a Message-transforming endpoint. In addition to "input-channel" and "output-channel" attributes, it requires a "ref". The "ref" may either point to an Object that contains the @Transformer annotation on a single method (see below) or it may be combined with an explicit method name value provided via the "method" attribute.

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

Using a "ref" attribute is generally recommended if the custom transformer handler implementation can be reused in other <transformer> definitions. However if the custom transformer handler implementation should be scoped to a single definition of the <transformer>, you can define an inner bean definition:

<int:transformer id="testTransformer" input-channel="inChannel" method="transform"
                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 will result in an Exception being thrown.

The method that is used for transformation may expect either the Message type or the payload type of inbound Messages. It may also accept Message header values either individually or as a full map by using the @Header and @Headers parameter annotations respectively. The return value of the method can be any type. If the return value is itself a Message, that will be passed along to the transformer's output channel.

As of Spring Integration 2.0, a Message Transformer's transformation method can no longer return null. Returning null will result in an exception since a Message Transformer should always be expected to transform each source Message into a valid target Message. In other words, a Message Transformer should not be used as a Message Filter since there is a dedicated <filter> option for that. However, if you do need this type of behavior (where a component might return NULL and that should not be considered an error), a service-activator could be used. Its requires-reply value is FALSE by default, but that can be set to TRUE in order to have Exceptions thrown for NULL return values as with the transformer.

Transformers and Spring Expression Language (SpEL)

Just like Routers, Aggregators and other components, as of Spring Integration 2.0 Transformers can also benefit from SpEL support (http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html) whenever transformation logic is relatively simple.

<int:transformer input-channel="inChannel" 
	output-channel="outChannel" 
	expression="payload.toUpperCase() + '- [' + T(java.lang.System).currentTimeMillis() + ']'"/>

In the above configuration we are achieving a simple transformation of the payload with a simple SpEL expression and without writing a custom transformer. Our payload (assuming String) will be upper-cased and concatenated with the current timestamp with some simple formatting.

Common Transformers

There are also a few Transformer implementations available out of the box. Because, it is fairly common to use the toString() representation of an Object, Spring Integration provides an ObjectToStringTransformer whose output is a Message with a String payload. That String is the result of invoking the toString() operation on the inbound Message's payload.

 <int:object-to-string-transformer input-channel="in" output-channel="out"/>

A potential example for this would be sending some arbitrary object to the 'outbound-channel-adapter' in the file namespace. Whereas that Channel Adapter only supports String, byte-array, or java.io.File payloads by default, adding this transformer immediately before the adapter will handle the necessary conversion. Of course, that works fine as long as the result of the toString() call is what you want to be written to the File. Otherwise, you can just provide a custom POJO-based Transformer via the generic 'transformer' element shown previously.

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

If you need to serialize an Object to a byte array or deserialize a byte array back into an Object, Spring Integration provides symmetrical serialization transformers. These will use standard Java serialization by default, but you can provide an implementation of Spring 3.0's Serializer or Deserializer strategies via the 'serializer' and 'deserializer' attributes, respectively.

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

 <int:payload-deserializing-transformer input-channel="bytesIn" output-channel="objectsOut"/>

Object-to-Map Transformer

Spring Integration also provides Object-to-Map and Map-to-Object transformers which utilize the Spring Expression Language (SpEL) to serialize and de-serialize the object graphs. The object hierarchy is introspected to the most primitive types (String, int, etc.). The path to this type is described via SpEL, which becomes the key in the transformed Map. The primitive type becomes the value.

For example:

public class Parent{
    private Child child;
    private String name; 
    // setters and getters are omitted
}

public class Child{
   private String name; 
   private List<String> nickNames;
   // setters and getters are omitted
}

... will be transformed to a Map which looks like this: {person.name=George, person.child.name=Jenna, person.child.nickNames[0]=Bimbo . . . etc}

The SpEL-based Map allows you to describe the object structure without sharing the actual types allowing you to restore/rebuild the object graph into a differently typed Object graph as long as you maintain the structure.

For example: The above structure could be easily restored back to the following Object graph via the Map-to-Object transformer:

public class Father {
    private Kid child;
    private String name; 
    // setters and getters are omitted
}

public class Kid {
   private String name; 
   private List<String> nickNames;
   // setters and getters are omitted
}

To configure these transformers, Spring Integration provides namespace support Object-to-Map:

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

Map-to-Object

<int:map-to-object-transformer input-channel="input" 
                         output-channel="output" 
                          type="org.foo.Person"/>

or

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

[Note]Note
NOTE: 'ref' and 'type' attributes are mutually exclusive. You can only use one. Also, if using the 'ref' attribute, you must point to a 'prototype' scoped bean, otherwise a BeanCreationException will be thrown. 

JSON Transformers

Object to JSON and JSON to Object transformers are provided.

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

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

These use a vanilla Jackson ObjectMapper by default. If you wish to customize the ObjectMapper (for example, to configure the 'ALLOW_COMMENTS' feature when parsing JSON), you can supply a reference to your custom ObjectMapper bean using the object-mapper attribute.

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

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

public class ObjectMapperFactory {
    
    public static ObjectMapper getMapper() {
        ObjectMapper mapper = new ObjectMapper();
        mapper.configure(JsonParser.Feature.ALLOW_COMMENTS, true);
        return mapper;
    }
}

<bean id="customObjectMapper" class="foo.ObjectMapperFactory"
            factory-method="getMapper"/>

Configuring a Transformer with Annotations

The @Transformer annotation can also be added to methods that expect either the Message type or the message payload type. The return value will be handled in the exact same way as described above in the section describing the <transformer> element.

@Transformer
Order generateOrder(String productId) {
    return new Order(productId);
}

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

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

6.1.3 Header Filter

Some times your transformation use case might be as simple as removing a few headers. For such a use case, Spring Integration provides a Header Filter which allows you to specify certain header names that should be removed from the output Message (e.g. for security reasons or a value that was only needed temporarily). Basically the Header Filter is the opposite of the Header Enricher. The latter is discussed in Section 6.2.2, “Header Enricher”
<int:header-filter input-channel="inputChannel" 
		output-channel="outputChannel" header-names="lastName, state"/>
As you can see, configuration of a Header Filter is quite simple. It is a typical endpoint with input/output channels and a header-names attribute. That attribute accepts the names of the header(s) (delimited by commas if there are multiple) that need to be removed. So, in the above example the headers named 'lastName' and 'state' will not be present on the outbound Message.

6.2 Content Enricher

6.2.1 Introduction

At times you may have a requirement to enhance a request with more information than was provided by the target system. The Content Enricher pattern describes various scenarios as well as the component (Enricher), which allows you to address such requirements.

The Spring Integration Core module includes 2 enrichers:

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

Please go to the adapter specific sections of this reference manual to learn more about those adapters.

6.2.2 Header Enricher

If you only need to add headers to a Message, and they are not dynamically determined by the Message content, then referencing a custom implementation of a Transformer may be overkill. For that reason, Spring Integration provides support for the Header Enricher pattern. It is exposed via the <header-enricher> element.

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

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

<int:header-enricher input-channel="in" output-channel="out">
		<int:error-channel ref="applicationErrorChannel"/>
		<int:reply-channel ref="quoteReplyChannel"/>
		<int:correlation-id value="123"/>
		<int:priority value="HIGHEST"/>
		<int:header name="bar" ref="someBean"/>
</int:header-enricher>

In the above configuration you can clearly see that for well-known headers such as errorChannel, correlationId, priority, replyChanneletc., 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.

POJO Support

Often a header value cannot be defined statically and has to be determined dynamically based on some content in the Message. That is why Header Enricher allows you to also specify a bean reference using the ref and method attribute. The specified method will calculate the header value. Let's look at the following configuration:

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

<bean id="myBean" class="foo.bar.MyBean"/>
public class MyBean {
    public String computeValue(String payload){
        return payload.toUpperCase() + "_US";
    }

}

You can also configure your POJO as inner bean:

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

as well as point to a Groovy script:

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

SpEL Support

In Spring Integration 2.0 we have introduced the convenience of the Spring Expression Language (SpEL) to help configure many different components. The Header Enricher is one of them. Looking again at the POJO example above, you can see that the computation logic to determine the header value is actually pretty simple. A natural question would be: "is there a simpler way to accomplish this?". That is where SpEL shows its true power.

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

As you can see, by using SpEL for such simple cases, we no longer have to provide a separate class and configure it in the application context. All we need is the expression attribute configured with a valid SpEL expression. The 'payload' and 'headers' variables are bound to the SpEL Evaluation Context, giving you full access to the incoming Message.

6.2.3 Payload Enricher

In certain situations the Header Enricher, as discussed above, may not be sufficient and payloads themselves may have to be enriched with additional information. For example, order messages that enter the Spring Integration messaging system have to look up the order's customer based on the provided customer number and then enrich the original payload with that information.

Since Spring Integration 2.1, the Payload Enricher is provided. A Payload Enricher defines an endpoint that passes a Message to the exposed request channel and then expects a reply message. The reply message then becomes the root object for evaluation of expressions to enrich the target payload.

The Payload Enricher provides full XML namespace support via the enricher element. In order to send request messages, the payload enricher has a request-channel attribute that allows you to dispatch messages to a request channel.

Basically by defining the request channel, the Payload Enricher acts as a Gateway, waiting for the message that were sent to the request channel to return, and the Enricher then augments the message's payload with the data provided by the reply message.

When sending messages to the request channel you also have the option to only send a subset of the original payload using the request-payload-expression attribute.

The enriching of payloads is configured through SpEL expressions, providing users with a maximum degree of flexibility. Therefore, users are not only able to enrich payloads with direct values from the reply channel's Message, but they can use SpEL expressions to extract a subset from that Message, only, or to apply addtional inline transformations, allowing them to further manipulate the data.

If you only need to enrich payloads with static values, you don't have to provide the request-channel attribute.

[Note]Note
Enrichers are a variant of Transformers and in many cases you could use a Payload Enricher or a generic Transformer implementation to add additional data to your messages payloads. Thus, familiarize yourself with all transformation-capable components that are provided by Spring Integration and carefully select the implementation that semantically fits your business case best.

Configuration

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

<int:enricher request-channel=""                          1
              auto-startup="true"                         2
              id=""                                       3
              order=""                                    4
              output-channel=""                           5
              request-payload-expression=""               6
              reply-channel=""                            7
              send-timeout=""                             8
              should-clone-payload="false">               9
    <int:poller></int:poller>                             10
    <int:property name="" expression=""/>  11
    <int:property name="" value=""/>
</int:enricher>

1

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

2

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

3

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

4

Specifies the order for invocation when this endpoint is connected as a subscriber to a channel. This is particularly relevant when that channel is using a "failover" dispatching strategy. It has no effect when this endpoint itself is a Polling Consumer for a channel with a queue. Optional.

5

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

6

By default the original message's payload will be used as payload that will be send to the request-channel. By specifying a SpEL expression as value for the request-payload-expression attribute, a subset of the original payload, a header value or any other resolvable SpEL expression can be used as the basis for the payload, that will be sent to the request-channel.

For the Expression evaluation the full message is available as the 'root object'.

For instance the following SpEL expressions (among others) are possible:

  • payload.foo
  • headers.foobar
  • new java.util.Date()
  • 'foo' + 'bar'

If more sophisticated logic is required (e.g. changing the message headers etc.) please use additional downstream transformers. Optional.

7

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

8

Maximum amount of time in milliseconds to wait when sending a message to the channel, if such channel may block.

For example, a Queue Channel can block until space is available, if its maximum capacity has been reached. Internally the send timeout is set on the MessagingTemplate and ultimately applied when invoking the send operation on the MessageChannel.

By default the send timeout is set to '-1', which may cause the send operation on the MessageChannel, depending on the implementation, to block indefinitely. Optional.

9

Boolean value indicating whether any payload that implements Cloneable should be cloned prior to sending the Message to the request chanenl for acquiring the enriching data. The cloned version would be used as the target payload for the ultimate reply. Default is false. Optional.

10

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

11

Each property sub-element provides the name of a property (via the mandatory name attribute). That property should be settable on the target payload instance. Exactly one of the value or expression attributes must be provided as well. The former for a literal value to set, and the latter for a SpEL expression to be evaluated. The root object of the evaluation context is the Message that was returned from the flow initiated by this enricher, the input Message if there is no request channel, or the application context (using the '@<beanName>.<beanProperty>' SpEL syntax).

Examples

Below, please find several examples of using a Payload Enricher in various situations.

In the following example, a User object is passed as the payload of the Message. The User has several properties but only the username is set initially. The Enricher's request-channel attribute below is configured to pass the User on to the findUserServiceChannel.

Through the implicitly set reply-channel a User object is returned and using the property sub-element, properties from the reply are extracted and used to enrich the original payload.

<int:enricher id="findUserEnricher"
              input-channel="findUserEnricherChannel"
              request-channel="findUserServiceChannel">
    <int:property name="email"    expression="payload.email"/>
    <int:property name="password" expression="payload.password"/>
</int:enricher>
[Note]Note
The code samples shown here, are part of the Spring Integration Samples project. Please feel free to check it out at: https://github.com/SpringSource/spring-integration-samples

How do I pass only a subset of data to the request channel?

Using a request-payload-expression attribute a single property of the payload can be passed on to the request channel instead of the full message. In the example below on the username property is passed on to the request channel. Keep in mind, that alwhough only the username is passed on, the resulting message send to the request channel will contain the full set of MessageHeaders.

<int:enricher id="findUserByUsernameEnricher"
              input-channel="findUserByUsernameEnricherChannel"
              request-channel="findUserByUsernameServiceChannel"
              request-payload-expression="payload.username">
    <int:property name="email"    expression="payload.email"/>
    <int:property name="password" expression="payload.password"/>
</int:enricher>

How can I enrich payloads that consist of Collection data?

In the following example, instead of a User object, a Map is passed in. The Map contains the username under the map key username. Only the username is passed on to the request channel. The reply contains a full User object, which is ultimately added to the Map under the user key.

<int:enricher id="findUserWithMapEnricher"
              input-channel="findUserWithMapEnricherChannel"
              request-channel="findUserByUsernameServiceChannel"
              request-payload-expression="payload.username">
    <int:property name="user"    expression="payload"/>
</int:enricher>

How can I enrich payloads with static information without using a request channel?

Here is an example that does not use a request channel at all, but solely enriches the message's payload with static values. But please be aware that the word 'static' is used loosly here. You can still use SpEL expressions for setting those values.

<int:enricher id="userEnricher"
              input-channel="input">
    <int:property name="user.updateDate" expression="new java.util.Date()"/>
    <int:property name="user.firstName" value="foo"/>
    <int:property name="user.lastName"  value="bar"/>
    <int:property name="user.age"       value="42"/>
</int:enricher>

6.3 Claim Check

6.3.1 Introduction

In the earlier sections we've covered several Content Enricher type components that help you deal with situations where a message is missing a piece of data. We also discussed Content Filtering which lets you remove data items from a message. However there are times when we want to hide data temporarily. For example, in a distributed system we may receive a Message with a very large payload. Some intermittent message processing steps may not need access to this payload and some may only need to access certain headers, so carrying the large Message payload through each processing step may cause performance degradation, may produce a security risk, and may make debugging more difficult.

The Claim Check pattern describes a mechanism that allows you to store data in a well known place while only maintaining a pointer (Claim Check) to where that data is located. You can pass that pointer around as a payload of a new Message thereby allowing any component within the message flow to get the actual data as soon as it needs it. This approach is very similar to the Certified Mail process where you'll get a Claim Check in your mailbox and would have to go to the Post Office to claim your actual package. Of course it's also the same idea as baggage-claim on a flight or in a hotel.

Spring Integration provides two types of Claim Check transformers:

  • Incoming Claim Check Transformer
  • Outgoing Claim Check Transformer

Convenient namespace-based mechanisms are available to configure them.

6.3.2 Incoming Claim Check Transformer

An Incoming Claim Check Transformer will transform an incoming Message by storing it in the Message Store identified by its message-store attribute.

<int:claim-check-in id="checkin"
        input-channel="checkinChannel"
        message-store="testMessageStore"
        output-channel="output"/>

In the above configuration the Message that is received on the input-channel will be persisted to the Message Store identified with the message-store attribute and indexed with generated ID. That ID is the Claim Check for that Message. The Claim Check will also become the payload of the new (transformed) Message that will be sent to the output-channel.

Now, lets assume that at some point you do need access to the actual Message. You can of course access the Message Store manually and get the contents of the Message, or you can use the same approach as before except now you will be transforming the Claim Check to the actual Message by using an Outgoing Claim Check Transformer.

Here is an overview of all available parameters of an Incoming Claim Check Transformer:

<int:claim-check-in auto-startup="true" 1
                    id=""                          2
                    input-channel=""               3
                    message-store="messageStore"   4
                    order=""                       5
                    output-channel=""              6
                    send-timeout="">               7
    <int:poller></int:poller>                      8
</int:claim-check-in>

1

Lifecycle attribute signaling if this component should be started during Application Context startup. Defaults to true. Attribute is not available inside a Chain element. Optional.

2

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

3

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

4

Reference to the MessageStore to be used by this Claim Check transformer. If not specified, the default reference will be to a bean named messageStore. Optional.

5

Specifies the order for invocation when this endpoint is connected as a subscriber to a channel. This is particularly relevant when that channel is using a failover dispatching strategy. It has no effect when this endpoint itself is a Polling Consumer for a channel with a queue. Attribute is not available inside a Chain element. Optional.

6

Identifies the Message channel where Message will be sent after its being processed by this endpoint. Attribute is not available inside a Chain element. Optional.

7

Specify the maximum amount of time in milliseconds to wait when sending a reply Message to the output channel. By default the send will block for one second. Attribute is not available inside a Chain element. Optional.

8

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

6.3.3 Outgoing Claim Check Transformer

An Outgoing Claim Check Transformer allows you to transform a Message with a Claim Check payload into a Message with the original content as its payload.

<int:claim-check-out id="checkout"
        input-channel="checkoutChannel"
        message-store="testMessageStore"
        output-channel="output"/>

In the above configuration, the Message that is received on the input-channel should have a Claim Check as its payload and the Outgoing Claim Check Transformer will transform it into a Message with the original payload by simply querying the Message store for a Message identified by the provided Claim Check. It then sends the newly checked-out Message to the output-channel.

Here is an overview of all available parameters of an Outgoing Claim Check Transformer:

<int:claim-check-out auto-startup="true" 1
                     id=""                          2
                     input-channel=""               3
                     message-store="messageStore"   4
                     order=""                       5
                     output-channel=""              6
                     remove-message="false"         7
                     send-timeout="">               8
    <int:poller></int:poller>                       9
</int:claim-check-out>

1

Lifecycle attribute signaling if this component should be started during Application Context startup. Defaults to true. Attribute is not available inside a Chain element. Optional.

2

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

3

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

4

Reference to the MessageStore to be used by this Claim Check transformer. If not specified, the default reference will be to a bean named messageStore. Optional.

5

Specifies the order for invocation when this endpoint is connected as a subscriber to a channel. This is particularly relevant when that channel is using a failover dispatching strategy. It has no effect when this endpoint itself is a Polling Consumer for a channel with a queue. Attribute is not available inside a Chain element. Optional.

6

Identifies the Message channel where Message will be sent after its being processed by this endpoint. Attribute is not available inside a Chain element. Optional.

7

If set to true the Message will be removed from the MessageStore by this transformer. Useful when Message can be "claimed" only once. Defaults to false. Optional.

8

Specify the maximum amount of time in milliseconds to wait when sending a reply Message to the output channel. By default the send will block for one second. Attribute is not available inside a Chain element. Optional.

9

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

Claim Once

There are scenarios when a particular message must be claimed only once. As an analogy, consider the airplane luggage check-in/out process. Checking-in your luggage on departure and and then claiming it on arrival is a classic example of such a scenario. Once the luggage has been claimed, it can not be claimed again without first checking it back in. To accommodate such cases, we introduced a remove-message boolean attribute on the claim-check-out transformer. This attribute is set to false by default. However, if set to true, the claimed Message will be removed from the MessageStore, so that it can no longer be claimed again.

This is also something to consider in terms of storage space, especially in the case of the in-memory Map-based SimpleMessageStore, where failing to remove the Messages could ultimately lead to an OutOfMemoryException. Therefore, if you don't expect multiple claims to be made, it's recommended that you set the remove-message attribute's value to true.

<int:claim-check-out id="checkout"
        input-channel="checkoutChannel"
        message-store="testMessageStore"
        output-channel="output"
        remove-message="true"/>

6.3.4 A word on Message Store

Although we rarely care about the details of the claim checks as long as they work, it is still worth knowing that the current implementation of the actual Claim Check (the pointer) in Spring Integration is a UUID to ensure uniqueness.

org.springframework.integration.store.MessageStore is a strategy interface for storing and retrieving messages. Spring Integration provides two convenient implementations of it. SimpleMessageStore: an in-memory, Map-based implementation (the default, good for testing) and JdbcMessageStore: an implementation that uses a relational database via JDBC.

7. Messaging Endpoints

7.1 Message Endpoints

The first part of this chapter covers some background theory and reveals quite a bit about the underlying API that drives Spring Integration's various messaging components. This information can be helpful if you want to really understand what's going on behind the scenes. However, if you want to get up and running with the simplified namespace-based configuration of the various elements, feel free to skip ahead to Section 7.1.4, “Namespace Support” for now.

As mentioned in the overview, Message Endpoints are responsible for connecting the various messaging components to channels. Over the next several chapters, you will see a number of different components that consume Messages. Some of these are also capable of sending reply Messages. Sending Messages is quite straightforward. As shown above in Section 3.1, “Message Channels”, it's easy to send a Message to a Message Channel. However, receiving is a bit more complicated. The main reason is that there are two types of consumers: Polling Consumers and Event Driven Consumers.

Of the two, Event Driven Consumers are much simpler. Without any need to manage and schedule a separate poller thread, they are essentially just listeners with a callback method. When connecting to one of Spring Integration's subscribable Message Channels, this simple option works great. However, when connecting to a buffering, pollable Message Channel, some component has to schedule and manage the polling thread(s). Spring Integration provides two different endpoint implementations to accommodate these two types of consumers. Therefore, the consumers themselves can simply implement the callback interface. When polling is required, the endpoint acts as a container for the consumer instance. The benefit is similar to that of using a container for hosting Message Driven Beans, but since these consumers are simply Spring-managed Objects running within an ApplicationContext, it more closely resembles Spring's own MessageListener containers.

7.1.1 Message Handler

Spring Integration's MessageHandler interface is implemented by many of the components within the framework. In other words, this is not part of the public API, and a developer would not typically implement MessageHandler directly. Nevertheless, it is used by a Message Consumer for actually handling the consumed Messages, and so being aware of this strategy interface does help in terms of understanding the overall role of a consumer. The interface is defined as follows:

public interface MessageHandler {

    void handleMessage(Message<?> message);

}

Despite its simplicity, this provides the foundation for most of the components that will be covered in the following chapters (Routers, Transformers, Splitters, Aggregators, Service Activators, etc). Those components each perform very different functionality with the Messages they handle, but the requirements for actually receiving a Message are the same, and the choice between polling and event-driven behavior is also the same. Spring Integration provides two endpoint implementations that host these callback-based handlers and allow them to be connected to Message Channels.

7.1.2 Event Driven Consumer

Because it is the simpler of the two, we will cover the Event Driven Consumer endpoint first. You may recall that the SubscribableChannel interface provides a subscribe() method and that the method accepts a MessageHandler parameter (as shown in the section called “SubscribableChannel”):

subscribableChannel.subscribe(messageHandler);

Since a handler that is subscribed to a channel does not have to actively poll that channel, this is an Event Driven Consumer, and the implementation provided by Spring Integration accepts a a SubscribableChannel and a MessageHandler:

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

EventDrivenConsumer consumer = new EventDrivenConsumer(channel, exampleHandler);

7.1.3 Polling Consumer

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

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

PollingConsumer consumer = new PollingConsumer(channel, exampleHandler);
[Note]Note
For more information regarding Polling Consumers, please also read Section 3.2, “Poller (Polling Consumer)” as well as Section 3.3, “Channel Adapter”.

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

PollingConsumer consumer = new PollingConsumer(channel, handler);

consumer.setTrigger(new IntervalTrigger(30, TimeUnit.SECONDS));

Spring Integration currently provides two implementations of the Trigger interface: IntervalTrigger and CronTrigger. The IntervalTrigger is typically defined with a simple interval (in milliseconds), but also supports an initialDelay property and a boolean fixedRate property (the default is false, i.e. fixed delay):

IntervalTrigger trigger = new IntervalTrigger(1000);
trigger.setInitialDelay(5000);
trigger.setFixedRate(true);

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

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

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

PollingConsumer consumer = new PollingConsumer(channel, handler);

consumer.setMaxMessagesPerPoll(10);
consumer.setReceiveTimeout(5000);

The maxMessagesPerPoll property specifies the maximum number of messages to receive within a given poll operation. This means that the poller will continue calling receive() without waiting until either null is returned or that max is reached. For example, if a poller has a 10 second interval trigger and a maxMessagesPerPoll setting of 25, and it is polling a channel that has 100 messages in its queue, all 100 messages can be retrieved within 40 seconds. It grabs 25, waits 10 seconds, grabs the next 25, and so on.

The receiveTimeout property specifies the amount of time the poller should wait if no messages are available when it invokes the receive operation. For example, consider two options that seem similar on the surface but are actually quite different: the first has an interval trigger of 5 seconds and a receive timeout of 50 milliseconds while the second has an interval trigger of 50 milliseconds and a receive timeout of 5 seconds. The first one may receive a message up to 4950 milliseconds later than it arrived on the channel (if that message arrived immediately after one of its poll calls returned). On the other hand, the second configuration will never miss a message by more than 50 milliseconds. The difference is that the second option requires a thread to wait, but as a result it is able to respond much more quickly to arriving messages. This technique, known as long polling, can be used to emulate event-driven behavior on a polled source.

A Polling Consumer may also delegate to a Spring TaskExecutor, as illustrated in the following example:

PollingConsumer consumer = new PollingConsumer(channel, handler);

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

Furthermore, a PollingConsumer has a property called adviceChain. This property allows you to specify a List of AOP Advices for handling additional cross cutting concerns including transactions. These advices are applied around the doPoll() method. For more in-depth information, please see the sections AOP Advice chains and Transaction Support under Section 7.1.4, “Namespace Support”.

The examples above show dependency lookups, but keep in mind that these consumers will most often be configured as Spring bean definitions. In fact, Spring Integration also provides a FactoryBean called ConsumerEndpointFactoryBean that creates the appropriate consumer type based on the type of channel, and there is full XML namespace support to even further hide those details. The namespace-based configuration will be featured as each component type is introduced.

[Note]Note
Many of the MessageHandler implementations are also capable of generating reply Messages. As mentioned above, sending Messages is trivial when compared to the Message reception. Nevertheless, when and how many reply Messages are sent depends on the handler type. For example, an Aggregator waits for a number of Messages to arrive and is often configured as a downstream consumer for a Splitter which may generate multiple replies for each Message it handles. When using the namespace configuration, you do not strictly need to know all of the details, but it still might be worth knowing that several of these components share a common base class, the AbstractReplyProducingMessageHandler, and it provides a setOutputChannel(..) method.

7.1.4 Namespace Support

Throughout the reference manual, you will see specific configuration examples for endpoint elements, such as router, transformer, service-activator, and so on. Most of these will support an input-channel attribute and many will support an output-channel attribute. After being parsed, these endpoint elements produce an instance of either the PollingConsumer or the EventDrivenConsumer depending on the type of the input-channel that is referenced: PollableChannel or SubscribableChannel respectively. When the channel is pollable, then the polling behavior is determined based on the endpoint element's poller sub-element and its attributes.

Configuration

Below you find a poller with all available configuration options:

<int:poller cron=""                                 1
            default="false"                         2
            error-channel=""                        3
            fixed-delay=""                          4
            fixed-rate=""                           5
            id=""                                   6
            max-messages-per-poll=""                7
            receive-timeout=""                      8
            ref=""                                  9
            task-executor=""                        10
            time-unit="MILLISECONDS"                11
            trigger="">                             12
            <int:advice-chain />                    13
            <int:transactional />                   14
</int:poller>

1

Provides the ability to configure Pollers using Cron expressions. The underlying implementation uses a org.springframework.scheduling.support.CronTrigger. If this attribute is set, none of the following attributes must be specified: fixed-delay, trigger, fixed-rate, ref.

2

By setting this attribute to true, it is possible to define exactly one (1) global default poller. An exception is raised if more than one default poller is defined in the application context. Any endpoints connected to a PollableChannel (PollingConsumer) or any SourcePollingChannelAdapter that does not have any explicitly configured poller will then use the global default Poller. Optional. Defaults to false.

3

Identifies the channel which error messages will be sent to if a failure occurs in this poller's invocation. To completely suppress Exceptions, provide a reference to the nullChannel. Optional.

4

The fixed delay trigger uses a PeriodicTrigger under the covers. If the time-unit attribute is not used, the specified value is represented in milliseconds. If this attribute is set, none of the following attributes must be specified: fixed-rate, trigger, cron, ref.

5

The fixed rate trigger uses a PeriodicTrigger under the covers. If the time-unit attribute is not used the specified value is represented in milliseconds. If this attribute is set, none of the following attributes must be specified: fixed-delay, trigger, cron, ref.

6

The Id referring to the Poller's underlying bean-definition, which is of type org.springframework.integration.scheduling.PollerMetadata. The id attribute is required for a top-level poller element unless it is the default poller (default="true").

7

Please see Section 3.3.1, “Configuring An Inbound Channel Adapter” for more information. Optional. If not specified the default values used depends on the context. If a PollingConsumer is used, this atribute will default to -1. However, if a SourcePollingChannelAdapter is used, then the max-messages-per-poll attribute defaults to 1.

8

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

9

Bean reference to another top-level poller. The ref attribute must not be present on the top-level poller element. However, if this attribute is set, none of the following attributes must be specified: fixed-rate, trigger, cron, fixed-deleay.

10

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

11

This attribute specifies the java.util.concurrent.TimeUnit enum value on the underlying org.springframework.scheduling.support.PeriodicTrigger. Therefore, this attribute can ONLY be used in combination with the fixed-delay or fixed-rate attributes. If combined with either cron or a trigger reference attribute, it will cause a failure.

The minimal supported granularity for a PeriodicTrigger is MILLISECONDS. Therefore, the only available options are MILLISECONDS and SECONDS. If this value is not provided, then any fixed-delay or fixed-rate value will be interpreted as MILLISECONDS by default.

Basically this enum provides a convenience for SECONDS-based interval trigger values. For hourly, daily, and monthly settings, consider using a cron trigger instead.

12

Reference to any spring configured bean which implements the org.springframework.scheduling.Trigger interface. Optional. However, if this attribute is set, none of the following attributes must be specified: fixed-delay, fixed-rate, cron, ref.

13

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

14

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

Examples

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

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

As an alternative to fixed-rate you can also use the fixed-delay attribute.

For a poller based on a Cron expression, use the cron attribute instead:

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

If the input channel is a PollableChannel, then the poller configuration is required. Specifically, as mentioned above, the trigger is a required property of the PollingConsumer class. Therefore, if you omit the poller sub-element for a Polling Consumer endpoint's configuration, an Exception may be thrown. The exception will also be thrown if you attempt to configure a poller on the element that is connected to a non-pollable channel.

It is also possible to create top-level pollers in which case only a ref is required:

 <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 only allowed on the inner-poller definitions. Defining this attribute on a top-level poller will result in a configuration exception thrown during initialization of the Application Context.

Global Default Pollers

In fact, to simplify the configuration even further, you can define a global default poller. A single top-level poller within an ApplicationContext may have the default attribute with a value of true. In that case, any endpoint with a PollableChannel for its input-channel that is defined within the same ApplicationContext and has no explicitly configured poller sub-element will use that default.

 <int:poller id="defaultPoller" default="true" max-messages-per-poll="5" fixed-rate="3000"/>

 <!-- No <poller/> sub-element is necessary since there is a default -->
 <int:transformer input-channel="pollable"
                  ref="transformer"
                  output-channel="output"/>

Transaction Support

Spring Integration also provides transaction support for the pollers so that each receive-and-forward operation can be performed as an atomic unit-of-work. To configure transactions for a poller, simply add the <transactional/> sub-element. The attributes for this element should be familiar to anyone who has experience with Spring's Transaction management:

<int:poller fixed-delay="1000">
    <int:transactional transaction-manager="txManager"
                       propagation="REQUIRED"
                       isolation="REPEATABLE_READ"
                       timeout="10000"
                       read-only="false"/>
</int:poller>

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

AOP Advice chains

Since Spring transaction support depends on the Proxy mechanism  with TransactionInterceptor (AOP Advice) handling transactional behavior of the message flow initiated by the poller, some times there is a need to provide extra Advice(s) to handle other cross cutting behavior associated with the poller. For that poller defines an advice-chain element allowing you to add more advices - class that  implements MethodInterceptor interface.. 

<int:service-activator id="advicedSa" input-channel="goodInputWithAdvice" ref="testBean"
		method="good" output-channel="output">
	<int:poller max-messages-per-poll="1" fixed-rate="10000">
		<int:transactional transaction-manager="txManager" />
		 <int:advice-chain>
			<ref bean="adviceA" />
			<beans:bean class="org.bar.SampleAdvice"/>
		</int:advice-chain>
	</int:poller>
</int:service-activator>

For more information on how to implement MethodInterceptor please refer to AOP sections of Spring reference manual (section 8 and 9). Advice chain can also be applied on the poller that does not have any transaction configuration essentially allowing you to enhance the behavior of the message flow initiated by the poller.

TaskExecutor Support

The polling threads may be executed by any instance of Spring's TaskExecutor abstraction. This enables concurrency for an endpoint or group of endpoints. As of Spring 3.0, there is a task namespace in the core Spring Framework, and its <executor/> element supports the creation of a simple thread pool executor. That element accepts attributes for common concurrency settings such as pool-size and queue-capacity. Configuring a thread-pooling executor can make a substantial difference in how the endpoint performs under load. These settings are available per-endpoint since the performance of an endpoint is one of the major factors to consider (the other major factor being the expected volume on the channel to which the endpoint subscribes). To enable concurrency for a polling endpoint that is configured with the XML namespace support, provide the task-executor reference on its <poller/> element and then provide one or more of the properties shown below:

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

 <task:executor id="pool"
                pool-size="5-25"
                queue-capacity="20"
                keep-alive="120"/>

If no task-executor is provided, the consumer's handler will be invoked in the caller's thread. Note that the caller is usually the default TaskScheduler (see Section B.3, “Configuring the Task Scheduler”). Also, keep in mind that the task-executor attribute can provide a reference to any implementation of Spring's TaskExecutor interface by specifying the bean name. The executor element above is simply provided for convenience.

As mentioned in the background section for Polling Consumers above, you can also configure a Polling Consumer in such a way as to emulate event-driven behavior. With a long receive-timeout and a short interval-trigger, you can ensure a very timely reaction to arriving messages even on a polled message source. Note that this will only apply to sources that have a blocking wait call with a timeout. For example, the File poller does not block, each receive() call returns immediately and either contains new files or not. Therefore, even if a poller contains a long receive-timeout, that value would never be usable in such a scenario. On the other hand when using Spring Integration's own queue-based channels, the timeout value does have a chance to participate. The following example demonstrates how a Polling Consumer will receive Messages nearly instantaneously.

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

 </int:service-activator>

Using this approach does not carry much overhead since internally it is nothing more then a timed-wait thread which does not require nearly as much CPU resource usage as a thrashing, infinite while loop for example.

7.1.5 Change Polling Rate at Runtime

When configuring Pollers with a fixed-delay or fixed-rate attribute, the default implementation will use a PeriodicTrigger instance. The PeriodicTrigger is part of the Core Spring Framework and it accepts the interval as a constructor argument, only. Therefore it cannot be changed at runtime.

However, you can define your own implementation of the org.springframework.scheduling.Trigger interface. You could even use the PeriodicTrigger as a starting point. Then, you can add a setter for the interval (period), or you could even embed your own throttling logic within the trigger itself if desired. The period property will be used with each call to nextExecutionTime to schedule the next poll. To use this custom trigger within pollers, declare the bean defintion of the custom Trigger in your application context and inject the dependency into your Poller configuration using the trigger attribute, which references the custom Trigger bean instance. You can now obtain a reference to the Trigger bean and the polling interval can be changed between polls.

For an example, please see the Spring Integration Samples project. It contains a sample called dynamic-poller, which uses a custom Trigger and demonstrates the ability to change the polling interval at runtime.

The sample provides a custom Trigger which implements the org.springframework.scheduling.Trigger interface. The sample's Trigger is based on Spring's PeriodicTrigger implementation. However, the fields of the custom trigger are not final and the properties have explicit getters and setters, allowing to dynamically change the polling period at runtime.

[Note]Note

It is important to note, though, that because the Trigger method is nextExecutionTime(), any changes to a dynamic trigger will not take effect until the next poll, based on the existing configuration. It is not possible to force a trigger to fire before it's currently configured next execution time.

7.1.6 Payload Type Conversion

Throughout the reference manual, you will also see specific configuration and implementation examples of various endpoints which can accept a Message or any arbitrary Object as an input parameter. In the case of an Object, such a parameter will be mapped to a Message payload or part of the payload or header (when using the Spring Expression Language). However there are times when the type of input parameter of the endpoint method does not match the type of the payload or its part. In this scenario we need to perform type conversion. Spring Integration provides a convenient way for registering type converters (using the Spring 3.x ConversionService) within its own instance of a conversion service bean named integrationConversionService. That bean is automatically created as soon as the first converter is defined using the Spring Integration namespace support. To register a Converter all you need is to implement org.springframework.core.convert.converter.Converter and define it via convenient namespace support:

 <int:converter ref="sampleConverter"/>

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

or as an inner bean:

 <int:converter>
		<bean class="org.springframework.integration.config.xml.ConverterParserTests$TestConverter3"/>
	</int:converter>

7.1.7 Asynchronous polling

If you want the polling to be asynchronous, a Poller can optionally specify a task-executor attribute pointing to an existing instance of any TaskExecutor bean (Spring 3.0 provides a convenient namespace configuration via the task namespace). However, there are certain things you must understand when configuring a Poller with a TaskExecutor. 

The problem is that there are two configurations in place. The Poller and the TaskExecutor, and they both have to be in tune with each other otherwise you might end up creating an artificial memory leak.

Let's look at the following configuration provided by one of the users on the Spring Integration forum (http://forum.springsource.org/showthread.php?t=94519):

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

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

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

The poller keeps scheduling new tasks even though all the threads are blocked waiting for either a new message to arrive, or the timeout to expire. Given that there are 20 threads executing tasks with a 5 second timeout, they will be executed at a rate of 4 per second (5000/20 = 250ms). But, new tasks are being scheduled at a rate of 20 per second, so the internal queue in the task executor will grow at a rate of 16 per second (while the process is idle), so we essentially have a memory leak.

One of the ways to handle this is to set the queue-capacity attribute of the Task Executor to 0. You can also manage it by specifying what to do with messages that can not be queued by setting the rejection-policy attribute of the Task Executor (e.g., DISCARD). In other words there are certain details you must understand with regard to configuring the TaskExecutor. Please refer to - Section 25 - Task Execution and Scheduling of the Spring reference manual for more detail on the subject.

7.2 Messaging Gateways

The primary purpose of a Gateway is to hide the messaging API provided by Spring Integration. It allows your application's business logic to be completely unaware of the Spring Integration API and using a generic Gateway, your code interacts instead with a simple interface, only.

7.2.1 Enter the GatewayProxyFactoryBean

As mentioned above, it would be great to have no dependency on the Spring Integration API at all - including the gateway class. For that reason, Spring Integration provides the GatewayProxyFactoryBean that generates a proxy for any interface and internally invokes the gateway methods shown below. Using dependency injection you can then expose the interface to your business methods.

Here is an example of an interface that can be used to interact with Spring Integration:

package org.cafeteria;

public interface Cafe {

    void placeOrder(Order order);

}

7.2.2 Gateway XML Namespace Support

Namespace support is also provided which allows you to configure such an interface as a service as demonstrated by the following example.

<int:gateway id="cafeService"
         service-interface="org.cafeteria.Cafe"
         default-request-channel="requestChannel"
         default-reply-channel="replyChannel"/>

With this configuration defined, the "cafeService" can now be injected into other beans, and the code that invokes the methods on that proxied instance of the Cafe interface has no awareness of the Spring Integration API. The general approach is similar to that of Spring Remoting (RMI, HttpInvoker, etc.). See the "Samples" Appendix for an example that uses this "gateway" element (in the Cafe demo).

7.2.3 Setting the Default Reply Channel

Typically you don't have to specify the default-reply-channel, since a Gateway will auto-create a temporary, anonymous reply channel, where it will listen for the reply. However, there are some cases which may prompt you to define a default-reply-channel (or reply-channel with adapter gateways such as HTTP, JMS, etc.).

For some background, we'll quickly discuss some of the inner-workings of the Gateway. A Gateway will create a temporary point-to-point reply channel which is anonymous and is added to the Message Headers with the name replyChannel. When providing an explicit default-reply-channel (reply-channel with remote adapter gateways), you have the option to point to a publish-subscribe channel, which is so named because you can add more than one subscriber to it. Internally Spring Integration will create a Bridge between the temporary replyChannel and the explicitly defined default-reply-channel.

So let's say you want your reply to go not only to the gateway, but also to some other consumer. In this case you would want two things: a) a named channel you can subscribe to and b) that channel is a publish-subscribe-channel. The default strategy used by the gateway will not satisfy those needs, because the reply channel added to the header is anonymous and point-to-point. This means that no other subscriber can get a handle to it and even if it could, the channel has point-to-point behavior such that only one subscriber would get the Message. So by defining a default-reply-channel you can point to a channel of your choosing, which in this case would be a publish-subscribe-channel. The Gateway would create a bridge from it to the temporary, anonymous reply channel that is stored in the header.

Another case where you might want to provide a reply channel explicitly is for monitoring or auditing via an interceptor (e.g., wiretap). You need a named channel in order to configure a Channel Interceptor.

7.2.4 Gateway Configuration with Annotations and/or XML

The reason that the attributes on the 'gateway' element are named 'default-request-channel' and 'default-reply-channel' is that you may also provide per-method channel references by using the @Gateway annotation.

 public interface Cafe {

     @Gateway(requestChannel="orders")
     void placeOrder(Order order);

 }

You may alternatively provide such content in method sub-elements if you prefer XML configuration (see the next paragraph).

It is also possible to pass values to be interpreted as Message headers on the Message that is created and sent to the request channel by using the @Header annotation:

 public interface FileWriter {

     @Gateway(requestChannel="filesOut")
     void write(byte[] content, @Header(FileHeaders.FILENAME) String filename);

 }

If you prefer the XML approach of configuring Gateway methods, you can provide method sub-elements to the gateway configuration.

<int:gateway id="myGateway" service-interface="org.foo.bar.TestGateway"
      default-request-channel="inputC">
  <int:method name="echo" request-channel="inputA" reply-timeout="2" request-timeout="200"/>
      <int:method name="echoUpperCase" request-channel="inputB"/>
      <int:method name="echoViaDefault"/>
</int:gateway>

You can also provide individual headers per method invocation via XML. This could be very useful if the headers you want to set are static in nature and you don't want to embed them in the gateway's method signature via @Header annotations. For example, in the Loan Broker example we want to influence how aggregation of the Loan quotes will be done based on what type of request was initiated (single quote or all quotes). Determining the type of the request by evaluating what gateway method was invoked, although possible, would violate the separation of concerns paradigm (the method is a java artifact),  but expressing your intention (meta information) via Message headers is natural in a Messaging architecture.

<int:gateway id="loanBrokerGateway"
         service-interface="org.springframework.integration.loanbroker.LoanBrokerGateway">
  <int:method name="getLoanQuote" request-channel="loanBrokerPreProcessingChannel">
    <int:header name="RESPONSE_TYPE" value="BEST"/>
  </int:method>
  <int:method name="getAllLoanQuotes" request-channel="loanBrokerPreProcessingChannel">
    <int:header name="RESPONSE_TYPE" value="ALL"/>
  </int:method>
</int:gateway>

In the above case you can clearly see how a different value will be set for the 'RESPONSE_TYPE' header based on the gateway's method.

7.2.5 Invoking No-Argument Methods

When invoking methods on a Gateway interface that do not have any arguments, the default behavior is to receive a Message from a PollableChannel.

At times however, you may want to trigger no-argument methods so that you can in fact interact with other components downstream that do not require user-provided parameters, e.g. triggering no-argument SQL calls or Stored Procedures.

In order to achieve send-and-receive semantics, you must provide a payload. In order to generate a payload, method parameters on the interface are not necessary. You can either use the @Payload annotation or the payload-expression attribute in XML on the method sub-element. Below please find a few examples of what the payloads could be:

  • a literal string
  • #method (for the method name)
  • new java.util.Date()
  • @someBean.someMethod()'s return value

Here is an example using the @Payload annotation:

public interface Cafe {

    @Payload("new java.util.Date()")
    List<Order> retrieveOpenOrders();

}

If a method has no argument and no return value, but does contain a payload expression, it will be treated as a send-only operation.

7.2.6 Error Handling

Of course, the Gateway invocation might result in errors. By default any error that has occurred downstream will be re-thrown as a MessagingException (RuntimeException) upon the Gateway's method invocation. However there are times when you may want to simply log the error rather than propagating it, or you may want to treat an Exception as a valid reply, by mapping it to a Message that will conform to some "error message" contract that the caller understands. To accomplish this, our Gateway provides support for a Message Channel dedicated to the errors via the error-channel attribute. In the example below, you can see that a 'transformer' is used to create a reply Message from the Exception.

<int:gateway id="sampleGateway"
    default-request-channel="gatewayChannel"
    service-interface="foo.bar.SimpleGateway"
    error-channel="exceptionTransformationChannel"/>

<int:transformer input-channel="exceptionTransformationChannel"
        ref="exceptionTransformer" method="createErrorResponse"/>

The exceptionTransformer could be a simple POJO that knows how to create the expected error response objects. That would then be the payload that is sent back to the caller. Obviously, you could do many more elaborate things in such an "error flow" if necessary. It might involve routers (including Spring Integration's ErrorMessageExceptionTypeRouter), filters, and so on. Most of the time, a simple 'transformer' should be sufficient, however.

Alternatively, you might want to only log the Exception (or send it somewhere asynchronously). If you provide a one-way flow, then nothing would be sent back to the caller. In the case that you want to completely suppress Exceptions, you can provide a reference to the global "nullChannel" (essentially a /dev/null approach). Finally, as mentioned above, if no "error-channel" is defined at all, then the Exceptions will propagate as usual.

[Important]Important
Exposing the messaging system via simple POJI Gateways obviously provides benefits, but "hiding" the reality of the underlying messaging system does come at a price so there are certain things you should consider. We want our Java method to return as quickly as possible and not hang for an indefinite amount of time while the caller is waiting on it to return (void, return value, or a thrown Exception). When regular methods are used as a proxies in front of the Messaging system, we have to take into account the potentially asynchronous nature of the underlying messaging. This means that there might be a chance that a Message that was initiated by a Gateway could be dropped by a Filter, thus never reaching a component that is responsible for producing a reply. Some Service Activator method might result in an Exception, thus providing no reply (as we don't generate Null messages). So as you can see there are multiple scenarios where a reply message might not be coming. That is perfectly natural in messaging systems. However think about the implication on the gateway method. The Gateway's method input arguments  were incorporated into a Message and sent downstream. The reply Message would be converted to a return value of the Gateway's method. So you might want to ensure that for each Gateway call there will always be a reply Message. Otherwise, your Gateway method might never return and will hang indefinitely. One of the ways of handling this situation is via an Asynchronous Gateway (explained later in this section). Another way of handling it is to explicitly set the reply-timeout attribute. That way, the gateway will not hang any longer than the time specified by the reply-timeout and will return 'null' if that timeout does elapse. Finally, you might want to consider setting downstream flags such as 'requires-reply' on a service-activator or 'throw-exceptions-on-rejection' on a filter. These options will be discussed in more detail in the final section of this chapter.

7.2.7 Asynchronous Gateway

As a pattern the Messaging Gateway is a very nice way to hide messaging-specific code while still exposing the full capabilities of the messaging system. As you've seen, the GatewayProxyFactoryBean provides a convenient way to expose a Proxy over a service-interface thus giving you POJO-based access to a messaging system (based on objects in your own domain, or primitives/Strings, etc).  But when a gateway is exposed via simple POJO methods which return values it does imply that for each Request message (generated when the method is invoked) there must be a Reply message (generated when the method has returned). Since Messaging systems naturally are asynchronous you may not always be able to guarantee the contract where "for each request there will always be be a reply".  With Spring Integration 2.0 we are introducing support for an Asynchronous Gateway which is a convenient way to initiate flows where you may not know if a reply is expected or how long will it take for replies to arrive.

A natural way to handle these types of scenarios in Java would be relying upon java.util.concurrent.Future instances, and that is exactly what Spring Integration uses to support an Asynchronous Gateway.

From the XML configuration, there is nothing different and you still define Asynchronous Gateway the same way as a regular Gateway.

<int:gateway id="mathService" 
     service-interface="org.springframework.integration.sample.gateway.futures.MathServiceGateway"
     default-request-channel="requestChannel"/>

However the Gateway Interface (service-interface) is a bit different.

public interface MathServiceGateway {
  Future<Integer> multiplyByTwo(int i);
}

As you can see from the example above the return type for the gateway method is a Future. When GatewayProxyFactoryBean sees that the return type of the gateway method is a Future, it immediately switches to the async mode by utilizing an AsyncTaskExecutor. That is all. The call to such a method always returns immediately with a Future instance. Then, you can interact with the Future at your own pace to get the result, cancel, etc. And, as with any other use of Future instances, calling get() may reveal a timeout, an execution exception, and so on.

MathServiceGateway mathService = ac.getBean("mathService", MathServiceGateway.class);
Future<Integer> result = mathService.multiplyByTwo(number);
// do something else here since the reply might take a moment
int finalResult =  result.get(1000, TimeUnit.SECONDS);

For a more detailed example, please refer to the async-gateway sample distributed within the Spring Integration samples.

Asynchronous Gateway and AsyncTaskExecutor

By default GatewayProxyFactoryBean uses org.springframework.core.task.SimpleAsyncTaskExecutor when submitting internal AsyncInvocationTask instances for any gateway method whose return type is Future.class. However the async-executor attribute in the <gateway/> element's configuration allows you to provide a reference to any implementation of java.util.concurrent.Executor available within the Spring application context.

7.2.8 Gateway behavior when no response arrives

As it was explained earlier, the Gateway provides a convenient way of interacting with a Messaging system via POJO method invocations, but realizing that a typical method invocation, which is generally expected to always return (even with an Exception), might not always map one-to-one to message exchanges (e.g., a reply message might not arrive - which is equivalent to a method not returning). It is important to go over several scenarios especially in the Sync Gateway case and understand the default behavior of the Gateway and how to deal with these scenarios to make the Sync Gateway behavior more predictable regardless of the outcome of the message flow that was initialed from such Gateway.

There are certain attributes that could be configured to make Sync Gateway behavior more predictable, but some of them might not always work as you might have expected. One of them is reply-timeout. So, lets look at the reply-timeout attribute and see how it can/can't influence the behavior of the Sync Gateway in various scenarios. We will look at single-threaded scenario (all components downstream are connected via Direct Channel) and multi-threaded scenarios (e.g., somewhere downstream you may have Pollable or Executor Channel which breaks single-thread boundary)

Long running process downstream

Sync Gateway - single-threaded. If a component downstream is still running (e.g., infinite loop or a very slow service), then setting a reply-timeout has no effect and the Gateway method call will not return until such downstream service exits (via return or exception). Sync Gateway - multi-threaded. If a component downstream is still running (e.g., infinite loop or a very slow service), in a multi-threaded message flow setting the reply-timeout will have an effect by allowing gateway method invocation to return once the timeout has been reached, since the GatewayProxyFactoryBean  will simply poll on the reply channel waiting for a message until the timeout expires. However it could result in a 'null' return from the Gateway method if the timeout has been reached before the actual reply was produced. It is also important to understand that the reply message (if produced) will be sent to a reply channel after the Gateway method invocation might have returned, so you must be aware of that and design your flow with this in mind.

Downstream component returns 'null'

Sync Gateway - single-threaded. If a component downstream returns 'null' and no reply-timeout has been configured, the Gateway method call will hang indefinitely unless: a) a reply-timeout has been configured or b) the requires-reply attribute has been set on the downstream component (e.g., service-activator) that might return 'null'. In this case, an Exception would be thrown and propagated to the Gateway. Sync Gateway - multi-threaded. Behavior is the same as above.

Downstream component return signature is 'void' while Gateway method signature is non-void

Sync Gateway - single-threaded. If a component downstream returns 'void' and no reply-timeout has been configured, the Gateway method call will hang indefinitely unless a reply-timeout has been configured  Sync Gateway - multi-threaded Behavior is the same as above.

Downstream component results in Runtime Exception (regardless of the method signature)

Sync Gateway - single-threaded. If a component downstream throws a Runtime Exception, such exception will be propagated via an Error Message back to the gateway and re-thrown. Sync Gateway - multi-threaded Behavior is the same as above.

[Important]Important
It is also important to understand that by default reply-timeout is unbounded* which means that if not explicitly set there are several scenarios (described above) where your Gateway method invocation might hang indefinitely. So, make sure you analyze your flow and if there is even a remote possibility of one of these scenarios to occur, set the reply-timeout attribute to a 'safe' value or, even better, set the requires-reply attribute of the downstream component to 'true' to ensure a timely response as produced by the throwing of an Exception as soon as that downstream component does return null internally. But also, realize that there are some scenarios (see the very first one) where reply-timeout will not help. That means it is also important to analyze your message flow and decide when to use a Sync Gateway vs an Async Gateway. As you've seen the latter case is simply a matter of defining Gateway methods that return Future instances. Then, you are guaranteed to receive that return value, and you will have more granular control over the results of the invocation.

Also, when dealing with a Router you should remember that setting the resolution-required attribute to 'true' will result in an Exception thrown by the router if it can not resolve a particular channel. Likewise, when dealing with a Filter, you can set the throw-exception-on-rejection attribute. In both of these cases, the resulting flow will behave like that containing a service-activator with the 'requires-reply' attribute. In other words, it will help to ensure a timely response from the Gateway method invocation.

[Note]Note

* reply-timeout is unbounded for <gateway/> elements (created by the GatewayProxyFactoryBean). Inbound gateways for external integration (ws, http, etc.) share many characteristics and attributes with these gateways. However, for those inbound gateways, the default reply-timeout is 1000 milliseconds (1 second). If a downstream async handoff is made to another thread, you may need to increase this attribute to allow enough time for the flow to complete before the gateway times out.

7.3 Service Activator

7.3.1 Introduction

The Service Activator is the endpoint type for connecting any Spring-managed Object to an input channel so that it may play the role of a service. If the service produces output, it may also be connected to an output channel. Alternatively, an output producing service may be located at the end of a processing pipeline or message flow in which case, the inbound Message's "replyChannel" header can be used. This is the default behavior if no output channel is defined, and as with most of the configuration options you'll see here, the same behavior actually applies for most of the other components we have seen.

7.3.2 Configuring Service Activator

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

<int:service-activator input-channel="exampleChannel" ref="exampleHandler"/>

The configuration above assumes that "exampleHandler" either contains a single method annotated with the @ServiceActivator annotation or that it contains only one public method at all. To delegate to an explicitly defined method of any object, simply add the "method" attribute.

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

In either case, when the service method returns a non-null value, the endpoint will attempt to send the reply message to an appropriate reply channel. To determine the reply channel, it will first check if an "output-channel" was provided in the endpoint configuration:

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

If no "output-channel" is available, it will then check the Message's replyChannel header value. If that value is available, it will then check its type. If it is a MessageChannel, the reply message will be sent to that channel. If it is a String, then the endpoint will attempt to resolve the channel name to a channel instance. If the channel cannot be resolved, then a ChannelResolutionException will be thrown. It it can be resolved, the Message will be sent there. This is the technique used for Request Reply messaging in Spring Integration, and it is also an example of the Return Address pattern.

The argument in the service method could be either a Message or an arbitrary type. If the latter, then it will be assumed that it is a Message payload, which will be extracted from the message and injected into such service method. This is generally the recommended approach as it follows and promotes a POJO model when working with Spring Integration. Arguments may also have @Header or @Headers annotations as described in Section B.5, “Annotation Support”

[Note]Note
The service method is not required to have any arguments at all, which means you can implement event-style Service Activators, where all you care about is an invocation of the service method, not worrying about the contents of the message. Think of it as a NULL JMS message. An example use-case for such an implementation could be a simple counter/monitor of messages deposited on the input channel.

Using a "ref" attribute is generally recommended if the custom Service Activator handler implementation can be reused in other <service-activator> definitions. However if the custom Service Activator handler implementation is only used within a single definition of the <service-activator>, you can provide an inner bean definition:

<int:service-activator id="exampleServiceActivator" input-channel="inChannel"
            output-channel = "outChannel" method="foo">
    <beans:bean class="org.foo.ExampleServiceActivator"/>
</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 will result in an Exception being thrown.

Service Activators and the Spring Expression Language (SpEL)

Since Spring Integration 2.0, Service Activators can also benefit from SpEL (http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html).

For example, you may now invoke any bean method without pointing to the bean via a ref attribute or including it as an inner bean definition. For example:

<int:service-activator input-channel="in" output-channel="out" 
	expression="@accountService.processAccount(payload, headers.accountId)"/>
	
	<bean id="accountService" class="foo.bar.Account"/>

In the above configuration instead of injecting 'accountService' using a ref or as an inner bean, we are simply using SpEL's @beanId notation and invoking a method which takes a type compatible with Message payload. We are also passing a header value. As you can see, any valid SpEL expression can be evaluated against any content in the Message. For simple scenarios your Service Activators do not even have to reference a bean if all logic can be encapsulated by such an expression.

<int:service-activator input-channel="in" output-channel="out" expression="payload * 2"/>

In the above configuration our service logic is to simply multiply the payload value by 2, and SpEL lets us handle it relatively easy.

7.4 Delayer

7.4.1 Introduction

A Delayer is a simple endpoint that allows a Message flow to be delayed by a certain interval. When a Message is delayed, the original sender will not block. Instead, the delayed Messages will be scheduled with an instance of org.springframework.scheduling.TaskScheduler to be sent to the output channel after the delay has passed. This approach is scalable even for rather long delays, since it does not result in a large number of blocked sender Threads. On the contrary, in the typical case a thread pool will be used for the actual execution of releasing the Messages. Below you will find several examples of configuring a Delayer.

7.4.2 Configuring Delayer

The <delayer> element is used to delay the Message flow between two Message Channels. As with the other endpoints, you can provide the 'input-channel' and 'output-channel' attributes, but the delayer also has 'default-delay' and 'delay-header-name' attributes that are used to determine the number of milliseconds that each Message should be delayed. The following delays all messages by 3 seconds:

 <int:delayer id="delayer" input-channel="input" default-delay="3000" output-channel="output"/>

If you need per-Message determination of the delay, then you can also provide the name of a header using the 'delay-header-name' attribute:

 <int:delayer id="delayer" input-channel="input" output-channel="output"
          default-delay="3000" delay-header-name="delay"/>

In the example above the 3 second delay would only apply in the case that the header value is not present for a given inbound Message. If you only want to apply a delay to Messages that have an explicit header value, then you can set the 'default-delay' to 0 or don't use it at all (by default it is 0). For any Message that has a delay of 0 (or less), the Message will be sent directly. In fact, if there is not a positive delay value for a Message, it will be sent to the output channel on the calling Thread.

[Tip]Tip
The delay handler supports header values that represent an interval in milliseconds (any Object whose toString() method produces a value that can be parsed into a Long) as well as java.util.Date instances representing an absolute time. In the first case, the milliseconds will be counted from the current time (e.g. a value of 5000 would delay the Message for at least 5 seconds from the time it is received by the Delayer). With a Date instance, the Message will not be released until that Date occurs. In either case, a value that equates to a non-positive delay, or a Date in the past, will not result in any delay. Instead, it will be sent directly to the output channel on the original sender's Thread. If the header is not a Date, and can not be parsed as a Long, the default delay (if any) will be applied.

The delayer delegates to an instance of Spring's TaskScheduler abstraction. The default scheduler used by the delayer is the ThreadPoolTaskScheduler instance provided by Spring Integration on startup: Section B.3, “Configuring the Task Scheduler”. If you want to delegate to a different scheduler, you can provide a reference through the delayer element's 'scheduler' attribute:

 <int:delayer id="delayer" input-channel="input" output-channel="output"
          delay-header-name="delay"
          scheduler="exampleTaskScheduler"/>

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

[Tip]Tip
If you configure an external ThreadPoolTaskScheduler you can set on this scheduler property waitForTasksToCompleteOnShutdown = true. It allows successful completion of 'delay' tasks, which already in the execution state (releasing the Message), when the application is shutdown. Before Spring Integration 2.2 this property was available on the <delayer> element, because DelayHandler could create its own scheduler on the background. Since 2.2 delayer requires an external scheduler instance and waitForTasksToCompleteOnShutdown was deleted; you should use the scheduler's own configuration.

[Tip]Tip
Also keep in mind ThreadPoolTaskScheduler has a property errorHandler which can be injected with some implementation of org.springframework.util.ErrorHandler. This handler allows to process an Exception from the thread of the scheduled task sending the delayed message. By default it uses an org.springframework.scheduling.support.TaskUtils$LoggingErrorHandler and you will see a stack trace in the logs. You might want to consider using an org.springframework.integration.channel.MessagePublishingErrorHandler, which sends an ErrorMessage into an error-channel, either from the failed Message's header or into the default error-channel.

7.4.3 Delayer and Message Store

The DelayHandler persists delayed Messages into the Message Group in the provided MessageStore. (The 'groupId' is based on required 'id' attribute of <delayer> element.) A delayed message is removed from the MessageStore by the scheduled task just before the DelayHandler sends the Message to the output-channel. If the provided MessageStore is persistent (e.g. JdbcMessageStore) it provides the ability to not lose Messages on the application shutdown. After application startup, the DelayHandler reads Messages from its Message Group in the MessageStore and reschedules them with a delay based on the original arrival time of the Message (if the delay is numeric). For messages where the delay header was a Date, that is used when rescheduling. If a delayed Message remained in the MessageStore more than its 'delay', it will be sent immediately after startup.

The DelayHandler can be exported as a JMX MBean with managed operations getDelayedMessageCount and reschedulePersistedMessages, which allows the rescheduling of delayed persisted Messages at runtime, for example, if the TaskScheduler has previously been stopped. These operations can be invoked via a Control Bus command:

      Message<String> delayerReschedulingMessage = MessageBuilder.withPayload("@'delayer.handler'.reschedulePersistedMessages()").build();
      controlBusChannel.send(delayerReschedulingMessage);

[Note]Note
For more information regarding the Message Store, JMX and the Control Bus, please read Chapter 8, System Management.

7.5 Scripting support

With Spring Integration 2.1 we've added support for the JSR223 Scripting for Java specification, introduced in Java version 6. This allows you to use scripts written in any supported language including Ruby/JRuby, Javascript and Groovy to provide the logic for various integration components similar to the way the Spring Expression Language (SpEL) is used in Spring Integration. For more information about JSR223 please refer to the documentation

[Important]Important
Note that this feature requires Java 6 or higher. Sun developed a JSR223 reference implementation which works with Java 5 but it is not officially supported and we have not tested it with Spring Integration.

In order to use a JVM scripting language, a JSR223 implementation for that language must be included in your class path. Java 6 natively supports Javascript. The Groovy and JRuby projects provide JSR233 support in their standard distribution. Other language implementations may be available or under development. Please refer to the appropriate project website for more information.

[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/or the implementer's interpretation of the specification.

[Tip]Tip
If you plan to use Groovy as your scripting language, we recommended you use Section 7.6, “Groovy support” as it offers additional features specific to Groovy. However you will find this section relevant as well.

7.5.1 Script configuration

Depending on the complexity of your integration requirements scripts may be provided inline as CDATA in XML configuration or as a reference to a Spring resource containing the script. To enable scripting support Spring Integration defines a ScriptExecutingMessageProcessor which will bind the Message Payload to a variable named payload and the Message Headers to a headers variable, both accessible within the script execution context. All that is left for you to do is write a script that uses these variables. Below are a couple of sample configurations:

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>

Here, you see that the script can be included inline or can reference a resource location via the location attribute. Additionally the lang attribute corresponds to the language name (or JSR223 alias)

Other Spring Integration endpoint elements which support scripting include router, service-activator, transformer, and splitter. The scripting configuration in each case would be identical to the above (besides the endpoint element).

Another useful feature of Scripting support is the ability to update (reload) scripts without having to restart the Application Context. To accomplish this, specify the refresh-check-delay attribute on the script element:

<int-script:script location="..." refresh-check-delay="5000"/>

In the above example, the script location will be checked for updates every 5 seconds. If the script is updated, any invocation that occurs later than 5 seconds since the update will result in execution of the new script.

<int-script:script location="..." refresh-check-delay="0"/>

In the above example the context will be updated with any script modifications as soon as such modification occurs, providing a simple mechanism for 'real-time' configuration. Any negative number value means the script will not be reloaded after initialization of the application context. This is the default behavior.

[Important]Important
Inline scripts can not be reloaded.
<int-script:script location="..." refresh-check-delay="-1"/>

Script variable bindings

Variable bindings are required to enable the script to reference variables externally provided to the script's execution context. As we have seen, payload and headers are used as binding variables by default. You can bind additional variables to a script via <variable> sub-elements:

<script:script lang="js" location="foo/bar/MyScript.js">
	<script:variable name="foo" value="foo"/>
	<script:variable name="bar" value="bar"/>
	<script:variable name="date" ref="date"/>
</script:script>

As shown in the above example, you can bind a script variable either to a scalar value or a Spring bean reference. Note that payload and headers will still be included as binding variables.

If you need more control over how variables are generated, you can implement your own Java class using the ScriptVariableGenerator strategy:

public interface ScriptVariableGenerator {
  
	Map<String, Object> generateScriptVariables(Message<?> message);
	
}

This interface requires you to implement the method generateScriptVariables(Message). The Message argument allows you to access any data available in the Message payload and headers and the return value is the Map of bound variables. This method will be called every time the script is executed for a Message. All you need to do is provide an implementation of ScriptVariableGenerator and reference it with the script-variable-generator attribute:

<int-script:script location="foo/bar/MyScript.groovy"
				script-variable-generator="variableGenerator"/>

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

[Important]Important
You cannot provide both the script-variable-generator attribute and <variable> sub-element(s) as they are mutually exclusive. Also, custom variable bindings cannot be used with an inline script.

7.6 Groovy support

In Spring Integration 2.0 we added Groovy support allowing you to use the Groovy scripting language to provide the logic for various integration components similar to the way the Spring Expression Language (SpEL) is supported for routing, transformation and other integration concerns. For more information about Groovy please refer to the Groovy documentation which you can find on the project website

7.6.1 Groovy configuration

With Spring Integration 2.1, Groovy Support's configuration namespace is an extension of Spring Integration's Scripting Support and shares the core configuration and behavior described in detail in the Section 7.5, “Scripting support” section. Even though Groovy scripts are well supported by generic Scripting Support, Groovy Support provides the Groovy configuration namespace which is backed by the Spring Framework's org.springframework.scripting.groovy.GroovyScriptFactory and related components, offering extended capabilities for using Groovy. Below are a couple of sample configurations:

Filter

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

<int:filter input-channel="inlineScriptInput">
     <int-groovy:script><![CDATA[
     return payload == 'good'
   ]]></int-groovy:script>
</int:filter>

As the above examples show, the configuration looks identical to the general Scripting Support configuration. The only difference is the use of the Groovy namespace as indicated in the examples by the int-groovy namespace prefix. Also note that the lang attribute on the <script> tag is not valid in this namespace.

Groovy object customization

If you need to customize the Groovy object itself, beyond setting variables, you can reference a bean that implements org.springframework.scripting.groovy.GroovyObjectCustomizer via the customizer attribute. For example, this might be useful if you want to implement a domain-specific language (DSL) by modifying the MetaClass and registering functions to be available within the script:

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

<beans:bean id="groovyCustomizer" class="org.foo.MyGroovyObjectCustomizer"/>

Setting a custom GroovyObjectCustomizer is not mutually exclusive with <variable> sub-elements or the script-variable-generator attribute. It can also be provided when defining an inline script.

7.6.2 Control Bus

As described in (EIP), the idea behind the Control Bus is that the same messaging system can be used for monitoring and managing the components within the framework as is used for "application-level" messaging. In Spring Integration we build upon the adapters described above so that it's possible to send Messages as a means of invoking exposed operations. One option for those operations is Groovy scripts.

 <int-groovy:control-bus input-channel="operationChannel"/>

The Control Bus has an input channel that can be accessed for invoking operations on the beans in the application context.

The Groovy Control Bus executes messages on the input channel as Groovy scripts. It takes a message, compiles the body to a Script, customizes it with a GroovyObjectCustomizer, and then executes it. The Control Bus' MessageProcessor exposes all beans in the application context that are annotated with @ManagedResource, implement Spring's Lifecycle interface or extend Spring's CustomizableThreadCreator base class (e.g. several of the TaskExecutor and TaskScheduler implementations).

[Important]Important
Be careful about using managed beans with custom scopes (e.g. 'request') in the Control Bus' command scripts, especially inside an async message flow. If The Control Bus' MessageProcessor can't expose a bean from the application context, you may end up with some BeansException during command script's executing. For example, if a custom scope's context is not established, the attempt to get a bean within that scope will trigger a BeanCreationException.

If you need to further customize the Groovy objects, you can also provide a reference to a bean that implements org.springframework.scripting.groovy.GroovyObjectCustomizer via the customizer attribute.

<int-groovy:control-bus input-channel="input"
        output-channel="output"
        customizer="groovyCustomizer"/>

<beans:bean id="groovyCustomizer" class="org.foo.MyGroovyObjectCustomizer"/>

8. System Management

8.1 JMX Support

Spring Integration provides Channel Adapters for receiving and publishing JMX Notifications. There is also an Inbound Channel Adapter for polling JMX MBean attribute values, and an Outbound Channel Adapter for invoking JMX MBean operations.

8.1.1 Notification Listening Channel Adapter

The Notification-listening Channel Adapter requires a JMX ObjectName for the MBean that publishes notifications to which this listener should be registered. A very simple configuration might look like this:

<int-jmx:notification-listening-channel-adapter id="adapter"
    channel="channel"
    object-name="example.domain:name=publisher"/>
[Tip]Tip
The notification-listening-channel-adapter registers with an MBeanServer at startup, and the default bean name is mbeanServer which happens to be the same bean name generated when using Spring's <context:mbean-server/> element. If you need to use a different name, be sure to include the mbean-server attribute.

The adapter can also accept a reference to a NotificationFilter and a handback Object to provide some context that is passed back with each Notification. Both of those attributes are optional. Extending the above example to include those attributes as well as an explicit MBeanServer bean name would produce the following:

<int-jmx:notification-listening-channel-adapter id="adapter"
    channel="channel"
    mbean-server="someServer"
    object-name="example.domain:name=somePublisher"
    notification-filter="notificationFilter"
    handback="myHandback"/>

The Notification-listening Channel Adapter is event-driven and registered with the MBeanServer directly. It does not require any poller configuration.

8.1.2 Notification Publishing Channel Adapter

The Notification-publishing Channel Adapter is relatively simple. It only requires a JMX ObjectName in its configuration as shown below.

<context:mbean:export/>

<int-jmx:notification-publishing-channel-adapter id="adapter"
    channel="channel"
    object-name="example.domain:name=publisher"/>

It does also require that an MBeanExporter be present in the context. That is why the <context:mbean-export/> element is shown above as well.

When Messages are sent to the channel for this adapter, the Notification is created from the Message content. If the payload is a String it will be passed as the message text for the Notification. Any other payload type will be passed as the userData of the Notification.

JMX Notifications also have a type, and it should be a dot-delimited String. There are two ways to provide the type. Precedence will always be given to a Message header value associated with the JmxHeaders.NOTIFICATION_TYPE key. On the other hand, you can rely on a fallback default-notification-type attribute provided in the configuration.

<context:mbean:export/>

<int-jmx:notification-publishing-channel-adapter id="adapter"
    channel="channel"
    object-name="example.domain:name=publisher"
    default-notification-type="some.default.type"/>

8.1.3 Attribute Polling Channel Adapter

The Attribute Polling Channel Adapter is useful when you have a requirement, to periodically check on some value that is available through an MBean as a managed attribute. The poller can be configured in the same way as any other polling adapter in Spring Integration (or it's possible to rely on the default poller). The object-name and attribute-name are required. An MBeanServer reference is also required, but it will automatically check for a bean named mbeanServer by default, just like the Notification-listening Channel Adapter described above.

<int-jmx:attribute-polling-channel-adapter id="adapter"
    channel="channel"
    object-name="example.domain:name=someService"
    attribute-name="InvocationCount">
        <int:poller max-messages-per-poll="1" fixed-rate="5000"/>
</int-jmx:attribute-polling-channel-adapter>

8.1.4 Operation Invoking Channel Adapter

The operation-invoking-channel-adapter enables Message-driven invocation of any managed operation exposed by an MBean. Each invocation requires the operation name to be invoked and the ObjectName of the target MBean. Both of these must be explicitly provided via adapter configuration:

<int-jmx:operation-invoking-channel-adapter id="adapter"
    object-name="example.domain:name=TestBean"
    operation-name="ping"/>

Then the adapter only needs to be able to discover the mbeanServer bean. If a different bean name is required, then provide the mbean-server attribute with a reference.

The payload of the Message will be mapped to the parameters of the operation, if any. A Map-typed payload with String keys is treated as name/value pairs, whereas a List or array would be passed as a simple argument list (with no explicit parameter names). If the operation requires a single parameter value, then the payload can represent that single value, and if the operation requires no parameters, then the payload would be ignored.

If you want to expose a channel for a single common operation to be invoked by Messages that need not contain headers, then that option works well.

8.1.5 Operation Invoking Outbound Gateway

Similar to the operation-invoking-channel-adapter Spring Integration also provides a operation-invoking-outbound-gateway, which could be used when dealing with non-void operations and a return value is required. Such return value will be sent as message payload to the reply-channel specified by this Gateway.

<int-jmx:operation-invoking-outbound-gateway request-channel="requestChannel"
   reply-channel="replyChannel"
   object-name="o.s.i.jmx.config:type=TestBean,name=testBeanGateway"
   operation-name="testWithReturn"/>

If the reply-channel attribute is not provided, the reply message will be sent to the channel that is identified by the MessageHeaders.REPLY_CHANNEL header. That header is typically auto-created by the entry point into a message flow, such as any Gateway component. However, if the message flow was started by manually creating a Spring Integration Message and sending it directly to a Channel, then you must specify the message header explicitly or use the provided reply-channel attribute.

8.1.6 MBean Exporter

Spring Integration components themselves may be exposed as MBeans when the IntegrationMBeanExporter is configured. To create an instance of the IntegrationMBeanExporter, define a bean and provide a reference to an MBeanServer and a domain name (if desired). The domain can be left out, in which case the default domain is org.springframework.integration.

<int-jmx:mbean-export default-domain="my.company.domain" server="mbeanServer"/>

<bean id="mbeanServer" class="org.springframework.jmx.support.MBeanServerFactoryBean">
    <property name="locateExistingServerIfPossible" value="true"/>
</bean>

Once the exporter is defined, start up your application with:

-Dcom.sun.management.jmxremote
    -Dcom.sun.management.jmxremote.port=6969
    -Dcom.sun.management.jmxremote.ssl=false
    -Dcom.sun.management.jmxremote.authenticate=false

Then start JConsole (free with the JDK), and connect to the local process on localhost:6969 to get a look at the management endpoints exposed. (The port and client are just examples to get you started quickly, there are other JMX clients available and some offer more sophisticated features than JConsole.)

The MBean exporter is orthogonal to the one provided in Spring core - it registers message channels and message handlers, but not itself. You can expose the exporter itself, and certain other components in Spring Integration, using the standard <context:mbean-export/> tag. The exporter has a couple of useful metrics attached to it, for instance a count of the number of active handlers and the number of queued messages (these would both be important if you wanted to shutdown the context without losing any messages).

MBean ObjectNames

All the MessageChannel, MessageHandler and MessageSource instances in the application are wrapped by the MBean exporter to provide management and monitoring features. The generated JMX object names for each component type are listed in the table below:

Table 8.1. 

Component TypeObjectName
MessageChannelo.s.i:type=MessageChannel,name=<channelName>
MessageSourceo.s.i:type=MessageSource,name=<channelName>,bean=<source>
MessageHandlero.s.i:type=MessageSource,name=<channelName>,bean=<source>

The bean attribute in the object names for sources and handlers takes one of the values in the table below:

Table 8.2. 

Bean ValueDescription
endpointThe bean name of the enclosing endpoint (e.g. <service-activator>) if there is one
anonymousAn indication that the enclosing endpoint didn't have a user-specified bean name, so the JMX name is the input channel name
internalFor well-known Spring Integration default components
handlerNone of the above: fallback to the toString() of the object being monitored (handler or source)

MessageChannel MBean Features

Message channels report metrics according to their concrete type. If you are looking at a DirectChannel, you will see statistics for the send operation. If it is a QueueChannel, you will also see statistics for the receive operation, as well as the count of messages that are currently buffered by this QueueChannel. In both cases there are some metrics that are simple counters (message count and error count), and some that are estimates of averages of interesting quantities. The algorithms used to calculate these estimates are described briefly in the table below:

Table 8.3. 

Metric TypeExampleAlgorithm
CountSend CountSimple incrementer. Increase by one when an event occurs.
DurationSend Duration (method execution time in milliseconds) Exponential Moving Average with decay factor 10. Average of the method execution time over roughly the last 10 measurements.
RateSend Rate (number of operations per second)Inverse of Exponential Moving Average of the interval between events with decay in time (lapsing over 60 seconds) and per measurement (last 10 events).
RatioSend Error Ratio (ratio of errors to total sends)Estimate the success ratio as the Exponential Moving Average of the series composed of values 1 for success and 0 for failure (decaying as per the rate measurement over time and events). Error ratio is 1 - success ratio.

A feature of the time-based average estimates is that they decay with time if no new measurements arrive. To help interpret the behaviour over time, the time (in seconds) since the last measurement is also exposed as a metric.

There are two basic exponential models: decay per measurement (appropriate for duration and anything where the number of measurements is part of the metric), and decay per time unit (more suitable for rate measurements where the time in between measurements is part of the metric). Both models depend on the fact that

S(n) = sum(i=0,i=n) w(i) x(i)

has a special form when w(i) = r^i, with r=constant:

S(n) = x(n) + r S(n-1)

(so you only have to store S(n-1), not the whole series x(i), to generate a new metric estimate from the last measurement). The algorithms used in the duration metrics use r=exp(-1/M) with M=10. The net effect is that the estimate S(n) is more heavily weighted to recent measurements and is composed roughly of the last M measurements. So M is the "window" or lapse rate of the estimate In the case of the vanilla moving average, i is a counter over the number of measurements. In the case of the rate we interpret i as the elapsed time, or a combination of elapsed time and a counter (so the metric estimate contains contributions roughly from the last M measurements and the last T seconds).

Orderly Shutdown Managed Operation

The MBean exporter provides a JMX operation to shut down the application in an orderly manner, intended for use before terminating the JVM.

public void stopActiveComponents(boolean force, long howLong)

Its use and operation are described in Section 8.5, “Orderly Shutdown”.

8.2 Message History

The key benefit of a messaging architecture is loose coupling where participating components do not maintain any awareness about one another. This fact alone makes your application extremely flexible, allowing you to change components without affecting the rest of the flow, change messaging routes,   message consuming styles (polling vs event driven), and so on. However, this unassuming style of architecture could prove to be difficult when things go wrong. When debugging, you would probably like to get as much information about the message as you can (its origin, channels it has traversed, etc.)

Message History is one of those patterns that helps by giving you an option to maintain some level of awareness of a message path either for debugging purposes or to maintain an audit trail. Spring integration provides a simple way to configure your message flows to maintain the Message History by adding a header to the Message and updating that header every time a message passes through a tracked component.

8.2.1 Message History Configuration

To enable Message History all you need is to define the message-history element in your configuration.

<int:message-history/>

Now every named component (component that has an 'id' defined) will be tracked. The framework will set the 'history' header in your Message. Its value is very simple - List<Properties>.

<int:gateway id="sampleGateway" 
    service-interface="org.springframework.integration.history.sample.SampleGateway"
    default-request-channel="bridgeInChannel"/>

<int:chain id="sampleChain" input-channel="chainChannel" output-channel="filterChannel">
  <int:header-enricher>
    <int:header name="baz" value="baz"/>
  </int:header-enricher>
</int:chain>

The above configuration will produce a very simple Message History structure:

[{name=sampleGateway, type=gateway, timestamp=1283281668091},
 {name=sampleChain, type=chain, timestamp=1283281668094}]

To get access to Message History all you need is access the MessageHistory header. For example:

Iterator<Properties> historyIterator =
    message.getHeaders().get(MessageHistory.HEADER_NAME, MessageHistory.class).iterator();
assertTrue(historyIterator.hasNext());
Properties gatewayHistory = historyIterator.next();
assertEquals("sampleGateway", gatewayHistory.get("name"));
assertTrue(historyIterator.hasNext());
Properties chainHistory = historyIterator.next();
assertEquals("sampleChain", chainHistory.get("name"));

You might not want to track all of the components. To limit the history to certain components based on their names, all you need is provide the tracked-components attribute and specify a comma-delimited list of component names and/or patterns that match the components you want to track.

<int:message-history tracked-components="*Gateway, sample*, foo"/>

In the above example, Message History will only be maintained for all of the components that end with 'Gateway', start with 'sample', or match the name 'foo' exactly.

[Note]Note
Remember that by definition the Message History header is immutable (you can't re-write history, although some try). Therefore, when writing Message History values, the components are either creating brand new Messages (when the component is an origin), or they are copying the history from a request Message, modifying it and setting the new list on a reply Message. In either case, the values can be appended even if the Message itself is crossing thread boundaries. That means that the history values can greatly simplify debugging in an asynchronous message flow.

8.3 Message Store

Enterprise Integration Patterns (EIP) identifies several patterns that have the capability to buffer messages. For example, an Aggregator buffers messages until they can be released and a QueueChannel buffers messages until consumers explicitly receive those messages from that channel. Because of the failures that can occur at any point within your message flow, EIP components that buffer messages also introduce a point where messages could be lost.

To mitigate the risk of losing Messages, EIP defines the Message Store pattern which allows EIP components to store Messages typically in some type of persistent store (e.g. RDBMS).

Spring Integration provides support for the Message Store pattern by a) defining a org.springframework.integration.store.MessageStore strategy interface, b) providing several implementations of this interface, and c) exposing a message-store attribute on all components that have the capability to buffer messages so that you can inject any instance that implements the MessageStore interface.

Details on how to configure a specific Message Store implementation and/or how to inject a MessageStore implementation into a specific buffering component are described throughout the manual (see the specific component, such as QueueChannel, Aggregator, Resequencer etc.), but here are a couple of samples to give you an idea:

QueueChannel

<int:channel id="myQueueChannel">
    <int:queue message-store="refToMessageStore"/> 
<int:channel>

Aggregator

<int:aggregator . . . message-store="refToMessageStore"/>

By default Messages are stored in-memory using org.springframework.integration.store.SimpleMessageStore, an implementation of MessageStore. That might be fine for development or simple low-volume environments where the potential loss of non-persistent messages is not a concern. However, the typical production application will need a more robust option, not only to mitigate the risk of message loss but also to avoid potential out-of-memory errors. Therefore, we also provide MessageStore implementations for a variety of data-stores. Below is a complete list of supported implementations:

[Important]Important

However be aware of some limitations while using persistent implementations of the MessageStore.

The Message data (payload and headers) is serialized and deserialized using different serialization strategies depending on the implementation of the MessageStore. For example, when using JdbcMessageStore, only Serializable data is persisted by default. In this case non-Serializable headers are removed before serialization occurs. Also be aware of the protocol specific headers that are injected by transport adapters (e.g., FTP, HTTP, JMS etc.). For example, <http:inbound-channel-adapter/> maps HTTP-headers into Message Headers and one of them is an ArrayList of non-Serializable org.springframework.http.MediaType instances. However you are able to inject your own implementation of the Serializer and/or Deserializer strategy interfaces into some MessageStore implementations (such as JdbcMessageStore) to change the behaviour of serialization and deserialization.

Special attention must be paid to the headers that represent certain types of data. For example, if one of the headers contains an instance of some Spring Bean, upon deserialization you may end up with a different instance of that bean, which directly affects some of the implicit headers created by the framework (e.g., REPLY_CHANNEL or ERROR_CHANNEL). Currently they are not serializable, but even if they were the deserialized channel would not represent the expected instance. As a workaround we suggest to remove bean-ref headers via a <header-filter/> before sending a message to an endpoint backed by a persistent MessageStore. Also, we recommend using channel names instead of channel instances when setting those types of headers, thus allowing it to be resolved in real time by the ChannelResolver.

Also avoid configuration of a message-flow like this: gateway -> queue-channel (backed by a persistent Message Store) -> service-activator That gateway creates a Temporary Reply Channel in the background, and it will be lost by the time the service-activator's poller reads from the queue, because it has been deserialized by another thread on the sending side.

Nevertheless we are constantly thinking about potential improvements to the framework, such as a way to provide some robust default serialization strategy for messages in these cases.

8.4 Control Bus

As described in (EIP), the idea behind the Control Bus is that the same messaging system can be used for monitoring and managing the components within the framework as is used for "application-level" messaging. In Spring Integration we build upon the adapters described above so that it's possible to send Messages as a means of invoking exposed operations.

<int:control-bus input-channel="operationChannel"/>

The Control Bus has an input channel that can be accessed for invoking operations on the beans in the application context. It also has all the common properties of a service activating endpoint, e.g. you can specify an output channel if the result of the operation has a return value that you want to send on to a downstream channel.

The Control Bus executes messages on the input channel as Spring Expression Language expressions. It takes a message, compiles the body to an expression, adds some context, and then executes it. The default context supports any method that has been annotated with @ManagedAttribute or @ManagedOperation. It also supports the methods on Spring's Lifecycle interface, and it supports methods that are used to configure several of Spring's TaskExecutor and TaskScheduler implementations. The simplest way to ensure that your own methods are available to the Control Bus is to use the @ManagedAttribute and/or @ManagedOperation annotations. Since those are also used for exposing methods to a JMX MBean registry, it's a convenient by-product (often the same types of operations you want to expose to the Control Bus would be reasonable for exposing via JMS). Resolution of any particular instance within the application context is achieved in the typical SpEL syntax. Simply provide the bean name with the SpEL prefix for beans (@). For example, to execute a method on a Spring Bean a client could send a message to the operation channel as follows:

Message operation = MessageBuilder.withPayload("@myServiceBean.shutdown()").build();
operationChannel.send(operation)

The root of the context for the expression is the Message itself, so you also have access to the 'payload' and 'headers' as variables within your expression. This is consistent with all the other expression support in Spring Integration endpoints.

8.5 Orderly Shutdown

As described in Section 8.1.6, “MBean Exporter”, the MBean exporter provides a JMX operation stopActiveComponents, which is used to stop the application in an orderly manner. The operation has two parameters, a boolean and a long. The boolean indicates whether attempts will be made to stop (interrupt) active threads; in most cases this will be set to false for orderly shutdown. The long parameter indicates how long (in milliseconds) the operation will wait to allow in-flight messages to complete. The operation works as follows:

The first step calls beforeShutdown() on all beans that implement OrderlyShutdownCapable. This allows such components to prepare for shutdown. Examples of components that implement this interface, and what they do with this call include: JMS and AMQP message-driven adapters stop their listener containers; TCP server connection factories stop accepting new connections (while keeping existing connections open); TCP inbound endpoints drop (log) any new messages received; http inbound endpoints return 503 - Service Unavailable for any new requests.

The second step stops any active channels, such as JMS- or AMQP-backed channels.

The third step stops all TaskSchedulers, preventing any new scheduled operations (polling etc).

The fourth step stops all TaskExecutors, preventing any new tasks from running.

[Note]Note
If the shutdown is running from a Spring-managed TaskExecutor, shutting down that executor would cause all the timeout time to be consumed by this step, because the thread won't terminate). For this reason, either use a dedicated executor (via the shutdownExecutor property on the MBean exporter), or do not use a Spring-managed executor to invoke this operation.

The fifth step stops all MessageSources.

The sixth step waits for any remaining time left, as defined by the value of the long parameter passed in to the operation. This is intended to allow any in-flight messages to complete their journeys. It is therefore important to select an appropriate timeout when invoking this operation.

The seventh step calls afterShutdown() on all OrderlyShutdownCapable components. This allows such components to perform final shutdown tasks (closing all open sockets, for example).

[Note]Note
If no time is left when we get to step 6, it probably means some thread is hung; in which case, the operation attempts a forced shutdown on all schedulers and executors before exiting.

Part IV. Integration Adapters

This section covers the various Channel Adapters and Messaging Gateways provided by Spring Integration to support Message-based communication with external systems.

9. AMQP Support

9.1 Introduction

Spring Integration provides Channel Adapters for receiving and sending messages using the Advanced Message Queuing Protocol (AMQP). The following adapters are available:

  • Inbound Channel Adapter
  • Outbound Channel Adapter
  • Inbound Gateway
  • Outbound Gateway

Spring Integration also provides a point-to-point Message Channel as well as a publish/subscribe Message Channel backed by AMQP Exchanges and Queues.

In order to provide AMQP support, Spring Integration relies on Spring AMQP (http://www.springsource.org/spring-amqp) which "applies core Spring concepts to the development of AMQP-based messaging solutions". Spring AMQP provides similar semantics as Spring JMS (http://.../spring-framework-reference.html#jms).

Whereas the provided AMQP Channel Adapters are intended for unidirectional Messaging (send or receive) only, Spring Integration also provides inbound and outbound AMQP Gateways for request/reply operations.

[Tip]Tip

Please familiarize yourself with the reference documentation of the Spring AMQP project as well. It provides much more in-depth information regarding Spring's integration with AMQP in general and RabbitMQ in particular.

You can find the documentation at: http://static.springsource.org/spring-amqp/docs/1.0.x/reference/html/

9.2 Inbound Channel Adapter

A configuration sample for an AMQP Inbound Channel Adapter is shown below with all available parameters.

<int-amqp:inbound-channel-adapter id="inboundAmqp"1
                                  channel="inboundChannel"2
                                  queue-names="si.test.queue"3
                                  acknowledge-mode="AUTO"4
                                  advice-chain=""5
                                  channel-transacted=""6
                                  concurrent-consumers=""7
                                  connection-factory=""8
                                  error-channel=""9
                                  expose-listener-channel=""10
                                  header-mapper=""11
                                  mapped-request-headers=""12
                                  mapped-reply-headers=""13
                                  listener-container=""14
                                  message-converter=""15
                                  message-properties-converter=""(16)
                                  phase=""(17)
                                  prefetch-count=""(18)
                                  receive-timeout=""(19)
                                  recovery-interval=""(20)
                                  shutdown-timeout=""(21)
                                  task-executor=""(22)
                                  transaction-attribute=""(23)
                                  transaction-manager=""(24)
                                  tx-size=""(25)/>
    

1

Unique ID for this adapter. Optional.

2

Message Channel to which converted Messages should be sent. Required.

3

Names of the AMQP Queues from which Messages should be consumed (comma-separated list). Required.

4

Acknowledge Mode for the MessageListenerContainer. Optional (Defaults to AUTO).

5

Extra AOP Advice(s) to handle cross cutting behavior associated with this Inbound Channel Adapter. Optional.

6

Flag to indicate that channels created by this component will be transactional. Ff true, tells the framework to use a transactional channel and to end all operations (send or receive) with a commit or rollback depending on the outcome, with an exception signalling a rollback. Optional (Defaults to false).

7

Specify the number of concurrent consumers to create. Default is 1. Raising the number of concurrent consumers is recommended in order to scale the consumption of messages coming in from a queue. However, note that any ordering guarantees are lost once multiple consumers are registered. In general, stick with 1 consumer for low-volume queues. Optional.

8

Bean reference to the RabbitMQ ConnectionFactory. Optional (Defaults to 'connectionFactory').

9

Message Channel to which error Messages should be sent. Optional.

10

Shall the listener channel (com.rabbitmq.client.Channel) be exposed to a registered ChannelAwareMessageListener. Optional (Defaults to true).

11

HeaderMapper to use when receiving AMQP Messages. Optional. By default only standard AMQP properties (e.g. contentType) will be copied to and from Spring Integration MessageHeaders. Any user-defined headers within the AMQP MessageProperties will NOT be copied to or from an AMQP Message unless explicitly identified via 'requestHeaderNames' and/or 'replyHeaderNames' properties of this HeaderMapper. If you need to copy all user-defined headers simply use wild-card character '*'.

12

Comma-separated list of names of AMQP Headers to be mapped from the AMQP request into the MessageHeaders. This can only be provided if the 'header-mapper' reference is not being set directly. The values in this list can also be simple patterns to be matched against the header names (e.g. "*" or "foo*, bar" or "*foo").

13

Comma-separated list of names of MessageHeaders to be mapped into the AMQP Message Properties of the AMQP reply message. All standard Headers (e.g., contentType) will be mapped to AMQP Message Properties while user-defined headers will be mapped to 'headers' property which itself is a Map. This can only be provided if the 'header-mapper' reference is not being set directly. The values in this list can also be simple patterns to be matched against the header names (e.g. "*" or "foo*, bar" or "*foo").

14

Reference to the SimpleMessageListenerContainer to use for receiving AMQP Messages. If this attribute is provided, then no other attribute related to the listener container configuration should be provided. In other words, by setting this reference, you must take full responsibility of the listener container configuration. The only exception is the MessageListener itself. Since that is actually the core responsibility of this Channel Adapter implementation, the referenced listener container must NOT already have its own MessageListener configured. Optional.

15

The MessageConverter to use when receiving AMQP Messages. Optional.

(16)

The MessagePropertiesConverter to use when receiving AMQP Messages. Optional.

(17)

Specify the phase in which the underlying SimpleMessageListenerContainer should be started and stopped. The startup order proceeds from lowest to highest, and the shutdown order is the reverse of that. By default this value is Integer.MAX_VALUE meaning that this container starts as late as possible and stops as soon as possible. Optional.

(18)

Tells the AMQP broker how many messages to send to each consumer in a single request. Often this can be set quite high to improve throughput. It should be greater than or equal to the transaction size (see attribute "tx-size"). Optional (Defaults to 1).

(19)

Receive timeout in milliseconds. Optional (Defaults to 1000).

(20)

Specifies the interval between recovery attempts of the underlying SimpleMessageListenerContainer (in milliseconds). Optional (Defaults to 5000).

(21)

The time to wait for workers in milliseconds after the underlying SimpleMessageListenerContainer is stopped, and before the AMQP connection is forced closed. If any workers are active when the shutdown signal comes they will be allowed to finish processing as long as they can finish within this timeout. Otherwise the connection is closed and messages remain unacked (if the channel is transactional). Defaults to 5000 milliseconds. Optional (Defaults to 5000).

(22)

By default, the underlying SimpleMessageListenerContainer uses a SimpleAsyncTaskExecutor implementation, that fires up a new Thread for each task, executing it asynchronously. By default, the number of concurrent threads is unlimited. NOTE: This implementation does not reuse threads. Consider a thread-pooling TaskExecutor implementation as an alternative. Optional (Defaults to SimpleAsyncTaskExecutor).

(23)

By default the underlying SimpleMessageListenerContainer creates a new instance of the DefaultTransactionAttribute (takes the EJB approach to rolling back on runtime, but not checked exceptions. Optional (Defaults to DefaultTransactionAttribute).

(24)

Sets a Bean reference to an external PlatformTransactionManager on the underlying SimpleMessageListenerContainer. The transaction manager works in conjunction with the "channel-transacted" attribute. If there is already a transaction in progress when the framework is sending or receiving a message, and the channelTransacted flag is true, then the commit or rollback of the messaging transaction will be deferred until the end of the current transaction. If the channelTransacted flag is false, then no transaction semantics apply to the messaging operation (it is auto-acked). For further information see chapter 1.9 of the Spring AMQP reference guide: http://static.springsource.org/spring-amqp/docs/1.0.x/reference/html/#d0e525 Optional.

(25)

Tells the SimpleMessageListenerContainer how many messages to process in a single transaction (if the channel is transactional). For best results it should be less than or equal to the set "prefetch-count". Optional (Defaults to 1).

[Important]Important

Even though the Spring Integration JMS and AMQP support is very similar, important differences exist. The JMS Inbound Channel Adapter is using a JmsDestinationPollingSource under the covers and expects a configured Poller. The AMQP Inbound Channel Adapter on the other side uses a SimpleMessageListenerContainer and is message driven. In that regard it is more similar to the JMS Message Driven Channel Adapter.

9.3 Outbound Channel Adapter

A configuration sample for an AMQP Outbound Channel Adapter is shown below with all available parameters.

<int-amqp:outbound-channel-adapter id="outboundAmqp"1
                               channel="outboundChannel"2
                               amqp-template="myAmqpTemplate"3
                               exchange-name=""4
                               order="1"5
                               routing-key=""6
                               routing-key-expression=""7
                               confirm-correlation-expression=""8
                               confirm-ack-channel=""9
                               confirm-nack-channel=""10
                               return-channel=""11/>
    

1

Unique ID for this adapter. Optional.

2

Message Channel to which Messages should be sent in order to have them converted and published to an AMQP Exchange. Required.

3

Bean Reference to the configured AMQP Template Optional (Defaults to "amqpTemplate").

4

The name of the AMQP Exchange to which Messages should be sent. If not provided, Messages will be sent to the default, no-name Exchange. Optional.

5

The order for this consumer when multiple consumers are registered thereby enabling load- balancing and/or failover. Optional (Defaults to Ordered.LOWEST_PRECEDENCE [=Integer.MAX_VALUE]).

6

The fixed routing-key to use when sending Messages. By default, this will be an empty String. Optional.

7

The routing-key to use when sending Messages evaluated as an expression on the message (e.g. 'payload.key'). By default, this will be an empty String. Optional.

8

An expression defining correlation data. When provided, this configures the underlying amqp template to receive publisher confirms. Requires a RabbitTemplate and a CachingConnectionFactory with publisherConfirms enabled. When a publisher confirm is received, it is written to either the confirm-ack-channel, or the confirm-nack-channel, depending on the confirmation type. The payload of the confirm is the correlation data as defined by this expression and the message will have a header 'amqp_publishConfirm' set to true (ack) or false (nack). Examples: "headers['myCorrelationData']", "payload". Optional.

9

The channel to which positive (ack) publisher confirms are sent; payload is the correlation data defined by the confirm-correlation-expression. Optional, default=nullChannel.

10

The channel to which negative (nack) publisher confirms are sent; payload is the correlation data defined by the confirm-correlation-expression. Optional, default=nullChannel.

11

The channel to which returned messages are sent. When provided, the underlying amqp template is configured to return undeliverable messages. The message will be constructed from the data received from amqp, with the following additional headers: amqp_returnReplyCode, amqp_returnReplyText, amqp_returnExchange, amqp_returnRoutingKey. Optional.

9.4 Inbound Gateway

A configuration sample for an AMQP Inbound Gateway is shown below with all available parameters.

<int-amqp:inbound-gateway id="inboundGateway"1
                          request-channel="myRequestChannel"2
                          queue-names="si.test.queue"3
                          advice-chain=""4
                          concurrent-consumers="1"5
                          connection-factory="connectionFactory"6
                          reply-channel="myReplyChannel"7/>
      

1

Unique ID for this adapter. Optional.

2

Message Channel to which converted Messages should be sent. Required.

3

Names of the AMQP Queues from which Messages should be consumed (comma-separated list). Required.

4

Extra AOP Advice(s) to handle cross cutting behavior associated with this Inbound Gateway. Optional.

5

Specify the number of concurrent consumers to create. Default is 1. Raising the number of concurrent consumers is recommended in order to scale the consumption of messages coming in from a queue. However, note that any ordering guarantees are lost once multiple consumers are registered. In general, stick with 1 consumer for low-volume queues. Optional (Defaults to 1).

6

Bean reference to the RabbitMQ ConnectionFactory. Optional (Defaults to 'connectionFactory').

7

Message Channel where reply Messages will be expected. Optional.

9.5 Outbound Gateway

A configuration sample for an AMQP Outbound Gateway is shown below with all available parameters.

<int-amqp:outbound-gateway id="inboundGateway"1
                           request-channel="myRequestChannel"2
                           amqp-template=""3
                           exchange-name=""4
                           order="1"5
                           reply-channel=""6
                           routing-key=""7
                           routing-key-expression=""8
                           return-channel=""9/>
      

1

Unique ID for this adapter. Optional.

2

Message Channel to which Messages should be sent in order to have them converted and published to an AMQP Exchange. Required.

3

Bean Reference to the configured AMQP Template Optional (Defaults to "amqpTemplate").

4

The name of the AMQP Exchange to which Messages should be sent. If not provided, Messages will be sent to the default, no-name Exchange. Optional.

5

The order for this consumer when multiple consumers are registered thereby enabling load- balancing and/or failover. Optional (Defaults to Ordered.LOWEST_PRECEDENCE [=Integer.MAX_VALUE]).

6

Message Channel to which replies should be sent after being received from an AQMP Queue and converted. Optional.

7

The routing-key to use when sending Messages. By default, this will be an empty String. Optional.

8

The routing-key to use when sending Messages evealuated as an expression on the message (e.g. 'payload.key'). By default, this will be an empty String. Optional.

9

The channel to which returned messages are sent. When provided, the underlying amqp template is configured to return undeliverable messages. The message will be constructed from the data received from amqp, with the following additional headers: amqp_returnReplyCode, amqp_returnReplyText, amqp_returnExchange, amqp_returnRoutingKey. Optional.

[Note]Note

Prior to Spring Integration 2.2, and Spring AMQP 1.1, the outbound gateway used a new, temporary, reply queue for each request. This is still the default, but now the RabbitTemplate can be configured with a specific queue for replies; headers are added to the outbound message for request/reply correlation. It is important that the consuming application returns these headers unchanged. The headers are spring_reply_correlation and spring_reply_to. If the consuming application is a Spring Integration application, these headers will be managed automatically, including the case where that application might send a request/reply to a third application using an outbound gateway.

9.6 AMQP Backed Message Channels

There are two Message Channel implementations available. One is point-to-point, and the other is publish/subscribe. Both of these channels provide a wide range of configuration attributes for the underlying AmqpTemplate and SimpleMessageListenerContainer as you have seen on the Channel Adapters and Gateways. However, the examples we'll show here are going to have minimal configuration. Explore the XML schema to view the available attributes.

A point-to-point channel would look like this:

<int-amqp:channel id="p2pChannel"/>

Under the covers a Queue named "si.p2pChannel" would be declared, and this channel will send to that Queue (technically by sending to the no-name Direct Exchange with a routing key that matches this Queue's name). This channel will also register a consumer on that Queue. If for some reason, you want the Queue to be "pollable" instead of message-driven, then simply provide the "message-driven" flag with a value of false:

<int-amqp:channel id="p2pPollableChannel"  message-driven="false"/>

A publish/subscribe channel would look like this:

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

Under the covers a Fanout Exchange named "si.fanout.pubSubChannel" would be declared, and this channel will send to that Fanout Exchange. This channel will also declare a server-named exclusive, autodelete, non-durable Queue and bind that to the Fanout Exchange while registering a consumer on that Queue to receive Messages. There is no "pollable" option for a publish-subscribe-channel; it must be message-driven.

9.7 AMQP Message Headers

The Spring Integration AMPQ Adapters will map standard AMQP properties automatically. These properties will be copied by default to and from Spring Integration MessageHeaders using the DefaultAmqpHeaderMapper.

Of course, you can pass in your own implementation of AMQP specific header mappers, as the adapters have respective properties to support that.

Any user-defined headers within the AMQP MessageProperties will NOT be copied to or from an AMQP Message, unless explicitly specified by the requestHeaderNames and/or replyHeaderNames properties of the HeaderMapper.

[Tip]Tip
When mapping user-defined headers, the values can also contain simple wildcard patterns (e.g. "foo*" or "*foo") to be matched. For example, if you need to copy all user-defined headers simply use the wild-card character '*'.

Class AmqpHeaders identifies the default headers that will be used by the DefaultAmqpHeaderMapper:

  • amqp_appId
  • amqp_clusterId
  • amqp_contentEncoding
  • amqp_contentLength
  • content-type
  • amqp_correlationId
  • amqp_deliveryMode
  • amqp_deliveryTag
  • amqp_expiration
  • amqp_messageCount
  • amqp_messageId
  • amqp_receivedExchange
  • amqp_receivedRoutingKey
  • amqp_redelivered
  • amqp_replyTo
  • amqp_timestamp
  • amqp_type
  • amqp_userId
  • amqp_springReplyCorrelation
  • amqp_springReplyToStack
  • amqp_publishConfirm
  • amqp_returnReplyCode
  • amqp_returnReplyText
  • amqp_returnExchange
  • amqp_returnRoutingKey

9.8 AMQP Samples

To experiment with the AMQP adapters, check out the samples available in the Spring Integration Samples Git repository at:

Currently there is one sample available that demonstrates the basic functionality of the Spring Integration AMQP Adapter using an Outbound Channel Adapter and an Inbound Channel Adapter. As AMQP Broker implementation the sample uses RabbitMQ (http://www.rabbitmq.com/).

[Note]Note
In order to run the example you will need a running instance of RabbitMQ. A local installation with just the basic defaults will be sufficient. For detailed RabbitMQ installation procedures please visit: http://www.rabbitmq.com/install.html

Once the sample application is started, you enter some text on the command prompt and a message containing that entered text is dispatched to the AMQP queue. In return that message is retrieved via Spring Integration and then printed to the console.

The image belows illustrates the basic set of Spring Integration components used in this sample.

The Spring Integration graph of the AMQP sample

10. Spring ApplicationEvent Support

Spring Integration provides support for inbound and outbound ApplicationEvents as defined by the underlying Spring Framework. For more information about Spring's support for events and listeners, refer to the Spring Reference Manual.

10.1 Receiving Spring ApplicationEvents

To receive events and send them to a channel, simply define an instance of Spring Integration's ApplicationEventListeningMessageProducer. This class is an implementation of Spring's ApplicationListener interface. By default it will pass all received events as Spring Integration Messages. To limit based on the type of event, configure the list of event types that you want to receive with the 'eventTypes' property. If a received event has a Message instance as its 'source', then that will be passed as-is. Otherwise, if a SpEL-based "payloadExpression" has been provided, that will be evaluated against the ApplicationEvent instance. If the event's source is not a Message instance and no "payloadExpression" has been provided, then the ApplicationEvent itself will be passed as the payload.

For convenience namespace support is provided to configure an ApplicationEventListeningMessageProducer via the inbound-channel-adapter element.

<int-event:inbound-channel-adapter channel="eventChannel" 
                                   error-channel="eventErrorChannel"
                                   event-types="example.FooEvent, example.BarEvent"/>

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

In the above example, all Application Context events that match one of the types specified by the 'event-types' (optional) attribute will be delivered as Spring Integration Messages to the Message Channel named 'eventChannel'. If a downstream component throws an exception, a MessagingException containing the failed message and exception will be sent to the channel named 'eventErrorChannel'. If no "error-channel" is specified and the downstream channels are synchronous, the Exception will be propagated to the caller.

10.2 Sending Spring ApplicationEvents

To send Spring ApplicationEvents, create an instance of the ApplicationEventPublishingMessageHandler and register it within an endpoint. This implementation of the MessageHandler interface also implements Spring's ApplicationEventPublisherAware interface and thus acts as a bridge between Spring Integration Messages and ApplicationEvents.

For convenience namespace support is provided to configure an ApplicationEventPublishingMessageHandler via the outbound-channel-adapter element.

<int:channel id="eventChannel"/>

<int-event:outbound-channel-adapter channel="eventChannel"/>

If you are using a PollableChannel (e.g., Queue), you can also provide poller as a sub-element of the outbound-channel-adapter element. You can also optionally provide a task-executor reference for that poller. The following example demonstrates both.

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

<int-event:outbound-channel-adapter channel="eventChannel">
  <int:poller max-messages-per-poll="1" task-executor="executor" fixed-rate="100"/>
</int-event:outbound-channel-adapter>

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

In the above example, all messages sent to the 'eventChannel' channel will be published as ApplicationEvents to any relevant ApplicationListener instances that are registered within the same Spring ApplicationContext. If the payload of the Message is an ApplicationEvent, it will be passed as-is. Otherwise the Message itself will be wrapped in a MessagingEvent instance.

11. Feed Adapter

Spring Integration provides support for Syndication via Feed Adapters

11.1 Introduction

Web syndication is a form of publishing material such as news stories, press releases, blog posts, and other items typically available on a website but also made available in a feed format such as RSS or ATOM.

Spring integration provides support for Web Syndication via its 'feed' adapter and provides convenient namespace-based configuration for it. To configure the 'feed' namespace, include the following elements within the headers of your XML configuration file:

xmlns:int-feed="http://www.springframework.org/schema/integration/feed"
xsi:schemaLocation="http://www.springframework.org/schema/integration/feed 
	http://www.springframework.org/schema/integration/feed/spring-integration-feed.xsd"

11.2 Feed Inbound Channel Adapter

The only adapter that is really needed to provide support for retrieving feeds is an inbound channel adapter. This allows you to subscribe to a particular URL. Below is an example configuration:

<int-feed:inbound-channel-adapter id="feedAdapter" 
		channel="feedChannel" 
		url="http://feeds.bbci.co.uk/news/rss.xml">
	<int:poller fixed-rate="10000" max-messages-per-poll="100" />
</int-feed:inbound-channel-adapter>

In the above configuration, we are subscribing to a URL identified by the url attribute.

As news items are retrieved they will be converted to Messages and sent to a channel identified by the channel attribute. The payload of each message will be a com.sun.syndication.feed.synd.SyndEntry instance. That encapsulates various data about a news item (content, dates, authors, etc.).

You can also see that the Inbound Feed Channel Adapter is a Polling Consumer. That means you have to provide a poller configuration. However, one important thing you must understand with regard to Feeds is that its inner-workings are slightly different then most other poling consumers. When an Inbound Feed adapter is started, it does the first poll and receives a com.sun.syndication.feed.synd.SyndEntryFeed instance. That is an object that contains multiple SyndEntry objects. Each entry is stored in the local entry queue and is released based on the value in the max-messages-per-poll attribute such that each Message will contain a single entry. If during retrieval of the entries from the entry queue the queue had become empty, the adapter will attempt to update the Feed thereby populating the queue with more entries (SyndEntry instances) if available. Otherwise the next attempt to poll for a feed will be determined by the trigger of the poller (e.g., every 10 seconds in the above configuration).

Duplicate Entries

Polling for a Feed might result in entries that have already been processed ("I already read that news item, why are you showing it to me again?"). Spring Integration provides a convenient mechanism to eliminate the need to worry about duplicate entries. Each feed entry will have a published date field. Every time a new Message is generated and sent, Spring Integration will store the value of the latest published date in an instance of the org.springframework.integration.store.MetadataStore strategy. The MetadataStore interface is designed to store various types of generic meta-data (e.g., published date of the last feed entry that has been processed) to help components such as this Feed adapter deal with duplicates.

The default rule for locating this metadata store is as follows: Spring Integration will look for a bean of type org.springframework.integration.store.MetadataStore in the ApplicationContext. If one is found then it will be used, otherwise it will create a new instance of SimpleMetadataStore which is an in-memory implementation that will only persist metadata within the lifecycle of the currently running Application Context. This means that upon restart you may end up with duplicate entries. If you need to persist metadata between Application Context restarts, you may use the PropertiesPersistingMetadataStore which is backed by a properties file and a properties-persister. Alternatively, you could provide your own implementation of the MetadataStore interface (e.g. JdbcMetadataStore) and configure it as bean in the Application Context.

<bean id="metadataStore" 
    class="org.springframework.integration.store.PropertiesPersistingMetadataStore"/>

12. File Support

12.1 Introduction

Spring Integration's File support extends the Spring Integration Core with a dedicated vocabulary to deal with reading, writing, and transforming files. It provides a namespace that enables elements defining Channel Adapters dedicated to files and support for Transformers that can read file contents into strings or byte arrays.

This section will explain the workings of FileReadingMessageSource and FileWritingMessageHandler and how to configure them as beans. Also the support for dealing with files through file specific implementations of Transformer will be discussed. Finally the file specific namespace will be explained.

12.2 Reading Files

A FileReadingMessageSource can be used to consume files from the filesystem. This is an implementation of MessageSource that creates messages from a file system directory.

<bean id="pollableFileSource"
      class="org.springframework.integration.file.FileReadingMessageSource"
        p:inputDirectory="${input.directory}"/>

To prevent creating messages for certain files, you may supply a FileListFilter. By default, an AcceptOnceFileListFilter is used. This filter ensures files are picked up only once from the directory.

<bean id="pollableFileSource"
      class="org.springframework.integration.file.FileReadingMessageSource"
        p:inputDirectory="${input.directory}"
        p:filter-ref="customFilterBean"/>

A common problem with reading files is that a file may be detected before it is ready. The default AcceptOnceFileListFilter does not prevent this. In most cases, this can be prevented if the file-writing process renames each file as soon as it is ready for reading. A filename-pattern or filename-regex filter that accepts only files that are ready (e.g. based on a known suffix), composed with the default AcceptOnceFileListFilter allows for this. The CompositeFileListFilter enables the composition.

<bean id="pollableFileSource"
      class="org.springframework.integration.file.FileReadingMessageSource"
        p:inputDirectory="${input.directory}"
        p:filter-ref="compositeFilter"/>
<bean id="compositeFilter"
      class="org.springframework.integration.file.filters.CompositeFileListFilter">
  <constructor-arg>
    <list>
      <bean class="org.springframework.integration.file.filters.AcceptOnceFileListFilter"/>
      <bean class="org.springframework.integration.file.filters.RegexPatternFileListFilter">
        <constructor-arg value="^test.*$"/>
      </bean>
    </list>
  </constructor-arg>
</bean>

The configuration can be simplified using the file specific namespace. To do this use the following template.

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

Within this namespace you can reduce the FileReadingMessageSource and wrap it in an inbound Channel Adapter like this:

 <int-file:inbound-channel-adapter id="filesIn1"
           directory="file:${input.directory}" prevent-duplicates="true"/>

 <int-file:inbound-channel-adapter id="filesIn2"
           directory="file:${input.directory}"
           filter="customFilterBean" />

 <int-file:inbound-channel-adapter id="filesIn3"
           directory="file:${input.directory}"
           filename-pattern="test*" />

 <int-file:inbound-channel-adapter id="filesIn4"
           directory="file:${input.directory}"
           filename-regex="test[0-9]+\.txt" />              

The first channel adapter is relying on the default filter that just prevents duplication, the second is using a custom filter, the third is using the filename-pattern attribute to add an AntPathMatcher based filter, and the fourth is using the filename-regex attribute to add a regular expression Pattern based filter to the FileReadingMessageSource. The filename-pattern and filename-regex attributes are each mutually exclusive with the regular filter reference attribute. However, you can use the filter attribute to reference an instance of CompositeFileListFilter that combines any number of filters, including one or more pattern based filters to fit your particular needs.

When multiple processes are reading from the same directory it can be desirable to lock files to prevent them from being picked up concurrently. To do this you can use a FileLocker. There is a java.nio based implementation available out of the box, but it is also possible to implement your own locking scheme. The nio locker can be injected as follows

 <int-file:inbound-channel-adapter id="filesIn"
         directory="file:${input.directory}" prevent-duplicates="true">
     <int-file:nio-locker/>
 </int-file:inbound-channel-adapter>

A custom locker you can configure like this:

 <int-file:inbound-channel-adapter id="filesIn"
         directory="file:${input.directory}" prevent-duplicates="true">
     <int-file:locker ref="customLocker"/>
 </int-file:inbound-channel-adapter>

[Note]Note
When a file inbound adapter is configured with a locker, it will take the responsibility to acquire a lock before the file is allowed to be received. It will not assume the responsibility to unlock the file. If you have processed the file and keeping the locks hanging around you have a memory leak. If this is a problem in your case you should call FileLocker.unlock(File file) yourself at the appropriate time.

When filtering and locking files is not enough it might be needed to control the way files are listed entirely. To implement this type of requirement you can use an implementation of DirectoryScanner. This scanner allows you to determine entirely what files are listed each poll. This is also the interface that Spring Integration uses internally to wire FileListFilters FileLocker to the FileReadingMessageSource. A custom DirectoryScanner can be injected into the <int-file:inbound-channel-adapter/> on the scanner attribute.

 <int-file:inbound-channel-adapter id="filesIn" directory="file:${input.directory}"
       prevent-duplicates="true" scanner="customDirectoryScanner"/>

This gives you full freedom to choose the ordering, listing and locking strategies.

12.3 Writing files

To write messages to the file system you can use a FileWritingMessageHandler. This class can deal with File, String, or byte array payloads. In its simplest form the FileWritingMessageHandler only requires a destination directory for writing the files. The name of the file to be written is determined by the handler's FileNameGenerator. The default implementation looks for a Message header whose key matches the constant defined as FileHeaders.FILENAME.

Additionally, you can configure the encoding and the charset that will be used in case of a String payload.

To make things easier, you can configure the FileWritingMessageHandler as part of an Outbound Channel Adapter or Outbound Gateway using the provided XML namespace support.

12.3.1 Specifying the Output Directory

Both, the File Oubound Channel Adapter and the File Outbound Gateway provide two configuration attributes for specifying the output directory:

  • directory

  • directory-expression

[Note]Note
The directory-expression attribute is available since Spring Integration 2.2.

Using the directory attribute

When using the directory attribute, the output directory will be set to a fixed value, that is set at intialization time of the FileWritingMessageHandler. If you don't specify this attribute, then you must use the directory-expression attribute.

Using the directory-expression attribute

If you want to have full SpEL support you would choose the directory-expression attribute. This attribute accepts a SpEL expression that is evaluated for each message being processed. Thus, you have full access to a Message's payload and its headers to dynamically specify the output file directory.

The SpEL expression must resolve to either a String or to java.io.File. Furthermore the resulting String or File must point to a directory. If you don't specify the directory-expression attribute, then you must set the directory attribute.

Using the auto-create-directory attribute

If the destination directory does not exists, yet, by default the respective destination directory and any non-existing parent directories are being created automatically. You can set the auto-create-directory attribute to false in order to prevent that. This attribute applies to both, the directory and the directory-expression attribute.

[Note]Note

When using the directory attribute and auto-create-directory is false, the following change was made starting with Spring Integration 2.2:

Instead of checking for the existence of the destination directory at initialization time of the adapter, this check is now performed for each message being processed.

Furthermore, if auto-create-directory is true and the directory was deleted between the processing of messages, the directory will be re-created for each message being processed.

12.3.2 Dealing with Existing Destination Files

When writing files and the destination file already exists, the default behavior is to overwrite that target file. This behavior, though, can be changed by setting the mode attribute on the respective File Outbound components. The following options exist:

  • REPLACE (Default)
  • APPEND
  • FAIL
  • IGNORE
[Note]Note
The mode attribute and the options APPEND, FAIL and IGNORE, are available since Spring Integration 2.2.

REPLACE

If the target file already exists, it will be overwritten. If the mode attribute is not specified, then this is the default behavior when writing files.

APPEND

This mode allows you to append Message content to the existing file instead of creating a new file each time. Note that this attribute is mutually exclusive with temporary-file-suffix attribute since when appending content to the existing file, the adapter no longer uses a temporary file.

FAIL

If the target file exists, a MessageHandlingException is thrown.

IGNORE

If the target file exists, the message payload is silently ignored.

12.3.3 File Outbound Channel Adapter

 <int-file:outbound-channel-adapter id="filesOut" directory="${input.directory.property}"/>

The namespace based configuration also supports a delete-source-files attribute. If set to true, it will trigger the deletion of the original source files after writing to a destination. The default value for that flag is false.

 <int-file:outbound-channel-adapter id="filesOut"
    directory="${output.directory}"
    delete-source-files="true"/>
[Note]Note
The delete-source-files attribute will only have an effect if the inbound Message has a File payload or if the FileHeaders.ORIGINAL_FILE header value contains either the source File instance or a String representing the original file path.

12.3.4 Outbound Gateway

In cases where you want to continue processing messages based on the written file, you can use the outbound-gateway instead. It plays a very similar role as the outbound-channel-adapter. However, after writing the file, it will also send it to the reply channel as the payload of a Message.

<int-file:outbound-gateway id="mover" request-channel="moveInput"
    reply-channel="output"
    directory="${output.directory}"
    mode="REPLACE" delete-source-files="true"/>

As mentioned earlier, you can also specify the mode attribute, which defines the behavior of how to deal with situations where the destination file already exists. Please see Section 12.3.2, “Dealing with Existing Destination Files” for further details. Generally, when using the File Outbound Gateway, the result file is returned as the Message payload on the reply channel.

This also applies when specifying the IGNORE mode. In that case the pre-existing destination file is returned. If the payload of the request message was a file, you still have access to that original file through the Message Header FileHeaders.ORIGINAL_FILE.

[Note]Note
The 'outbound-gateway' works well in cases where you want to first move a file and then send it through a processing pipeline. In such cases, you may connect the file namespace's 'inbound-channel-adapter' element to the 'outbound-gateway' and then connect that gateway's reply-channel to the beginning of the pipeline.

If you have more elaborate requirements or need to support additional payload types as input to be converted to file content you could extend the FileWritingMessageHandler, but a much better option is to rely on a Transformer.

12.4 File Transformers

To transform data read from the file system to objects and the other way around you need to do some work. Contrary to FileReadingMessageSource and to a lesser extent FileWritingMessageHandler, it is very likely that you will need your own mechanism to get the job done. For this you can implement the Transformer interface. Or extend the AbstractFilePayloadTransformer for inbound messages. Some obvious implementations have been provided.

FileToByteArrayTransformer transforms Files into byte[]s using Spring's FileCopyUtils. It is often better to use a sequence of transformers than to put all transformations in a single class. In that case the File to byte[] conversion might be a logical first step.

FileToStringTransformer will convert Files to Strings as the name suggests. If nothing else, this can be useful for debugging (consider using with a Wire Tap).

To configure File specific transformers you can use the appropriate elements from the file namespace.

 <int-file:file-to-bytes-transformer  input-channel="input" output-channel="output"
             delete-files="true"/>

 <int-file:file-to-string-transformer input-channel="input" output-channel="output"
             delete-files="true" charset="UTF-8"/>

The delete-files option signals to the transformer that it should delete the inbound File after the transformation is complete. This is in no way a replacement for using the AcceptOnceFileListFilter when the FileReadingMessageSource is being used in a multi-threaded environment (e.g. Spring Integration in general).

13. FTP/FTPS Adapters

Spring Integration provides support for file transfer operations via FTP and FTPS.

13.1 Introduction

The File Transfer Protocol (FTP) is a simple network protocol which allows you to transfer files between two computers on the Internet.

There are two actors when it comes to FTP communication: client and server. To transfer files with FTP/FTPS, you use a client which initiates a connection to a remote computer that is running an FTP server. After the connection is established, the client can choose to send and/or receive copies of files.

Spring Integration supports sending and receiving files over FTP/FTPS by providing three client side endpoints: Inbound Channel Adapter, Outbound Channel Adapter, and Outbound Gateway. It also provides convenient namespace-based configuration options for defining these client components.

To use the FTP namespace, add the following to the header of your XML file:

xmlns:int-ftp="http://www.springframework.org/schema/integration/ftp"
xsi:schemaLocation="http://www.springframework.org/schema/integration/ftp 
	http://www.springframework.org/schema/integration/ftp/spring-integration-ftp.xsd"

13.2 FTP Session Factory

Before configuring FTP adapters you must configure an FTP Session Factory. You can configure the FTP Session Factory with a regular bean definition where the implementation class is org.springframework.integration.ftp.session.DefaultFtpSessionFactory: Below is a basic configuration:

<bean id="ftpClientFactory" 
	class="org.springframework.integration.ftp.session.DefaultFtpSessionFactory">
		<property name="host" value="localhost"/>
		<property name="port" value="22"/>
		<property name="username" value="kermit"/>
		<property name="password" value="frog"/>
		<property name="clientMode" value="0"/>
		<property name="fileType" value="2"/>
		<property name="bufferSize" value="100000"/>
</bean>

For FTPS connections all you need to do is use org.springframework.integration.ftp.session.DefaultFtpsSessionFactory instead. Below is the complete configuration sample:

<bean id="ftpClientFactory" 
	class="org.springframework.integration.ftp.client.DefaultFtpsClientFactory">
		<property name="host" value="localhost"/>
		<property name="port" value="22"/>
		<property name="username" value="oleg"/>
		<property name="password" value="password"/>
		<property name="clientMode" value="1"/>
		<property name="fileType" value="2"/>
		<property name="useClientMode" value="true"/>
		<property name="cipherSuites" value="a,b.c"/>
		<property name="keyManager" ref="keyManager"/>
		<property name="protocol" value="SSL"/>
		<property name="trustManager" ref="trustManager"/>
		<property name="prot" value="P"/>
		<property name="needClientAuth" value="true"/>
		<property name="authValue" value="oleg"/>
		<property name="sessionCreation" value="true"/>
		<property name="protocols" value="SSL, TLS"/>
		<property name="implicit" value="true"/>
</bean>

Every time an adapter requests a session object from its SessionFactory the session is returned from a session pool maintained by a caching wrapper around the factory. A Session in the session pool might go stale (if it has been disconnected by the server due to inactivity) so the SessionFactory will perform validation to make sure that it never returns a stale session to the adapter. If a stale session was encountered, it will be removed from the pool, and a new one will be created.

[Note]Note
If you experience connectivity problems and would like to trace Session creation as well as see which Sessions are polled you may enable it by setting the logger to TRACE level (e.g., log4j.category.org.springframework.integration.file=TRACE)

Now all you need to do is inject these session factories into your adapters. Obviously the protocol (FTP or FTPS) that an adapter will use depends on the type of session factory that has been injected into the adapter.

[Note]Note
A more practical way to provide values for FTP/FTPS Session Factories is by using Spring's property placeholder support (See: http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-factory-placeholderconfigurer).

Advanced Configuration

DefaultFtpSessionFactory provides an abstraction over the underlying client API which, in the current release of Spring Integration, is Apache Commons Net. This spares you from the low level configuration details of the org.apache.commons.net.ftp.FTPClient. However there are times when access to lower level FTPClient details is necessary to achieve more advanced configuration (e.g., setting data timeout, default timeout etc.). For that purpose, AbstractFtpSessionFactory (the base class for all FTP Session Factories) exposes hooks, in the form of the two post-processing methods below.

/**
	 * Will handle additional initialization after client.connect() method was invoked, 
	 * but before any action on the client has been taken 
	 */
	protected void postProcessClientAfterConnect(T t) throws IOException {
		// NOOP
	}
	/**
	 * Will handle additional initialization before client.connect() method was invoked. 
	 */
	protected void postProcessClientBeforeConnect(T client) throws IOException {
		// NOOP
	}

As you can see, there is no default implementation for these two methods. However, by extending DefaultFtpSessionFactory you can override these methods to provide more advanced configuration of the FTPClient. For example:

public class AdvancedFtpSessionFactory extends DefaultFtpSessionFactory {

  protected void postProcessClientBeforeConnect(FTPClient ftpClient) throws IOException {
     ftpClient.setDataTimeout(5000);
     ftpClient.setDefaultTimeout(5000);
  }
}

13.3 FTP Inbound Channel Adapter

The FTP Inbound Channel Adapter is a special listener that will connect to the FTP server and will listen for the remote directory events (e.g., new file created) at which point it will initiate a file transfer.

<int-ftp:inbound-channel-adapter id="ftpInbound"
				channel="ftpChannel" 
				session-factory="ftpSessionFactory"
				charset="UTF-8"
				auto-create-local-directory="true"
				delete-remote-files="true"
				filename-pattern="*.txt"
				remote-directory="some/remote/path"
				remote-file-separator="/"
				local-filename-generator-expression="#this.toUpperCase() + '.a'"
				local-directory=".">
			<int:poller fixed-rate="1000"/>
</int-ftp:inbound-channel-adapter>

As you can see from the configuration above you can configure an FTP Inbound Channel Adapter via the inbound-channel-adapter element while also providing values for various attributes such as local-directory, filename-pattern (which is based on simple pattern matching, not regular expressions), and of course the reference to a session-factory.

By default the transferred file will carry the same name as the original file. If you want to override this behavior you can set the local-filename-generator-expression attribute which allows you to provide a SpEL Expression to generate the name of the local file. Unlike outbound gateways and adapters where the root object of the SpEL Evaluation Context is a Message, this inbound adapter does not yet have the Message at the time of evaluation since that's what it ultimately generates with the transferred file as its payload. So, the root object of the SpEL Evaluation Context is the original name of the remote file (String).

Sometimes file filtering based on the simple pattern specified via filename-pattern attribute might not be sufficient. If this is the case, you can use the filename-regex attribute to specify a Regular Expression (e.g. filename-regex=".*\.test$"). And of course if you need complete control you can use filter attribute and provide a reference to any custom implementation of the org.springframework.integration.file.filters.FileListFilter, a strategy interface for filtering a list of files.

[Note]Note
As of Spring Integration 2.0.2, we have added a 'remote-file-separator' attribute. That allows you to configure a file separator character to use if the default '/' is not applicable for your particular environment.

Please refer to the schema for more details on these attributes.

It is also important to understand that the FTP Inbound Channel Adapter is a Polling Consumer and therefore you must configure a poller (either via a global default or a local sub-element). Once a file has been transferred, a Message with a java.io.File as its payload will be generated and sent to the channel identified by the channel attribute.

More on File Filtering and Large Files

Sometimes the file that just appeared in the monitored (remote) directory is not complete. Typically such a file will be written with temporary extension (e.g., foo.txt.writing) and then renamed after the writing process finished. As a user in most cases you are only interested in files that are complete and would like to filter only files that are complete. To handle these scenarios you can use the filtering support provided by the filename-pattern, filename-regex and filter attributes. Here is an example that uses a custom Filter implementation.

<int-ftp:inbound-channel-adapter 
			channel="ftpChannel" 
			session-factory="ftpSessionFactory"
			filter="customFilter"
			local-directory="file:/my_transfers">
			remote-directory="some/remote/path"
	<int:poller fixed-rate="1000"/>
</int-ftp:inbound-channel-adapter>
	
<bean id="customFilter" class="org.example.CustomFilter"/>

Poller configuration notes for the inbound FTP adapter

The job of the inbound FTP adapter consists of two tasks: 1) Communicate with a remote server in order to transfer files from a remote directory to a local directory. 2) For each transferred file, generate a Message with that file as a payload and send it to the channel identified by the 'channel' attribute. That is why they are called 'channel-adapters' rather than just 'adapters'. The main job of such an adapter is to generate a Message to be sent to a Message Channel. Essentially, the second task mentioned above takes precedence in such a way that *IF* your local directory already has one or more files it will first generate Messages from those, and *ONLY* when all local files have been processed, will it initiate the remote communication to retrieve more files.

Also, when configuring a trigger on the poller you should pay close attention to the max-messages-per-poll attribute. Its default value is 1 for all SourcePollingChannelAdapter instances (including FTP). This means that as soon as one file is processed, it will wait for the next execution time as determined by your trigger configuration. If you happened to have one or more files sitting in the local-directory, it would process those files before it would initiate communication with the remote FTP server. And, if the max-messages-per-poll were set to 1 (default), then it would be processing only one file at a time with intervals as defined by your trigger, essentially working as one-poll = one-file.

For typical file-transfer use cases, you most likely want the opposite behavior: to process all the files you can for each poll and only then wait for the next poll. If that is the case, set max-messages-per-poll to -1. Then, on each poll, the adapter will attempt to generate as many Messages as it possibly can. In other words, it will process everything in the local directory, and then it will connect to the remote directory to transfer everything that is available there to be processed locally. Only then is the poll operation considered complete, and the poller will wait for the next execution time.

You can alternatively set the 'max-messages-per-poll' value to a positive value indicating the upward limit of Messages to be created from files with each poll. For example, a value of 10 means that on each poll it will attempt to process no more than 10 files.

13.4 FTP Outbound Channel Adapter

The FTP Outbound Channel Adapter relies upon a MessageHandler implementation that will connect to the FTP server and initiate an FTP transfer for every file it receives in the payload of incoming Messages. It also supports several representations of the File so you are not limited only to java.io.File typed payloads. The FTP Outbound Channel Adapter supports the following payloads: 1) java.io.File - the actual file object; 2) byte[] - a byte array that represents the file contents; and 3) java.lang.String - text that represents the file contents.

<int-ftp:outbound-channel-adapter id="ftpOutbound"
				channel="ftpChannel" 
				session-factory="ftpSessionFactory"
				charset="UTF-8"
				remote-file-separator="/"
				auto-create-directory="true"
				remote-directory-expression="headers.['remote_dir']"
				temporary-remote-directory-expression="headers.['temp_remote_dir']"
				filename-generator="fileNameGenerator"/>

As you can see from the configuration above you can configure an FTP Outbound Channel Adapter via the outbound-channel-adapter element while also providing values for various attributes such as filename-generator (an implementation of the org.springframework.integration.file.FileNameGenerator strategy interface), a reference to a session-factory, as well as other attributes. You can also see some examples of *expression attributes which allow you to use SpEL to configure things like remote-directory-expression, temporary-remote-directory-expression and remote-filename-generator-expression (a SpEL alternative to filename-generator shown above). As with any component that allows the usage of SpEL, access to Payload and Message Headers is available via 'payload' and 'headers' variables. Please refer to the schema for more details on the available attributes.

[Note]Note
By default Spring Integration will use org.springframework.integration.file.DefaultFileNameGenerator if none is specified. DefaultFileNameGenerator will determine the file name based on the value of the file_name header (if it exists) in the MessageHeaders, or if the payload of the Message is already a java.io.File, then it will use the original name of that file.

[Important]Important
Defining certain values (e.g., remote-directory) might be platform/ftp server dependent. For example as it was reported on this forum http://forum.springsource.org/showthread.php?p=333478&posted=1#post333478 on some platforms you must add slash to the end of the directory definition (e.g., remote-directory="/foo/bar/" instead of remote-directory="/foo/bar")

Avoiding Partially Written Files

One of the common problems, when dealing with file transfers, is the possibility of processing a partial file - a file might appear in the file system before its transfer is actually complete.

To deal with this issue, Spring Integration FTP adapters use a very common algorithm where files are transferred under a temporary name and then renamed once they are fully transferred.

By default, every file that is in the process of being transferred will appear in the file system with an additional suffix which, by default, is .writing; this can be changed using the temporary-file-suffix attribute.

However, there may be situations where you don't want to use this technique (for example, if the server does not permit renaming files). For situations like this, you can disable this feature by setting use-temporary-file-name to false (default is true). When this attribute is false, the file is written with its final name and the consuming application will need some other mechanism to detect that the file is completely uploaded before accessing it.

13.5 FTP Outbound Gateway

The FTP Outbound Gateway provides a limited set of commands to interact with a remote FTP/FTPS server.

Commands supported are:

  • ls (list files)
  • get (retrieve file)
  • mget (retrieve file(s))
  • rm (remove file(s))

ls

ls lists remote file(s) and supports the following options:

  • -1 - just retrieve a list of filenames, default is to retrieve a list of FileInfo objects.
  • -a - include all files (including those starting with '.')
  • -f - do not sort the list
  • -dirs - include directories (excluded by default)
  • -links - include symbolic links (excluded by default)

In addition, filename filtering is provided, in the same manner as the inbound-channel-adapter.

The message payload resulting from an ls operation is a list of file names, or a list of FileInfo objects. These objects provide information such as modified time, permissions etc.

The remote directory that the ls command acted on is provided in the file_remoteDirectory header.

get

get retrieves a remote file and supports the following option:

  • -P - preserve the timestamp of the remote file

The message payload resulting from a get operation is a File object representing the retrieved file.

The remote directory is provided in the file_remoteDirectory header, and the filename is provided in the file_remoteFile header.

mget

mget retrieves multiple remote files based on a pattern and supports the following option:

  • -x - Throw an exception if no files match the pattern (otherwise an empty list is returned)

The message payload resulting from an mget operation is a List<File> object - a List of File objects, each representing a retrieved file.

The remote directory is provided in the file_remoteDirectory header, and the pattern for the filenames is provided in the file_remoteFile header.

rm

The rm command has no options.

The message payload resulting from an rm operation is Boolean.TRUE if the remove was successful, Boolean.FALSE otherwise. The remote directory is provided in the file_remoteDirectory header, and the filename is provided in the file_remoteFile header.

In each case, the PATH that these commands act on is provided by the 'expression' property of the gateway. For the mget command, the expression might evaluate to '*', meaning retrieve all files, or 'somedirectory/*' etc.

Here is an example of a gateway configured for an ls command...

<int-ftp:outbound-gateway id="gateway1"
		session-factory="ftpSessionFactory"
		request-channel="inbound1"
		command="ls"
		command-options="-1"
		expression="payload"
		reply-channel="toSplitter"/>

The payload of the message sent to the toSplitter channel is a list of String objects containing the filename of each file. If the command-options was omitted, it would be a list of FileInfo objects. Options are provided space-delimited, e.g. command-options="-1 -dirs -links".

13.6 FTP Session Caching

As of version 2.1 we've exposed more flexibility with regard to session management for remote file adapters (e.g., FTP, SFTP etc). In previous versions the sessions were cached automatically by default. We did expose a cache-sessions attribute for disabling the auto caching, but that solution did not provide a way to configure other session caching attributes. For example, one of the requested features was to support a limit on the number of sessions created since a remote server may impose a limit on the number of client connections. To support that requirement and other configuration options, we decided to promote explicit definition of the CachingSessionFactory instance. That provides the sessionCacheSize and sessionWaitTimeout properties. As its name suggests, the sessionCacheSize property controls how many active sessions this adapter will maintain in its cache (the DEFAULT is unbounded). If the sessionCacheSize threshold has been reached, any attempt to acquire another session will block until either one of the cached sessions becomes available or until the wait time for a Session expires (the DEFAULT wait time is Integer.MAX_VALUE). The sessionWaitTimeout property enables configuration of that value.

If you want your Sessions to be cached, simply configure your default Session Factory as described above and then wrap it in an instance of CachingSessionFactory where you may provide those additional properties.

<bean id="ftpSessionFactory" class="org.springframework.integration.ftp.session.DefaultFtpSessionFactory">
		<property name="host" value="localhost"/>
	</bean>
	
	<bean id="cachingSessionFactory" class="org.springframework.integration.file.remote.session.CachingSessionFactory">
		<constructor-arg ref="ftpSessionFactory"/>
		<constructor-arg value="10"/>
		<property name="sessionWaitTimeout" value="1000"/>
	</bean>

In the above example you see a CachingSessionFactory created with the sessionCacheSize set to 10 and the sessionWaitTimeout set to 1 second (its value is in millliseconds).

14. GemFire Support

Spring Integration provides support for VMWare vFabric GemFire

14.1 Introduction

VMWare vFabric GemFire (GemFire) is a distributed data management platform providing a key-value data grid along with advanced distributed system features such as event processing, continuous querying, and remote function execution. This guide assumes some familiarity with GemFire and its API.

Spring integration provides support for GemFire by providing inbound adapters for entry and continuous query events, an outbound adapter to write entries to the cache, and MessageStore and MessageGroupStore implementations. Spring integration leverages the Spring Gemfire project, providing a thin wrapper over its components.

To configure the 'int-gfe' namespace, include the following elements within the headers of your XML configuration file:

xmlns:int-gfe="http://www.springframework.org/schema/integration/gemfire"
xsi:schemaLocation="http://www.springframework.org/schema/integration/gemfire 
	http://www.springframework.org/schema/integration/gemfire/spring-integration-gemfire.xsd"

14.2 Inbound Channel Adapter

The inbound-channel-adapter produces messages on a channel triggered by a GemFire EntryEvent. GemFire generates events whenever an entry is CREATED, UPDATED, DESTROYED, or INVALIDATED in the associated region. The inbound channel adapter allows you to filter on a subset of these events. For example, you may want to only produce messages in response to an entry being CREATED. In addition, the inbound channel adapter can evaluate a SpEL expression if, for example, you want your message payload to contain an event property such as the new entry value.

  	<gfe:cache/>
	<gfe:replicated-region id="region"/>
	<int-gfe:inbound-channel-adapter id="inputChannel" region="region" 
		cache-events="CREATED" expression="newValue"/>
	

In the above configuration, we are creating a GemFire Cache and Region using Spring GemFire's 'gfe' namespace. The inbound-channel-adapter requires a reference to the GemFire region for which the adapter will be listening for events. Optional attributes include cache-events which can contain a comma separated list of event types for which a message will be produced on the input channel. By default CREATED and UPDATED are enabled. Note that this adapter conforms to Spring integration conventions. If no channel attribute is provided, the channel will be created from the id attribute. This adapter also supports an error-channel. If expression is not provided the message payload will be a GemFire EntryEvent

14.3 Continuous Query Inbound Channel Adapter

The cq-inbound-channel-adapter produces messages a channel triggered by a GemFire continuous query or CqEvent event. Spring GemFire introduced continuous query support in release 1.1, including a ContinuousQueryListenerContainer which provides a nice abstraction over the GemFire native API. This adapter requires a reference to a ContinuousQueryListenerContainer, and creates a listener for a given query and executes the query. The continuous query acts as an event source that will fire whenever its result set changes state.

[Note]Note
GemFire queries are written in OQL and are scoped to the entire cache (not just one region). Additionally, continuous queries require a remote (i.e., running in a separate process or remote host) cache server. Please consult the GemFire documentation for more information on implementing continuous queries.

<gfe:client-cache id="client-cache" pool-name="client-pool"/>
	
	<gfe:pool id="client-pool" subscription-enabled="true" >
		<!--configure server or locator here required to address the cache server -->
	</gfe:pool>
	
	<gfe:client-region id="test" cache-ref="client-cache" pool-name="client-pool"/>
	
	<gfe:cq-listener-container id="queryListenerContainer" cache="client-cache" 
		pool-name="client-pool"/>
	 
	<int-gfe:cq-inbound-channel-adapter id="inputChannel" 
		cq-listener-container="queryListenerContainer" 
		query="select * from /test"/>
	
	

In the above configuration, we are creating a GemFire client cache (recall a remote cache server is required for this implementation and its address is configured as a sub-element of the pool), a client region and a ContinuousQueryListenerContainer using Spring GemFire. The continuous query inbound channel adapter requires a cq-listener-container attribute which contains a reference to the ContinuousQueryListenerContainer. Optionally, it accepts an expression attribute which uses SpEL to transform the CqEvent or extract an individual property as needed. The cq-inbound-channel-adapter provides a query-events attribute, containing a comma separated list of event types for which a message will be produced on the input channel. Available event types are CREATED, UPDATED, DESTROYED, REGION_DESTROYED, REGION_INVALIDATED. CREATED and UPDATED are enabled by default. Additional optional attributes include, query-name which provides an optional query name, and expression which works as described in the above section, and durable - a boolean value indicating if the query is durable (false by default). Note that this adapter conforms to Spring integration conventions. If no channel attribute is provided, the channel will be created from the id attribute. This adapter also supports an error-channel

14.4 Outbound Channel Adapter

The outbound-channel-adapter writes cache entries mapped from the message payload. In its simplest form, it expects a payload of type java.util.Map and puts the map entries into its configured region.

<int-gfe:outbound-channel-adapter id="cacheChannel" region="region"/>

Given the above configuration, an exception will be thrown if the payload is not a Map. Additionally, the outbound channel adapter can be configured to create a map of cache entries using SpEL of course.

<int-gfe:outbound-channel-adapter id="cacheChannel" region="region">
<int-gfe:cache-entries>
        <entry key="payload.toUpperCase()" value="payload.toLowerCase()"/>
        <entry key="'foo'" value="'bar'"/>
</int-gfe:cache-entries>
</int-gfe:outbound-channel-adapter>

In the above configuration, the inner element cache-entries is semantically equivalent to Spring 'map' element. The adapter interprets the key and value attributes as SpEL expressions with the message as the evaluation context. Note that this contain arbitrary cache entries (not only those derived from the message) and that literal values must be enclosed in single quotes. In the above example, if the message sent to cacheChannel has a String payload with a value "Hello", two entries [HELLO:hello, foo:bar] will be written (created or updated) in the cache region. This adapter also supports the order attribute which may be useful if it is bound to a PublishSubscribeChannel.

14.5 Gemfire Message Store

As described in EIP, a Message Store allows you to persist Messages. This can be very useful when dealing with components that have a capability to buffer messages (QueueChannel, Aggregator, Resequencer, etc.) if reliability is a concern. In Spring Integration, the MessageStore strategy also provides the foundation for the ClaimCheck pattern, which is described in EIP as well.

Spring Integration's Gemfire module provides the GemfireMessageStore which is an implementation of both the the MessageStore strategy (mainly used by the QueueChannel and ClaimCheck patterns) and the MessageGroupStore strategy (mainly used by the Aggregator and Resequencer patterns).

<bean id="gemfireMessageStore" class="org.springframework.integration.gemfire.store.GemfireMessageStore">
        <constructor-arg ref="myCache"/>
</bean>
	
<bean id="myCache" class="org.springframework.data.gemfire.CacheFactoryBean"/>

<int:channel id="somePersistentQueueChannel">
    <int:queue message-store="gemfireMessageStore"/>
<int:channel>

<int:aggregator input-channel="inputChannel" output-channel="outputChannel"
         message-store="gemfireMessageStore"/>

Above is a sample GemfireMessageStore configuration that shows its usage by a QueueChannel and an Aggregator. As you can see it is a normal Spring bean configuration. The simplest configuration requires a reference to a GemFireCache (created by CacheFactoryBean) as a constructor argument. If the cache is standalone, i.e., embedded in the same JVM, the MessageStore will create a message store region named "messageStoreRegion". If your application requires customization of the messageStore region, for example, multiple Gemfire message stores each with its own region, you can configure a region for each message store instance and use the Region as the constructor argument:

<bean id="gemfireMessageStore" class="org.springframework.integration.gemfire.store.GemfireMessageStore">
        <constructor-arg ref="myRegion"/>
</bean>

<gfe:cache/>

<gfe:replicated-region id="myRegion"/>

In the above examle, the cache and region are configured using the spring-gemfire namespace (not to be confused with the spring-integration-gemfire namespace). Often it is desirable for the message store to be maintained in one or more remote cache servers in a client-server configuration (See the GemFire product documentation for more details). In this case, you configure a client cache, client region, and client pool and inject the region into the MessageStore. Here is an example:

<bean id="gemfireMessageStore"
      class="org.springframework.integration.gemfire.store.GemfireMessageStore">
        <constructor-arg ref="myRegion"/>
</bean>

<gfe:client-cache/>

<gfe:client-region id="myRegion" shortcut="PROXY" pool-name="messageStorePool"/>

<gfe:pool id="messageStorePool">
        <gfe:server host="localhost" port="40404" />
</gfe:pool>

Note the pool element is configured with the address of a cache server (a locator may be substituted here). The region is configured as a 'PROXY' so that no data will be stored locally. The region's id corresponds to a region with the same name configured in the cache server.

15. HTTP Support

15.1 Introduction

The HTTP support allows for the execution of HTTP requests and the processing of inbound HTTP requests. Because interaction over HTTP is always synchronous, even if all that is returned is a 200 status code, the HTTP support consists of two gateway implementations: HttpInboundEndpoint and HttpRequestExecutingMessageHandler.

15.2 Http Inbound Gateway

To receive messages over HTTP, you need to use an HTTP Inbound Channel Adapter or Gateway. To support the HTTP Inbound Adapters, they need to be deployed within a servlet container such as Apache Tomcat or Jetty. The easiest way to do this is to use Spring's HttpRequestHandlerServlet, by providing the following servlet definition in the web.xml file:

<servlet>
    <servlet-name>inboundGateway</servlet-name>
    <servlet-class>o.s.web.context.support.HttpRequestHandlerServlet</servlet-class>
</servlet>

Notice that the servlet name matches the bean name. For more information on using the HttpRequestHandlerServlet, see chapter "Remoting and web services using Spring", which is part of the Spring Framework Reference documentation.

If you are running within a Spring MVC application, then the aforementioned explicit servlet definition is not necessary. In that case, the bean name for your gateway can be matched against the URL path just like a Spring MVC Controller bean. For more information, please see the chapter "Web MVC framework", which is part of the Spring Framework Reference documentation.

[Tip]Tip
For a sample application and the corresponding configuration, please see the Spring Integration Samples repository. It contains the Http Sample application demonstrating Spring Integration's HTTP support.

Below is an example bean definition for a simple HTTP inbound endpoint.

<bean id="httpInbound"
  class="org.springframework.integration.http.inbound.HttpRequestHandlingMessagingGateway">
  <property name="requestChannel" ref="httpRequestChannel" />
  <property name="replyChannel" ref="httpReplyChannel" />
</bean>

The HttpRequestHandlingMessagingGateway accepts a list of HttpMessageConverter instances or else relies on a default list. The converters allow customization of the mapping from HttpServletRequest to Message. The default converters encapsulate simple strategies, which for example will create a String message for a POST request where the content type starts with "text", see the Javadoc for full details.

Starting with this release MultiPart File support was implemented. If the request has been wrapped as a MultipartHttpServletRequest, when using the default converters, that request will be converted to a Message payload that is a MultiValueMap containing values that may be byte arrays, Strings, or instances of Spring's MultipartFile depending on the content type of the individual parts.

[Note]Note
The HTTP inbound Endpoint will locate a MultipartResolver in the context if one exists with the bean name "multipartResolver" (the same name expected by Spring's DispatcherServlet). If it does in fact locate that bean, then the support for MultipartFiles will be enabled on the inbound request mapper. Otherwise, it will fail when trying to map a multipart-file request to a Spring Integration Message. For more on Spring's support for MultipartResolvers, refer to the Spring Reference Manual.

In sending a response to the client there are a number of ways to customize the behavior of the gateway. By default the gateway will simply acknowledge that the request was received by sending a 200 status code back. It is possible to customize this response by providing a 'viewName' to be resolved by the Spring MVC ViewResolver. In the case that the gateway should expect a reply to the Message then setting the expectReply flag (constructor argument) will cause the gateway to wait for a reply Message before creating an HTTP response. Below is an example of a gateway configured to serve as a Spring MVC Controller with a view name. Because of the constructor arg value of TRUE, it wait for a reply. This also shows how to customize the HTTP methods accepted by the gateway, which are POST and GET by default.

<bean id="httpInbound"
  class="org.springframework.integration.http.inbound.HttpRequestHandlingController">
  <constructor-arg value="true" /> <!-- indicates that a reply is expected -->
  <property name="requestChannel" ref="httpRequestChannel" />
  <property name="replyChannel" ref="httpReplyChannel" />
  <property name="viewName" value="jsonView" />
  <property name="supportedMethodNames" >
    <list>
      <value>GET</value>
      <value>DELETE</value>
    </list>
  </property>
</bean>

The reply message will be available in the Model map. The key that is used for that map entry by default is 'reply', but this can be overridden by setting the 'replyKey' property on the endpoint's configuration.

15.3 Http Outbound Gateway

To configure the HttpRequestExecutingMessageHandler write a bean definition like this:

<bean id="httpOutbound"
  class="org.springframework.integration.http.outbound.HttpRequestExecutingMessageHandler">
  <constructor-arg value="http://localhost:8080/example" />
  <property name="outputChannel" ref="responseChannel" />
</bean>

This bean definition will execute HTTP requests by delegating to a RestTemplate. That template in turn delegates to a list of HttpMessageConverters to generate the HTTP request body from the Message payload. You can configure those converters as well as the ClientHttpRequestFactory instance to use:

<bean id="httpOutbound"
  class="org.springframework.integration.http.outbound.HttpRequestExecutingMessageHandler">
  <constructor-arg value="http://localhost:8080/example" />
  <property name="outputChannel" ref="responseChannel" />
  <property name="messageConverters" ref="messageConverterList" />
  <property name="requestFactory" ref="customRequestFactory" />
</bean>

By default the HTTP request will be generated using an instance of SimpleClientHttpRequestFactory which uses the JDK HttpURLConnection. Use of the Apache Commons HTTP Client is also supported through the provided CommonsClientHttpRequestFactory which can be injected as shown above.

[Note]Note
In the case of the Outbound Gateway, the reply message produced by the gateway will contain all Message Headers present in the request message.

Cookies

Basic cookie support is provided by the transfer-cookies attribute on the outbound gateway. When set to true (default is false), a Set-Cookie header received from the server in a response will be converted to Cookie in the reply message. This header will then be used on subsequent sends. This enables simple stateful interactions, such as...

...->logonGateway->...->doWorkGateway->...->logoffGateway->...

If transfer-cookies is false, any Set-Cookie header received will remain as Set-Cookie in the reply message, and will be dropped on subsequent sends.

15.4 HTTP Namespace Support

Spring Integration provides an http namespace and the corresponding schema definition. To include it in your configuration, simply provide the following namespace declaration in your application context configuration file:

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

Inbound

The XML Namespace provides two components for handling HTTP Inbound requests. In order to process requests without returning a dedicated response, use the inbound-channel-adapter:

<int-http:inbound-channel-adapter id="httpChannelAdapter" channel="requests"
    supported-methods="PUT, DELETE"/>

To process requests that do expect a response, use an inbound-gateway:

 <int-http:inbound-gateway id="inboundGateway"
    request-channel="requests"
    reply-channel="responses"/>
[Important]Important

Beginning with Spring Integration 2.1 the HTTP Inbound Gateway and the HTTP Inbound Channel Adapter should use the path attribute instead of the name attribute for specifying the request path. The name attribute for those 2 components has been deprecated.

If you simply want to identify component itself within your application context, please use the id attribute.

Defining the UriPathHandlerMapping

In order to use the HTTP Inbound Gateway or the HTTP Inbound Channel Adapter you must define a UriPathHandlerMapping. This particular implementation of the HandlerMapping matches against the value of the path attribute.

<bean class="org.springframework.integration.http.inbound.UriPathHandlerMapping"/>

For more information regarding Handler Mappings, please see:

URI Template Variables and Expressions

By Using the path attribute in conjunction with the payload-expression attribute as well as the header sub-element, you have a high degree of flexiblity for mapping inbound request data.

In the following example configuration, an Inbound Channel Adapter is configured to accept requests using the following URI: /first-name/{firstName}/last-name/{lastName}

Using the payload-expression attribute, the URI template variable {firstName} is mapped to be the Message payload, while the {lastName} URI template variable will map to the lname Message header.

<int-http:inbound-channel-adapter id="inboundAdapterWithExpressions"
                                  path="/first-name/{firstName}/last-name/{lastName}"
                                  channel="requests"
                                  payload-expression="#pathVariables.firstName">
        <int-http:header name="lname" expression="#pathVariables.lastName"/>
</int-http:inbound-channel-adapter>

For more information about URI template variables, please see the Spring Reference Manual:

Outbound

To configure the outbound gateway you can use the namespace support as well. The following code snippet shows the different configuration options for an outbound Http gateway. Most importantly, notice that the 'http-method' and 'expected-response-type' are provided. Those are two of the most commonly configured values. The default http-method is POST, and the default response type is null. With a null response type, the payload of the reply Message would contain the ResponseEntity as long as it's http status is a success (non-successful status codes will throw Exceptions). If you are expecting a different type, such as a String, then provide that fully-qualified class name as shown below.

<int-http:outbound-gateway id="example"
    request-channel="requests"
    url="http://localhost/test"
    http-method="POST"
    extract-request-payload="false"
    expected-response-type="java.lang.String"
    charset="UTF-8"
    request-factory="requestFactory"
    reply-timeout="1234"
    reply-channel="replies"/>
[Important]Important
Beginning with Spring Integration 2.1 the request-timeout attribute of the HTTP Outbound Gateway was renamed to reply-timeout to better reflect the intent.

Beginning with Spring Integration 2.2 you can also determine the HTTP Method dynamically using SpEL and the http-method-expression attribute. Note that this attribute is obviously murually exclusive with http-method You can also use expected-response-type-expression attribute instead of expected-response-type and provide any valid SpEL expression that determines the type of the response.

<int-http:outbound-gateway id="example"
    request-channel="requests"
    url="http://localhost/test"
    http-method-expression="headers.httpMethod"
    extract-request-payload="false"
    expected-response-type-expression="payload"
    charset="UTF-8"
    request-factory="requestFactory"
    reply-timeout="1234"
    reply-channel="replies"/>

If your outbound adapter is to be used in a unidirectional way, then you can use an outbound-channel-adapter instead. This means that a successful response will simply execute without sending any Messages to a reply channel. In the case of any non-successful response status code, it will throw an exception. The configuration looks very similar to the gateway:

<int-http:outbound-channel-adapter id="example"
      url="http://localhost/example"
      http-method="GET"
      channel="requests"
      charset="UTF-8"
      extract-payload="false"
      expected-response-type="java.lang.String"
      request-factory="someRequestFactory"
      order="3"
      auto-startup="false"/>

[Note]Note

To specify the URL; you can use either the 'url' attribute or the 'url-expression' attribute. The 'url' is a simple string (with placedholders for URI variables, as described below); the 'url-expression' is a SpEL expression, with the Message as the root object, enabling dynamic urls. The url resulting from the expression evaluation can still have placeholders for URI variables.

In previous releases, some users used the place holders to replace the entire URL with a URI variable. Changes in Spring 3.1 can cause some issues with escaped characters, such as '?'. For this reason, it is recommended that if you wish to generate the URL entirely at runtime, you use the 'url-expression' attribute.

Mapping URI variables

If your URL contains URI variables, you can map them using the uri-variable sub-element. This sub-element is available for the Http Outbound Gateway and the Http Outbound Channel Adapter.

<int-http:outbound-gateway id="trafficGateway"
    url="http://local.yahooapis.com/trafficData?appid=YdnDemo&amp;zip={zipCode}"
		              request-channel="trafficChannel"
		              http-method="GET"
		              expected-response-type="java.lang.String">
		<int-http:uri-variable name="zipCode" expression="payload.getZip()"/>
</int-http:outbound-gateway>

The uri-variable sub-element defines two attributes: name and expression. The name attribute identifies the name of the URI variable, while the expression attribute is used to set the actual value. Using the expression attribute, you can leverage the full power of the Spring Expression Language (SpEL) which gives you full dynamic access to the message payload and the message headers. For example, in the above configuration the getZip() method will be invoked on the payload object of the Message and the result of that method will be used as the value for the URI variable named 'zipCode'.

15.5 Timeout Handling

In the context of HTTP components, there are two timing areas that have to be considered.

  • Timeouts when interacting with Spring Integration Channels
  • Timeouts when interacting with a remote HTTP server

First, the components interact with Message Channels, for which timeouts can be specified. For example, an HTTP Inbound Gateway will forward messages received from connected HTTP Clients to a Message Channel (Request Timeout) and consequently the HTTP Inbound Gateway will receive a reply Message from the Reply Channel (Reply Timeout) that will be used to generate the HTTP Response. Please see the figure below for an illustration.

How timeout settings apply to an HTTP Inbound Gateway

For outbound endpoints, the second thing to consider is timing while interacting with the remote server.

How timeout settings apply to an HTTP Outbound Gateway

You may want to configure the HTTP related timeout behavior, when making active HTTP requests using the HTTP Oubound Gateway or the HTTP Outbound Channel Adapter. In those instances, these two components use Spring's RestTemplate support to execute HTTP requests.

In order to configure timeouts for the HTTP Oubound Gateway and the HTTP Outbound Channel Adapter, you can either reference a RestTemplate bean directly, using the rest-template attribute, or you can provide a reference to a ClientHttpRequestFactory bean using the request-factory attribute. Spring provides the following implementations of the ClientHttpRequestFactory interface:

SimpleClientHttpRequestFactory - Uses standard J2SE facilities for making HTTP Requests

HttpComponentsClientHttpRequestFactory - Uses Apache HttpComponents HttpClient (Since Spring 3.1)

ClientHttpRequestFactory - Uses Jakarta Commons HttpClient (Deprecated as of Spring 3.1)

If you don't explicitly configure the request-factory or rest-template attribute respectively, then a default RestTemplate which uses a SimpleClientHttpRequestFactory will be instantiated.

[Note]Note

With some JVM implementations, the handling of timeouts using the URLConnection class may not be consistent.

E.g. from the Java™ Platform, Standard Edition 6 API Specification on setConnectTimeout: Some non-standard implmentation of this method may ignore the specified timeout. To see the connect timeout set, please call getConnectTimeout().

Please test your timeouts if you have specific needs. Consider using the HttpComponentsClientHttpRequestFactory which, in turn, uses Apache HttpComponents HttpClient instead.

Here is an example of how to configure an HTTP Outbound Gateway using a SimpleClientHttpRequestFactory, configured with connect and read timeouts of 5 seconds respectively:

<int-http:outbound-gateway url="http://www.google.com/ig/api?weather={city}"
                           http-method="GET"
                           expected-response-type="java.lang.String"
                           request-factory="requestFactory"
                           request-channel="requestChannel"
                           reply-channel="replyChannel">
    <int-http:uri-variable name="city" expression="payload"/>
</int-http:outbound-gateway>

<bean id="requestFactory"
      class="org.springframework.http.client.SimpleClientHttpRequestFactory">
    <property name="connectTimeout" value="5000"/>
    <property name="readTimeout"    value="5000"/>
</bean>

HTTP Outbound Gateway

For the HTTP Outbound Gateway, the XML Schema defines only the reply-timeout. The reply-timeout maps to the sendTimeout property of the org.springframework.integration.http.outbound.HttpRequestExecutingMessageHandler class. More precisely, the property is set on the extended AbstractReplyProducingMessageHandler class, which ultimatelly sets the property on the MessagingTemplate.

The value of the sendTimeout property defaults to "-1" and will be applied to the connected MessageChannel. This means, that depending on the implementation, the Message Channel's send method may block indefinitely. Furthermore, the sendTimeout property is only used, when the actual MessageChannel implementation has a blocking send (such as 'full' bounded QueueChannel).

HTTP Inbound Gateway

For the HTTP Inbound Gateway, the XML Schema defines the request-timeout attribute, which will be used to set the requestTimeout property on the HttpRequestHandlingMessagingGateway class (on the extended MessagingGatewaySupport class). Secondly, the reply-timeout attribute exists and it maps to the replyTimeout property on the same class.

The default for both timeout properties is "1000ms". Ultimately, the request-timeout property will be used to set the sendTimeout on the used MessagingTemplate instance. The replyTimeout property on the other hand, will be used to set the receiveTimeout property on the used MessagingTemplate instance.

[Tip]Tip
In order to simulate connection timeouts, connect to a non-routable IP address, for example 10.255.255.10.

15.6 HTTP Proxy configuration

If you are behind a proxy and need to configure proxy settings for HTTP outbound adapters and/or gateways, you can apply one of two approaches. In most cases, you can rely on the standard Java System Properties that control the proxy settings. Otherwise, you can explicitly configure a Spring bean for the HTTP client request factory instance.

Standard Java Proxy configuration

There are 3 System Properties you can set to configure the proxy settings that will be used by the HTTP protocol handler:

  • http.proxyHost - the host name of the proxy server.

  • http.proxyPort - the port number, the default value being 80.

  • http.nonProxyHosts - a list of hosts that should be reached directly, bypassing the proxy. This is a list of patterns separated by '|'. The patterns may start or end with a '*' for wildcards. Any host matching one of these patterns will be reached through a direct connection instead of through a proxy.

And for HTTPS:

  • https.proxyHost - the host name of the proxy server.

  • https.proxyPort - the port number, the default value being 80.

For more information please refer to this document: http://download.oracle.com/javase/6/docs/technotes/guides/net/proxies.html

Spring's SimpleClientHttpRequestFactory

If for any reason, you need more explicit control over the proxy configuration, you can use Spring's SimpleClientHttpRequestFactory and configure its 'proxy' property as such:

<bean id="requestFactory"
    			class="org.springframework.http.client.SimpleClientHttpRequestFactory">
	<property name="proxy">
		<bean id="proxy" class="java.net.Proxy">
			<constructor-arg>
				<util:constant static-field="java.net.Proxy.Type.HTTP"/>
			</constructor-arg>
			<constructor-arg>
				<bean class="java.net.InetSocketAddress">
					<constructor-arg value="123.0.0.1"/>
					<constructor-arg value="8080"/>
				</bean>
			</constructor-arg>
		</bean>
	</property>
</bean>

15.7  HTTP Header Mappings

Spring Integration provides support for Http Header mapping for both HTTP Request and HTTP Responses.

By default all standard Http Headers as defined here http://en.wikipedia.org/wiki/List_of_HTTP_header_fields will be mapped from the message to HTTP request/response headers without further configuration. However if you do need further customization you may provide additional configuration via convenient namespace support. You can provide a comma-separated list of header names, and you can also include simple patterns with the '*' character acting as a wildcard. If you do provide such values, it will override the default behavior. Basically, it assumes you are in complete control at that point. However, if you do want to include all of the standard HTTP headers, you can use the shortcut patterns: HTTP_REQUEST_HEADERS and HTTP_RESPONSE_HEADERS. Here are some examples:

<int-http:outbound-gateway id="httpGateway"
			url="http://localhost/test2"
			mapped-request-headers="foo, bar"
			mapped-response-headers="X-*, HTTP_RESPONSE_HEADERS"
			channel="someChannel"/>

<int-http:outbound-channel-adapter id="httpAdapter"
			url="http://localhost/test2"
			mapped-request-headers="foo, bar, HTTP_REQUEST_HEADERS"
			channel="someChannel"/>

The adapters and gateways will use the DefaultHttpHeaderMapper which now provides two static factory methods for "inbound" and "outbound" adapters so that the proper direction can be applied (mapping HTTP requests/responses IN/OUT as appropriate).

If further customization is required you can also configure a DefaultHttpHeaderMapper independently and inject it into the adapter via the header-mapper attribute.

<int-http:outbound-gateway id="httpGateway"
			url="http://localhost/test2"
			header-mapper="headerMapper"
			channel="someChannel"/>

<bean id="headerMapper" class="org.springframework.integration.http.support.DefaultHttpHeaderMapper">
		<property name="inboundHeaderNames" value="foo*, *bar, baz"/>
		<property name="outboundHeaderNames" value="a*b, d"/>
</bean>

Of course, you can even implement the HeaderMapper strategy interface directly and provide a reference to that if you need to do something other than what the DefaultHttpHeaderMapper supports.

15.8 HTTP Samples

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

This example demonstrates how simple it is to send a Multipart HTTP request via Spring's RestTemplate and receive it with a Spring Integration HTTP Inbound Adapter. All we are doing is creating a MultiValueMap and populating it with multi-part data. The RestTemplate will take care of the rest (no pun intended) by converting it to a MultipartHttpServletRequest . This particular client will send a multipart HTTP Request which contains the name of the company as well as an image file with the company logo.

RestTemplate template = new RestTemplate();
String uri = "http://localhost:8080/multipart-http/inboundAdapter.htm";
Resource s2logo = 
   new ClassPathResource("org/springframework/samples/multipart/spring09_logo.png");
MultiValueMap map = new LinkedMultiValueMap();
map.add("company""SpringSource");
map.add("company-logo", s2logo);
HttpHeaders headers = new HttpHeaders();
headers.setContentType(new MediaType("multipart""form-data"));
HttpEntity request = new HttpEntity(map, headers);
ResponseEntity<?> httpResponse = template.exchange(uri, HttpMethod.POST, request, null);

That is all for the client.

On the server side we have the following configuration:

<int-http:inbound-channel-adapter id="httpInboundAdapter"
  channel="receiveChannel"
  name="/inboundAdapter.htm"
  supported-methods="GET, POST" />

<int:channel id="receiveChannel"/>

<int:service-activator input-channel="receiveChannel">
  <bean class="org.springframework.integration.samples.multipart.MultipartReceiver"/>
</int:service-activator>

<bean id="multipartResolver"
    class="org.springframework.web.multipart.commons.CommonsMultipartResolver"/>

The 'httpInboundAdapter' will receive the request, convert it to a Message with a payload that is a LinkedMultiValueMap. We then are parsing that in the 'multipartReceiver' service-activator;

public void receive(LinkedMultiValueMap<String, Object> multipartRequest){
  System.out.println("### Successfully received multipart request ###");
  for (String elementName : multipartRequest.keySet()) {
    if (elementName.equals("company")){
      System.out.println("\t" + elementName + " - " +
        ((String[]) multipartRequest.getFirst("company"))[0]);
    }
    else if (elementName.equals("company-logo")){
      System.out.println("\t" + elementName + " - as UploadedMultipartFile: " +
        ((UploadedMultipartFile) multipartRequest.getFirst("company-logo")).
        											getOriginalFilename());
    }
  }
}

You should see the following output:

### Successfully received multipart request ###
   company - SpringSource
   company-logo - as UploadedMultipartFile: spring09_logo.png

16. TCP and UDP Support

Spring Integration provides Channel Adapters for receiving and sending messages over internet protocols. Both UDP (User Datagram Protocol) and TCP (Transmission Control Protocol) adapters are provided. Each adapter provides for one-way communication over the underlying protocol. In addition, simple inbound and outbound tcp gateways are provided. These are used when two-way communication is needed.

16.1 Introduction

Two flavors each of UDP inbound and outbound channel adapters are provided UnicastSendingMessageHandler sends a datagram packet to a single destination. UnicastReceivingChannelAdapter receives incoming datagram packets. MulticastSendingMessageHandler sends (broadcasts) datagram packets to a multicast address. MulticastReceivingChannelAdapter receives incoming datagram packets by joining to a multicast address.

TCP inbound and outbound channel adapters are provided TcpSendingMessageHandler sends messages over TCP. TcpReceivingChannelAdapter receives messages over TCP.

An inbound TCP gateway is provided; this allows for simple request/response processing. While the gateway can support any number of connections, each connection can only process serially. The thread that reads from the socket waits for, and sends, the response before reading again. If the connection factory is configured for single use connections, the connection is closed after the socket times out.

An outbound TCP gateway is provided; this allows for simple request/response processing. If the associated connection factory is configured for single use connections, a new connection is immediately created for each new request. Otherwise, if the connection is in use, the calling thread blocks on the connection until either a response is received or a timeout or I/O error occurs.

The TCP and UDP inbound channel adapters, and the TCP inbound gateway, support the "error-channel" attribute. This provides the same basic functionality as described in Section 7.2.1, “Enter the GatewayProxyFactoryBean”.

16.2 UDP Adapters

 <int-ip:udp-outbound-channel-adapter id="udpOut"
    host="somehost"
    port="11111"
    multicast="false"
    channel="exampleChannel" />

A simple UDP outbound channel adapter.

[Tip]Tip
When setting multicast to true, provide the multicast address in the host attribute.

UDP is an efficient, but unreliable protocol. Two attributes are added to improve reliability. When check-length is set to true, the adapter precedes the message data with a length field (4 bytes in network byte order). This enables the receiving side to verify the length of the packet received. If a receiving system uses a buffer that is too short the contain the packet, the packet can be truncated. The length header provides a mechanism to detect this.

  <int-ip:udp-outbound-channel-adapter id="udpOut"
    host="somehost"
    port="11111"
    multicast="false"
    check-length="true"
    channel="exampleChannel" />

An outbound channel adapter that adds length checking to the datagram packets.

[Tip]Tip
The recipient of the packet must also be configured to expect a length to precede the actual data. For a Spring Integration UDP inbound channel adapter, set its check-length attribute.

The second reliability improvement allows an application-level acknowledgment protocol to be used. The receiver must send an acknowledgment to the sender within a specified time.

  <int-ip:udp-outbound-channel-adapter id="udpOut"
    host="somehost"
    port="11111"
    multicast="false"
    check-length="true"
    acknowledge="true"
    ack-host="thishost"
    ack-port="22222"
    ack-timeout="10000"
    channel="exampleChannel" />

An outbound channel adapter that adds length checking to the datagram packets and waits for an acknowledgment.

[Tip]Tip
Setting acknowledge to true implies the recipient of the packet can interpret the header added to the packet containing acknowledgment data (host and port). Most likely, the recipient will be a Spring Integration inbound channel adapter.

[Tip]Tip
When multicast is true, an additional attribute min-acks-for-success specifies how many acknowledgments must be received within the ack-timeout.

For even more reliable networking, TCP can be used.

  <int-ip:udp-inbound-channel-adapter id="udpReceiver"
    channel="udpOutChannel"
    port="11111"
    receive-buffer-size="500"
    multicast="false"
    check-length="true" />

A basic unicast inbound udp channel adapter.

  <int-ip:udp-inbound-channel-adapter id="udpReceiver"
    channel="udpOutChannel"
    port="11111"
    receive-buffer-size="500"
    multicast="true"
    multicast-address="225.6.7.8"
    check-length="true" />

A basic multicast inbound udp channel adapter.

By default, reverse DNS lookups are done on inbound packets to convert IP addresses to hostnames for use in message headers. In environments where DNS is not configured, this can cause delays. This default behavior can be overridden by setting the lookup-host attribute to "false".

16.3 TCP Connection Factories

For TCP, the configuration of the underlying connection is provided using a Connection Factory. Two types of connection factory are provided; a client connection factory and a server connection factory. Client connection factories are used to establish outgoing connections; Server connection factories listen for incoming connections.

A client connection factory is used by an outbound channel adapter but a reference to a client connection factory can also be provided to an inbound channel adapter and that adapter will receive any incoming messages received on connections created by the outbound adapter.

A server connection factory is used by an inbound channel adapter or gateway (in fact the connection factory will not function without one). A reference to a server connection factory can also be provided to an outbound adapter; that adapter can then be used to send replies to incoming messages to the same connection.

[Tip]Tip

Reply messages will only be routed to the connection if the reply contains the header ip_connection_id that was inserted into the original message by the connection factory.

[Tip]Tip

This is the extent of message correlation performed when sharing connection factories between inbound and outbound adapters. Such sharing allows for asynchronous two-way communication over TCP. Only payload information is transferred using TCP; therefore any message correlation must be performed by downstream components such as aggregators or other endpoints. For more information refer to Section 16.7, “TCP Message Correlation”.

A maximum of one adapter of each type may be given a reference to a connection factory.

Connection factories using java.net.Socket and java.nio.channel.SocketChannel are provided.

  <int-ip:tcp-connection-factory id="server"
    type="server"
    port="1234"
  />

A simple server connection factory that uses java.net.Socket connections.

  <int-ip:tcp-connection-factory id="server"
    type="server"
    port="1234"
    using-nio="true"
  />

A simple server connection factory that uses java.nio.channel.SocketChannel connections.

  <int-ip:tcp-connection-factory id="client"
    type="client"
    host="localhost"
    port="1234"
    single-use="true"
    so-timeout="10000"
  />

A client connection factory that uses java.net.Socket connections and creates a new connection for each message.

  <int-ip:tcp-connection-factory id="client"
    type="client"
    host="localhost"
    port="1234"
    single-use="true"
    so-timeout="10000"
    using-nio=true
  />

A client connection factory that uses java.nio.channel.Socket connections and creates a new connection for each message.

TCP is a streaming protocol; this means that some structure has to be provided to data transported over TCP, so the receiver can demarcate the data into discrete messages. Connection factories are configured to use (de)serializers to convert between the message payload and the bits that are sent over TCP. This is accomplished by providing a deserializer and serializer for inbound and outbound messages respectively. A number of standard (de)serializers are provided.

The ByteArrayCrlfSerializer, converts a byte array to a stream of bytes followed by carriage return and linefeed characters (\r\n). This is the default (de)serializer and can be used with telnet as a client, for example.

The ByteArrayStxEtxSerializer, converts a byte array to a stream of bytes preceded by an STX (0x02) and followed by an ETX (0x03).

The ByteArrayLengthHeaderSerializer, converts a byte array to a stream of bytes preceded by a binary length in network byte order (big endian). This a very efficient deserializer because it does not have to parse every byte looking for a termination character sequence. It can also be used for payloads containing binary data; the above serializers only support text in the payload. The default size of the length header is 4 bytes (Integer), allowing for messages up to 2**31-1 bytes. However, the length header can be a single byte (unsigned) for messages up to 255 bytes, or an unsigned short (2 bytes) for messages up to 2**16 bytes. If you need any other format for the header, you can subclass this class and provide implementations for the readHeader and writeHeader methods. The absolute maximum data size supported is 2**31-1 bytes.

The ByteArrayRawSerializer, converts a byte array to a stream of bytes and adds no additional message demarcation data; with this (de)serializer, the end of a message is indicated by the client closing the socket in an orderly fashion. When using this serializer, message reception will hang until the client closes the socket, or a timeout occurs; a timeout will NOT result in a message. When this serializer is being used, and the client is a Spring Integration application, the client must use a connection factory that is configured with single-use=true - this causes the adapter to close the socket after sending the message; the serializer will not, itself, close the connection. This serializer should only be used with connection factories used by channel adapters (not gateways), and the connection factories should be used by either an inbound or outbound adapter, and not both.

Each of these is a subclass of AbstractByteArraySerializer which implements both org.springframework.core.serializer.Serializer and org.springframework.core.serializer.Deserializer. For backwards compatibility, connections using any subclass of AbstractByteArraySerializer for serialization will also accept a String which will be converted to a byte array first. Each of these (de)serializers converts an input stream containing the corresponding format to a byte array payload.

To avoid memory exhaustion due to a badly behaved client (one that does not adhere to the protocol of the configured serializer), these serializers impose a maximum message size. If the size is exceeded by an incoming message, an exception will be thrown. The default maximum message size is 2048 bytes, and can be increased by setting the maxMessageSize property. If you are using the default (de)serializer and wish to increase the maximum message size, you must declare it as an explicit bean with the property set and configure the connection factory to use that bean.

The final standard serializer is org.springframework.core.serializer.DefaultSerializer which can be used to convert Serializable objects using java serialization. org.springframework.core.serializer.DefaultDeserializer is provided for inbound deserialization of streams containing Serializable objects.

To implement a custom (de)serializer pair, implement the org.springframework.core.serializer.Deserializer and org.springframework.core.serializer.Serializer interfaces.

If you do not wish to use the default (de)serializer (ByteArrayCrLfSerializer), you must supply serializer and deserializer attributes on the connection factory (example below).

  <bean id="javaSerializer"
        class="org.springframework.core.serializer.DefaultSerializer" />
  <bean id="javaDeserializer"
        class="org.springframework.core.serializer.DefaultDeserializer" />

  <int-ip:tcp-connection-factory id="server"
    type="server"
    port="1234"
    deserializer="javaDeserializer"
    serializer="javaSerializer"
  />

A server connection factory that uses java.net.Socket connections and uses Java serialization on the wire.

For full details of the attributes available on connection factories, see the reference at the end of this section.

By default, reverse DNS lookups are done on inbound packets to convert IP addresses to hostnames for use in message headers. In environments where DNS is not configured, this can cause connection delays. This default behavior can be overridden by setting the lookup-host attribute to "false".

[Note]Note

It is possible to modify the creation of and/or attributes of sockets - see Section 16.9, “SSL/TLS Support”. As is noted there, such modifications are possible whether or not SSL is being used.

16.3.1 TCP Caching Client Connection Factory

As noted above, TCP sockets cam be 'single-use' (one request/response) or shared. Shared sockets do not perform well with outbound gateways, in high-volume environments, because the socket can only process one request/response at a time.

To improve performance, users could use collaborating channel adapters instead of gateways, but that requires application-level message correlation. See Section 16.7, “TCP Message Correlation”for more information.

Spring Integration 2.2 introduced a caching client connection factory, where a pool of shared sockets is used, allowing a gateway to process multiple concurrent requests with a pool of shared connections.

16.3.2 TCP Failover Client Connection Factory

It is now possible to configure a TCP connection factory that supports failover to one or more other servers. When sending a message, the factory will iterate over all its configured factories until either the message can be sent, or no connection can be found. Initially, the first factory in the configured list is used; if a connection subsequently fails the next factory will become the current factory.

<bean id="failCF" class="o.s.i.ip.tcp.connection.FailoverClientConnectionFactory">
    <constructor-arg>
        <list>
            <ref bean="clientFactory1"/>
            <ref bean="clientFactory2"/>
        </list>
    </constructor-arg>
</bean>              
              

[Note]Note
When using the failover connection factory, the singleUse property must be consistent between the factory itself and the list of factories it is configured to use.

16.4 TCP Connection Interceptors

Connection factories can be configured with a reference to a TcpConnectionInterceptorFactoryChain. Interceptors can be used to add behavior to connections, such as negotiation, security, and other setup. No interceptors are currently provided by the framework but, for an example, see the InterceptedSharedConnectionTests in the source repository.

The HelloWorldInterceptor used in the test case works as follows:

When configured with a client connection factory, when the first message is sent over a connection that is intercepted, the interceptor sends 'Hello' over the connection, and expects to receive 'world!'. When that occurs, the negotiation is complete and the original message is sent; further messages that use the same connection are sent without any additional negotiation.

When configured with a server connection factory, the interceptor requires the first message to be 'Hello' and, if it is, returns 'world!'. Otherwise it throws an exception causing the connection to be closed.

All TcpConnection methods are intercepted. Interceptor instances are created for each connection by an interceptor factory. If an interceptor is stateful, the factory should create a new instance for each connection. Interceptor factories are added to the configuration of an interceptor factory chain, which is provided to a connection factory using the interceptor-factory attribute. Interceptors must implement the TcpConnectionInterceptor interface; factories must implement the TcpConnectionInterceptorFactory interface. A convenience class AbstractTcpConnectionInterceptor is provided with passthrough methods; by extending this class, you only need to implement those methods you wish to intercept.

<bean id="helloWorldInterceptorFactory"
   class="org.springframework.integration.ip.tcp.connection.TcpConnectionInterceptorFactoryChain">
  <property name="interceptors">
    <array>
      <bean class="org.springframework.integration.ip.tcp.connection.HelloWorldInterceptorFactory"/>
    </array>
  </property>
</bean>

<int-ip:tcp-connection-factory id="server"
  type="server"
  port="12345"
  using-nio="true"
  single-use="true"
  interceptor-factory-chain="helloWorldInterceptorFactory"
/>

<int-ip:tcp-connection-factory id="client"
  type="client"
  host="localhost"
  port="12345"
  single-use="true"
  so-timeout="100000"
  using-nio="true"
  interceptor-factory-chain="helloWorldInterceptorFactory"
/>

Configuring a connection interceptor factory chain.

16.5 TCP Adapters

TCP inbound and outbound channel adapters that utilize the above connection factories are provided. These adapters have attributes connection-factory and channel. The channel attribute specifies the channel on which messages arrive at an outbound adapter and on which messages are placed by an inbound adapter. The connection-factory attribute indicates which connection factory is to be used to manage connections for the adapter. While both inbound and outbound adapters can share a connection factory, server connection factories are always 'owned' by an inbound adapter; client connection factories are always 'owned' by an outbound adapter. One, and only one, adapter of each type may get a reference to a connection factory.

  <bean id="javaSerializer"
              class="org.springframework.core.serializer.DefaultSerializer" />
  <bean id="javaDeserializer"
              class="org.springframework.core.serializer.DefaultDeserializer" />

  <int-ip:tcp-connection-factory id="server"
    type="server"
    port="1234"
    deserializer="javaDeserializer"
    serializer="javaSerializer"
    using-nio="true"
    single-use="true"
  />

  <int-ip:tcp-connection-factory id="client"
    type="client"
    host="localhost"
    port="#{server.port}"
    single-use="true"
    so-timeout="10000"
    deserializer="javaDeserializer"
    serializer="javaSerializer"
  />

  <int:channel id="input" />

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

  <int-ip:tcp-outbound-channel-adapter id="outboundClient"
    channel="input"
    connection-factory="client"/>

  <int-ip:tcp-inbound-channel-adapter id="inboundClient"
    channel="replies"
    connection-factory="client"/>

  <int-ip:tcp-inbound-channel-adapter id="inboundServer"
    channel="loop"
    connection-factory="server"/>

  <int-ip:tcp-outbound-channel-adapter id="outboundServer"
    channel="loop"
    connection-factory="server"/>

  <int:channel id="loop" />

In this configuration, messages arriving in channel 'input' are serialized over connections created by 'client' received at the server and placed on channel 'loop'. Since 'loop' is the input channel for 'outboundServer' the message is simply looped back over the same connection and received by 'inboundClient' and deposited in channel 'replies'. Java serialization is used on the wire.

Normally, inbound adapters use a type="server" connection factory, which listens for incoming connection requests. In some cases, it is desireable to establish the connection in reverse, whereby the inbound adapter connects to an external server and then waits for inbound messages on that connection.

This topology is supported by using client-mode="true" on the inbound adapter. In this case, the connection factory must be of type 'client' and must have single-use set to false.

Two additional attributes are used to support this mechanism: retry-interval specifies (in milliseconds) how often the framework will attempt to reconnect after a connection failure. scheduler is used to supply a TaskScheduler used to schedule the connection attempts, and to test that the connection is still active.

For an outbound adapter, the connection is normally established when the first message is sent. client-mode="true" on an outbound adapter will cause the connection to be established when the adapter is started. Adapters are automatically started by default. Again, the connection factory must be of type client and have single-use set to false and retry-interval and scheduler are also supported. If a connection fails, it will be re-established either by the scheduler or when the next message is sent.

For both inbound and outbound, if the adapter is started, you may force the adapter to establish a connection by sending a <control-bus /> command: @adapter_id.retryConnection() and examine the current state with @adapter_id.isConnected().

16.6 TCP Gateways

The inbound TCP gateway TcpInboundGateway and outbound TCP gateway TcpOutboundGateway use a server and client connection factory respectively. Each connection can process a single request/response at a time.

The inbound gateway, after constructing a message with the incoming payload and sending it to the requestChannel, waits for a response and sends the payload from the response message by writing it to the connection.

[Note]Note

For the inbound gateway, care must be taken to retain, or populate, the ip_connnection_id header because it is used to correlate the message to a connection. Messages that originate at the gateway will automatically have the header set. If the reply is constructed as a new message, you will need to set the header. The header value can be captured from the incoming message.

As with inbound adapters, inbound gateways normally use a type="server" connection factory, which listens for incoming connection requests. In some cases, it is desireable to establish the connection in reverse, whereby the inbound gateway connects to an external server and then waits for, and replies to, inbound messages on that connection.

This topology is supported by using client-mode="true" on the inbound gateway. In this case, the connection factory must be of type 'client' and must have single-use set to false.

Two additional attributes are used to support this mechanism: retry-interval specifies (in milliseconds) how often the framework will attempt to reconnect after a connection failure. scheduler is used to supply a TaskScheduler used to schedule the connection attempts, and to test that the connection is still active.

If the gateway is started, you may force the gateway to establish a connection by sending a <control-bus /> command: @adapter_id.retryConnection() and examine the current state with @adapter_id.isConnected().

The outbound gateway, after sending a message over the connection, waits for a response and constructs a response message and puts in on the reply channel. Communications over the connections are single-threaded. Users should be aware that only one message can be handled at a time and, if another thread attempts to send a message before the current response has been received, it will block until any previous requests are complete (or time out). If, however, the client connection factory is configured for single-use connections each new request gets its own connection and is processed immediately.

  <int-ip:tcp-inbound-gateway id="inGateway"
    request-channel="tcpChannel"
    reply-channel="replyChannel"
    connection-factory="cfServer"
    reply-timeout="10000"
        />

A simple inbound TCP gateway; if a connection factory configured with the default (de)serializer is used, messages will be \r\n delimited data and the gateway can be used by a simple client such as telnet.

  <int-ip:tcp-outbound-gateway id="outGateway"
    request-channel="tcpChannel"
    reply-channel="replyChannel"
    connection-factory="cfClient"
    request-timeout="10000"
    remote-timeout="10000"
    />

A simple outbound TCP gateway.

16.7 TCP Message Correlation

16.7.1 Overview

One goal of the IP Endpoints is to provide communication with systems other than another Spring Integration application. For this reason, only message payloads are sent and received. No message correlation is provided by the framework, except when using the gateways, or collaborating channel adapters on the server side. In the paragraphs below we discuss the various correlation techniques available to applications. In most cases, this requires specific application-level correlation of messages, even when message payloads contain some natural correlation data (such as an order number).

16.7.2 Gateways

The gateways will automatically correlate messages. However, an outbound gateway should only be used for relatively low-volume use. When the connection factory is configured for a single shared connection to be used for all message pairs ('single-use="false"'), only one message can be processed at a time. A new message will have to wait until the reply to the previous message has been received. When a connection factory is configured for each new message to use a new connection ('single-use="true"'), the above restriction does not apply. While this may give higher throughput than a shared connection environment, it comes with the overhead of opening and closing a new connection for each message pair.

Therefore, for high-volume messages, consider using a collaborating pair of channel adapters. However, you will need to provide collaboration logic.

Another solution, introduced in Spring Integration 2.2, is to use a CachingClientConnectionFactory, which allows the use of a pool of shared connections.

16.7.3 Collaborating Outbound and Inbound Channel Adapters

To achieve high-volume throughput (avoiding the pitfalls of using gateways as mentioned above) you may consider configuring a pair of collaborating outbound and inbound channel adapters. Collaborating adapters can also be used (server-side or client-side) for totally asynchronous communication (rather than with request/reply semantics). On the server side, message correlation is automatically handled by the adapters because the inbound adapter adds a header allowing the outbound adapter to determine which connection to use to send the reply message.

[Note]Note

On the server side, care must be taken to populate the ip_connnection_id header because it is used to correlate the message to a connection. Messages that originate at the inbound adapter will automatically have the header set. If you wish to construct other messages to send, you will need to set the header. The header value can be captured from an incoming message.

On the client side, the application will have to provide its own correlation logic, if needed. This can be done in a number of ways.

If the message payload has some natural correlation data, such as a transaction id or an order number, AND there is no need to retain any information (such as a reply channel header) from the original outbound message, the correlation is simple and would done at the application level in any case.

If the message payload has some natural correlation data, such as a transaction id or an order number, but there is a need to retain some information (such as a reply channel header) from the original outbound message, you may need to retain a copy of the original outbound message (perhaps by using a publish-subscribe channel) and use an aggregator to recombine the necessary data.

For either of the previous two paragraphs, if the payload has no natural correlation data, you may need to provide a transformer upstream of the outbound channel adapter to enhance the payload with such data. Such a transformer may transform the original payload to a new object containing both the original payload and some subset of the message headers. Of course, live objects (such as reply channels) from the headers can not be included in the transformed payload.

If such a strategy is chosen you will need to ensure the connection factory has an appropriate serializer/deserializer pair to handle such a payload, such as the DefaultSerializer/Deserializer which use java serialization, or a custom serializer and deserializer. The ByteArray*Serializer options mentioned in Section 16.3, “TCP Connection Factories”, including the default ByteArrayCrLfSerializer, do not support such payloads, unless the transformed payload is a String or byte[],

[Note]Note

Before the 2.2 release, when a client connection factory was used by collaborating channel adapters, the so-timeout attribute defaulted to the default reply timeout (10 seconds). This meant that if no data were received by the inbound adapter for this period of time, the socket was closed.

This default behavior was not appropriate in a truly asynchronous environment, so it now defaults to an infinite timeout. You can reinstate the previous default behavior by setting the so-timeout attribute on the client connection factory to 10000 milliseconds.

16.8 A Note About NIO

Using NIO (see using-nio in Section 16.10, “IP Configuration Attributes”) avoids dedicating a thread to read from each socket. For a small number of sockets, you will likely find that not using NIO, together with an async handoff (e.g. to a QueueChannel), will perform as well as, or better than, using NIO.

Consider using NIO when handling a large number of connections. However, the use of NIO has some other ramifications. A pool of threads (in the task executor) is shared across all the sockets; each incoming message is assembled and sent to the configured channel as a separate unit of work on a thread selected from that pool. Two sequential messages arriving on the same socket might be processed by different threads. This means that the order in which the messages are sent to the channel is indeterminate; the strict ordering of the messages arriving on the socket is not maintained.

For some applications, this is not an issue; for others it is. If strict ordering is required, consider setting using-nio to false and using async handoff.

Alternatively, you may choose to insert a resequencer downstream of the inbound endpoint to return the messages to their proper sequence. Set apply-sequence to true on the connection factory, and messages arriving on a TCP connection will have sequenceNumber and correlationId headers set. The resequencer uses these headers to return the messages to their proper sequence.

Pool Size

The pool size attribute is no longer used; previously, it specified the size of the default thread pool when a task-executor was not specified. It was also used to set the connection backlog on server sockets. The first function is no longer needed (see below); the second function is replaced by the backlog attribute.

Previously, when using a fixed thread pool task executor (which was the default), with NIO, it was possible to get a deadlock and processing would stop. The problem occurred when a buffer was full, a thread reading from the socket was trying to add more data to the buffer, and there were no threads available to make space in the buffer. This only occurred with a very small pool size, but it could be possible under extreme conditions. Since 2.2, two changes have eliminated this problem. First, the default task executor is a cached thread pool executor. Second, deadlock detection logic has been added such that if thread starvation occurs, instead of deadlocking, an exception is thrown, thus releasing the deadlocked resources.

[Note]Note
Now that the default task executor is unbounded, it is possible that an out of memory condition might occur with high rates of incoming messages, if message processing takes extended time. If your application exhibits this type of behavior, you are advised to use a pooled task executor with an appropriate pool size.

16.9 SSL/TLS Support

16.9.1 Overview

Secure Sockets Layer/Transport Layer Security is supported. When using NIO, the JDK 5+ SSLEngine feature is used to handle handshaking after the connection is established. When not using NIO, standard SSLSocketFactory and SSLServerSocketFactory objects are used to create connections. A number of strategy interfaces are provided to allow significant customization; default implementations of these interfaces provide for the simplest way to get started with secure communications.

16.9.2 Getting Started

Regardless of whether NIO is being used, you need to configure the ssl-context-support attribute on the connection factory. This attribute references a <bean/> definition that describes the location and passwords for the required key stores.

SSL/TLS peers require two keystores each; a keystore containing private/public key pairs identifying the peer; a truststore, containing the public keys for peers that are trusted. See the documentation for the keytool utility provided with the JDK. The essential steps are

  1. Create a new key pair and store in a keystore.

  2. Export the public key.

  3. Import the public key into the peer's truststore.

Repeat for the other peer.

[Note]Note

It is common in test cases to use the same key stores on both peers, but this should be avoided for production.

After establishing the key stores, the next step is to indicate their locations to the TcpSSLContextSupport bean, and provide a reference to that bean to the connection factory.

    <bean id="sslContextSupport"
        class="o.sf.integration.ip.tcp.connection.support.DefaultTcpSSLContextSupport">
        <constructor-arg value="client.ks"/>
        <constructor-arg value="client.truststore.ks"/>
        <constructor-arg value="secret"/>
        <constructor-arg value="secret"/>
    </bean>

    <ip:tcp-connection-factory id="clientFactory"
        type="client"
        host="localhost"
        port="1234"
        ssl-context-support="sslContextSupport"

The DefaulTcpSSLContextSupport class also has an optional 'protocol' property, which can be 'SSL' or 'TLS' (default).

The keystore file names (first two constructor arguments) use the Spring Resource abstraction; by default the files will be located on the classpath, but this can be overridden by using the file: prefix, to find the files on the filesystem instead.

16.9.3 Advanced Techniques

In many cases, the configuration described above is all that is needed to enable secure communication over TCP/IP. However, a number of strategy interfaces are provided to allow customization and modification of socket factories and sockets.

  • TcpSSLContextSupport

  • TcpSocketFactorySupport

  • TcpSocketSupport

public interface TcpSSLContextSupport {

	SSLContext getSSLContext() throws Exception;

}

Implementations of this interface are responsible for creating an SSLContext. The sole implementation provided by the framework is the DefaultTcpSSLContextSupport described above. If you require different behavior, implement this interface and provide the connection factory with a reference to a bean of your class' implementation.

public interface TcpSocketFactorySupport {

    ServerSocketFactory getServerSocketFactory();

    SocketFactory getSocketFactory();

}

Implementations of this interface are responsible for obtaining references to ServerSocketFactory and SocketFactory. Two implementations are provided; the first is DefaultTcpNetSocketFactorySupport for non-SSL sockets (when no 'ssl-context-support' attribute is defined); this simply uses the JDK's default factories. The second implementation is DefaultTcpNetSSLSocketFactorySupport; this is used, by default, when an 'ssl-context-support' attribute is defined; it uses the SSLContext created by that bean to create the socket factories.

[Note]Note

This interface only applies if using-nio is "false"; socket factories are not used by NIO.

public interface TcpSocketSupport {

    void postProcessServerSocket(ServerSocket serverSocket);

    void postProcessSocket(Socket socket);

Implementations of this interface can modify sockets after they are created, and after all configured attributes have been applied, but before the sockets are used. This applies whether or not NIO is being used. For example, you could use an implementation of this interface to modify the supported cipher suites on an SSL socket, or you could add a listener that gets notified after SSL handshaking is complete. The sole implementation provided by the framework is the DefaultTcpSocketSupport which does not modify the sockets in any way

To supply your own implementation of TcpSocketFactorySupport or TcpSocketSupport, provide the connection factory with references to beans of your custom type using the socket-factory-support and socket-support attributes, respectively.

16.10 IP Configuration Attributes

Table 16.1. Connection Factory Attributes

Attribute NameClient?Server?Allowed ValuesAttribute Description
typeYYclient, serverDetermines whether the connection factory is a client or server.
hostYN The host name or ip address of the destination.
portYY The port.
serializerYY An implementation of Serializer used to serialize the payload. Defaults to ByteArrayCrLfSerializer
deserializerYY An implementation of Deserializer used to deserialize the payload. Defaults to ByteArrayCrLfSerializer
using-nioYYtrue, falseWhether or not connection uses NIO. Refer to the java.nio package for more information. See Section 16.8, “A Note About NIO”. Default false.
using-direct-buffersYNtrue, falseWhen using NIO, whether or not the connection uses direct buffers. Refer to java.nio.ByteBuffer documentation for more information. Must be false if using-nio is false.
apply-sequenceYYtrue, falseWhen using NIO, it may be necessary to resequence messages. When this attribute is set to true, correlationId and sequenceNumber headers will be added to received messages. See Section 16.8, “A Note About NIO”. Default false.
so-timeoutYY Defaults to 0 (infinity), except for server connection factories with single-use="true". In that case, it defaults to the default reply timeout (10 seconds).
so-send-buffer-sizeYY See java.net.Socket. setSendBufferSize().
so-receive-buffer- sizeYY See java.net.Socket. setReceiveBufferSize().
so-keep-aliveYYtrue, falseSee java.net.Socket. setKeepAlive().
so-lingerYY Sets linger to true with supplied value. See java.net.Socket. setSoLinger().
so-tcp-no-delayYYtrue, falseSee java.net.Socket. setTcpNoDelay().
so-traffic-classYY See java.net.Socket. setTrafficClass().
local-addressNY On a multi-homed system, specifies an IP address for the interface to which the socket will be bound.
task-executorYY  Specifies a specific Executor to be used for socket handling. If not supplied, an internal cached thread executor will be used. Needed on some platforms that require the use of specific task executors such as a WorkManagerTaskExecutor.
single-useYYtrue, falseSpecifies whether a connection can be used for multiple messages. If true, a new connection will be used for each message.
pool-sizeNN This attribute is no longer used. For backward compatibility, it sets the backlog but users should use backlog to specify the connection backlog in server factories
backlogNY Sets the connection backlog for server factories.
lookup-hostYYtrue, false Specifies whether reverse lookups are done on IP addresses to convert to host names for use in message headers. If false, the IP address is used instead. Defaults to true.
interceptor-factory-chainYY See Section 16.4, “TCP Connection Interceptors”
ssl-context-supportYY See Section 16.9, “SSL/TLS Support”
socket-factory-supportYY See Section 16.9, “SSL/TLS Support”
socket-supportYY See Section 16.9, “SSL/TLS Support”


Table 16.2. UDP Inbound Channel Adapter Attributes

Attribute NameAllowed ValuesAttribute Description
port The port on which the adapter listens.
multicasttrue, falseWhether or not the udp adapter uses multicast.
multicast-address When multicast is true, the multicast address to which the adapter joins.
pool-size Specifies the concurrency. Specifies how many packets can be handled concurrently. It only applies if task-executor is not configured. Defaults to 5.
task-executor  Specifies a specific Executor to be used for socket handling. If not supplied, an internal pooled executor will be used. Needed on some platforms that require the use of specific task executors such as a WorkManagerTaskExecutor. See pool-size for thread requirements.
receive-buffer-size The size of the buffer used to receive DatagramPackets. Usually set to the MTU size. If a smaller buffer is used than the size of the sent packet, truncation can occur. This can be detected by means of the check-length attribute..
check-lengthtrue, falseWhether or not a udp adapter expects a data length field in the packet received. Used to detect packet truncation.
so-timeout See java.net.DatagramSocket setSoTimeout() methods for more information.
so-send-buffer-size Used for udp acknowledgment packets. See java.net.DatagramSocket setSendBufferSize() methods for more information.
so-receive-buffer- size See java.net.DatagramSocket setReceiveBufferSize() for more information.
local-address On a multi-homed system, specifies an IP address for the interface to which the socket will be bound.
error-channel If an Exception is thrown by a downstream component, the MessagingException message containing the exception and failed message is sent to this channel.
lookup-hosttrue, false Specifies whether reverse lookups are done on IP addresses to convert to host names for use in message headers. If false, the IP address is used instead. Defaults to true.


Table 16.3. UDP Outbound Channel Adapter Attributes

Attribute NameAllowed ValuesAttribute Description
host The host name or ip address of the destination. For multicast udp adapters, the multicast address.
port The port on the destination.
multicasttrue, falseWhether or not the udp adapter uses multicast.
acknowledgetrue, falseWhether or not a udp adapter requires an acknowledgment from the destination. when enabled, requires setting the following 4 attributes.
ack-host When acknowledge is true, indicates the host or ip address to which the acknowledgment should be sent. Usually the current host, but may be different, for example when Network Address Transaction (NAT) is being used.
ack-port When acknowledge is true, indicates the port to which the acknowledgment should be sent. The adapter listens on this port for acknowledgments.
ack-timeout When acknowledge is true, indicates the time in milliseconds that the adapter will wait for an acknowledgment. If an acknowledgment is not received in time, the adapter will throw an exception.
min-acks-for- success Defaults to 1. For multicast adapters, you can set this to a larger value, requiring acknowledgments from multiple destinations.
check-lengthtrue, falseWhether or not a udp adapter includes a data length field in the packet sent to the destination.
time-to-live For multicast adapters, specifies the time to live attribute for the MulticastSocket; controls the scope of the multicasts. Refer to the Java API documentation for more information.
so-timeout See java.net.DatagramSocket setSoTimeout() methods for more information.
so-send-buffer-size See java.net.DatagramSocket setSendBufferSize() methods for more information.
so-receive-buffer- size Used for udp acknowledgment packets. See java.net.DatagramSocket setReceiveBufferSize() methods for more information.
local-address On a multi-homed system, for the UDP adapter, specifies an IP address for the interface to which the socket will be bound for reply messages. For a multicast adapter it is also used to determine which interface the multicast packets will be sent over.
task-executor  Specifies a specific Executor to be used for acknowledgment handling. If not supplied, an internal single threaded executor will be used. Needed on some platforms that require the use of specific task executors such as a WorkManagerTaskExecutor. One thread will be dedicated to handling acknowledgments (if the acknowledge option is true).


Table 16.4. TCP Inbound Channel Adapter Attributes

Attribute NameAllowed ValuesAttribute Description
channel The channel to which inbound messages will be sent.
connection-factory If the connection factory has a type 'server', the factory is 'owned' by this adapter. If it has a type 'client', it is 'owned' by an outbound channel adapter and this adapter will receive any incoming messages on the connection created by the outbound adapter.
error-channel If an Exception is thrown by a downstream component, the MessagingException message containing the exception and failed message is sent to this channel.
client-modetrue, false When true, the inbound adapter will act as a client, with respect to establishing the connection and then receive incoming messages on that connection. Default = false. Also see retry-interval and scheduler. The connection factory must be of type 'client' and have single-use set to false.
retry-interval  When in client-mode, specifies the number of milliseconds to wait between connection attempts, or after a connection failure. Default 60,000 (60 seconds).
schedulertrue, false Specifies a TaskScheduler to use for managing the client-mode connection. Defaults to a ThreadPoolTaskScheduler with a pool size of `.


Table 16.5. TCP Outbound Channel Adapter Attributes

Attribute NameAllowed ValuesAttribute Description
channel The channel on which outbound messages arrive.
connection-factory If the connection factory has a type 'client', the factory is 'owned' by this adapter. If it has a type 'server', it is 'owned' by an inbound channel adapter and this adapter will attempt to correlate messages to the connection on which an original inbound message was received.
client-modetrue, false When true, the outbound adapter will attempt to establish the connection as soon as it is started. When false, the connection is established when the first message is sent. Default = false. Also see retry-interval and scheduler. The connection factory must be of type 'client' and have single-use set to false.
retry-interval  When in client-mode, specifies the number of milliseconds to wait between connection attempts, or after a connection failure. Default 60,000 (60 seconds).
schedulertrue, false Specifies a TaskScheduler to use for managing the client-mode connection. Defaults to a ThreadPoolTaskScheduler with a pool size of `.


Table 16.6. TCP Inbound Gateway Attributes

Attribute NameAllowed ValuesAttribute Description
connection-factory The connection factory must be of type server.
request-channel The channel to which incoming messages will be sent.
reply-channel The channel on which reply messages may arrive. Usually replies will arrive on a temporary reply channel added to the inbound message header
reply-timeout The time in milliseconds for which the gateway will wait for a reply. Default 1000 (1 second).
error-channel If an Exception is thrown by a downstream component, the MessagingException message containing the exception and failed message is sent to this channel; any reply from that flow will then be returned as a response by the gateway.
client-modetrue, false When true, the inbound gateway will act as a client, with respect to establishing the connection and then receive (and reply to) incoming messages on that connection. Default = false. Also see retry-interval and scheduler. The connection factory must be of type 'client' and have single-use set to false.
retry-interval  When in client-mode, specifies the number of milliseconds to wait between connection attempts, or after a connection failure. Default 60,000 (60 seconds).
schedulertrue, false Specifies a TaskScheduler to use for managing the client-mode connection. Defaults to a ThreadPoolTaskScheduler with a pool size of `.


Table 16.7. TCP Outbound Gateway Attributes

Attribute NameAllowed ValuesAttribute Description
connection-factory The connection factory must be of type client.
request-channel The channel on which outgoing messages will arrive.
reply-channel Optional. The channel to which reply messages may be sent if the original outbound message did not contain a reply channel header.
remote-timeout The time in milliseconds for which the gateway will wait for a reply from the remote system. Default: Same value as reply-timeout, if specified, or 10000 (10 seconds) otherwise.
request-timeout If a single-use connection factory is not being used, The time in milliseconds for which the gateway will wait to get access to the shared connection.
reply-timeout The time in milliseconds for which the gateway will wait when sending the reply to the reply-channel. Only applies if the reply-channel might block, such as a bounded QueueChannel that is currently full.


17. JDBC Support

Spring Integration provides Channel Adapters for receiving and sending messages via database queries. Through those adapters Spring Integration supports not only plain JDBC SQL Queries, but also Stored Procedure and Stored Function calls.

The following JDBC components are available by default:

Furthermore, the Spring Integration JDBC Module also provides a JDBC Message Store

17.1 Inbound Channel Adapter

The main function of an inbound Channel Adapter is to execute a SQL SELECT query and turn the result set as a message. The message payload is the whole result set, expressed as a List, and the types of the items in the list depend on the row-mapping strategy that is used. The default strategy is a generic mapper that just returns a Map for each row in the query result. Optionally, this can be changed by adding a reference to a RowMapper instance (see the Spring JDBC documentation for more detailed information about row mapping).

[Note]Note
If you want to convert rows in the SELECT query result to individual messages you can use a downstream splitter.

The inbound adapter also requires a reference to either a JdbcTemplate instance or a DataSource.

As well as the SELECT statement to generate the messages, the adapter above also has an UPDATE statement that is being used to mark the records as processed so that they don't show up in the next poll. The update can be parameterized by the list of ids from the original select. This is done through a naming convention by default (a column in the input result set called "id" is translated into a list in the parameter map for the update called "id"). The following example defines an inbound Channel Adapter with an update query and a DataSource reference.

<int-jdbc:inbound-channel-adapter query="select * from item where status=2"
    channel="target" data-source="dataSource"
    update="update item set status=10 where id in (:id)" />

[Note]Note
The parameters in the update query are specified with a colon (:) prefix to the name of a parameter (which in this case is an expression to be applied to each of the rows in the polled result set). This is a standard feature of the named parameter JDBC support in Spring JDBC combined with a convention (projection onto the polled result list) adopted in Spring Integration. The underlying Spring JDBC features limit the available expressions (e.g. most special characters other than period are disallowed), but since the target is usually a list of or an individual object addressable by simple bean paths this isn't unduly restrictive.

To change the parameter generation strategy you can inject a SqlParameterSourceFactory into the adapter to override the default behavior (the adapter has a sql-parameter-source-factory attribute).

17.1.1 Polling and Transactions

The inbound adapter accepts a regular Spring Integration poller as a sub element, so for instance the frequency of the polling can be controlled. A very important feature of the poller for JDBC usage is the option to wrap the poll operation in a transaction, for example:

<int-jdbc:inbound-channel-adapter query="..."
        channel="target" data-source="dataSource" update="...">
    <int:poller fixed-rate="1000">
        <int:transactional/>
    </int:poller>
</int-jdbc:inbound-channel-adapter>
[Note]Note
If a poller is not explicitly specified, a default value will be used (and as per normal with Spring Integration can be defined as a top level bean).

In this example the database is polled every 1000 milliseconds, and the update and select queries are both executed in the same transaction. The transaction manager configuration is not shown, but as long as it is aware of the data source then the poll is transactional. A common use case is for the downstream channels to be direct channels (the default), so that the endpoints are invoked in the same thread, and hence the same transaction. Then if any of them fail, the transaction rolls back and the input data is reverted to its original state.

17.1.2 Max-rows-per-poll versus Max-messages-per-poll

The JDBC Inbound Channel Adapter defines an attribute max-rows-per-poll. When you specify the adapter's Poller, you can also define a property called max-messages-per-poll. While these two attributes look similar, their meaning is quite different.

max-messages-per-poll specifies the number of times the query is executed per polling interval, whereas max-rows-per-poll specifies the number of rows returned for each execution.

Under normal circumstances, you would likely not want to set the Poller's max-messages-per-poll property when using the JDBC Inbound Channel Adapter. Its default value is 1, which means that the JDBC Inbound Channel Adapter's receive() method is executed exactly once for each poll interval.

Setting the max-messages-per-poll attribute to a larger value means that the query is executed that many times back to back. For more information regarding the max-messages-per-poll attribute, please see Section 3.3.1, “Configuring An Inbound Channel Adapter”.

In contrast, the max-rows-per-poll attribute, if greater than 0, specifies the maximum number of rows that will be used from the query result set, per execution of the receive() method. If the attribute is set to 0, then all rows will be included in the resulting message. If not explicitly set, the attribute defaults to 0.

17.2 Outbound Channel Adapter

The outbound Channel Adapter is the inverse of the inbound: its role is to handle a message and use it to execute a SQL query. The message payload and headers are available by default as input parameters to the query, for instance:

<int-jdbc:outbound-channel-adapter
    query="insert into foos (id, status, name) values (:headers[id], 0, :payload[foo])"
    data-source="dataSource"
    channel="input"/>

In the example above, messages arriving on the channel labelled input have a payload of a map with key foo, so the [] operator dereferences that value from the map. The headers are also accessed as a map.

[Note]Note
The parameters in the query above are bean property expressions on the incoming message (not Spring EL expressions). This behavior is part of the SqlParameterSource which is the default source created by the outbound adapter. Other behavior is possible in the adapter, and requires the user to inject a different SqlParameterSourceFactory.

The outbound adapter requires a reference to either a DataSource or a JdbcTemplate. It can also have a SqlParameterSourceFactory injected to control the binding of each incoming message to a query.

If the input channel is a direct channel, then the outbound adapter runs its query in the same thread, and therefore the same transaction (if there is one) as the sender of the message.

Passing Parameters using SpEL Expressions

A common requirement for most JDBC Channel Adapters is to pass parameters as part of Sql queries or Stored Procedures/Functions. As mentioned above, these parameters are by default bean property expressions, not SpEL expressions. However, if you need to pass SpEL expression as parameters, you must inject a SqlParameterSourceFactory explicitly.

The following example uses a ExpressionEvaluatingSqlParameterSourceFactory to achieve that requirement.

<jdbc:outbound-channel-adapter data-source="dataSource" channel="input"
    query="insert into MESSAGES (MESSAGE_ID,PAYLOAD,CREATED_DATE)     \
    values (:id, :payload, :createdDate)"
    sql-parameter-source-factory="spelSource"/>

<bean id="spelSource"
      class="o.s.integration.jdbc.ExpressionEvaluatingSqlParameterSourceFactory">
    <property name="parameterExpressions">
        <map>
            <entry key="id"          value="headers['id'].toString()"/>
            <entry key="createdDate" value="new java.util.Date()"/>
            <entry key="payload"     value="payload"/>
        </map>
    </property>
</bean>

For further information, please also see Section 17.5.5, “Defining Parameter Sources”

17.3 Outbound Gateway

The outbound Gateway is like a combination of the outbound and inbound adapters: its role is to handle a message and use it to execute a SQL query and then respond with the result sending it to a reply channel. The message payload and headers are available by default as input parameters to the query, for instance:

<int-jdbc:outbound-gateway
    update="insert into foos (id, status, name) values (:headers[id], 0, :payload[foo])"
    request-channel="input" reply-channel="output" data-source="dataSource" />

The result of the above would be to insert a record into the "foos" table and return a message to the output channel indicating the number of rows affected (the payload is a map: {UPDATED=1}).

If the update query is an insert with auto-generated keys, the reply message can be populated with the generated keys by adding keys-generated="true" to the above example (this is not the default because it is not supported by some database platforms). For example:

<int-jdbc:outbound-gateway
    update="insert into foos (status, name) values (0, :payload[foo])"
    request-channel="input" reply-channel="output" data-source="dataSource"
    keys-generated="true"/>

Instead of the update count or the generated keys, you can also provide a select query to execute and generate a reply message from the result (like the inbound adapter), e.g:

<int-jdbc:outbound-gateway
    update="insert into foos (id, status, name) values (:headers[id], 0, :payload[foo])"
    query="select * from foos where id=:headers[$id]"
    request-channel="input" reply-channel="output" data-source="dataSource"/>

Since Spring Integration 2.2 the update SQL query is no longer mandatory. You can now solely provide a select query, using either the query attribute or the query sub-element. This is extremely useful if you need to actively retrieve data using e.g. a generic Gateway or a Payload Enricher. The reply message is then generated from the result, like the inbound adapter, and passed to the reply channel.

<int-jdbc:outbound-gateway
    query="select * from foos where id=:headers[id]"
    request-channel="input"
    reply-channel="output"
    data-source="dataSource"/>

As with the channel adapters, there is also the option to provide SqlParameterSourceFactory instances for request and reply. The default is the same as for the outbound adapter, so the request message is available as the root of an expression. If keys-generated="true" then the root of the expression is the generated keys (a map if there is only one or a list of maps if multi-valued).

The outbound gateway requires a reference to either a DataSource or a JdbcTemplate. It can also have a SqlParameterSourceFactory injected to control the binding of the incoming message to the query.

17.4 JDBC Message Store

The JDBC module provides an implementation of the Spring Integration MessageStore (important in the Claim Check pattern) and MessageGroupStore (important in stateful patterns like Aggregator) backed by a database. Both interfaces are implemented by the JdbcMessageStore, and there is also support for configuring store instances in XML. For example:

<int-jdbc:message-store id="messageStore" data-source="dataSource"/>

A JdbcTemplate can be specified instead of a DataSource.

Other optional attributes are show in the next example:

<int-jdbc:message-store id="messageStore" data-source="dataSource"
    lob-handler="lobHandler" table-prefix="MY_INT_"/>

Here we have specified a LobHandler for dealing with messages as large objects (e.g. often necessary if using Oracle) and a prefix for the table names in the queries generated by the store. The table name prefix defaults to "INT_".

17.4.1 Initializing the Database

Spring Integration ships with some sample scripts that can be used to initialize a database. In the spring-integration-jdbc JAR file you will find scripts in the org.springframework.integration.jdbc package: there is a create and a drop script example for a range of common database platforms. A common way to use these scripts is to reference them in a Spring JDBC data source initializer. Note that the scripts are provided as samples or specifications of the the required table and column names. You may find that you need to enhance them for production use (e.g. with index declarations).

17.4.2 Partitioning a Message Store

It is common to use a JdbcMessageStore as a global store for a group of applications, or nodes in the same application. To provide some protection against name clashes, and to give control over the database meta-data configuration, the message store allows the tables to be partitioned in two ways. One is to use separate table names, by changing the prefix as described above, and the other is to specify a "region" name for partitioning data within a single table. An important use case for this is when the MessageStore is managing persistent queues backing a Spring Integration Message Channel. The message data for a persistent channel is keyed in the store on the channel name, so if the channel names are not globally unique then there is the danger of channels picking up data that was not intended for them. To avoid this, the message store region can be used to keep data separate for different physical channels that happen to have the same logical name.

17.5 Stored Procedures

In certain situations plain JDBC support is not sufficient. Maybe you deal with legacy relational database schemas or you have complex data processing needs, but ultimately you have to use Stored Procedures or Stored Functions. Since Spring Integration 2.1, we provide three components in order to execute Stored Procedures or Stored Functions:

  • Stored Procedures Inbound Channel Adapter
  • Stored Procedures Outbound Channel Adapter
  • Stored Procedures Outbound Gateway

17.5.1 Supported Databases

In order to enable calls to Stored Procedures and Stored Functions, the Stored Procedure components use the org.springframework.jdbc.core.simple.SimpleJdbcCall class. Consequently, the following databases are fully supported for executing Stored Procedures:

  • Apache Derby
  • DB2
  • MySQL
  • Microsoft SQL Server
  • Oracle
  • PostgreSQL
  • Sybase

If you want to exute Stored Functions instead, the following databases are fully supported:

  • MySQL
  • Microsoft SQL Server
  • Oracle
  • PostgreSQL
[Note]Note

Even though your particular database may not be fully supported, chances are, that you can use the Stored Procedure Spring Integration components quite successfully anyway, provided your RDBMS supports Stored Procedures or Functions.

As a matter of fact, some of the provided integration tests use the H2 database. Nevertheless, it is very important to thoroughly test those usage scenarios.

17.5.2 Configuration

The Stored Procedure components provide full XML Namespace support and configuring the components is similar as for the general purpose JDBC components discussed earlier.

17.5.3 Common Configuration Attributes

Certain configuration parameters are shared among all Stored Procedure components and are described below:

auto-startup

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

data-source

Reference to a javax.sql.DataSource, which is used to access the database. Required.

id

Identifies the underlying Spring bean definition, which is an instance of either EventDrivenConsumer or PollingConsumer, depending on whether the Outbound Channel Adapter's channel attribute references a SubscribableChannel or a PollableChannel. Optional.

ignore-column-meta-data

For fully supported databases, the underlying SimpleJdbcCall class can automatically retrieve the parameter information for the to be invoked Stored Procedure or Function from the JDBC Meta-data.

However, if the used database does not support meta data lookups or if you like to provide customized parameter definitions, this flag can be set to true. It defaults to false. Optional.

is-function

If true, a SQL Function is called. In that case the stored-procedure-name or stored-procedure-name-expression attributes define the name of the called function. Defaults to false. Optional.

stored-procedure-name

The attribute specifies the name of the stored procedure. If the is-function attribute is set to true, this attribute specifies the function name instead. Either this property or stored-procedure-name-expression must be specified.

stored-procedure-name-expression

This attribute specifies the name of the stored procedure using a SpEL expression. Using SpEL you have access to the full message (if available), including its headers and payload. You can use this attribute to invoke different Stored Procedures at runtime. For example, you can provide Stored Procedure names that you would like to execute as a Message Header. The expression must resolve to a String.

If the is-function attribute is set to true, this attribute specifies a Stored Function. Either this property or stored-procedure-name must be specified.

jdbc-call-operations-cache-size

Defines the maximum number of cached SimpleJdbcCallOperations instances. Basically, for each Stored Procedure Name a new SimpleJdbcCallOperations instance is created that in return is being cached.

[Note]Note
The stored-procedure-name-expression attribute and the jdbc-call-operations-cache-size were added with Spring Integration 2.2.

The default cache size is 10. A value of 0 disables caching. Negative values are not permitted.

If you enable JMX, statistical information about the jdbc-call-operations-cache is exposed as MBean. Please see Section 8.1.6, “MBean Exporter” for more information.

sql-parameter-source-factory (Not available for the Stored Procedure Inbound Channel Adapter.)

Reference to a SqlParameterSourceFactory. By default bean properties of the passed in Message payload will be used as a source for the Stored Procedure's input parameters using a BeanPropertySqlParameterSourceFactory.

This may be sufficient for basic use cases. For more sophisticated options, consider passing in one or more ProcedureParameter. Please also refer to Section 17.5.5, “Defining Parameter Sources”. Optional.

use-payload-as-parameter-source (Not available for the Stored Procedure Inbound Channel Adapter.)

If set to true, the payload of the Message will be used as a source for providing parameters. If false, however, the entire Message will be available as a source for parameters.

If no Procedure Parameters are passed in, this property will default to true. This means that using a default BeanPropertySqlParameterSourceFactory the bean properties of the payload will be used as a source for parameter values for the to-be-executed Stored Procedure or Stored Function.

However, if Procedure Parameters are passed in, then this property will by default evaluate to false. ProcedureParameter allow for SpEL Expressions to be provided and therefore it is highly beneficial to have access to the entire Message. The property is set on the underlying StoredProcExecutor. Optional.

17.5.4 Common Configuration Sub-Elements

The Stored Procedure components share a common set of sub-elements to define and pass parameters to Stored Procedures or Functions. The following elements are available:

  • parameter
  • returning-resultset
  • sql-parameter-definition
  • poller

parameter

Provides a mechanism to provide Stored Procedure parameters. Parameters can be either static or provided using a SpEL Expressions. Optional.

<int-jdbc:parameter name=""    1
                    type=""    2
                    value=""/> 3

<int-jdbc:parameter name=""
                    expression=""/>4

1

The name of the parameter to be passed into the Stored Procedure or Stored Function. Required.

2

This attribute specifies the type of the value. If nothing is provided this attribute will default to java.lang.String. This attribute is only used when the value attribute is used. Optional.

3

The value of the parameter. You have to provider either this attribute or the expression attribute must be provided instead. Optional.

4

Instead of the value attribute, you can also specify a SpEL expression for passing the value of the parameter. If you specify the expression the value attribute is not allowed. Optional.

returning-resultset

Stored Procedures may return multiple resultsets. By setting one or more returning-resultset elements, you can specify RowMappers in order to convert each returned ResultSet to meaningful objects. Optional.

<int-jdbc:returning-resultset name="" row-mapper="" />

sql-parameter-definition

If you are using a database that is fully supported, you typically don't have to specify the Stored Procedure parameter definitions. Instead, those parameters can be automatically derived from the JDBC Meta-data. However, if you are using databases that are not fully supported, you must set those parameters explicitly using the sql-parameter-definition sub-element.

You can also choose to turn off any processing of parameter meta data information obtained via JDBC using the ignore-column-meta-data attribute.

<int-jdbc:sql-parameter-definition name=""         1
                                    direction="IN"  2
                                    type="STRING"   3
                                    scale=""/>      4

1

Specifies the name of the SQL parameter. Required.

2

Specifies the direction of the SQL parameter definition. Defaults to IN. Valid values are: IN, OUT and INOUT. If your procedure is returning ResultSets, please use the returning-resultset element. Optional.

3

The SQL type used for this SQL parameter definition. Will translate into the integer value as defined by java.sql.Types. Alternatively you can provide the integer value as well. If this attribute is not explicitly set, then it will default to 'VARCHAR'. Optional.

4

The scale of the SQL parameter. Only used for numeric and decimal parameters. Optional.

poller

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

17.5.5 Defining Parameter Sources

Parameter Sources govern the techniques of retrieving and mapping the Spring Integration Message properties to the relevant Stored Procedure input parameters. The Stored Procedure components follow certain rules.

By default bean properties of the passed in Message payload will be used as a source for the Stored Procedure's input parameters. In that case a BeanPropertySqlParameterSourceFactory will be used. This may be sufficient for basic use cases. The following example illustrates that default behavior.

[Important]Important
Please be aware that for the "automatic" lookup of bean properties using the BeanPropertySqlParameterSourceFactory to work, your bean properties must be defined in lower case. This is due to the fact that in org.springframework.jdbc.core.metadata.CallMetaDataContext (method matchInParameterValuesWithCallParameters()), the retrieved Stored Procedure parameter declarations are converted to lower case. As a result, if you have camel-case bean properties such as "lastName", the lookup will fail. In that case, please provide an explicit ProcedureParameter.

Let's assume we have a payload that consists of a simple bean with the following three properties: id, name and description. Furthermore, we have a simplistic Stored Procedure called INSERT_COFFEE that accepts three input parameters: id, name and description. We also use a fully supported database. In that case the following configuration for a Stored Procedure Oubound Adapter will be sufficient:

<int-jdbc:stored-proc-outbound-channel-adapter data-source="dataSource"
                                        channel="insertCoffeeProcedureRequestChannel"
                                        stored-procedure-name="INSERT_COFFEE"/>

For more sophisticated options consider passing in one or more ProcedureParameter.

If you do provide ProcedureParameter explicitly, then as default an ExpressionEvaluatingSqlParameterSourceFactory will be used for parameter processing in order to enable the full power of SpEL expressions.

Furthermore, if you need even more control over how parameters are retrieved, consider passing in a custom implementation of a SqlParameterSourceFactory using the sql-parameter-source-factory attribute.

17.5.6 Stored Procedure Inbound Channel Adapter

<int-jdbc:stored-proc-inbound-channel-adapter
                                   channel=""                                   1
                                   stored-procedure-name=""
                                   data-source=""
                                   auto-startup="true"
                                   id=""
                                   ignore-column-meta-data="false"
                                   is-function="false"
                                   max-rows-per-poll=""                         2
                                   skip-undeclared-results=""                   3
    <int:poller/>
    <int-jdbc:sql-parameter-definition name="" direction="IN"
                                               type="STRING"
                                               scale=""/>
    <int-jdbc:parameter name="" type="" value=""/>
    <int-jdbc:parameter name="" expression=""/>
    <int-jdbc:returning-resultset name="" row-mapper="" />
</int-jdbc:stored-proc-inbound-channel-adapter>

1

Channel to which polled messages will be sent. If the stored procedure or function does not return any data, the payload of the Message will be Null. Required.

2

Limits the number of rows extracted per query. Otherwise all rows are extracted into the outgoing message. Optional.

3

If this attribute is set to true, then all results from a stored procedure call that don't have a corresponding SqlOutParameter declaration will be bypassed.

E.g. Stored Procedures may return an update count value, even though your Stored Procedure only declared a single result parameter. The exact behavior depends on the used database. The value is set on the underlying JdbcTemplate.

Few developers will probably ever want to process update counts, thus the value defaults to true. Optional.

[Note]Note
When you declare a Poller, you may notice the Poller's max-messages-per-poll attribute. For information about how it relates to the max-rows-per-poll attribute of the Stored Procedure Inbound Channel Adapter, please see Section 17.1.2, “Max-rows-per-poll versus Max-messages-per-poll” for a thourough discussion. The meaning of the attributes is the same as for the JDBC Inbound Channel Adapter.

17.5.7 Stored Procedure Outbound Channel Adapter

<int-jdbc:stored-proc-outbound-channel-adapter channel=""                       1
                                               stored-procedure-name=""
                                               data-source=""
                                               auto-startup="true"
                                               id=""
                                               ignore-column-meta-data="false"
                                               order=""                         2
                                               return-value-required="false"    3
                                               sql-parameter-source-factory=""
                                               use-payload-as-parameter-source="">
    <int:poller fixed-rate=""/>
    <int-jdbc:sql-parameter-definition name=""/>
    <int-jdbc:parameter name=""/>

</int-jdbc:stored-proc-outbound-channel-adapter>

1

The receiving Message Channel of this endpoint. Required.

2

Specifies the order for invocation when this endpoint is connected as a subscriber to a channel. This is particularly relevant when that channel is using a failover dispatching strategy. It has no effect when this endpoint itself is a Polling Consumer for a channel with a queue. Optional.

3

Indicates whether this procedure's return value should be included. Optional.

17.5.8 Stored Procedure Outbound Gateway

<int-jdbc:stored-proc-outbound-gateway request-channel=""                       1
                                       stored-procedure-name=""
                                       data-source=""
                                   auto-startup="true"
                                   id=""
                                   ignore-column-meta-data="false"
                                   is-function="false"
                                   order=""
                                   reply-channel=""                             2
                                   reply-timeout=""                             3
                                   return-value-required="false"                4
                                   skip-undeclared-results=""                   5
                                   sql-parameter-source-factory=""
                                   use-payload-as-parameter-source="">
<int-jdbc:sql-parameter-definition name="" direction="IN"
                                   type=""
                                   scale="10"/>
<int-jdbc:sql-parameter-definition name=""/>
<int-jdbc:parameter name="" type="" value=""/>
<int-jdbc:parameter name="" expression=""/>
<int-jdbc:returning-resultset name="" row-mapper="" />

1

The receiving Message Channel of this endpoint. Required.

2

Message Channel to which replies should be sent, after receiving the database response. Optional.

3

Allows you to specify how long this gateway will wait for the reply message to be sent successfully before throwing an exception. Keep in mind that when sending to a DirectChannel, the invocation will occur in the sender's thread so the failing of the send operation may be caused by other components further downstream. By default the Gateway will wait indefinitely. The value is specified in milliseconds. Optional.

4

Indicates whether this procedure's return value should be included. Optional.

5

If the skip-undeclared-results attribute is set to true, then all results from a stored procedure call that don't have a corresponding SqlOutParameter declaration will be bypassed.

E.g. Stored Procedures may return an update count value, even though your Stored Procedure only declared a single result parameter. The exact behavior depends on the used database. The value is set on the underlying JdbcTemplate.

Few developers will probably ever want to process update counts, thus the value defaults to true. Optional.

17.5.9 Examples

In the following two examples we call Apache Derby Stored Procedures. The first procedure will call a Stored Procedure that returns a ResultSet, and using a RowMapper the data is converted into a domain object, which then becomes the Spring Integration message payload.

In the second sample we call a Stored Procedure that uses Output Parameters instead, in order to return data.

[Note]Note

Please have a look at the Spring Integration Samples project, located at https://github.com/SpringSource/spring-integration-samples

The project contains the Apache Derby example referenced here, as well as instruction on how to run it. The Spring Integration Samples project also provides an example using Oracle Stored Procedures.

In the first example, we call a Stored Procedure named FIND_ALL_COFFEE_BEVERAGES that does not define any input parameters but which returns a ResultSet.

In Apache Derby, Stored Procedures are implemented using Java. Here is the method signature followed by the corresponding Sql:

public static void findAllCoffeeBeverages(ResultSet[] coffeeBeverages)
            throws SQLException {
    ...
}
CREATE PROCEDURE FIND_ALL_COFFEE_BEVERAGES() \
PARAMETER STYLE JAVA LANGUAGE JAVA MODIFIES SQL DATA DYNAMIC RESULT SETS 1 \
EXTERNAL NAME 'org.springframework.integration.jdbc.storedproc.derby.DerbyStoredProcedures.findAllCoffeeBeverages';

In Spring Integration, you can now call this Stored Procedure using e.g. a stored-proc-outbound-gateway

<int-jdbc:stored-proc-outbound-gateway id="outbound-gateway-storedproc-find-all"
                                       data-source="dataSource"
                                       request-channel="findAllProcedureRequestChannel"
                                       expect-single-result="true"
                                       stored-procedure-name="FIND_ALL_COFFEE_BEVERAGES">
    <int-jdbc:returning-resultset name="coffeeBeverages"
        row-mapper="org.springframework.integration.support.CoffeBeverageMapper"/>
    </int-jdbc:stored-proc-outbound-gateway>

In the second example, we call a Stored Procedure named FIND_COFFEE that has one input parameter. Instead of returning a ResultSet, an output parameter is used:

public static void findCoffee(int coffeeId, String[] coffeeDescription)
            throws SQLException {
    ...
}
CREATE PROCEDURE FIND_COFFEE(IN ID INTEGER, OUT COFFEE_DESCRIPTION VARCHAR(200)) \
PARAMETER STYLE JAVA LANGUAGE JAVA EXTERNAL NAME \
'org.springframework.integration.jdbc.storedproc.derby.DerbyStoredProcedures.findCoffee';

In Spring Integration, you can now call this Stored Procedure using e.g. a stored-proc-outbound-gateway

<int-jdbc:stored-proc-outbound-gateway id="outbound-gateway-storedproc-find-coffee"
                                       data-source="dataSource"
                                       request-channel="findCoffeeProcedureRequestChannel"
                                       skip-undeclared-results="true"
                                       stored-procedure-name="FIND_COFFEE"
                                       expect-single-result="true">
    <int-jdbc:parameter name="ID" expression="payload" />
</int-jdbc:stored-proc-outbound-gateway>

18. JPA Support

Spring Integration's JPA (Java Persistence API) module provides components for performing various database operations using JPA. The following components are provided:

These components can be used to perform select, create, update and delete operations on the targeted databases by sending/receiving messages to them.

The JPA Inbound Channel Adapter lets you poll and retrieve (select) data from the database using JPA whereas the JPA Outbound Channel Adapter lets you create, update and delete entities.

Outbound Gateways for JPA can be used to persist entities to the database, yet allowing you to continue with the flow and execute further components downstream. Similarly, you can use an Outbound Gateway to retrieve entities from the database.

For example, you may use the Outbound Gateway, which receives a Message with a user Id as payload on its request channel, to query the database and retrieve the User entity and pass it downstream for further processing.

Recognizing these semantic differences, Spring Integration provides 2 separate JPA Outbound Gateways:

  • Retrieving Outbound Gateway

  • Updating Outbound Gateway

Functionality

All JPA components perform their respective JPA operations by using either one of the following:

  • Entity classes

  • Java Persistence Query Language (JPQL) for update, select and delete (inserts are not supported by JPQL)

  • Native Query

  • Named Query

In the following sections we will describe each of these components in more detail.

18.1 Supported Persistence Providers

The Spring Integration JPA support has been tested using the following persistence providers:

  • Hibernate

  • OpenJPA

  • EclipseLink

When using a persistence provider, please ensure that the provider is compatible with JPA 2.0.

18.2 Java Implementation

Each of the provided components will use the o.s.i.jpa.core.JpaExecutor class which in turn will use an implementation of the o.s.i.jpa.core.JpaOperations interface. JpaOperations operates like a typical Data Access Object (DAO) and provides methods such as find, persist, executeUpdate etc. For most use cases the provided default implementation o.s.i.jpa.core.DefaultJpaOperations should be sufficient. Nevertheless, you have the option to optionally specify your own implementation in case you require custom behavior.

For initializing a JpaExecutor you have to use one of 3 available constructors that accept one of:

  • EntityManagerFactory

  • EntityManager or

  • JpaOperations

[Note]Note
The XML Namespace Support described further below is also very flexible and provides configuration attributes for each JPA component to pass in an EntityManagerFactory, EntityManager or JpaOperations reference.

Java Configuration Example

The following example of a JPA Retrieving Outbound Gateway is configured purely through Java. In typical usage scenarios you will most likely prefer the XML Namespace Support described further below. However, the example illustrates how the classes are wired up. Understanding the inner workings can also be very helpful for debugging or customizing the individual JPA components.

First, we instantiate a JpaExecutor using an EntityManager as constructor argument. The JpaExecutor is then in return used as constructor argument for the o.s.i.jpa.outbound.JpaOutboundGateway and the JpaOutboundGateway will be passed as constructor argument into the EventDrivenConsumer.

<bean id="jpaExecutor" class="o.s.i.jpa.core.JpaExecutor">
	<constructor-arg name="entityManager" ref="entityManager"/