Support Logical Resources

This is the plan item:

"The Eclipse Platform supports a strong physical view of projects, files, and folders in the workspace. However, there are many situations where a physical view is not the most salient or useful for many purposes. In some cases, multiple distinct objects happen to be stored in a single file, like an archive. Conversely, in other cases, something that is logically a single object is stored across multiple files. This discrepancy between logical and physical creates problems for common operations such as searching, comparing, and versioning, which need to work in the physical realm. Eclipse should support some way of mapping between a logical view and the physical organization of files on disk."

Last Modified: July 2nd, 2003

Motivation

By definition Eclipse supports logical resources. It's a "an open extensible IDE for anything and nothing in particular". The applications that are built with it can be tailored to a particular problem domain and the workbench extensions can be used to provide support for any logical model. What Eclipse really doesn't support is integrating tools at the logical model. In order to integrate two plugins into Eclipse either the two plugins have to know about each other, or both plugins have to depend on some common plugin. While the first option is satisfactory for a few cases, the second case is the most common and the most problematic. To illustrate, the Eclipse SDK contains several plugins that are based on the Resources plugin (e.g. Team, Search, Compare, JDT). When an application is packaged based on the SDK, because the plugins in the SDK are resource based that is the common integration point between plug-ins.

As you will see later, even the users of the SDK (JDT+CVS+Resources) can observe some of the problems associated with the lack of support for logical resources and the implicit mapping to physical resources. The lack of a logical integration point causes the co-existance of plugins in Eclipse to be error prone for the user. The next sections will examine the relationships between logical and physical resources and outline the visible problems with Eclipse 3.0.

Existing Bugs

Bug 32582 logical to physical mapping problem , 1 model element = 2 Files problem
Bug 3979 [CVS Decorator] show version info works incorrectly for sub packages (1GFDIEB)

Logical Resources Defined

Whereas logical resources are elements of the application that model the data/processes of a particular problem domain, the physical resources are the file system resources (e.g. files and folders) into which an application will eventually transform their application model for storage. Applications that don't use file system resources are not being considered as part of this plan item. For example, an application that stores it's application data directly into a database.

The following table enumerates concrete examples of how logical and physical resources are used in current applications integrated into Eclipse.

Table 1: Example logical to physical uses

Complaints

The following complaints are representative of bug reports and requirements received from several Eclipse users and developers.

Complaint 1: Not very adaptable

Object contributions and decorators are key mechanisms for providing rich integration between tools. Using object contributions and adaptable objects, any plugin can provide actions and decorators that will show in another plugin's view.

Since IResource is the lowest common integration class and is strongly mapped to its physical storage as files and folders, the integration point for actions and decorators cannot be the logical types in the view. The actions will consequently use the adaptable type from the selection to perform the action or the decorator the resource from the getImage request.

Here is an example to illustrate the problem with the CVS plugin. When running a CVS commit action in the packages view the action doesn't know that the IFolder is a Java package and is a shallow namespace. It will use the selection and traverse the selected IContainer using IContainer.members() and commit all child resources. This is the same when the CVS outgoing decorator is shown on a package. It will reflect the deep outgoing state of the IContainer. This can lead to unexpected behavior because the user expected the action to run on the model that the action was displayed on.

Example object contribution for the CVS commit action:

<extension point="org.eclipse.ui.popupMenus">
 <objectContribution
  objectClass="org.eclipse.core.resources.IResource"
  adaptable="true"
  id="org.eclipse.team.ccvs.ui.IResourceContributions">
 <filter
  name="projectPersistentProperty"
  value="org.eclipse.team.core.repository=org.eclipse.team.cvs.core.cvsnature">
 </filter>
 <action
  label="Commit"
  tooltip="Commit resource to CVS repository"
  class="org.eclipse.team.internal.ccvs.ui.actions.CommitAction"
  menubarPath="team.main/group3"
  id="org.eclipse.team.ccvs.ui.commit">
 </action>
 <objectContribution>
</extension>

Example code run in the commit action to calculate the resources to commit:

