IBM
Contents Index Previous Next



Comparing and Merging Diagrams


Overview

Compare and Merge for MSC diagrams

This section describes more details about how the comparison is done in the Compare and Merge functionality for MSC diagrams. The intention is that this should be of interest for a user who wants to understand how the comparison is done and to anticipate what a resulting Compare/Merge will look like.

Compare operation

Two MSC or HMSC diagrams are input to the Compare operation. In general when differences are found related objects are grouped together to form difference groups. In the graphical report it is possible to navigate between these difference groups using the Next and Previous buttons.

For MSC diagrams the algorithms to find difference groups are as follows:

Comparing Headings

The heading texts will be compared in the two diagrams. If they differ the heading will form a difference group of its own.

Comparing Instances

When instances are compared the algorithm will for each instance try to find a matching instance in the other diagram. To find the match, first of all it uses the name to find the match. If there is no name match, the objectID for the instances will be used to find the match. The objectID is a unique (within each diagram) number that every object has, this is normally not visible for the user but it can be shown using the Info Window. By using objectIDs we will hopefully match instances where the difference is that the name has been changed. When instances have been matched, differences will be reported if any of the three text fields, name, kind and decomposition will differ.

Instances that have not been matched in the two diagrams will then be classified as being added or removed. Each instance will form a difference group of its own.

Figure 316 Comparing instances

In Figure 316 two diagrams are shown. When using the Compare command, the instances with the name A will be matched and they will also differ as the instance kind texts are different. Instances with the name B will match and no difference will be detected even though the positions of the instances are not the same. The instance with the name C will be matched and differ against the instance with the name otherC because both have the same objectID. The figure also indicates by the color that all the text symbols differ as either the text has changed or they only appear in one of the diagrams.

Comparing Events

The events will be checked for one instance at a time. All events connected to one instance are ordered from top to bottom. For the corresponding matched instance in the other diagram the event sequences are compared using an algorithm similar to the UNIX diff function for text comparison. The events are group in sequences that have been unchanged, changed, added or removed. Each such sequence will then form a difference group.

If there is an instance without a match in the other diagrams all the events connected to this instance will be considered as being added and they will all form a difference group.

Special treatment is made for events that are connected to more than one event. For messages the event will be treated together with events connected to the instance where the message starts, except for found messages that are treated on the incoming instance.

Multi instance events like conditions, references and inline expressions are treated in the event sequence for the instance that first encounters the multi event.

After all the event sequences have been checked, difference groups that differ will be sorted from top to bottom according to the Y-position of the objects in the group. Thus, when they are presented in the graphical report they are shown in this order.

Comparing Comments

A comment that is connected to an object will be handled together with that object. This means that if the comment texts differ the whole object will be considered as being different.

An unconnected comment will be matched using the geometrical position of the object or if this check fails the objectID will be used.

Each unconnected comment having differences will form a difference group of its own.

Comparing Text Symbols

The text symbols uses the same algorithms to find differences as the unconnected comments described in the previous section.

Merge operation

The merge operation has two source diagrams as input. The Source2 diagram is merged with Source1 and the resulting diagram is placed in the Result diagram. An optional input is the Ancestor diagram which is used to drive the automerge functionality.

The algorithm for the merge operation is to use the difference groups found when comparing Source1 and Source2. All objects not belonging to any difference group, these are objects being the same in both Source1 and Source2, will be copied from Source1 to Result. For each difference group, the objects in the group are compared with the Ancestor diagram, if no Ancestor is specified the behavior is the same as if the Ancestor diagram was present and it had no objects. If the difference group is a group that has changed and Source1 is the same as the Ancestor, then Source2 is copied to the Result, and if Source2 is the same then Source1 is copied. If none of Source1 or Source2 is the same as Ancestor then the group is classified as being unresolved and the user must decide what the Result should look like.

If a difference group indicates that there are objects in Source1 that have no matching objects in Source2, these objects will be added to Result if they also do not have any matching objects in the Ancestor diagram. However, if there are unchanged matching objects for the whole difference group in the Ancestor they will not be added to Result as in this case they have been removed in Source2. If only parts of them match the group will be classified as unresolved. Similar if a group indicates that objects have been added to Source2 the objects will be added to the Result diagram if the objects also are missing in the Ancestor diagram. If they all have matching objects in Ancestor they will not be added, otherwise the group is set as unresolved.

Figure 317 shows an example of the merge operation.

