## org.apache.xerces.util
Class XMLCatalogResolver

    java.lang.Object
      org.apache.xerces.util.XMLCatalogResolver

All Implemented Interfaces:
  org.apache.xerces.xni.parser.XMLEntityResolver, org.w3c.dom.ls.LSResourceResolver, org.xml.sax.EntityResolver, org.xml.sax.ext.EntityResolver2

    public class XMLCatalogResolver

extends java.lang.Object
implements org.apache.xerces.xni.parser.XMLEntityResolver, org.xml.sax.ext.EntityResolver2, org.w3c.dom.ls.LSResourceResolver

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.

Version:
  $Id: XMLCatalogResolver.java 447241 2006-09-18 05:12:57Z mrglavas $
Author:
  Michael Glavassevich, IBM

Constructor Summary
`XMLCatalogResolver()` Constructs a catalog resolver with a default configuration.
`XMLCatalogResolver(java.lang.String[] catalogs)` Constructs a catalog resolver with the given list of entry files.
`XMLCatalogResolver(java.lang.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.

Method Summary
`void` `clear()` Forces the cache of catalog mappings to be cleared.
`java.lang.String[]` `getCatalogList()` Returns the initial list of catalog entry files.
`org.xml.sax.InputSource` `getExternalSubset(java.lang.String name, java.lang.String baseURI)` Locates an external subset for documents which do not explicitly provide one.
`boolean` `getPreferPublic()` Returns the preference for whether system or public matches are preferred.
`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.
`org.xml.sax.InputSource` `resolveEntity(java.lang.String publicId, java.lang.String systemId)` Resolves an external entity.
`org.xml.sax.InputSource` `resolveEntity(java.lang.String name, java.lang.String publicId, java.lang.String baseURI, java.lang.String systemId)` Resolves an external entity.
`org.apache.xerces.xni.parser.XMLInputSource` `resolveEntity(org.apache.xerces.xni.XMLResourceIdentifier resourceIdentifier)` Resolves an external entity.
`java.lang.String` `resolveIdentifier(org.apache.xerces.xni.XMLResourceIdentifier resourceIdentifier)` Resolves an identifier using the catalog.
`java.lang.String` `resolvePublic(java.lang.String publicId, java.lang.String systemId)` Returns the URI mapping in the catalog for the given external identifier or `null` if no mapping exists.
`org.w3c.dom.ls.LSInput` `resolveResource(java.lang.String type, java.lang.String namespaceURI, java.lang.String publicId, java.lang.String systemId, java.lang.String baseURI)` Resolves a resource using the catalog.
`java.lang.String` `resolveSystem(java.lang.String systemId)` Returns the URI mapping in the catalog for the given external identifier or `null` if no mapping exists.
`java.lang.String` `resolveURI(java.lang.String uri)` Returns the URI mapping in the catalog for the given URI reference or `null` if no mapping exists.
`void` `setCatalogList(java.lang.String[] catalogs)` Sets the initial list of catalog entry files.
`void` `setPreferPublic(boolean preferPublic)` Sets the preference for whether system or public matches are preferred.
`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.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### XMLCatalogResolver

    public XMLCatalogResolver()

  Constructs a catalog resolver with a default configuration.

### XMLCatalogResolver

    public XMLCatalogResolver(java.lang.String[] catalogs)

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

  Parameters:
    `catalogs` - an ordered array list of absolute URIs

### XMLCatalogResolver

    public XMLCatalogResolver(java.lang.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

Method Detail

### getCatalogList

    public final java.lang.String[] getCatalogList()

  Returns the initial list of catalog entry files.

  Returns:
    the initial list of catalog entry files

### setCatalogList

    public final void setCatalogList(java.lang.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

### clear

    public final void clear()

  Forces the cache of catalog mappings to be cleared.

### getPreferPublic

    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

### setPreferPublic

    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

### getUseLiteralSystemId

    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:
    `setUseLiteralSystemId(boolean)`

### setUseLiteralSystemId

    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

### resolveEntity

    public org.xml.sax.InputSource resolveEntity(java.lang.String publicId,
                                                 java.lang.String systemId)
                                          throws org.xml.sax.SAXException,
                                                 java.io.IOException

  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.

  Specified by:
    `resolveEntity` in interface `org.xml.sax.EntityResolver`
  Parameters:
    `publicId` - the public identifier, or `null` if none was supplied
    `systemId` - the system identifier
  Returns:
    An InputSource object describing the new input source, or null to request that the parser open a regular URI connection to the system identifier.
  Throws:
    `org.xml.sax.SAXException` - any SAX exception, possibly wrapping another exception
    `java.io.IOException` - thrown if some i/o error occurs
  See Also:
    `InputSource`

### resolveEntity

    public org.xml.sax.InputSource resolveEntity(java.lang.String name,
                                                 java.lang.String publicId,
                                                 java.lang.String baseURI,
                                                 java.lang.String systemId)
                                          throws org.xml.sax.SAXException,
                                                 java.io.IOException

  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.

  Specified by:
    `resolveEntity` in interface `org.xml.sax.ext.EntityResolver2`
  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
  Returns:
    An InputSource object describing the new input source to be used by the parser. Returning null directs the parser to resolve the system ID against the base URI and open a connection to resulting URI.
  Throws:
    `org.xml.sax.SAXException` - any SAX exception, possibly wrapping another exception
    `java.io.IOException` - thrown if some i/o error occurs

### getExternalSubset

    public org.xml.sax.InputSource getExternalSubset(java.lang.String name,
                                                     java.lang.String baseURI)
                                              throws org.xml.sax.SAXException,
                                                     java.io.IOException

  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.

  Specified by:
    `getExternalSubset` in interface `org.xml.sax.ext.EntityResolver2`
  Parameters:
    `name` - the identifier of the document root element
    `baseURI` - the document's base URI
  Returns:
    An InputSource object describing the new external subset to be used by the parser, or null to indicate that no external subset is provided.
  Throws:
    `org.xml.sax.SAXException` - any SAX exception, possibly wrapping another exception
    `java.io.IOException` - thrown if some i/o error occurs

### resolveResource

    public org.w3c.dom.ls.LSInput resolveResource(java.lang.String type,
                                                  java.lang.String namespaceURI,
                                                  java.lang.String publicId,
                                                  java.lang.String systemId,
                                                  java.lang.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.

  Specified by:
    `resolveResource` in interface `org.w3c.dom.ls.LSResourceResolver`
  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
  Returns:
    A `LSInput` object describing the new input source, or `null` to request that the parser open a regular URI connection to the resource.

### resolveEntity

    public org.apache.xerces.xni.parser.XMLInputSource resolveEntity(org.apache.xerces.xni.XMLResourceIdentifier resourceIdentifier)
                                                              throws org.apache.xerces.xni.XNIException,
                                                                     java.io.IOException

  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.

  Specified by:
    `resolveEntity` in interface `org.apache.xerces.xni.parser.XMLEntityResolver`
  Parameters:
    `resourceIdentifier` - location of the XML resource to resolve
  Throws:
    `org.apache.xerces.xni.XNIException` - thrown on general error
    `java.io.IOException` - thrown if some i/o error occurs
  See Also:
    `XMLResourceIdentifier`

### resolveIdentifier

    public java.lang.String resolveIdentifier(org.apache.xerces.xni.XMLResourceIdentifier resourceIdentifier)
                                       throws java.io.IOException,
                                              org.apache.xerces.xni.XNIException

  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:
    `org.apache.xerces.xni.XNIException` - thrown on general error
    `java.io.IOException` - thrown if some i/o error occurs

### resolveSystem

    public final java.lang.String resolveSystem(java.lang.String systemId)
                                         throws java.io.IOException

  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:
    `java.io.IOException` - if an i/o error occurred while reading the catalog

### resolvePublic

    public final java.lang.String resolvePublic(java.lang.String publicId,
                                                java.lang.String systemId)
                                         throws java.io.IOException

  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:
    `java.io.IOException` - if an i/o error occurred while reading the catalog

### resolveURI

    public final java.lang.String resolveURI(java.lang.String uri)
                                      throws java.io.IOException

  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:
    `java.io.IOException` - if an i/o error occurred while reading the catalog

Copyright © 1999-2006 The Apache Software Foundation. All Rights Reserved.