Supporting Repository Operations on Logical Models

The purpose of this document is to present details of the solutions for the repository operation scenarios presented in Enabling Logical Model Integration in the Eclipse Platform.

Logical to Physical Mappings

A well integrated development environment should support 3rd party operations, such as repository provider operations, on UI model elements that map to the underlying Platform Resource model. Eclipse currently does support this for cases where there is a one-to-one mapping from a model element to a resource. However, to get full integration, one-to-many, and many-to-one should also be supported.

Performing Resource Based Operations on Logical Models

In order for resource based operations, such as repository operations, to be performed on logical models, a means to communicate resources that constitute the model elements is required. This is the purpose of the ResourceMapping API introduced in Eclipse 3.1 M5. This mapping supports a "one model element to many resource" mapping. The specifics of this support is outlined here.

The following points summarize how ResourceMappings are used to communicate the resources of a model element to a repository provider.

1. Repository providers contribute menu operations to model elements through the Platform adaptable mechanism. The menu items will appear on any elements that adapt to ResourceMapping.
2. When the user performs a repository operation on a model element, the contributed operation is handed the ResourceMappings obtained from the model elements.
3. What happens next depends on what operation was chosen. For instance, a check-in (or commit) operation can use the resource mapping to check-in the appropriate files. Other operations can similarly be performed on the resources that constitute the model element.
4. In some cases, the remote state of the model may contain additional resources. The ResourceMappingContext API is a way to allow the repository provider to communicate to the model provider the means to determine the remote state of the model so that all relevant resources can be included in the operation. For instance, an html file model may include the images shown on a page. If additional images are added to the remote state, operations such as update or merge would want to include the new images.

Once an operation is triggered, some operations may need to obtain additional input from the user or show operation feedback. Ideally, the information shown in dialogs or other views used to obtain information from or show information to the user should be consistent with the model from which the operation was launched or, in the very least, provide a link between the resources being operated on and the originating model elements. The following list outlines some of the different scenarios where this issue may occur:

• It may be desirable to provide the ability to exclude some of the model elements from the operation due to resource state (e.g. may want to prompt when replacing model elements that contain dirty files). When a single model element maps to one or more resources, this is straight forward. However, if many model elements are contained in the same file, the model elements may need to be included/excluded as a group. This is further complicated by the fact that all affected model elements may not be contained in the input to the operation. This is covered in the "Handling Many-to-One Mappings" section.
• Repository operations often involve the merging of remote changes with local changes. This involves fairly complicated interactions between the model and the repository. This discussed in more detail in the next section.

Merging Logical Model Changes

One of the more complicated scenarios involving repository providers is when remote changes need to be merged with local changes. Here are the merge cases:

• When a merge is required, a headless merge may be possible at the file level which means that it could be performed by the repository provider without the involvement of the model (i.e. no knowledge of model semantics is needed).
• It is also possible that a headless merge is not possible at the file level but is possible at the model level (i.e. the knowledge of the models semantics makes a headless merge possible).
• If a headless merge is not possible, the user will need to perform a manual merge.

The interesting cases are the last two (i.e. merge involving model semantics and manual merge).

There are several complications that must be considered when formulating a solution:

• The elements being merged may come from different model tooling and hence are parts of different models. This is currently unlikely since there are few generic views showing elements from different models but may become more likely in the future as more generic views surface.
• At the lowest level, merges happen on files. If the multiple model elements are contained in a single file, it is highly possible that additional model elements may be affected by the merge. This means that the scope of the merge may be greater than what was originally indicated by the user when they launched the operation that triggered the merge.
• The model elements being merged may be contained by higher level models or may involve files that are contained by other models. The challenge here is to display the merge in a way that makes this obvious to the user and allows them to decide which merge mechanism is more appropriate. In the case of layered models, it may be appropriate to choose the highest level model as the default merge mechanism.
• In order for model tooling to display the merge in a form that is consistent with the model, access to the ancestor and remote state for files needs to be accessible.This would require API provided by the repository provider.
• The merge happens as part of a repository operation. When the merge is complete, the repository operation may then need to perform additional portions of the operation (e.g. modify the synchronization state of local resources). This is complicated by the fact that the merge may have been completed on a subset of the elements included in the operation (and the other elements skipped).

A solution for presenting model based merges could take several forms:

• A separate dialog or wizard page for each model type involved in the merge. This is OK if the models are disjoint but may be a problem if there is overlap.
• A single page that displays all the model elements being merged. Selecting a model element will populate other portions of the page appropriately. The advantage is that the user will see the entire scope of the operation at once. However, it will still be difficult to highlight model overlap. This will also require a more standardized presentation which may be more restrictive.

