Spring Integration 2.0 to 2.1 Migration Guide

ghillert edited this page Feb 28, 2012 · 43 revisions

Spring Integration 2.0 to 2.1 Migration Guide

For reference see: https://jira.springsource.org/browse/INT-2324

This migration guide explicitly covers the changes between Spring Integration 2.0 to 2.1. For earlier versions please see: the Spring Integration 1.0 to 2.0 Migration Guide.



Spring Integration 2.1 now depends by default on Spring 3.0.7.RELEASE. However, Spring Integration will still work with Spring 3.0.5. Furthermore, Spring Integration has been tested with Spring 3.1.0.RELEASE as well.

Dependency Change Matrix

The following dependencies were updated between Spring Integration 2.0.5.RELEASE and 2.1:

Dependency Old Version New Version Notes
Apache Commons Net 2.0 3.0.1
Jackson 1.4.3 1.9.2
Spring 3.0.5.RELEASE 3.0.7.RELEASE*
Spring Security 3.0.5.RELEASE 3.1.0.RELEASE
Spring Web Services 2.0.2.RELEASE 2.0.3.RELEASE
Groovy 1.7.5 1.8.5
JSch 0.1.42 0.1.45
Mockito 1.8.4 1.9.0
Smack 3.1.0 3.2.1 One thing we've observed with upgrading to Smack 3.2.1 is that the default service name is no longer NULL. Its default value has changed to the name of the host (e.g. 'localhost')

These upgrades do not necessarily mean that a particular version is required. It only means that Spring Integration 2.1.GA builds on a particular version. In most cases previous version of a given API would still work. For example: Spring 3.0.5.RELEASE will still work.

The Spring Integration Twitter Module now uses Spring Social 1.0.1.RELEASE, instead of Twitter4j.

XML Schema Changes

Spring Integration 2.1 ships with an updated version 2.1 XML Schema. Users must make sure to use either version-less XML Spring Integration namespaces or to use the 2.1 XML namespace. If you try to use a Spring Integration 2.1 based application with the old 2.0 or 1.0 XML namespace, an exception will be thrown.

Example of a version-less Schema declaration:

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

Poller Changes

The following previously deprecated XML sub-elements were removed in Spring Integration 2.1:

  • cron-trigger - Please use the cron attribute instead.
  • interval-trigger - Please use one of the interval trigger attributes such as fixed-delay or fixed-rate.

Channel Changes

The dispatcher attribute is deprecated. Please use the dispatcher sub-element instead.

FTP and SFTP Module Changes

The cache-sessions XML attribute has been deprecated. Consider wrapping your SessionFactory in an instance of org.springframework.integration.file.remote.session.CachingSessionFactory instead.

HTTP Module Changes

For the inbound-channel-adapter the name XML attribute has been deprecated. Use the path attribute, if you want to specify the path. Alternatively, use the id attribute, if you simply want to identify this component.

Keep in mind that in order to use the path attribute of 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"/>

JMS Module Changes

The delivery-mode XML attribute is deprecated and may be removed in future Spring Integration versions. Please use the delivery-persistent XML attribute instead.

Mail Module

On the imap-idle-channel-adapter component, the task-executor attribute was removed.

XML Module

The xpath-selector element is deprecated as of Spring Integration 2.1. Please use an xpath-filter instead.

Removed Module

The spring-integration-httpinvoker module, which was deprecated in version 2.0, has been removed with Spring Integration 2.1.


XMPP Module

In org.springframework.integration.xmpp.core.AbstractXmppConnectionAwareEndpoint the setter setRequestChannel is deprecated and will be removed in future versions. Please use setOutputChannel instead.

In org.springframework.integration.xmpp.XmppHeaders the following 2 constants are deprecated:

  • Constant CHAT_TO is deprecated. Use the TO Header Constant instead.
  • Constant CHAT_THREAD_ID is deprecated. Use the **THREAD Header Constant instead.

Functional Changes


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 a MessageDeliveryException, if no channel was determined (or an attempt to send was not successful).

If you desire to drop messages silently simply set:


Other Router Changes

