[[migration-4.3-5.0]]
=== Changes between 4.3 and 5.0

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

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

Version 5.0 added a number of new components.

===== Java DSL

The separate https://github.com/spring-projects/spring-integration-java-dsl[Spring Integration Java DSL] project has now been merged into the core Spring Integration project.
The `IntegrationComponentSpec` implementations for channel adapters and gateways are distributed to their specific modules.
See <<./dsl.adoc#java-dsl,Java DSL>> for more information about Java DSL support.
See also the https://github.com/spring-projects/spring-integration/wiki/Spring-Integration-4.3-to-5.0-Migration-Guide#java-dsl[4.3 to 5.0 Migration Guide] for the required steps to move to Spring Integration 5.0.

===== Testing Support

We created a new Spring Integration Test Framework to help with testing Spring Integration applications.
Now, with the `@SpringIntegrationTest` annotation on test classes and the `MockIntegration` factory, you can make your JUnit tests for integration flows somewhat easier.

See <<./testing.adoc#testing,Testing support>> for more information.

===== MongoDB Outbound Gateway

The new `MongoDbOutboundGateway` lets you make queries to the database on demand by sending a message to its request channel.

See <<./mongodb.adoc#mongodb-outbound-gateway,MongoDB Outbound Gateway>> for more information.

===== WebFlux Gateways and Channel Adapters

We introduced the new WebFlux support module for Spring WebFlux Framework gateways and channel adapters.

See <<./webflux.adoc#webflux,WebFlux Support>> for more information.

===== Content Type Conversion

Now that we use the new `InvocableHandlerMethod`-based infrastructure for service method invocations, we can perform `contentType` conversion from the payload to a target method argument.

See <<./endpoint.adoc#content-type-conversion,Content Type Conversion>> for more information.

===== `ErrorMessagePublisher` and `ErrorMessageStrategy`

We added `ErrorMessagePublisher` and the `ErrorMessageStrategy` for creating `ErrorMessage` instances.

See <<./error-handling.adoc#error-handling,Error Handling>> for more information.

===== JDBC Metadata Store

We added a JDBC implementation of the `MetadataStore` implementation.
This is useful when you need to ensure transactional boundaries for metadata.

See <<./jdbc.adoc#jdbc-metadata-store,JDBC Metadata Store>> for more information.

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

Spring Integration is now fully based on Spring Framework `5.0` and Project Reactor `3.1`.
Previous Project Reactor versions are no longer supported.

===== Core Changes

The `@Poller` annotation now has the `errorChannel` attribute for easier configuration of the underlying `MessagePublishingErrorHandler`.
See <<./configuration.adoc#annotations,Annotation Support>> for more information.

All the request-reply endpoints (based on `AbstractReplyProducingMessageHandler`) can now start transactions and, therefore, make the whole downstream flow transactional.
See <<./handler-advice.adoc#tx-handle-message-advice,Transaction Support>> for more information.

The `SmartLifecycleRoleController` now provides methods to obtain status of endpoints in roles.
See <<./endpoint.adoc#endpoint-roles,Endpoint Roles>> for more information.

By default, POJO methods are now invoked by using an `InvocableHandlerMethod`, but you can configure them to use SpEL, as before.
See <<./overview.adoc#pojo-invocation,POJO Method invocation>> for more information.

When targeting POJO methods as message handlers, you can now mark one of the service methods with the `@Default` annotation to provide a fallback mechanism for non-matched conditions.
See <<./service-activator.adoc#service-activator-namespace,Configuring Service Activator>> for more information.

We added a simple `PassThroughTransactionSynchronizationFactory` to always store a polled message in the current transaction context.
That message is used as a `failedMessage` property of the `MessagingException`, which wraps any raw exception thrown during transaction completion.
See <<./transactions.adoc#transaction-synchronization,Transaction Synchronization>> for more information.

