Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
EMF Compare/Specifications/GraphicalComparison
Contents
- 1 Evolution Specification: Graphical Comparison
- 1.1 Preamble
- 1.2 Introduction
- 1.3 Detailed Specification
- 1.4 Backward Compatibility and Migration Paths
- 1.5 Tests and Non-regression strategy
- 1.6 Implementation choices and tradeoffs
Evolution Specification: Graphical Comparison
Current status is DRAFT
Preamble
Summary: This feature is about all topics around the comparison of graphical objects.
Links to the Bugzilla tickets which are related to the change:
- Bug 400816 - Phantom display of removed graphical items
- Bug 401526 - Enhance markers of graphical comparison
Introduction
PENDING This section should contain a summary of the proposed evolution, including why it is needed. Ideally it should be self-contained so that non-developers can get a quick overview of the evolution without reading the detailed specification.
Detailed Specification
The aim is to be the most consistent with the look of the "semantic" comparison (tree).
- The same mechanism of color management will be used (standard behavior of eclipse compare):
- One for local changes (grey by default). The end-user will watch these changes on the left side.
- One for remote changes (blue by default). The end-user will watch these changes on the right side.
- To put in relief the graphical differences, some decorators should be used:
- On one hand, to focus on the impacted objects, highlighting them with markers.
- On the other hand, through phantoms (place-holders), to locate either the place where objects were deleted or the target location where objects should be added after merging.
- The color of the concerned decorators will be highlighted on selection of the difference.
Not to overload the diagrams to compare and to ease the understanding of each difference, only the decorators concerned by the selected change will appear.
About phantoms (place-holders):
- To ease their readability, in some cases, their context will have to be displayed:
- If they are nested in an other phantom (e.g. due to a delete of the parent object), this last contextual one will be displayed at the same time as the main phantom concerned by the current selected change.
- If they are edges connected to deleted nodes or edges, these last contextual ones will be displayed at the same time as the main edge phantom.
- The color of the contextual phantoms (dependencies) will not be highlighted.
- They will be drawn as:
- A simple rectangle for nodes, at the same origin location.
- A simple line (with the same bend points) for edges, at the same location.
- A simple line for nodes as element of containment list. For this case, The same LCS computation will be used to locate in the list, at the good index.
- Particular cases: If the location of the contextual phantoms was changed, the new location of the main phantom has to be computed.
- A node place-holder, related to a delete of a node, embedded in a node where the location changed.
- An edge place-holder between nodes where the location changed. In this case, the display of the line will have to be drawn again (it will be a default display, computed by GMF, without potential bend points).
About markers, they will be simple transparent rectangles which will be set down above the concerned objects and they will be lightly larger.
Below, different cases are detailed.
Non conflicting cases
- Locally added elements:
You can see a locally added object on the left side of the comparison viewer. It is identified by a marker in transparent highlighted gray color (default color). On the other side, a phantom with the same color is drawn, as place-holder, in order to locate the place where the related object would be added if the end-user merged from left to right. In this example:
|
- Locally deleted elements:
You can see a locally deleted object on the left side of the comparison viewer. It is represented by a phantom in highlighted gray color (default value), as place-holder. On the other side, the related object is identified by a marker with the same transparent color. On the ancestor version, the origin object is marked too. In this example:
|
- Remotely added elements:
You can see a remotely added object on the right side of the comparison viewer. It is identified by a marker in transparent highlighted blue color (default color). On the other side, a phantom with the same color is drawn, as place-holder, in order to locate the place where the related object would be added if the end-user merged from right to left. In this example:
|
- Remotely deleted elements:
You can see a remotely deleted object on the right side of the comparison viewer. It is represented by a phantom in highlighted blue color (default value), as place-holder. On the other side, the related object is identified by a marker with the same transparent color. On the ancestor version, the origin object is marked too. In this example:
|
- Local coordinates changes:
You can see a local coordinate change on the left side of the comparison viewer. The object concerned by this change is identified by a marker in transparent highlighted gray color (default color). On the other side or the ancestor version, the same object, at the old location, is marked with the same color too. In this example:
|
- Remote coordinates changes:
You can see a remote coordinate change on the right side of the comparison viewer. The object concerned by this change is identified by a marker in transparent highlighted blue color (default color). On the other side or the ancestor version, the same object, at the old location, is marked with the same color too. In this example:
|
- Local move (and potentially coordinates change):
You can see an object moved from a container to another one, on the left side of the comparison viewer. The object concerned by this move is identified by a marker in transparent highlighted gray color (default color). On the other side or the ancestor version, the same object, at the old location, is marked with the same color too. In this example:
|
Conflicting cases
|
|
|
REMOTE | |||||||||||||||||||||||
|
|
|
ADD |
DELETE |
Coordinates Change (CHANGE) |
MOVE | ||||||||||||||||||||
|
|
|
nodes |
children nodes |
parent nodes |
edges |
connected edges |
connected nodes |
nodes |
children nodes |
parent nodes |
edges |
connected edges |
connected nodes |
nodes | children nodes |
parent nodes |
edges |
connected edges |
connected nodes |
nodes |
children nodes |
parent nodes |
edges |
connected edges |
connected nodes |
LOCAL |
ADD |
nodes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
children nodes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
parent nodes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
edges |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
connected edges |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
connected nodes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
DELETE |
nodes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
children nodes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
parent nodes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
edges |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
connected edges |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
connected nodes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
Coordinates Change (CHANGE) |
nodes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
? |
|
|
|
|
| |
children nodes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
parent nodes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
edges |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
? | ||
connected edges |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
? |
|
|
|
|
| ||
connected nodes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
MOVE |
nodes |
|
|
|
|
|
|
|
|
|
|
|
|
? |
|
|
|
? |
|
|
|
|
|
|
| |
children nodes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
parent nodes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
edges |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
connected edges |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| ||
connected nodes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
? |
|
|
|
|
|
|
|
|
|
Conflict (or pseudo conflict) |
? | Is a conflict ? |
|
Potential pseudo-conflict |
Conflicts
A conflict is created when a change has been made both on left and right side, on the same element.
A graphical conflict can be related to 0 or n semantic conflict.
For example, the change of the coordinates of an object, in local, may be in conflict with an other change of these coordinates on the same object, in remote. However, no conflict (no difference too) exists at the related semantic objects level.
The add of a graphical object (with its semantic one) in a container, on one hand, and the delete of this container, on the other hand, involves conflicts on the both levels.
Also, a semantic conflict may involve no graphical conflict (e.g. on the name of an object).
The conflict devoted markers will be visible only for graphical conflicts.
The markers and phantoms will be drawn according to this rule:
- On the ancestor version, a marker is set down on the object(s) impacted by the conflict.
- On each side, it is the respective change which is put in relief.
If it is a delete of edge inferred by the delete of one of its extremities at least, then phantoms for the related deletions will be drawn too.
If it is a delete of node inferred by the delete of its parent, then a phantom for the parent will be drawn too.
Markers and phantoms:
|
Markers and phantoms:
|
Markers and phantoms:
|
Markers and phantoms:
|
Markers and phantoms:
|
Markers and phantoms:
|
Markers and phantoms:
|
Pseudo conflicts
A pseudo conflict may happen when exactly the same change has been made on both side.
The add of a node/edge on the right and left side may involve a pseudo conflict only if these added elements own the same identifier (in case of manual handling of the XMI source or using of computed functional identifiers).
These pseudo conflicts could be visible in the same way as the "conflict" markers and phantoms, but using a specific color code.
Question about MOVE and CHANGE
- The MOVE of a node may involve a CHANGE (coordinates) of it if the new container requires its own coordinate system.
- So, the MOVE would require the CHANGE. But does the CHANGE require the MOVE ? Because it has no sense outside of the context of the MOVE (to merge the change location whereas the frame of reference is different).
- Is the MOVE in conflict with a CHANGE if the frame of reference is different ?
Required differences
Default behavior
The computation of the required differences from a graphical one inherits from the generic post-processor behavior.
So:
Change kind |
Reference kind to a graphical object |
Requires: |
ADD |
content |
|
reference |
e.g. The ADD of a reference to the target or source of an edge requires the ADD of the edge itself and the ADD of the target and source objects, the ADD of a reference to the semantic object from a graphical one requires the ADD of the graphical and semantic object. | |
DELETE |
content |
|
MOVE |
content |
|
CHANGE |
reference permutation |
|
Specific behavior
PENDING: see with LGO for his modifications on Node and Edge changes.
These cases are already managed by the default requirements post-processor:
- The DELETE of a graphical object is required by the DELETE of the related semantic one ("DELETE object requires DELETE of incoming references" case)
- The DELETE of a graphical object does NOT require the DELETE of the related semantic one.
- MOVE requires and is required by CHANGE if the coordinate system of the new container is relative.
Extension definition and refining
Difference extensions for diagram comparison are defined to encapsulate a set of unitary differences related to the notational model and so to obtain a vision more macroscopic. To summarize, the extensions are refined by other differences.
Extensions |
Kind |
Refined by: |
Edge Change | ADD |
|
DELETE |
| |
CHANGE |
| |
MOVE |
N/A | |
Node Change | ADD |
|
DELETE |
| |
CHANGE |
| |
MOVE |
| |
Hide Change |
CHANGE |
|
Show Change |
CHANGE |
|
Merge of extensions
The merge of the graphical extensions consist in merging the potential required differences then the ones refined by the extension.
Each refining difference will merge its required ones before merging itself.
Design
Creation of extensions
Creation of phantoms
Backward Compatibility and Migration Paths
PENDING Every one of the sections below should be present. Even if there is no corresponding change (for example no API change), it should exist to mention explicitly "This evolution does not change any API."
Metamodel Changes
PENDING Document any change to the Viewpoint metamodel. If they require a migration operation, mention it and describe the general idea of how migration process. If any information can be lost during the migration, mention it clearly. If validation rules must be added/modified, mention it also.
API Changes
PENDING List every API addition, removal and deprecation. For each removal and deprecation, indicate the migration path for existing code.
User Interface Changes
PENDING List every user-visible change in the interface. Here "user" includes not only end-users but also developpers.
Documentation Changes
PENDING List every documentation needing an update here, starting by the New and Noteworthy documentation.
Tests and Non-regression strategy
PENDING This part of the document should describe the strategy to use to correctly test the evolution and guarantee the non-regression.
Implementation choices and tradeoffs
PENDING Any important tradeoff or choice made during the implementation should be referenced here with pros/cons leading to the final decision.