## 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:
  java.lang.Cloneable, org.xml.sax.EntityResolver, javax.xml.transform.URIResolver

public class XMLCatalog
extends DataType
implements java.lang.Cloneable, org.xml.sax.EntityResolver, javax.xml.transform.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.

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" />
</xmlcatalog>
`

The object implemention `sometask` 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. 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, and external catalog files using the xml-commons resolver library

Version:
  $Id: XMLCatalog.java,v 1.9.2.8 2003/02/10 14:25:22 bodewig Exp $
Author:
  dIon Gillard, Erik Hatcher, Craeg Strong

Field Summary

Fields inherited from class org.apache.tools.ant.types.DataType
`checked, description, ref`

Fields inherited from class org.apache.tools.ant.ProjectComponent
`project`

Constructor Summary
`XMLCatalog()`

Method Summary
`void` `addConfiguredXMLCatalog(XMLCatalog catalog)` Loads a nested `<xmlcatalog>` into our definition.
`void` `addDTD(DTDLocation dtd)` Creates the nested `<dtd>` element.
`void` `addEntity(DTDLocation dtd)` Creates the nested `<entity>` element.
`Path` `createClasspath()` Allows nested classpath elements.
`javax.xml.transform.Source` `resolve(java.lang.String href, java.lang.String base)` Implements the URIResolver.resolve() interface method.
`org.xml.sax.InputSource` `resolveEntity(java.lang.String publicId, java.lang.String systemId)` Implements the EntityResolver.resolveEntity() interface method.
`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
`circularReference, dieOnCircularReference, getCheckedRef, getDescription, isReference, noChildrenAllowed, setDescription, tooManyAttributes`

Methods inherited from class org.apache.tools.ant.ProjectComponent
`getProject, log, log, setProject`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### XMLCatalog

    public XMLCatalog()

Method Detail

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

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

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

### addDTD

    public void addDTD(DTDLocation 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(DTDLocation dtd)
                   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:
    `dtd` - 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 org.xml.sax.InputSource resolveEntity(java.lang.String publicId,
                                                 java.lang.String systemId)
                                          throws org.xml.sax.SAXException,
                                                 java.io.IOException

  Implements the EntityResolver.resolveEntity() interface method.

  Specified by:
    `resolveEntity` in interface `org.xml.sax.EntityResolver`
  Throws:
    `org.xml.sax.SAXException`
    `java.io.IOException`
  See Also:
    `EntityResolver.resolveEntity(java.lang.String, java.lang.String)`

### resolve

    public javax.xml.transform.Source resolve(java.lang.String href,
                                              java.lang.String base)
                                       throws javax.xml.transform.TransformerException

  Implements the URIResolver.resolve() interface method.

  Specified by:
    `resolve` in interface `javax.xml.transform.URIResolver`
  Throws:
    `javax.xml.transform.TransformerException`
  See Also:
    `URIResolver.resolve(java.lang.String, java.lang.String)`

Copyright © 2000-2003 Apache Software Foundation. All Rights Reserved.