XML Catalog Support - xspec/xspec GitHub Wiki

XSpec can use OASIS XML Catalog to map references to resources to known resources. The reasons for using XML Catalog in XSpec are generally the same as the reasons for using an XML Catalog in other environments. In XSpec specifically, if a system under test or a test scenario relies on files that are retrieved over a network, an XML Catalog that points to local copies of the resources may: reduce the execution time of tests, allow test to run when network resources are not available, and isolate tests from being affected by changes to the external resources.

Prerequisites

Using XML Catalogs with XSpec requires Apache XML Resolver jar:

https://repo1.maven.org/maven2/xml-resolver/xml-resolver/1.2/xml-resolver-1.2.jar

Specifying XML Catalog files

When you specify XML Catalog files, their file paths may be absolute or relative from the current directory (xspec.bat and xspec.sh) or from basedir (Ant).

Multiple XML Catalog files are separated by semicolons (;) regardless of operating system. Note that your shell may require putting a parameter in quotes (") when it contains ;.

You can't specify a file system path and a URI at the same time.

Examples

The examples below use files that are available in the test/catalog folder in the GitHub repository.

Using XML Catalog with xspec.bat and xspec.sh

Specifying XML Resolver jar for xspec.bat and xspec.sh

SAXON_CP

If you have installed XSpec by setting the SAXON_CP environment variable, SAXON_CP should be updated to include the XML Resolver jar. For example:

Windows:

set SAXON_CP=C:\path\to\saxon-he-12.4.jar;C:\path\to\xml-resolver-1.2.jar

Linux/macOS:

export SAXON_CP=/path/to/saxon-he-12.4.jar:/path/to/xml-resolver-1.2.jar

Note that the SAXON_CP delimiter is platform-dependent: ; (Windows) and : (Linux/macOS).

SAXON_HOME

If you have installed XSpec by setting the SAXON_HOME environment variable, the XML Resolver jar should be named xml-resolver-1.2.jar and placed in the same folder as the Saxon jar.

Specifying XML Catalog files for xspec.bat and xspec.sh

There are two ways to provide XSpec with the location of the XML Catalog files, using a command line parameter -catalog or an environment variable XML_CATALOG.

-catalog

The command line parameter -catalog can be used to specify the location of XML Catalog files. For example:

Windows:

bin\xspec.bat ^
    -catalog "test\catalog\01\catalog-public.xml;test\catalog\01\catalog-rewriteURI.xml" ^
    test\catalog\catalog-01_stylesheet.xspec

Mac/Linux:

bin/xspec.sh \
    -catalog "test/catalog/01/catalog-public.xml;test/catalog/01/catalog-rewriteURI.xml" \
    test/catalog/catalog-01_stylesheet.xspec

XML_CATALOG

Alternatively, the environment variable XML_CATALOG can be used to specify the location of XML Catalog files. For example:

Windows:

set "XML_CATALOG=test\catalog\01\catalog-public.xml;test\catalog\01\catalog-rewriteURI.xml"
bin\xspec.bat test\catalog\catalog-01_stylesheet.xspec

Linux/macOS:

export XML_CATALOG="test/catalog/01/catalog-public.xml;test/catalog/01/catalog-rewriteURI.xml"
bin/xspec.sh test/catalog/catalog-01_stylesheet.xspec

Using XML Catalog with Ant

Specifying XML Resolver for Ant

The path to the XML Resolver jar, along with the path to the Saxon jar, can be provided using the -lib parameter.

If you want to omit the -lib parameters, you can place the XML Resolver jar and the Saxon jar in one of the Ant library folders such as %USERPROFILE%\.ant\lib on Windows or ~/.ant/lib on Linux/macOS.

Specifying XML Catalog files for Ant

The location of the XML catalog must be provided using the Ant catalog property.

Ant Example

Windows:

ant ^
    -lib C:\path\to\saxon-he-12.4.jar ^
    -lib C:\path\to\xml-resolver-1.2.jar ^
    -Dcatalog="test\catalog\01\catalog-public.xml;test\catalog\01\catalog-rewriteURI.xml" ^
    -Dxspec.xml=test\catalog\catalog-01_stylesheet.xspec

Linux/macOS:

ant \
    -lib C:/path/to/saxon-he-12.4.jar \
    -lib C:/path/to/xml-resolver-1.2.jar \
    -Dcatalog="test/catalog/01/catalog-public.xml;test/catalog/01/catalog-rewriteURI.xml" \
    -Dxspec.xml=test/catalog/catalog-01_stylesheet.xspec