[[migration-4.1-4.2]]
= Changes between 4.1 and 4.2

See the https://github.com/spring-projects/spring-integration/wiki/Spring-Integration-4.1-to-4.2-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].

[[x4.2-new-components]]
== New Components

Version 4.2 added a number of new components.

[[x4.2-JMX]]
=== Major Management/JMX Rework

We added a new `MetricsFactory` strategy interface.
This change, together with other changes in the JMX and management infrastructure, provides much more control over management configuration and runtime performance.

However, this has some important implications for (some) user environments.

For complete details, see xref:metrics.adoc[Metrics and Management] and xref:jmx.adoc#jmx-42-improvements[JMX Improvements].

[[x4.2-mongodb-metadata-store]]
=== MongoDB Metadata Store

The `MongoDbMetadataStore` is now available.
For more information, see xref:mongodb.adoc#mongodb-metadata-store[MongoDB Metadata Store].

[[x4.2-secured-channel-annotation]]
=== SecuredChannel Annotation

We introduced the `@SecuredChannel` annotation, replacing the deprecated `ChannelSecurityInterceptorFactoryBean`.
For more information, see xref:security.adoc[Security in Spring Integration].

[[x4.2-security-context-propagation]]
=== `SecurityContext` Propagation

We introduced the `SecurityContextPropagationChannelInterceptor` for the `SecurityContext` propagation from one message flow's thread to another.
For more information, see xref:security.adoc[Security in Spring Integration].


[[x4.2-file-splitter]]
=== FileSplitter

In 4.1.2, we added `FileSplitter`, which splits text files into lines.
It now has full support in the `int-file:` namespace.
See xref:file/splitter.adoc[File Splitter] for more information.

[[x4.2-zk]]
=== Zookeeper Support

We added Zookeeper support to the framework to assist when running on a clustered or multi-host environment.
The change impacts the following features:

* `ZookeeperMetadataStore`
* `ZookeeperLockRegistry`
* Zookeeper Leadership

See xref:zookeeper.adoc[Zookeeper Support] for more information.

[[x4.2-barrier]]
=== Thread Barrier

A new thread `<int:barrier/>` component is available, letting a thread be suspended until some asynchronous event occurs.
See xref:barrier.adoc[Thread Barrier] for more information.

[[x4.2-stomp]]
=== STOMP Support

We added STOMP support to the framework as an inbound and outbound channel adapters pair.
See xref:stomp.adoc[STOMP Support] for more information.

[[x4.2-codec]]
=== Codec
A new `Codec` abstraction has been introduced, to encode and decode objects to and from `byte[]`.
We added an implementation that uses Kryo.
We also added codec-based transformers and message converters.
See xref:codec.adoc[Codec] for more information.

[[x4.2-prepared-statement-setter]]
=== Message PreparedStatement Setter

A new `MessagePreparedStatementSetter` functional interface callback is available for the `JdbcMessageHandler` (`<int-jdbc:outbound-gateway>` and `<int-jdbc:outbound-channel-adapter>`) as an alternative to using `SqlParameterSourceFactory` to populate parameters on the `PreparedStatement` with the `requestMessage` context.
See xref:jdbc/outbound-channel-adapter.adoc[Outbound Channel Adapter] for more information.

[[x4.2-general]]
== General Changes

This section describes general changes from version 4.1 to version 4.2.

[[x4.2-wire-tap]]
=== WireTap

As an alternative to the existing `selector` attribute, the `<wire-tap/>` element now supports the `selector-expression` attribute.

[[x4.2-file-changes]]
=== File Changes

See xref:file.adoc[File Support] for more information about these changes.

[[appending-new-lines]]
==== Appending New Lines

The `<int-file:outbound-channel-adapter>` and `<int-file:outbound-gateway>` now support an `append-new-line` attribute.
If set to `true`, a new line is appended to the file after a message is written.
The default attribute value is `false`.

[[ignoring-hidden-files]]
==== Ignoring Hidden Files

We added the `ignore-hidden` attribute for the `<int-file:inbound-channel-adapter>` to let you set whether to pick up hidden files from the source directory.
It defaults to `true`.

[[writing-inputstream-payloads]]
==== Writing `InputStream` Payloads

The `FileWritingMessageHandler` now also accepts `InputStream` as a valid message payload type.

