Getting Started

Introduction

Welcome to the XML Compare product! XML Compare enables you to compare any XML documents or data and either view the changes in a browser or process the changes to integrate change control into your own systems. The XML Compare product provides a toolkit for general purpose, extensible comparison and recombination for XML data.

The Java release contains:

• The com.deltaxml.cores9api package: our latest API providing a high performance and feature rich comparison pipeline using Java pre-compiled or XSLT filters and providing support for Saxon's s9api interfaces.

• deltaxml-rest-x.y.z.jar^* - XML Compare's REST API, built to run DXP / DCP / DTCP pipelines. To learn more about its use, see the REST documentation.

• The command-x.y.z.jar^* command-line interface/driver (no programming required).

• The com.deltaxml.core package: legacy API for easy comparison pipeline construction using Java or XSLT filters.

• The com.deltaxml.api package: a JAXP compatible, low-level legacy API to DeltaXML.

^*where 'x.y.z' is the major.minor.patch version e.g. '17.0.0'

The REST API is licensed separately, and is also not yet intended for use in a Software-As-A-Service model. Please contact DeltaXML for more details.

For a high-level overview of XML Compare along with links to more detailed documentation, please see the User Guide. For general DeltaXML documentation and resources: General Documentation

What can XML Compare do?

XML Compare compares two input XML documents and generates an output delta. This delta has been designed to be concise, easy to understand and easy to process. You can choose between a full context delta showing the changes in the context of the original document and a changes only delta. The delta may be used simply to display changes to the user, or may be fed through for downstream processing. Configuration is through the use of pipelines, giving Java and XSLT programmers a simple and powerful way to adapt XML Compare processing for specific needs. You'll find more details in the  User Guide

Prerequisites

XML Compare is written in pure Java, so the only software requirement is to install a Java runtime (and SDK to use the Java API) version 1.8 or greater, either 32-bit or 64-bit.

There are no specific hardware requirements, however we recommend a system with a minimum of 8 Gigabytes of RAM installed.

Command Line Interface

The release includes a command line processor which can be used to perform comparison and recombination operations on local files through a simple command line interface. This command line interface is contained in command-x.y.z.jar and is used like this, replacing 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 status
java -jar command-x.y.z.jar compare diffreport file1.xml file2.xml diffs.html
java -jar command-x.y.z.jar ...

Further details are on page  Using the Command-Line Tool

Java APIs

A number of Java APIs are provided. They have differing capabilities and some are retained for compatibility reasons. This section provides an outline of the different packages.

Samples with code and data are provided on Bitbucket here.  These include Ant build scripts which can automate compilation/running.

Also see the  Samples And Guides page.

For versions prior to 10.0.0 - to determine the release/version information for the API, invoke:

java -jar deltaxml.jar

(S9API) PipelinedComparatorS9, DocumentComparator, and DataComparator

This API based on Saxon's s9api includes the PipelinedComparatorS9 class. First included in the 6.0 release, this class provides a more efficient and powerful pipeline than the APIs used in earlier releases. Comparison pipelines can include either Java or XSLT filters. You can construct the pipelines in Java or in XML using a 'DXP' (DeltaXML Pipeline).  See the  DXP User Guide.

The DocumentComparator class, introduced in release 7.0, is based on the PipelinedComparatorS9 class but has been extended with a pipeline readily configurable for text-centric XML comparisons. The Java API or a 'DCP' (Document Comparator Pipeline) file can be used to configure DocumentComparator properties and also extend the comparison pipeline at specific extension points with your own filters.  See the  DCP User Guide.

The DataComparator class, introduced in release 17.0, is also based on the PipelinedComparatorS9 class but has been extended with a pipeline readily configurable for data-centric XML comparisons. it is the preferred API for new users whose main interest is in data-centric comparisons. The Java API or a 'DTCP' (Data Comparator Pipeline) file can be used to configure DataComparator properties and also extend the comparison pipeline at specific extension points with your own filters.  See the  DTCP User Guide.

