Working with the Eclipse FileSystem

During the 3.2 timeframe, the Eclipse platform team developed EFS: The Eclipse FileSystem . EFS is an abstract filesystem API, with implementations available for several 'filesystems' (or schemes that could be considered filesystemts) including local, FTP, zip files, in-memory-only, and even CVS.

The API is pluggable, and already as detailed on the EFS Wiki Homepage there are open-source implementations available.

The general idea behind EFS is to provide an abstraction away from the filesystem implementation to allow applications, like the Eclipse IDE, to read and write to a wide array of data stores (the Eclipse team is in process of moving from direct local filesystem references to EFS for Eclipse 3.3). This obviously has a wide degree of benefits, and thankfully for any Eclipse based product, it is a free API readily available.

To use EFS in your project, the first step is to include the org.eclipse.core.filesystem dependency to your plug-in definition. Once you have EFS as an available dependency, you simply need to know how to use it. Most interaction with EFS starts with a class called (surprise, surprise) org.eclipse.core.filesystem.EFS . This class provides an entry point for gaining access to the various filesystem proivders you have installed.

A cursory glance at the EFS class finds a few different methods: getLocalFileSystem() , getNullFileSystem() , getFileSystem(String scheme) , and getStore(URI scheme) . getLocal... and getNull... are just convenience methods wrapping the String parameterized getFileSystem method. The idea is that you should always have some access to the local filesystem, and you can also always work with the dead-end null file system. Calls to getFileSystem(String) return instances of the IFileSystem interface.

IFileSystem provides global detail about the filesystem (such as whether or not it can be written to or deleted from), and provides a handful of methods for getting references to IFileStore objects, which are really the heart of the EFS API.

IFileSystem fileSystem = EFS.getLocalFileSystem();
fileSystem.canDelete(); // returns true for me.
fileSystem.canWrite(); // returns true for me.
fileSystem.getScheme(); // return 'file', or EFS.SCHEME_FILE
fileSystem.isCaseSensitive(); // returns true for me on Linux.
fileSystem.getStore(URI.create("/")); // returns a IFileStore for '/' in my filesystem.

IFileStore has now shown up twice already; once in a convenience method on EFS , and now in a method on IFileSystem . IFileStore effectively represents a single file or directory in a filesystem; and in that sense is analogous to java.io.File . There are several key differences, however:

• IFileStore is abstracted to any type of filesystem (it is not restricted to local file stores)
• The API of IFileStore is arguably a richer API than java.io.File . There are methods for directly getting streams, as well as performing larger contextual operations, such as a recursive delete and recursive copy.
• All expensive operations in IFileStore are capable of consulting with an IProgressMonitor so they can be monitored and managed by the application.
• IFileStores from different file systems can interact, effectively allowing you to copy or move from one file system to another.

IFileStore objects can do several things. Let's look at copy. There are several ways to ask an IFileStore to copy. Let's see the options when the store is pointing to a directory:

IFileStore homeDir = fileSystem.getStore(URI.create("/home/rj/"));
IFileStore backupDir = fileSystem.getStore(URI.create("/home/rjbackup"));
// Will recursively copy the home directory to the backup directory, 
// but if any files are in place on the destination matching files to 
// be copied an exception will be thrown with that given file name.
homeDir.copy(backupDir, EFS.NONE, null);
 
// Will recursively copy the home directory to the backup 
directory, overwriting any files in the backup directory in the way.
homeDir.copy(backupDir, EFS.OVERWRITE, null);
 
// Will copy the immediate child files of the home directory to the 
// backup directory, not copying any directories recursively.
homeDir.copy(backupDir, EFS.SHALLOW, null);
 
// A combination of the shallow behavior and the overwrite behavior.
homeDir.copy(backupDir, EFS.SHALLOW | EFS.OVERWRITE, null);

Copy is just one feature, of course. Others include delete, move, and mkdir; they all work in a similar fashion:

// Will recursively move the home directory to the backup 
directory, overwriting any files in the backup directory in the way.
homeDir.move(backupDir, EFS.OVERWRITE, null);
 
// Deletes any existing 'homeDir'.
homeDir.delete(EFS.NONE, null);
 
// Says make the dir represented by this file store, but if any parents 
// need to be created and aren't there, throw an exception. If EFS.NONE 
// was used, it would be recursive (analogous to java.io.File.mkdirs())
homeDir.mkdir(EFS.SHALLOW, null);

If you want to write or read to a file, you can do so by retrieving a stream:

IFileStore file = fileSystem.getStore(URI.create("/home/rj/myfile.txt"));
InputStream in = file.openInputStream(EFS.NONE, null);
// Buffering should be applied if desired.
BufferedInputStream bin = new BufferedInputStream(in);
 
// rewrite the file.
OutputStream out = file.openOutputStream(EFS.NONE, null);
// or...
// append to the end of the file.
OutputStream out = file.openOutputStream(EFS.APPEND, null);
// Buffering should be applied if desired.
BufferedOutputStream bout = new BufferedOutputStream(out);

IFileStore objects are not necessarily connected to the underlying filesystem in any way. For that reason, getting file information (the name, last modified date, file attributes, and even whether or not it exists at all) is a separate operation (which is considered to be potentially expensive). For that reason, there is an additional object available on a file store called IFileInfo containing all of these various bits of information. It's simple to get:

IFileInfo info = store.fetchInfo();
// Or if you need a progress monitor, replace 'null':
IFileInfo info = store.fetchInfo(EFS.NONE, null);
 
boolean exists = info.exists();
String nme = info.getName();
long len = info.getLength();
long lastMod = info.getLastModified();
boolean isDir = info.isDirectory();

There are several ways to traverse the file system from a given point. From any file store you can either ask for its child file stores or its child file infos. This is an important distinction, as the method to retrieve IFileInfo objects can be optimized to retrieve several at a time (it is largely dependent on the implementation).

IFileInfo[] childInfos = store.childInfos(EFS.NONE, null);
IFileStore[] childStores = store.childStores(EFS.NONE, null);
String[] names = store.childNames(EFS.NONE, null);

A few final notes:

• This is not a comprehensive scan of the API. There are plenty corners and avenues that I didn't cover in this. (setting file attributes, native filesystem support, loading entire file trees) Check it out for yourself!
• As ofyet, as far as I know there is no way to get a list of all available filesystem implementations registered.