[[headdirectoryscanner]]
==== `HeadDirectoryScanner`

You can now use the `HeadDirectoryScanner` with other `FileListFilter` implementations.

[[last-modified-filter]]
==== Last Modified Filter

We added the `LastModifiedFileListFilter`.

[[watch-service-directory-scanner]]
==== Watch Service Directory Scanner

We added the `WatchServiceDirectoryScanner`.

[[persistent-file-list-filter-changes]]
==== Persistent File List Filter Changes

The `AbstractPersistentFileListFilter` has a new property (`flushOnUpdate`) which, when set to `true`, calls `flush()` on the metadata store if it implements `Flushable` (for example, `PropertiesPersistingMetadataStore`).

[[x4.2-class-package-change]]
=== Class Package Change

We moved the `ScatterGatherHandler` class from the `org.springframework.integration.handler` to the `org.springframework.integration.scattergather`.

[[tcp-changes]]
=== TCP Changes

This section describes general changes to the Spring Integration TCP functionality.

[[x4.2-tcp-serializers]]
==== TCP Serializers

The TCP `Serializers` no longer `flush()` the `OutputStream`.
This is now done by the `TcpNxxConnection` classes.
If you use the serializers directly within your code, you may have to `flush()` the `OutputStream`.

[[x4.2-tcp-server-exceptions]]
==== Server Socket Exceptions

`TcpConnectionServerExceptionEvent` instances are now published whenever an unexpected exception occurs on a TCP server socket (also added to 4.1.3 and 4.0.7).
See xref:changes-4.1-4.2.adoc#x4.2-tcp-events[TCP Connection Events] for more information.

[[x4.2-tcp-server-port]]
==== TCP Server Port

If you configure a TCP server socket factory to listen on a random port, you can now obtain the actual port chosen by the OS by using `getPort()`.
`getServerSocketAddress()` is also available.

See "xref:ip/tcp-connection-factories.adoc[TCP Connection Factories]" for more information.

[[x4.2-tcp-gw-rto]]
==== TCP Gateway Remote Timeout

The `TcpOutboundGateway` now supports `remote-timeout-expression` as an alternative to the existing `remote-timeout` attribute.
This allows setting the timeout based on each message.

Also, the `remote-timeout` no longer defaults to the same value as `reply-timeout`, which has a completely different meaning.

See xref:ip/endpoint-reference.adoc#tcp-ob-gateway-attributes[.TCP Outbound Gateway Attributes] for more information.

[[x4.2-tcp-ssl]]
==== TCP SSLSession Available for Header Mapping

`TcpConnection` implementations now support `getSslSession()` to let you extract information from the session to add to message headers.
See xref:ip/msg-headers.adoc[IP Message Headers] for more information.

[[x4.2-tcp-events]]
==== TCP Events

New events are now published whenever a correlation exception occurs -- such as sending a message to a non-existent socket.

The `TcpConnectionEventListeningMessageProducer` is deprecated.
Use the generic event adapter instead.

See xref:changes-4.1-4.2.adoc#x4.2-tcp-events[TCP Connection Events] for more information.

[[x4.2-inbound-channel-adapter-annotation]]
=== `@InboundChannelAdapter` Changes

Previously, the `@Poller` on an inbound channel adapter defaulted the `maxMessagesPerPoll` attribute to `-1` (infinity).
This was inconsistent with the XML configuration of `<inbound-channel-adapter/>`, which defaults to `1`.
The annotation now defaults this attribute to `1`.

[[x4.2-api-changes]]
=== API Changes

`o.s.integration.util.FunctionIterator` now requires a `o.s.integration.util.Function` instead of a `reactor.function.Function`.
This was done to remove an unnecessary hard dependency on Reactor.
Any uses of this iterator need to change the import.

Reactor is still supported for functionality such as the `Promise` gateway.
The dependency was removed for those users who do not need it.

[[x4.2-jms-changes]]
=== JMS Changes

This section describes general changes to the Spring Integration TCP functionality.

[[reply-listener-lazy-initialization]]
==== Reply Listener Lazy Initialization

You can now configure the reply listener in JMS outbound gateways to be initialized on-demand and stopped after an idle period, instead of being controlled by the gateway's lifecycle.
See xref:jms.adoc#jms-outbound-gateway[Outbound Gateway] for more information.