The aggregator expression-based `ReleaseStrategy` now evaluates the expression against the `MessageGroup` instead of just the collection of `Message<?>`.
See <<./aggregator.adoc#aggregator-spel,Aggregators and Spring Expression Language (SpEL)>> for more information.

You can now supply the `ObjectToMapTransformer` with a customized `JsonObjectMapper`.

See <<./aggregator.adoc#aggregator-spel,Aggregators and Spring Expression Language (SpEL)>> for more information.

The `@GlobalChannelInterceptor` annotation and `<int:channel-interceptor>` now support negative patterns (via `!` prepending) for component names matching.
See <<./channel.adoc#global-channel-configuration-interceptors,Global Channel Interceptor Configuration>> for more information.

When a candidate failed to acquire the lock, the `LockRegistryLeaderInitiator` now emits a new `OnFailedToAcquireMutexEvent` through `DefaultLeaderEventPublisher`.
See `<<./endpoint.adoc#leadership-event-handling,Leadership Event Handling>>` for more information.

===== Gateway Changes

When the gateway method has a `void` return type and an error channel is provided, the gateway now correctly sets the `errorChannel` header.
Previously, the header was not populated.
This caused synchronous downstream flows (running on the calling thread) to send the exception to the configured channel, but an exception on an asynchronous downstream flow would be sent to the default `errorChannel` instead.

The `RequestReplyExchanger` interface now has a `throws MessagingException` clause to meet the proposed messages exchange contract.

You can now specify the request and reply timeouts with SpEL expressions.
See <<./gateway.adoc#gateway,Messaging Gateways>> for more information.

===== Aggregator Performance Changes

By default, aggregators now use a `SimpleSequenceSizeReleaseStrategy`, which is more efficient, especially with large groups.
Empty groups are now scheduled for removal after `empty-group-min-timeout`.
See <<./aggregator.adoc#aggregator,Aggregator>> for more information.

===== Splitter Changes

The splitter component can now handle and split Java `Stream` and Reactive Streams `Publisher` objects.
If the output channel is a `ReactiveStreamsSubscribableChannel`, the `AbstractMessageSplitter` builds a `Flux` for subsequent iteration instead of a regular `Iterator`, independent of the object being split.
In addition, `AbstractMessageSplitter` provides `protected obtainSizeIfPossible()` methods to allow determination of the size of the `Iterable` and `Iterator` objects, if that is possible.
See <<./splitter.adoc#splitter,Splitter>> for more information.

===== JMS Changes

Previously, Spring Integration JMS XML configuration used a default bean name of `connectionFactory` for the JMS connection factory, letting the property be omitted from component definitions.
We renamed it to `jmsConnectionFactory`, which is the bean name used by Spring Boot to auto-configure the JMS connection factory bean.

If your application relies on the previous behavior, you can rename your `connectionFactory` bean to `jmsConnectionFactory` or specifically configure your components to use your bean by using its current name.
See <<./jms.adoc#jms,JMS Support>> for more information.

===== Mail Changes

Some inconsistencies with rendering IMAP mail content have been resolved.
See <<./mail.adoc#imap-format-important,the note in the "`Mail-receiving Channel Adapter`" section>> for more information.

===== Feed Changes

Instead of the `com.rometools.fetcher.FeedFetcher`, which is deprecated in ROME, we introduced a new `Resource` property for the `FeedEntryMessageSource`.
See <<./feed.adoc#feed,Feed Adapter>> for more information.

===== File Changes

We introduced the new `FileHeaders.RELATIVE_PATH` message header to represent relative path in `FileReadingMessageSource`.

The tail adapter now supports `idleEventInterval` to emit events when there is no data in the file during that period.

The flush predicates for the `FileWritingMessageHandler` now have an additional parameter.

The file outbound channel adapter and gateway (`FileWritingMessageHandler`) now support the `REPLACE_IF_MODIFIED` `FileExistsMode`.

They also now support setting file permissions on the newly written file.

