| This data type provides a catalog of resource locations (such as
DTDs and XML entities), based on the
OASIS "Open Catalog" standard. The catalog entries are used
both for Entity resolution and URI resolution, in accordance with
the
org.xml.sax.EntityResolver EntityResolver and
javax.xml.transform.URIResolver URIResolver interfaces as defined
in the Java API for XML
Processing Specification.
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 classpath. External catalog files may be either
plain text format or
XML format. If the xml-commons resolver library is not found
in the classpath, external catalog files, specified in
<catalogpath> paths, will be ignored and a warning will
be logged. In this case, however, processing of inline entries will proceed
normally.
Currently, only <dtd> and
<entity> elements may be specified inline; these
correspond to OASIS catalog entry types PUBLIC and
URI respectively.
The following is a usage example:
<xmlcatalog>
<dtd publicId="" location="/path/to/file.jar" />
<dtd publicId="" location="/path/to/file2.jar" />
<entity publicId="" location="/path/to/file3.jar" />
<entity publicId="" location="/path/to/file4.jar" />
<catalogpath>
<pathelement location="/etc/sgml/catalog"/>
</catalogpath>
<catalogfiles dir="/opt/catalogs/" includes="**\catalog.xml" />
</xmlcatalog>
Tasks wishing to use <xmlcatalog> must provide a method called
createXMLCatalog which returns an instance of
XMLCatalog. Nested DTD and entity definitions are handled by
the XMLCatalog object and must be labeled dtd and
entity respectively.
The following is a description of the resolution algorithm:
entities/URIs/dtds are looked up in each of the following contexts,
stopping when a valid and readable resource is found:
- In the local filesystem
- In the classpath
- Using the Apache xml-commons resolver (if it is available)
- In URL-space
See
org.apache.tools.ant.taskdefs.optional.XMLValidateTaskXMLValidateTask for an example of a task that has integrated
support for XMLCatalogs.
Possible future extension could provide for additional OASIS
entry types to be specified inline.
| 