Ignore Changes

 Table of Contents

1. Introduction

This document describes the concepts behind ignoring changes. For the resources associated with this sample, see the Bitbucket repo.

The XML files that you are comparing may contain data that you expect to change. You may wish to ignore these changes.

1.1. What does "ignore" really mean?

First, we need to ask the question: What is meant by "ignore"?

Consider this very simple example of attribute change:

Input 1:

<x y='1'/> 

Input 2:

<x y='2'/>

XML Data Compare implements the ability to:

  1. remove it completely from the result: <x/>
  2. prefer the 'A' or 'old' value: <x y='1'/>
  3. prefer the 'B' or 'new' value: <x y='2'/>

2. Example data

Imagine comparing the following two inputs, with the intention of ignoring the change made to the lastUpdated attribute:

Example 1: a small address book as an XML file (addressesA.xml)

<addressList>
  <person customerid="16" lastUpdated="01062018">
    <name>Sherlock Holmes</name>
    <email>sherlock@sherlock-holmes.com</email>
    <address>
      <line>221b Baker St</line>
      <line>Marylebone</line>
      <line>London</line>
      <zip>NW1 6XE</zip>
    </address>
    <age>42</age>
    <notes>One night-it was on the 20th of March, 1888-I was returning from a journey to a patient 
      ...
      some new problem. I rang the bell, and was shown up to the chamber which had formerly been in part my own.
    </notes>
    <extra>His manner was not effusive. It seldom was; but he was glad, I think,
      to see me. With hardly a word spoken, but with a kindly eye, he waved
      me to an arm-chair, threw across his case of cigars, and indicated a
      spirit case and a gasogene in the corner. Then he stood before the
      fire, and looked me over in his singular introspective fashion.</extra>
  </person>
</addressList>

Example 2: an updated version of the address book (addressesB.xml)

<addressList>
  <person customerid="16" lastUpdated="01012019">
    <name>Sherlock Holmes</name>
    <email>sherlock@sherlock-holmes.com</email>
    <address>
      <line>221b Baker St</line>
      <line>Marylebone</line>
       <line>London</line>
       <zip>NW1 6XE</zip>
     </address>
    <age>42</age>
    <notes>One night-it was on the 20th of March, 1888-I was returning from a
       ...
      bell, and was shown up to the chamber which had formerly been in part
      my own.
    </notes>
    <extra>His manner was not effusive. It seldom was; but he was glad, I think,
      to see me. With hardly a word spoken, but with a roving eye, he waved
      me to an arm-chair, threw across his case of cigars, and indicated a
      spirit case and a SodaStream in the corner. Then he stood before the
      window, and looked me over in his singular introspective fashion.</extra>
  </person>
</addressList>

XML Data Compare will produce the following delta:

<addressList xmlns:deltaxml="http://www.deltaxml.com/ns/well-formed-delta-v1" xmlns:dxx="http://www.deltaxml.com/ns/xml-namespaced-attribute" xmlns:pi="http://www.deltaxml.com/ns/processing-instructions" xmlns:ignore="http://www.deltaxml.com/ns/ignoreForAlignment" xmlns:preserve="http://www.deltaxml.com/ns/preserve" xmlns:dxa="http://www.deltaxml.com/ns/non-namespaced-attribute" xmlns:er="http://www.deltaxml.com/ns/entity-references" deltaxml:deltaV2="A!=B" deltaxml:version="2.0" deltaxml:content-type="full-context">
    <person deltaxml:deltaV2="A!=B" customerid="16">
        <deltaxml:attributes deltaxml:deltaV2="A!=B">
            <dxa:lastUpdated deltaxml:deltaV2="A!=B">
                <deltaxml:attributeValue deltaxml:deltaV2="A">01062018</deltaxml:attributeValue>
                <deltaxml:attributeValue deltaxml:deltaV2="B">01012019</deltaxml:attributeValue>
            </dxa:lastUpdated>
        </deltaxml:attributes>
        <name deltaxml:deltaV2="A=B">Sherlock Holmes</name>
        <email deltaxml:deltaV2="A=B">sherlock@sherlock-holmes.com</email>
        <address deltaxml:deltaV2="A=B">
            <line>221b Baker St</line>
            <line>Marylebone</line>
            <line>London</line>
            <zip>NW1 6XE</zip>
        </address>
        <age deltaxml:deltaV2="A=B">42</age>
        <notes deltaxml:deltaV2="A=B">One night-it was on the 20th of March, 1888 ... I rang the bell, and was shown up to the chamber which had formerly been in part my own. </notes>
        <extra deltaxml:deltaV2="A!=B">His manner was not effusive. It seldom was; but he was glad, I think, to see me. With hardly a word spoken, but with a 
            <deltaxml:textGroup deltaxml:deltaV2="A!=B">
                <deltaxml:text deltaxml:deltaV2="A">kindly</deltaxml:text>
                <deltaxml:text deltaxml:deltaV2="B">roving</deltaxml:text>
            </deltaxml:textGroup> eye, he waved me to an arm-chair, threw across his case of cigars, and indicated a spirit case and a
            <deltaxml:textGroup deltaxml:deltaV2="A!=B">
                <deltaxml:text deltaxml:deltaV2="A">gasogene</deltaxml:text>
                <deltaxml:text deltaxml:deltaV2="B">SodaStream</deltaxml:text>
            </deltaxml:textGroup> in the corner. Then he stood before the
            <deltaxml:textGroup deltaxml:deltaV2="A!=B">
                <deltaxml:text deltaxml:deltaV2="A">fire</deltaxml:text>
                <deltaxml:text deltaxml:deltaV2="B">window</deltaxml:text>
            </deltaxml:textGroup>, and looked me over in his singular introspective fashion.
        </extra>
    </person>
</addressList>

3. Indicating data that needs to be ignored

Next we need to mark our data to be ignored, this is achieved by adding elements to the config file:

  • to ignore an attribute change: specify the XPath of the attribute 
  • to ignore a sub-tree change: specify the XPath of the sub-tree

See the Configuration File Schema Guide for details of the syntax of the options for which version to use.

An example for ignoring changes to the lastUpdated attribute and the extra element is included below.

Example 3: Config file (config-ignore-changes.xml in the sample on Bitbucket)

<dcf:configuration id="config1" version="1.0" xmlns:dcf="com.deltaxml.data.config"> 
  <!-- Any differences between elements called <extra> will always be ignored and the version in document A used in the result-->
  <dcf:location name="Extra" xpath="//extra">
    <dcf:ignore-changes use="B"/>
  </dcf:location>
  <dcf:location name="Updated" xpath="//person/@lastUpdated">
    <dcf:ignore-changes use="DELETE"/>
  </dcf:location>
</dcf:configuration>

4. Running the sample code

For the resources associated with this sample, see the Bitbucket repo, here 

Download the sample resources and compare the sample files.

Instructions for running the sample are given in README.md

#content .code