EFS

Overview

The Eclipse File System (EFS) is an abstract file system API. It is used in the Eclipse platform to abstract away implementation details about what file system is used to store data in the workspace. This page is a repository of information for plug-in developers who are writing their own EFS implementations.

EFS for Platform Committers

See the EFS for Platform Committers page for information on working with EFS within platform code.

A word or two about URI

EFS makes heavy use of Uniform Resource Identifiers, as defined by RFC 2396. URI is used to uniquely identify some file or directory in a backing file system. If you are implementing EFS for your own protocol or file system, an important decision you need to make is how to define a URI encoding for your file system. If you are not familiar with it, start by perusing the URI spec - you should know the difference between absolute and relative, opaque and hierarchical URIs before proceeding.

While some file systems and protocols already have well-known mappings onto URI, others do not. Since the URI specification is quite flexible, the temptation is to simply convert your file system's path strings directly into URI. For example, a CVS path like extssh:johna@dev.eclipse.org:/cvsroot/eclipse is technically a legal URI. However, this is not the best representation. What you need is an absolute, hierarchical URI. The most important piece of the URI from the viewpoint of EFS is the path component. One should be able to navigate to a file's parent, siblings, and children by manipulating only the path portion of the URI and leaving the rest intact. In other words, the rest of the URI should define how to find the root of your file system, and the path segment defines how to navigate down a strict tree hierarchy from that root.

The relationship between EFS and IResource

The org.eclipse.core.resources plugin provides the Eclipse core tools API, including notions of workspace, projects, folders, and files (IWorkspace, IProject, IResource, etc). In Eclipse 3.2, this plug-in has been rewritten to sit on top of the EFS API. In other words, whenever the resources plugin needs to interact with the disk, it talks through the EFS API. If you have written your own file system implementation, you can completely control how and where resources are persisted on disk.

The relationship with EFS is not exposed directly in the resources plugin API. Instead, resources now use URI when referring to file system locations. When the resources plugin is provided with a URI, it looks up the corresponding IFileStore using EFS API. To create a project stored in your own custom file system, use the method IProjectDescription#setLocationURI(), followed by IProject#create(IProjectDescription, IProgressMonitor). To link a resource in another file system into an existing project, using IFolder#createLink(URI, int, IProgressMonitor) or IFile#createLink(URI, int, IProgressMonitor).

If you have an IFileStore or URI, and you want to determine if there is an existing resource corresponding to it, using IWorkspaceRoot#findFilesForLocationURI(URI) or IWorkspaceRoot#findContainersForLocationURI(URI).

Known Implementations

Are you working on an EFS implementation that you would like the community to know about? If so, add it to the list below. If possible, include CVS connection and contact information. You may find others in the community who are working on an implementation for the same kind of file system and may be able to pool resources.

Local file system

Plug-in id: org.eclipse.core.filesystem
CVS: dev.eclipse.org:/cvsroot/eclipse/org.eclipse.core.filesystem
Bugs: Eclipse Platform Resources
Contact: The platform-core-dev mailing list
Description: This EFS implementation is backed by the local fileystem through a combination of java.io API, and some optional native fragments. The implementation is product quality, and is available in Eclipse Platform 3.2 release or greater.

Remote System Explorer (SSH, FTP, dstore)

Plug-in id: org.eclipse.rse.eclipse.filesystem (requires RSE-runtime-core and providers to be installed)
CVS: dev.eclipse.org:/cvsroot/dsdp/org.eclipse.tm.rse/plugins/org.eclipse.rse.eclipse.filesystem
Bugs: DSDP Target Management Resources
Contact: The dsdp-tm-dev mailing list
Description: Remote System Explorer (RSE) is a complete toolkit for working on remote systems. Simply get it from the download page or update site (Soon also Europa Discovery Site). The RSE EFS provider is milestone quality and included in the downloads since TM 2.0M6. Provides remote file system access including credential storage management and caching through any registered RSE file system. Requires Eclipse-Platform 3.3M6 or later.

FTP

Plug-in id: org.eclipse.core.filesystem.ftp
CVS: dev.eclipse.org:/cvsroot/eclipse/platform-core-home/plugins/org.eclipse.core.filesystem.ftp
Bugs: Eclipse Platform Resources
Contact: The platform-core-dev mailing list
Description: This is a partial EFS implementation backed by the File Transfer Protocol (FTP). This implementation is not currently functional. You will need to create a KeyRing class with your FTP connection information. This plugin depends on the "team extras" FTP plug-in, found in the same repository at the path /platform-vcm-home/plugins/target/org.eclipse.ftp.

