Commons VFS - Supported File Systems

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