## XMLCatalog

An XMLCatalog is a catalog of public resources such as DTDs or entities that are referenced in an XML document and are available locally.

This allows the XML Parser, XSL Processor or other consumer of XML documents to efficiently allow a local substitution for a resource available on the web.

For example, in a `web.xml` file, the DTD is referenced as:

    <!DOCTYPE web-app
      PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application
    2.2//EN"
      "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

The XML processor, without XMLCatalog support, would need to retrieve the DTD from the URL specified whenever validation of the document was required.

This can be very time consuming during the build process, especially where network throughput is limited.

XMLCatalogs can appear inside tasks that support this feature or at the same level as `target` - i.e., as children of `project` for reuse across different tasks, e.g. XML Validation and XSL Translation.

XMLCatalogs are specified as either a reference to another XMLCatalog, defined previously in a build file, or as a list of `dtd` or `entity` locations.

### XMLCatalog attributes

Attribute | Description | Required
id | a unique name for an XMLCatalog, used for referencing the XMLCatalog's contents from another XMLCatalog | No
refid | the `id` of another XMLCatalog whose contents you would like to be used for this XMLCatalog | No

### XMLCatalog nested elements

The `dtd` and `entity` elements used to specify XMLCatalogs are identical in their structure

Attribute | Description | Required
publicId | The public identifier used when defining a dtd or entity, e.g. `"-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"` | Yes
location | 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 | Yes

### Examples

Set up an XMLCatalog with a single dtd referenced locally in a user's home directory:

>         <xmlcatalog>
>             <dtd publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
>      location="/home/dion/downloads/docbook/docbookx.dtd"/>
>         </xmlcatalog>

Set up an XMLCatalog with a multiple dtds referenced locally in a user's home directory:

>         <xmlcatalog id="commonDTDs">
>             <dtd publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
>      location="/home/dion/downloads/docbook/docbookx.dtd"/>
>             <dtd publicId="-//Sun Microsystems, Inc.//DTD Web
>     Application 2.2//EN"
>                  location="/home/dion/web-app_2_2.dtd"/>
>         </xmlcatalog>

To reference the above xmlcatalog in a style task:

>         <style basedir="${source.doc}"
>                destdir="${dest.xdocs}"
>                extension=".xml"
>                style="${source.xsl.converter.docbook}"
>                includes="**/*.xml"
>                force="true">
>             <xmlcatalog refid="commonDTDs"/>
>         </style>

Copyright © 2002 Apache Software Foundation. All rights Reserved.