Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> gnu >> xml >> [ util overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of gnu.xml.util.XCat JAVADOC | Sourc code of gnu.xml.util.XCat SOURCE | Download gnu.xml.util.XCat DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

gnu.xml.util
Class XCat  view XCat download XCat.java

java.lang.Object
  extended bygnu.xml.util.XCat
All Implemented Interfaces:
org.xml.sax.EntityResolver, org.xml.sax.ext.EntityResolver2
public class XCat
extends java.lang.Object
implements org.xml.sax.ext.EntityResolver2

Packages OASIS XML Catalogs, primarily for entity resolution by parsers. That specification defines an XML syntax for mappings between identifiers declared in DTDs (particularly PUBLIC identifiers) and locations. SAX has always supported such mappings, but conventions for an XML file syntax to maintain them have previously been lacking.

This has three main operational modes. The primary intended mode is to create a resolver, then preloading it with one or more site-standard catalogs before using it with one or more SAX parsers: 

	XCat	catalog = new XCat ();
	catalog.setErrorHandler (diagnosticErrorHandler);
	catalog.loadCatalog ("file:/local/catalogs/catalog.cat");
	catalog.loadCatalog ("http://shared/catalog.cat");
	...
	catalog.disableLoading ();
	parser1.setEntityResolver (catalog);
	parser2.setEntityResolver (catalog);
	...

A second mode is to arrange that your application uses instances of this class as its entity resolver, and automatically loads catalogs referenced by <?oasis-xml-catalog...?> processing instructions found before the DTD in documents it parses. It would then discard the resolver after each parse.

A third mode applies catalogs in contexts other than entity resolution for parsers. The resolveURI() 55 method supports resolving URIs stored in XML application data, rather than inside DTDs. Catalogs would be loaded as shown above, and the catalog could be used concurrently for parser entity resolution and for application URI resolution.

Errors in catalogs implicitly loaded (during resolution) are ignored beyond being reported through any ErrorHandler assigned using setErrorHandler() 55 . SAX exceptions thrown from such a handler won't abort resolution, although throwing a RuntimeException or Error will normally abort both resolution and parsing. Useful diagnostic information is available to any ErrorHandler used to report problems, or from any exception thrown from an explicit loadCatalog() 55 invocation. Applications can use that information as troubleshooting aids.

While this class requires SAX2 Extensions 1.1 classes in its class path, basic functionality does not require using a SAX2 parser that supports the extended entity resolution functionality. See the original SAX1 resolveEntity() 55 method for a list of restrictions which apply when it is used with older SAX parsers.

Nested Class Summary
private static class XCat.Catalog
          Represents a OASIS XML Catalog, and encapsulates much of the catalog functionality.
private static class XCat.DoneDelegation
           
private static class XCat.Loader
          Loads/unmarshals one catalog.
 
Field Summary
private static java.lang.String catalogNamespace
          This is the namespace URI used for OASIS XML Catalogs.
private  XCat.Catalog[] catalogs
           
private  org.xml.sax.ErrorHandler errorHandler
           
private  boolean loadingPermitted
           
private  java.lang.String parserClass
           
private  boolean unified
           
private  boolean usingPublic
           
 
Constructor Summary
XCat()
          Initializes without preloading a catalog.
XCat(java.lang.String uri)
          Initializes, and preloads a catalog using the default SAX parser.
 
Method Summary
 void disableLoading()
          Records that catalog loading is no longer permitted.
 org.xml.sax.ErrorHandler getErrorHandler()
          Returns the error handler used to report catalog errors.
 org.xml.sax.InputSource getExternalSubset(java.lang.String name, java.lang.String baseURI)
          "New Style" parser callback to add an external subset.
 java.lang.String getParserClass()
          Returns the name of the SAX2 parser class used to parse catalogs.
private static int hexNibble(int c)
           
 boolean isUnified()
          Returns true (the default) if all methods resolve a given URI in the same way.
private static boolean isUriExcluded(int c)
           
 boolean isUsingPublic()
          Returns true (the default) if a catalog's public identifier mappings will be used.
 void loadCatalog(java.lang.String uri)
          Loads an OASIS XML Catalog.
private static XCat.Catalog loadCatalog(java.lang.String parserClass, org.xml.sax.ErrorHandler eh, java.lang.String uri, boolean unified)
           
private static java.lang.String normalizePublicId(boolean full, java.lang.String publicId)
           
private static java.lang.String normalizeURI(java.lang.String systemId)
           
 org.xml.sax.InputSource resolveEntity(java.lang.String publicId, java.lang.String systemId)
          "Old Style" external entity resolution for parsers.
 org.xml.sax.InputSource resolveEntity(java.lang.String name, java.lang.String publicId, java.lang.String baseURI, java.lang.String systemId)
          "New Style" external entity resolution for parsers.
 org.xml.sax.InputSource resolveURI(java.lang.String baseURI, java.lang.String uri)
          Resolves a URI reference that's not defined to the DTD.
 void setErrorHandler(org.xml.sax.ErrorHandler handler)
          Assigns the error handler used to report catalog errors.
 void setParserClass(java.lang.String parser)
          Names the SAX2 parser class used to parse catalogs.
 void setUnified(boolean value)
          Assigns the value of the flag returned by isUnified() 55 .
 void setUsingPublic(boolean value)
          Specifies which catalog search mode is used.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

catalogs

private XCat.Catalog[] catalogs

usingPublic

private boolean usingPublic

loadingPermitted

private boolean loadingPermitted

unified

private boolean unified

parserClass

private java.lang.String parserClass

errorHandler

private org.xml.sax.ErrorHandler errorHandler

catalogNamespace

private static final java.lang.String catalogNamespace
This is the namespace URI used for OASIS XML Catalogs.

See Also:
Constant Field Values
Constructor Detail

XCat

public XCat()
Initializes without preloading a catalog. This API is convenient when you may want to arrange that catalogs are automatically loaded when explicitly referenced in documents, using the oasis-xml-catalog processing instruction. In such cases you won't usually be able to preload catalogs.

XCat

public XCat(java.lang.String uri)
     throws org.xml.sax.SAXException,
            java.io.IOException
Initializes, and preloads a catalog using the default SAX parser. This API is convenient when you operate with one or more standard catalogs.

This just delegates to loadCatalog() 55 ; see it for exception information.

Method Detail

loadCatalog

public void loadCatalog(java.lang.String uri)
                 throws org.xml.sax.SAXException,
                        java.io.IOException
Loads an OASIS XML Catalog. It is appended to the list of currently active catalogs, or reloaded if a catalog with the same URI was already loaded. Callers have control over what parser is used, how catalog parsing errors are reported, and whether URIs will be resolved consistently.

The OASIS specification says that errors detected when loading catalogs "must recover by ignoring the catalog entry file that failed, and proceeding." In this API, that action can be the responsibility of applications, when they explicitly load any catalog using this method.

Note that catalogs referenced by this one will not be loaded at this time. Catalogs referenced through nextCatalog or delegate* elements are normally loaded only if needed.

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
"New Style" external entity resolution for parsers. Calls to this method prevent explicit loading of additional catalogs using loadCatalog() 55 .

This supports the full core catalog functionality for locating (and relocating) parsed entities that have been declared in a document's DTD.

Specified by:
resolveEntity in interface org.xml.sax.ext.EntityResolver2

getExternalSubset

public org.xml.sax.InputSource getExternalSubset(java.lang.String name,
                                                 java.lang.String baseURI)
                                          throws org.xml.sax.SAXException,
                                                 java.io.IOException
"New Style" parser callback to add an external subset. For documents that don't include an external subset, this may return one according to doctype catalog entries. (This functionality is not a core part of the OASIS XML Catalog specification, though it's presented in an appendix.) If no such entry is defined, this returns null to indicate that this document will not be modified to include such a subset. Calls to this method prevent explicit loading of additional catalogs using loadCatalog() 55 .

