Features and Properties

1. Introduction

The comparison engine used in several DeltaXML API packages has a number of configuration properties and features which affect the behaviour of the comparison/alignment process. This document lists all of the available properties and features and also describes the various ways in which they can be used (in API code and DXP files).

The configuration technique is modelled on the properties and features configuration mechanism provided by the Java JAXP interfaces for XML/SAX parser and XSLT transformer configuration. One of the motivations for JAXP was to provide 'pluggable' parser and transform implementations so that, for example, users could swap between Xerces and Aelfred, for Xalan-J and Saxon by runtime configuration. Having a late bound configuration mechanism using properties and features supports the run-time configuration of the processors.

At DeltaXML we copied this metaphor when we created our first Java APIs and we still provide this mechanism. We now also provide some early-bound method calls in addition to properties and features as these provide better type safety and API usability particularly when using an IDE.

2. Using Features and Properties

DeltaXML APIs provide a number of methods for feature and property configuration. In the following table we will document the various 'set' methods, there are also corresponding 'get' methods. Please see the API documentation for further details.

RuntimePackage/NamespaceClass and method
Javacom.deltaxml.api XMLComparator.setFeature(String, boolean)
XMLComparator.setProperty(String, Object)
XMLCombiner.setFeature(String, boolean)
XMLCombiner.setProperty(String, Object)
com.deltaxml.corePipelinedComparator.setComparatorFeature(String, boolean)
PipelinedComparator.setComparatorProperty(String, Object)
com.deltaxml.cores9api PipelinedComparatorS9.setComparatorFeature(String, boolean)
PipelinedComparatorS9.setComparatorProperty(String, Object)
.NETDeltaXML.CoreS9Api PipelinedComparator.setComparatorFeature(string, bool)
PipelinedComparator.setComparatorProperty(string, Object)

As well as the above methods our later pipeline orientated APIs also include other methods for setting properties and features on other components within the pipeline such as the parser and serializer. These methods have similar names and signatures such as:

However these methods do not accept the same feature and property name strings. Our API documentation usually includes links to webpages or other resources which document the allowed values (please note the 'See also' links in Javadoc).

Our DXP declarative pipeline definition language includes XML elements for comparator configuration. Here is a fragment of a DXP file providing a configuration example:

<comparatorPipeline id="demo">...
  <parserFeatures>
    <feature name="http://apache.org/xml/features/xinclude" 
             literalValue="true"/>
  </parserFeatures>
  <comparatorFeatures>
    <feature name="http://deltaxml.com/api/feature/isFullDelta" 
             literalValue="true"/>
  </comparatorFeatures>
  <comparatorProperties>
    <property name="http://deltaxml.com/api/property/orderlessPresentation" 
              literalValue="a_matches_deletes_adds"/>
  </comparatorProperties>
</comparatorPipeline>

Further details are included in our DXP User Guide.

3. Lists of Features

The following sections list the available features. Some are available only with the XMLCombiner class provided in the com.deltaxml.api package and others can be used with the comparator in both its basic and pipelined forms as described above. When 'PipelinedComapatorS9' is used within 'Applies to' sections below this means it can be used in both the Javc com.deltaxml.cores9api package and the .NET DeltaXML.CoreS9Api namespace.

3.1. isFullDelta

Full name: http://deltaxml.com/api/feature/isFullDelta
True: A full delta containing both the differences and also the similarities between the two input trees is produced
False: A standard (differences only) delta is produced
Default value: true
Applies to: XMLComparator, PipelinedComparator, PipelinedComparatorS9

3.2. deltaV2

Full name: http://deltaxml.com/api/feature/deltaV2
True: The feature setting controls the version of the delta format produced by the comparator. The true setting causes the newer version 2 delta format to be generated. We recommend this setting for all new users.
False: A backwards-compatible (version 1) delta is produced.
Default value: true
Applies to: XMLComparator, XMLCombiner, PipelinedComparator, PipelinedComparatorS9

