XMLCatalog

XMLCatalog

An XMLCatalog is a catalog of public resources such as DTDs orentities that are referenced in an XML document. Catalogs aretypically used to make web references to resources point to a locallycached copy of the resource.

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

Note: This task uses, but does not depend on externallibraries not included in the Apache Ant distribution. See Library Dependencies for moreinformation.

This data type provides a catalog of resource locations basedon the OASIS "Open Catalog" standard. The catalog entries are usedboth for Entity resolution and URI resolution, in accordance withthe org.xml.sax.EntityResolver and javax.xml.transform.URIResolver interfaces as definedin the Java API for XMLProcessing (JAXP) Specification.

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

This can be very time consuming during the build process,especially where network throughput is limited. Alternatively, youcan do the following:

1. Copy web-app_2_2.dtd onto your local disk somewhere (either in thefilesystem or even embedded inside a jar or zip file on the classpath).
2. Create an <xmlcatalog> with a <dtd> element whose location attribute points to the file.
3. Success! The XML processor will now use the local copy instead of calling outto the internet.

XMLCatalogs can appear inside tasksthat 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 XSLT Transformation. The XML Validate taskuses XMLCatalogs for entity resolution. The XSLT Transformationtask uses XMLCatalogs for both entity and URI resolution.

XMLCatalogs are specified as either a reference to anotherXMLCatalog, defined previously in a build file, or as a list ofdtd or entity locations. In addition,external catalog files may be specified in a nested catalogpath ,but they will be ignored unless the resolver library fromxml-commons is available in the system classpath. Due to backwardsincompatible changes in the resolver code after the release ofresolver 1.0, Ant will not support resolver.jar in version 1.0 - weexpect a resolver release 1.1 to happen before Ant 1.6 getsreleased. A separate classpath for entity resolution may bespecified inline via nested classpath elements; otherwisethe system classpath is used for this as well.

XMLCatalogs can also be nested inside other XMLCatalogs. Forexample, a "superset" XMLCatalog could be made by including severalnested XMLCatalogs that referred to other, previously definedXMLCatalogs.

Resource locations can be specified either in-line or inexternal catalog file(s), or both. In order to use an externalcatalog file, the xml-commons resolver library ("resolver.jar")must be in your path. External catalog files may be either plain text format or XML format. If the xml-commons resolver library is not found in theclasspath, external catalog files, specified in catalogpath, will be ignored and a warningwill be logged. In this case, however, processing of inline entries willproceed normally.

Currently, only <dtd> and<entity> elements may be specified inline; theseroughly correspond to OASIS catalog entry types PUBLIC andURI respectively. By contrast, external catalog filesmay use any of the entry types defined in the +OASIS specification.

Entity/DTD/URI Resolution Algorithm

1. Filesystem lookup

The location is first looked up in the filesystem. Ifthe location is a relative path, the ant project basedirattribute is used as the base directory. If the locationspecifies an absolute path, it is used as is. Once we have anabsolute path in hand, we check to see if a valid and readable fileexists at that path. If so, we are done. If not, we proceed to thenext step.

2. Classpath lookup

The location is next looked up in the classpath.Recall that jar files are merely fancy zip files. For classpathlookup, the location is used as is (no base isprepended). We use a Classloader to attempt to load the resource fromthe classpath. For example, if hello.jar is in the classpath and itcontains foo/bar/blat.dtd it will resolve an entity whoselocation is foo/bar/blat.dtd. Of course, itwill not resolve an entity whose location isblat.dtd.

3a. Apache xml-commons resolver lookup

What happens next depends on whether the resolver library fromxml-commons is available on the classpath. If so, we defer allfurther attempts at resolving to it. The resolver library supportsextremely sophisticated functionality like URL rewriting and so on,which can be accessed by making the appropriate entries in externalcatalog files (XMLCatalog does not yet provide inline support for allof the entries defined in the OASISstandard).

3. URL-space lookup

Finally, we attempt to make a URL out of the location.At first this may seem like this would defeat the purpose ofXMLCatalogs -- why go back out to the internet? But in fact, this canbe used to (in a sense) implement HTTP redirects, substituting one URLfor another. The mapped-to URL might also be served by a local webserver. If the URL resolves to a valid and readable resource, we aredone. Otherwise, we give up. In this case, the XML processor willperform its normal resolution algorithm. Depending on the processorconfiguration, further resolution failures may or may not result infatal (i.e. build-ending) errors.

XMLCatalog attributes

XMLCatalog nested elements

dtd/entity

The dtd and entity elements used to specifyXMLCatalogs are identical in their structure

classpath

The classpath to use for entityresolution. The nested <classpath> is apath-like structure.

catalogpath

The nested catalogpath element is a path-like structure listing catalog files tosearch. All files in this path are assumed to be OASIS catalog files, ineitherplain text format or XML format. Entries specifying nonexistent files will be ignored. If theresolver library from xml-commons is not available in the classpath, allcatalogpaths will be ignored and a warning will be logged.

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 to be found either in thefilesystem (relative to the Ant project basedir) or in the classpath:

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

Set up an XMLCatalog with a combination of DTDs and entities aswell as a nested XMLCatalog and external catalog files in bothformats:

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

To reference the above XMLCatalog in an xslt task:

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