Using a Catalog Resolver

1. Introduction

This sample shows a how to configure the default catalog resolver for use with the command-line tool and the PipelinedComparatorS9 API.

2. OASIS Catalog Support

The DeltaXML core product is shipped with a slightly customized variant of the Apache commons OASIS catalog resolver - version 1.2, which fixes some of the published bugs and provides an enhancement for locating resolvable entities using Java's resource loading mechanism. Details of this customization are on our catalog resolver page.

3. Locating the catalogs

The provided catalog resolver reads the Java xml.catalog.files system property to determine where the catalogs are located. This can be achieved by

  1. setting the system property in the source code,
  2. supplying a JVM (Java Virtual Machine) argument, or
  3. reading a DeltaXML configuration properties file.

The first of the techniques used to set the Java xml.catalog.files property is used, unless technique (1) is used after the call to setup the default DeltaXML catalog support; hence, technique (1) should be applied before any invocation of either a Catalog or DeltaXML method.

The sample code uses a DeltaXML configuration properties file (deltaxmlConfig.xml) to set the xml.catalog.files system property.

Note that if the xml.catalog.files system property is not set then the "catalogs" entry in a Apache commons CatalogManager.properties file is used instead.

4. Running the Sample

The sample code essentially loads two input files (that require catalog support), compares them, and produces an output that is saved to a file (out.xml). The DTD referenced in the DOCTYPE of the samples files (a.xml and b.xml) does not exist, therefore a catalog (catalog.xml) is required to provide the DTDs. Furthermore, the DTD provides a default attribute (/root/@i='42') that does not appear in the input data, but does appear in the full-context delta result.

4.1. Running the Sample via the Command-line

The command-line version of this sample can be run by issuing the following command:

java -jar ../../command.jar compare delta a.xml b.xml out.xml

4.2. Running the Sample via the API

The API version of the sample is designed to be built and run via the Ant build technology. The provided build.xml script has two main targets

  • run - the default target which compiles and runs the sample code.
  • clean - returns the sample to its original state.

It can be run by issuing either the ant or the ant run commands.

Alternatively, the sample can be manually compiled and run using the following Java commands, asuming that both the Java compiler and runtime platforms are avaialble on the command-line.

javac -cp ../../deltaxml.jar:../../saxon9pe.jar:../../resolver.jar FilesWithCatalog.java
java -cp .:../../deltaxml.jar:../../saxon9pe.jar:../../resolver.jar:../../xercesImpl.jar FilesWithCatalog

Note that you need to ensure that you use the correct directory and class path separators for your operating system.

5. Further information

The general DeltaXML's configuration properties documentation for how properties can be specified in general.

The Javadoc comments in FilesWithCatalog.java contain further implementation specific details.

Useful catalog resources:

Other resources:

  • If you want to use a file URI that is a local path to your catalog file, you must take care to specify the URI using the correct form, as specified in IETF RFC 8089 - the file URI scheme