FTP 外发网关
FTP outbound 网关提供了一组有限的命令来与远程 FTP 或 FTPS 服务器进行交互。支持的命令有：
-
ls(列出文件) -
nlst(列出文件名) -
get(获取文件) -
mget(获取文件) -
rm(删除文件) -
mv(移动/重命名文件) -
put(发送文件) -
mput(发送多个文件)
使用 ls 命令
ls 列出远程文件并支持以下选项：
-
-1: 检索文件名列表。默认情况下，检索FileInfo对象列表。 -
-a：包含所有文件（包括以 '.' 开头的文件） -
-f：不排序列表 -
-dirs：包含目录（默认情况下它们被排除） -
-links：包含符号链接（默认情况下它们被排除） -
-R：递归列出远程目录
此外，提供了文件名过滤功能，方式与 inbound-channel-adapter 相同。请参阅 FTP 入站通道适配器。
ls 操作产生的消息有效负载是文件名列表或 FileInfo 对象列表。这些对象提供了修改时间、权限等其他详细信息。
ls 命令作用的远程目录在 file_remoteDirectory 标头中提供。
当使用递归选项 (-R) 时，fileName 包含任何子目录元素，表示文件的相对路径（相对于远程目录）。如果包含 -dirs 选项，则每个递归目录也会作为列表中的一个元素返回。在这种情况下，建议您不要使用 -1 选项，因为您将无法区分文件和目录，而这是可以通过 FileInfo 对象来完成的。
从 4.3 版本开始，FtpSession 支持 list() 和 listNames() 方法的 null。因此，你可以省略 expression 属性。为了方便，Java 配置有两个没有 expression 参数的构造函数。对于 LS、NLST、PUT 和 MPUT 命令，根据 FTP 协议，null 被视为客户端工作目录。所有其他命令必须提供 expression 以根据请求消息评估远程路径。你可以在扩展 DefaultFtpSessionFactory 并实现 postProcessClientAfterConnect() 回调时，使用 FTPClient.changeWorkingDirectory() 函数设置工作目录。
使用 nlst 命令
版本 5 引入了对 nlst 命令的支持。
nlst 列出远程文件名，并且只支持一个选项：
-f：不排序列表
nlst 操作产生的消息有效负载是文件名列表。
nlst 命令作用的远程目录在 file_remoteDirectory 标头中提供。
与 ls 命令 的 -1 选项不同，它使用 LIST 命令，而 nlst 命令向目标 FTP 服务器发送 NLST 命令。当服务器由于安全限制等原因不支持 LIST 时，此命令很有用。nlst 操作的结果是仅返回名称而没有其他详细信息。因此，框架无法确定实体是否为目录，从而无法执行过滤或递归列出等操作。
使用 get 命令
get 检索远程文件。它支持以下选项：
-
-P: 保留远程文件的时间戳。 -
-stream: 以流的形式获取远程文件。 -
-D: 在成功传输后删除远程文件。如果传输被忽略，则不会删除远程文件，因为FileExistsMode是IGNORE且本地文件已存在。
file_remoteDirectory 标头提供远程目录名称，file_remoteFile 标头提供文件名称。
Closeable closeable = new IntegrationMessageHeaderAccessor(message).getCloseableResource();
if (closeable != null) {
closeable.close();
}
以下示例展示了如何将文件作为流进行消费：
<int-ftp:outbound-gateway session-factory="ftpSessionFactory"
request-channel="inboundGetStream"
command="get"
command-options="-stream"
expression="payload"
remote-directory="ftpTarget"
reply-channel="stream" />
<int-file:splitter input-channel="stream" output-channel="lines" />
如果您在自定义组件中消费输入流，则必须关闭 Session。您可以在自定义代码中执行此操作，也可以通过将消息的副本路由到 service-activator 并使用 SpEL 来完成，如下例所示：
<int:service-activator input-channel="closeSession"
expression="headers['closeableResource'].close()" />
使用 mget 命令
mget 根据模式检索多个远程文件，并支持以下选项：
-
-P: 保留远程文件的时间戳。 -
-R: 递归地检索整个目录树。 -
-x: 如果没有文件匹配该模式则抛出异常（否则返回一个空列表）。 -
-D: 在成功传输后删除每个远程文件。如果传输被忽略，则远程文件不会被删除，因为FileExistsMode是IGNORE且本地文件已存在。
mget 操作产生的消息有效负载是一个 List<File> 对象（即，一个 File 对象的 List，每个 File 对象表示一个已检索的文件）。
从 5.0 版本开始，如果 FileExistsMode 是 IGNORE，输出消息的有效负载将不再包含由于文件已存在而未获取的文件。以前，列表包含所有文件，包括那些已经存在的文件。
用于确定远程路径的表达式应产生以 ** 结尾的结果 - 例如，somedir/ 将获取 somedir 下的完整树。
从 5.0 版本开始，可以使用递归的 mget，结合新的 FileExistsMode.REPLACE_IF_MODIFIED 模式，定期将整个远程目录树同步到本地。此模式会用远程时间戳替换本地文件的最后修改时间戳，无论是否使用 -P（保留时间戳）选项。
使用递归 (-R)
模式被忽略，并假设为 *。默认情况下，整个远程树将被检索。但是，可以通过提供 FileListFilter 来过滤树中的文件。树中的目录也可以通过这种方式过滤。可以通过引用、filename-pattern 或 filename-regex 属性提供 FileListFilter。例如，filename-regex="(subDir|.*1.txt)" 检索远程目录和 subDir 子目录中所有以 1.txt 结尾的文件。然而，下一个示例展示了一种替代方法，这是 5.0 版本提供的。
如果子目录被过滤，则不会对该子目录进行进一步遍历。
不允许使用 -dirs 选项（递归的 mget 使用递归的 ls 来获取目录树，因此目录本身不能包含在列表中）。
通常，您会在 local-directory-expression 中使用 #remoteDirectory 变量，以便在本地保留远程目录结构。
持久化文件列表过滤器现在有一个布尔属性 forRecursion。将此属性设置为 true，也会设置 alwaysAcceptDirectories，这意味着在出站网关 (ls 和 mget) 上的递归操作每次都将遍历完整的目录树。这是为了解决目录树深层的变化未被检测到的问题。此外，forRecursion=true 会导致使用文件的完整路径作为元数据存储键；这解决了如果不同目录中出现同名文件时过滤器无法正常工作的问题。重要提示：这意味着持久化元数据存储中现有的键对于顶级目录下的文件将无法找到。因此，默认情况下该属性为 false；这可能会在未来版本中更改。
从 5.0 版开始，可以通过将 alwaysAcceptDirectories 属性设置为 true 来配置 FtpSimplePatternFileListFilter 和 FtpRegexPatternFileListFilter 以始终通过目录。这样做允许简单模式的递归，如下例所示：
<bean id="starDotTxtFilter"
class="org.springframework.integration.ftp.filters.FtpSimplePatternFileListFilter">
<constructor-arg value="*.txt" />
<property name="alwaysAcceptDirectories" value="true" />
</bean>
<bean id="dotStarDotTxtFilter"
class="org.springframework.integration.ftp.filters.FtpRegexPatternFileListFilter">
<constructor-arg value="^.*\.txt$" />
<property name="alwaysAcceptDirectories" value="true" />
</bean>
一旦你定义了过滤器，比如前面示例中的那些，你可以通过在网关上设置 filter 属性来使用其中一个。
另请参阅 传出网关部分成功 (mget 和 mput)。
使用 put 命令
put 命令将文件发送到远程服务器。消息的有效负载可以是 java.io.File、byte[] 或 String。使用 remote-filename-generator（或表达式）来命名远程文件。其他可用属性包括 remote-directory、temporary-remote-directory 以及它们的 *-expression 等效项：use-temporary-file-name 和 auto-create-directory。更多信息请参阅 schema 文档。
put 操作 resulting from a put operation 的消息有效负载是一个表示文件传输到服务器后完整路径的 String。
Version 5.2 引入了 chmod 属性，它在上传后更改远程文件权限。你可以使用常规的 Unix 八进制格式（例如，600 仅允许文件所有者读写）。当使用 java 配置适配器时，你可以使用 setChmod(0600)。仅在你的 FTP 服务器支持 SITE CHMOD 子命令时适用。
使用 mput 命令
mput 将多个文件发送到服务器，并且只支持一个选项：
-R：递归。发送目录及其子目录中的所有文件（可能是经过过滤的）。
消息有效负载必须是表示本地目录的 java.io.File（或 String）。自 5.1 版起，也支持 File 或 String 的集合。
此命令支持与put 命令相同的属性。此外，本地目录中的文件可以使用 mput-pattern、mput-regex、mput-filter 或 mput-filter-expression 之一进行过滤。只要子目录本身通过过滤器，过滤器就会递归工作。未通过过滤器的子目录不会被递归。
mput 操作产生的消息有效负载是一个 List<String> 对象（即，传输结果的远程文件路径列表）。
另请参阅 传出网关部分成功 (mget 和 mput)。
版本 5.2 引入了 chmod 属性，它允许你在上传后更改远程文件权限。你可以使用常规的 Unix 八进制格式（例如，600 仅允许文件所有者读写）。在使用 Java 配置适配器时，你可以使用 setChmodOctal("600") 或 setChmod(0600)。仅在你的 FTP 服务器支持 SITE CHMOD 子命令时适用。
使用 rm 命令
rm 命令删除文件。
rm 命令没有选项。
rm 操作产生的消息有效载荷是 Boolean.TRUE，如果删除成功，或者 Boolean.FALSE 如果删除失败。file_remoteDirectory 头提供了远程目录，而 file_remoteFile 头提供了文件名。
使用 mv 命令
mv 命令移动文件。
mv 命令没有选项。
expression 属性定义了 “from” 路径，rename-expression 属性定义了 “to” 路径。默认情况下，rename-expression 是 headers['file_renameTo']。此表达式不能评估为 null 或空的 String。如有必要，会创建任何必要的远程目录。结果消息的有效载荷是 Boolean.TRUE。file_remoteDirectory 头提供了原始远程目录，file_remoteFile 头提供了文件名。新路径在 file_renameTo 头中。
从版本 5.5.6 开始，可以在 mv 命令中使用 remoteDirectoryExpression 以方便操作。如果“from”文件不是完整的文件路径，则将 remoteDirectoryExpression 的结果用作远程目录。同样的规则也适用于“to”文件，例如，如果任务只是在某个目录中重命名远程文件。
关于 FTP 外发网关命令的其他信息
get 和 mget 命令支持 local-filename-generator-expression 属性。它定义了一个 SpEL 表达式，在传输期间生成本地文件的名称。评估上下文的根对象是请求消息。remoteFileName 变量对于 mget 特别有用，也可以使用 — 例如，local-filename-generator-expression="#remoteFileName.toUpperCase() + headers.something"。
get 和 mget 命令支持 local-directory-expression 属性。它定义了一个 SpEL 表达式，在传输过程中生成本地目录的名称。评估上下文的根对象是请求消息，但 remoteDirectory 变量也可用，对于 mget 尤其有用——例如：local-directory-expression="'/tmp/local/' + #remoteDirectory.toUpperCase() + headers.something"。此属性与 local-directory 属性互斥。
对于所有命令，网关的 'expression' 属性提供了命令作用的路径。对于 mget 命令，表达式可能求值为 ''，表示检索所有文件，或者 'somedirectory/'，等等。
以下示例展示了一个为 ls 命令配置的网关：
<int-ftp:outbound-gateway id="gateway1"
session-factory="ftpSessionFactory"
request-channel="inbound1"
command="ls"
command-options="-1"
expression="payload"
reply-channel="toSplitter"/>
发送到 toSplitter 通道的消息的有效负载是一个 String 对象列表，每个对象包含一个文件的名称。如果省略了 command-options 属性，则它持有 FileInfo 对象。它使用空格分隔的选项 — 例如，command-options="-1 -dirs -links"。
从 4.2 版本开始，GET、MGET、PUT 和 MPUT 命令支持一个 FileExistsMode 属性（在使用命名空间支持时为 mode）。这会影响本地文件已存在（针对 GET 和 MGET）或远程文件已存在（针对 PUT 和 MPUT）时的行为。支持的模式有 REPLACE、APPEND、FAIL 和 IGNORE。为了向后兼容，默认情况下 PUT 和 MPUT 操作的模式是 REPLACE。对于 GET 和 MGET 操作，默认模式是 FAIL。
从 5.0 版本开始，在 FtpOutboundGateway (<int-ftp:outbound-gateway> 在 XML 中) 上提供了 setWorkingDirExpression() (working-dir-expression 在 XML 中) 选项。它允许你在运行时更改客户端工作目录。该表达式针对请求消息进行求值。在每次网关操作后，之前的工作目录将被恢复。
使用Java配置
下面的 Spring Boot 应用展示了如何使用 Java 配置来配置 outbound gateway 的示例：
@SpringBootApplication
public class FtpJavaApplication {
public static void main(String[] args) {
new SpringApplicationBuilder(FtpJavaApplication.class)
.web(false)
.run(args);
}
@Bean
public SessionFactory<FTPFile> ftpSessionFactory() {
DefaultFtpSessionFactory sf = new DefaultFtpSessionFactory();
sf.setHost("localhost");
sf.setPort(port);
sf.setUsername("foo");
sf.setPassword("foo");
sf.setTestSession(true);
return new CachingSessionFactory<FTPFile>(sf);
}
@Bean
@ServiceActivator(inputChannel = "ftpChannel")
public MessageHandler handler() {
FtpOutboundGateway ftpOutboundGateway =
new FtpOutboundGateway(ftpSessionFactory(), "ls", "'my_remote_dir/'");
ftpOutboundGateway.setOutputChannelName("lsReplyChannel");
return ftpOutboundGateway;
}
}
使用 Java DSL 进行配置
以下的 Spring Boot 应用展示了如何使用 Java DSL 配置出站网关的示例：
@SpringBootApplication
public class FtpJavaApplication {
public static void main(String[] args) {
new SpringApplicationBuilder(FtpJavaApplication.class)
.web(false)
.run(args);
}
@Bean
public SessionFactory<FTPFile> ftpSessionFactory() {
DefaultFtpSessionFactory sf = new DefaultFtpSessionFactory();
sf.setHost("localhost");
sf.setPort(port);
sf.setUsername("foo");
sf.setPassword("foo");
sf.setTestSession(true);
return new CachingSessionFactory<FTPFile>(sf);
}
@Bean
public FtpOutboundGatewaySpec ftpOutboundGateway() {
return Ftp.outboundGateway(ftpSessionFactory(),
AbstractRemoteFileOutboundGateway.Command.MGET, "payload")
.options(AbstractRemoteFileOutboundGateway.Option.RECURSIVE)
.regexFileNameFilter("(subFtpSource|.*1.txt)")
.localDirectoryExpression("'localDirectory/' + #remoteDirectory")
.localFilenameExpression("#remoteFileName.replaceFirst('ftpSource', 'localTarget')");
}
@Bean
public IntegrationFlow ftpMGetFlow(AbstractRemoteFileOutboundGateway<FTPFile> ftpOutboundGateway) {
return f -> f
.handle(ftpOutboundGateway)
.channel(c -> c.queue("remoteFileOutputChannel"));
}
}
外发网关部分成功 (mget 和 mput)
当你对多个文件执行操作（使用 mget 和 mput）时，有时在一个或多个文件传输之后会发生异常。在这种情况下（从 4.2 版本开始），会抛出一个 PartialSuccessException。除了常规的 MessagingException 属性（failedMessage 和 cause），此异常还有两个附加属性：
-
partialResults: 成功的传输结果。 -
derivedInput: 从请求消息生成的文件列表（例如，mput的本地文件）。
这些属性让你确定哪些文件成功传输，哪些没有成功传输。
在递归 mput 的情况下，PartialSuccessException 可能会有嵌套的 PartialSuccessException 实例。
考虑以下目录结构：
root/
|- file1.txt
|- subdir/
| - file2.txt
| - file3.txt
|- zoo.txt
如果异常发生在 file3.txt 上，网关抛出的 PartialSuccessException 具有 derivedInput，内容为 file1.txt、subdir 和 zoo.txt，以及 partialResults 为 file1.txt。它的 cause 是另一个 PartialSuccessException，其 derivedInput 为 file2.txt 和 file3.txt，partialResults 为 file2.txt。