Warning: That catalog functionality can be dangerous. It can provide definitions of general entities, and thereby mask certain well formedess errors.

Specified by:
getExternalSubset in interface org.xml.sax.ext.EntityResolver2

resolveEntity

public final org.xml.sax.InputSource resolveEntity(java.lang.String publicId,
                                                   java.lang.String systemId)
                                            throws org.xml.sax.SAXException,
                                                   java.io.IOException
"Old Style" external entity resolution for parsers. This API provides only core functionality. Calls to this method prevent explicit loading of additional catalogs using loadCatalog() 55 .

The functional limitations of this interface include:

  • Since system IDs will be absolutized before the resolver sees them, matching against relative URIs won't work. This may affect system, rewriteSystem, and delegateSystem catalog entries.
  • Because of that absolutization, documents declaring entities with system IDs using URI schemes that the JVM does not recognize may be unparsable. URI schemes such as file:/, http://, https://, and ftp:// will usually work reliably.
  • Because missing external subsets can't be provided, the doctype catalog entries will be ignored. (The getExternalSubset() 55 method is a "New Style" resolution option.)

Applications can tell whether this limited functionality will be used: if the feature flag associated with the org.xml.sax.ext.EntityResolver2 interface is not true, the limitations apply. Applications can't usually know whether a given document and catalog will trigger those limitations. The issue can only be bypassed by operational procedures such as not using catalogs or documents which involve those features.

Specified by:
resolveEntity in interface org.xml.sax.EntityResolver

