Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
EMF Compare/Development/MergeViewerItem Refactor Documentation
The (Tree) MergeViewerItem refactoring has two distinct goals: Clear separation of concerns in the code and allow the user to customize the tree.
During the refactoring the MergeViewerItem was changed a lot. Previously it combined the responsibility of the Content- and LabelProvider in itself. Since the accessors directly provide the root MergeViewerItems there was no room for customization.
Contents
General Principles
- The responsibility of determining the children of a MergeViewerItem should be taken by ContentProviders
- The responsibility of determining the label of a MergeViewerItem should be taken by LabelProviders
- The user can ‘easily’ customize the Providers
- We should be as much backward compatible as possible / reasonable
Separation of Concerns
The determination of ‘real’ children and the determination of ‘stub’ children should be separated
- Use a ContentProvider for MergeViewerItems to determine MergeViewerItem children.
- The default ContentProvider for MergeViewerItems uses a ContentProvider for the match values to create MergeViewerItems
Customization Rules
By separating and providing two different ContentProviders the user has full control for customization:
- Customize the ContentProvider within the MergeViewerItemContentProvider when the user does not want to handle the ‘stub’ elements and the default behavior is good enough. The user does not need any knowledge about EMFCompare when this option is chosen.
- Replace the whole MergeViewerItemContentProvider for maximum control, although some knowledge about EMFCompare is then required to properly display differences (if desired).
Backward Compatibility
The interface of ‘IMergeViewerItem’ provides all necessary functions. This means the new behavior can be implemented without breaking any builds on a source level.
- The `IMergeViewerItem.Container’ will be deprecated
- Some functions of the ‘IMergeViewerItem’ itself can be deprecated
- There could be a LegacyMergeViewerItemContentProvider which still tries to use the MergeViewerItem implementation itself. This should not be activated by default, but if a user insists on the old behavior to not break an existing application this option can be offered
Implementation
See change 78735
Core Functionality
| Class/Interface name | Role | Customization |
|---|---|---|
| IMergeViewerItemProvider | Responsible to extract the root IMergeViewerItems from the input given to the ContentMergeViewers (e.g. ICompareAccessors) | Instances are registered to a new extension point. |
| CompareAccessorMergeViewerItemProvider | Default implementation of IMergeViewerItemProvider. Extracts the IMergeViewerItems from ICompareAccessors. | Default registered to extension point for all contexts with a low prio. |
| IMergeViewerItemContentProvider | The ContentProvider which is used to determine parent and children of given IMergeViewerItems | Instances are registered to a new extension point. |
| TreeMergeViewerItemContentProvider | Default implementation of IMergeViewerItemContentProvider.
Unwraps the compared EObject from IMergeViewerItems, determines their children via the AdapterFactory utility of EMFCompare and wraps them back into IMergeViewerItems. |
Default registered to extension point for all contexts with a low prio. |
| DelegatingTreeMergeViewerItemContentProvider | Set in the TreeContentMergeViewer as ContentProvider for the tree. | Uses the registry to get the best fitting IMergeViewerItemProvider to get the root IMergeViewerItems.
Also uses the registry to get the best fitting IMergeViewerItemContentProvider to determine the children of these IMergeViewerItems |
Customization Functionality
Using the extension point
A new extension point “contentMergeViewerCustomization” was introduced. There IMergeViewerItemProvider and IMergeViewerItemContentProvider can be registered. They are registered with an integral ranking and a newly introduced optional IContextTester class. If this class is specified it is able to check the comparison to see if the customization shall be active or not.
The algorithm for the extensions is as follows.
Go through all registered extensions:
- Check if a IContextTester is specified and returns true (If no IContextTester is specified it is assumed to be valid for all contexts)
- Check if the ranking is higher as the currently best ranking
- Check whether the provided IMergeViewerItemProvider or IMergeViewerItemContentProvider actually do want to handle the specific object.
- If 1.-3. is yes the save the extension as the currently best one
Return the best extension
The extension point can be used for minor changes or a complete overhaul of the tree. Especially useful is the notion of contexts which is missing in the current EMFCompare extension points.
Using the existing AdapterFactory mechanism
Since the default active TreeMergeViewerItemContentProvider uses the AdapterFactory mechanism of EMFCompare, users can also customize the TreeContentMergeViewer by registering their own AdapterFactories to the already existing org.eclipse.emf.compare.edit.adapterFactory extension point.
Backward Compatibility
Already existing custom implementations of IMergeViewerItem and subclasses of the default MergeViewerItem.Container class can easily be supported.
For the existing two subclasses of MergeViewerItem.Container ResourceAttachmentChangeMergeViewerItem and DanglingStereotypeApplicationMergeViewerItem, IMergeViewerItemContentProviders were registered. These are only responsible for the specialized MergeViewerItems: They just call the MergeViewerItem.Container methods as usual.
A user of EMFCompare who has already customized the ContentMergeViewer with his/her own MergeViewerItems can do the same to keep their functionality in the new version of EMFCompare.