The second approach is already supported by the compare framework and feels like a better approach. Hence, we will concentrate on that solution for the time being. Here is what this solution may involve:

• A mechanism is provided for obtaining a model specific DiffNode (Compare component API) for each ResourceMapping that is being operated on. This would allow the merge operation to convert the selection into a form that could appear in a merge viewer. Each type of DiffNode may have model specific operations that should appear in the context menu or toolbar.
  • The mechanism for creating the DiffNodes will need access to the remote and ancestor (or base) state of the model.
  • Need to be able to include additional DiffNodes from a model for the case where one of the selected elements is contained in a file with other model elements.
  • Ideally, DiffNodes could be obtained from other models that are interested in the resources being merged.This becomes more complicated as there may be relationships between multiple models (i.e. one may be built on top of another) and you would want the display of the DiffNodes to reflect this.
• A merge viewer that can contain DiffNodes from one or more models. Operations appropriate to a selected node should appear in the context menu and toolbar. Also, selecting a node should update the other portions of the merge viewer (structured comparison and content comparison panes). Expansion of DiffNodes should also be supported.

The key here is that the model is in complete control of the merge of its model elements (i.e. the user may not even need to be aware of the underlying files).

Handling Many-to-One Mappings

Another interesting case involves the case where a single Platform resource contains several model elements. If the user selects a single model element and performs a repository operation on it, it will affect other model elements as well. This will be confusing to the user if they see other model elements being affected by an operation on one element. Here are some the scenarios involving this case:

• The user wants to tag (i.e. label or version) a specific model element but doing so will tag all the elements contained in the same file. It may be enough to warn the user that more than one element will be tagged but ideally, the user could be shown all the elements that will be tagged.
• The user wants to merge a model element. If the model provides the merge viewer, than this may be possible without involving the other elements. However, the repository provider would need to be able to differentiate this from a full file merge since the action taken upon merge completion may differ. For some operations that start with a merge, such as check-in, all the elements in the file would need to be merged.
• The user wants to replace a model element with the contents from the repository. The operation doesn't need a merge since local contents are being replaced. However, like a merge, it may be possible for the model to perform the replace on the specific element given the contents of the two files. Without this capability, the user would need to be informed that additional elements will be included in the operation.
• Goto action on a file marker (https://bugs.eclipse.org/bugs/show_bug.cgi?id=87288). If many elements are contained in a single file, it is possible that multiple editors may be open on the same file. A mechanism to pcik the proper editor is needed.

Possible solutions to this problem are:

• Provide a hint on the resource mapping or traversals that the file is not wholly contained by the model element. This would at least allow the repository provider to warn the user that the operation will affect additional elements. If the traversal also included the range within a file, this could be used for linking operation such as the one involving the linking of markers to editors mentioned above. This could also be used to perform replacement of file sections but would require the the ability to obtain the corresponding range from the remote contents as well.
• Provide a means of obtaining the additional model elements that will be affected. This will allow the repository provider to display all the elements that will be affected but requires additional API.

This problem has some overlap with the physical to logical problem which is covered in the "Physical to Logical" section, in the sense that, if a mechanism existed for finding all model elements from any model that are contained within a resource, this could be used as the API for the second point mentioned above.

Decorations

Decorating logical elements based on their resource mapping is problematic is some cases. The most interesting case is decorating elements to indicate that they have changed locally with respect to the repository. There are two aspects of this that are problematic:

1. When a file contains many logical elements, only a few may be dirty when the file is dirty. However, they will all appear dirty if the file dirty state is used to determine the decoration. This can be overcome by allowing the model provider to determine model element dirty state by comparing the modified local file contents with that of the unmodified contents from the repository. Unfortunately, this requires that either the unmodified contents are cached or fetched from the server.
2. When elements are shown in a tree, the resource mapping of a parent may not contain all the resource mappings of its children. This is due to the use of content providers in tree views that determine what the children of an element are in the tree. The only solution to this is to use model elements that contain the logic of determining their children and use a simple content provider that obtains the children from the model element. The problem with this approach is that it leads to model wrapping when alternate views are used (which is something the content provider API was supposed to solve).

Status

Here is the status of this work as of 3.1 M5

• ResourceMapping/ResourceMappingContext: Initial cut is available in 3.1 M5 and will be in 3.1 as provisional API.
• Merge Support: Although work has not begun, this area is well bounded and well understood.

Open Issues

Here are the list of open issues:

• Transaction support: Some repository may have transaction support. It is unclear how this fits in with logical model support.