A new `FileSystemMarkerFilePresentFileListFilter` is now available.
See <<./file.adoc#file-incomplete,Dealing With Incomplete Data>> for more information.

The `FileSplitter` now provides a `firstLineAsHeader` option to carry the first line of content as a header in the messages emitted for the remaining lines.

See <<./file.adoc#files,File Support>> for more information.

===== FTP and SFTP Changes

The inbound channel adapters now have a property called `max-fetch-size`, which is used to limit the number of files fetched during a poll when no files are currently in the local directory.
By default, they also are configured with a `FileSystemPersistentAcceptOnceFileListFilter` in the `local-filter`.

You can also provide a custom `DirectoryScanner` implementation to inbound channel adapters by setting the newly introduced `scanner` attribute.

You can now configure the regex and pattern filters to always pass directories.
This can be useful when you use recursion in the outbound gateways.

By default, all the inbound channel adapters (streaming and synchronization-based) now use an appropriate `AbstractPersistentAcceptOnceFileListFilter` implementation to prevent duplicate downloads of remote files.

The FTP and SFTP outbound gateways now support the `REPLACE_IF_MODIFIED` `FileExistsMode` when fetching remote files.

The FTP and SFTP streaming inbound channel adapters now add remote file information in a message header.

The FTP and SFTP outbound channel adapters (as well as the `PUT` command for outbound gateways) now support `InputStream` as `payload`, too.

The inbound channel adapters can now build file trees locally by using a newly introduced `RecursiveDirectoryScanner`.
See the `scanner` option in the <<./ftp.adoc#ftp-inbound,FTP Inbound Channel Adapter>> section for injection.
Also, you can now switch these adapters to the `WatchService` instead.

We added The `NLST` command to the `AbstractRemoteFileOutboundGateway` to perform the list files names remote command.

You can now supply the `FtpOutboundGateway` with `workingDirExpression` to change the FTP client working directory for the current request message.

The `RemoteFileTemplate` is supplied now with the `invoke(OperationsCallback<F, T> action)` to perform several `RemoteFileOperations` calls in the scope of the same, thread-bounded, `Session`.

We added new filters for detecting incomplete remote files.

The `FtpOutboundGateway` and `SftpOutboundGateway` now support an option to remove the remote file after a successful transfer by using the `GET` or `MGET` commands.

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

===== Integration Properties

Version 4.3.2 added a new `spring.integration.readOnly.headers` global property to let you customize the list of headers that should not be copied to a newly created `Message` by the `MessageBuilder`.
See <<./configuration.adoc#global-properties,Global Properties>> for more information.

===== Stream Changes

We added a new option on the `CharacterStreamReadingMessageSource` to let it be used to "`pipe`" stdin and publish an application event when the pipe is closed.
See <<./stream.adoc#stream-reading,Reading from Streams>> for more information.

===== Barrier Changes

The `BarrierMessageHandler` now supports a discard channel to which late-arriving trigger messages are sent.
See <<./barrier.adoc#barrier,Thread Barrier>> for more information.

===== AMQP Changes

The AMQP outbound endpoints now support setting a delay expression when you use the RabbitMQ Delayed Message Exchange plugin.

The inbound endpoints now support the Spring AMQP `DirectMessageListenerContainer`.

Pollable AMQP-backed channels now block the poller thread for the poller's configured `receiveTimeout` (default: one second).

Headers, such as `contentType`, that are added to message properties by the message converter are now used in the final message.
Previously, it depended on the converter type as to which headers and message properties appeared in the final message.
To override the headers set by the converter, set the `headersMappedLast` property to `true`.
See <<./amqp.adoc#amqp,AMQP Support>> for more information.

===== HTTP Changes

By default, the `DefaultHttpHeaderMapper.userDefinedHeaderPrefix` property is now an empty string instead of `X-`.
See <<./http.adoc#http-header-mapping,HTTP Header Mappings>> for more information.

