Folding DiffReport with DCP

1. Introduction

1.1. DCP and the Document Comparator

For this sample we will use DeltaXML Core'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:

1.2. The Folding DiffReport

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

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.

2. 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. A full description of all the DCP parameters is shown using the command-line:

java -jar ../../command.jar describe dcp-folding
Alternatively, if you're using the .NET distribution of Core, the following command is equivalent:
..\..\bin\deltaxml.exe 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}/DeltaXMLCore-7_1_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
      

3. Running the sample

The sample code (in the samples/DCPdiffReport directory of the DeltaXML Core release) 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.

3.1. Using Java

With the Command-line interface

If you are using any Java version of DeltaXML Core and have Apache Ant installed, use the build script provided to run the command-line sample. Simply type the following command. This will generate output for all three methods in the results directory.

ant

Also using the Apache Ant build script provided, you can simply type the following command to generate output for the two command line DCP methods in the results directory.

ant run-dcp-command

If you don't have Ant installed, you can run the samples from a command line by issuing commands from the sample directory (ensuring that you use the correct directory and class path separators for your operating system):

java -jar ../../command.jar compare dcp-folding input1.xml input2.xml result.html formatting-element-list=b,i,u convert-to-html=true
java -jar ../../command.jar compare dcp-folding input1.xml input2.xml result.xml formatting-element-list=b,i,u convert-to-html=false
    

With DCPConfiguration Java API

The DCPConfiguration class 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);
    ...
    

The following command is used to compile and run this API sample using Apache Ant.

ant run-dcp-api

3.2. Using .NET Framework

With the Command-line interface

To run the sample using the command-line interface for deltaxml.exe, launch the batch file run-dcp.bat, either from the command-line or from Windows Explorer. Alternatively, deltaxml.exe could be run with the sample dcp directly from the command-line with the following command.

..\..\bin\deltaxml.exe compare dcp-folding input1.xml input2.xml result.html

With C# and the .NET API DCPConfiguration class

From Visual Studio, select File, Open Project/Solution from the menu-bar (Ctrl-Shift-O), navigate to the dotnet-api directory and open the DiffReportDCP.sln file. Once the DiffReportDCP project is loaded, you can build and run it in the usual way for Visual Studio (keyboard shortcut: F5).