| 
 | ||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
  |
  +--org.apache.tools.ant.ProjectComponent
        |
        +--org.apache.tools.ant.types.DataType
              |
              +--org.apache.tools.ant.types.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 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:
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 java.lang.String | APACHE_RESOLVERThe name of the bridge to the Apache xml-commons resolver class, used to determine whether resolver.jar is present in the classpath. | 
| static java.lang.String | CATALOG_RESOLVERResolver base class | 
| 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()Default constructor | |
| Method Summary | |
|  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. | 
|  Path | getCatalogPath()Returns the catalog path in which to attempt to resolve DTDs. | 
|  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 | 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, dieOnCircularReference, getCheckedRef, getDescription, getRefid, isChecked, isReference, noChildrenAllowed, setChecked, 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 | 
| Field Detail | 
public static final java.lang.String APACHE_RESOLVER
public static final java.lang.String CATALOG_RESOLVER
| Constructor Detail | 
public XMLCatalog()
| Method Detail | 
public Path createClasspath()
public void setClasspath(Path classpath)
classpath - the classpath to use to look up entities.public void setClasspathRef(Reference r)
r - an Ant reference containing a classpath.public Path createCatalogPath()
<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.
BuildException - if this is a reference and no nested elements are allowed.public void setCatalogPathRef(Reference r)
r - an Ant reference containing a classpath to be used as
 the catalog path.public Path getCatalogPath()
public void addDTD(ResourceLocation dtd)
            throws BuildException
<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.
dtd - the information about the PUBLIC resource mapping to
            be added to the catalog
BuildException - if this is a reference and no nested
       elements are allowed.
public void addEntity(ResourceLocation entity)
               throws BuildException
<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.
entity - the information about the URI resource mapping to be
       added to the catalog.
BuildException - if this is a reference and no nested
       elements are allowed.public void addConfiguredXMLCatalog(XMLCatalog catalog)
<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.
catalog - Nested XMLCatalog
public void setRefid(Reference r)
              throws BuildException
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.
setRefid in class DataTyper - the reference to which this catalog instance is associated
BuildException - if this instance already has been configured.
public org.xml.sax.InputSource resolveEntity(java.lang.String publicId,
                                             java.lang.String systemId)
                                      throws org.xml.sax.SAXException,
                                             java.io.IOException
resolveEntity in interface org.xml.sax.EntityResolverorg.xml.sax.SAXException
java.io.IOExceptionEntityResolver.resolveEntity(java.lang.String, java.lang.String)
public javax.xml.transform.Source resolve(java.lang.String href,
                                          java.lang.String base)
                                   throws javax.xml.transform.TransformerException
resolve in interface javax.xml.transform.URIResolverjavax.xml.transform.TransformerExceptionURIResolver.resolve(java.lang.String, java.lang.String)| 
 | ||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||