3.3. enhancedMatch1

Full name: http://deltaxml.com/api/feature/enhancedMatch1
True: A modified comparison (matching) algorithm that is tailored to documents, i.e. XML with a high proportion of text data, is used. This gives better matching results particularly when used in conjunction with word-by-word filtering.
False: A backwards-compatible (pre release 4.x) matching algorithm is used
Default value: true
Applies to: XMLComparator, PipelinedComparator, PipelinedComparatorS9

3.4. isCombineForward

Full name: http://deltaxml.com/api/feature/isCombineForward
True: A (standard) forward combination is performed. If a delta is produced between file-a and file-b called delta-ab then this can be combined with file-a in a forward direction to produce file-b.
False: A reverse combination (delta-ab with file-b producing file-a) is performed.
Default value: true
Applies to: XMLCombiner

3.5. outputHeaderComment

Full name: http://deltaxml.com/api/feature/outputHeaderComment
True: A comment is added to the output to record that the XML file is the result of using DeltaXML Core and the inputs that were used.
False: No comment is added to the output.
Default value: true
Applies to: XMLComparator, XMLCombiner, PipelinedComparator, PipelinedComparatorS9

4. List of Properties

Properties are more complex settings than features, in that rather than having a boolean value, the value is an Object. In some cases we would expect the values provided to be of a certain type, otherwise an exception will be thrown. Exceptions may also be thrown for illegal or unexcepted values. Further details of the expected types and values are included below.

When 'PipelinedComapatorS9' is used within 'Applies to' sections below this means it can be used in both the Java com.deltaxml.cores9api package and the .NET DeltaXML.CoreS9Api namespace.

4.1. orderlessPresentation

Full name: http://deltaxml.com/api/property/orderlessPresentation
Java Field: PipelinedComparatorS9.ORDERLESS_PRESENTATION
Java value type:java.lang.String
.NET value type:System.String
String:
a_matches_deletes_adds

With this value, the output for any orderless comparison is presented in a defined order as follows:

  1. all of the matches from the A input in the same order as they appear in A. In this context matches means elements with these deltaxml:deltaV2 values: 'A=B' and 'A!=B'.
  2. These are followed by 'deletes' (elements which only appear in the 'A' input and have deltaxml:deltaV2='A')
  3. Finally 'adds' (elements which only appear in the 'B' input and have deltaxml:deltaV2='B').
String:
a_adds

The 'adds' and then the 'deletes' appear in the same order as they appear in their respective inputs.

With this value, all of the elements from the A input appear in the result in the same order as they appear in that input. Their deltaxml:deltaV2 values ('A=B', 'A!=B' and 'A') will indicate if a similar (as defined by exact subtree or key matching) element appears in the B input and if so how they correspond. Finally the 'adds' - elements from B, with no matches to those in the A input, are listed in the order in which they appear in B.

String:
b_matches_adds_deletes

The output for any orderless comparison is presented in a defined order as follows:

  1. all of the matches from the B input in the same order as they appear in B. In this context matches means elements with these deltaxml:deltaV2 values: 'A=B' and 'A!=B'.
  2. These are followed by 'adds' (elements which only appear in the 'B' input and have deltaxml:deltaV2='B')
  3. Finally 'deletes' (elements which only appear in the 'A' input and have deltaxml:deltaV2='A').
String:
b_deletes

The 'deletes' and then the 'adds' appear in the same order as they appear in their respective inputs.

With this value, all of the elements from the B input appear in the result in the same order as they appear in that input. Their deltaxml:deltaV2 values ('A=B', 'A!=B' and 'B') will indicate if a similar (as defined by exact subtree or key matching) element appears in the A input and if so how they correspond. Finally the 'deletes' - elements from A, with no matches to those in the B input, are listed in the order in which they appear in A.

Default value: a_matches_deletes_adds
Applies to: XMLComparator, PipelinedComparator, PipelinedComparatorS9