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:
- In the local filesystem
- In the classpath
- Using the Apache xml-commons resolver (if it is available)
- 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.
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.
catalog
- Nested XMLCatalog
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.
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.
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.
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.
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.
- a path to be configured as the catalog path.
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.
- a Path instance to be configured.
getCatalogPath
public Path getCatalogPath()
Returns the catalog path in which to attempt to resolve DTDs.
- the catalog path
resolve
public Source resolve(String href,
String base)
throws TransformerException
Implements the URIResolver.resolve() interface method.
javax.xml.transform.URIResolver.resolve
resolveEntity
public InputSource resolveEntity(String publicId,
String systemId)
throws SAXException,
IOException
Implements the EntityResolver.resolveEntity() interface method.
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.
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.
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.
r
- an Ant reference containing a classpath.
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.
- setRefid in interface DataType
r
- the reference to which this catalog instance is associated
BuildException
- if this instance already has been configured.