Using the Command-Line Tool

Introduction

Although XML Compare provides an API which can be embedded in applications or server processes for internal or OEM applications, some evaluators may wish to experiment with a simple command line process.

The file command-x.y.z.jar is included in this distribution allows the XML Compare differencing and recombination engines to be invoked, together with a range of input and output filters on the command line.

Replace x.y.z with the major.minor.patch version number of your release e.g. command-10.0.0.jar

General Usage

The command-x.y.z.jar can be run using a command-line interface that is invoked from a terminal window or Windows command line. It is used like this for Java:

TEXT

java -jar command-x.y.z.jar command arguments
java -jar ../command-x.y.z.jar command arguments
java -jar /usr/local/DeltaXML-XML-Compare-10_0_0/command-10.0.0.jar command arguments

It should be noted that the command-x.y.z.jar file should always be in the same location as deltaxml-x.y.z.jar; we do not recommend moving or copying these jar files once installed. You should use a relative or absolute file path to their install locations as in the above examples.

Supported commands

Each invocation of the XML Compare command-line has a subcommand name, followed by options and arguments.

The subcommands are:

status	Provides version information and an informative message about available options.
describe	Provides a description of the configuration passed as an argument, including available parameters
compare	Used to perform a comparison of two input files to produce an output file. Arguments includes a configuration id, three file arguments and optional configuration parameter arguments.
recombine-forward, recombine-reverse	These commands can be used in conjunction with 'compare delta' to do 'round-trip' processing, i.e. one of the original input files can be generated from the delta file and the other input file. Note: to allow recombination, the delta file produced must be a 'raw' delta file and we recommend using the compare raw sub-command, provided in recent releases, in conjunction with the recombination operations.

Command Arguments

describe

Takes a single configuration id argument. For a list of available configuration ids, run

TEXT

java -jar command-x.y.z.jar status

compare

Takes a configuration id and 3 file arguments. Optional parameter overrides can also be included.

Examples:

TEXT

java -jar command-x.y.z.jar compare delta doc1.xml doc2.xml delta-1-2.xml
java -jar command-x.y.z.jar compare diffreport doc1.xml doc2.xml report.html "Word By Word=true"

Parameter overrides are always of the form param=value, with surrounding quotes if spaces are present. For a list of available parameters, use

TEXT

java -jar command-x.y.z.jar describe configuration-id

recombine-forward, recombine-reverse

The recombine commands take 3 arguments, the first argument is one of the original input files, the second is a delta file, and the third is the regenerated version of the other input file, for example:

TEXT

java -jar command-x.y.z.jar compare raw doc1.xml doc2.xml delta-1-2.xml
java -jar command-x.y.z.jar recombine-forward doc1.xml delta-1-2.xml regen-2.xml
java -jar command-x.y.z.jar recombine-reverse doc2.xml delta-1-2.xml regen-1.xml

OASIS Catalog Support

As of version 2.0 of the command line comparator it is possible to provide a series of OASIS catalogs, which can be used during comparison. A simple way of doing this with the command line processor is to set the value of the xml.catalog.files property on the command line to a list of semi-colon separated catalog files, for example:

TEXT

java -Dxml.catalog.files=catalogFile1;catalogFile2;...;catalogFileN -jar command-x.y.z.jar ...

In this case the catalogFiles must be specified using either absolute paths or paths relative to the current directory.

It is possible to use a Configuration Properties file. One benefit of this technique is that catalogs can be referenced using an absolute location, a relative location from the current directory, or a relative location from the install, home, or working directories (using ${install.dir}, ${user.home}, and ${user.dir} directories respectively).

A catalog can be used to locate/redirect XML external entities including notations and the public (or system) doctype of an XML document. It can also be used during filter processing and may be relevant when locating files referenced through document(), <xsl:import> or <xsl:include>.

Catalog support replaces the 1.3+ ability to directly set an entity or URI resolver. Additionally catalog support is available when using our Java APIs, please see our How to use a catalog resolver sample.

Extensibility

It is possible to extend the functionality of the command line tool with your own configurations by including customised configuration files in specific directories. The configuration files should be DXP or DCP files (see Pipeline Configuration using DXP and Document Comparator Configuration using DCP for more information) and should be placed in one of the following directories:

command-x.y.z.jar (or deltaxml.exe) installation directory
current working directory i.e. the directory where the command is being invoked
user home directory (this has the highest priority)

Any DXP or DCP files found in these directories will be available for use as a command line tool configuration. To see which configurations are currently available, use

TEXT

java -jar command-x.y.z.jar status