[[migration-2.2-3.0]]
=== Changes Between 2.2 and 3.0

See the https://github.com/spring-projects/spring-integration/wiki/Spring-Integration-2.2-to-3.0-Migration-Guide[Migration Guide] for important changes that might affect your applications.
You can find migration guides for all versions back to 2.1 on the https://github.com/spring-projects/spring-integration/wiki[wiki].

[[x3.0-new-components]]
==== New Components

Version 3.0 added a number of new components.

[[x3.0-request-mapping]]
===== HTTP Request Mapping

The HTTP module now provides powerful request mapping support for inbound endpoints.
We replaced the `UriPathHandlerMapping` class with `IntegrationRequestMappingHandlerMapping`, which is registered under the bean name of `integrationRequestMappingHandlerMapping` in the application context.
Upon parsing of the HTTP inbound endpoint, either a new `IntegrationRequestMappingHandlerMapping` bean is registered or an existing bean is reused.
To achieve flexible request mapping configuration, Spring Integration provides the `<request-mapping/>` child element for `<http:inbound-channel-adapter/>` and the `<http:inbound-gateway/>`.
Both HTTP inbound endpoints are now fully based on the request mapping infrastructure that was introduced with Spring MVC 3.1.
For example, multiple paths are supported on a single inbound endpoint.
For more information see <<./http.adoc#http-namespace,HTTP Namespace Support>>.

[[x3.0-spel-customization]]
===== Spring Expression Language (SpEL) Configuration

We added a new `IntegrationEvaluationContextFactoryBean` to allow configuration of custom `PropertyAccessor` implementations and functions for use in SpEL expressions throughout the framework.
For more information, see <<./spel.adoc#spel,Spring Expression Language (SpEL)>>.

[[x3.0-spel-functions]]
===== SpEL Functions Support

To customize the SpEL `EvaluationContext` with static `Method` functions, we introduced the `<spel-function/>` component.
We also added two built-in functions: `#jsonPath` and `#xpath`.
For more information, see <<./spel.adoc#spel-functions,SpEL Functions>>.

[[x3.0-spel-property-accessors]]
===== SpEL PropertyAccessors Support

To customize the SpEL `EvaluationContext` with `PropertyAccessor` implementations, we added the `<spel-property-accessors/>` component.
For more information, see <<./spel.adoc#spel-property-accessors,Property Accessors>>.

[[x3.0-redis-new-components]]
===== Redis: New Components

We added a new Redis-based https://docs.spring.io/spring-integration/api/org/springframework/integration/metadata/MetadataStore.html[`MetadataStore`] implementation.
You can use the `RedisMetadataStore` to maintain the state of a `MetadataStore` across application restarts.
This new `MetadataStore` implementation can be used with adapters, such as:

* Twitter inbound adapters
* Feed inbound channel adapter

We added new queue-based components.
We added the `<int-redis:queue-inbound-channel-adapter/>` and `<int-redis:queue-outbound-channel-adapter/>` components to perform 'right pop' and 'left push' operations, respectively, on a Redis List.

For more information, "`see <<./redis.adoc#redis,Redis Support>>`".

[[x3.0-hcr]]
===== Header Channel Registry

You can now instruct the framework to store reply channels and error channels in a registry for later resolution.
This is useful for cases where the `replyChannel` or `errorChannel` might be lost (for example, when serializing a message).
See <<./content-enrichment.adoc#header-enricher,Header Enricher>> for more information.

[[x3.0-configurable-mongo-MS]]
===== MongoDB support: New `ConfigurableMongoDbMessageStore`

In addition to the existing `eMongoDbMessageStore`, we introduced a new `ConfigurableMongoDbMessageStore`.
This provides a more robust and flexible implementation of `MessageStore` for MongoDB.
It does not have backward compatibility with the existing store, but we recommend using it for new applications.
Existing applications can use it, but messages in the old store are not available.
See <<./mongodb.adoc#mongodb,MongoDb Support>> for more information.

[[x3.0-syslog]]
===== Syslog Support