resolveURI

public org.xml.sax.InputSource resolveURI(java.lang.String baseURI,
                                          java.lang.String uri)
                                   throws org.xml.sax.SAXException,
                                          java.io.IOException
Resolves a URI reference that's not defined to the DTD. This is intended for use with URIs found in document text, such as xml-stylesheet processing instructions and in attribute values, where they are not recognized as URIs by XML parsers. Calls to this method prevent explicit loading of additional catalogs using loadCatalog() 55 .

This functionality is supported by the OASIS XML Catalog specification, but will never be invoked by an XML parser. It corresponds closely to functionality for mapping system identifiers for entities declared in DTDs; closely enough that this implementation's default behavior is that they be identical, to minimize potential confusion.

This method could be useful when implementing the javax.xml.transform.URIResolver interface, wrapping the input source in a javax.xml.transform.sax.SAXSource.

disableLoading

public void disableLoading()
Records that catalog loading is no longer permitted. Loading is automatically disabled when lookups are performed, and should be manually disabled when startDTD() (or any other DTD declaration callback) is invoked, or at the latest when the document root element is seen.

getErrorHandler

public org.xml.sax.ErrorHandler getErrorHandler()
Returns the error handler used to report catalog errors. Null is returned if the parser's default error handling will be used.

setErrorHandler

public void setErrorHandler(org.xml.sax.ErrorHandler handler)
Assigns the error handler used to report catalog errors. These errors may come either from the SAX2 parser or from the catalog parsing code driven by the parser.

If you're sharing the resolver between parsers, don't change this once lookups have begun.

getParserClass

public java.lang.String getParserClass()
Returns the name of the SAX2 parser class used to parse catalogs. Null is returned if the system default is used.

setParserClass

public void setParserClass(java.lang.String parser)
Names the SAX2 parser class used to parse catalogs.

If you're sharing the resolver between parsers, don't change this once lookups have begun.

Note that in order to properly support the xml:base attribute and relative URI resolution, the SAX parser used to parse the catalog must provide a org.xml.sax.Locator and support the optional declaration and lexical handlers.

isUnified

public boolean isUnified()
Returns true (the default) if all methods resolve a given URI in the same way. Returns false if calls resolving URIs as entities (such as resolveEntity() 55 ) use different catalog entries than those resolving them as URIs (resolveURI() 55 ), which will generally produce different results.

The OASIS XML Catalog specification defines two related schemes to map URIs "as URIs" or "as system IDs". URIs use uri, rewriteURI, and delegateURI elements. System IDs do the same things with systemId, rewriteSystemId, and delegateSystemId. It's confusing and error prone to maintain two parallel copies of such data. Accordingly, this class makes that behavior optional. The unified interpretation of URI mappings is preferred, since it prevents surprises where one URI gets mapped to different contents depending on whether the reference happens to have come from a DTD (or not).

setUnified

public void setUnified(boolean value)
Assigns the value of the flag returned by isUnified() 55 . Set it to false to be strictly conformant with the OASIS XML Catalog specification. Set it to true to make all mappings for a given URI give the same result, regardless of the reason for the mapping.

Don't change this once you've loaded the first catalog.

isUsingPublic

public boolean isUsingPublic()
Returns true (the default) if a catalog's public identifier mappings will be used. When false is returned, such mappings are ignored except when system IDs are discarded, such as for entities using the urn:publicid: URI scheme in their system identifiers. (See RFC 3151 for information about that URI scheme. Using it in system identifiers may not work well with many SAX parsers unless the resolve-dtd-uris feature flag is set to false.)

setUsingPublic

public void setUsingPublic(boolean value)
Specifies which catalog search mode is used. By default, public identifier mappings are able to override system identifiers when both are available. Applications may choose to ignore public identifier mappings in such cases, so that system identifiers declared in DTDs will only be overridden by an explicit catalog match for that system ID.

If you're sharing the resolver between parsers, don't change this once lookups have begun.

loadCatalog

private static XCat.Catalog loadCatalog(java.lang.String parserClass,
                                        org.xml.sax.ErrorHandler eh,
                                        java.lang.String uri,
                                        boolean unified)
                                 throws org.xml.sax.SAXException,
                                        java.io.IOException

normalizePublicId

private static java.lang.String normalizePublicId(boolean full,
                                                  java.lang.String publicId)

isUriExcluded

private static boolean isUriExcluded(int c)

hexNibble

private static int hexNibble(int c)

normalizeURI

private static java.lang.String normalizeURI(java.lang.String systemId)
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> gnu >> xml >> [ util overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of gnu.xml.util.XCat JAVADOC | Sourc code of gnu.xml.util.XCat SOURCE | Download gnu.xml.util.XCat DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD