Apache Commons VFS – Using The API

Using The API

The FileSystemManager interface provides access to Commons VFS. Using this interface you can locate files and create file systems. There are a number of ways to obtain a FileSystemManager instance. The simplest is to use the static VFS.getManager() method, which returns the default Commons VFS implementation.

Once you have a FileSystemManager, you can use its resolveFile() methods to locate a file by name. For example:

FileSystemManager fsManager = VFS.getManager();
FileObject jarFile = fsManager.resolveFile("jar:lib/aJarFile.jar");

Each file is represented by a FileObject instance. Using this interface you can create or delete the file, list its children, read or write its content, and so on. For example:

// Locate the Jar file
FileSystemManager fsManager = VFS.getManager();
FileObject jarFile = fsManager.resolveFile("jar:lib/aJarFile.jar");

// List the children of the Jar file
FileObject[] children = jarFile.getChildren();
System.out.println("Children of " + jarFile.getName().getURI());
for (int i = 0; i < children.length; i++) {
    System.out.println(children[i].getName().getBaseName());
}

In some cases you might want to explicitely free resources allocated by the filesystem. You can do this by calling VFS.getManager().closeFileSystem(fs). If you use VFS as singleton (as described above) you should take care that this will close the filesystem for all threads.
In other words, do not close any globally used filesystem like the one for local files.

See the FileObject Javadocs for more detail.

Cache

Commons VFS uses a SoftRefFilesCache to release memory if a file is no longer used by the application.

This cache will return the same instance for a file as long as it is "strongly reachable" e.g. you hold a reference to this object. If the FileObject is no longer reachable, and the jvm needs some memory, it will be released.

There is also a internal cache of each file object avoid the need to access the network layer. Now its possible to configure this behviour through the use of CacheStrategy.
Do this on the DefaultFileSystemManager. For example: ((DefaultFileSystemManager) VFS.getManager()).setCacheStrategy(CacheStrategy.ON_CALL)

User Authentication

You can put the credentials into the url, but the drawback here is, that it is easily possible to get access to the password.

To solve you can use the UserAuthenticator

For example:

StaticUserAuthenticator auth = new StaticUserAuthenticator("domain", "username", "password");
FileSystemOptions opts = new FileSystemOptions();
DefaultFileSystemConfigBuilder.getInstance().setUserAuthenticator(opts, auth);

FileObject fo = VFS.getManager().resolveFile("smb://host/anyshare/dir", opts);

Internally the UserAuthenticator uses char arrays which will be zeroed before it is freed for garbage collection.Unhappily none of the current libraries use char arrays and so VFS has to create a string. Thus, the main advantage of this solution - security - is lost, but hey, thats not VFS fault ;-)

VFS calls UserAuthenticator.requestAuthentication each time it requires credentials, it depends on the filesystem implementation how often this might be. For example, with FTP this is on every connection, in SMB/JCIFS this is for EVERY OBJECT. It is up to you how long you will cache credentials of if you would like to provide a "save credentials" checkbox.

Examples

For an example of using the API, take a look at the classes in the example package.

Configuring Commons VFS

Commons VFS is represented using the FileSystemManager interface. There are a number of ways to create and configure a FileSystemManager instance.

The simplest method is to use the static VFS.getManager() method, which returns the default Commons VFS implementation.

This method will also automatically scan the classpath for a /META-INF/vfs-providers.xml file (also in jar files). If such a file is found Commons VFS uses it in addition to the default providers.xml. This allows you to start using a new filesystem by simply drop its implementation into the classpath. The configuration file format is described below.
Notice: Currently it is not allowed to override a already configured filesystem. Commons VFS throws an exception if there is already a filesystem for a scheme.

To configure Commons VFS programatically, you can create an instance of DefaultFileSystemManager and configure it manually. The default constructor DefaultFileSystemManager creates a manager that is completely empty. You will have to add file providers to it to make it do anything useful.

Here are the steps for using DefaultFileSystemManager:

Create a new instance.
Set the logger for the manager and all its components, using setLogger(). This step is optional, and if skipped, the manager will use the default logger provided by Commons Logging.
Add file providers, using addProvider().
Set the default provider, using setDefaultProvider(). This step is optional. See UrlFileProvider for a useful default provider.
Set the file replicator, using setReplicator(). This step is optional.
Set the temporary file store, using setTemporaryFileStore(). This step is optional.
Set the base file using setBaseFile(). The base file is used to resolve relative URI passed to resolveFile(). This step is optional.
Initialise the manager using init().

You should make sure that you call close() on the manager when you are finished with it.

The third method for configuring Commons VFS, is to configure it from a file. Create an instance of StandardFileSystemManager, and use its setConfiguration() method to set the location of the configuration file to use. The configuration file format is described below.

StandardFileSystemManager is a subclass of DefaultFileSystemManager, so you can also configure it programmatically, as described above.

Configuration File

The configuration file is an XML file. The root element of the configuration file should be a <providers> element. The <providers> element may contain:

Zero or more <provider> elements.
An optional <default-provider> element.
Zero or more <extension-map> elements.
Zero or more <mime-type-map> elements.

<provider>

The <provider> element defines a file provider. It must have a class-name attribute, which specifies the fully-qualified name of the provider class. The provider class must be public, and must have a public constructor with an FileSystemManager argument which allows the systems to pass the used filesystem manager.

The <provider> element may contain zero or more <scheme> elements, and zero or more <if-available> elements.

The <scheme> element defines a URI scheme that the provider will handle. It must have a name attribute, which specifies the URI scheme.

The <if-available> elements is used to disable the provider if certain classes are not present in the class-path. It must have a class-name attribute, which specifies the fully qualified name of a class to test for. If the class cannot be found, the provider is not registered.

<default-provider>

The <default-provider> element defines the default provider. It has the same format as the <provider> element.

<extension-map>

The <extension-map> element defines a mapping from a file's extension to the provider that should handle files with that extension. It must have an extension attribute, which specifies the extension, and a scheme attribute, which specifies the URI scheme of the provider.

<mime-type-map>

The <mime-type-map> element defines a mapping from a file's MIME type to the provider that should handle files with that MIME type. It must have an mime-type attribute, which specifies the MIME type, and a scheme attribute, which specified the URI scheme of the provider.

Below is an example configuration file:

<providers>
    <provider class-name="org.apache.commons.vfs2.provider.zip.ZipFileProvider">
        <scheme name="zip"/>
    </provider>
    <extension-map extension="zip" scheme="zip"/>
    <mime-type-map mime-type="application/zip" scheme="zip"/>
    <provider class-name="org.apache.commons.vfs2.provider.ftp.FtpFileProvider">
        <scheme name="ftp"/>
        <if-available class-name="org.apache.commons.net.ftp.FTPFile"/>
    </provider>
    <default-provider class-name="org.apache.commons.vfs2.provider.url.UrlFileProvider"/>
</providers>