|
如需使用最新稳定版本，请使用 Spring Integration 7.0.4！ |
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 命令，null 被视为客户端工作目录，符合 FTP 协议规定。
所有其他命令都必须提供 expression，以便根据请求消息评估远程路径。
当您扩展 DefaultFtpSessionFactory 并实现 postProcessClientAfterConnect() 回调时，可以使用 FTPClient.changeWorkingDirectory() 函数来设置工作目录。
使用nlst命令
版本 5 引入对 nlst 命令的支持。
nlst 列出远程文件名，仅支持一个选项：
-
-f: 不要对列表进行排序
由 nlst 操作产生的消息负载是一个文件名列表。
对nlst命令操作的远程目录信息在file_remoteDirectory头中提供。
与使用LIST命令的ls命令的-1选项不同，nlst命令会向目标 FTP 服务器发送NLST命令。
当服务器不支持LIST（例如由于安全限制）时，此命令非常有用。
nlst操作的结果是不包含其他详细信息的名称列表。
因此，框架无法判断实体是否为目录，从而无法执行过滤或递归列出等操作。
使用get命令
get 检索远程文件。
它支持以下选项：
-
-P: 保留远程文件的时间戳。 -
-stream: 将远程文件作为流检索。 -
-D: 传输成功后删除远程文件。 如果传输被忽略，则不会删除远程文件，因为FileExistsMode为IGNORE且本地文件已存在。
file_remoteDirectory 标头提供远程目录名称，file_remoteFile 标头提供文件名。
由 get 操作产生的消息负载是一个表示检索到的文件的 File 对象，或者当您使用 -stream 选项时为一个 InputStream。
-stream 选项允许将文件作为流进行检索。
对于文本文件，一个常见的用例是将此操作与 文件分割器 或 流转换器 结合使用。
当将远程文件作为流消费时，您需要在流消费完毕后负责关闭 Session。
为方便起见，Session 已提供在 closeableResource 头中，您可以通过 IntegrationMessageHeaderAccessor 上的便捷方法访问它。
以下示例展示了如何使用该便捷方法：
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，每个对象代表一个检索到的文件）。
从 5.0 版本开始，如果 FileExistsMode 为 IGNORE，输出消息的负载将不再包含因文件已存在而未获取的文件。
此前，列表包含所有文件，包括那些已存在的文件。 |
用于确定远程路径的表达式应产生以 - e.g. somedir/将获取其下完整的树结构somedir.
从 5.0 版本开始，递归 mget 结合新的 FileExistsMode.REPLACE_IF_MODIFIED 模式可用于定期将完整的远程目录树同步到本地。
此模式会替换本地文件的最后修改时间戳为远程时间戳，无论是否启用 -P（保留时间戳）选项。
|
使用递归 (
-R)该模式将被忽略，并假设为 如果某个子目录被过滤，则不会对该子目录进行额外的遍历。
通常，您会在 |
持久化文件列表过滤器现在有一个布尔属性 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命令
The 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命令
The mput 向服务器发送多个文件，仅支持一个选项：
-
-R: 递归。 发送目录及其子目录中的所有文件（可能经过过滤）。
消息负载必须是一个代表本地目录的 java.io.File（或 String）。
自 5.1 版本起，也支持 File 或 String 的集合。
此命令支持与 put 命令 相同的属性。
此外，本地目录中的文件可以使用 mput-pattern、mput-regex、mput-filter 或 mput-filter-expression 之一进行过滤。
该过滤器支持递归操作，只要子目录本身也通过过滤器即可。
未通过过滤器的子目录将不会被递归处理。
由 mput 操作产生的消息负载是一个 List<String> 对象（即，一组因传输而产生的远程文件路径的 List）。
另请参阅 出站网关部分成功 (mget 和 mput)。
版本 5.2 引入了 chmod 属性，允许您在上传后更改远程文件的权限。
您可以使用传统的 Unix 八进制格式（例如，600 仅允许文件所有者进行读写）。
在使用 Java 配置适配器时，可以使用 setChmodOctal("600") 或 setChmod(0600)。
仅当您的 FTP 服务器支持 SITE CHMOD 子命令时才适用。
使用rm命令
The rm 命令用于删除文件。
命令 rm 没有选项。
从 rm 操作生成的消息负载，如果移除成功则为 Boolean.TRUE，否则为 Boolean.FALSE。
file_remoteDirectory 标头提供远程目录，file_remoteFile 标头提供文件名。
使用mv命令
The mv 命令用于移动文件。
命令 mv 没有选项。
expression属性定义“源”路径，rename-expression属性定义“目标”路径。
默认情况下，rename-expression为headers['file_renameTo']。
该表达式求值结果不能为null或空的String。
如有必要，将创建所需的远程目录。
结果消息的负载为Boolean.TRUE。
file_remoteDirectory头提供原始远程目录，file_remoteFile头提供文件名。
新路径位于file_renameTo头中。
从版本 5.5.6 开始，remoteDirectoryExpression 可用于 mv 命令以方便使用。
如果“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 表达式，用于在传输过程中生成本地目录的名称。
评估上下文的根对象是请求消息但（注：原文"but"疑似为笔误或截断，此处直译）。
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 版本开始，setWorkingDirExpression()（在 XML 中为working-dir-expression）选项已提供于FtpOutboundGateway（在 XML 中为<int-ftp:outbound-gateway>）。
它允许您在运行时更改客户端工作目录。
该表达式会针对请求消息进行求值。
每次网关操作后都会恢复之前的工作目录。
使用 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 具有 derivedInput 的 file1.txt、subdir 和 zoo.txt，以及 partialResults 的 file1.txt。
其 cause 是另一个带有 derivedInput 的 file2.txt 和 file3.txt，以及 partialResults 的 file2.txt 的 PartialSuccessException。