By default, `uriVariablesExpression` now uses a `SimpleEvaluationContext` (since 5.0.4).

See <<./http.adoc#mapping-uri-variables,Mapping URI Variables>> for more information.

===== MQTT Changes

Inbound messages are now mapped with the `RECEIVED_TOPIC`, `RECEIVED_QOS`, and `RECEIVED_RETAINED` headers to avoid inadvertent propagation to outbound messages when an application relays messages.

The outbound channel adapter now supports expressions for the topic, qos, and retained properties.
The defaults remain the same.
See <<./mqtt.adoc#mqtt,MQTT Support>> for more information.

===== STOMP Changes

We changed the STOMP module to use `ReactorNettyTcpStompClient`, based on the Project Reactor `3.1` and `reactor-netty` extension.
We renamed `Reactor2TcpStompSessionManager` to `ReactorNettyTcpStompSessionManager`, according to the `ReactorNettyTcpStompClient` foundation.
See <<./stomp.adoc#stomp,STOMP Support>> for more information.

===== Web Services Changes

You can now supply `WebServiceOutboundGateway` instances with an externally configured `WebServiceTemplate` instances.

`DefaultSoapHeaderMapper` can now map a `javax.xml.transform.Source` user-defined header to a SOAP header element.

Simple WebService inbound and outbound gateways can now deal with the complete `WebServiceMessage` as a `payload`, allowing the manipulation of MTOM attachments.

See <<./ws.adoc#ws,Web Services Support>> for more information.

===== Redis Changes

The `RedisStoreWritingMessageHandler` is supplied now with additional `String`-based setters for SpEL expressions (for convenience with Java configuration).
You can now configure the `zsetIncrementExpression` on the `RedisStoreWritingMessageHandler` as well.
In addition, this property has been changed from `true` to `false` since the `INCR` option on `ZADD` Redis command is optional.

You can now supply the `RedisInboundChannelAdapter` with an `Executor` for executing Redis listener invokers.
In addition, the received messages now contain a `RedisHeaders.MESSAGE_SOURCE` header to indicate the source of the message (topic or pattern).

See <<./redis.adoc#redis,Redis Support>> for more information.

===== TCP Changes

We added a new `ThreadAffinityClientConnectionFactory` to bind TCP connections to threads.

You can now configure the TCP connection factories to support `PushbackInputStream` instances, letting deserializers "`unread`" (push back) bytes after "`reading ahead`".

We added a `ByteArrayElasticRawDeserializer` without `maxMessageSize` to control and buffer incoming data as needed.

See <<./ip.adoc#ip,TCP and UDP Support>> for more information.

===== Gemfire Changes

The `GemfireMetadataStore` now implements `ListenableMetadataStore`, letting you listen to cache events by providing `MetadataStoreListener` instances to the store.
See <<./gemfire.adoc#gemfire,Pivotal GemFire and Apache Geode Support>> for more information.

===== JDBC Changes

The `JdbcMessageChannelStore` now provides a setter for `ChannelMessageStorePreparedStatementSetter`, letting you customize message insertion in the store.

The `ExpressionEvaluatingSqlParameterSourceFactory` now provides a setter for `sqlParameterTypes`, letting you customize the SQL types of the parameters.

See <<./jdbc.adoc#jdbc,JDBC Support>> for more information.


===== Metrics Changes

https://micrometer.io/[Micrometer] application monitoring is now supported (since version 5.0.2).
See <<./metrics.adoc#micrometer-integration,Micrometer Integration>> for more information.

IMPORTANT: Changes were made to the Micrometer `Meters` in version 5.0.3 to make them more suitable for use in dimensional systems.
Further changes were made in 5.0.4.
If you use Micrometer, we recommend a minimum of version 5.0.4.


===== `@EndpointId` Annotations

Introduced in version 5.0.4, this annotation provides control over bean naming when you use Java configuration.
See <<./overview.adoc#endpoint-bean-names,Endpoint Bean Names>> for more information.
