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 pipelines. To learn more about its use, see the REST documentation.
The command-x.y.z.jar^* command-line interface/driver (no programming required).
deltaxml-gui.sh for Unix based systems, or deltaxml-gui.bat for Windows: a simple graphical interface sample (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. '10.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 document. 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:

TEXT

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

Using the GUI (Java & macOS)

The easiest way to access XML Compare is to use the GUI, a demonstration application providing a graphical interface to let you compare your own files. The GUI handles any XML and also has special processing for different file types, e.g. XHTML, Schema. Select two files and the GUI will display the changes using one of several different report styles.

The GUI is a useful tool as it stands, but more importantly it is easy to configure it to process your own XML formats, using XSLT or Java and a simple configuration file to define the parameters and XML processing pipeline.

You can start the GUI by running deltaxml-gui.sh (Unix/macOS) or deltaxml-gui.bat (Windows) in your terminal.

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:

CODE

java -jar deltaxml.jar

(S9API) PipelinedComparatorS9 and DocumentComparator

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; it is the preferred API for new users whose main interest is in data-centric comparisons. 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 document-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 command line processor, GUI, and REST API use either DXP or DCP files for the PipelinedComparatorS9 or DocumentComparator 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 .

Legacy APIs

PipelinedComparator based on JAXP

This API, first included in the 3.0 release, also supports building pipelines consisting of Java or XSLT filters. Programming directly using Java or a more declarative/data-driven approach using DXP files is also supported. The DXP file format is the same for both the s9api and JAXP based pipelines. Further details including prerequisites are contained in the com.deltaxml.core package summary.

JAXP API

This JAXP compatible API provides both comparison and optionally recombination operations and is generally backwards-compatible with 2.x releases of the XML Compare API (or 'DeltaXML API').

For full API details please read the com.deltaxml.api package summary which has details of prerequisites, properties and features as well as standard Javadoc API documentation.

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.

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

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

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

deltaxml-gui.sh

This is the GUI client for running pipelines on Unix based operating systems, including Linux and macOS. It makes use of: deltaxml-gui.jar, deltaxml.jar, saxon9pe.jar, resolver.jar, puremvc.jar and the relevant platform specific SWT .jar from swt-libs/ (the relevant JAR file is detected by the shell script). These files should be present in the same directory for correct operation.

deltaxml-gui.bat

This is the GUI client for running pipelines on Windows. It makes use of: deltaxml-gui.jar, deltaxml.jar, saxon9pe.jar, resolver.jar, puremvc.jar and the relevant platform specific SWT .jar from swt-libs (the relevant JAR file is detected by the batch script). These files should be present in the same directory for correct operation.

deltaxml-gui.jar

This JAR file is required when using the GUI (invoked via deltaxml-gui.sh or deltaxml-gui.bat).

fastutil-8.4.2.jar

This JAR file is always required when performing comparisons.

puremvc.jar

This JAR file is required when using the GUI (invoked via deltaxml-gui.sh or deltaxml-gui.bat).

swt-libs/*.jar

The swt-lib/ folder contains platform specific SWT JAR files, which are required when using the GUI (invoked via deltaxml-gui.sh or deltaxml-gui.bat) and the correct one is autodetected.

resolver.jar

This modified version of the Apache catalog resolver is need when using catalogs (either through the deltaxml-x.y.z.jar APIs or when using the command-x.y.z.jar or GUI clients. Classes from this file are invoked using reflection and it is therefore an optional JAR and is only required if using catalog files. Please see Customized Catalog Resolver for further details of the modifications we have made.

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.
10.x versions are supported as well, and we run tests against version 10.5, 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.
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.

xercesImpl.jar

This file is required by the client applications and is recommended for use with the com.deltaxml.core and com.deltaxml.cores9api packages by including it on the classpath. Alternative SAX parsers can be used by using the classpath or the JAXP SAXParserFactory methods.

When using DocumentComparator or PipelinedComparatorS9 (either configured directly or via DCP / DXP), the SAX / JAXP parser implementation on the classpath must be Apache Xerces version 2.11.0 (included in the XML Compare download) or later.

xml-apis.jar

This file is required by any applications which also make use of xercesImpl.jar version 2.11.0 or later. In previous releases, where Xerces-J version 2.9 was provided, this file was not required, and it was preferable to make use of the JAXP interfaces provided by the Java JDK/JRE. However, changes to the way in which Xerces is shipped means this JAR file is now required at runtime (but not compile time, where the JDK is sufficient).

icu4j-69_1.jar

This JAR file is required when using the com.deltaxml.pipe.filters.dx2.wbw.WordInfilter filter.

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.

istack-commons-runtime-3.0.12.jar, javax.activation-1.2.0.jar, jaxb-api-2.3.1.jar, jaxb-runtime-2.3.6.jar

These JAR files are only required when your license is using Usage Logging and you’re also using Java 11+

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.