The command line processor, GUI, and REST API use either DXP, DCP, or DTCP files for the PipelinedComparatorS9, DocumentComparator, or DataComparator classes respectively. You can select either one of your own custom configurations or one included with XML Compare.

Please consult and review the Samples And Guides and the com.deltaxml.cores9api package summary .

Samples

Our code samples are available from Bitbucket here for Java. Please see the Samples And Guides page for further information.

The samples directory in the release contains:

• a number of XSLT filters (samples/xsl-filters), described here: Guide to Sample XSL Filters.

• The DXP configuration files (samples/dxp) included, by default, in the GUI and command-line processors and also a DTD file used for DXP validity checking. These should be useful starting points for developing custom pipelines.

• For DCP validation, the samples/dcp directory contains XML Schemas for DCP - for XSD v1.0 and v1.1. This directory also includes copies of the DCP configuration files available in the GUI and command-line processor.

• For DTCP validation, the samples/dtcp directory contains XML Schemas for DTCP - for XSD v1.0 and v1.1. This directory also includes copies of the DTCP configuration files available in the GUI and command-line processor.

JAR and Script Files (Java Release)

The release contains a number of files. This section lists them and also explains why/when they are required, which may be useful when considering deployment or redistribution.

deltaxml-x.y.z.jar

(Replace x.y.z with the major.minor.patch version number of your release e.g. deltaxml-17.0.0.jar)

This is the command-line driver, normally invoked using java -jar deltaxml-x.y.z.jar, replacing x.y.z with the major.minor.patch version number of your release e.g. deltaxml-17.0.0.jar. It uses a manifest classpath containing: deltaxml.jar, saxon9pe.jar, resolver.jar and xercesImpl.jar. These files should be present in the same directory for correct operation.

This JAR file contains the main XML Compare API classes and associated resources (such as Java filters). It does not have any manifest dependencies, but there may be dependencies when certain sub-packages are used.

If using the com.deltaxml.cores9api package then saxon9pe.jar will be needed on the classpath. A SAX Parser will also be required, either using a JAXP factory configuration or direct instantiation from the xercesImpl.jar file.

When using the com.deltaxml.core package XSLT transformers and SAX parsers are required. The included saxon9pe.jar and xercesImpl.jar are recommended, but alternate implementations could also be used.

command-x.y.z.jar

This is the command-line driver, normally invoked using java -jar command-x.y.z.jar, replacing x.y.z with the major.minor.patch version number of your release e.g. command-17.0.0.jar. It uses a manifest classpath containing: deltaxml.jar, saxon9pe.jar, resolver.jar and xercesImpl.jar. These files should be present in the same directory for correct operation.

saxon9pe.jar

This JAR file is required when using the com.deltaxml.cores9api package and the client applications. Saxon PE 9.9 (currently 9.9.1.8) is distributed with XML Compare.
Up to and including XML Compare version 15, Saxon 10.x versions are supported as well, and we run tests against version 10.9, however we have observed degraded performance with version 10 in some cases (your mileage may vary) which is why we have currently chosen against distributing it for the time being. 

Since XML Compare version 16.0, XML Compare supports Saxon versions 9.9, 10.9, 11.5 and 12.4, and we run tests against all these specific versions.

Saxon versions before 9.9 will not work with XML Compare due to API incompatibilities.

The saxon9pe.jar is also recommended for use with the com.deltaxml.core package by including it on your classpath, but alternative implementations can be used on the classpath or with JAXP TransformerFactory methods.

flexlm.jar, EccpressoAll.jar

These JAR files are required for the Flexera based licensing capabilities introduced in the 8.0 and later releases. They should always be included on the classpath.

Feedback

We are always keen to improve our products - please contact us if you have any comments or suggestions while working with XML Compare. We hope you enjoy it!

The DeltaXML Team.

Licensing and Legal Notices

The DeltaXML software is licensed under the terms described in the file Licence.html. The software also includes components developed by others, the redistribution and copyright terms, including necessary notices are described here.