<XMLCatalog>

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 {@link org.xml.sax.EntityResolver EntityResolver} and {@link 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 {@link org.apache.tools.ant.taskdefs.optional.XMLValidateTask XMLValidateTask} 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.

<entity>

Helper class to handle the <dtd> and <entity> nested elements. These correspond to the PUBLIC and URI catalog entry types, respectively, as defined in the OASIS "Open Catalog" standard.

Possible Future Enhancements:

Bring the Ant element names into conformance with the OASIS standard
Add support for additional OASIS catalog entry types

Attribute	Description	Type	Required
publicid		String	?
base		URL	?

<classpath> ...

This object represents a path as used by CLASSPATH or PATH environment variable.

<sometask> <somepath> <pathelement location="/path/to/file.jar" /> <pathelement path="/path/to/file2.jar:/path/to/class2;/path/to/class3" /> <pathelement location="/path/to/file3.jar" /> <pathelement location="/path/to/file4.jar" /> </somepath> </sometask>

The object implemention sometask must provide a method called createSomepath which returns an instance of Path. Nested path definitions are handled by the Path object and must be labeled pathelement.

The path element takes a parameter path which will be parsed and split into single elements. It will usually be used to define a path from an environment variable.

Attribute	Description	Type	Required
refid	Makes this instance in effect a reference to another Path instance. You must not set another attribute or nest elements inside this element if you make it a reference.	Reference	?
path	Parses a path definition and creates single PathElements.	String	?

<catalogpath> ...