Resources and the workspace
The central hub for your user's data files is called a workspace. You can think of the platform
workbench as a tool that allows the user to navigate and manipulate the workspace. The resources
plug-in provides APIs for creating, navigating, and manipulating resources in a workspace. The workbench
uses these APIs to provide this functionality to the user. Your plug-in can also use these APIs.
From the standpoint of a resource-based plug-in, there is exactly one workspace, and it is always open for
business as long as the plug-in is running. The workspace gets opened automatically when the resources
plug-in is activated, and closed when the platform is shut down. If your plug-in requires the resources
plug-in, then the resources plug-in will be started before your plug-in, and the workspace will be available to you.
The workspace contains a collection of resources. From the user's perspective, there are three different types
of resources: projects, folders, and files. A project is a collection of any number of
files and folders. It is a container for organizing other resources that relate to a specific area. Files and
folders are just like files and directories in the file system. A folder contains other folders or files.
A file contains an arbitrary sequence of bytes. Its content is not interpreted by the platform.
A workspace's resources are organized into a tree structure, with projects at the top, and folders and files
underneath. A special resource, the workspace root resource, serves as the root of the resource tree.
The workspace root is created internally when a workspace is created and exists as long as the workspace exists.
A workspace can have any number of projects, each of which can be stored in
a different location in some file system.
The workspace resource namespace is always case-sensitive and case-preserving.
Thus the workspace allows multiple sibling resources to exist with names that
differ only in case. The workspace also doesn't put any restrictions on valid characters
in resource names, the length of resource names, or the size of resources on disk.
Of course, if you store resources in a file system that is not case-sensitive, or that does
have restrictions on resource names, then those restrictions will show through
when you actually try to create and modify resources.
A sample resource tree
The tree below (represented in the workbench navigator view) illustrates a typical hierarchy of resources in a
workspace. The (implied) root of the tree is the workspace root. The projects are immediate children of the
workspace root. Each node (other than the root) is one of the three kinds of resources, and each has a name that
is different from its siblings.
Resource names are arbitrary strings (almost -- they must be legal file names).
The platform itself does not dictate resource names, nor does it specify any names with special
significance. (One exception is that you cannot name a project ".metadata"
since this name is used internally.)
Projects contain files and folders, but not other projects. Projects and folders
are like directories in a file system. When you delete a project, you will
be asked whether you want to delete all of the files and folders that it
contains. Deleting a folder from a project will delete
the folder and all of its children. Deleting a file is analogous to deleting a file in the file system.