| org.xml.sax.ext.EntityResolver2
All known Subclasses: org.xml.sax.ext.DefaultHandler2,
| EntityResolver2 | | public interface EntityResolver2 extends EntityResolver(Code) | | Extended interface for mapping external entity references to input
sources, or providing a missing external subset. The
XMLReader.setEntityResolver XMLReader.setEntityResolver() method
is used to provide implementations of this interface to parsers.
When a parser uses the methods in this interface, the
EntityResolver2.resolveEntity EntityResolver2.resolveEntity() method (in this interface) is used instead of the older (SAX 1.0)
EntityResolver.resolveEntity EntityResolver.resolveEntity() method.
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.
See Also: org.xml.sax.XMLReader.setEntityResolver
since:
SAX 2.0 (extensions 1.1 alpha)
author:
David Brownell
version:
TBD |
| Method Summary | |
| public InputSource | getExternalSubset(String name, String baseURI)
Allows applications to provide an external subset for documents
that don't explicitly define one. | | public InputSource | resolveEntity(String name, String publicId, String baseURI, String systemId)
Allows applications to map references to external entities into input
sources, or tell the parser it should use conventional URI resolution.
This method is only called for external entities which have been
properly declared.
This method provides more flexibility than the
EntityResolver interface, supporting implementations of more complex catalogue
schemes such as the one defined by the OASIS XML Catalogs specification.
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
EntityResolver2.getExternalSubset 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. |
| getExternalSubset | | public InputSource getExternalSubset(String name, String baseURI) throws SAXException, IOException(Code) | | Allows applications to provide an external subset for documents
that don't explicitly define one. Documents with DOCTYPE declarations
that omit an external subset can thus augment the declarations
available for validation, entity processing, and attribute processing
(normalization, defaulting, and reporting types including ID).
This augmentation is reported
through the
LexicalHandler.startDTD startDTD() method as if
the document text had originally included the external subset;
this callback is made before any internal subset data or errors
are reported.
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
EntityResolver2.resolveEntity 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.
Parameters:
name - Identifies the document root element. This name comesfrom a DOCTYPE declaration (where available) or from the actualroot element.
Parameters:
baseURI - The document's base URI, serving as an additionalhint for selecting the external subset. This is always an absoluteURI, unless it is null because the XMLReader was given an InputSourcewithout one. An InputSource object describing the new external subsetto be used by the parser, or null to indicate that no externalsubset is provided.
exception:
SAXException - Any SAX exception, possibly wrappinganother exception.
exception:
IOException - Probably indicating a failure to createa new InputStream or Reader, or an illegal URL. |
| resolveEntity | | public InputSource resolveEntity(String name, String publicId, String baseURI, String systemId) throws SAXException, IOException(Code) | | Allows applications to map references to external entities into input
sources, or tell the parser it should use conventional URI resolution.
This method is only called for external entities which have been
properly declared.
This method provides more flexibility than the
EntityResolver interface, supporting implementations of more complex catalogue
schemes such as the one defined by the OASIS XML Catalogs specification.
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
EntityResolver2.getExternalSubset 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.
Note that the entity naming scheme used here is the same one
used in the
LexicalHandler , or in the
org.xml.sax.ContentHandler.skippedEntityContentHandler.skippedEntity() method.
Parameters:
name - Identifies the external entity being resolved.Either "[dtd]" for the external subset, or a name startingwith "%" to indicate a parameter entity, or else the name ofa general entity. This is never null when invoked by a SAX2parser.
Parameters:
publicId - The public identifier of the external entity beingreferenced (normalized as required by the XML specification), ornull if none was supplied.
Parameters:
baseURI - The URI with respect to which relative systemIDsare interpreted. This is always an absolute URI, unless it isnull (likely because the XMLReader was given an InputSource withoutone). This URI is defined by the XML specification to be the oneassociated with the "<" starting the relevant declaration.
Parameters:
systemId - The system identifier of the external entitybeing referenced; either a relative or absolute URI.This is never null when invoked by a SAX2 parser; only declaredentities, and any external subset, are resolved by such parsers. An InputSource object describing the new input source tobe used by the parser. Returning null directs the parser toresolve the system ID against the base URI and open a connectionto resulting URI.
exception:
SAXException - Any SAX exception, possibly wrappinganother exception.
exception:
IOException - Probably indicating a failure to createa new InputStream or Reader, or an illegal URL. |
|
|