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:

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:

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.


Copyright 2001 Apache Jakarta Project. All Rights Reserved.