INT-3737: (S)FTP Outbound Gateway Streaming GET

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

Support returning an `InputStream` from a GET operation.

This can be used in conjuction with a `<file:splitter/>` to stream a text file.

The user is responsible for releasing the session when the download is complete.

The session object is stored in the message header and `RemoteFileUtils.closeSession()` should be called
to clean up and close the session.

INT-3737: Polishing and Docs

Fix `CachedSession.close()` bug

Preventing `Caused by: java.io.IOException: Previous raw read was not finalized`
when `Session` is returned to the pool, but `readingRaw` hasn't been finalized
because the real `close()` isn't invoked in case of normal return to pool.

spring-integration-sftp/src/test/java/org/springframework/integration/sftp/outbound/SftpServerOutboundTests-context.xml

@@ -1,12 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <beans xmlns="http://www.springframework.org/schema/beans"
-	   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-	   xmlns:int-sftp="http://www.springframework.org/schema/integration/sftp"
-	   xmlns:int="http://www.springframework.org/schema/integration"
-	   xsi:schemaLocation="http://www.springframework.org/schema/integration/sftp
-	 http://www.springframework.org/schema/integration/sftp/spring-integration-sftp.xsd
-		http://www.springframework.org/schema/integration http://www.springframework.org/schema/integration/spring-integration.xsd
-		http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xmlns:int-sftp="http://www.springframework.org/schema/integration/sftp"
+	xmlns:int="http://www.springframework.org/schema/integration"
+	xmlns:int-file="http://www.springframework.org/schema/integration/file"
+	xsi:schemaLocation="http://www.springframework.org/schema/integration/sftp http://www.springframework.org/schema/integration/sftp/spring-integration-sftp.xsd
+		http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
+		http://www.springframework.org/schema/integration/file http://www.springframework.org/schema/integration/file/spring-integration-file.xsd
+		http://www.springframework.org/schema/integration http://www.springframework.org/schema/integration/spring-integration.xsd">
 
 	<int:channel id="output">
 		<int:queue/>
@@ -133,4 +134,23 @@
 							  auto-create-directory="true"
 							  remote-file-separator="/"	/>
 
+	<int-sftp:outbound-gateway session-factory="sftpSessionFactory"
+							  request-channel="inboundGetStream"
+							  command="get"
+							  command-options="-stream"
+							  expression="payload"
+							  remote-directory="ftpTarget"
+							  reply-channel="stream" />
+
+	<int:chain input-channel="stream">
+		<int-file:splitter markers="true" />
+		<int:payload-type-router resolution-required="false" default-output-channel="output">
+			<int:mapping type="org.springframework.integration.file.splitter.FileSplitter$FileMarker"
+						 channel="markers" />
+		</int:payload-type-router>
+	</int:chain>
+
+	<int:service-activator input-channel="markers"
+	  expression="payload.mark.toString().equals('END') ? headers['file_remoteSession'].close() : null"/>
+
 </beans>

spring-integration-sftp/src/test/java/org/springframework/integration/sftp/outbound/SftpServerOutboundTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2013-2014 the original author or authors.
+ * Copyright 2013-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,6 +21,7 @@ import static org.hamcrest.Matchers.containsString;
 import static org.hamcrest.Matchers.equalTo;
 import static org.hamcrest.Matchers.not;
 import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertSame;
 import static org.junit.Assert.assertThat;
@@ -125,6 +126,9 @@ public class SftpServerOutboundTests {
 	@Autowired
 	private TestSftpServer sftpServer;
 
+	@Autowired
+	private DirectChannel inboundGetStream;
+
 	@Before
 	@After
 	public void setup() {
@@ -404,6 +408,18 @@ public class SftpServerOutboundTests {
 
 	}
 
+	@Test
+	public void testStream() {
+		String dir = "sftpSource/";
+		this.inboundGetStream.send(new GenericMessage<Object>(dir + "sftpSource1.txt"));
+		Message<?> result = this.output.receive(1000);
+		assertNotNull(result);
+		assertEquals("source1", result.getPayload());
+		assertEquals("sftpSource/", result.getHeaders().get(FileHeaders.REMOTE_DIRECTORY));
+		assertEquals("sftpSource1.txt", result.getHeaders().get(FileHeaders.REMOTE_FILE));
+		assertFalse(((Session<?>) result.getHeaders().get(FileHeaders.REMOTE_SESSION)).isOpen());
+	}
+
 	private void assertLength6(SftpRemoteFileTemplate template) {
 		LsEntry[] files = template.execute(new SessionCallback<LsEntry, LsEntry[]>() {