| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>XMLCatalog Type</title> |
| </head> |
| |
| <body> |
| |
| <h2><a name="XMLCatalog">XMLCatalog</a></h2> |
| |
| <p>An XMLCatalog is a catalog of public resources such as DTDs or |
| entities that are referenced in an XML document. Catalogs are |
| typically used to make web references to resources point to a locally |
| cached copy of the resource.</p> |
| |
| <p>This allows the XML Parser, XSLT Processor or other consumer of XML |
| documents |
| to efficiently allow a local substitution for a resource available on the |
| web. |
| </p> |
| <p><b>Note:</b> This task <em>uses, but does not depend on</em> external |
| libraries not included in the Ant distribution. See <a |
| href="../install.html#librarydependencies">Library Dependencies</a> for more |
| information.</p> |
| <p>This data type provides a catalog of resource locations based |
| on the <a |
| href="http://oasis-open.org/committees/entity/spec-2001-08-06.html"> |
| OASIS "Open Catalog" standard</a>. The catalog entries are used |
| both for Entity resolution and URI resolution, in accordance with |
| the <code>org.xml.sax.EntityResolver</code> and <code> |
| javax.xml.transform.URIResolver</code> interfaces as defined |
| in the <a href="http://java.sun.com/xml/jaxp">Java API for XML |
| Processing (JAXP) Specification</a>.</p> |
| <p>For example, in a <code>web.xml</code> file, the DTD is referenced as: |
| <pre> |
| <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" |
| "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"> |
| </pre> |
| The XML processor, without XMLCatalog support, would need to retrieve the |
| DTD from |
| the URL specified whenever validation of the document was required. |
| </p> |
| <p>This can be very time consuming during the build process, |
| especially where network throughput is limited. Alternatively, you |
| can do the following: |
| <ol> |
| <li>Copy <code>web-app_2_2.dtd</code> onto your local disk somewhere (either in the |
| filesystem or even embedded inside a jar or zip file on the classpath).</li> |
| <li>Create an <code><xmlcatalog></code> with a <code><dtd></code> |
| element whose <code>location</code> attribute points to the file.</li> |
| <li>Success! The XML processor will now use the local copy instead of calling out |
| to the internet.</li> |
| </ol> |
| </p> |
| <p>XMLCatalogs can appear inside tasks |
| that support this feature or at the same level as <code>target</code> |
| - i.e., as children of <code>project</code> for reuse across different |
| tasks, |
| e.g. XML Validation and XSLT Transformation. The XML Validate task |
| uses XMLCatalogs for entity resolution. The XSLT Transformation |
| task uses XMLCatalogs for both entity and URI resolution.</p> |
| <p>XMLCatalogs are specified as either a reference to another |
| XMLCatalog, defined previously in a build file, or as a list of |
| <code>dtd</code> or <code>entity</code> locations. In addition, |
| external catalog files may be specified in a nested <code>catalogpath</code> , |
| but they will be ignored unless the resolver library from |
| xml-commons is available in the system classpath. <b>Due to backwards |
| incompatible changes in the resolver code after the release of |
| resolver 1.0, Ant will not support resolver.jar in version 1.0 - we |
| expect a resolver release 1.1 to happen before Ant 1.6 gets |
| released.</b> A separate classpath for entity resolution may be |
| specified inline via nested <code>classpath</code> elements; otherwise |
| the system classpath is used for this as well.</p> |
| <p>XMLCatalogs can also be nested inside other XMLCatalogs. For |
| example, a "superset" XMLCatalog could be made by including several |
| nested XMLCatalogs that referred to other, previously defined |
| XMLCatalogs.</p> |
| <p>Resource locations can be specified either in-line or in |
| external catalog file(s), or both. In order to use an external |
| catalog file, the xml-commons resolver library ("resolver.jar") |
| must be in your path. External catalog files may be either <a |
| href="http://oasis-open.org/committees/entity/background/9401.html"> |
| plain text format</a> or <a |
| href="http://www.oasis-open.org/committees/entity/spec-2001-08-06.html"> |
| XML format</a>. If the xml-commons resolver library is not found in the |
| classpath, external catalog files, specified in <code>catalogpath</code>, |
| will be ignored and a warning |
| will be logged. In this case, however, processing of inline entries will |
| proceed normally.</p> |
| <p>Currently, only <code><dtd></code> and |
| <code><entity></code> elements may be specified inline; these |
| roughly correspond to OASIS catalog entry types <code>PUBLIC</code> and |
| <code>URI</code> respectively. By contrast, external catalog files |
| may use any of the entry types defined in the |
| <a href="http://oasis-open.org/committees/entity/spec-2001-08-06.html"> |
| +OASIS specification</a>.</p> |
| <h3><a name="ResolverAlgorithm">Entity/DTD/URI Resolution Algorithm</a></h3> |
| |
| When an entity, DTD, or URI is looked up by the XML processor, the |
| XMLCatalog searches its list of entries to see if any match. That is, |
| it attempts to match the <code>publicId</code> attribute of each entry |
| with the PublicID or URI of the entity to be resolved. Assuming a |
| matching entry is found, XMLCatalog then executes the following steps: |
| |
| <h4>1. Filesystem lookup</h4> |
| |
| <p>The <code>location</code> is first looked up in the filesystem. If |
| the <code>location</code> is a relative path, the ant project basedir |
| attribute is used as the base directory. If the <code>location</code> |
| specifies an absolute path, it is used as is. Once we have an |
| absolute path in hand, we check to see if a valid and readable file |
| exists at that path. If so, we are done. If not, we proceed to the |
| next step.</p> |
| |
| <h4>2. Classpath lookup</h4> |
| |
| <p>The <code>location</code> is next looked up in the classpath. |
| Recall that jar files are merely fancy zip files. For classpath |
| lookup, the <code>location</code> is used as is (no base is |
| prepended). We use a Classloader to attempt to load the resource from |
| the classpath. For example, if hello.jar is in the classpath and it |
| contains <code>foo/bar/blat.dtd</code> it will resolve an entity whose |
| <code>location</code> is <code>foo/bar/blat.dtd</code>. Of course, it |
| will <em>not</em> resolve an entity whose <code>location</code> is |
| <code>blat.dtd</code>. |
| |
| |
| <h4>3a. Apache xml-commons resolver lookup</h4> |
| |
| <p>What happens next depends on whether the resolver library from |
| xml-commons is available on the classpath. If so, we defer all |
| further attempts at resolving to it. The resolver library supports |
| extremely sophisticated functionality like URL rewriting and so on, |
| which can be accessed by making the appropriate entries in external |
| catalog files (XMLCatalog does not yet provide inline support for all |
| of the entries defined in the <a |
| href="http://oasis-open.org/committees/entity/spec-2001-08-06.html">OASIS |
| standard</a>).</p> |
| |
| <h4>3. URL-space lookup</h4> |
| |
| <p>Finally, we attempt to make a URL out of the <code>location</code>. |
| At first this may seem like this would defeat the purpose of |
| XMLCatalogs -- why go back out to the internet? But in fact, this can |
| be used to (in a sense) implement HTTP redirects, substituting one URL |
| for another. The mapped-to URL might also be served by a local web |
| server. If the URL resolves to a valid and readable resource, we are |
| done. Otherwise, we give up. In this case, the XML processor will |
| perform its normal resolution algorithm. Depending on the processor |
| configuration, further resolution failures may or may not result in |
| fatal (i.e. build-ending) errors.</p> |
| |
| <h3>XMLCatalog attributes</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">id</td> |
| <td valign="top">a unique name for an XMLCatalog, used for referencing |
| the |
| XMLCatalog's contents from another XMLCatalog</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">refid</td> |
| <td valign="top">the <code>id</code> of another XMLCatalog whose |
| contents |
| you would like to be used for this XMLCatalog</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| <h3>XMLCatalog nested elements</h3> |
| <h4>dtd/entity</h4> |
| <p>The <code>dtd</code> and <code>entity</code> elements used to specify |
| XMLCatalogs are identical in their structure</p> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">publicId</td> |
| <td valign="top">The public identifier used when defining a dtd or |
| entity, |
| e.g. <code>"-//Sun Microsystems, Inc.//DTD Web Application |
| 2.2//EN"</code> |
| </td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">location</td> |
| <td valign="top">The location of the local replacement to be used for |
| the public identifier specified. This may be specified as a file name, |
| resource name found on the classpath, or a URL. Relative paths will |
| be resolved according to the base, which by default is the Ant project |
| basedir. |
| </td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| </table> |
| <h4>classpath</h4> |
| <p>The classpath to use for <a href="#ResolverAlgorithm">entity |
| resolution</a>. The nested <code><classpath></code> is a |
| <a href="../using.html#path">path</a>-like structure.</p> |
| <h4>catalogpath</h4> |
| <p> |
| The nested <code>catalogpath</code> element is a <a |
| href="../using.html#path">path</a>-like structure listing catalog files to |
| search. All files in this path are assumed to be OASIS catalog files, in |
| either |
| <a href="http://oasis-open.org/committees/entity/background/9401.html"> |
| plain text format</a> or <a |
| href="http://www.oasis-open.org/committees/entity/spec-2001-08-06.html"> |
| XML format</a>. Entries specifying nonexistent files will be ignored. If the |
| resolver library from xml-commons is not available in the classpath, all |
| <code>catalogpaths</code> will be ignored and a warning will be logged. |
| </p> |
| <h3>Examples</h3> |
| <p>Set up an XMLCatalog with a single dtd referenced locally in a user's |
| home |
| directory:</p> |
| <blockquote><pre> |
| <xmlcatalog> |
| <dtd |
| publicId="-//OASIS//DTD DocBook XML V4.1.2//EN" |
| location="/home/dion/downloads/docbook/docbookx.dtd"/> |
| </xmlcatalog> |
| </pre></blockquote> |
| <p>Set up an XMLCatalog with a multiple dtds to be found either in the |
| filesystem (relative to the Ant project basedir) or in the classpath: |
| </p> |
| <blockquote><pre> |
| <xmlcatalog id="commonDTDs"> |
| <dtd |
| publicId="-//OASIS//DTD DocBook XML V4.1.2//EN" |
| location="docbook/docbookx.dtd"/> |
| <dtd |
| publicId="-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" |
| location="web-app_2_2.dtd"/> |
| </xmlcatalog> |
| </pre></blockquote> |
| |
| <p>Set up an XMLCatalog with a combination of DTDs and entities as |
| well as a nested XMLCatalog and external catalog files in both |
| formats:</p> |
| |
| <blockquote><pre> |
| <xmlcatalog id="allcatalogs"> |
| <dtd |
| publicId="-//ArielPartners//DTD XML Article V1.0//EN" |
| location="com/arielpartners/knowledgebase/dtd/article.dtd"/> |
| <entity |
| publicId="LargeLogo" |
| location="com/arielpartners/images/ariel-logo-large.gif"/> |
| <xmlcatalog refid="commonDTDs"/> |
| <catalogpath> |
| <pathelement location="/etc/sgml/catalog"/> |
| <fileset |
| dir="/anetwork/drive" |
| includes="**/catalog"/> |
| <fileset |
| dir="/my/catalogs" |
| includes="**/catalog.xml"/> |
| </catalogpath> |
| </xmlcatalog> |
| </xmlcatalog> |
| </pre></blockquote> |
| <p>To reference the above XMLCatalog in an <code>xslt</code> task:<p> |
| <blockquote><pre> |
| <xslt basedir="${source.doc}" |
| destdir="${dest.xdocs}" |
| extension=".xml" |
| style="${source.xsl.converter.docbook}" |
| includes="**/*.xml" |
| force="true"> |
| <xmlcatalog refid="allcatalogs"/> |
| </xslt> |
| </pre></blockquote> |
| |
| |
| |
| </body> |
| </html> |
