org.apache.tools.ant.types

Class XMLCatalog

public class XMLCatalog extends DataType implements Cloneable, EntityResolver, URIResolver

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:

  1. In the local filesystem
  2. In the classpath
  3. Using the Apache xml-commons resolver (if it is available)
  4. In URL-space

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

Field Summary
static StringAPACHE_RESOLVER
The name of the bridge to the Apache xml-commons resolver class, used to determine whether resolver.jar is present in the classpath.
static StringCATALOG_RESOLVER
Resolver base class
Constructor Summary
XMLCatalog()
Default constructor
Method Summary
voidaddConfiguredXMLCatalog(XMLCatalog catalog)
Loads a nested <xmlcatalog> into our definition.
voidaddDTD(ResourceLocation dtd)
Creates the nested <dtd> element.
voidaddEntity(ResourceLocation entity)
Creates the nested <entity> element.
PathcreateCatalogPath()
Creates a nested <catalogpath> element.
PathcreateClasspath()
Allows nested classpath elements.
PathgetCatalogPath()
Returns the catalog path in which to attempt to resolve DTDs.
Sourceresolve(String href, String base)
Implements the URIResolver.resolve() interface method.
InputSourceresolveEntity(String publicId, String systemId)
Implements the EntityResolver.resolveEntity() interface method.
voidsetCatalogPathRef(Reference r)
Allows catalogpath reference.
voidsetClasspath(Path classpath)
Allows simple classpath string.
voidsetClasspathRef(Reference r)
Allows classpath reference.
voidsetRefid(Reference r)
Makes this instance in effect a reference to another XMLCatalog instance.

Field Detail

APACHE_RESOLVER

public static final String APACHE_RESOLVER
The name of the bridge to the Apache xml-commons resolver class, used to determine whether resolver.jar is present in the classpath.

CATALOG_RESOLVER

public static final String CATALOG_RESOLVER
Resolver base class

Constructor Detail

XMLCatalog

public XMLCatalog()
Default constructor

Method Detail

addConfiguredXMLCatalog

public void addConfiguredXMLCatalog(XMLCatalog catalog)
Loads a nested <xmlcatalog> into our definition. Not allowed if this catalog is itself a reference to another catalog -- that is, a catalog cannot both refer to another and contain elements or other attributes.

Parameters: catalog Nested XMLCatalog

addDTD

public void addDTD(ResourceLocation dtd)
Creates the nested <dtd> element. Not allowed if this catalog is itself a reference to another catalog -- that is, a catalog cannot both refer to another and contain elements or other attributes.

Parameters: dtd the information about the PUBLIC resource mapping to be added to the catalog

Throws: BuildException if this is a reference and no nested elements are allowed.

addEntity

public void addEntity(ResourceLocation entity)
Creates the nested <entity> element. Not allowed if this catalog is itself a reference to another catalog -- that is, a catalog cannot both refer to another and contain elements or other attributes.

Parameters: entity the information about the URI resource mapping to be added to the catalog.

Throws: BuildException if this is a reference and no nested elements are allowed.

createCatalogPath

public Path createCatalogPath()
Creates a nested <catalogpath> element. Not allowed if this catalog is itself a reference to another catalog -- that is, a catalog cannot both refer to another and contain elements or other attributes.

Returns: a path to be configured as the catalog path.

Throws: BuildException if this is a reference and no nested elements are allowed.

createClasspath

public Path createClasspath()
Allows nested classpath elements. Not allowed if this catalog is itself a reference to another catalog -- that is, a catalog cannot both refer to another and contain elements or other attributes.

Returns: a Path instance to be configured.

getCatalogPath

public Path getCatalogPath()
Returns the catalog path in which to attempt to resolve DTDs.

Returns: the catalog path

resolve

public Source resolve(String href, String base)
Implements the URIResolver.resolve() interface method.

Parameters: href an href attribute. base the base URI.

Returns: a Source object, or null if href cannot be resolved.

Throws: TransformerException if an error occurs.

See Also: javax.xml.transform.URIResolver#resolve

resolveEntity

public InputSource resolveEntity(String publicId, String systemId)
Implements the EntityResolver.resolveEntity() interface method.

Parameters: publicId the public id to resolve. systemId the system id to resolve.

Returns: the resolved entity.

Throws: SAXException if there is a parsing problem. IOException if there is an IO problem.

See Also: org.xml.sax.EntityResolver#resolveEntity

setCatalogPathRef

public void setCatalogPathRef(Reference r)
Allows catalogpath reference. Not allowed if this catalog is itself a reference to another catalog -- that is, a catalog cannot both refer to another and contain elements or other attributes.

Parameters: r an Ant reference containing a classpath to be used as the catalog path.

setClasspath

public void setClasspath(Path classpath)
Allows simple classpath string. Not allowed if this catalog is itself a reference to another catalog -- that is, a catalog cannot both refer to another and contain elements or other attributes.

Parameters: classpath the classpath to use to look up entities.

setClasspathRef

public void setClasspathRef(Reference r)
Allows classpath reference. Not allowed if this catalog is itself a reference to another catalog -- that is, a catalog cannot both refer to another and contain elements or other attributes.

Parameters: r an Ant reference containing a classpath.

setRefid

public void setRefid(Reference r)
Makes this instance in effect a reference to another XMLCatalog instance.

You must not set another attribute or nest elements inside this element if you make it a reference. That is, a catalog cannot both refer to another and contain elements or attributes.

Parameters: r the reference to which this catalog instance is associated

Throws: BuildException if this instance already has been configured.