XML Entity and URI Resolvers

It's very common for web resources to be related to other resources: documents rely on DTDs and schemas, schemas are derived from other schemas, stylesheets are often customizations of other stylesheets, documents refer to the schemas and stylesheets with which the expect to be processed, etc. These relationships are expressed using URIs, most often URLs.

Relying on URLs to directly identify resources to be retrieved often causes problems for end users:

One way to avoid these problems is to use an entity resolver (a standard part of SAX) or a URI Resolver (a standard part of JAXP). A resolver can examine the URIs of the resources being requested and determine how best to satisfy those requests.

The best way to make this function in an interoperable way is to define a standard format for mapping system identifiers and URIs. The OASIS Entity Resolution Technical Committee is defining an XML representation for just such a mapping. These “catalog files” can be used to map public and system identifiers and other URIs to local files (or just other URIs).

The problems associated with system identifiers (and URIs in general) arise in several ways:

Public identifiers offer an effective solution to this problem, at least for documents. They provide global, unique names for entities independent of their storage location. Unfortunately, public identifiers aren't used very often because many users find that they cannot rely on applications resolving them in an interoperable manner.

For XSLT, XML Schemas, and other applications that rely on URIs without providing a mechanism for associating public identifiers with them, the situation is a little more irksome, but it can still be addressed using a URI Resolver.

In some contexts, it's more useful to refer to a resource by name than by address. If I want the version 3.1 of the DocBook DTD, or the 1911 edition of Webster's dictionary, or The Declaration of Independence, that's what I want, irrespective of its location on the net (or even if it's available on the net). While it is possible to view a URL as an address, I don't think that's the natural interpretation.

There are currently two ways that I might reasonably assign an address-independent name to an object: public identifiers or Uniform Resource Names (URNs)^[2].

-//OASIS//DTD DocBook XML V4.1.2//EN

urn:oasis:names:specification:docbook:dtd:xml:4.1.2

Having extolled the virtues of location-independent names, it must be said that a name isn't very useful if you can't find the thing it refers to. In order to do that, you must have a name resolution mechanism that allows you to determine what resource is referred to by a given name.

One important feature of this mechanism is that it can allow resources to be distributed, so you don't have to go to http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd to get the XML version of DocBook V4.1.2, if you have a local copy.

There are a few possible resolution mechanisms:

Catalog files are straightforward text files that describe a mapping from names to addresses. Here's a simple one:

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

<public publicId="-//OASIS//DTD XML DocBook V4.1.2//EN"
        uri="docbook/xml/docbookx.dtd"/>

<system systemId="urn:x-oasis:docbook-xml-v4.1.2"
        uri="docbook/xml/docbookx.dtd"/>

<delegatePublic publicIdStartString="-//Example//"
          catalog="http://www.example.com/catalog"/>
</catalog>

This file maps both the public identifier and the URN I mentioned earlier to a local copy of DocBook on my system. If the doctype declaration uses the public identifier for DocBook, I'll get DocBook regardless of the (possibly bogus) system identifier! Likewise, my local copy of DocBook will be used if the system identifier contains the DocBook URN.

The delegate entry instructs the resolver to use the catalog “http://www.example.com/catalog” for any public identifier that begins with “-//Example//”. The advantage of delegate in this case is that I don't have to parse that catalog file unless I encounter a public identifier that I reasonably expect to find there.

The OASIS Entity Resolution Technical Committee is actively defining the next generation XML-based catalog file format. When this work is finished, it is expected to become the official XML Catalog format. In the meantime, the existing OASIS Technical Resolution TR9401 format is the standard.

The Resolver classes uses either Java system properties or a standard Java properties file to establish an initial environment. The property file, if it is used, must be called CatalogManager.properties and must be somewhere on your CLASSPATH. The following properties are supported:

My CatalogManager.properties file looks like this:

#CatalogManager.properties

verbosity=1

relative-catalogs=yes

# Always use semicolons in this list
catalogs=./xcatalog;/share/doctypes/catalog;/share/doctypes/xcatalog

prefer=public

static-catalog=yes

allow-oasis-xml-catalog-pi=yes

catalog-class-name=com.sun.resolver.Resolver

A number of popular applications provide easy access to catalog resolution:

If you work with Java applications using a parser that supports the SAX1 Parser interface or the SAX2 XMLReader interface, adding Catalog support to your applications is a snap. The SAX interfaces include an entityResolver hook designed to provide an application with an opportunity to do this sort of indirection. The Resolver classes implements the full OASIS Catalog semantics and provide an appropriate class that implements the SAX entityResolver interface.

All you have to do is setup a com.sun.resolver.tools.CatalogResolver on your parser's entityResolver hook. The code listing in Example 3 demonstrates how straightforward this is:

import com.sun.resolver.tools.CatalogResolver;
...
    CatalogResolver cr = new CatalogResolver();
...
    yourParser.setEntityResolver(cr)

The system catalogs are loaded from the CatalogManager.properties file on your CLASSPATH. (For all the gory details about these classes, consult the API documentation.) You can explicitly parse your own catalogs (perhaps taken from command line arguments or a Preferences dialog) instead of or in addition to the system catalogs.

The Resolver distribution includes a couple of test programs, resolver and xparse, that you can use to see how this all works.

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

<public publicId="-//Example//DTD Example V1.0//EN"
        uri="example.dtd"/>

</catalog>

$ java com.sun.resolver.apps.resolver -d 2 -c example/catalog.xml \
  -p "-//Example//DTD Example V1.0//EN" public
Loading catalog: ./catalog
Loading catalog: /share/doctypes/catalog
Resolve PUBLIC (publicid, systemid):
  public id: -//Example//DTD Example V1.0//EN
Loading catalog: file:/share/doctypes/entities.cat
Loading catalog: /share/doctypes/xcatalog
Loading catalog: example/catalog.xml
Result: file:/share/documents/articles/sun/2001/01-resolver/example/example.dtd

<!DOCTYPE example PUBLIC "-//Example//DTD Example V1.0//EN"
                  "file:///dev/this/does/not/exist/example.dtd">
<example>
<p>This is just a trivial example.</p>
</example>

$ java com.sun.resolver.apps.xparse -d 2 example.xml
Attempting validating, namespace-aware parse
Fatal error:example.xml:2:External entity not found:
   "file:///dev/this/does/not/exist/example.dtd".
Parse failed with 1 error and no warnings.

$ java com.sun.resolver.apps.xparse -d 2 -c catalog.xml example.xml
Loading catalog: catalog.xml
Attempting validating, namespace-aware parse
Resolved public: -//Example//DTD Example V1.0//EN
    file:/share/documents/articles/sun/2001/01-resolver/example/example.dtd
Parse succeeded (0.32) with no errors and no warnings.

We hope that these classes become a standard part of your toolkit. Incorporating this code allows you to utilize public identifiers in XML documents with the confidence that you will be able to move those documents from one system to another and around the Web.