diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Types/xmlcatalog.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/Types/xmlcatalog.html | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/xmlcatalog.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/xmlcatalog.html new file mode 100644 index 00000000..a0ddafc0 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/xmlcatalog.html @@ -0,0 +1,306 @@ +<!-- + 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 Apache 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="https://jaxp.dev.java.net/">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> |