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.

Navigator view with sample workspace

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.