GH-2605: (S)FTP test cached sessions

Resolves https://github.com/spring-projects/spring-integration/issues/2605

* Suppress unused field warning.

* Fix typos.

* Use lstat() - don't follow symbolic lincs

src/reference/asciidoc/ftp.adoc

@@ -85,10 +85,6 @@ The following example shows a complete configuration:
 ----
 ====
 
-Every time an adapter requests a session object from its `SessionFactory`, the session is returned from a session pool maintained by a caching wrapper around the factory.
-A session in the session pool might go stale (if it has been disconnected by the server due to inactivity), so the `SessionFactory` performs validation to make sure that it never returns a stale session to the adapter.
-If a stale session was encountered, it is removed from the pool, and a new one is created.
-
 NOTE: If you experience connectivity problems and would like to trace session creation as well as see which sessions are polled, you can enable session tracing by setting the logger to the `TRACE` level (for example, `log4j.category.org.springframework.integration.file=TRACE`).
 
 Now you need only inject these session factories into your adapters.
@@ -482,6 +478,7 @@ public class FtpJavaApplication {
         sf.setPort(port);
         sf.setUsername("foo");
         sf.setPassword("foo");
+        sf.setTestSession(true);
         return new CachingSessionFactory<FTPFile>(sf);
     }
 
@@ -884,6 +881,7 @@ public class FtpJavaApplication {
         sf.setPort(port);
         sf.setUsername("foo");
         sf.setPassword("foo");
+        sf.setTestSession(true);
         return new CachingSessionFactory<FTPFile>(sf);
     }
 
@@ -941,6 +939,7 @@ public class FtpJavaApplication {
         sf.setPort(port);
         sf.setUsername("foo");
         sf.setPassword("foo");
+        sf.setTestSession(true);
         return new CachingSessionFactory<FTPFile>(sf);
     }
 
@@ -1274,6 +1273,7 @@ public class FtpJavaApplication {
         sf.setPort(port);
         sf.setUsername("foo");
         sf.setPassword("foo");
+        sf.setTestSession(true);
         return new CachingSessionFactory<FTPFile>(sf);
     }
 
@@ -1313,6 +1313,7 @@ public class FtpJavaApplication {
         sf.setPort(port);
         sf.setUsername("foo");
         sf.setPassword("foo");
+        sf.setTestSession(true);
         return new CachingSessionFactory<FTPFile>(sf);
     }
 
@@ -1412,6 +1413,9 @@ Starting with Spring Integration 3.0, the `CachingConnectionFactory` provides a
 When invoked, all idle sessions are immediately closed and in-use sessions are closed when they are returned to the cache.
 New requests for sessions establish new sessions as necessary.
 
+Starting with version 5.1, the `CachingSessionFactory` has a new property `testSession`.
+When true, the session will be tested by sending a NOOP command to ensure it is still active; if not, it will be removed from the cache; a new session is created if no active sessions are in the cache.
+
 [[ftp-rft]]
 === Using `RemoteFileTemplate`
 

src/reference/asciidoc/sftp.adoc

@@ -253,6 +253,9 @@ When invoked, all idle sessions are immediately closed and in-use sessions are c
 When using `isSharedSession=true`, the channel is closed and the shared session is closed only when the last channel is closed.
 New requests for sessions establish new sessions as necessary.
 
+Starting with version 5.1, the `CachingSessionFactory` has a new property `testSession`.
+When true, the session will be tested by performing a `stat(getHome())` command to ensure it is still active; if not, it will be removed from the cache; a new session is created if no active sessions are in the cache.
+
 [[sftp-rft]]
 === Using `RemoteFileTemplate`
 
@@ -476,6 +479,7 @@ public class SftpJavaApplication {
         factory.setUser("foo");
         factory.setPassword("foo");
         factory.setAllowUnknownKeys(true);
+        factory.setTestSession(true);
         return new CachingSessionFactory<LsEntry>(factory);
     }
 
@@ -873,6 +877,7 @@ public class SftpJavaApplication {
         factory.setUser("foo");
         factory.setPassword("foo");
         factory.setAllowUnknownKeys(true);
+        factory.setTestSession(true);
         return new CachingSessionFactory<LsEntry>(factory);
     }
 
@@ -1257,6 +1262,7 @@ public class SftpJavaApplication {
         sf.setPort(port);
         sf.setUsername("foo");
         sf.setPassword("foo");
+        factory.setTestSession(true);
         return new CachingSessionFactory<LsEntry>(sf);
     }
 

src/reference/asciidoc/whats-new.adoc

@@ -162,6 +162,10 @@ See <<ftp-streaming>> and <<sftp-streaming>> for more information.
 In addition, the synchronizers for inbound channel adapters can now be provided with a `Comparator`.
 This is useful when using `maxFetchSize` to limit the files retrieved.
 
+The `CachingSessionFactory` has a new property `testSession` which, when true, causes the factory to perform a `test()` operation on the `Session` when checking out an existing session from the cache.
+
+See <<sftp-session-caching>> and <<ftp-session-caching>> for more information.
+
 [[x51.-tcp]]
 === TCP Support