XML Compare Extension Points: idMapping

# idMapping

Identifier: org.eclipse.compare.examples.xml.idMapping

Description: This extension point allows to define internal XML ID Mapping schemes using the mapping element. These schemes can then be used when performing an XML compare to uniquely identify XML elements by the value of an attribute or the text in a child element.
Additionally, ordered elements can be used to specify that the direct children of an element should be compared in ordered fashion instead of the default unordered way.

Configuration Markup:

`<!ELEMENT idmap (mapping*)>`
`<!ATTLIST idmap`
`name CDATA #REQUIRED`
`extension CDATA`
`>`

- name - the name of the ID Mapping scheme. Should be unique.
- extension - (optional) a file extension associated with this ID Mapping Scheme. When comparing files with this extension, the current ID Mapping Scheme will automatically be used.
  If an extension is specified, then the extension should also be added in the plugin.xml file of the XML Compare Plugin. For example, if we create an ID Mapping Scheme with extension cd, the plugin.xml of the XML Compare Plugin is updated as follows (update shown in bold): `

  <extension
  point="org.eclipse.compare.structureMergeViewers">
  <structureMergeViewer
  extensions="cxml,classpath,cd"
  class="org.eclipse.compare.xml.XMLStructureViewerCreator">
  </structureMergeViewer>

  `

  Warning: If an extension is associated more than once, only the first association will be considered. Also, internal ID Mapping schemes have priority over user ID Mapping schemes when duplicate extensions are defined.

  Warning: When an internal ID Mapping scheme with extension association is removed (from a `plugin.xml`), the XML Compare plugin has to be reloaded to disassociate itself from the extension. If not, on the first compare of files with this extension, the XML Compare plugin will be used with the default Unordered algorithm. (However, at this point the extension will have been disassociated from the XML Plugin, as the plugin has been loaded.)

`<!ELEMENT mapping EMPTY>`
`<!ATTLIST mapping`
`signature CDATA #REQUIRED`
`id CDATA #REQUIRED`
`id-source CDATA`
`>`

- signature - the XML path from the root to the current element (see examples below).
- id - the attribute that identifies this element or the name of the child element whose text identifies this element.
- id-source - (optional) if id is the name of a child element, then this attribute must have the value body. If id-source is left out, it is assumed that id is an attribute.

`<!ELEMENT ordered EMPTY>`
`<!ATTLIST ordered`
`signature CDATA #REQUIRED`
`>`

- signature - the XML path from the root to the element whose direct children will be compared in ordered fashion instead of the default unordered way.

Examples:
The following is an example ID Mappings Scheme for ANT files.
project elements are identified by an attribute name. target elements (which are children of project) are also identified by an attribute name. Also, the children of target will be compared in the order in which they appear in the document. `

<idmap name="ANT">
<mapping signature="project" id="name"/>
<mapping signature="project>target" id="name"/>
<ordered signature="project>target"/>
<idmap>

`

The following example illustrates a case where the text of a child element is used as id: ``

<idmap name="Book Catalog" extension="book">
<mapping signature="catalog>book" id="isbn" id-source="body"/>
<idmap>

Supplied Implementation:
The XML Compare plugin defines an ID Mapping scheme for Eclipse `plugin.xml` files, one for `.classpath` files and one for ANT files.