| 1 |
<!DOCTYPE html> |
| 2 |
<!-- |
| 3 |
Licensed to the Apache Software Foundation (ASF) under one or more |
| 4 |
contributor license agreements. See the NOTICE file distributed with |
| 5 |
this work for additional information regarding copyright ownership. |
| 6 |
The ASF licenses this file to You under the Apache License, Version 2.0 |
| 7 |
(the "License"); you may not use this file except in compliance with |
| 8 |
the License. You may obtain a copy of the License at |
| 9 |
|
| 10 |
https://www.apache.org/licenses/LICENSE-2.0 |
| 11 |
|
| 12 |
Unless required by applicable law or agreed to in writing, software |
| 13 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 14 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 15 |
See the License for the specific language governing permissions and |
| 16 |
limitations under the License. |
| 17 |
--> |
| 18 |
<html lang="en"> |
| 19 |
|
| 20 |
<head> |
| 21 |
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| 22 |
<title>XMLCatalog Type</title> |
| 23 |
</head> |
| 24 |
|
| 25 |
<body> |
| 26 |
|
| 27 |
<h2 id="XMLCatalog">XMLCatalog</h2> |
| 28 |
|
| 29 |
<p>An XMLCatalog is a catalog of public resources such as DTDs or entities that are referenced in an |
| 30 |
XML document. Catalogs are typically used to make web references to resources point to a locally |
| 31 |
cached copy of the resource.</p> |
| 32 |
|
| 33 |
<p>This allows the XML Parser, XSLT Processor or other consumer of XML documents to efficiently |
| 34 |
allow a local substitution for a resource available on the web.</p> |
| 35 |
<p><strong>Note:</strong> This task <em>uses, but does not depend on</em> external libraries not |
| 36 |
included in the Apache Ant distribution. See <a href="../install.html#librarydependencies">Library |
| 37 |
Dependencies</a> for more information.</p> |
| 38 |
<p>This data type provides a catalog of resource locations based on |
| 39 |
the <a href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html" |
| 40 |
target="_top">OASIS XML Catalog standard</a>. The catalog entries are used both for Entity |
| 41 |
resolution and URI resolution, in accordance with |
| 42 |
the <code class="code">org.xml.sax.EntityResolver</code> |
| 43 |
and <code class="code">javax.xml.transform.URIResolver</code> interfaces as defined in |
| 44 |
the <a href="https://download.oracle.com/otn-pub/jcp/jaxp-1_6-mrel3-spec/JAXP1_6-FinalSpec.pdf" |
| 45 |
target="_top">Java API for XML Processing (JAXP) Specification</a>.</p> |
| 46 |
<p>For example, in a <code>web.xml</code> file, the DTD is referenced as:</p> |
| 47 |
<pre> |
| 48 |
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" |
| 49 |
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"></pre> |
| 50 |
<p>The XML processor, without XMLCatalog support, would need to retrieve the DTD from the URL |
| 51 |
specified whenever validation of the document was required.</p> |
| 52 |
<p>This can be very time consuming during the build process, especially where network throughput |
| 53 |
is limited. Alternatively, you can do the following:</p> |
| 54 |
<ol> |
| 55 |
<li>Copy <samp>web-app_2_2.dtd</samp> onto your local disk somewhere (either in the filesystem |
| 56 |
or even embedded inside a jar or zip file on the classpath).</li> |
| 57 |
<li>Create an <code><xmlcatalog></code> with a <code><dtd></code> element |
| 58 |
whose <var>location</var> attribute points to the file.</li> |
| 59 |
<li>Success! The XML processor will now use the local copy instead of calling out to the |
| 60 |
internet.</li> |
| 61 |
</ol> |
| 62 |
<p>XMLCatalogs can appear inside tasks that support this feature or at the same level |
| 63 |
as <code>target</code>—i.e., as children of <code>project</code> for reuse across |
| 64 |
different tasks, e.g. XML Validation and XSLT Transformation. The XML Validate task uses |
| 65 |
XMLCatalogs for entity resolution. The XSLT Transformation task uses XMLCatalogs for both |
| 66 |
entity and URI resolution.</p> |
| 67 |
<p>XMLCatalogs are specified as either a reference to another XMLCatalog, defined previously in |
| 68 |
a build file, or as a list of <code>dtd</code> or <code>entity</code> locations. In addition, |
| 69 |
external catalog files may be specified in a nested <code>catalogpath</code>, but they will be |
| 70 |
ignored unless the resolver library from xml-commons is available in the system |
| 71 |
classpath. <strong>Due to backwards incompatible changes in the resolver code after the release |
| 72 |
of resolver 1.0, Ant supports only resolver 1.1 or later.</strong> A separate classpath for |
| 73 |
entity resolution may be specified inline via nested <code>classpath</code> elements; otherwise |
| 74 |
the system classpath is used for this as well.</p> |
| 75 |
<p>XMLCatalogs can also be nested inside other XMLCatalogs. For example, a "superset" |
| 76 |
XMLCatalog could be made by including several nested XMLCatalogs that referred to other, |
| 77 |
previously defined XMLCatalogs.</p> |
| 78 |
<p>Resource locations can be specified either in-line or in external catalog file(s), or both. In |
| 79 |
order to use an external catalog file, the xml-commons resolver library (<samp>resolver.jar</samp>) |
| 80 |
must be in your path. External catalog files may be |
| 81 |
either <a href="https://oasis-open.org/committees/entity/background/9401.html" target="_top">plain |
| 82 |
text format</a> or <a href="https://www.oasis-open.org/committees/entity/spec-2001-08-06.html" |
| 83 |
target="_top">XML format</a>. If the xml-commons resolver library is not found in the classpath, |
| 84 |
external catalog files, specified in <code>catalogpath</code>, will be ignored and a warning will be |
| 85 |
logged. In this case, however, processing of inline entries will proceed normally.</p> |
| 86 |
<p>Currently, only <code><dtd></code> and <code><entity></code> elements may be |
| 87 |
specified inline; these roughly correspond to OASIS catalog entry types <code>PUBLIC</code> |
| 88 |
and <code>URI</code> respectively. By contrast, external catalog files may use any of the entry |
| 89 |
types defined in |
| 90 |
the <a href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html" |
| 91 |
target="_top">OASIS specification</a>.</p> |
| 92 |
<h3 id="ResolverAlgorithm">Entity/DTD/URI resolution algorithm</h3> |
| 93 |
<p>When an entity, DTD, or URI is looked up by the XML processor, the XMLCatalog searches its list |
| 94 |
of entries to see if any match. That is, it attempts to match the <var>publicId</var> attribute of |
| 95 |
each entry with the PublicID or URI of the entity to be resolved. Assuming a matching entry is |
| 96 |
found, XMLCatalog then executes the following steps:</p> |
| 97 |
|
| 98 |
<h4>1. Filesystem lookup</h4> |
| 99 |
|
| 100 |
<p>The <var>location</var> is first looked up in the filesystem. If the <var>location</var> is a |
| 101 |
relative path, the Ant project <var>basedir</var> attribute is used as the base directory. If |
| 102 |
the <var>location</var> specifies an absolute path, it is used as is. Once we have an absolute path |
| 103 |
in hand, we check to see if a valid and readable file exists at that path. If so, we are done. If |
| 104 |
not, we proceed to the next step.</p> |
| 105 |
|
| 106 |
<h4>2. Classpath lookup</h4> |
| 107 |
|
| 108 |
<p>The <var>location</var> is next looked up in the classpath. Recall that jar files are merely |
| 109 |
fancy zip files. For classpath lookup, the <var>location</var> is used as is (no base is |
| 110 |
prepended). We use a Classloader to attempt to load the resource from the classpath. For example, |
| 111 |
if <samp>hello.jar</samp> is in the classpath and it contains <samp>foo/bar/blat.dtd</samp> it will |
| 112 |
resolve an entity whose <var>location</var> is <samp>foo/bar/blat.dtd</samp>. Of course, it |
| 113 |
will <em>not</em> resolve an entity whose <var>location</var> is <code>blat.dtd</code>.</p> |
| 114 |
|
| 115 |
<h4>3a. Apache xml-commons resolver lookup</h4> |
| 116 |
|
| 117 |
<p>What happens next depends on whether the resolver library from xml-commons is available on the |
| 118 |
classpath. If so, we defer all further attempts at resolving to it. The resolver library supports |
| 119 |
extremely sophisticated functionality like URL rewriting and so on, which can be accessed by making |
| 120 |
the appropriate entries in external catalog files (XMLCatalog does not yet provide inline support |
| 121 |
for all of the entries defined in |
| 122 |
the <a href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html" |
| 123 |
target="_top">OASIS standard</a>).</p> |
| 124 |
|
| 125 |
<h4>3. URL-space lookup</h4> |
| 126 |
|
| 127 |
<p>Finally, we attempt to make a URL out of the <var>location</var>. At first this may seem like |
| 128 |
this would defeat the purpose of XMLCatalogs—why go back out to the internet? But in fact, |
| 129 |
this can be used to (in a sense) implement HTTP redirects, substituting one URL for another. The |
| 130 |
mapped-to URL might also be served by a local web server. If the URL resolves to a valid and |
| 131 |
readable resource, we are done. Otherwise, we give up. In this case, the XML processor will |
| 132 |
perform its normal resolution algorithm. Depending on the processor configuration, further |
| 133 |
resolution failures may or may not result in fatal (i.e. build-ending) errors.</p> |
| 134 |
|
| 135 |
<h3>XMLCatalog attributes</h3> |
| 136 |
<table class="attr"> |
| 137 |
<tr> |
| 138 |
<th scope="col">Attribute</th> |
| 139 |
<th scope="col">Description</th> |
| 140 |
<th scope="col">Required</th> |
| 141 |
</tr> |
| 142 |
<tr> |
| 143 |
<td>id</td> |
| 144 |
<td>a unique name for an XMLCatalog, used for referencing the XMLCatalog's contents from |
| 145 |
another XMLCatalog</td> |
| 146 |
<td>No</td> |
| 147 |
</tr> |
| 148 |
<tr> |
| 149 |
<td>refid</td> |
| 150 |
<td>the <var>id</var> of another XMLCatalog whose contents you would like to be used for |
| 151 |
this XMLCatalog</td> |
| 152 |
<td>No</td> |
| 153 |
</tr> |
| 154 |
</table> |
| 155 |
|
| 156 |
<h3>XMLCatalog nested elements</h3> |
| 157 |
<h4>dtd/entity</h4> |
| 158 |
<p>The <code>dtd</code> and <code>entity</code> elements used to specify XMLCatalogs are |
| 159 |
identical in their structure</p> |
| 160 |
<table class="attr"> |
| 161 |
<tr> |
| 162 |
<th scope="col">Attribute</th> |
| 163 |
<th scope="col">Description</th> |
| 164 |
<th scope="col">Required</th> |
| 165 |
</tr> |
| 166 |
<tr> |
| 167 |
<td>publicId</td> |
| 168 |
<td>The public identifier used when defining a dtd or entity, e.g. |
| 169 |
<code>"-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"</code></td> |
| 170 |
<td>Yes</td> |
| 171 |
</tr> |
| 172 |
<tr> |
| 173 |
<td>location</td> |
| 174 |
<td>The location of the local replacement to be used for the public identifier specified. This |
| 175 |
may be specified as a file name, resource name found on the classpath, or a URL. Relative paths |
| 176 |
will be resolved according to the base, which by default is the Ant |
| 177 |
project <var>basedir</var>.</td> |
| 178 |
<td>Yes</td> |
| 179 |
</tr> |
| 180 |
</table> |
| 181 |
<h4>classpath</h4> |
| 182 |
<p>The classpath to use for <a href="#ResolverAlgorithm">entity resolution</a>. The |
| 183 |
nested <code><classpath></code> is a <a href="../using.html#path">path</a>-like structure.</p> |
| 184 |
<h4>catalogpath</h4> |
| 185 |
<p>The nested <code>catalogpath</code> element is a <a href="../using.html#path">path</a>-like |
| 186 |
structure listing catalog files to search. All files in this path are assumed to be OASIS catalog |
| 187 |
files, in either <a href="https://oasis-open.org/committees/entity/background/9401.html" |
| 188 |
target="_top">plain text format</a> |
| 189 |
or <a href="https://www.oasis-open.org/committees/entity/spec-2001-08-06.html" target="_top">XML |
| 190 |
format</a>. Entries specifying nonexistent files will be ignored. If the resolver library from |
| 191 |
xml-commons is not available in the classpath, all <code>catalogpath</code>s will be ignored and a |
| 192 |
warning will be logged.</p> |
| 193 |
<h3>Examples</h3> |
| 194 |
<p>Set up an XMLCatalog with a single DTD referenced locally in a user's home directory:</p> |
| 195 |
<pre> |
| 196 |
<xmlcatalog> |
| 197 |
<dtd publicId="-//OASIS//DTD DocBook XML V4.1.2//EN" |
| 198 |
location="/home/dion/downloads/docbook/docbookx.dtd"/> |
| 199 |
</xmlcatalog></pre> |
| 200 |
<p>Set up an XMLCatalog with a multiple DTDs to be found either in the filesystem (relative to |
| 201 |
the Ant project <var>basedir</var>) or in the classpath: |
| 202 |
</p> |
| 203 |
<pre> |
| 204 |
<xmlcatalog id="commonDTDs"> |
| 205 |
<dtd publicId="-//OASIS//DTD DocBook XML V4.1.2//EN" |
| 206 |
location="docbook/docbookx.dtd"/> |
| 207 |
<dtd publicId="-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" |
| 208 |
location="web-app_2_2.dtd"/> |
| 209 |
</xmlcatalog></pre> |
| 210 |
|
| 211 |
<p>Set up an XMLCatalog with a combination of DTDs and entities as well as a nested XMLCatalog |
| 212 |
and external catalog files in both formats:</p> |
| 213 |
|
| 214 |
<pre> |
| 215 |
<xmlcatalog id="allcatalogs"> |
| 216 |
<dtd publicId="-//ArielPartners//DTD XML Article V1.0//EN" |
| 217 |
location="com/arielpartners/knowledgebase/dtd/article.dtd"/> |
| 218 |
<entity publicId="LargeLogo" |
| 219 |
location="com/arielpartners/images/ariel-logo-large.gif"/> |
| 220 |
<xmlcatalog refid="commonDTDs"/> |
| 221 |
<catalogpath> |
| 222 |
<pathelement location="/etc/sgml/catalog"/> |
| 223 |
<fileset dir="/anetwork/drive" |
| 224 |
includes="**/catalog"/> |
| 225 |
<fileset dir="/my/catalogs" |
| 226 |
includes="**/catalog.xml"/> |
| 227 |
</catalogpath> |
| 228 |
</xmlcatalog> |
| 229 |
</xmlcatalog></pre> |
| 230 |
<p>To reference the above XMLCatalog in an <code>xslt</code> task:<p> |
| 231 |
<pre> |
| 232 |
<xslt basedir="${source.doc}" |
| 233 |
destdir="${dest.xdocs}" |
| 234 |
extension=".xml" |
| 235 |
style="${source.xsl.converter.docbook}" |
| 236 |
includes="**/*.xml" |
| 237 |
force="true"> |
| 238 |
<xmlcatalog refid="allcatalogs"/> |
| 239 |
</xslt></pre> |
| 240 |
|
| 241 |
</body> |
| 242 |
</html> |