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, ordeltaxml-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:
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:
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. ASAX Parser
will also be required, either using a JAXP factory configuration or direct instantiation from thexercesImpl.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.
Version 9.8 is also supported for backwards compatibility.
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.
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.
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.