Figure 317 Example using automerge

The automerge gives the following result when the Source2 diagram is merged into the Source1 diagram and the Ancestor diagram has been specified:

Merged diagram with layout changes

During a merge the normal behavior is that, if necessary, a Make Space operation will be performed when a merged object is added to the Result diagram. This will make sure that objects are placed in the correct order and that the diagram will not have overlapping objects.

However, in some circumstances the resulting diagram from a merge operation can have objects placed at positions, which can not be obtained when editing the same diagram by hand. This can happen when the source diagrams do not have much free space in them or when matched objects from the sources are placed at different geometrical positions.

Specifically, please note the following observations:

Merged diagram with unresolved instances

When instances are merged and an unresolved difference is detected for a given instance, all events connected to this instance will be grouped together in one or more difference groups and will be classified as unresolved. If, from the merge dialog, one of the versions of this instance is accepted, the events can also be accepted in later difference groups. If the difference groups will wrap, i.e. by pressing Next many times the difference groups will start from the beginning again, the events connected to this merged instance might not be presented again. They will appear only if there is a real difference for the events. This happens because after a wrap all difference groups are dynamically recalculated and difference groups are first of all found from the differences between Source1 and Source2, and secondly they are formed if any of the instances does not appear in the merged diagram. After the instance has been manually merged the unchanged events connected will then not be part a any difference group.

Performance

The time it takes to perform a Compare/Merge operation depends on how many instances the diagram contains and also on the height of the diagram. There is also a dependence on the type of objects that are used in the diagram, use of multi axis objects like inline expressions, conditions and reference symbols will increase the time used. A 5 pages long diagram with 10 instances and 10 multi-axis objects can take about a minute to perform the Compare/Merge operation.

Unsymmetrical differences can give unexpected difference groups

The use of the diff algorithm when comparing the event sequence on two instance axis can in certain situations give rise to some unexpected results. The diff algorithm looks for the longest sequences of identical events when finding differences. Sometimes this results in two different results for the same sources. Assume Source1 has the sequence ABCD and Source2 has the sequence ACBD. A diff on Source1 and Source2 gives as a result that in Source2 C is unchanged but B has been removed and then B has been added. If instead Source2 is compared with Source1 we will get that B is unchanged and that C has been removed and added. Thus the comparison is not symmetrical.

To compensate for this unsymmetry the resulting difference groups after the diff algorithm are checked for patterns like the one described above. For each unchanged difference group (Ug) the following check is done. If there is a changed or added difference group (CAg) preceding the unchanged one, Ug, and all objects belonging to CAg also can be found in a changed or removed difference group following Ug, the Ug group will also be set as being a changed difference group. Similar if there is a changed or removed difference group (CRg) preceding Ug and all objects belonging to CRg also can be found in a changed or added group following Ug, the Ug group is set as being changed.

Using the example above, we will then get that both B and C will appear in some difference group and thus be considered to have been altered. For the user this can be unexpected, as for example if we only change the diagram by moving object B by dragging it below C we would expect that only B will appear in a difference. However as the compare algorithm rely on semantical information rather than geometrical the tool cannot decide whether it is B or C that has been changed. With the extra check done, we set both as changed and we then will get more difference groups than expected.

With the extra check made there can still exist some unsymmetry left when comparing. There will be difference groups for the same objects but the difference groups can be of different kinds. This can result, in an automerge situation, that the merged result will not be the same if Source2 is merged into Source1 or if Source1 is merged into Source2. Also the kind of conflicts appearing might be different.

In Figure 318 an example illustrates how this can affect the resulting diagram from an automerge.

Figure 318 Result from automerge

From the changes in Source1 and Source2 it is uncertain what the result of a merge will look like. Is the changed that the message Req1 will be either after or before the action symbols? or is the change that the action symbols are moved relative to the message? Both expectations could be justified and in the automerge, both when merging Source2 into Source1 or Source1 into Source2, we will get a merge conflict (however not the same conflict), which signals the user that he must check this more carefully.

The conclusion is that you should be careful when using automatic merge, sometimes your expectations will not come true.

Compare and Merge

Figure 319 : The Compare Diagrams dialog in the MSC Editor

Figure 320 The Merge Diagrams dialog in the MSC Editor

