org.apache.avalon.excalibur.catalog
Class Catalog

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

public class Catalog

extends java.lang.Object

Represents OASIS Open Catalog files.

This class loads one or more OASIS Open Catalog files (defined by OASIS Technical Resolution 9401:1997 (Amendment 2 to TR 9401) ) and provides methods for implementing the Catalog semantics.

The primary purpose of the Catalog is to associate resources in the document with local system identifiers. Some entities (document types, XML entities, and notations) have names and all of them can have either public or system identifiers or both. (In XML, only a notation can have a public identifier without a system identifier, but the methods implemented in this class obey the Catalog semantics from the SGML days when system identifiers were optional.)

The system identifiers returned by the resolution methods in this class are valid, i.e. usable by, and in fact constructed by, the java.net.URL class. Unfortunately, this class seems to behave in somewhat non-standard ways and the system identifiers returned may not be directly usable in a browser or filesystem context.

This class processes the following Catalog entries:

• BASE changes the base URI for resolving relative system identifiers. The initial base URI is the URI of the location of the catalog (which is, in turn, relative to the location of the current working directory at startup, as returned by the user.dir system property).
• CATALOG processes other catalog files. An included catalog occurs logically at the end of the including catalog.
• DELEGATE specifies alternate catalogs for some public identifiers. The delegated catalogs are not loaded until they are needed, but they are cached once loaded.
• DOCTYPE associates the names of root elements with URIs. (In other words, an XML processor might infer the doctype of an XML document that does not include a doctype declaration by looking for the DOCTYPE entry in the catalog which matches the name of the root element of the document.)
• DOCUMENT provides a default document.
• DTDDECL recognized and silently ignored. Not relevant for XML.
• ENTITY associates entity names with URIs.
• LINKTYPE recognized and silently ignored. Not relevant for XML.
• NOTATION associates notation names with URIs.
• OVERRIDE changes the override behavior. Initial behavior is set by the system property xml.catalog.override . The default initial behavior is 'YES', that is, entries in the catalog override system identifiers specified in the document.
• PUBLIC maps a public identifier to a system identifier.
• SGMLDECL recognized and silently ignored. Not relevant for XML.
• SYSTEM maps a system identifier to another system identifier.

Note that subordinate catalogs (all catalogs except the first, including CATALOG and DELEGATE catalogs) are only loaded if and when they are required.

If provided with an SAX Parser class, this object can also load XML Catalogs. For the details about which XML Catalog formats are recognized, see XMLCatalogReader.

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.

xml.catalog.override

Specifies the default override behavior. If override is true ("true", "yes", "1"), system identifiers in the catalog file are used in preference to system identifiers in the document. In other words, a value of false essentially disables catalog processing since almost all external entities are required to have a system identifier in XML. A value of true is assumed if the property is not set.

xml.catalog.files

Identifies the list of catalog files to parse initially. (Additional catalog files may be parsed if the CATALOG entry is used.) Components of the list should be separated by the system property " path.separator " character (typically ";" on DOS/Windows systems, ":" on Unix systems).

Additional catalogs may also be loaded with the parseCatalog(java.lang.String) method.

Change Log:

1.0.1

Fixed a bug in the calculation of the list of subordinate catalogs. This bug caused an infinite loop where parsing would alternately process two catalogs indefinitely.

Version:

1.0.1

Author:

Abortext, Inc., Norman Walsh

See Also:

CatalogReader, XMLCatalogReader, CatalogEntry

Field Summary

int	debug The debug level.

Constructor Summary

Catalog()
Constructs an empty Catalog.

Method Summary

void	loadSystemCatalogs() Load the system catalog files.
void	parseAllCatalogs() Parse all subordinate catalogs.
void	parseCatalog(java.lang.String fileName) Parse a catalog file, augmenting internal data structures
java.lang.String	resolveDoctype(java.lang.String entityName, java.lang.String publicId, java.lang.String systemId) Return the applicable DOCTYPE system identifier.
java.lang.String	resolveDocument() Return the applicable DOCUMENT entry.
java.lang.String	resolveEntity(java.lang.String entityName, java.lang.String publicId, java.lang.String systemId) Return the applicable ENTITY system identifier.
java.lang.String	resolveNotation(java.lang.String notationName, java.lang.String publicId, java.lang.String systemId) Return the applicable NOTATION system identifier.
java.lang.String	resolvePublic(java.lang.String publicId, java.lang.String systemId) Return the applicable PUBLIC or SYSTEM identifier.
java.lang.String	resolveSystem(java.lang.String systemId) Return the applicable SYSTEM system identifier
void	setParserClass(java.lang.String parser) Sets the parser class, enabling XML Catalog parsing.

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, more messages
• 3, detailed messages

Constructor Detail

Catalog

public Catalog()

Constructs an empty Catalog.

The constructor interrogates the relevant system properties and initializes the catalog data structures.

Method Detail

loadSystemCatalogs

public void loadSystemCatalogs()
                        throws java.net.MalformedURLException,
                               java.io.IOException

Load the system catalog files.

The method adds all of the catalogs specified in the xml.catalog.files property to the Catalog list.

Throws:

java.net.MalformedURLException - One of the system catalogs is identified with a filename that is not a valid URL.

java.io.IOException - One of the system catalogs cannot be read.

parseCatalog

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

Parse a catalog file, augmenting internal data structures

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.

parseAllCatalogs

