FTP 出站网关
FTP出站网关提供了一组有限的命令，用于与远程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 属性来使用它们。
使用 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 操作返回的消息载荷是一个 String，表示传输完成后文件在服务器上的完整路径。
版本 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> 对象（即传输产生的远程文件路径的 List）。
版本 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 属性定义了“源”路径，而 rename-expression 属性定义了“目标”路径。默认情况下，rename-expression 为 headers['file_renameTo']。此表达式的求值结果不得为 null 或空 String。如有必要，系统将创建所需的远程目录。结果消息的有效载荷为 Boolean.TRUE。file_remoteDirectory 标头提供原始远程目录，file_remoteFile 标头提供文件名。新路径位于 file_renameTo 标头中。
从 5.5.6 版本开始，为了方便起见，mv 命令中可以使用 remoteDirectoryExpression。如果“源”文件不是完整文件路径，则使用 remoteDirectoryExpression 的结果作为远程目录。对于“目标”文件同样适用，例如，如果任务只是重命名某个目录中的远程文件。
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（XML 中为 <int-ftp:outbound-gateway>）提供了 setWorkingDirExpression() 选项（XML 中为 working-dir-expression）。该选项允许您在运行时更改客户端的工作目录。表达式将根据请求消息进行评估。每次网关操作后，先前的工作目录将被恢复。
使用 Java 配置进行配置
以下 Spring Boot 应用程序展示了如何通过 Java 配置来配置出站网关的示例：
@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 将包含 file1.txt、subdir 和 zoo.txt 作为 derivedInput，以及 file1.txt 作为 partialResults。其 cause 是另一个 PartialSuccessException，该异常的 derivedInput 为 file2.txt 和 file3.txt，partialResults 为 file2.txt。