Apache Commons logo Commons VFS

Supported File Systems

Commons VFS directly supports the following file systems with the listed capabilities:

File System Directory Contents Authentication Read Write Create/Delete Random Version Rename
BZIP2 No No Yes Yes No No No No
File No No Yes Yes Yes Read/Write No Yes
FTP No Yes Yes Yes Yes Read No Yes
FTPS No Yes Yes Yes Yes Read No Yes
GZIP No No Yes Yes No No No No
HDFS Yes No Yes No No Read No No
HTTP Yes Yes Yes No No Read No No
HTTPS Yes Yes Yes No No Read No No
Jar No No Yes No No No No No
RAM No No Yes Yes Yes Read/Write No Yes
RES No No Yes Yes Yes Read/Write No Yes
SFTP No Yes Yes Yes Yes Read No Yes
Tar No No Yes No No No No No
Temp No No Yes Yes Yes Read/Write No Yes
WebDAV Yes Yes Yes Yes Yes Read/Write Yes Yes
Zip No No Yes No No No No No

Things from the sandbox

The following file systems are in development:

File System Directory Contents Authentication Read Write Create/Delete Random Version Rename
CIFS No Yes Yes Yes Yes Read/Write No Yes
mime No No Yes No No No No No

Naming

All filenames are treated as URIs. One of the consequences of this is you have to encode the '%' character using %25.
Depending on the filesystem additional characters are encoded if needet. This is done automatically, but might be reflected in the filename.

Examples

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

Many file systems accept a userid and password as part of the url. However, storing a password in clear text in a file is usually unacceptable. To help with that Commons VFS provides a mechanism to encrypt the password. It should be noted though, that this is not completely secure since the password needs to be unencrypted before Commons VFS can use it.

To create an encrypted password do:

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

where mypassword is the password you want to encrypt. The result of this will be a single line of output containing uppercase hex characters. For example,

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

Then cut the output returned and paste it into the URL as:

https://testuser:{D7B82198B272F5C93790FEB38A73C7B8}@myhost.com/svn/repos/vfstest/trunk

VFS treats a password enclosed in {} as being encrypted and will decrypt the password before using it.

Local Files

Provides access to the files on the local physical file system.

URI Format

[file://] absolute-path

Where absolute-path is a valid absolute file name for the local platform. UNC names are supported under Windows.

Examples

  • 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

Zip, Jar and Tar

Provides read-only access to the contents of Zip, Jar and Tar files.

URI Format

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]

Where arch-file-uri refers to a file of any supported type, including other zip files. Note: if you would like to use the ! as normal character it must be escaped using %21.
tgz and tbz2 are convenience for tar:gz and tar:bz2.

Examples

  • 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://anyhost/dir/mytar.tar.gz!/mytar.tar!/path/in/tar/README.txt
  • tgz:file://anyhost/dir/mytar.tgz!/somepath/somefile

gzip and bzip2

Provides read-only access to the contents of gzip and bzip2 files.

URI Format

gz:// compressed-file-uri

bz2:// compressed-file-uri

Where compressed-file-uri refers to a file of any supported type. There is no need to add a ! part to the uri if you read the content of the file you always will get the uncompressed version.

Examples

  • gz:/my/gz/file.gz

HDFS

Provides access to files in an Apache Hadoop File System (HDFS). This implementation inherits all of the restrictions of the Hadoop implementation. For example, the tests are disabled on Windows platforms as it is only supported when using Cygwin and Windows is not supported by Hadoop in production environments.

URI Format

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

Examples

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

HTTP and HTTPS

Provides access to files on an HTTP server.

URI Format

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

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

File System Options

  • proxyHost The proxy host to connect through.
  • proxyPort The proxy port to use.
  • cookies An array of Cookies to add to the request.
  • maxConnectionsPerHost The maximum number of connections allowed to a specific host and port. The default is 5.
  • maxTotalConnections The maximum number of connections allowed to all hosts. The default is 50.

Examples

  • http://somehost:8080/downloads/somefile.jar
  • http://myusername@somehost/index.html

WebDAV

Provides access to files on a WebDAV server.

URI Format

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

File System Options

  • versioning true if versioning should be enabled
  • creatorName the user name to be identified with changes to a file. If not set the user name used to authenticate will be used.

Examples

  • webdav://somehost:8080/dist

FTP

Provides access to the files on an FTP server.

URI Format

ftp://[ username[: password]@] hostname[: port][ relative-path]

Examples

  • ftp://myusername:mypassword@somehost/pub/downloads/somefile.tgz

By default, the path is relative to the user's home directory. This can be changed with:

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

FTPS

Provides access to the files on an FTP server over SSL.

URI Format

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

Examples

  • ftps://myusername:mypassword@somehost/pub/downloads/somefile.tgz

SFTP

Provides access to the files on an SFTP server (that is, an SSH or SCP server).

URI Format

sftp://[ username[: password]@] hostname[: port][ relative-path]

Examples

  • sftp://myusername:mypassword@somehost/pub/downloads/somefile.tgz

By default, the path is relative to the user's home directory. This can be changed with:

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

CIFS

Provides access to the files on a CIFS server, such as a Samba server, or a Windows share.

URI Format

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

Examples

  • smb://somehost/home

Temporary Files

Provides access to a temporary file system, or scratchpad, that is deleted when Commons VFS shuts down. The temporary file system is backed by a local file system.

URI Format

tmp://[ absolute-path]

Examples

  • tmp://dir/somefile.txt

res

This is not really a filesystem, it just tries to lookup a resource using javas ClassLoader.getResource() and creates a VFS url for further processing.

URI Format

res://[ path]

Examples

  • res:path/in/classpath/image.png
    might result in jar:file://my/path/to/images.jar!/path/in/classpath/image.png

ram

A filesystem which stores all the data in memory. You can configure the max size and a predicate (FileSelector). The predicate will be used to check if it is allowed to add a given file.

URI Format

ram://[ path]

Examples

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

mime

This filesystem can read mails and its attachements like archives.
If a part in the parsed mail has no name, a dummy name will be generated. The dummy name is: _body_part_X where X will be replaced by the part number.

URI Format

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

Examples

  • 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