DeltaXML Core README (Java platform)

1. Introduction

Welcome to the DeltaXML Core product! DeltaXML 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 Core product provides a toolkit for general purpose, extensible comparison and recombination for XML data.

This release contains:

The com.deltaxml.cores9api package: our latest API providing a high performance and feature rich comparison pipeline using Java or XSLT filters and providing support for Saxon's s9api interfaces.
The com.deltaxml.core package: an API for easy comparison pipeline construction using Java or XSLT filters
The com.deltaxml.api package: a JAXP compatible, low-level API to DeltaXML
The command.jar command-line interface/driver (no programming required)
The deltaxml-gui.sh simple graphical interface sample (no programming required)

For support information (such as how to compare large files) and further technical details, please refer to the following URLs on the DeltaXML web site:

DeltaXML Core Features Interactive Walkthrough: http://www.deltaxml.com/free/examples/core-features/
Documentation index: http://www.deltaxml.com/library/
DeltaXML Tour: http://www.deltaxml.com/library/tour-of-deltaxml.html

2. Quick Start with the GUI

The easiest way to access DeltaXML 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 in your terminal.

3. What can DeltaXML Core do?

DeltaXML Core 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 minimal delta showing just the changes. 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 DeltaXML processing for specific needs. You'll find more details in the DeltaXML Tour.

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

To determine the release/version information for the API, invoke:

java -jar deltaxml.jar

The samples directory provides code samples and data together with a ReadMe file and Ant build scripts which can automate compilation/running.

4.1. PipelinedComparator based on Saxon's s9api

This new API, first included in the 6.0 release, provides a more efficient and powerful pipeline than the APIs used in earlier releases and is our preferred API for new users. Comparison pipelines can include either Java or XSLT filters. You can construct the pipelines in Java or in XML using a 'dxp' (DeltaXML pipeline) file. A dxp file can be read directly by the command line processor and the GUI. Please consult and review the sample code and the com.deltaxml.cores9api package summary.

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

4.3. JAXP API

This JAXP compatible API provides both comparison and optionally recombination operations and is generally backwards-compatible with 2.x releases of the DeltaXML Core 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.

5. Command-line interface

The release also 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.jar and is used like this:

java -jar command.jar status
java -jar command.jar compare diffreport file1.xml file2.xml diffs.html
java -jar command.jar ...

Further details are in the file docs/command-processor.html

6. Samples

The samples directory contains a number of sample programs, their data and Ant build scripts. These samples assume you are using J2SE 1.5 or later and Apache Ant. The samples directory also contains a number of XSLT filters (samples/xsl-filters), described in further detail here: http://www.deltaxml.com/library/filters-and-pipelines.html

The samples/dxp directory contains the DXP configuration files 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.

Please see the samples ReadMe for further information.

7. JAR Files

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

deltaxml.jar

This jar file contains the main DeltaXML Core 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.jar

This is the command-line driver, normally invoked using java -jar command.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 Mac OS X. 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.jar

This jar file is required when using the GUI (invoked via ./deltaxml-gui.sh).

puremvc.jar

This jar file is required when using the GUI (invoked via ./deltaxml-gui.sh).

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) 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.jar APIs or when using the command.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 Catalog Resolver Customizations 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. It is recommend 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.

8. Source code

The source.zip file contains the source code to:

The com.deltaxml.pipe package: code to support pipelining and push-mode Java filtering
The com.deltaxml.pipe.filters, com.deltaxml.pipe.filters.dx2 and com.deltaxml.pipe.filters.dx2.wbw packages: source code to Java filters
the source code for the simple command-line interpreter

In addition various Junit tests and Ant build scripts are included.

9. 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 DeltaXML. We hope you enjoy it!

The DeltaXML Team.

10. Licence Information

10.1. DeltaXML Licensing

The DeltaXML software is licenced under the terms described in the file Licence.html. The licence terms in this file differ depending upon whether this is an evaluation release of the software or a purchased release.

10.2. Saxon Licensing

Included in the distribution is saxon9pe.jar, which is a binary component of the professional edition of Saxon ('The SAXON XSLT and XQuery Processor from Saxonica Limited.'). This version of Saxon may only be used when invoked from a DeltaXML product.

