Debian Codegraph @

manual/Types/xmlcatalog.html

raw
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 &lt;!DOCTYPE web-app PUBLIC &quot;-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN&quot;
49 &quot;http://java.sun.com/j2ee/dtds/web-app_2_2.dtd&quot;&gt;</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>&lt;xmlcatalog&gt;</code> with a <code>&lt;dtd&gt;</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>&mdash;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>&lt;dtd&gt;</code> and <code>&lt;entity&gt;</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&mdash;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>&quot;-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN&quot;</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>&lt;classpath&gt;</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 &lt;xmlcatalog&gt;
197 &lt;dtd publicId=&quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot;
198 location=&quot;/home/dion/downloads/docbook/docbookx.dtd&quot;/&gt;
199 &lt;/xmlcatalog&gt;</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 &lt;xmlcatalog id=&quot;commonDTDs&quot;&gt;
205 &lt;dtd publicId=&quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot;
206 location=&quot;docbook/docbookx.dtd&quot;/&gt;
207 &lt;dtd publicId=&quot;-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN&quot;
208 location=&quot;web-app_2_2.dtd&quot;/&gt;
209 &lt;/xmlcatalog&gt;</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 &lt;xmlcatalog id=&quot;allcatalogs&quot;&gt;
216 &lt;dtd publicId=&quot;-//ArielPartners//DTD XML Article V1.0//EN&quot;
217 location=&quot;com/arielpartners/knowledgebase/dtd/article.dtd&quot;/&gt;
218 &lt;entity publicId=&quot;LargeLogo&quot;
219 location=&quot;com/arielpartners/images/ariel-logo-large.gif&quot;/&gt;
220 &lt;xmlcatalog refid="commonDTDs"/&gt;
221 &lt;catalogpath&gt;
222 &lt;pathelement location="/etc/sgml/catalog"/&gt;
223 &lt;fileset dir=&quot;/anetwork/drive&quot;
224 includes=&quot;**/catalog&quot;/&gt;
225 &lt;fileset dir=&quot;/my/catalogs&quot;
226 includes=&quot;**/catalog.xml&quot;/&gt;
227 &lt;/catalogpath&gt;
228 &lt;/xmlcatalog&gt;
229 &lt;/xmlcatalog&gt;</pre>
230 <p>To reference the above XMLCatalog in an <code>xslt</code> task:<p>
231 <pre>
232 &lt;xslt basedir="${source.doc}"
233 destdir="${dest.xdocs}"
234 extension=".xml"
235 style="${source.xsl.converter.docbook}"
236 includes="**/*.xml"
237 force="true"&gt;
238 &lt;xmlcatalog refid=&quot;allcatalogs&quot;/&gt;
239 &lt;/xslt&gt;</pre>
240
241 </body>
242 </html>