当前位置：网站首页 > 技术文章 > 正文

程序员的福音 - Apache Commons VFS(上)

zhezhongyun 2025-05-08 22:24 40 浏览

此文是系列文章第十篇，前几篇请点击链接查看

程序猿的福音 - Apache Commons简介

程序员的福音 - Apache Commons Lang

程序员的福音 - Apache Commons IO

程序员的福音 - Apache Commons Codec

程序员的福音 - Apache Commons Compress

程序员的福音 - Apache Commons Exec

程序员的福音 - Apache Commons Email

程序员的福音 - Apache Commons Net

程序员的福音 - Apache Commons Collections

程序员的福音 - Apache Commons HttpClient

Apache Commons VFS 为访问各种不同的文件系统提供了一个统一API。支持本地磁盘、HTTP服务器、FTP服务器、HDFS文件系统、ZIP压缩包等，支持自行扩展存储客户端。

commons-vfs 目前最新版本是 2.9.0，最低要求 Java8 以上。

maven坐标如下：

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-vfs2</artifactId>
    <version>2.9.0</version>
</dependency>

下面我将从整体结构，使用方式，自定义扩展等方面简单介绍一下。

—

简介

VFS 对所有文件名都被视为 URI，这样就必须使用 %25 对“%”字符进行编码。

示例

file:///somedir/some%25file.txt

许多文件系统接受用户ID和密码作为 url 的一部分。为了安全性考虑，Commons VFS 提供了一种加密机制。不过这并不是完全安全的，因为在Commons VFS 使用密码之前，还是需要对密码进行解密的。

创建加密密码，需要执行以下操作：

$ java-cp commons-vfs-2.0.jar org.apache.commons.vfs2.util.EncryptUtil encrypt mypassword

其中 mypassword 是要加密的密码。结果是一行十六进制字符串。例如

$ java-cp commons-vfs-2.0.jar org.apache.commons.vfs2.util.EncryptUtil encrypt WontUBee9

$ D7B82198B272F5C93790FEB38A73C7B8

然后将输出粘贴到 URL 中，如下所示：

https://testUser：{D7B82198B272F5C93790FEB38A73C7B8}@test.com/test

VFS 将 {} 中包含的密码视为已加密，并将在使用密码之前对其进行解密。

Commons VFS 目前支持以下几种文件系统的访问

1. 本地文件

提供对本地物理文件系统上的文件的访问。

URI格式

