org.apache.tools.ant.types
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:
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 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 String | CATALOG_RESOLVER
Resolver base class |
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.
|
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.
|
<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
<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.
<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.
<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.
Returns: a Path instance to be configured.
Returns: the catalog path
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
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
Parameters: r an Ant reference containing a classpath to be used as the catalog path.
Parameters: classpath the classpath to use to look up entities.
Parameters: r an Ant reference containing a classpath.
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.