XMLCatalog Type

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>