docs/manual/CoreTypes/xmlcatalog.html - ant - Git at Google

 <html>

 <head>
 <meta http-equiv="Content-Language" content="en-us">
 <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>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>
 &lt;!DOCTYPE web-app PUBLIC &quot;-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN&quot;
   &quot;http://java.sun.com/j2ee/dtds/web-app_2_2.dtd&quot;&gt;
 </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>&lt;xmlcatalog&gt;</code> with a <code>&lt;dtd&gt;</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.  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>Currently, only <code>&lt;dtd&gt;</code> and
 <code>&lt;entity&gt;</code> elements may be specified inline; these
 roughly correspond to OASIS catalog entry types <code>PUBLIC</code> and
 <code>URI</code> respectively.</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>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>&quot;-//Sun Microsystems, Inc.//DTD Web Application
 2.2//EN&quot;</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>&lt;classpath&gt;</code> is a
 <a href="../using.html#path">path</a>-like structure.</p>
 <h3>Examples</h3>
 <p>Set up an XMLCatalog with a single dtd referenced locally in a user's
 home
 directory:</p>
 <blockquote><pre>
     &lt;xmlcatalog&gt;
         &lt;dtd
             publicId=&quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot;
             location=&quot;/home/dion/downloads/docbook/docbookx.dtd&quot;/&gt;
     &lt;/xmlcatalog&gt;
 </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>
     &lt;xmlcatalog id=&quot;commonDTDs&quot;&gt;
         &lt;dtd
             publicId=&quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot;
             location=&quot;docbook/docbookx.dtd&quot;/&gt;
         &lt;dtd
             publicId=&quot;-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN&quot;
             location=&quot;web-app_2_2.dtd&quot;/&gt;
     &lt;/xmlcatalog&gt;
 </pre></blockquote>

 <p>Set up an XMLCatalog with a combination of DTDs and entities as
 well as a nested XMLCatalog:</p>

 <blockquote><pre>
     &lt;xmlcatalog id=&quot;allcatalogs&quot;&gt;
         &lt;dtd
             publicId=&quot;-//ArielPartners//DTD XML Article V1.0//EN&quot;
             location=&quot;com/arielpartners/knowledgebase/dtd/article.dtd&quot;/&gt;
         &lt;entity
             publicId=&quot;LargeLogo&quot;
             location=&quot;com/arielpartners/images/ariel-logo-large.gif&quot;/&gt;
 	&lt;xmlcatalog refid="commonDTDs"/&gt;
     &lt;/xmlcatalog&gt;
 </pre></blockquote>
 <p>To reference the above XMLCatalog in an <code>xslt</code> task:<p>
 <blockquote><pre>
     &lt;xslt basedir="${source.doc}"
            destdir="${dest.xdocs}"
            extension=".xml"
            style="${source.xsl.converter.docbook}"
            includes="**/*.xml"
            force="true"&gt;
         &lt;xmlcatalog refid=&quot;allcatalogs&quot;/&gt;
     &lt;/xslt&gt;
 </pre></blockquote>

 <hr>
 <p align="center">Copyright &copy; 2002 Apache Software Foundation. All
 rights
 Reserved.</p>

 </body>
 </html>
	<html>

	<head>
	<meta http-equiv="Content-Language" content="en-us">
	<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>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. 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>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.</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>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>
	<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:</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"/>
	</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>

	<hr>
	<p align="center">Copyright © 2002 Apache Software Foundation. All
	rights
	Reserved.</p>

	</body>
	</html>