Anyone extending org.springframework.integration.router.AbstractMessageRouter might need to modify code, as there is a new subclass AbstractMappingMessageRouter, that encapsulates the channel mapping, and also renamed getChannelIdentifiers() to getChannelMappings(). That method is now only needed for mapping router extensions.

Routers that are not mapping routers (That do not extend org.springframework.integration.router.AbstractMappingMessageRouter), need to implement determineTargetChannels (returning null if the desire is to route to the discard channel).

Router Deprecations

The channel-resolver XML attribute has been deprecated and may be removed in a future version. However, please be aware that the underlying property on the org.springframework.integration.router.AbstractMappingMessageRouter is NOT deprecated. It is considered an infrastructural configuration option and as of 2.1. Therefore, it has only been deprecated as a configuration-driven attribute.


Handlers within a chain are no longer registered as beans, and therefore would not be exposed directly as MBeans (the chain is effectively a black box)

API Changes

org.springframework.integration.store.MessageGroupStore (JavaDoc)

Besides re-factoring its implementations there were some structural changes to the strategy itself:

Added methods

 * Returns the size of this MessageGroup
 * @param groupId
 int messageGroupSize(Object groupId);

 * Completes this MessageGroup. Completion of the MessageGroup generally means 
 * that this group should not be allowing any more mutating operation to be performed on it. 
 * For example any attempt to add/remove new Message form the group should not be allowed.
 void completeGroup(Object groupId);

 * Polls Message from this {@link MessageGroup} (in FIFO style if supported by the implementation)
 * while also removing the polled {@link Message}
 Message<?> pollMessageFromGroup(Object groupId);

 * Allows you to set the sequence number of the last released Message. Used for Resequencing use cases
 * @param sequenceNumber
 void setLastReleasedSequenceNumberForGroup(Object groupId, int sequenceNumber);
Removed Methods
 int getMarkedMessageCountForAllMessageGroups();

 MessageGroup markMessageGroup(MessageGroup group);

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

The removed methods are no longer needed since they were only used to maintain the state of the MessageGroup in the resequencer case where released messages were marked. Later we realized that we only need to keep the sequence number of the last message, hence the added method setLastReleasedSequenceNumberForGroup(int)

org.springframework.integration.store.MessageGroup (JavaDoc)

Besides re-factoring its implementations there were some structural changes to the strategy itself

Added methods
* @return the timestamp (milliseconds since epoch) associated with the time this group was last updated
long getLastModified();

* Sets the complete flag for this message group
void complete();

Removed methods

Collection<Message<?>> getUnmarked();

Collection<Message<?>> getMarked();

org.springframework.integration.file.remote.session.Session (JavaDoc)

Besides re-factoring its implementations there were some structural changes to the strategy itself

Added methods

* Validates if path exists in the file system
boolean exists(String path) throws IOException;

Changed methods

the previous method would return void

* Creates new directory 
boolean mkdir(String directory) throws IOException;

Also, org.springframework.integration.file.remote.session.Session is now parameterized:

public interface Session<T> {
 . . .

Aggregator and Resequencer refactoring

In previous versions of Spring Integration both Aggregator and Resequencer were implemented by org.springframework.integration.aggregator.CorrelatingMessageHandler. Since version 2.1 org.springframework.integration.aggregator.CorrelatingMessageHandler was turned into an abstract class:

and we introduced two new subclasses:

to support some of the more advanced use cases described in EIP (e.g., unbounded resequencer, aggregator receiving messages correlated to the group that has already been released etc.)

This effort also resulted in a few new attributes added to both aggregator and resequencer elements:

expire-groups-upon-completion (only aggregator) - Boolean flag specifying if MessageGroup should be removed once completed. Useful for handling late arrival use cases where messages arriving with the correlationKey that is the same as the completed MessageGroup will be discarded. Default is 'false'

Web Services Module

Removed Class

This class was removed in Spring Integration 2.1. It is no longer necessary, since constructors were added that take a URI directly as a String, and previously it had been used simply as a way to pass a "static" URI via the DestinationProvider strategy.

The reason that those constructors were added is that we also now (as of 2.1) support "URI variables" to replace {placeholder} values within the URI at runtime with content taken from the Message payload or headers.