public static Object[] getSelectedAdaptables(ISelection selection)    {
  ArrayList result = null;
  if (!selection.isEmpty()) {
    result = new ArrayList();
    Iterator elements = ((IStructuredSelection) selection).iterator();
    while (elements.hasNext()) {
      Object adapter = getAdapter(elements.next(), IResource.class);
      if (c.isInstance(adapter)) {
        result.add(adapter);
      }
    }
   }
   if (result != null && !result.isEmpty()) {
   return (Object[])result.toArray((Object[])Array.newInstance(IResource.class, result.size()));
  }
  return (Object[])Array.newInstance(IResource.class, 0);
}

Example code for defining an IResource adaptable decorator:

<extension
  point="org.eclipse.ui.decorators">
    <decorator objectClass="org.eclipse.core.resources.IResource"
     adaptable="true"
     label="%DecoratorStandard.name"
     state="false"
     lightweight= "true"
     quadrant = "BOTTOM_RIGHT"
     class="org.eclipse.team.internal.ccvs.ui.CVSLightweightDecorator"
     id="org.eclipse.team.cvs.ui.decorator">
    <description>
      %DecoratorStandard.desc
    </description>
  </decorator>
</extension>

Complaint 2: Decorators

When the CVS decorator decorates a logical container in a view, the desire is to decorate parents with the dirty indicator if one or more of their logical children are dirty. To do this properly, the decorator would need to query the dirty status of each of the logical children of the container. This can be a costly operation as each child may itself be a logical container. We have optimized the dirty decoration by caching folder dirty states. This optimization becomes far more complicated with logical models where the caching must be based on this alternate model (i.e. the state must be cached for each model).

In addition, often decorators rely on IResource change events to re-calculate some new state. In the case of a logical elements representing several physical resources there is no easy way of associated a IResource change event to its files and the actual logical element.

Complaint 3: Presentation of mixed logical models

It would be nice to see the Java logical view in the Synchronize view, in the navigator, or in dialogs contributed by other plug-ins besides JDT. However, the entries in these views may not be IResources so an IResource independent mapping mechanism would be required. A workaround for this problem is demonstrated by the Search plug-in which allows for plug-ins to integrate with other tools by contributing domain specific pages. JDT contributes a JDT search page to the view and shows logical Java elements. This solution however doesn't allow showing mixed logical models in the same widget, which is required several presentations in the SDK such as the Synchronize View, Navigator, Refactoring Preview, and many others.

• Need for full access to a logical model that would allow building a dynamic UI. This would include mapping from an IResource to a logical element (Complex).
  

• Need name and icon for a logical element to display in simple dialogs (Simple).
  

Complaint 4: Change Sets

Consider a user's action as a logical change, for example, the user renames a class using the JDT refactoring action. In the user's mind he 'renamed a class' and knows that there have been side effects to other resources. Currently there is not way of capturing these logical actions and associating the set of affected resources. This problem manifests itself more in tools where almost every change to the model has side effects.

Complaint 5: Participating in operations

Complaint 6: IResource based views in the IDE

Complaint 7: Merging can't consider all files related to a logical element

Complaint 8: Creating non-IResource projects that appear in the navigator

Discussion

Given the number of different complaints about logical resource support indicates that this is indeed a large problem space. If we plan on addressing any of the complaints for 3.1, we will have to scope the solution to address a subset of the complaints. I propose the following grouping of the complaints:

Adaptables: Related to providing a richer adaptable interface between plug-ins
Complaint 1: Not very adaptable
Complaint 2: Decorators
Complaint 7: Merging can't consider files related to a logical element

Presentation of logical models: Related to exposing a non-resource based data modeling framework
Complaint 6: IResource based views in the IDE
Complaint 3: Presentation of mixed logical models

A common discussion in the community is the idea that the resources plug-in should be generalized to become this generic model, but in reality it wasn't designed as such and although it contains common model services such as eventing and threading, it was explicitly designed to model the file system. Changes to the resources plug-in would be a major breaking API change and not acceptable to the community.

For 3.1 we will only address the Adaptables group of complaints. See Solution 1: Support Logical Resources - Adaptables for a discussion on a possible solution and investigate possible solutions for Complaint 3 and 5.