Module java.xml

Package javax.xml.catalog

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 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:

• SAXException and IOException by EntityResolver.resolveEntity(java.lang.String, java.lang.String)
• XMLStreamException by XMLResolver.resolveEntity(java.lang.String, java.lang.String, java.lang.String, java.lang.String)
• TransformerException by URIResolver.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

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static enum	CatalogResolver.NotFoundAction	Defines the actions that a CatalogResolver may take when it is unable to resolve an external reference.

Method Summary

Modifier and Type	Method	Description
Source	resolve(String href, String base)	Implements URIResolver.
InputSource	resolveEntity(String publicId, String systemId)	Implements EntityResolver.
InputStream	resolveEntity(String publicId, String systemId, String baseUri, String namespace)	Implements XMLResolver.
LSInput	resolveResource(String type, String namespaceUri, String publicId, String systemId, String baseUri)	Implements LSResourceResolver.

Method Details

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 interface EntityResolver

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:

• 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 interface URIResolver

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

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 interface XMLResolver

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

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 interface LSResourceResolver

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