java.lang.Object | +--gnu.xml.util.XCatAll Implemented Interfaces:
XCat() Initializes without preloading a catalog. |
XCat(java.lang.String uri) Initializes, and preloads a catalog using the default SAX parser. |
synchronized 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. |
boolean | isUnified() Returns true (the default) if all methods resolve a given URI in the same way. |
boolean | isUsingPublic() Returns true (the default) if a catalog's public identifier mappings will be used. |
synchronized void | loadCatalog(java.lang.String uri) Loads an OASIS XML Catalog. |
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 | resolveEntity(java.lang.String publicId, java.lang.String systemId) "Old 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. |
void | setUsingPublic(boolean value) Specifies which catalog search mode is used. |
public XCat()
public XCat(java.lang.String uri)
This just delegates to #loadCatalog loadCatalog(); see it for exception information.
uri
- absolute URI for the catalog file.public synchronized void disableLoading()
public ErrorHandler getErrorHandler()
public InputSource getExternalSubset(java.lang.String name, java.lang.String baseURI)
Warning: That catalog functionality can be dangerous. It can provide definitions of general entities, and thereby mask certain well formedess errors.
name
- Name of the document element, either as declared in
a DOCTYPE declaration or as observed in the text.baseURI
- Document's base URI (absolute).public String getParserClass()
public boolean isUnified()
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).
public boolean isUsingPublic()
public synchronized void loadCatalog(java.lang.String uri)
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.
uri
- absolute URI for the catalog file.IOException
- As thrown by the parser, typically to
indicate problems reading data from that URI.SAXException
- As thrown by the parser, typically to
indicate problems parsing data from that URI.IllegalStateException
- When attempting to load a
catalog after loading has been #disableLoading disabled,
such as after any entity or URI lookup has been performed.public final InputSource resolveEntity(java.lang.String publicId, java.lang.String systemId)
The functional limitations of this interface include:
Applications can tell whether this limited functionality will be used: if the feature flag associated with the 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.
publicId
- Either a normalized public ID, or nullsystemId
- Always an absolute URI.public InputSource resolveEntity(java.lang.String name, java.lang.String publicId, java.lang.String baseURI, java.lang.String systemId)
This supports the full core catalog functionality for locating (and relocating) parsed entities that have been declared in a document's DTD.
name
- Entity name, such as "dudley", "%nell", or "[dtd]".publicId
- Either a normalized public ID, or null.baseURI
- Absolute base URI associated with systemId.systemId
- URI found in entity declaration (may be
relative to baseURI).public InputSource resolveURI(java.lang.String baseURI, java.lang.String uri)
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.
baseURI
- The relevant base URI as specified by the XML Base
specification.uri
- Either an absolute URI, or one relative to baseURIpublic void setErrorHandler(org.xml.sax.ErrorHandler handler)
If you're sharing the resolver between parsers, don't change this once lookups have begun.
handler
- The error handler, or null saying to use the default
(no diagnostics, and only fatal errors terminate loading).public void setParserClass(java.lang.String parser)
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 Locator and support the optional declaration and lexical handlers.
parser
- The parser class name, or null saying to use the
system default SAX2 parser.public void setUnified(boolean value)
Don't change this once you've loaded the first catalog.
value
- new flag settingpublic void setUsingPublic(boolean value)
If you're sharing the resolver between parsers, don't change this once lookups have begun.
value
- true to always use public identifier mappings,
false to only use them for system ids using the urn:publicid:
URI scheme.
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:
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 resolveURI() 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 setErrorHandler(). 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 loadCatalog() 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(java.lang.String,java.lang.String) resolveEntity() method for a list of restrictions which apply when it is used with older SAX parsers.