Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

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.

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 in 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.

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.

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.

Back to the top