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 头中提供。

与 ls 命令 的 -1 选项（使用 LIST 命令）不同，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，则输出消息的有效负载不再包含由于文件已存在而未获取的文件。以前，列表包含所有文件，包括已存在的文件。

用于确定远程路径的表达式应产生以 - 例如 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。有关更多信息，请参阅 模式 文档。

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）。

另请参阅 出站网关部分成功 (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属性定义“源”路径，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的derivedInput为file1.txt、subdir和zoo.txt，partialResults为file1.txt。它的cause是另一个PartialSuccessException，其derivedInput为file2.txt和file3.txt，partialResults为file2.txt。