< prev index next >
src/java.xml/share/classes/org/xml/sax/ext/EntityResolver2.java
Print this page
*** 59,69 ****
* <em>http://xml.org/sax/features/use-entity-resolver2</em> feature flag
* set to <em>true</em> (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
* {@link EntityResolver} method will be used.
! * </p>
*
* <p>That supports three categories of application that modify entity
* resolution. <em>Old Style</em> applications won't know about this interface;
* they will provide an EntityResolver.
* <em>Transitional Mode</em> provide an EntityResolver2 and automatically
--- 59,69 ----
* <em>http://xml.org/sax/features/use-entity-resolver2</em> feature flag
* set to <em>true</em> (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
* {@link EntityResolver} method will be used.
! *
*
* <p>That supports three categories of application that modify entity
* resolution. <em>Old Style</em> applications won't know about this interface;
* they will provide an EntityResolver.
* <em>Transitional Mode</em> provide an EntityResolver2 and automatically
*** 74,84 ****
* <em>New style</em> 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.
! * </p>
*
* @see org.xml.sax.XMLReader#setEntityResolver
*
* @since 1.5, SAX 2.0 (extensions 1.1 alpha)
* @author David Brownell
--- 74,84 ----
* <em>New style</em> 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 org.xml.sax.XMLReader#setEntityResolver
*
* @since 1.5, SAX 2.0 (extensions 1.1 alpha)
* @author David Brownell
*** 93,112 ****
* (normalization, defaulting, and reporting types including ID).
* This augmentation is reported
* through the {@link 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.</p>
*
* <p>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:</p>
*
* <pre>
* ... comments and PIs from the prolog (as usual)
* startDTD ("rootName", source.getPublicId (), source.getSystemId ());
* startEntity ("[dtd]");
--- 93,112 ----
* (normalization, defaulting, and reporting types including ID).
* This augmentation is reported
* through the {@link 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.
*
* <p>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:
*
* <pre>
* ... comments and PIs from the prolog (as usual)
* startDTD ("rootName", source.getPublicId (), source.getSystemId ());
* startEntity ("[dtd]");
*** 120,144 ****
* <p>Note that the InputSource gets no further resolution.
* Implementations of this method may wish to invoke
* {@link #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. </p>
*
* <p>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.</p>
*
* <p><strong>Warning:</strong> 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.
! * </p>
*
* @param name Identifies the document root element. This name comes
* from a DOCTYPE declaration (where available) or from the actual
* root element.
* @param baseURI The document's base URI, serving as an additional
--- 120,144 ----
* <p>Note that the InputSource gets no further resolution.
* Implementations of this method may wish to invoke
* {@link #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.
*
* <p>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.
*
* <p><strong>Warning:</strong> 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.
! *
*
* @param name Identifies the document root element. This name comes
* from a DOCTYPE declaration (where available) or from the actual
* root element.
* @param baseURI The document's base URI, serving as an additional
*** 165,190 ****
* properly declared.
* This method provides more flexibility than the {@link EntityResolver}
* interface, supporting implementations of more complex catalogue
* schemes such as the one defined by the <a href=
"http://www.oasis-open.org/committees/entity/spec-2001-08-06.html"
! >OASIS XML Catalogs</a> specification.</p>
*
* <p>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 {@link #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. </p>
*
* <p>Note that the entity naming scheme used here is the same one
* used in the {@link LexicalHandler}, or in the {@link
org.xml.sax.ContentHandler#skippedEntity
ContentHandler.skippedEntity()}
! * method. </p>
*
* @param name Identifies the external entity being resolved.
* Either "[dtd]" for the external subset, or a name starting
* with "%" to indicate a parameter entity, or else the name of
* a general entity. This is never null when invoked by a SAX2
--- 165,190 ----
* properly declared.
* This method provides more flexibility than the {@link EntityResolver}
* interface, supporting implementations of more complex catalogue
* schemes such as the one defined by the <a href=
"http://www.oasis-open.org/committees/entity/spec-2001-08-06.html"
! >OASIS XML Catalogs</a> specification.
*
* <p>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 {@link #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.
*
* <p>Note that the entity naming scheme used here is the same one
* used in the {@link LexicalHandler}, or in the {@link
org.xml.sax.ContentHandler#skippedEntity
ContentHandler.skippedEntity()}
! * method.
*
* @param name Identifies the external entity being resolved.
* Either "[dtd]" for the external subset, or a name starting
* with "%" to indicate a parameter entity, or else the name of
* a general entity. This is never null when invoked by a SAX2
*** 194,204 ****
* null if none was supplied.
* @param baseURI The URI with respect to which relative systemIDs
* are interpreted. This is always an absolute URI, unless it is
* null (likely because the XMLReader was given an InputSource without
* one). This URI is defined by the XML specification to be the one
! * associated with the "<" starting the relevant declaration.
* @param systemId The system identifier of the external entity
* being referenced; either a relative or absolute URI.
* This is never null when invoked by a SAX2 parser; only declared
* entities, and any external subset, are resolved by such parsers.
*
--- 194,204 ----
* null if none was supplied.
* @param baseURI The URI with respect to which relative systemIDs
* are interpreted. This is always an absolute URI, unless it is
* null (likely because the XMLReader was given an InputSource without
* one). This URI is defined by the XML specification to be the one
! * associated with the "{@literal <}" starting the relevant declaration.
* @param systemId The system identifier of the external entity
* being referenced; either a relative or absolute URI.
* This is never null when invoked by a SAX2 parser; only declared
* entities, and any external subset, are resolved by such parsers.
*
< prev index next >