Features and Properties

Introduction

The comparison engine used in several XML Compare 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.

Using Features and Properties

XML Compare 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.

Runtime	Package/Namespace	Class and method
Java	com.deltaxml.api	XMLComparator.setFeature(String, boolean)
		XMLComparator.setProperty(String, Object)
		XMLCombiner.setFeature(String, boolean)
		XMLCombiner.setProperty(String, Object)
	com.deltaxml.core	PipelinedComparator.setComparatorFeature(String, boolean)
	com.deltaxml.core	PipelinedComparator.setComparatorProperty(String, Object)
	com.deltaxml.cores9api	PipelinedComparatorS9.setComparatorFeature(String, boolean)
	com.deltaxml.cores9api	PipelinedComparatorS9.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/DCP declarative pipeline definition languages include XML elements for comparator configuration. Here is a fragment of a DXP file providing a configuration example:

XML

<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.

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 i the Java com.deltaxml.cores9api package.

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

deltaV2

This feature has been deprecated in version 11.0.0

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

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

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

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 XML Compare and the inputs that were used.
False:	No comment is added to the output.
Default value:	true
Applies to:	XMLComparator, XMLCombiner, PipelinedComparator, PipelinedComparatorS9

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 the Java com.deltaxml.cores9api package.

orderlessPresentation

Full name:	`http://deltaxml.com/api/property/orderlessPresentation`
Java Field:	PipelinedComparatorS9.ORDERLESS_PRESENTATION
Java value type:	`java.lang.String`
String: a_matches_deletes_adds	With this value, the output for any orderless comparison is presented in a defined order as follows: 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'. These are followed by 'deletes' (elements which only appear in the 'A' input and have deltaxml:deltaV2='A') 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: 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'. These are followed by 'adds' (elements which only appear in the 'B' input and have deltaxml:deltaV2='B') 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