A Catalog Resolver that implements SAX
EntityResolver,
StAX
XMLResolver,
DOM LS
LSResourceResolver used by Schema Validation, and
Transform
URIResolver, and resolves
external references using catalogs.
The
Catalog Standard distinguished external identifiers from uri entries
as being used to solely identify DTDs, while uri entries for
other resources such as stylesheets and schema. The Java APIs, such as
XMLResolver and LSResourceResolver
however, make no such distinction.
In consistent with the existing Java API, this CatalogResolver recognizes a
system identifier as a URI and will search both system and uri
entries in a catalog in order to find a matching entry.
The search is started in the current catalog. If a match is found,
no further attempt will be made. Only if there is no match in the current
catalog, will alternate catalogs including delegate and next catalogs be considered.
Search Order
The resolver will first search the system-type of entries with the specified
systemId. The system entries include
system,
rewriteSystem and
systemSuffix entries.
If no match is found, public entries may be searched in accordance with
the prefer attribute.
The prefer attribute: if the prefer is public,
and there is no match found through the system entries, public entries
will be considered. If it is not specified, the prefer is public
by default (Note that by the OASIS standard, system entries will always
be considered before public entries. Prefer public means that public entries
will be matched when both system and public identifiers are specified.
In general therefore, prefer public is recommended.)
If no match is found with the systemId and public identifier,
the resolver will continue searching uri entries
with the specified systemId or href. The uri entries
include uri, rewriteURI, and uriSuffix entries.
Error Handling
The interfaces that the CatalogResolver extend specified checked exceptions, including:
The CatalogResolver however, will throw CatalogException
only when javax.xml.catalog.resolve is specified as strict.
For applications that expect to handle the checked Exceptions, it may be
necessary to use a custom resolver to wrap the CatalogResolver or implement it
with a Catalog object.
Implements
EntityResolver. The method searches through
the catalog entries in the main and alternative catalogs to attempt to find
a match with the specified
publicId or systemId.
Specified by:
Parameters:
publicId - the public identifier of the external entity being
referenced, or null if none was supplied
systemId - the system identifier of the external entity being
referenced. A system identifier is required on all external entities. XML
requires a system identifier on all external entities, so this value is
always specified.
Returns:
a
InputSource object if a mapping is found.
If no mapping is found, returns a
InputSource object
containing an empty
Reader if the
javax.xml.catalog.resolve property is set to
ignore;
returns null if the
javax.xml.catalog.resolve property is set to
continue.
Throws:
CatalogException - if no mapping is found and
javax.xml.catalog.resolve is specified as
strict See Also:
Implements URIResolver. The method searches through the catalog entries
in the main and alternative catalogs to attempt to find a match
with the specified
href attribute. The
href attribute will
be used literally, with no attempt to be made absolute to the
base.
If the value is a URN, the href attribute is recognized as a
publicId, and used to search public entries.
If the value is a URI, it is taken as a systemId, and used to
search both system and uri entries.
Specified by:
Parameters:
href - the href attribute that specifies the URI of a style sheet,
which may be relative or absolute
base - The base URI against which the href attribute will be made
absolute if the absolute URI is required
Returns:
a
Source object if a mapping is found.
If no mapping is found, returns an empty
Source
object if the
javax.xml.catalog.resolve property is set to
ignore;
returns a
Source object with the original URI
(href, or href resolved with base if base is not null) if the
javax.xml.catalog.resolve property is set to
continue.
Throws:
CatalogException - if no mapping is found and
javax.xml.catalog.resolve is specified as
strict
Implements
XMLResolver. For the purpose of resolving
publicId and
systemId, this method is equivalent to
resolveEntity(java.lang.String, java.lang.String).
The systemId will be used literally, with no attempt to be made
absolute to the baseUri. The baseUri and namespace
are not used in the search for a match in a catalog. However, a relative
systemId in an xml source may have been made absolute by the parser
with the baseURI, thus making it unable to find a system entry.
In such a case, a systemSuffix entry is recommended over a
system entry.
Specified by:
Parameters:
publicId - the public identifier of the external entity being
referenced, or null if none was supplied
systemId - the system identifier of the external entity being
referenced. A system identifier is required on all external entities. XML
requires a system identifier on all external entities, so this value is
always specified.
baseUri - the absolute base URI, not used by the CatalogResolver
namespace - the namespace of the entity to resolve, not used by the
CatalogResolver.
Returns:
an
InputStream object if a mapping is found; null
if no mapping is found and the
javax.xml.catalog.resolve property
is set to
continue or
ignore. Note that for XMLResolver,
it is not possible to ignore a reference,
ignore is therefore
treated the same as
continue.
Throws:
CatalogException - if no mapping is found and
javax.xml.catalog.resolve is specified as
strict
Implements
LSResourceResolver. For the purpose of
resolving
publicId and
systemId, this method is equivalent
to
resolveEntity(java.lang.String, java.lang.String).
The systemId will be used literally, with no attempt to be made
absolute to the baseUri. The baseUri, namespaceUri
and type are not used in the search for a match in a catalog.
However, a relative systemId in a source may have been made absolute
by the parser with the baseURI, thus making it unable to find a
system entry. In such a case, a systemSuffix entry is
recommended over a system entry.
Specified by:
Parameters:
type - the type of the resource being resolved,
not used by the CatalogResolver
namespaceUri - the namespace of the resource being resolved,
not used by the CatalogResolver
publicId - the public identifier of the external entity being
referenced, or null if no public identifier was
supplied or if the resource is not an entity.
systemId - the system identifier, a URI reference of the
external resource being referenced
baseUri - the absolute base URI, not used by the CatalogResolver
Returns:
a
LSInput object if a mapping is found; null
if no mapping is found and the
javax.xml.catalog.resolve property
is set to
continue or
ignore. Note that for
LSResourceResolver, it is not possible to ignore a
reference,
ignore is therefore treated the same as
continue.
Throws:
CatalogException - if no mapping is found and
javax.xml.catalog.resolve is specified as
strict