The home page for Saxonica is http://www.saxonica.com. For further details of Saxon's licensing please see http://www.saxonica.com/license/license.xml and the docs/notices/saxon/ subdirectory included in the distribution. In particular, the docs/notices/saxon/LEGAL.txt file describes how the license/notices of third party code included in Saxon is handled.

10.3. Apache Licensing

This product includes software developed by the Apache Software Foundation (http://www.apache.org), these include:

the xercesImpl.jar component from the binary 2.9.0 release of the Xerces-J SAX parser.
the DeltaXML variant of the resolver.jar component from the 1.2 release of the Apache Commons Resolver OASIS catalog reader.

The DeltaXML adaptation of Apache's resolver contains standard fixes for some of the known bugs and an enhancement that enables entities to be loaded via Java's resource loading mechanism. For further information please see our Customized Catalog Resolver page for details of the changes and the associated source code and/or contact us.

These components are: Copyright (c) 1999-2006 The Apache Software Foundation. All rights reserved. and are licensed under the terms of the Apache License, Version 2.0. These components must be used under the terms of the license at: http://www.apache.org/licenses/LICENSE-2.0

In accordance with section 4(d) of the Apache License, the notices for these libraries are enclosed in appropriately labelled subdirectories of the ${product.name.spaces} distribution, as follows:

Xerces-J SAX parser notices are in the docs/notices/xerces/ directory.
Resolver catalog reader notices are in the docs/notices/resolver/ directory.

10.4. TrueLicense Licensing

The deltaxml.jar file contains one compiled class from the 'TrueLicense Library', which is a component of the TrueLicense Library Collection. This code is: Copyright 2005 Schlichtherle IT Services, and licensed under the terms of the Apache License, Version 2.0.

In accordance with section 4(d) of the Apache License, the notices for these libraries are enclosed in the docs/notices/truelicense/ directory of the distribution.

10.5. PureMVC Licensing

Included in the release is the puremvc-java-1.0.jar file from the Java port of the PureMVC framework. It is Copyright 2006-2008 Futurescale Inc. and its reuse is governed by the Creative Commons Attribution 3.0 License The PureMVC product and documentation is available from http://trac.puremvc.org/PureMVC_Java. For details of the PureMVC Java please see the docs/notices/puremvc/license.txt included in the release.

10.6. SWT Licensing

The Standard Widget Toolkit (SWT) has been used to construct the GUI components used in the release. One or more jar files may be included according to the specific platform release. These are licensed using the Eclipse Public License version 1.0 and a copy of the EPL is available at: http://www.eclipse.org/legal/epl-v10.html. The various SWT files also include third party content which may have different copyright and license terms. We have included the various about.html files with further details and the about_files directories with these notices as summarized below:

filename	license details	associated notices
`swt-lib/cocoa-macosx-x86.jar`	`docs/notices/swt-3.7/cocoa-macosx-x86/about.html`	`docs/notices/swt-3.7/cocoa-macosx-x86/about_files/`
`swt-lib/cocoa-macosx-x86_64.jar`	`docs/notices/swt-3.7/cocoa-macosx-x86_64/about.html`	`docs/notices/swt-3.7/cocoa-macosx-x86_64/about_files/`
`swt-lib/gtk-linux-x86.jar`	`docs/notices/swt-3.7/gtk-linux-x86/about.html`	`docs/notices/swt-3.7/gtk-linux-x86/about_files/`
`swt-lib/gtk-linux-x86_64.jar`	`docs/notices/swt-3.7/gtk-linux-x86_64/about.html`	`docs/notices/swt-3.7/gtk-linux-x86_64/about_files/`

10.7. jCanvas Licensing

The 'Side by Side' result report output makes use of version 4.0 of the jCanvas JavaScript library. The file is included in various Jar files within the release and also at: samples/xsl-filters/side-by-side/jcanvas.js. This file is Copyright 2011, Caleb Evans and Licensed under the terms of the MIT License as per the comments at the top of the file.

10.8. jQuery licensing

The 'Side by Side' result report output also makes use of the jQuery JavaScript library v1.4.2. The file is included in various Jar files within the release and also at: samples/xsl-filters/side-by-side/jquery-1.4-min.js. This file is Copyright 2010, John Resig and is dual licensed using the MIT and GPL v2 licenses. The file also contains a further copyright statement, please see the comments at the top of the file.

DeltaXML Core 6.2

Table of Contents