org.apache.avalon.excalibur.catalog
Class CatalogEntityResolver

java.lang.Object
  |
  +--org.apache.avalon.excalibur.catalog.CatalogEntityResolver

All Implemented Interfaces:

org.xml.sax.EntityResolver

public class CatalogEntityResolver

extends java.lang.Object

implements org.xml.sax.EntityResolver

Implements SAX entityResolver using OASIS Open Catalogs.

This class implements the SAX entityResolver interface. It uses OASIS Open catalog files to provide a facility for mapping public or system identifiers in source documents to local system identifiers.

This code interrogates the following non-standard system properties:

xml.catalog.debug

Sets the debug level. A value of 0 is assumed if the property is not set or is not a number.

Version:

1.0

Author:

Arbortext, Inc., Norman Walsh

See Also:

Catalog

Field Summary

Catalog	catalog The OASIS Open Catalog used for entity resolution.
int	debug The debug level

Constructor Summary

CatalogEntityResolver()
Constructs a CatalogEntityResolver with an empty catalog.

Method Summary

void	parseCatalog(java.lang.String fileName) Parse a Catalog file.
org.xml.sax.InputSource	resolveEntity(java.lang.String publicId, java.lang.String systemId) Implements the resolveEntity method for the SAX interface.
void	setCatalog(Catalog cat) Set the Catalog that will be used to resolve entities.
void	setRetry(boolean retry) Establish whether or not bad system identifiers should be ignored.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

debug

public int debug

The debug level

In general, higher numbers produce more information:

• 0, no messages
• 1, minimal messages (high-level status)
• 2, detailed messages

catalog

public Catalog catalog

The OASIS Open Catalog used for entity resolution.

This field is exposed so that the catalog can be updated after creating the instance of CatalogEntityResolver that will be used by the parser.

Constructor Detail

CatalogEntityResolver

public CatalogEntityResolver()

Constructs a CatalogEntityResolver with an empty catalog.

Method Detail

parseCatalog

public void parseCatalog(java.lang.String fileName)
                  throws java.net.MalformedURLException,
                         java.io.IOException

Parse a Catalog file.

This is really just a convenience method which calls catalog.parseCatalog() .

Parameters:

fileName - The filename of the catalog file to process

Throws:

java.net.MalformedURLException - The fileName cannot be turned into a valid URL.

java.io.IOException - Error reading catalog file.

resolveEntity

public org.xml.sax.InputSource resolveEntity(java.lang.String publicId,
                                             java.lang.String systemId)

Implements the resolveEntity method for the SAX interface.

Presented with an optional public identifier and a system identifier, this function attempts to locate a mapping in the catalogs.

If such a mapping is found, the resolver attempts to open the mapped value as an InputSource and return it. Exceptions are ignored and null is returned if the mapped value cannot be opened as an input source.

If no mapping is found (or an error occurs attempting to open the mapped value as an input source), null is returned and the system will use the specified system identifier as if no entityResolver was specified.

Specified by:

resolveEntity in interface org.xml.sax.EntityResolver

Parameters:

publicId - The public identifier for the entity in question. This may be null.

systemId - The system identifier for the entity in question. XML requires a system identifier on all external entities, so this value is always specified.

Returns:

An InputSource for the mapped identifier, or null.

setCatalog

public void setCatalog(Catalog cat)

Set the Catalog that will be used to resolve entities.

This is a convenience method for setting the catalog field.

Parameters:

cat - The new Catalog value

setRetry

public void setRetry(boolean retry)

Establish whether or not bad system identifiers should be ignored.

The semantics of catalog file lookup are such that if a system identifier is supplied in the instance document, it is possible that it will be used in preference to alternative system identifiers in the catalog.

If this variable is true and the system identifier passed to the entity resolver would be returned, the entity resolver attempts to open it. If it cannot be opened, the resolver does another catalog search, ignoring the fact that a system identifier was specified. If this second search locates a system identifer, it will be returned.

This setting is initially false meaning that system identifiers in the document will be used in preference to some entries in the catalog.

Parameters:

retry - If true, the resolver will retry Catalog lookups when the supplied system identifer cannot be opened.