All Implemented Interfaces:
All Known Implementing Classes:
This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY.
If a SAX application requires the customized handling which this interface defines for external entities, it must ensure that it uses an XMLReader with the http://xml.org/sax/features/use-entity-resolver2 feature flag set to true (which is its default value when the feature is recognized). If that flag is unrecognized, or its value is false, or the resolver does not implement this interface, then only the EntityResolver method will be used.
That supports three categories of application that modify entity resolution. Old Style applications won't know about this interface; they will provide an EntityResolver. Transitional Mode provide an EntityResolver2 and automatically get the benefit of its methods in any systems (parsers or other tools) supporting it, due to polymorphism. Both Old Style and Transitional Mode applications will work with any SAX2 parser. New style applications will fail to run except on SAX2 parsers that support this particular feature. They will insist that feature flag have a value of "true", and the EntityResolver2 implementation they provide might throw an exception if the original SAX 1.0 style entity resolution method is invoked.
SAX- 2.0 (extensions 1.1 alpha)
|Method from org.xml.sax.ext.EntityResolver2 Summary:|
|Method from org.xml.sax.ext.EntityResolver2 Detail:|
public InputSource getExternalSubset(String name, String baseURI) throws SAXException, IOException
This method can also be used with documents that have no DOCTYPE declaration. When the root element is encountered, but no DOCTYPE declaration has been seen, this method is invoked. If it returns a value for the external subset, that root element is declared to be the root element, giving the effect of splicing a DOCTYPE declaration at the end the prolog of a document that could not otherwise be valid. The sequence of parser callbacks in that case logically resembles this:
... comments and PIs from the prolog (as usual) startDTD ("rootName", source.getPublicId (), source.getSystemId ()); startEntity ("[dtd]"); ... declarations, comments, and PIs from the external subset endEntity ("[dtd]"); endDTD (); ... then the rest of the document (as usual) startElement (..., "rootName", ...);
Note that the InputSource gets no further resolution. Implementations of this method may wish to invoke resolveEntity() to gain benefits such as use of local caches of DTD entities. Also, this method will never be used by a (non-validating) processor that is not including external parameter entities.
Uses for this method include facilitating data validation when interoperating with XML processors that would always require undesirable network accesses for external entities, or which for other reasons adopt a "no DTDs" policy. Non-validation motives include forcing documents to include DTDs so that attributes are handled consistently. For example, an XPath processor needs to know which attibutes have type "ID" before it can process a widely used type of reference.
Warning: Returning an external subset modifies the input document. By providing definitions for general entities, it can make a malformed document appear to be well formed.
public InputSource resolveEntity(String name, String publicId, String baseURI, String systemId) throws SAXException, IOException
Parsers configured to use this resolver method will call it to determine the input source to use for any external entity being included because of a reference in the XML text. That excludes the document entity, and any external entity returned by getExternalSubset() . When a (non-validating) processor is configured not to include a class of entities (parameter or general) through use of feature flags, this method is not invoked for such entities.