[[conversion-errors-in-message-driven-endpoints]]
==== Conversion Errors in Message-Driven Endpoints

The `error-channel` is now used for the conversion errors.
In previous versions, they caused transaction rollback and message redelivery.

See xref:changes-2.2-3.0.adoc#x3.0-jms-mdca-te[Message-driven Channel Adapter] and xref:jms.adoc#jms-inbound-gateway[Inbound Gateway] for more information.

[[default-acknowledge-mode]]
==== Default Acknowledge Mode

When using an implicitly defined `DefaultMessageListenerContainer`, the default `acknowledge` is now `transacted`.
We recommend using `transacted` when using this container, to avoid message loss.
This default now applies to the message-driven inbound adapter and the inbound gateway.
It was already the default for JMS-backed channels.

See xref:changes-2.2-3.0.adoc#x3.0-jms-mdca-te[Message-driven Channel Adapter] and xref:jms.adoc#jms-inbound-gateway[Inbound Gateway] for more information.

[[shared-subscriptions]]
==== Shared Subscriptions

We added Namespace support for shared subscriptions (JMS 2.0) to message-driven endpoints and the `<int-jms:publish-subscribe-channel>`.
Previously, you had to wire up listener containers as `<bean/>` declarations to use shared connections.

See xref:jms.adoc[JMS Support] for more information.

[[x4.2-conditional-pollers]]
=== Conditional Pollers

We now provide much more flexibility for dynamic polling.

See xref:changes-4.1-4.2.adoc#x4.2-conditional-pollers[Conditional Pollers for Message Sources] for more information.

[[x4.2-amqp-changes]]
=== AMQP Changes

This section describes general changes to the Spring Integration AMQP functionality.

[[publisher-confirmations]]
==== Publisher Confirmations

The `<int-amqp:outbound-gateway>` now supports `confirm-correlation-expression`, `confirm-ack-channel`, and `confirm-nack-channel` attributes (which have a purpose similar to that of `<int-amqp:outbound-channel-adapter>`).

[[correlation-data]]
==== Correlation Data

For both the outbound channel adapter and the inbound gateway, if the correlation data is a `Message<?>`, it becomes the basis of the message on the ack or nack channel, with the additional header(s) added.
Previously, any correlation data (including `Message<?>`) was returned as the payload of the ack or nack message.

[[inbound-gateway-properties]]
==== Inbound Gateway Properties

The `<int-amqp:inbound-gateway>` now exposes the `amqp-template` attribute to allow more control over an external bean for the reply `RabbitTemplate`.
You can also provide your own `AmqpTemplate` implementation.
In addition, you can use `default-reply-to` if the request message does not have a `replyTo` property.

See xref:amqp.adoc[AMQP Support] for more information.

[[x4.2-xpath-splitter]]
=== XPath Splitter Improvements

The `XPathMessageSplitter` (`<int-xml:xpath-splitter>`) now allows the configuration of `output-properties` for the internal `javax.xml.transform.Transformer` and supports an `Iterator` mode (defaults to `true`) for the XPath evaluation `org.w3c.dom.NodeList` result.

See xref:xml/xpath-splitting.adoc[Splitting XML Messages] for more information.

[[x4.2-http-changes]]
=== HTTP Changes

This section describes general changes to the Spring Integration HTTP functionality.

[[cors]]
==== CORS

The HTTP inbound endpoints (`<int-http:inbound-channel-adapter>` and `<int-http:inbound-gateway>`) now allow the
configuration of Cross-origin Resource Sharing (CORS).

See xref:http/namespace.adoc#http-cors[Cross-origin Resource Sharing (CORS) Support] for more information.

[[inbound-gateway-timeout]]
==== Inbound Gateway Timeout

You can configure the HTTP inbound gate way to return a status code that you specify when a request times out.
The default is now `500 Internal Server Error` instead of `200 OK`.

See xref:http/namespace.adoc#http-response-statuscode[Response Status Code] for more information.

[[form-data]]
==== Form Data

We added documentation for proxying `multipart/form-data` requests.
See xref:http.adoc[HTTP Support] for more information.

[[x4.2-gw]]
=== Gateway Changes

This section describes general changes to the Spring Integration Gateway functionality.

[[gateway-methods-can-return-completablefuture<?>]]
==== Gateway Methods can Return `CompletableFuture<?>`

