Interface CatalogResolver
- All Superinterfaces:
-
EntityResolver
,LSResourceResolver
,URIResolver
,XMLResolver
public interface CatalogResolver extends EntityResolver, XMLResolver, URIResolver, LSResourceResolver
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 specifiedsystemId
. 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:-
SAXException
andIOException
byEntityResolver.resolveEntity(java.lang.String, java.lang.String)
-
XMLStreamException
byXMLResolver.resolveEntity(java.lang.String, java.lang.String, java.lang.String, java.lang.String)
-
TransformerException
byURIResolver.resolve(java.lang.String, java.lang.String)
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.
- Since:
- 9
Method Summary
Modifier and Type | Method | Description |
---|---|---|
Source | resolve(String href,
String base) | Implements URIResolver. |
InputSource | resolveEntity(String publicId,
String systemId) | Implements |
InputStream | resolveEntity(String publicId,
String systemId,
String baseUri,
String namespace) | Implements |
LSInput | resolveResource(String type,
String namespaceUri,
String publicId,
String systemId,
String baseUri) | Implements |
Method Detail
resolveEntity
InputSource resolveEntity(String publicId, String systemId)
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:
-
resolveEntity
in interfaceEntityResolver
- 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 aInputSource
object containing an emptyReader
if thejavax.xml.catalog.resolve
property is set toignore
; returns null if thejavax.xml.catalog.resolve
property is set tocontinue
. - Throws:
-
CatalogException
- if no mapping is found andjavax.xml.catalog.resolve
is specified asstrict
- See Also:
InputSource
resolve
Source resolve(String href, String base)
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:
-
resolve
in interfaceURIResolver
- 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 emptySource
object if thejavax.xml.catalog.resolve
property is set toignore
; returns aSource
object with the original URI (href, or href resolved with base if base is not null) if thejavax.xml.catalog.resolve
property is set tocontinue
. - Throws:
-
CatalogException
- if no mapping is found andjavax.xml.catalog.resolve
is specified asstrict
resolveEntity
InputStream resolveEntity(String publicId, String systemId, String baseUri, String namespace)
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:
-
resolveEntity
in interfaceXMLResolver
- 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 thejavax.xml.catalog.resolve
property is set tocontinue
orignore
. Note that for XMLResolver, it is not possible to ignore a reference,ignore
is therefore treated the same ascontinue
. - Throws:
-
CatalogException
- if no mapping is found andjavax.xml.catalog.resolve
is specified asstrict
resolveResource
LSInput resolveResource(String type, String namespaceUri, String publicId, String systemId, String baseUri)
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:
-
resolveResource
in interfaceLSResourceResolver
- 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, ornull
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 thejavax.xml.catalog.resolve
property is set tocontinue
orignore
. Note that forLSResourceResolver
, it is not possible to ignore a reference,ignore
is therefore treated the same ascontinue
. - Throws:
-
CatalogException
- if no mapping is found andjavax.xml.catalog.resolve
is specified asstrict