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.
This allows the XML Parser, XSLT Processor or other consumer of XML
to efficiently allow a local substitution for a resource available on the
This data type provides a catalog of resource locations based
OASIS "Open Catalog" standard. The catalog entries are used
both for Entity resolution and URI resolution, in accordance with
Processing (JAXP) Specification.
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
The XML processor, without XMLCatalog support, would need to retrieve the
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. Alternatively, you
can do the following:
web-app_2_2.dtd onto your local disk somewhere (either in the
filesystem or even embedded inside a jar or zip file on the classpath).
location attribute points to the file.
- Success! The XML processor will now use the local copy instead of calling out
to the internet.
XMLCatalogs can appear inside tasks
that support this feature or at the same level as
- i.e., as children of
project for reuse across different
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.
XMLCatalogs are specified as either a reference to another XMLCatalog,
previously in a build file, or as a list of
entity locations. A separate classpath for entity resolution
may be specified inline via nested
otherwise the system classpath is used for this as well.
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
When an entity, DTD, or URI is looked up by the XML processor, the
it attempts to match the
<entity> elements may be specified inline; these
roughly correspond to OASIS catalog entry types
publicId 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:
1. Filesystem lookup
location is first looked up in the filesystem. If
location is a relative path, the ant project basedir
attribute is used as the base directory. If the
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
2. Classpath lookup
location is next looked up in the classpath.
Recall that jar files are merely fancy zip files. For classpath
location 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
foo/bar/blat.dtd it will resolve an entity whose
foo/bar/blat.dtd. Of course, it
will not resolve an entity whose
3. URL-space lookup
Finally, we attempt to make a URL out of the
At first this may seem like this would defeat the purpose of
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.
||a unique name for an XMLCatalog, used for referencing
XMLCatalog's contents from another XMLCatalog
id of another XMLCatalog whose
you would like to be used for this XMLCatalog
XMLCatalog nested elements
entity elements used to specify
||The public identifier used when defining a dtd or
"-//Sun Microsystems, Inc.//DTD Web Application
||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
The classpath to use for entity
resolution. The nested
<classpath> is a
Set up an XMLCatalog with a single dtd referenced locally in a user's
publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
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:
publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
publicId="-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
Set up an XMLCatalog with a combination of DTDs and entities as
well as a nested XMLCatalog:
publicId="-//ArielPartners//DTD XML Article V1.0//EN"
To reference the above XMLCatalog in an
Copyright © 2002 Apache Software Foundation. All