Getting Started

 Table of Contents

1. 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* - our new 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.

The .NET release contains:

  • The DeltaXML.CoreS9Api namespace: our latest API providing a high performance and feature rich comparison pipeline using pre-compiled or XSLT filters and providing support for Saxon's s9api interfaces.
  • The deltaxml.exe command-line interface/driver (no programming required).

The .NET release is considered deprecated as of version 10.0.0 and will be removed in a future release. Please contact DeltaXML if you need help with migrating to our Java or REST APIs.

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

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

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

The .NET version requires the Microsoft .NET Framework version 3.5 or later.

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

4. 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 or deltaxml.exe 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 or deltaxml.10.0.0:

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

Or for .NET:

deltaxml status
deltaxml compare diffreport file1.xml file2.xml diffs.html
deltaxml ...

Further details are on page  Using the Command-Line Tool

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

Alternatively if using the macOS release simply open DeltaXML XML Compare.app

The .NET release does not include the GUI

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

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

6.2. Legacy APIs

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

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

7. Microsoft .NET APIs

The .NET release is considered deprecated as of version 10.0.0 and will be removed in a future release. Please contact DeltaXML if you need help with migrating to our Java or REST APIs.

The primary API for the .NET platform is provided in the DeltaXML.CoreS9Api namespace. The classes here are an approximate match for the classes contained in the com.deltaxml.cores9api Java package.

Samples with code and data are provided on Bitbucket here. These include batch files and/or Visual Studio solutions which can automate compilation/running.

Also see the Samples And Guides page.

The classes in DeltaXML.CoreS9Api are specific to the .NET platform and are designed to be compatible with the various types provided in the .NET runtime. However, they make use of underlying code which has been converted using IKVM.NET to convert Java classes into .NET CLR assemblies. This converted code uses various com.deltaxml.* packages/namespaces and is provided in deltaxml.dll. The API documentation we have provided documents the DeltaXML.CoreS9Api namespace and some aspects of the com.deltaxml.* namespaces which may be needed on .NET. These aspects include documentation of the exceptions which may be thrown and details of the pre-compiled filters that can be used in pipelines.

8. Samples

Our code samples are available from Bitbucket here for Java or here for .NET. 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.

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

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

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

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

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

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

9.5. deltaxml-gui.jar

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

9.6. puremvc.jar

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

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

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

9.9. saxon9pe.jar

This JAR file is required when using the com.deltaxml.cores9api package and the client applications. Saxon 9.8 is distributed with XML Compare as, at the time of writing, this is the more mature version. Saxon version 9.9 starting with 9.9.0.2 or later is also supported. Saxon versions before 9.8 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.

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

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

9.12. icu4j.jar

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

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

9.14. gson-2.8.5.jar

This JAR is required when logging usage to our database.

10. DLL Files (.NET Release)

The .NET release contains a number of '.dll' files. This section lists them and also explains why they are required; we currently recommend you include then all when deploying or redistributing your applications. When deploying you may either keep/copy all of the DLL files in a local directory or insert them into the Global Assembly Cache.

10.1. deltaxml.dll

This file contains the main XML Compare code and associated resources (such as Java filters) which have been converted from Java classes using IVKM.NET. It is possible to write .NET CLR code using this dll if you are familiar with the Java platform runtime libraries, however we do not document or support such use and recommend users use our .NET specific namespace.

10.2. DeltaXML.CoreS9Api.dll

This DLL contains our .NET namespace and is our recommended API for the .NET platform.

10.3. IKVM.*.dll

These files either support the IKVM converted code or the (OpenJDK) Java runtime libraries on which the Java code depends. This collection of DLLs is a subset of those included with IKVM.NET, but should be sufficient for runtime use of our code.

10.4. deltaxml-xercesImpl.dll

This file provides parsing and catalog resolving support in our pipelined architecture. The parser used is Apache Xerces and the catalog resolver is from Apache XML Commons. Please see Catalog Resolver Customizations for further details of the modifications we have made to the resolver.deltaxml-saxon9pe.dll This file provides support for XSLT processing within our pipelined architecture. It has been IVKM converted from the corresponding saxon9pe.jar file.

10.5. deltaxml-saxon9he-dotnet.dll

This file is provides conversion code between Java and .NET libraries, it was compiled from Saxon HE source code, and then IVKM converted into a DLL.

10.6. deltaxml-icu4j.dll

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

10.7. deltaxml-flexlm.dll, deltaxml-eccpressoall.dll

These files are required for the Flexera based licensing capabilities for .NET introduced in the 8.0 and later releases. They are IKVM derived versions of the equivalent files used in the Java releases. They should always be included on the classpath.

10.8. deltaxml-gson.dll

This file is required when logging usage to our database.

11. Feedback

We are always keen to improve our products - please make use of our Support Forums if you have any comments or suggestions while working with XML Compare. We hope you enjoy it!

The DeltaXML Team.

12. 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 in legal-notices.html - for Java and for .NET

#content .code