In order to use XML Catalogs with Xerces, the Apache XML Commons Resolver: resolver.jar needs to be on your classpath (or accessible in some other way to the ClassLoader). The resolver provides an implementation of OASIS XML Catalogs v1.1 as well as some other catalog formats. The XML Commons Resolver 1.2 is included with the binary distribution of Xerces. For information about interacting directly with the Resolver's API visit the XML Commons site.

As a convenience for users the parser provides a utility class: org.apache.xerces.util.XMLCatalogResolver which encapsulates the XML Commons Resolver exposing methods relevant to resolving XML entities. It implements the (org.apache.xerces.xni.parser.XMLEntityResolver) XNI entity resolver, the (org.xml.sax.EntityResolver) SAX entity resolver and the (org.w3c.dom.ls.LSResourceResolver) DOM resource resolver interfaces. In XMLCatalogResolver the resolveEntity methods only query the catalog for a mapping of the given identifier. These methods may be overridden if other behaviour is required.

To use XMLCatalogResolver as an XNI EntityResolver you need to do something like this:

	import org.apache.xerces.util.XMLCatalogResolver; import org.xml.sax.*; ... XMLReader reader; String [] catalogs = {"file:///C:/catalog/cat1.xml", "file:///C:/catalog/cat2.xml"}; ... // Create catalog resolver and set a catalog list. XMLCatalogResolver resolver = new XMLCatalogResolver(); resolver.setPreferPublic(true); resolver.setCatalogList(catalogs); // Set the resolver on the parser. reader.setProperty( "http://apache.org/xml/properties/internal/entity-resolver", resolver); ...

Note that setting an XNI entity resolver on a SAX or DOM parser will replace any type of entity resolver which was previously registered. If some other type of resolver is registered on the parser it will replace any XNI entity resolver previously registered.

In addition to being used as an entity resolver, it is intended that the XMLCatalogResolver may be used standalone to perform catalog resolution outside of a parsing context. It may also be shared between several parsers and the application. See the API documentation for details.

The XMLCatalogResolver class requires the XML Commons Resolver 1.1 or a version compatible with 1.1.

If an instance of XMLCatalogResolver has been registered on the parser as an entity resolver it will first try to lookup the schema in the catalog by its target namespace if it has one using the catalog's uri entries. If the schema has no target namespace, or the namespace is unavailable or no mapping for the namespace could be found the resolver will then try to locate the schema using any location hints provided. These location hints are interpreted to be system identifiers.

When XMLCatalogResolver is registered as a SAX entity resolver, the target namespace of the schema will not be available.

The example below demonstrates resolution of URI references for the purpose of reading XML Schema documents. It's assumed that all the files are located in the same directory and that the list of catalog entry files consists only of catalog.xml and that an instance of XMLCatalogResolver has been registered on the parser as an XNI entity resolver. The parser has been instructed to parse and validate the instance document example.xml against an XML Schema. No location hints are provided so only the namespace of the schema components is known. When the parser attempts to locate the schema for the namespace "http://apache.org/xml/xcatalog/example" it would first query the catalog catalog.xml to resolve the namespace to the URI for the schema. The resolver would find that the mapping for the namespace URI is example.xsd and then return this to the parser. The parser would then load the schema, enabling it to validate the instance document.

	example.xml: <?xml version="1.0"?> <root xmlns="http://apache.org/xml/xcatalog/example"> http://apache.org/xml/anyURI</root> example.xsd: <?xml version="1.0"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://apache.org/xml/xcatalog/example" targetNamespace="http://apache.org/xml/xcatalog/example"> <xs:element name="root" type="xs:anyURI"/> </xs:schema> catalog.xml: <!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"> <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="public"> <uri name="http://apache.org/xml/xcatalog/example" uri="example.xsd"/> </catalog>

If an instance of XMLCatalogResolver has been registered on the parser as an entity resolver it will try to lookup the DTD or external entity in the catalog using the system identifier and public identifier if one is available.

The example below demonstrates resolution of external identifiers for the purpose of reading external entities. Resolution of external DTD subsets and external parameter entities can be done similarly. It's assumed that all the files are located in the same directory and that the list of catalog entry files consists only of catalog.xml and that an instance of XMLCatalogResolver has been registered on the parser as an entity resolver. When the parser references the entity named text in the instance document example.xml it would query the catalog catalog.xml to resolve the public identifier. Note that the system identifier is in an URN and after "unwrapping" is equivalent to the public identifier. Since there is no mapping in this catalog for the public identifier, catalog.xml would delegate to catalog2.xml since the public id starts with "-//A//". Upon reading catalog2.xml the resolver would find a mapping for "-//A//XML CATALOG IDENTIFIER//EN" and then return the URI example.ent. The parser would then open this resource and then report "Hello world!" as the replacement text for the entity named text.

	example.xml: <?xml version="1.0"?> <!DOCTYPE root [ <!ENTITY text PUBLIC "-//A//XML CATALOG IDENTIFIER//EN" "urn:publicid:-:A:XML+CATALOG+IDENTIFIER:EN"> ]> <root>&text;</root> example.ent: Hello world! catalog.xml: <!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"> <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="public"> <delegatePublic publicIdStartString="-//A//" catalog="catalog2.xml"/> </catalog> catalog2.xml: <!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"> <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="public"> <public publicId="-//A//XML CATALOG IDENTIFIER//EN" uri="example.ent"/> </catalog>

No, the parser has no built in support for these processing instructions, however the XML Commons Resolver includes a SAX XMLFilter called org.apache.xml.resolver.tools.ResolvingXMLFilter which is able to process them.

Xerces only includes a utility class for OASIS XML Catalogs, however the XML Commons Resolver supports a few other catalog formats including: the plain text format described by OASIS TR 9401 and the XCatalog XML format defined by John Cowan. For more information visit the XML Commons site.