Class XMLCatalog
- All Implemented Interfaces:
Cloneable
,URIResolver
,EntityResolver
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.
-
Field Summary
Modifier and TypeFieldDescriptionstatic final String
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
Resolver base classFields inherited from class org.apache.tools.ant.ProjectComponent
description, location, project
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
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.Creates a nested<catalogpath>
element.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).Returns the catalog path in which to attempt to resolve DTDs.Implements the URIResolver.resolve() interface method.resolveEntity
(String publicId, String systemId) Implements the EntityResolver.resolveEntity() interface method.void
Allows catalogpath reference.void
setClasspath
(Path classpath) Allows simple classpath string.void
Allows classpath reference.void
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
-
Field Details
-
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:
-
CATALOG_RESOLVER
Resolver base class- See Also:
-
-
Constructor Details
-
XMLCatalog
public XMLCatalog()Default constructor
-
-
Method Details
-
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
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
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
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
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
Returns the catalog path in which to attempt to resolve DTDs.- Returns:
- the catalog path
-
addDTD
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
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
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
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 classDataType
- Parameters:
r
- the reference to which this catalog instance is associated- Throws:
BuildException
- if this instance already has been configured.
-
resolveEntity
Implements the EntityResolver.resolveEntity() interface method.- Specified by:
resolveEntity
in interfaceEntityResolver
- 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:
-
resolve
Implements the URIResolver.resolve() interface method.- Specified by:
resolve
in interfaceURIResolver
- 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:
-
dieOnCircularReference
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 classDataType
- Parameters:
stk
- the stack of references to check.p
- the project to use to dereference the references.- Throws:
BuildException
- on error.
-