[file://]absolute-path

其中绝对路径是本地平台的有效绝对文件名。Windows 下支持 UNC 名称。

示例

file:///home/someuser/somedir

file:///C:/Documents and Settings

file://///somehost/someshare/afile.txt

/home/someuser/somedir

c:\program files\some dir

c:/program files/some dir

2. Zip, Jar and Tar

提供对Zip、Jar和Tar文件内容的只读访问，需要单独引入 commons-compress 包。

URI格式

zip://arch-file-uri[!absolute-path]

jar://arch-file-uri[!absolute-path]

tar://arch-file-uri[!absolute-path]

tgz://arch-file-uri[!absolute-path]

tbz2://arch-file-uri[!absolute-path]

注意：如果您想使用 ! 作为普通字符，必须使用 %21进行转义。

tgz 和 tbz2 是 tar:gz 和 tar:bz2 简写形式

示例

jar:../lib/classes.jar!/META-INF/manifest.mf

zip:http://somehost/downloads/somefile.zip

jar:zip:outer.zip!/nested.jar!/somedir

jar:zip:outer.zip!/nested.jar!/some%21dir

tar:gz:http://host/my.tar.gz!/my.tar!/path/in/R.txt

tgz:file://host/dir/my.tgz!/somepath/somefile

3. gzip and bzip2

提供对gzip和bzip2文件内容的只读访问，需要单独引入 commons-compress

URI格式

gz://compressed-file-uri

bz2://compressed-file-uri

示例

gz:/my/gz/file.gz

4. HDFS

提供对 apache hadoop 文件系统（HDFS）中文件的读写访问。在 Windows 上，集成测试在默认情况下是禁用的，因为它需要二进制文件。需要单独引入 HDFS 相关依赖

<dependency>
    <groupId>org.apache.hadoop</groupId>
    <artifactId>hadoop-hdfs-client</artifactId>
    <version>3.3</version>
    </dependency>
<dependency>
    <groupId>org.apache.hadoop</groupId>
    <artifactId>hadoop-common</artifactId>
    <version>3.3</version>
</dependency>
<dependency>
    <groupId>org.apache.hadoop</groupId>
    <artifactId>hadoop-hdfs</artifactId>
    <version>3.3</version>
</dependency>

URI格式

hdfs://hostname[:port][absolute-path]

示例

hdfs://somehost:8080/downloads/some_dir

hdfs://somehost:8080/downloads/some_file.ext

5. HTTP and HTTPS

提供对 HTTP 服务器上文件的访问，需要依赖 HttpClient，同时支持HttpClient 3，HttpClient 4，HttpClient 5 版本，只需要引入其中一个版本的依赖即可。

URI格式

http://[username[:password]@]hostname[:port][absolute-path]

https://[username[:password]@]hostname[:port][absolute-path]

额外可选参数

proxyHost：要连接的代理主机。

proxyPort：要使用的代理端口。

proxyScheme：要使用的代理方案（http/https）。

cookies：要添加到请求的 cookies 数组。

maxConnectionsPerHost：允许连接到特定主机和端口的最大连接数。默认值为5。

maxTotalConnections：所有主机允许的最大连接数。默认值为50。

keystoreFile：SSL连接的密钥库文件。

keystorePass：密钥库密码。

keystoreType：密钥库类型。

示例

http://somehost:8080/downloads/somefile.jar

http://myusername@somehost/index.html

6. WebDAV

通过 commons-vfs2-jackrabbit1 和 commons-vfs2-jackrabbit2 模块提供对 WebDAV 服务器上文件的访问。

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-vfs2-jackrabbit1</artifactId>
    <version>2.9.0</version>
</dependency>

URI格式

webdav://[username[:password]@]hostname[:port][absolute-path]

额外可选参数

versioning ：如果应启用版本控制，则版本控制为 true

creatorName：要通过更改文件来标识的用户名。如果未设置，将使用用于身份验证的用户名。

示例

webdav://somehost:8080/dist

7. FTP and FTPS

提供对FTP服务器上文件的访问。依赖 commons-net

URI格式

ftp://[user[:pass]@]host[:port][relative-path]

示例

ftp://user:pass@somehost/pub/somefile.tgz

默认情况下，路径相对于用户的主目录。可通过以下方式进行更改：

FtpFileSystemConfigBuilder.getInstance().setUserDirIsRoot(options, false);

8. SFTP

提供对 SFTP 服务器（即 SSH 或 SCP 服务器）上的文件的访问。需要添加如下依赖

<dependency>
    <groupId>com.jcraft</groupId>
    <artifactId>jsch</artifactId>
    <version>0.1.55</version>
</dependency>

URI格式

sftp://[user[:pass]@]hostname[:port][relative-path]

示例

sftp://user:pass@somehost/pub/file.tgz

默认情况下，路径相对于用户的主目录。可通过以下方式进行更改：

FtpFileSystemConfigBuilder.getInstance().setUserDirIsRoot(options, false);

9. Temporary Files

提供对临时文件系统的访问，该文件系统在 Commons VFS 关闭时被删除。临时文件系统由本地文件系统支持

URI格式

tmp://[absolute-path]

示例

tmp://dir/somefile.txt

10. RAM

在内存中存储所有数据的文件系统（每个文件内容一个字节数组）

URI格式

ram://[path]

额外可选参数

maxsize：最大文件系统大小（所有文件内容的总字节数）

示例

ram:///any/path/to/file.txt

11. Resource

这实际上不是一个文件系统，它使用 ClassLoader.getResource() 查找资源，并创建一个 VFS url 以供进一步处理

URI格式

res://[path]

示例

res://path/in/image.png

将会转换为 ->

jar:file://my/path/images.jar!/path/in/image.png

12. CIFS

提供对 CIFS 服务器（如 Samba服务或 Windows共享）的访问。

官方还在开发中（截止本文发布时间2021-08-22）

URI格式

smb://[username[:password]@]hostname[:port][absolute-path]

示例

smb://somehost/home

13. MIME

可以读取邮件及其附件，比如归档文件。如果已解析邮件中的某个部分没有名称，则将生成一个伪名称。虚拟名称是：_body_part_X，其中X将被零件号替换。

官方还在开发中（截止本文发布时间2021-08-22）

URI格式

mime://mime-file-uri[!absolute-path]

示例

mime:file:///your/path/mail/anymail.mime!/

mime:file:///your/path/mail/anymail.mime!/filename.pdf

mime:file:///your/path/mail/anymail.mime!/_body_part_0

14. 自定义扩展

Commons VFS 接口支持开闭原则，允许开发者在不改变原有类的基础上自行扩展自己的实现，如亚马逊S3文件，阿里云文件等。只需在类路径下创建"
META-INF/vfs-providers.xml"文件，添加额外的配置并编写类实现 VFS 对应的接口。具体扩展方式将在下章节做介绍。

—

整体结构

FileSystemManager：管理一组文件系统。此接口用于按名称从这些文件系统之一中定位获取
org.apache.commons.vfs2.FileObject 。

FileProvider：文件提供者。每个文件提供者负责处理特定 URI 的文件。

FileNameParser：提供将文件名解析为
org.apache.commons.vfs2.FileName 的方法。

FileSystem：一个文件系统，由文件的层次结构组成。

FileObject：代表一个文件，用于访问文件的内容和结构。有两种类型的文件：文件夹，包含其他文件；普通文件，包含数据或内容。一个文件夹可能没有任何内容，普通文件不能包含其他文件。

FilesCache：文件缓存接口。VFS 内置一下几种实现，SoftRefFilesCache（软引用，默认值），WeakRefFilesCache（弱引用），DefaultFilesCache（没有过期和限制），LRUFilesCache（LRU实现，默认容量100个），NullFilesCache（空实现，不做任何缓存）。

FileSelector：该接口用于查找子文件时定义选择规则，使用方式 FileObject.findFiles(FileSelector) 。VFS 内置了 7 种选择器。

VFS 加载文件流程大致如下：

FileSystemManager 解析文件名，通过文件名中的协议（如ftp://中的ftp）获取对应 FileProvider 对象，FileProvider 通过 FileNameParser 对象解析文件名获取对应的 FileSystem 对象，通过 FileSystem 对象的 resolveFile 方法获取文件（默认先从缓存中查找，不存在再调用 createFile 方法创建 FileObject 对象，FileObject 就是实体文件的抽象，提供读取和修改等相关能力）

主要类图结构如下

—

使用方式

1. 文件属性

// 获取默认FileSystemManager
FileSystemManager fsMgr = VFS.getManager();
String path = "D:/test/abc";
// 获取的是 LocalFileObject 实现
FileObject fo = fsMgr.resolveFile(path);
println(fo.getFileSystem()); // LocalFileSystem
if (!fo.exists()) {
    println("fo not exists");
    return;
}
println("parent："+fo.getParent().toString());// "file:///D:/"
println("name："+fo.getName());// "file:///D:/test"
println("path："+fo.getPath());// "D:\test"
println("pubURI："+fo.getPublicURIString());// "file:///D:/test"
println("URI："+fo.getURI().toString());// "file:///D:/test"
println("URL："+fo.getURL());// "file:///D:/test"
boolean isFile = fo.isFile();
boolean isFolder = fo.isFolder();
// 是否符号链接
boolean isSymbolic = fo.isSymbolicLink();
boolean executable = fo.isExecutable();
boolean isHidden = fo.isHidden();
println("type："+fo.getType());
// 应该放到finally块中关闭，为了便于阅读直接在此关闭了
// 会同时关闭FileContent并释放FileObject
fo.close();
// 关闭文件系统，释放连接，清除缓存等
fsMgr.close();

2. 读取文件内容

// 读取文件内容
// 支持获取字符串，流，字节数组等
FileSystemManager fsMgr = VFS.getManager();
String path = "E:\\yuanzhy\\yyhc.py";
FileObject fo = fsMgr.resolveFile(path);
if (fo.isFile()) {
    FileContent fc = fo.getContent();
    // fc.getInputStream();
    // fc.getByteArray();
    // 获取内容 - 字符串形式
    String content = fc.getString("UTF-8");
    println(content);
}
// 在finally或者try-resources中关闭资源
fo.close();
fsMgr.close();

3. 读取文件属性

读取文件只读的属性信息

只有本地 Jar文件和 HDFS文件支持此功能，其他类型文件获取的为空

jar 属性就是 manifest 中的属性

HDFS 支持的属性都在 HdfsFileAttributes 枚举中

访问时间：
HdfsFileAttributes.LAST_ACCESS_TIME

块大小：
HdfsFileAttributes.BLOCK_SIZE

用户组：HdfsFileAttributes.GROUP

所有者：HdfsFileAttributes.OWNER

操作权限：
HdfsFileAttributes.PERMISSIONS

文件大小：HdfsFileAttributes.LENGTH

修改时间：
HdfsFileAttributes.MODIFICATION_TIME

FileSystemManager fsMgr = VFS.getManager();
String path = "D:/test/a.txt";
FileObject fo = fsMgr.resolveFile(path);
if (fo.isFile()) {
    FileContent fc = fo.getContent();
    // 获取只读的文件属性
    Map<String, Object> attrs = fc.getAttributes();
    println(fc.getAttributes());
}
// 在finally或者try-resources中关闭资源
fo.close();
fsMgr.close();

4. 设置文件权限

设置文件属性，如可读可写可执行等，只有本地文件和 SFTP 上的文件支持此功能

FileSystemManager fsMgr = VFS.getManager();
String path = "D:/test/a.txt";
FileObject fo = fsMgr.resolveFile(path);
if (fo.isFile()) {
    fo.setWritable(true, true);
    fo.setExecutable(true, true);
}
// 在finally或者try-resources中关闭资源
fo.close();
fsMgr.close();

5. 读取目录

// 主要是获取子文件
FileSystemManager fsMgr = VFS.getManager();
String path = "D:/test";
FileObject fo = fsMgr.resolveFile(path);
if (fo.isFolder()) {
    // 获取所有子文件
    FileObject[] foArr = fo.getChildren();
    // 获取子文件（名称为test）
    FileObject test = fo.getChild("a.txt");
    // 从所有后代中获取类型是文件的文件
    FileObject[] files = fo.findFiles(Selectors.SELECT_FILES);
}
// 在finally或者try-resources中关闭资源
fo.close();
fsMgr.close();

6. 删除

目录可通过参数删除部分子文件。只有本地文件、内存文件、FTP、SFTP、HDFS支持删除

FileSystemManager fsMgr = VFS.getManager();
String path = "D:/test/a.txt";
FileObject fo = fsMgr.resolveFile(path);
if (fo.isFolder()) {
    // 删除此文件和所有子文件, 返回删除的数量
    fo.deleteAll(); // 同fo.delete(Selectors.SELECT_ALL);
    // 只删除所有子文件
    fo.delete(Selectors.EXCLUDE_SELF);
    // 只删除直接子文件和空目录
    fo.delete(Selectors.SELECT_CHILDREN);
    // 只删除文件
    fo.delete(Selectors.SELECT_FILES);
    // 只删除空的子目录
    fo.delete(Selectors.SELECT_FOLDERS);
    // 删除目录本身（如果包含子文件则删除失败返回0）
    fo.delete(Selectors.SELECT_SELF);
    // 目录不为空则删除失败返回false
    boolean suc = fo.delete();
} else if (fo.isFile()) {
    // 删除文件本身
    boolean suc = fo.delete();
}
// 在finally或者try-resources中关闭资源
fo.close();
fsMgr.close();

7. 拷贝文件

// 将文件内容写入其他地方
FileSystemManager fsMgr = VFS.getManager();
String path = "D:/test/a.txt";
FileObject fo = fsMgr.resolveFile(path);
if (fo.isFile()) {
    FileContent fc = fo.getContent();
    // 支持写入输出流，FileContent和FileObject中
    // fc.write(FileObject);
    // fc.write(FileContent);
    // 相当于下载到 D:/test/a.txt
    fc.write(new FileOutputStream("E:/test/a.txt"));
}
// 在finally或者try-resources中关闭资源
fo.close();
fsMgr.close();

8. 修改文件

新增or修改内容。只有本地文件、内存文件、FTP、SFTP、GZip、bz2、HDFS支持，其中只有本地文件、内存文件、FTP、SFTP支持追加写，GZip、bz2、HDFS 只支持覆盖写。

FileSystemManager fsMgr = VFS.getManager();
String path = "D:/test/a.txt";
FileObject fo = fsMgr.resolveFile(path);
fo.createFile();
if (fo.isFile()) {
    FileContent fc = fo.getContent();
    OutputStream os = fc.getOutputStream();
    if (fo.isWriteable()) {
        // 覆盖写入
        IOUtils.write("测试", os, "UTF-8");
        os.close();
    }
    try {
        // 追加写
        os = fc.getOutputStream(true);
        IOUtils.write("追加数据", os, "UTF-8");
    } catch (FileSystemException e) {
        // 不支持追加写入
        System.err.println("不支持追加写入");
    }
}
// 在finally或者try-resources中关闭资源
fo.close();
fsMgr.close();

9. 随机读写

随机只读：本地文件、内存文件、FTP、SFTP、HDFS、HTTP支持

随机读写：本地文件、内存文件支持

FileSystemManager fsMgr = VFS.getManager();
String path = "D:/test/a.txt";
FileObject fo = fsMgr.resolveFile(path);
if (fo.isFile()) {
    FileContent fc = fo.getContent();
    try {
        RandomAccessContent rac = fc.getRandomAccessContent(RandomAccessMode.READ);
        // ... ...
    } catch (FileSystemException e) {
        // 不支持RandomAccessMode.READ
    }
}
// 在finally或者try-resources中关闭资源
fo.close();
fsMgr.close();

10. 更改缓存实现

StandardFileSystemManager fsMgr = new StandardFileSystemManager();


// 手动处理缓存数据。调用 FileObject#refresh() 来刷新对象数据
fsMgr.setCacheStrategy(CacheStrategy.MANUAL);
// 每次从 FileSystemManager#resolveFile 请求文件时刷新数据。
// fsMgr.setCacheStrategy(CacheStrategy.ON_RESOLVE);
// 每次在 fileObject 上调用方法时刷新数据。仅当您确实需要最新信息时才使用此设置，因为此设置会造成重大性能损失。
// fsMgr.setCacheStrategy(CacheStrategy.ON_CALL);


// 设置缓存实现为LRU
fsMgr.setFilesCache(new LRUFilesCache());
fsMgr.init();
FileObject fo = fsMgr.resolveFile("D:/test/a.txt");
// ... ...

11. 文件监听

监听文件创建，修改或删除

public class ListenersDemo {
    @Test
    public void test() throws IOException {
        // 监听文件创建，修改或删除
        FileSystemManager fsMgr = VFS.getManager();
        String path = "D:/test/a.txt";
        FileObject fo = fsMgr.toFileObject(new File(path));
        // 添加监听器
        fo.getFileSystem().addListener(fo, new MyListener());
        if (!fo.exists()) {
            fo.createFile();
        }
        fo.setWritable(false, false);
//        fo.delete();
        fo.close();
        fsMgr.close();
    }


    private class MyListener implements FileListener {
        @Override
        public void fileCreated(FileChangeEvent event) throws Exception {
            println("fileCreated："+event.getFileObject().getName());
        }
        @Override
        public void fileDeleted(FileChangeEvent event) throws Exception {
            println("fileDeleted："+event.getFileObject().getName());
        }
        @Override
        public void fileChanged(FileChangeEvent event) throws Exception {
            println("fileChanged："+event.getFileObject().getName());
        }
    }
}

—

总结

Commons VFS 拥有统一的文件系统访问 API，使用一套代码可以轻松的实现不同文件系统的读写操作，对于一些场景（比如同时支持多种存储系统，或者存储系统可以根据部署情况动态配置）来说还是非常实用的，由于其接口的抽象性设计可以非常方便的扩展以支持其他文件系统，有对应需求可以考虑使用。

由于篇幅原因，关于自定义扩展的方法我将在下一篇中再给大家做详细讲解。

后续章节我将继续给大家介绍commons中其他好用的工具类库，期待你的关注。

HTML meta scheme 属性

上一篇：angularjs应用prerender.io 搜索引擎优化实践
下一篇：如何实现一个高性能的对象存储(OSS)

程序员的福音 - Apache Commons VFS(上)

相关推荐

漏洞系列一一看我一招征服漏洞 SSRF

Web前端需要学什么?Web前端开发需要学习哪些?

接口测试遇到500报错?别慌，你的头部可能有点问题

前端Flex布局可视化布局工具介绍，vue和html5快速设计利器

「资讯」为强迫用户使用Edge浏览器，微软又出新招数

HTML 简介（html简介及优缺点）

HBuilderX，uni-app创建HTML5项目，同时支持浏览器和移动端

现在页面实时聊天都使用Websocket技术实现吗?

关于HTML5被简称做H5，你怎么看?（html5缩写）

在SpringBoot+Vue3项目中通过Nginx代理WebSocket实现跨域通信