Tutorial and Examples

General Matching vs. ID Mapping Schemes:
How to create an ID Mapping Scheme to improve compare results

Consider an example XML file in two slightly different versions, left and right. Assume that the element extension-point is uniquely identified by the attribute id. The textual differences are shown in bold. 
<?xml version="1.0" encoding="UTF-8"?>

<plugin
   name="%Plugin.name"
   id="org.eclipse.ui"
   version="1.0"
   provider-name="Object Technology International, Inc."
   class="org.eclipse.ui.internal.WorkbenchPlugin">

<extension-point name="%ExtPoint.editorMenus " id="editorActions"/>
<extension-point name="%ExtPoint.popupMenus " id="popupMenus"/>
<extension-point name="%ExtPoint.importWizards" id="importWizards"/>

</plugin>
   
<?xml version="1.0" encoding="UTF-8"?>

<plugin
   name="%Plugin.name"
   id="org.eclipse.ui"
   version="1.0"
   provider-name="Object Technology International, Inc."
   class="org.eclipse.ui.internal.WorkbenchPlugin">

<extension-point name="%ExtPoint.editorMenus " id="editorActions"/>
<extension-point name="%ExtPoint.popupMenus " id="popupMenus"/>
<extension-point name="%ExtPoint.exportWizards" id="exportWizards"/>

</plugin>

Assume that the order of the elements should be ignored. The structural difference between the two documents consists in the extension-point element on the left with id="importWizards" being replaced on the right with a new extension-point with id="exportWizards". Using the general matching algorithm called Unordered, because it ignores the order in which the XML elements appear in the document, we obtain the following tree of differences.

Difference Tree using General Matching Algorithm

The first two extension-point elements are identical and are therefore matched and are not shown in the difference tree. There remains the third extension-point element on both sides which, having the same element name, are also matched. The difference tree then shows the differences between the third extension-point element left and the third extension-point element right. These differences consist in the values of the attributes id and name.
However, this is not what we would like to see. We would like the difference tree to show us that an extension-point element was removed from the left side and a new extension-point element was added on the right side.
To achieve this, we create a new ID Mapping Scheme. We can do this by using the appropriate button on toolbar.

Creating a new ID Mapping Scheme

Assume we call the ID Mapping Scheme MyPlugin. We now select the ID Mapping Scheme MyPlugin from the drop-down list in the Toolbar

Select MyPlugin ID Map Scheme

and add to it the following Mapping:

Creating a new mapping from the preference page     Creating a new mapping using the context menu

This can be done from the preference page (left) or from the context menu in the structure view (right).
The difference tree now becomes:
(To refresh the structure view, click on the Button for updating view button of the drop-down list in the toolbar.)

Difference Tree using MyPlugin ID Mapping Scheme

This is the compare result that we wanted and that we achieved by created an ID Mapping Scheme.

The XML Compare Plugin already comes with a ID Mapping Scheme for Plugin files, which can be customized for particular Plugin files.

Warning:
If an ID Mapping is created, it is assumed that the id is unique, i.e. there are no two XML elements with the same name and path that have the same id. Should this not be the case, the ID Mapping Scheme may not deliver a sensible difference tree.
When an id can appear more than once, one should rely on the general algorithm.

Also, when an ID Mapping Scheme is used and there are elements with no id mapping specified, the Unordered compare method will be used, i.e. elements are matched by their similarity and not by the order in which they appear in the document. To specify that the children of an element should be compared in order of appearance. See the next section on Ordered entries.

Adding Ordered entries

Ordered entries are used to specify that the direct children (excluding attributes) of an xml element - identified by its path - should be compared in ordered way instead of the default unordered method.
As an example consider the following ANT file in two slightly different versions: 
<?xml version="1.0" encoding="UTF-8"?>

<project name="org.junit.wizards" default="export" basedir="..">
   <target name="export" depends="build">
      <mkdir dir="${destdir}" />

      <delete dir="${dest}" />
      <mkdir dir="${dest}" />

      <jar
         jarfile="${dest}/JUnitWizard.jar"
         basedir="bin"
      />

</project>
   
<?xml version="1.0" encoding="UTF-8"?>

<project name="org.junit.wizards" default="export" basedir="..">
   <target name="export" depends="build">
      <mkdir dir="${destdir}"/>

      <mkdir dir="${dest}"/>
      <delete dir="${dest}"/>

      <jar
         jarfile="${dest}/JUnitWizard.jar"
         basedir="bin"
      />

      <copy file="plugin.xml" todir="${dest}"/>


</project>

The differences between the two documents are shown in bold. Two elements have been swapped (<mkdir dir="${dest}"/> and <delete dir="${dest}"/>) and a new element (<copy .../>) has been appended to the target element.
Performing an unordered compare will result in the following tree of differences:

Difference Tree using Unordered Matching

The fact that two elements have been swapped is not shown since the order of elements is ignored.
However, from an ANT point of view, the two documents cause very different behaviour, because the order of the elements inside a target is important. We therefore want to create an ordered entry for target to instruct the compare engine to compare the direct children of target in ordered fashion.
We do so by first creating a new ID Mapping Scheme. This can be done using the appropriate button in the toolbar.

Creating a new ID Mapping Scheme

Assume we call the ID Mapping Scheme MyANT.
We now select the ID Mapping Scheme MyANT from the drop-down list in the Toolbar and add to it the following Ordered Entry:

Creating a new orderered entry from the preference page     Creating a new ordered entry using the context menu

This can be done from the preference page (left) or from the context menu in the structure view (right).
The difference tree now becomes:
(To refresh the structure view, click on the Button for updating view button of the drop-down list in the toolbar.)

Difference Tree using MyANT ID Mapping Scheme

This is the compare result that we wanted and that we achieved by creating an Ordered Entry.

Additionally, Id Mappings (see previous section) can be used to uniquely identify ordered children. Especially when there are many changes, this will improve compare results.

The XML Compare Plugin already comes with a ID Mapping Scheme for ANT files, which can be customized for particular ANT files.