# 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.
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.
Assume we call the ID Mapping Scheme MyPlugin. We now select the ID Mapping Scheme MyPlugin from the drop-down list in the Toolbar
and add to it the following Mapping:

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 of the drop-down list in the toolbar.)
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:
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.
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:

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 of the drop-down list in the toolbar.)
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.