UI Examples: Zip and Memory file systems

Plug-in id: org.eclipse.ui.examples.filesystem
CVS: dev.eclipse.org:/cvsroot/org.eclipse/www/eclipse/platform-ui/plugins/org.eclipse.ui.examples.filesystem
Bugs: Eclipse Platform Resources
Contact: The platform-core-dev mailing list
Description: This plug-in contains two sample EFS implementations. The first is an EFS implementation that treats a single zip file as the backing file system. The second is an entirely in-memory file system that is useful in automated tests.

CVS

Plug-in id: org.eclipse.team.cvs.core
CVS: dev.eclipse.org:/cvsroot/eclipse/org.eclipse.team.cvs.core
Bugs: Eclipse Platform CVS
Contact: The platform-team-dev mailing list
Description: This plug-in contains an implementation of EFS that interacts with a file system in a CVS repository. This EFS implementation is used internally by the CVS plug-in, and should not be relied upon by other plug-ins. However, it makes a useful example for your own implementation.

HTTP

Plug-in id: com.capeclear.filesystem.http
CVS: developer.capeclear.com:/cvsroot/eclipse/httpfs/com.capeclear.filesystem.http
Bugs: See the Cape Clear Developer website for information on reporting bugs
Contact: Email John O'Shea
Description: This is a partial EFS implementation backed by the Hypertext Transfer Protocol (HTTP 1.1). It is read-only and does not support https:// URLs.

JArchive

Plug-in id: net.sourceforge.jarchive.eclipse.core
CVS: jarchive.cvs.sourceforge.net:/cvsroot/jarchive/
Bugs: http://sourceforge.net/tracker/?group_id=166983&atid=841130
Contact: mail us using http://sourceforge.net/projects/jarchive/ and select a developer.
Or: Email mtstorm
Description: This is a readonly EFS implementation for accessing archive files. The JArchive plugin allows developers to add their own archive implementations. The current implementation is readonly and we are working on write capabilities. I'm working now on the alfa release.

WSEFS

Plug-in id: org.tschirpke.wsefs.filesystem
Web: https://ssl.tschirpke.org/wsefs/trac/
Description: An EFS implementation that communicates via Web Services from the client running Eclipse to a server where the file system resides.

efs-cmis

Plug-in id: ro.savatech.eclipse.efs.cmis
Web: http://code.google.com/a/eclipselabs.org/p/efs-cmis/
Description: An EFS implementation that communicates with a Content Repository via the CMIS Web Services APIs. It is very much work in progress and was tested with the alfresco public server (http://cmis.alfresco.com). It uses the metro stack for accessing the webservices. It provides a way of browsing/manipulating a Content Repository's content from inside Eclipse.

Frequently asked questions

Is there support in the import wizards for EFS?

There is currently no generic import wizard for importing from an EFS implementation. You currently have to write your own import wizard for your file system type. There is a bug report for this - please CC yourself on the bug, and comment/vote on it if this is important to you. To get you started, take a look at WizardFileSystemResourceImportPage1, and FileStoreStructureProvider. This is a great opportunity to contribute something back to the platform!

What is FileSystemContributor.getURI(String) supposed to do?

The idea is that the user types some string into the text box in the wizard. The getURI method is called to convert the user's input into a URI that is appropriate for your file system. THe idea is to shield the end user from implementation details such as the URI encoding used by your file system. For example, a local file system contributor might convert "d:\foo\bar.txt" to "file:///d:\foo\bar".

What is FileSystem.getStore(IPath) supposed to do?

This method is really only intended for file systems that can be completed expressed as scheme/IPath pair (the local file system, for example). Many file systems have more elaborate information such as domain, etc, and files within such file systems cannot be expressed using IPath (which is just an array of uninterpreted string segments). If this is the case for you, you can return EFS.getNullFileSystem().getStore(path);. Clients should only be calling this method if they know that your file system works that way.

Can I programmatically create a project located on a non-local filesystem?

Yes, use this sequence:

 IProject project = ResourcesPlugin.getWorkspace().getRoot().getProject(projectName);
 IProjectDescription description = workspace.newProjectDescription(projectName);
 description.setLocationURI(projectURI);
 project.create(description, ...);

workspaceRoot.getProject(projectName) will work as expected for an existing non-local project.

Does EFS support notifications for file system changes?

Not yet, bug bug 112980 is open for this.

Using EFS

To use EFS in your project, the first step is to include the org.eclipse.core.filesystem dependency to your plug-in definition. see [Working with the Eclipse FileSystem], [Eclipse File System]