public void parseAllCatalogs()
                      throws java.net.MalformedURLException,
                             java.io.IOException

Parse all subordinate catalogs.

This method recursively parses all of the subordinate catalogs. If this method does not throw an exception, you can be confident that no subsequent call to any resolve*() method will either, with two possible exceptions:

1. Delegated catalogs are re-parsed each time they are needed (because a variable list of them may be needed in each case, depending on the length of the matching partial public identifier).

   But they are parsed by this method, so as long as they don't change or disappear while the program is running, they shouldn't generate errors later if they don't generate errors now.

2. If you add new catalogs with parseCatalog , they won't be loaded until they are needed or until you call parseAllCatalogs again.

On the other hand, if you don't call this method, you may successfully parse documents without having to load all possible catalogs.

Throws:

java.net.MalformedURLException - The filename (URL) for a subordinate or delegated catalog is not a valid URL.

java.io.IOException - Error reading some subordinate or delegated catalog file.

resolveDoctype

public java.lang.String resolveDoctype(java.lang.String entityName,
                                       java.lang.String publicId,
                                       java.lang.String systemId)
                                throws java.net.MalformedURLException,
                                       java.io.IOException

Return the applicable DOCTYPE system identifier.

Parameters:

entityName - The name of the entity (element) for which a doctype is required.

publicId - The nominal public identifier for the doctype (as provided in the source document).

systemId - The nominal system identifier for the doctype (as provided in the source document).

Returns:

The system identifier to use for the doctype.

Throws:

java.net.MalformedURLException - The formal system identifier of a subordinate catalog cannot be turned into a valid URL.

java.io.IOException - Error reading subordinate catalog file.

resolveDocument

public java.lang.String resolveDocument()
                                 throws java.net.MalformedURLException,
                                        java.io.IOException

Return the applicable DOCUMENT entry.

Returns:

The system identifier to use for the doctype.

Throws:

java.net.MalformedURLException - The formal system identifier of a subordinate catalog cannot be turned into a valid URL.

java.io.IOException - Error reading subordinate catalog file.

resolveEntity

public java.lang.String resolveEntity(java.lang.String entityName,
                                      java.lang.String publicId,
                                      java.lang.String systemId)
                               throws java.net.MalformedURLException,
                                      java.io.IOException

Return the applicable ENTITY system identifier.

Parameters:

entityName - The name of the entity for which a system identifier is required.

publicId - The nominal public identifier for the entity (as provided in the source document).

systemId - The nominal system identifier for the entity (as provided in the source document).

Returns:

The system identifier to use for the entity.

Throws:

java.net.MalformedURLException - The formal system identifier of a subordinate catalog cannot be turned into a valid URL.

java.io.IOException - Error reading subordinate catalog file.

resolveNotation

public java.lang.String resolveNotation(java.lang.String notationName,
                                        java.lang.String publicId,
                                        java.lang.String systemId)
                                 throws java.net.MalformedURLException,
                                        java.io.IOException

Return the applicable NOTATION system identifier.

Parameters:

notationName - The name of the notation for which a doctype is required.

publicId - The nominal public identifier for the notation (as provided in the source document).

systemId - The nominal system identifier for the notation (as provided in the source document).

Returns:

The system identifier to use for the notation.

Throws:

java.net.MalformedURLException - The formal system identifier of a subordinate catalog cannot be turned into a valid URL.

java.io.IOException - Error reading subordinate catalog file.

resolvePublic

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

Return the applicable PUBLIC or SYSTEM identifier.

This method searches the Catalog and returns the system identifier specified for the given system or public identifiers. If no appropriate PUBLIC or SYSTEM entry is found in the Catalog, null is returned.

Parameters:

publicId - The public identifier to locate in the catalog. Public identifiers are normalized before comparison.

systemId - The nominal system identifier for the entity in question (as provided in the source document).

Returns:

The system identifier to use. Note that the nominal system identifier is not returned if a match is not found in the catalog, instead null is returned to indicate that no match was found.

Throws:

java.net.MalformedURLException - The formal system identifier of a subordinate catalog cannot be turned into a valid URL.

java.io.IOException - Error reading subordinate catalog file.

resolveSystem

public java.lang.String resolveSystem(java.lang.String systemId)
                               throws java.net.MalformedURLException,
                                      java.io.IOException

Return the applicable SYSTEM system identifier

If a SYSTEM entry exists in the Catalog for the system ID specified, return the mapped value.

The caller is responsible for doing any necessary normalization of the system identifier before calling this method. For example, a relative system identifier in a document might be converted to an absolute system identifier before attempting to resolve it.

On Windows-based operating systems, the comparison between the system identifier provided and the SYSTEM entries in the Catalog is case-insensitive.

Parameters:

systemId - The system ID to locate in the catalog.

Returns:

The system identifier to use for the notation.

Throws:

java.net.MalformedURLException - The formal system identifier of a subordinate catalog cannot be turned into a valid URL.

java.io.IOException - Error reading subordinate catalog file.

setParserClass

public void setParserClass(java.lang.String parser)

Sets the parser class, enabling XML Catalog parsing.

Sets the parser class that will be used for loading XML Catalogs. If this method is not called, all catalogs will be parsed as plain text (and assumed to conform to the OASIS Catalog format ).

Parameters:

parser - The name of a class implementing the SAX Parser interface to be used for subsequent XML Catalog parsing.