Building on the 2.2 `SyslogToMapTransformer`, Spring Integration 3.0 introduces `UDP` and `TCP` inbound channel adapters especially tailored for receiving SYSLOG messages.
For more information, see <<./syslog.adoc#syslog,Syslog Support>>.

[[x3.0-tail]]
===== `tail` Support

We added file inbound channel adapters that use the `tail` command to generate messages when lines are added to the end of text files.
See <<./file.adoc#file-tailing,'tail'ing Files>>.

[[x3.0-jmx]]
===== JMX Support

We added `<int-jmx:tree-polling-channel-adapter/>`.
This adapter queries the JMX MBean tree and sends a message with a payload that is the graph of objects that match the query.
By default, the MBeans are mapped to primitives and simple Objects (such as `Map`, `List`, and arrays).
It permits simple transformation to, for example, JSON.

The `IntegrationMBeanExporter` now allows the configuration of a custom `ObjectNamingStrategy` by using the `naming-strategy` attribute.

For more information, see <<./jmx.adoc#jmx,JMX Support>>.

[[x3.0-tcp-events]]
===== TCP/IP Connection Events and Connection Management

`TcpConnection` instances now emit `ApplicationEvent` instances (specifically `TcpConnectionEvent` instances) when connections are opened or closed or when an exception occurs.
This change lets applications be informed of changes to TCP connections by using the normal Spring `ApplicationListener` mechanism.

We renamed `AbstractTcpConnection` to `TcpConnectionSupport`.
Custom connections that are subclasses of this class can use its methods to publish events.
Similarly, we renamed `AbstractTcpConnectionInterceptor` to `TcpConnectionInterceptorSupport`.

In addition, we added `<int-ip:tcp-connection-event-inbound-channel-adapter/>`.
By default, this adapter sends all `TcpConnectionEvent` instances to a `Channel`.

Further, the TCP connection factories now provide a new method called `getOpenConnectionIds()`, which returns a list of identifiers for all open connections.
It lets applications broadcast to all open connections, among other uses.

Finally, the connection factories also provide a new method called `closeConnection(String connectionId)`, which lets applications explicitly close a connection by using its ID.

For more information see <<./ip.adoc#tcp-events,TCP Connection Events>>.

[[x3.0-inbound-script]]
===== Inbound Channel Adapter Script Support

The `<int:inbound-channel-adapter/>` now supports using `<expression/>` and `<script/>` child elements to create a `MessageSource`.
See <<./channel-adapter.adoc#channel-adapter-expressions-and-scripts,Channel Adapter Expressions and Scripts>>.

[[x3.0-content-enricher-headers]]
===== Content Enricher: Headers Enrichment Support

The content enricher now provides configuration for `<header/>` child elements, to enrich the outbound message with headers based on the reply message from the underlying message flow.
For more information see <<./content-enrichment.adoc#payload-enricher,Payload Enricher>>.

[[x3.0-general]]
==== General Changes

This section describes general changes from version 2.2 to version 3.0.

[[x3.0-message-id]]
===== Message ID Generation

Previously, message IDs were generated by using the JDK `UUID.randomUUID()` method.
With this release, the default mechanism has been changed to use a more efficient and significantly faster algorithm.
In addition, we added the ability to change the strategy used to generate message IDs.
For more information see <<./message.adoc#message-id-generation,Message ID Generation>>.

[[x3.0-gateway]]
===== "`<gateway>`" Changes

You can now set common headers across all gateway methods, and we added more options for adding information to the message about which method was invoked.

You can now entirely customize the way that gateway method calls are mapped to messages.

The `GatewayMethodMetadata` is now a public class.
It lets you programmatically configure the `GatewayProxyFactoryBean` from Java.

For more information, see <<./gateway.adoc#gateway,Messaging Gateways>>.

[[x3.0-http-endpointss]]
===== HTTP Endpoint Changes

* *Outbound Endpoint `encode-uri`*: `<http:outbound-gateway/>` and `<http:outbound-channel-adapter/>` now provide an `encode-uri` attribute to allow disabling the encoding of the URI object before sending the request.

