public class

XMLCatalogResolver

extends Object
implements XMLEntityResolver LSResourceResolver EntityResolver2
java.lang.Object
   ↳ org.apache.xerces.util.XMLCatalogResolver

Class Overview

The catalog resolver handles the resolution of external identifiers and URI references through XML catalogs. This component supports XML catalogs defined by the OASIS XML Catalogs Specification. It encapsulates the XML Commons resolver. An instance of this class may be registered on the parser as a SAX entity resolver, as a DOM LSResourceResolver or as an XNI entity resolver by setting the property (http://apache.org/xml/properties/internal/entity-resolver).

It is intended that this class may be used standalone to perform catalog resolution outside of a parsing context. It may be shared between several parsers and the application.

Summary

Public Constructors
XMLCatalogResolver()

Constructs a catalog resolver with a default configuration.

XMLCatalogResolver(String[] catalogs)

Constructs a catalog resolver with the given list of entry files.

XMLCatalogResolver(String[] catalogs, boolean preferPublic)

Constructs a catalog resolver with the given list of entry files and the preference for whether system or public matches are preferred.

Public Methods
synchronized final void clear()

Forces the cache of catalog mappings to be cleared.

synchronized final String[] getCatalogList()

Returns the initial list of catalog entry files.

InputSource getExternalSubset(String name, String baseURI)

Locates an external subset for documents which do not explicitly provide one.

final boolean getPreferPublic()

Returns the preference for whether system or public matches are preferred.

final boolean getUseLiteralSystemId()

Returns the preference for whether the literal system identifier should be used when resolving system identifiers when both it and the expanded system identifier are available.

InputSource resolveEntity(String publicId, String systemId)

Resolves an external entity.

XMLInputSource resolveEntity(XMLResourceIdentifier resourceIdentifier)

Resolves an external entity.

InputSource resolveEntity(String name, String publicId, String baseURI, String systemId)

Resolves an external entity.

String resolveIdentifier(XMLResourceIdentifier resourceIdentifier)

Resolves an identifier using the catalog.

synchronized final String resolvePublic(String publicId, String systemId)

Returns the URI mapping in the catalog for the given external identifier or null if no mapping exists.

LSInput resolveResource(String type, String namespaceURI, String publicId, String systemId, String baseURI)

Resolves a resource using the catalog.

synchronized final String resolveSystem(String systemId)

Returns the URI mapping in the catalog for the given external identifier or null if no mapping exists.

synchronized final String resolveURI(String uri)

Returns the URI mapping in the catalog for the given URI reference or null if no mapping exists.

synchronized final void setCatalogList(String[] catalogs)

Sets the initial list of catalog entry files.

final void setPreferPublic(boolean preferPublic)

Sets the preference for whether system or public matches are preferred.

final void setUseLiteralSystemId(boolean useLiteralSystemId)

Sets the preference for whether the literal system identifier should be used when resolving system identifiers when both it and the expanded system identifier are available.

[Expand]
Inherited Methods
From class java.lang.Object
From interface org.apache.xerces.xni.parser.XMLEntityResolver
From interface org.w3c.dom.ls.LSResourceResolver
From interface org.xml.sax.EntityResolver
From interface org.xml.sax.ext.EntityResolver2

Public Constructors

public XMLCatalogResolver ()

Constructs a catalog resolver with a default configuration.

public XMLCatalogResolver (String[] catalogs)

Constructs a catalog resolver with the given list of entry files.

Parameters
catalogs an ordered array list of absolute URIs

public XMLCatalogResolver (String[] catalogs, boolean preferPublic)

Constructs a catalog resolver with the given list of entry files and the preference for whether system or public matches are preferred.

Parameters
catalogs an ordered array list of absolute URIs
preferPublic the prefer public setting

Public Methods

public final synchronized void clear ()

Forces the cache of catalog mappings to be cleared.

public final synchronized String[] getCatalogList ()

Returns the initial list of catalog entry files.

Returns
  • the initial list of catalog entry files

public InputSource getExternalSubset (String name, String baseURI)

Locates an external subset for documents which do not explicitly provide one. This method always returns null. It should be overrided if other behaviour is required.

Parameters
name the identifier of the document root element
baseURI the document's base URI
Throws
SAXException any SAX exception, possibly wrapping another exception
IOException thrown if some i/o error occurs

public final boolean getPreferPublic ()

Returns the preference for whether system or public matches are preferred. This is used in the absence of any occurence of the prefer attribute on the catalog entry of a catalog. If this property has not yet been explicitly set its value is true.

Returns
  • the prefer public setting

public final boolean getUseLiteralSystemId ()

Returns the preference for whether the literal system identifier should be used when resolving system identifiers when both it and the expanded system identifier are available. If this property has not yet been explicitly set its value is true.

Returns
  • the preference for using literal system identifers for catalog resolution
See Also

public InputSource resolveEntity (String publicId, String systemId)

Resolves an external entity. If the entity cannot be resolved, this method should return null. This method returns an input source if an entry was found in the catalog for the given external identifier. It should be overrided if other behaviour is required.

Parameters
publicId the public identifier, or null if none was supplied
systemId the system identifier
Throws
SAXException any SAX exception, possibly wrapping another exception
IOException thrown if some i/o error occurs

public XMLInputSource resolveEntity (XMLResourceIdentifier resourceIdentifier)

Resolves an external entity. If the entity cannot be resolved, this method should return null. This method only calls resolveIdentifier and returns an input source if an entry was found in the catalog. It should be overrided if other behaviour is required.

Parameters
resourceIdentifier location of the XML resource to resolve
Throws
XNIException thrown on general error
IOException thrown if some i/o error occurs

public InputSource resolveEntity (String name, String publicId, String baseURI, String systemId)

Resolves an external entity. If the entity cannot be resolved, this method should return null. This method returns an input source if an entry was found in the catalog for the given external identifier. It should be overrided if other behaviour is required.

Parameters
name the identifier of the external entity
publicId the public identifier, or null if none was supplied
baseURI the URI with respect to which relative systemIDs are interpreted.
systemId the system identifier
Throws
SAXException any SAX exception, possibly wrapping another exception
IOException thrown if some i/o error occurs

public String resolveIdentifier (XMLResourceIdentifier resourceIdentifier)

Resolves an identifier using the catalog. This method interprets that the namespace of the identifier corresponds to uri entries in the catalog. Where both a namespace and an external identifier exist, the namespace takes precedence.

Parameters
resourceIdentifier the identifier to resolve
Throws
XNIException thrown on general error
IOException thrown if some i/o error occurs

public final synchronized String resolvePublic (String publicId, String systemId)

Returns the URI mapping in the catalog for the given external identifier or null if no mapping exists. Public identifiers are normalized before comparison.

Parameters
publicId the public identifier to locate in the catalog
systemId the system identifier to locate in the catalog
Returns
  • the mapped URI or null if no mapping was found in the catalog
Throws
IOException if an i/o error occurred while reading the catalog

public LSInput resolveResource (String type, String namespaceURI, String publicId, String systemId, String baseURI)

Resolves a resource using the catalog. This method interprets that the namespace URI corresponds to uri entries in the catalog. Where both a namespace and an external identifier exist, the namespace takes precedence.

Parameters
type the type of the resource being resolved
namespaceURI the namespace of the resource being resolved, or null if none was supplied
publicId the public identifier of the resource being resolved, or null if none was supplied
systemId the system identifier of the resource being resolved, or null if none was supplied
baseURI the absolute base URI of the resource being parsed, or null if there is no base URI

public final synchronized String resolveSystem (String systemId)

Returns the URI mapping in the catalog for the given external identifier or null if no mapping exists. If the system identifier is an URN in the publicid namespace it is converted into a public identifier by URN "unwrapping" as specified in the XML Catalogs specification.

Parameters
systemId the system identifier to locate in the catalog
Returns
  • the mapped URI or null if no mapping was found in the catalog
Throws
IOException if an i/o error occurred while reading the catalog

public final synchronized String resolveURI (String uri)

Returns the URI mapping in the catalog for the given URI reference or null if no mapping exists. URI comparison is case sensitive. If the URI reference is an URN in the publicid namespace it is converted into a public identifier by URN "unwrapping" as specified in the XML Catalogs specification and then resolution is performed following the semantics of external identifier resolution.

Parameters
uri the URI to locate in the catalog
Returns
  • the mapped URI or null if no mapping was found in the catalog
Throws
IOException if an i/o error occurred while reading the catalog

public final synchronized void setCatalogList (String[] catalogs)

Sets the initial list of catalog entry files. If there were any catalog mappings cached from the previous list they will be replaced by catalog mappings from the new list the next time the catalog is queried.

Parameters
catalogs an ordered array list of absolute URIs

public final void setPreferPublic (boolean preferPublic)

Sets the preference for whether system or public matches are preferred. This is used in the absence of any occurence of the prefer attribute on the catalog entry of a catalog.

Parameters
preferPublic the prefer public setting

public final void setUseLiteralSystemId (boolean useLiteralSystemId)

Sets the preference for whether the literal system identifier should be used when resolving system identifiers when both it and the expanded system identifier are available.

The literal system identifier is the URI as it was provided before absolutization. It may be embedded within an entity. It may be provided externally or it may be the result of redirection. For example, redirection may have come from the protocol level through HTTP or from an application's entity resolver.

The expanded system identifier is an absolute URI which is the result of resolving the literal system identifier against a base URI.

Parameters
useLiteralSystemId the preference for using literal system identifers for catalog resolution