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