<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="sourcedocs" page="xml-catalogs" subpage=""/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: Using XML Catalogs</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title" content="Saxonica: XSLT and XQuery Processing: Using XML Catalogs"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>Using XML Catalogs</h1>
<p>XML Catalogs (<a href="http://xml.apache.org/commons/components/resolver/resolver-article.html"
class="bodylink">defined by OASIS</a>)
provide a way to avoid hard-coding the locations of XML documents and other resources in your application. Instead,
the applicaton refers to the resource using a conventional system identifier (URI) or public identifier, and a local
catalog is used to map the system and public identifiers to an actual location.</p>
<p>When using Saxon from the command line, it is possible to specify a catalog to be used using the
option <code>-catalog:<i>files</i></code>. Here <i>files</i> is the catalog file to be searched, or a list
of filenames separated by semicolons. This catalog will be used to locate DTDs and external entities required
by the XML parser, XSLT stylesheet modules requested using <code>xsl:import</code> and <code>xsl:include</code>,
documents requested using the <code>document()</code> and <code>doc()</code> functions, and also schema documents,
however they are referenced.</p>
<p><i>The catalog is NOT currently used for non-XML resources, including query modules, unparsed text files,
collations, and collections.</i></p>
<p>With Saxon on the Java platform, if the <code>-catalog</code> option is used on the command line, then the
open-source Apache library <code>resolver.jar</code> must be present on the classpath. With Saxon on .NET, this
module (cross-compiled to IL) is included within the Saxon DLL.</p>
<p>Setting the <code>-catalog</code> option is equivalent to setting the following options:</p>
<table>
<tr>
<td>
<p>-r</p>
</td>
<td>
<p>org.apache.xml.resolver.tools.CatalogResolver</p>
</td>
</tr>
<tr>
<td>
<p>-x</p>
</td>
<td>
<p>org.apache.xml.resolver.tools.ResolvingXMLReader</p>
</td>
</tr>
<tr>
<td>
<p>-y</p>
</td>
<td>
<p>org.apache.xml.resolver.tools.ResolvingXMLReader</p>
</td>
</tr>
</table>
<p>In addition, the system property <code>xml.catalog.files</code> is set to the
value of the supplied <code><i>files</i></code> value. And if the <code>-t</code>
option is also set, Saxon sets the verbosity level of the catalog manager to 2,
causing it to report messages for each resolved URI. Saxon customizes the Apache resolver
library to integrate these messages with the other output from the <code>-t</code> option:
that is, by default it is sent to the standard error output.</p>
<p><i>This mechanism means that it is not possible to use any of the options <code>-r</code>,
<code>-x</code>, or <code>-y</code> when the <code>-catalog</code> option is used.</i></p>
<p>When the <code>-catalog</code> option is used on the command line, this overrides the internal
resolver used in Saxon (from 9.4) to redirect well-known W3C references (such as the XHTML DTD) to Saxon's local
copies of these resources. Because both these features rely on setting the XML parser's <code>EntityResolver</code>,
it is not possible to use them in conjunction.</p>
<p>This support for OASIS catalogs is implemented only in the Saxon command line. To use
catalogs from a Saxon application, it is necessary to configure the various options
individually. For example:</p>
<ul>
<li>
<p>To use catalogs to resolve references to DTDs and external entities,
choose <code>ResolvingXMLReader</code> as your XML parser, or set
<code>org.apache.xml.resolver.tools.CatalogResolver</code> as the
<code>EntityResolver</code> used by your chosen XML parser.</p>
</li>
<li>
<p>To use catalogs to resolve <code>xsl:include</code> and <code>xsl:import</code>
references, choose
<code>org.apache.xml.resolver.tools.CatalogResolver</code> as the
<code>URIResolver</code> used by Saxon when compiling the stylesheet.</p>
</li>
<li>
<p>To use catalogs to resolve calls on <code>doc()</code> or <code>document()</code>
references, choose
<code>org.apache.xml.resolver.tools.CatalogResolver</code> as the
<code>URIResolver</code> used by Saxon when running the stylesheet
(for example, using <code>Transformer.setURIResolver()</code>).</p>
</li>
</ul>
<p>Here is an example of a very simple catalog file. The <code>publicId</code> and <code>systemID</code>
attributes give the public or system identifier as used in the source document; the <code>uri</code>
attribute gives the location (in this case a relative location) where the actual resource will be found.</p>
<div class="codeblock"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">
<pre>
<code>
<?xml version="1.0"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<group prefer="public" xml:base="file:///usr/share/xml/" >
<public
publicId="-//OASIS//DTD DocBook XML V4.5//EN"
uri="docbook45/docbookx.dtd"/>
<system
systemId="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
uri="docbook45/docbookx.dtd"/>
</group>
</catalog>
</code>
</pre>
</div>
<p>There are many tutorials for XML catalogs available on the web, including some that have information
specific to Saxon, though this may well relate to earlier releases.</p>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="input-filters.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
