# Eclipse Platform XML Compare

The XML Compare plugin allows you to perform a structural compare of two XML documents. It returns a difference tree which indicates which XML elements have been added or removed and - for modified XML elements - what differences there are with respect to attributes or body text.

## Installing the plugin

- Copy the folder `org.eclipse.compare.examples.xml` to the `plugins` subfolder of Eclipse.

## Using the plugin

The plugin is automatically used when comparing files with the extension .cxml. The reason for this is that the plug-in illustrates how to register a compare merge viewer and other viewers, not to provide a compare of real XML files itself.
By default, the XML compare uses the Unordered compare method, which ignores the order in which the XML elements appear in the document and matches them so that elements which are most similar are matched. There is also an Ordered compare method, which simply compares the XML elements exactly in the order in which they appear in the document. In most cases, this compare method will not be of much use.
The compare method can be changed from a drop-down list in the toolbar of the structure view.
When an XML document contains elements that can uniquely be identified by an attribute or the text of a child element, it is recommended that an ID Mapping Scheme be created for this type of XML document.
See Tutorial and Examples for more information on using the plugin.

### ID Mapping Schemes

An ID Mapping Scheme specifies for XML elements an attribute or the text of a child element that uniquely identifies this element. This assures that - in the compare process - the right elements will be matched and therefore compared with each other. If for an XML element no ID Mapping is specified, a general matching algorithm is be used. However, this general matching algorithm does not always return the desired result. The reason for this is that the general matching algorithm looks for a matching of the nodes of the two parsed trees to compare that minimizes the differences. The effect is that often two XML elements are matched with are structurally similar but represent two completely different entities of information.

### Ordered entries

When using the default Unordered compare (with or without id mappings) it is sometimes desired to specify that the children of certain elements be compared in ordered fashion intead of the usual unordered method. For example, when comparing ANT files the order of appearance of the children of `target` elements is important.
In such cases one can create an Ordered entry. An Ordered entry specifies that the direct children of an xml element, identified by its path, will be compared in ordered fashion (attributes however are still compared in unordered way). The children of these children will continue to be compared in unordered way, unless otherwise specified.

### Defining ID Mapping Schemes and Ordered entries

ID Mapping Schemes can be created in three different ways:

1. By extending the extension point idMapping
2. Using the XML Compare Preference page.
3. Using the Create new Id Map Scheme button in the toolbar and the context menu

Method 1 creates a so-called internal mapping scheme. An internal ID Mapping Scheme cannot be edited at runtime. However, using the Edit Copy button in the Preference Page, an editable copy of the internal ID Mapping Scheme can be created.
Methods 2 and 3 create so-called user mapping schemes. These are created by the user at runtime and can be modified anytime in the Preference Page.

Internal and user mapping schemes can be associated with a file extension. As a result, when comparing two XML files with this file extension, the particular ID Mapping scheme with this extension is automatically used.
When creating or editing the ID mapping for a particular XML element, four items must be specified (see example):

1. The element name.
2. The element path. This is the path of the element from the root of the XML document to the element's parent.
3. The name of the id which will identify the element
4. Whether the id name in point 3 is the name of an attribute of the element or the name of one of its children (in which case the text of this child element will be used as id).

# Extension Points

Only one extension point is available in the XML Compare plugin. It is used to create internal ID Mapping Schemes:

- org.eclipse.compare.examples.xml.idMapping