* *Inbound Endpoint `merge-with-default-converters`*: `<http:inbound-gateway/>` and `<http:inbound-channel-adapter/>` now have a `merge-with-default-converters` attribute to include the list of default `HttpMessageConverter` instances after the custom message converters.

* *`If-Modified-Since` and `If-Unmodified-Since` HTTP Headers*: Previously, the `If-Modified-Since` and `If-Unmodified-Since` HTTP headers were incorrectly processed within from and to HTTP headers mapped in the `DefaultHttpHeaderMapper`.
Now, in addition to correcting that issue, `DefaultHttpHeaderMapper` provides date parsing from formatted strings for any HTTP headers that accept date-time values.

* *Inbound Endpoint Expression Variables*: In addition to the existing `#requestParams` and `#pathVariables`, the `<http:inbound-gateway/>` and `<http:inbound-channel-adapter/>` now support additional useful variables: `#matrixVariables`, `#requestAttributes`, `#requestHeaders`, and `#cookies`.
These variables are available in both payload and header expressions.

* *Outbound Endpoint 'uri-variables-expression'*: HTTP outbound endpoints now support the `uri-variables-expression` attribute to specify an `Expression` to evaluate a `Map` for all URI variable placeholders within URL template.
This allows selection of a different map of expressions based on the outgoing message.

For more information, see <<./http.adoc#http,HTTP Support>>.

[[x3.0-json-transformers]]
===== Jackson Support (JSON)

* A new abstraction for JSON conversion has been introduced.
Implementations for Jackson 1.x and Jackson 2 are currently provided, with the version being determined by presence on the classpath.
Previously, only Jackson 1.x was supported.

* The `ObjectToJsonTransformer` and `JsonToObjectTransformer` now emit/consume headers containing type information.

For more information, see "`JSON Transformers`" in <<./transformer.adoc#transformer,Transformer>>.

[[x3.0-id-for-chain-sub-components]]
===== Chain Elements `id` Attribute

Previously, the `id` attribute for elements within a `<chain>` was ignored and, in some cases, disallowed.
Now, the `id` attribute is allowed for all elements within a `<chain>`.
The bean names of chain elements is a combination of the surrounding chain's `id` and the `id` of the element itself.
For example: 'myChain$child.myTransformer.handler'.
For more information see, <<./chain.adoc#chain,Message Handler Chain>>.

[[x3.0-corr-endpoint-empty-groups]]
===== Aggregator 'empty-group-min-timeout' property

The `AbstractCorrelatingMessageHandler` provides a new property called `empty-group-min-timeout` to allow empty group expiry to run on a longer schedule than expiring partial groups.
Empty groups are not removed from the `MessageStore` until they have not been modified for at least this number of milliseconds.
For more information, see <<./aggregator.adoc#aggregator-xml,Configuring an Aggregator with XML>>.

[[x3.0-filelistfilter]]
===== Persistent File List Filters (file, (S)FTP)

New `FileListFilter` implementations that use a persistent `MetadataStore` are now available.
You can use these to prevent duplicate files after a system restart.
See <<./file.adoc#file-reading,Reading Files>>, <<./ftp.adoc#ftp-inbound,FTP Inbound Channel Adapter>>, and <<./sftp.adoc#sftp-inbound,SFTP Inbound Channel Adapter>> for more information.

[[x3.0-scripting-variables]]
===== Scripting Support: Variables Changes

We introduced a new `variables` attribute for scripting components.
In addition, variable bindings are now allowed for inline scripts.
See <<./groovy.adoc#groovy,Groovy support>> and <<./scripting.adoc#scripting,Scripting Support>> for more information.

[[x3.0-direct-channel-lb-ref]]
===== Direct Channel Load Balancing configuration

Previously, when configuring `LoadBalancingStrategy` on the channel's `dispatcher` child element, the only available option was to use a pre-defined enumeration of values which did not let developers set a custom implementation of the `LoadBalancingStrategy`.
You can now use `load-balancer-ref` to provide a reference to a custom implementation of the `LoadBalancingStrategy`.
For more information, see <<./channel.adoc#channel-implementations-directchannel,`DirectChannel`>>.

