INT-3491: (S)FTP Delegation Session Factory

JIRA: https://jira.spring.io/browse/INT-3491

Select the session factory at runtime.

Polishing; PR Comments

Also add/remove factories.

src/reference/asciidoc/ftp.adoc

@@ -121,6 +121,39 @@ public class AdvancedFtpSessionFactory extends DefaultFtpSessionFactory {
 }
 ----
 
+[[ftp-dsf]]
+=== Delegating Session Factory
+
+_Version 4.2_ introduced the `DelegatingSessionFactory` which allows the selection of the actual session factory at
+runtime.
+Prior to invoking the ftp endpoint, call `setThreadKey()` on the factory to associate a key with the current thread.
+That key is then used to lookup the actual session factory to be used.
+The key can be cleared by calling `clearThreadKey()` after use.
+
+Convenience methods have been added so this can easily be done from a message flow:
+
+[source, xml]
+----
+<bean id="dsf" class="org.springframework.integration.file.remote.session.DelegatingSessionFactory">
+    <constructor-arg>
+        <bean class="o.s.i.file.remote.session.DefaultSessionFactoryLocator">
+		    <!-- delegate factories here -->
+        </bean>
+    </constructor-arg>
+</bean>
+
+<int:service-activator input-channel="in" output-channel="c1"
+        expression="@dsf.setThreadKey(#root, headers['factoryToUse'])" />
+
+<int-ftp:outbound-gateway request-channel="c1" reply-channel="c2" ... />
+
+<int:service-activator input-channel="c2" output-channel="out"
+        expression="@dsf.clearThreadKey(#root)" />
+----
+
+IMPORTANT: When using session caching (see <<ftp-session-caching>>), each of the delegates should be cached; you
+cannot cache the `DelegatingSessionFactory` itself.
+
 [[ftp-inbound]]
 === FTP Inbound Channel Adapter
 

src/reference/asciidoc/sftp.adoc

@@ -159,6 +159,39 @@ Defaults to `0`, which means, that no timeout will occur.
 The remote user to use.
 _Mandatory_.
 
+[[sftp-dsf]]
+=== Delegating Session Factory
+
+_Version 4.2_ introduced the `DelegatingSessionFactory` which allows the selection of the actual session factory at
+runtime.
+Prior to invoking the ftp endpoint, call `setThreadKey()` on the factory to associate a key with the current thread.
+That key is then used to lookup the actual session factory to be used.
+The key can be cleared by calling `clearThreadKey()` after use.
+
+Convenience methods have been added so this can easily be done from a message flow:
+
+[source, xml]
+----
+<bean id="dsf" class="org.springframework.integration.file.remote.session.DelegatingSessionFactory">
+    <constructor-arg>
+        <bean class="o.s.i.file.remote.session.DefaultSessionFactoryLocator">
+		    <!-- delegate factories here -->
+        </bean>
+    </constructor-arg>
+</bean>
+
+<int:service-activator input-channel="in" output-channel="c1"
+        expression="@dsf.setThreadKey(#root, headers['factoryToUse'])" />
+
+<int-sftp:outbound-gateway request-channel="c1" reply-channel="c2" ... />
+
+<int:service-activator input-channel="c2" output-channel="out"
+        expression="@dsf.clearThreadKey(#root)" />
+----
+
+IMPORTANT: When using session caching (see <<sftp-session-caching>>), each of the delegates should be cached; you
+cannot cache the `DelegatingSessionFactory` itself.
+
 [[sftp-session-caching]]
 === SFTP Session Caching
 

src/reference/asciidoc/whats-new.adoc

@@ -270,6 +270,13 @@ occur after part of the request is completed.
 If such a condition occurs, a `PartialSuccessException` is thrown containing the partial results.
 See <<ftp-outbound-gateway>> and <<sftp-outbound-gateway>> for more information.
 
+===== Delegating Session Factory
+
+A delegating session factory is now available, enabling the selection of a particular session factory based on some
+thread context value.
+
+See <<ftp-dsf>> and <<sftp-dsf>> for more information.
+
 ==== Websocket Changes
 
 `WebSocketHandlerDecoratorFactory` support has been added to the `ServerWebSocketContainer`