xmlcatalog.html | searchcode

/projects/ant-1.8.2/docs/manual/Types/xmlcatalog.html

https://gitlab.com/essere.lab.public/qualitas.class-corpus
HTML | 306 lines | 268 code | 22 blank | 16 comment | 0 complexity | 0b24b97aa318c0964942835fd8ed0563 MD5 | raw file

<!--

   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>

&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.  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>&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.  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>&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>

<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>

    &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 and external catalog files in both

formats:</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;catalogpath&gt;

                &lt;pathelement location="/etc/sgml/catalog"/&gt;

                &lt;fileset 

                    dir=&quot;/anetwork/drive&quot;

                    includes=&quot;**/catalog&quot;/&gt;

                &lt;fileset 

                    dir=&quot;/my/catalogs&quot;

                    includes=&quot;**/catalog.xml&quot;/&gt;

            &lt;/catalogpath&gt;

        &lt;/xmlcatalog&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>







</body>

</html>