1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Tutorial and Examples</title>
</head>
<body link="#0000FF" vlink="#800080">
<h1>Tutorial and Examples</h1>
<h2><a id="id_mapping" name="id_mapping">
General Matching vs. ID Mapping Schemes:<br>How to create an ID Mapping Scheme to improve compare results
</a></h2>
Consider an example XML file in two slightly different versions, left and right. Assume that the element <tt>extension-point</tt> is uniquely identified by the attribute <tt>id</tt>.
The textual differences are shown in bold.
<table>
<tr>
<td><tt>
<br>
<p><?xml version="1.0" encoding="UTF-8"?>
<p><plugin
<br>
name="%Plugin.name"
<br>
id="org.eclipse.ui"
<br>
version="1.0"
<br>
provider-name="Object Technology International, Inc."
<br>
class="org.eclipse.ui.internal.WorkbenchPlugin">
<br>
<br><extension-point name="%ExtPoint.editorMenus " id="editorActions"/>
<br><extension-point name="%ExtPoint.popupMenus " id="popupMenus"/>
<br><extension-point name="%ExtPoint.<b>importWizards</b>" id="<b>importWizards</b>"/>
<br>
<p></plugin>
</tt>
</td>
<td>
</td>
<td><tt>
<p><?xml version="1.0" encoding="UTF-8"?>
<p><plugin
<br>
name="%Plugin.name"
<br>
id="org.eclipse.ui"
<br>
version="1.0"
<br>
provider-name="Object Technology International, Inc."
<br>
class="org.eclipse.ui.internal.WorkbenchPlugin">
<br>
<br><extension-point name="%ExtPoint.editorMenus " id="editorActions"/>
<br><extension-point name="%ExtPoint.popupMenus " id="popupMenus"/>
<br><extension-point name="%ExtPoint.<b>exportWizards</b>" id="<b>exportWizards</b>"/>
<br>
<p></plugin>
</tt>
</td>
</tr>
</table>
<br>
Assume that the order of the elements should be ignored. The structural difference between the two documents consists in the <tt>extension-point</tt> element on the left with <tt>id="importWizards"</tt> being replaced on the right with a new <tt>extension-point</tt> with <tt>id="exportWizards"</tt>.
Using the general matching algorithm called <em>Unordered</em>, because it ignores the order in which the XML elements appear in the document, we obtain the following tree of differences.
<br>
<br>
<img src="IDMap_GeneralMatching.gif" alt="Difference Tree using General Matching Algorithm">
<br>
<br>
The first two <tt>extension-point</tt> elements are identical and are therefore matched and are not shown in the difference tree. There remains the third <tt>extension-point</tt> element on both sides which, having the same element name, are also matched.
The difference tree then shows the differences between the third <tt>extension-point</tt> element left and the third <tt>extension-point</tt> element right.
These differences consist in the values of the attributes <tt>id</tt> and <tt>name</tt>.
<br>
However, this is not what we would like to see. We would like the difference tree to show us that an <tt>extension-point</tt> element was removed from the left side and a new <tt>extension-point</tt> element was added on the right side.
<br>
To achieve this, we create a new ID Mapping Scheme. We can do this by using the appropriate button on toolbar.
<br><br>
<img src="IDMap_NewIDMapScheme.gif" alt="Creating a new ID Mapping Scheme">
<br><br>
Assume we call the ID Mapping Scheme <em>MyPlugin</em>. We now select the ID Mapping Scheme MyPlugin from the drop-down list in the Toolbar
<br><br>
<img src="IDMap_SelectMyPlugin.gif" alt="Select MyPlugin ID Map Scheme">
<br><br>
and add to it the following Mapping:
<br><br>
<table>
<tr>
<td>
<img src="IDMap_NewMapping_PreferencePage.gif" alt="Creating a new mapping from the preference page">
</td>
<td>
</td>
<td>
<img src="IDMap_NewMapping_ContextMenu.gif" alt="Creating a new mapping using the context menu">
</td>
</tr>
</table>
<br>
This can be done from the preference page (left) or from the context menu in the structure view (right).
<br>
The difference tree now becomes:
<br>
(To refresh the structure view, click on the <img src="smartmode_co.gif" alt="Button for updating view"> button of the drop-down list in the toolbar.)
<br><br>
<img src="IDMap_MyPlugin.gif" alt="Difference Tree using MyPlugin ID Mapping Scheme">
<br><br>
This is the compare result that we wanted and that we achieved by created an ID Mapping Scheme.
<br>
<br>
The XML Compare Plugin already comes with a ID Mapping Scheme for Plugin files, which can be customized for particular Plugin files.
<br><br>
<b>Warning:</b>
<br>
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.
<br>
When an id can appear more than once, one should rely on the general algorithm.
<br>
<br>
Also, when an ID Mapping Scheme is used and there are elements with no id mapping specified, the <em>Unordered</em> 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.
<h2>Adding Ordered entries</h2>
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.
<br> As an example consider the following ANT file in two slightly different versions:
<table>
<tr>
<td>
<tt>
<p><?xml version="1.0" encoding="UTF-8"?>
<p><project name="org.junit.wizards" default="export" basedir="..">
<br>
<target name="export" depends="build">
<br>
<mkdir dir="${destdir}" />
<br>
<b>
<delete dir="${dest}" />
<br>
<mkdir dir="${dest}" />
<br>
</b>
<jar
<br>
jarfile="${dest}/JUnitWizard.jar"
<br>
basedir="bin"
<br>
/>
<br></project>
</tt>
</td>
<td>
</td>
<td>
<tt>
<p><?xml version="1.0" encoding="UTF-8"?>
<p><project name="org.junit.wizards" default="export" basedir="..">
<br>
<target name="export" depends="build">
<br>
<mkdir dir="${destdir}"/>
<br>
<b>
<mkdir dir="${dest}"/>
<br>
<delete dir="${dest}"/>
<br>
</b>
<jar
<br>
jarfile="${dest}/JUnitWizard.jar"
<br>
basedir="bin"
<br>
/>
<br>
<b>
<copy file="plugin.xml" todir="${dest}"/>
</b>
<br></project>
</tt>
</td>
</tr>
</table>
<br>
The differences between the two documents are shown in bold. Two elements have been swapped (<tt><mkdir dir="${dest}"/></tt> and <tt><delete dir="${dest}"/></tt>) and a new element (<tt><copy .../></tt>) has been appended to the target element.
<br>
Performing an unordered compare will result in the following tree of differences:
<br>
<br>
<img src="Ordered_UnorderedScheme.gif" alt="Difference Tree using Unordered Matching">
<br>
<br>
The fact that two elements have been swapped is not shown since the order of elements is ignored.
<br>
However, from an ANT point of view, the two documents cause very different behaviour, because the order of the elements inside a <tt>target</tt> is important.
We therefore want to create an <i>ordered entry</i> for target to instruct the compare engine to compare the direct children of target in ordered fashion.
<br>
We do so by first creating a new ID Mapping Scheme. This can be done using the appropriate button in the toolbar.
<br><br>
<img src="Ordered_NewIDMapScheme.gif" alt="Creating a new ID Mapping Scheme">
<br><br>
Assume we call the ID Mapping Scheme <em>MyANT</em>.
<br>We now select the ID Mapping Scheme MyANT from the drop-down list in the Toolbar and add to it the following Ordered Entry:
<br><br>
<table>
<tr>
<td>
<img src="Ordered_NewOrderedEntry_PreferencePage.gif" alt="Creating a new orderered entry from the preference page">
</td>
<td>
</td>
<td>
<img src="Ordered_NewOrderedEntry_ContextMenu.gif" alt="Creating a new ordered entry using the context menu">
</td>
</tr>
</table>
<br>
This can be done from the preference page (left) or from the context menu in the structure view (right).
<br>
The difference tree now becomes:
<br>
(To refresh the structure view, click on the <img src="smartmode_co.gif" alt="Button for updating view"> button of the drop-down list in the toolbar.)
<br><br>
<img src="Ordered_MyANT.gif" alt="Difference Tree using MyANT ID Mapping Scheme">
<br><br>
This is the compare result that we wanted and that we achieved by creating an Ordered Entry.
<br>
<br>
Additionally, Id Mappings (see <a href="#id_mapping">previous section</a>) can be used to uniquely identify ordered children. Especially when there are many changes, this will improve compare results.
<br>
<br>
The XML Compare Plugin already comes with a ID Mapping Scheme for ANT files, which can be customized for particular ANT files.
<br><br>
<p><a href="hglegal.htm"><img SRC="ngibmcpy.gif" ALT="Copyright IBM Corporation and others 2000, 2003. All Rights Reserved." BORDER=0 height=14 width=324></a></p>
</body>
</html>
|
