Using XML Catalogs
Questions
Usage
Resolving XML Schemas
Resolving DTDs and other External Entities
The XML Catalogs Processing Instruction
Other Catalog Formats
Answers
How do I use OASIS XML Catalogs with the parser?
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.
How does XMLCatalogResolver resolve XML Schemas?
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:
example.xsd:
targetNamespace="http://apache.org/xml/xcatalog/example">
catalog.xml:
PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
How does XMLCatalogResolver resolve DTDs and other external entities?
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:
"urn:publicid:-:A:XML+CATALOG+IDENTIFIER:EN">
]>
example.ent:
Hello world!
catalog.xml:
PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
catalog2.xml:
PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
Does the parser read the 'oasis-xml-catalog' processing instruction?
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.
Are other catalog formats supported?
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.
Copyright © 1999-2022 The Apache Software Foundation.