[[x3.0-pub-sub]]
===== PublishSubscribeChannel Behavior

Previously, sending to a <publish-subscribe-channel/> that had no subscribers would return a `false` result.
If used in conjunction with a `MessagingTemplate`, this would result in an exception being thrown.
Now, the `PublishSubscribeChannel` has a property called `minSubscribers` (default: `0`).
If the message is sent to at least the minimum number of subscribers, the send operation is deemed to be successful (even if the number is zero).
If an application expects to get an exception under these conditions, set the minimum subscribers to at least 1.

[[x3.0--s-ftp-changes]]
===== FTP, SFTP and FTPS Changes

The FTP, SFTP and FTPS endpoints no longer cache sessions by default.

We removed the deprecated `cached-sessions` attribute from all endpoints.
Previously, the embedded caching mechanism controlled by this attribute's value did not provide a way to limit the size of the cache, which could grow indefinitely.
Release 2.1 introduced `CachingConnectionFactory`, and it became the preferred (and is now the only) way to cache sessions.

`CachingConnectionFactory` now provides a new method: `resetCache()`.
This method immediately closes idle sessions and causes in-use sessions to be closed as and when they are returned to the cache.

The `DefaultSftpSessionFactory` (in conjunction with a `CachingSessionFactory`) now supports multiplexing channels over a single SSH connection (SFTP Only).

====== FTP, SFTP and FTPS Inbound Adapters

Previously, there was no way to override the default filter used to process files retrieved from a remote server.
The `filter` attribute determines which files are retrieved, but the `FileReadingMessageSource` uses an `AcceptOnceFileListFilter`.
This means that, if a new copy of a file is retrieved with the same name as a previously copied file, no message was sent from the adapter.

With this release, a new attribute `local-filter` lets you override the default filter (for example, with an `AcceptAllFileListFilter` or some other custom filter).

If you want the behavior of the `AcceptOnceFileListFilter` to be maintained across JVM executions, you can now configure a custom filter that retains state, perhaps on the file system.

Inbound channel adapters now support the `preserve-timestamp` attribute, which sets the local file modified timestamp to the timestamp from the server (default: `false`).

====== FTP, SFTP, and FTPS Gateways

The gateways now support the `mv` command, enabling the renaming of remote files.

The gateways now support recursive `ls` and `mget` commands, enabling the retrieval of a remote file tree.

The gateways now support `put` and `mput` commands, enabling sending files to the remote server.

The `local-filename-generator-expression` attribute is now supported, enabling the naming of local files during retrieval.
By default, the same name as the remote file is used.

The `local-directory-expression` attribute is now supported, enabling the naming of local directories during retrieval (based on the remote directory).

====== Remote File Template

A new higher-level abstraction (`RemoteFileTemplate`) is provided over the `Session` implementations used by the FTP and SFTP modules.
While it is used internally by endpoints, you can also use this abstraction programmatically.
Like all Spring `*Template` implementations, it reliably closes the underlying session while allowing low level access to the session.

For more information, see <<./ftp.adoc#ftp,FTP/FTPS Adapters>> and <<./sftp.adoc#sftp,SFTP Adapters>>.

[[x3.0-outbound-gateway-requires-reply]]
===== 'requires-reply' Attribute for Outbound Gateways

All outbound gateways (such as `<jdbc:outbound-gateway/>` or `<jms:outbound-gateway/>`) are designed for 'request-reply' scenarios.
A response is expected from the external service and is published to the `reply-channel` or the `replyChannel` message header.
However, there are some cases where the external system might not always return a result (for example,
a `<jdbc:outbound-gateway/>` when a SELECT ends with an empty `ResultSet` or perhaps a one-way web service).
Consequently, developers needed an option to configure whether or not a reply is required.
For this purpose, we introduced the `requires-reply` attribute for outbound gateway components.
In most cases, the default value for `requires-reply` is `true`.
If there is no result, a `ReplyRequiredException` is thrown.
Changing the value to `false` means that, if an external service does not return anything, the message flow ends at that point, similar to an outbound channel adapter.