When you select Compare Diagrams or Merge Diagrams from the Tools menu in the MSC Editor or in the HMSC Editor, a dialog will be opened where you can select the diagram to compare with. (It is also possible to compare more than one diagram pair in one operation, but to do this you should use the corresponding menu choices in the Organizer. See Compare > MSC Diagrams, Compare > HMSC Diagrams, Merge > MSC Diagrams and Merge > HMSC Diagrams.

Specifying the Diagram to Compare With

There are two ways for specifying the diagram that should be compared with the currently displayed diagram:

Selecting the Report Type

In the Compare Diagrams dialog, there are six alternatives for reporting differences between diagrams: Ignore white space and double space in text symbols, Textual Difference Report: Summary, Textual Difference Report: Details, Graphical Difference Report (with Merge Facility) and Select and Print Differences.

The Merge Diagrams dialog does not allow you to get a textual difference report. Instead, you always get a graphical difference report and the only option available is Auto-merge using original file.

Ignore white space and double space in text symbols

When this option is on, differences caused by different usage of white space are ignored when comparing texts. One space character is considered equal to two space characters.

Textual Difference Report: Summary

This option is only available when comparing using the Compare Diagrams menu choice.

A summary of how many differences that has been found is presented in the Organizer log. The summary may look like this:

Comparing /home/lat/x.spr
     with /home/lat/y.spr
27 differences (16 symbols, 11 lines) :
  7 changed objects (7 symbols, 0 lines)
  13 removed objects (6 symbols, 7 lines)
  7 added objects (3 symbols, 4 lines)

When you read this report, notice the following:

If at least one of the two compared diagrams has more than one page, then a summary is also presented for each page pair. It may look like this:

Comparing /home/lat/version1/registeredcard.spt
     with /home/lat/version2/registeredcard.spt
5 differences (1 symbol, 4 lines) :
  1 changed object (1 symbol, 0 lines)
  2 removed objects (0 symbols, 2 lines)
  2 added objects (0 symbols, 2 lines)

Page details:

Page ValidateCard
5 differences (1 symbol, 4 lines) :
  1 changed object (1 symbol, 0 lines)
  2 removed objects (0 symbols, 2 lines)
  2 added objects (0 symbols, 2 lines)

Page RegisterMode
0 differences

Textual Difference Report: Details

This option is only available when comparing using the Compare Diagrams menu choice.

This option will print information about each found difference in the Organizer log. This makes it possible to navigate from the Organizer log to every found difference by using the Show Error operation in the Organizer log. See Organizer Log Window.

The detailed textual difference report may look like this:

Comparing /home/lat/d1/db.sbk
     with /home/lat/d2/db.sbk

Comparing page 1

#SDTREF(SDL,/home/lat/d1/db.sbk(1),119(50,35))
ERROR This symbol has been changed...
#SDTREF(SDL,/home/lat/d2/db.sbk(1),119(50,40))
ERROR ...and now looks like this.

#SDTREF(SDL,/home/lat/d1/db.sbk(1),176(95,60))
ERROR This symbol has been removed.

#SDTREF(SDL,/home/lat/d2/db.sbk(1),182(60,60))
ERROR This line has been added.

Graphical Difference Report (with Merge Facility)

The merge facility is only available when merging with the Merge Diagrams menu choice, but you can get a graphical difference report both when comparing with the Compare Diagrams menu choice and when merging with the Merge Diagrams menu choice.

Two windows, named Source 1 and Source 2, displaying the two diagram versions and their differences, and one dialog will be opened. For merge, there will be a third window, named Result, showing the merge result.

Figure 321 : The Merge Diagrams dialog

The Compare Diagrams dialog is similar to the Merge Diagrams dialog. The difference is that the Compare Diagrams dialog is missing the first row of buttons. ("<<", Accept1, Accept2 and ">>".)
In the dialog that will be opened, you can:
  • Navigate between difference groups with the Next and Previous buttons.
  • (Merge Diagrams only.) Navigate between unresolved (not-yet merged) difference groups with the "<<" and ">>" buttons.
  • (Merge Diagrams only.) Do a merge, i.e. update the merge result diagram with information from the current difference group and one of the compared diagram versions, with the Accept1/Reject1 and Accept2/Reject2 buttons.
  • Compare or merge a text in a text symbol in the current difference group.
  • Print the current difference found in the current page pair.
    When the second compare dialog is closed, the editor windows are restored to how they appeared before the compare operation.

Comparing text in text symbols

When two text symbols differ the CompareText button will be available in the Compare Diagrams dialog and it will be possible to enter the Compare Text Symbols dialog.

The Compare Text Symbols dialog consists of two lists of text that are placed side by side with a "gutter" that will contain extra information about the differences. This gutter-information consist of:

The current difference is indicated with a highlight. Buttons make it possible to navigate to Previous and Next difference item.

Figure 322 : The Compare Text Symbols dialog

Merging text in text symbols

When manual merges are conducted the option to merge text symbols will always be available in the Merge Diagrams dialog. When merging a MergeText button is available as in the compare function. When a text symbol is selected there will be an option to select either symbol or merge the text in the symbols into a new symbol.

If the text merge is selected a Merge Text Symbols dialog is presented with three text lists, the two source texts and the result text. It is possible to navigate between the unresolved differences or between all differences.

Figure 323 : The Merge Text Symbols dialog

This works in the same way as in the normal merge. The buttons "<<" and ">>" will jump between the unresolved differences and the Previous and Next buttons will jump between all differences.

The use of Accept 1/Reject 1, Accept 2/Reject 2 buttons will select neither, either or both the texts for merge. The selections from the source files are presented in the result-list the gutter will show what version is selected. Additional symbols in the result list are:

It is also possible to edit the result line-by-line by selecting a line and edit it below the list. Clicking the Change button will replace the changed line in the result list.

Ignore moved or resized objects

If this option is on, the compare operation tries to ignore differences only caused by moved or resized symbols. You should only use this option if the two compared diagrams originates from the same diagram. (For instance, you have used Save as on the original diagram to get the second copy.) This option will not work well if you create two diagrams from scratch and compare them, because the operation uses object IDs to match moved or resized objects.

Select and Print Differences

If this option is on and there are differences, then a print dialog will pop up when the first dialog is closed. Only diagram pages containing differences will be printed, and the differences will be highlighted with selection markers. If the same page containing differences can be found in both compared diagrams, then the two pages will be printed after each other, beginning with the page from the diagram that was visible in the editor when the compare operation was invoked.

Auto-merge using original file

This option is only available in the Merge Diagrams dialog. It allows you to specify the original diagram file that both the diagram versions that are compared originates from. If you specify the original diagram file, then the merge operation can auto-merge all non-conflicting changes for you. Note that if you give the wrong original diagram, then the auto-merge operation may merge the two versions in the wrong way. If you do not specify an original diagram, then the merge operation leaves all merging of differences to you.

Differences That Will Be Reported

When you use Compare Diagrams or Merge Diagrams, all visual object differences will be found:

An object is considered to be moved if it has been moved relative to the upper left corner of the diagram frame. This means that if you move the frame, it will have no effect.

Diagrams are compared one page pair at a time. A page pair is one page from the original diagram and one page from the other diagram where both pages have the same name. If there is no page with the same name in the other diagram, then the complete page is considered to be a difference.

Difference Groups

Differing objects from the same page pair are grouped into difference groups. Two differing objects are placed in the same group if:

Color and the Current Difference Group

In the graphical difference report, all differing objects are given temporary background colors as specified in the initial dialog. As default, the color is green in the original diagram and magenta in the other diagram. Temporary colors are not saved in diagram files. How temporary colors are removed is described in Temporary Colors > Remove.

The dialog that will be opened during the graphical difference report, allows you to navigate between difference groups using previous and next buttons. All objects in the current difference group are selected.

Normally, version 1 of the compared diagrams (the diagram that was in the editor when the compare operation was invoked) is shown in a window in the top left corner of the screen. Version 2 (the diagram that was specified in the first compare dialog) is shown in the top right corner off the screen. For complete page differences (a difference where a page can not be found in the other diagram), the window that misses the page is hidden.

Note that it is possible to manually edit the compared diagrams while the compare operation is ongoing. This can be seen as a light-weight alternative to the full merge operation (described next).

Merging

During a merge operation, three windows are used in addition to the second merge dialog:

The second Merge dialog does not only have previous and next buttons to navigate between differences. It does also have Accept/Reject buttons and "<<" (fast backward) / ">>" (fast forward) buttons.

Note that it is possible to manually edit diagrams while a merge operation is ongoing. This can be useful if you want the merge result diagram to look different from both version 1 and version 2 of the compared diagrams.

When the second merge dialog is closed, the editor will ask you to save the merge result by displaying a save dialog above the window with the merge result diagram buffer. When the save dialog is closed, the editor windows are restored to how they appeared before the merge operation was invoked.


http://www.ibm.com/rational
Contents Index Previous Next