When using Java 8, gateway methods can now return `CompletableFuture<?>`.
See xref:gateway.adoc#gw-completable-future[`CompletableFuture`] for more information.

[[messaginggateway-annotation]]
==== MessagingGateway Annotation

The request and reply timeout properties are now `String` instead of `Long` to allow configuration with property placeholders or SpEL.
See xref:gateway.adoc#messaging-gateway-annotation[`@MessagingGateway` Annotation].

[[x4.2-aggregator-changes]]
=== Aggregator Changes

This section describes general changes to the Spring Integration aggregator functionality.

[[aggregator-performance]]
==== Aggregator Performance

This release includes some performance improvements for aggregating components (aggregator, resequencer, and others), by more efficiently removing messages from groups when they are released.
New methods (`removeMessagesFromGroup`) have been added to the message store.
Set the `removeBatchSize` property (default: `100`) to adjust the number of messages deleted in each operation.
Currently, the JDBC, Redis, and MongoDB message stores support this property.

[[output-message-group-processor]]
==== Output Message Group Processor

When using a `ref` or inner bean for the aggregator, you can now directly bind a `MessageGroupProcessor`.
In addition, we added a `SimpleMessageGroupProcessor` that returns the collection of messages in the group.
When an output processor produces a collection of `Message<?>`, the aggregator releases those messages individually.
Configuring the `SimpleMessageGroupProcessor` makes the aggregator a message barrier, where messages are held up until they all arrive and are then released individually.
See xref:overview.adoc#overview-endpoints-aggregator[Aggregator] for more information.

[[ftp-and-sftp-changes]]
=== FTP and SFTP Changes

This section describes general changes to the Spring Integration FTP and SFTP functionality.

[[inbound-channel-adapters]]
==== Inbound Channel Adapters

You can now specify a `remote-directory-expression` on the inbound channel adapters, to determine the directory at runtime.
See xref:ftp.adoc[FTP/FTPS Adapters] and xref:sftp.adoc[SFTP Adapters] for more information.

[[gateway-partial-results]]
==== Gateway Partial Results

When you use FTP or SFTP outbound gateways to operate on multiple files (with `mget` and `mput`), an exception can
occur after part of the request is completed.
If such a condition occurs, a `PartialSuccessException` that contains the partial results is thrown.
See xref:ftp/outbound-gateway.adoc[FTP Outbound Gateway] and xref:sftp/outbound-gateway.adoc[SFTP Outbound Gateway] for more information.

[[delegating-session-factory]]
==== Delegating Session Factory

We added a delegating session factory, enabling the selection of a particular session factory based on some thread context value.

See xref:ftp/dsf.adoc[Delegating Session Factory] and xref:sftp/dsf.adoc[Delegating Session Factory] for more information.

[[default-sftp-session-factory]]
==== Default Sftp Session Factory

Previously, the `DefaultSftpSessionFactory` unconditionally allowed connections to unknown hosts.
This is now configurable (default: `false`).

The factory now requires a configured `knownHosts`, file unless the `allowUnknownKeys` property is `true` (default: `false`).

See xref:sftp/session-factory.adoc#sftp-unk-keys[`allowUnknownKeys`::Set to `true` to allow connections to hosts with unknown (or changed) keys.] for more information.

[[message-session-callback]]
==== Message Session Callback

We introduced the `MessageSessionCallback<F, T>` to perform any custom `Session` operations with the `requestMessage` context in the `<int-(s)ftp:outbound-gateway/>`.

See xref:ftp/session-callback.adoc[Using `MessageSessionCallback`] and xref:sftp/session-callback.adoc[MessageSessionCallback] for more information.

[[websocket-changes]]
=== Websocket Changes

We added `WebSocketHandlerDecoratorFactory` support to the `ServerWebSocketContainer` to allow chained customization for the internal `WebSocketHandler`.
See xref:web-sockets.adoc#web-sockets-namespace[WebSockets Namespace Support] for more information.

[[application-event-adapters-changes]]
=== Application Event Adapters changes

The `ApplicationEvent` adapters can now operate with `payload` as an `event` to directly allow omitting custom `ApplicationEvent` extensions.
For this purpose, we introduced the `publish-payload` boolean attribute has been introduced on the `<int-event:outbound-channel-adapter>`.
See xref:event.adoc[Spring `ApplicationEvent` Support] for more information.
