When the platform is running and the resources plug-in is active, the workspace is represented by an instance of IWorkspace, which provides protocol for accessing the resources it contains. An IWorkspace instance represents an associated collection of files and directories in one or more file systems. You can access the workspace from the resources plug-in class (defined in org.eclipse.core.resources).
IWorkspace workspace = ResourcesPlugin.getWorkspace();
When the resources plug-in is not running, the workspace exists solely in the file system and is viewed or manipulated by the user via standard file-based tools. Let's look at what a workspace looks like on disk as we explain the resources plug-in API.
When you started the platform SDK, you were prompted to provide a workspace directory. This is the directory where various plug-ins store interesting metadata that is unique to a particular instance of the platform. By default, the resources plug-in stores each project in a sub-directory of the workspace directory. Within these subdirectories are the folders and files that each project contains.
Let's say your chose the directory c:\MySDK\workspace for your workspace. Inside this directory we find subdirectories named after the workspace's projects, MyWeb and MyServlet. These are called the projects' content directories. Content directories are created by the platform when the user creates a project.
Inside each directory, we find the files and folders within the project, laid out exactly the same as they are in the workspace's resource tree. All file names are the same, and the files' contents are the same whether accessed from the file system or from the workspace. The only surprise is the .project file, explained in a moment.
C:\MySDK\workspace (workspace root)
.metadata\ (platform metadata directory
MyWeb\ (project content directory for MyWeb)
.project
index.html
images\
logo.png
MyServlet\ (project content directory for MyServlet)
.project
src\
main.java
bin\
main.class
The platform has a special .metadata directory for holding platform internal information. The .metadata directory of a workspace is considered to be a "black box." Important information about the workspace structure, such as a project's references or a resource's properties, is stored in the metadata portion of the workspace and should only be accessed by tools through the platform API. These files should never be edited or manipulated using generic file system API.
In addition, each project has its own .project file, where metadata about the project is kept. This file is basically an on-disk equivalent of the information found in a project's IProjectDescription.
Apart from the .metadata directory and the .project files, the folders and files in the workspace directory are fair game for other tools. The files and folders can be manipulated by non-integrated tools, such as text editors and file system utilities. The only issue is that the user must be careful when editing these files both in the workbench and externally. (This is no different than when a user edits a file using two independent stand-alone tools.) The workbench provides refresh operations to reconcile the workspace view of resources with the actual state in the file system and there is an option to periodically refresh the workspace based on the state of the file system.
The resource API allows us to manipulate this resource tree in code. Here we will look at some code snippets for a quick taste of the resource API. The resource API is defined in a series of interfaces in org.eclipse.core.resources. There are interfaces for all of the resource types, such as IProject, IFolder, and IFile. Extensive common protocol is defined in IResource. We also make use of the org.eclipse.core.runtime interface IPath, which represents segmented paths such as resource or file system paths.
Manipulating resources is very similar to manipulating files using java.io.File. The API is based on handles. When you use API like getProject or getFolder, you are returned a handle to the resource. There is no guarantee or requirement that the resource itself exists until you try to do something with the handle. If you expect a resource to exist, you can use exists method to ensure this is the case.
To navigate the workspace from a plug-in, we must first obtain the IWorkspaceRoot, which represents the top of the resource hierarchy in the workspace.
IWorkspaceRoot myWorkspaceRoot = ResourcesPlugin.getWorkspace().getRoot();
Once we have a workspace root, we can access the projects in the workspace.
IProject myWebProject = myWorkspaceRoot.getProject("MyWeb");
// open if necessary
if (myWebProject.exists() && !myWebProject.isOpen())
myWebProject.open(null);
Before we can manipulate a project, we must open it. Opening the project reads the project's structure from disk and creates the in-memory object representation of the project's resource tree. Opening a project is an explicit operation since each open project consumes memory to represent the resource tree internally and open projects participate in various resource lifecycle events (such as building) which can be lengthy. In general, closed projects cannot be accessed and will appear empty even though the resources are still present in the file system.
You'll notice that many of these resource examples pass a null parameter when manipulating resources. Many resource operations are potentially heavyweight enough to warrant progress reporting and user cancellation. If your code has a user interface, you will typically pass an IProgressMonitor, which allows the resources plug-in to report progress as the resource is manipulated and allows the user to cancel the operation if desired. For now, we simply pass null, indicating no progress monitor.
Once we have an open project, we can access its folders and files, as well as create additional ones. In the following example we create a file resource from the contents of a file located outside of our workspace.
IFolder imagesFolder = myWebProject.getFolder("images");
if (imagesFolder.exists()) {
// create a new file
IFile newLogo = imagesFolder.getFile("newLogo.png");
FileInputStream fileStream = new FileInputStream(
"c:/MyOtherData/newLogo.png");
newLogo.create(fileStream, false, null);
// create closes the file stream, so no worries.
}
In the example above, the first line obtains a handle to the images folder. We must check that the folder exists before we can do anything interesting with it. Likewise, when we get the file newLogo, the handle does not represent a real file until we create the file in the last line. In this example, we create the file by populating it with the contents of logo.png.
The next snippet is similar to the previous one, except that it copies the newLogo file from the original logo rather than create a new one from its contents.
IFile logo = imagesFolder.getFile("logo.png");
if (logo.exists()) {
IPath newLogoPath = new Path("newLogo.png");
logo.copy(newLogoPath, false, null);
IFile newLogo = imagesFolder.getFile("newLogo.png");
...
}
Finally, we'll create another images folder and move the newly created file to it. We rename the file as a side effect of moving it.
...
IFolder newImagesFolder = myWebProject.getFolder("newimages");
newImagesFolder.create(false, true, null);
IPath renamedPath = newImagesFolder.getFullPath().append("renamedLogo.png");
newLogo.move(renamedPath, false, null);
IFile renamedLogo = newImagesFolder.getFile("renamedLogo.png");
Many of the resource API methods include a force boolean flag which specifies whether resources that are out of synch with the corresponding files in the file system will be updated anyway. See IResource for more information. You can also use IResource.isSynchronized to determine whether a particular resource is in synch with the file system.
In the sample resource tree, we've assumed that all of the project content directories are in the workspace directory underneath the platform root directory (C:\MySDK\workspace). This is the default configuration for projects. However, a project's content directory can be mapped to any arbitrary directory in some backing file system, perhaps even on a different machine.
The ability to map the location of a project independent of other projects allows the user to store the contents of a project in a place that makes sense for the project and the project team. A project's content directory should be considered "out in the open." This means that users can create, modify, and delete resources by using the workbench and plug-ins, or by directly using file system based tools and editors.
Resource path names are not complete file system paths. Resource paths are always based on the project's location (usually the workspace directory). To obtain the full file system path to a resource, you must query its location using IResource.getLocationURI. Howevever, you cannot use IProjectDescription.setLocation to change its location, because that method is just a simple setter for a data structure.
Conversely, if you want to get the corresponding resource object given a file system path, you can use IWorkspaceRoot.findFilesForLocationURI or IWorkspaceRoot.findContainersForLocationURI.
When we use the resources API to modify our workspace's resource tree, the files are changed in the file system in addition to updating our resource objects. What about changes to resource files that happen outside of the platform's API?
External changes to resources will not be reflected in the workspace and resource objects until detected by the resources plug-in. The resources plug-in also uses a mechanism appropriate for each particular native operating system for discovering external changes made in the file system. In addition, clients can use resource API to reconcile workspace and resource objects with the local file system quietly and without user intervention. The user can also explicitly force a refresh in the resource navigator view of the workbench.
Many of the methods in the resource APIs include a force parameter which specifies how resources that are out of sync with the file system should be handled. The API Reference for each method provides specific information about this parameter. Additional methods in the API allow programmatic control of file system refresh, such as IResource.refreshLocal(int depth, IProgressMonitor monitor). See IResource for information on correct usage and costs.
Plug-ins that wish to supply their own mechanism for periodically refreshing the workspace based on the state of the external file system may do so using the org.eclipse.core.resources.refreshProviders extension point. See Refresh providers for more information.