XML Redirecting URLs Using Resolvers

This article describes how you can set up your XML parser so that validation can occur while offline.

The problem of remote DTDs

A problem we first had was when we were disconnected from the internet was that our XML parser (Saxon) would try and connect to the internet to validate the DTD file.

The DocBook DTD has the DOCTYPE tag of:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
            "http://www.docbook.org/xml/4.2/docbookx.dtd">

As you can see, there is a URL, http://www.docbook.org/xml/4.2/docbookx.dtd, which is requested every time we validate the document. If we weren’t connected, the parser would then complain that it couldn’t reach the internet.

Error reported by XML parser: Cannot read from http://www.docbook.org/xml/4.2/
docbookx.dtd (www.docbook.org)
Transformation failed: Run-time errors were reported

The public identifier in this case is -//OASIS//DTD DocBook XML V4.2//EN

Download the DTDs locally

To rectify this, download and copy the DTDs locally onto your machine.

A good directory to choose might be somewhere in /usr/share/ if you are on UNIX.

On my Windows box, I had Cygwin installed, so I added the DocBook XML 4.2 distribution package to it.

However, don’t go ahead and change the URL inside your XML file just yet - what happens if you send this file to another person, or try to open the same document on another machine? Distributing this kind of XML document would lead to problems.

Download resolver.jar

Visit the Apache xml-commons site and download the xml-commons-resolver-1.1 release.

Unpack this, and add the file resolver.jar to your CLASSPATH.

Look at the documentation inside xml-commons-resolver-1.1/docs/ for further information.

Creating your catalog file

Create your catalog file similar to what we have below, but replace the URI with where you downloaded your docbookx.dtd locally. I happened to create my file as D:\cygwin\usr\share\catalog\docbook.catalog

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <public publicId="-//OASIS//DTD DocBook XML V4.2//EN"
          uri="file:///D:/cygwin/usr/share/docbook-xml42/docbookx.dtd"/>
</catalog>

This will tell the resolver that when it sees the public identifier -//OASIS//DTD DocBook XML V4.2//EN inside the XML document, it should lookup this catalog, and go to the URI specified instead. In this case it will open the file D:\cygwin\usr\share\docbook-xml42\docbookx.dtd.

You can also specify the uri as relative.

Check your catalog file

Use the resolver program that comes with the Apache distribution.

Make sure that the catalog will work by using the following:

java org.apache.xml.resolver.apps.resolver -d 2 \
  -c 'D:\cygwin\usr\share\catalog\docbook.catalog' \
  -p "-//OASIS//DTD DocBook XML V4.2//EN" public
Cannot find CatalogManager.properties
Loading catalog: ./xcatalog
Loading catalog: D:\cygwin\usr\share\catalog\docbook.catalog
Resolve PUBLIC (publicid, systemid):
  public id: -//OASIS//DTD DocBook XML V4.2//EN
Result: file:/D:/cygwin/usr/share/docbook-xml42/docbookx.dtd

Note that it says that is couldn’t find CatalogManager.properties, so we will need to rectify that.

Creating your catalog manager properties file

In order for the resolver to work, you must create a CatalogManager.properties file.

This file must be placed somewhere in your CLASSPATH.

Add the property catalogs that specifies the location of the catalog file.

If you have more than one you can separate the with semicolons.

The contents of my one line CatalogManager.properties file is below

catalogs=D:\\cygwin\\usr\\share\\catalog\\docbook.catalog

Testing the whole setup

When I tested this setup with saxon, I received an error:

$ java org.apache.xml.resolver.apps.xparse -d 2 magicmonster.xml
Loading catalog: D:\cygwin\usr\share\catalog\docbook.catalog
javax.xml.parsers.ParserConfigurationException: AElfred parser is non-validating

A validating parser is needed to test this. I removed saxon from my CLASSPATH, then installed xerces 2.6.2. I needed to include xercesImpl.jar and xmlParserAPIs.jar into my CLASSPATH. I am using Java 1.2

Another alternative to xerces is to use Sun’s java 1.4. This is distributed with the Crimson parser.

java org.apache.xml.resolver.apps.xparse -d 2 magicmonster.xml
Loading catalog: D:\cygwin\usr\share\catalog\docbook.catalog
Attempting validating, namespace-aware parse
Resolved public: -//OASIS//DTD DocBook XML V4.2//EN
        file:/D:/cygwin/usr/share/docbook-xml42/docbookx.dtd
Parse succeeded (1.382) with no errors and no warnings.

The above worked out well. It has successfully resolved the public identifier to the local file, and has successfully validated my xml document.

Incorporating all this into Saxon

I still needed xerces parser included in my CLASSPATH. Make sure saxon.jar is included after both of the Xerces jar files, or specifiy which Parser to use by using the following option:

-Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl

If you are using the Crimson parser that comes with Sun’s Java 1.4, use the following option:

-Djavax.xml.parsers.SAXParserFactory=org.apache.crimson.jaxp.SAXParserFactoryImpl

After this, you can add the following options to the Saxon stylesheet command line:

-x org.apache.xml.resolver.tools.ResolvingXMLReader
-y org.apache.xml.resolver.tools.ResolvingXMLReader
-r org.apache.xml.resolver.tools.CatalogResolver

JAXP URI Resolver

JAXP also provides an interface you can use when use when programmatically transforming documents using XSL. See javax.xml.transform.URIResolver.resolve

/**
 * Called by the processor when it encounters
 * an xsl:include, xsl:import, or document() function.
 *
 * @param href An href attribute, which may be relative or absolute.
 * @param base The base URI against which the first argument will be made
 * absolute if the absolute URI is required.
 *
 * @return A Source object, or null if the href cannot be resolved,
 * and the processor should try to resolve the URI itself.
 *
 * @throws TransformerException if an error occurs when trying to
 * resolve the URI.
 */
public Source resolve(String href, String base)
    throws TransformerException;