EMF Compare/Specifications/GraphicalComparison

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

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).

To put in relief the graphical differences, some decorators should be used.

• On one hand, it enables to focus on the impacted objects, highlighting them with markers.
• On the other hand, through phantoms, it enables to locate either the place where objects were deleted or the target location where objects should be added after merging.

On each difference selection, only the related markers will appear.
About phantoms, if they are nested in other phantoms, these last ones will be displayed on selection of the difference related to the first one. So, to display the context of the phantom eases the understanding of the difference.

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 highlighted by a marker in 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.

Locally added elements

• 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 gray color (default value), as place-holder. On the other side, the related object is highlighted by a marker with the same color. On the ancestor version, the origin object is marked too.

Locally deleted elements

• Remotely added elements:

You can see a remotely added object on the right side of the comparison viewer. It is highlighted by a marker in 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.

Remotely added elements

• 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 blue color (default value), as place-holder. On the other side, the related object is highlighted by a marker with the same color. On the ancestor version, the origin object is marked too.

Remotely deleted elements

• 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 highlighted by a marker in 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.

Local coordinates change

• 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 highlighted by a marker in 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.

Remote coordinates change

• Local move (and potentially coordinates change):

You can see a moved object from a container to another one, on the left side of the comparison viewer. The object concerned by this move is highlighted by a marker in 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.

Local move

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.

ADD nodes and DELETE parent nodes DELETE nodes and ADD children nodes Markers and phantoms: On the ancestor version, a marker is set down on the deleted node (container).

LOCAL ADD nodes, REMOTE DELETE parent nodes

ADD edges and DELETE connected nodes or edges DELETE nodes and ADD connected edges Markers and phantoms: On the ancestor version, a marker is set down on the deleted node/edge.

LOCAL ADD edges, REMOTE DELETE connected nodes

LOCAL ADD edges, REMOTE DELETE connected edges

DELETE edges and CHANGE these edges or connected edges or connected nodes DELETE nodes and CHANGE connected edges CHANGE edges and DELETE connected nodes CHANGE nodes and CHANGE connected edge Markers and phantoms: On the ancestor version, a marker is set down on the deleted/changed edge.

LOCAL DELETE edges, REMOTE CHANGE edges

LOCAL DELETE nodes, REMOTE CHANGE connected edges

LOCAL CHANGE edges, REMOTE DELETE connected edges

LOCAL CHANGE nodes, REMOTE CHANGE connected edges

DELETE nodes and CHANGE these nodes or their children CHANGE nodes and DELETE these nodes or their parent Markers and phantoms: On the ancestor version, a marker is set down on the deleted/changed node.

LOCAL DELETE nodes, REMOTE CHANGE nodes

LOCAL DELETE nodes, REMOTE CHANGE children nodes

MOVE nodes or their children and DELETE these nodes DELETE nodes or their parent and MOVE these nodes Markers and phantoms: On the ancestor version, a marker is set down on the deleted/move node.

LOCAL MOVE nodes, REMOTE DELETE nodes

LOCAL MOVE nodes, REMOTE DELETE parent nodes

CHANGE nodes on each side CHANGE edges on each side CHANGE edges and CHANGE connected nodes Markers and phantoms: On the ancestor version, a marker is set down on the changed edge or on the changed node (in relation to the selection of the conflict).

CHANGE on each side

MOVE nodes on each side Markers and phantoms: On the ancestor version, a marker is set down on the moved node.

MOVE on each side

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	ADD of its container DELETE of the origin value on the same containment mono-valued reference
	reference	ADD of the target object ADD of the source object 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	DELETE of the outgoing references and contained objects DELETE/CHANGE of the incoming references MOVE of the contained objects
MOVE	content	ADD of the new container of the object MOVE of the new container of the object
CHANGE	reference permutation	ADD of the target object

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	The ADD (content) of the Edge object (it can be ignored because it is required by the differences below) The ADD of every objects under the Edge (content: DecorationNode, FontStyle, IdentityAnchor...) and references (to the semantic object and source/target graphical objects)
	DELETE	The DELETE (content) of the Edge object (all the DELETE under are required by this one)
	CHANGE	The ADD (content) or CHANGE (attributes) of points in the RelativeBendpoints of the edge The ADD (content) or CHANGE (attributes) of the coordinates of an IdentityAnchor of the edge
	MOVE	N/A
Node Change	ADD	The ADD (content) of the Node object (it can be ignored because it is required by the differences below) The ADD of every objects under the Node (content: Node, DrawerStyle, SortingStyle...) and reference to the semantic object
	DELETE	The DELETE (content) of the Node object (all the DELETE under are required by this one)
	CHANGE	The CHANGE (attributes) of the coordinates in Location of the Node (over a preset threshold)
	MOVE	The MOVE (content) of the Node object
Hide Change	CHANGE	The CHANGE (attribute) of the "visible" property of the View to false
Show Change	CHANGE	The CHANGE (attribute) of the "visible" property of the View to true

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.

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.