NOTE: The WebService outbound gateway has an additional attribute called `ignore-empty-responses`.
It is used to treat an empty `String` response as if no response were received.
By default, it is `true`, but you can set it to `false` to allow the application to receive an empty `String` in the reply message payload.
When the attribute is `true`, an empty string is treated as no response for the purposes of the `requires-reply` attribute.
By default, `requires-reply` is false for the WebService outbound gateway.

Note that the `requiresReply` property was previously present but set to `false` in the `AbstractReplyProducingMessageHandler`, and there was no way to configure it on outbound gateways by using the XML namespace.

IMPORTANT: Previously, a gateway receiving no reply would silently end the flow (with a DEBUG log message).
By default, with this change, an exception is now thrown by most gateways.
To revert to the previous behavior, set `requires-reply` to `false`.

[[x3.0-amqp-mapping]]
===== AMQP Outbound Gateway Header Mapping

Previously, the <int-amqp:outbound-gateway/> mapped headers before invoking the message converter, and the converter could overwrite headers such as `content-type`.
The outbound adapter maps the headers after the conversion, which means headers like `content-type` from the outbound `Message` (if present) are used.

Starting with this release, the gateway now maps the headers after the message conversion, consistent with the adapter.
If your application relies on the previous behavior (where the converter's headers overrode the mapped headers), you either need to filter those headers (before the message reaches the gateway) or set them appropriately.
The headers affected by the `SimpleMessageConverter` are `content-type` and `content-encoding`.
Custom message converters may set other headers.

[[x3.0-stored-proc-sql-return-type]]
===== Stored Procedure Components Improvements

For more complex database-specific types not supported by the standard `CallableStatement.getObject` method, we introduced two new additional attributes to the `<sql-parameter-definition/>` element with OUT-direction:

* `type-name`
* `return-type`

The `row-mapper` attribute of the stored procedure inbound channel adapter `<returning-resultset/>` child element now supports a reference to a `RowMapper` bean definition.
Previously, it contained only a class name (which is still supported).

For more information, see <<./jdbc.adoc#stored-procedures,Stored Procedures>>.

[[x3.0-ws-outbound-uri-substitution]]
===== Web Service Outbound URI Configuration

The web service outbound gateway 'uri' attribute now supports `<uri-variable/>` substitution for all URI schemes supported by Spring Web Services.
For more information, see <<./ws.adoc#outbound-uri,Outbound URI Configuration>>.

[[x3.0-redis]]
===== Redis Adapter Changes

The Redis inbound channel adapter can now use a `null` value for the `serializer` property, with the raw data being the message payload.

The Redis outbound channel adapter now has the `topic-expression` property to determine the Redis topic for the `Message` at runtime.

The Redis inbound channel adapter, in addition to the existing `topics` attribute, now has the `topic-patterns` attribute.

For more information, see <<./redis.adoc#redis,Redis Support>>.

[[x3.0-advising-filters]]
===== Advising Filters

Previously, when a `<filter/>` had a `<request-handler-advice-chain/>`, the discard action was all performed within the scope of the advice chain (including any downstream flow on the `discard-channel`).
The filter element now has an attribute called `discard-within-advice` (default: `true`) to allow the discard action to be performed after the advice chain completes.
See <<./handler-advice.adoc#advising-filters,Advising Filters>>.

[[x3.0-annotation-advice]]
===== Advising Endpoints using Annotations

Request handler advice chains can now be configured using annotations.
See <<./handler-advice.adoc#advising-with-annotations,Advising Endpoints Using Annotations>>.

[[x3.0-o-t-s-t]]
===== ObjectToStringTransformer Improvements

This transformer now correctly transforms `byte[]` and `char[]` payloads to `String`.
For more information, see <<./transformer.adoc#transformer,Transformer>>.

[[x3.0-jpa-changes]]
===== JPA Support Changes

Payloads to persist or merge can now be of type `https://docs.oracle.com/javase/7/docs/api/java/lang/Iterable.html[java.lang.Iterable]`.

In that case, each object returned by the `Iterable` is treated as an entity and persisted or merged by using the underlying `EntityManager`.
Null values returned by the iterator are ignored.

The JPA adapters now have additional attributes to optionally flush and clear entities from the associated persistence context after performing persistence operations.

Retrieving gateways had no mechanism to specify the first record to be retrieved, which is a common use case.
The retrieving gateways now support specifying this parameter by adding the `first-result` and `first-result-expression` attributes to the gateway definition.
For more information, see <<./jpa.adoc#jpa-retrieving-outbound-gateway,Retrieving Outbound Gateway>>.

The JPA retrieving gateway and inbound adapter now have an attribute to specify the maximum number of results in a result set as an expression.
In addition, we introduced the `max-results` attribute to replace `max-number-of-results`, which has been deprecated.
`max-results` and `max-results-expression` are used to provide the maximum number of results or an expression to compute the maximum number of results, respectively, in the result set.

For more information, see <<./jpa.adoc#jpa,JPA Support>>.

[[x3.0-dalay-expression]]
===== Delayer: delay expression

Previously, the `<delayer>` provided a `delay-header-name` attribute to determine the delay value at runtime.
In complex cases, the `<delayer>` had to be preceded with a `<header-enricher>`.
Spring Integration 3.0 introduced the `expression` attribute and `expression` child element for dynamic delay determination.
The `delay-header-name` attribute is now deprecated, because you can specify the header evaluation in the `expression`.
In addition, we introduced the `ignore-expression-failures` to control the behavior when an expression evaluation fails.
For more information, see <<./delayer.adoc#delayer,Delayer>>.

[[x3.0-jdbc-mysql-v5_6_4]]
===== JDBC Message Store Improvements

Spring Integration 3.0 adds a new set of DDL scripts for MySQL version 5.6.4 and higher.
Now MySQL supports fractional seconds and is thus improving the FIFO ordering when polling from a MySQL-based message store.
For more information, see <<./jdbc.adoc#jdbc-message-store-generic,The Generic JDBC Message Store>>.

[[x3.0-event-for-imap-idle]]
===== IMAP Idle Connection Exceptions

Previously, if an IMAP idle connection failed, it was logged, but there was no mechanism to inform an application.
Such exceptions now generate `ApplicationEvent` instances.
Applications can obtain these events by using an `<int-event:inbound-channel-adapter>` or any `ApplicationListener` configured to receive an `ImapIdleExceptionEvent` (or one of its super classes).

[[x3.0-tcp-headers]]
===== Message Headers and TCP

The TCP connection factories now enable the configuration of a flexible mechanism to transfer selected headers (as well as the payload) over TCP.
A new `TcpMessageMapper` enables the selection of the headers, and you need to configure an appropriate serializer or deserializer to write the resulting `Map` to the TCP stream.
We added a `MapJsonSerializer` as a convenient mechanism to transfer headers and payload over TCP.
For more information, see <<./ip.adoc#ip-headers,Transferring Headers>>.

[[x3.0-jms-mdca-te]]
===== JMS Message Driven Channel Adapter

Previously, when configuring a `<message-driven-channel-adapter/>`, if you wished to use a specific `TaskExecutor`, you had to declare a container bean and provide it to the adapter by setting the `container` attribute.
We added the `task-executor`, letting it be set directly on the adapter.
This is in addition to several other container attributes that were already available.

[[x3.0-rmi-ec]]
===== RMI Inbound Gateway

The RMI Inbound Gateway now supports an `error-channel` attribute.
See <<./rmi.adoc#rmi-inbound,Inbound RMI>>.

[[x3.0-xslt-transformer]]
===== `XsltPayloadTransformer`

You can now specify the transformer factory class name by setting the `transformer-factory-class` attribute.
See `<<./xml.adoc#xml-xslt-payload-transformers,XsltPayloadTransformer>>`.
