XMLCatalog (Apache Ant API)
Description: declaration: package: org.apache.tools.ant.types, class: XMLCatalog

Package org.apache.tools.ant.types

# Class XMLCatalog

java.lang.Object
org.apache.tools.ant.ProjectComponent
org.apache.tools.ant.types.DataType
org.apache.tools.ant.types.XMLCatalog

All Implemented Interfaces:
  `Cloneable`, `URIResolver`, `EntityResolver`

public class XMLCatalog extends DataType implements 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 `EntityResolver` and `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

  Fields
  Modifier and Type
  Field
  Description
  `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.
  `static final String`
  `CATALOG_RESOLVER`
  Resolver base class

  ### Fields inherited from class org.apache.tools.ant.types.DataType

  `checked, ref`

  ### Fields inherited from class org.apache.tools.ant.ProjectComponent

  `description, location, project`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `XMLCatalog()`
  Default constructor

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addConfiguredXMLCatalog(XMLCatalog catalog)`
  Loads a nested `<xmlcatalog>` into our definition.
  `void`
  `addDTD(ResourceLocation dtd)`
  Creates the nested `<dtd>` element.
  `void`
  `addEntity(ResourceLocation entity)`
  Creates the nested `<entity>` element.
  `Path`
  `createCatalogPath()`
  Creates a nested `<catalogpath>` element.
  `Path`
  `createClasspath()`
  Allows nested classpath elements.
  `protected void`
  `dieOnCircularReference(Stack<Object> stk, Project p)`
  Check to see whether any DataType we hold references to is included in the Stack (which holds all DataType instances that directly or indirectly reference this instance, including this instance itself).
  `Path`
  `getCatalogPath()`
  Returns the catalog path in which to attempt to resolve DTDs.
  `Source`
  `resolve(String href, String base)`
  Implements the URIResolver.resolve() interface method.
  `InputSource`
  `resolveEntity(String publicId, String systemId)`
  Implements the EntityResolver.resolveEntity() interface method.
  `void`
  `setCatalogPathRef(Reference r)`
  Allows catalogpath reference.
  `void`
  `setClasspath(Path classpath)`
  Allows simple classpath string.
  `void`
  `setClasspathRef(Reference r)`
  Allows classpath reference.
  `void`
  `setRefid(Reference r)`
  Makes this instance in effect a reference to another XMLCatalog instance.

  ### Methods inherited from class org.apache.tools.ant.types.DataType

  `checkAttributesAllowed, checkChildrenAllowed, circularReference, clone, dieOnCircularReference, dieOnCircularReference, getCheckedRef, getCheckedRef, getCheckedRef, getCheckedRef, getCheckedRef, getDataTypeName, getRefid, invokeCircularReferenceCheck, isChecked, isReference, noChildrenAllowed, pushAndInvokeCircularReferenceCheck, setChecked, tooManyAttributes, toString`

  ### Methods inherited from class org.apache.tools.ant.ProjectComponent

  `getDescription, getLocation, getProject, log, log, setDescription, setLocation, setProject`

  ### Methods inherited from class java.lang.Object

  `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### 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.
    See Also:
      - Constant Field Values

  - ### CATALOG_RESOLVER

    public static final String CATALOG_RESOLVER
    Resolver base class
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### XMLCatalog

    public XMLCatalog()
    Default constructor

- ## Method Details

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

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

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

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

  - ### getCatalogPath

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

  - ### addDTD

    public void addDTD(ResourceLocation dtd) throws BuildException
    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) throws BuildException
    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.

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

  - ### setRefid

    public void setRefid(Reference r) throws BuildException
    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.

    Overrides:
      `setRefid` in class `DataType`
    Parameters:
      `r` - the reference to which this catalog instance is associated
    Throws:
      `BuildException` - if this instance already has been configured.

  - ### resolveEntity

    public InputSource resolveEntity(String publicId, String systemId) throws SAXException, IOException
    Implements the EntityResolver.resolveEntity() interface method.
    Specified by:
      `resolveEntity` in interface `EntityResolver`
    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:
      - `EntityResolver.resolveEntity(java.lang.String, java.lang.String)`

  - ### resolve

    public Source resolve(String href, String base) throws TransformerException
    Implements the URIResolver.resolve() interface method.
    Specified by:
      `resolve` in interface `URIResolver`
    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:
      - `URIResolver.resolve(java.lang.String, java.lang.String)`

  - ### dieOnCircularReference

    protected void dieOnCircularReference(Stack<Object> stk, Project p) throws BuildException
    Description copied from class: `DataType`
    Check to see whether any DataType we hold references to is included in the Stack (which holds all DataType instances that directly or indirectly reference this instance, including this instance itself).

    If one is included, throw a BuildException created by `circularReference`.

    This implementation is appropriate only for a DataType that cannot hold other DataTypes as children.

    The general contract of this method is that it shouldn't do anything if `DataType.checked` is true and set it to true on exit.

    Overrides:
      `dieOnCircularReference` in class `DataType`
    Parameters:
      `stk` - the stack of references to check.
      `p` - the project to use to dereference the references.
    Throws:
      `BuildException` - on error.