Folding DiffReport with DCP
Introduction
DCP and the Document Comparator
For this sample we will use XML Compare's Document Comparator component. We show how extensions to its built-in processing pipeline can be conveniently accessed using the included Document Comparator Pipeline (DCP) definition file 'diffreport.dcp'.
More information on the Document Comparator and DCP can be found here:
The Folding DiffReport
XML Compare includes built-in XSLT stylesheets for rendering XML comparison results using HTML to highlight differences at the syntax-level; this sample focuses on the 'folding' view, but there is also a 'side-by-side' view. The 'side-by-side' view is similar to the folding DiffReport but shows two synchronised-scrolling folding XML views
A folding DiffReport shows formatted XML syntax with folding points highlighted with an arrow icon. Clicking on the arrow either folds or unfolds the adjacent XML, depending on its current view state. When the comparison result is first rendered, nodes with fold-points that have changes are shown expanded and all other fold-points are collapsed. Nodes that have changes have start and end tags coloured in blue, unchanged nodes are shown in grey.
A screenshot of the DiffReport as rendered in a browser:
A simple toolbar along with a 'breadcrumb' view of the currently selected change is shown above the folding view in the DiffReport, there is also a 'Differences List' shown as a vertical panel alongside.
Using DCP to add an output filter
To render a folding DiffReport, it is necessary to add the included XSLT resource xsl/dx2-deltaxml-folding-html.xsl as the final output filter (this XSLT is also available externally in the samples/xsl-filters directory). The following snippet from the DCP file shows how this is done:
...
<extensionPoints>
...
<outputExtensionPoints>
<finalPoint>
<filter if="convert-to-html">
<resource name="xsl/dx2-deltaxml-folding-html.xsl"/>
<parameter name="smart-whitespace-normalization"
parameterRef="smart-whitespace-normalization"/>
...
</filter>
</finalPoint>
</outputExtensionPoints>
</extensionPoints>
The code above shows one of the available parameters for the DiffReport XSLT using a parameterRef attribute to associate it with a DCP parameter. (Note: for a 'side-by-side' change the resource name to 'dx2-deltaxml-sbs-folding-html.xsl'). A full description of all the DCP parameters is shown using the command-line. Replace x.y.z with the major.minor.patch version number of your release e.g. command-10.0.0.jar
java -jar ../../command-x.y.z.jar describe dcp-folding'dcp-folding' is the configuration id included in the DCP file. The output from running the above command summarises the purpose of this DCP and briefly describes each of the defined DCP parameters, as seen below.
Pipeline ID: 'dcp-folding'
Location:
file:{install-dir}/DeltaXML-XML-Compare-9_0_7_j/samples/DCPdiffReport/diffreport.dcp
Short Description:
Render result as folding html view.
Boolean Parameters:
Name | Default Value | Description
-------------------- | ------------- | -----------------------------------
convert-to-html | true | Show result as folding html
load-external-dtd | false | Load an external DTD referenced by
| | the input XML
indent-xml | true | Indent the serialized XML result
resolve-formatting- | true | For formatting-element changes, use
diffs | | those found in the 'B' document
String Parameters:
Name | Default Value | Description
----------------- | ------------------------ | ---------------------------
formatting- | b,i,u,em,strong,emphasis | Comma-separated list of
element-list | | formatting elements
| | defined in the input XML
| | grammar.
schema-location | | Space-separated list: For
| | each supplied namespace
| | give the location of an
| | associated XML Schema
| | file. Schema validation
| | will only be performed
| | when this value is non-
| | empty.
add-all- | false | If true, all namespaces in
namespace- | | rendering are declared
declarations | | in-situ - otherwise, only
| | root element namespaces
| | are declared
minimize- | false | Collapse and do not embed
unchanged- | | unchanged subtrees in
display | | result - helps minimize
| | file size
no-fold-size | 50 | Childless nodes of
| | character-length less
| | that this are shown in
| | full - and are not
| | foldable
Running the sample
The sample code can be downloaded from Bitbucket https://bitbucket.org/deltaxml/folding-diffreport.
Details of how to run the sample are given in the file README.md.
What the Sample Does
The sample code performs two comparisons using the Document Comparator. Each uses the same DCP file to configure the comparator, but with the convert-to-html parameter set true in the first comparison and false in the second.
The output files from the two comparisons are result1.html and result2.xml. The latter file is the 'delta' XML output, which is initially harder to understand than the html-rendered DiffReport, but may be useful for reference.
Notes on DCPConfiguration Java API
The DCPConfiguration class in the samples is used to manage DCP configurations using the API. This class has 'generate' and 'setParams' methods that are used to create or modify a DocumentComparator configured using the DCP file. Any parameter overrides are supplied within Map arguments for these methods. Full source code is included in the DCPConfigurationSample.java source file. A snippet is shown below.
...
Map dcpStringParams= new HashMap<String, String>();
dcpStringParams.put("formatting-element-list", "b,i,u");
Map dcpBooleanParams= new HashMap<String, Boolean>();
dcpBooleanParams.put("convert-to-html", true);
DCPConfiguration dcp= new DCPConfiguration(dcpDefinition);
// generate with initial configuration
dcp.generate(dcpBooleanParams, dcpStringParams);
DocumentComparator comparator = dcp.getDocumentComparator();
File result1= new File(dcResultFolder, "result1.html");
// comparison 1:
comparator.compare(input1, input2, result1);
// now modify configuration
dcpBooleanParams.put("convert-to-html", false);
dcp.setParams(dcpBooleanParams, dcpStringParams);
File result2= new File(dcResultFolder, "result2.xml");
// comparison 2:
comparator.compare(input1, input2, result2);
...