1. // EntityResolver2.java - Extended SAX entity resolver.
  2. // http://www.saxproject.org
  3. // No warranty; no copyright -- use this as you will.
  4. // $Id: EntityResolver2.java,v 1.1.2.1 2004/05/01 08:34:43 jsuttor Exp $
  5. package org.xml.sax.ext;
  6. import java.io.IOException;
  7. import org.xml.sax.EntityResolver;
  8. import org.xml.sax.InputSource;
  9. import org.xml.sax.XMLReader;
  10. import org.xml.sax.SAXException;
  11. /**
  12. * Extended interface for mapping external entity references to input
  13. * sources, or providing a missing external subset. The
  14. * {@link XMLReader#setEntityResolver XMLReader.setEntityResolver()} method
  15. * is used to provide implementations of this interface to parsers.
  16. * When a parser uses the methods in this interface, the
  17. * {@link EntityResolver2#resolveEntity EntityResolver2.resolveEntity()}
  18. * method (in this interface) is used <em>instead of</em> the older (SAX 1.0)
  19. * {@link EntityResolver#resolveEntity EntityResolver.resolveEntity()} method.
  20. *
  21. * <blockquote>
  22. * <em>This module, both source code and documentation, is in the
  23. * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
  24. * </blockquote>
  25. *
  26. * <p>If a SAX application requires the customized handling which this
  27. * interface defines for external entities, it must ensure that it uses
  28. * an XMLReader with the
  29. * <em>http://xml.org/sax/features/use-entity-resolver2</em> feature flag
  30. * set to <em>true</em> (which is its default value when the feature is
  31. * recognized). If that flag is unrecognized, or its value is false,
  32. * or the resolver does not implement this interface, then only the
  33. * {@link EntityResolver} method will be used.
  34. * </p>
  35. *
  36. * <p>That supports three categories of application that modify entity
  37. * resolution. <em>Old Style</em> applications won't know about this interface;
  38. * they will provide an EntityResolver.
  39. * <em>Transitional Mode</em> provide an EntityResolver2 and automatically
  40. * get the benefit of its methods in any systems (parsers or other tools)
  41. * supporting it, due to polymorphism.
  42. * Both <em>Old Style</em> and <em>Transitional Mode</em> applications will
  43. * work with any SAX2 parser.
  44. * <em>New style</em> applications will fail to run except on SAX2 parsers
  45. * that support this particular feature.
  46. * They will insist that feature flag have a value of "true", and the
  47. * EntityResolver2 implementation they provide might throw an exception
  48. * if the original SAX 1.0 style entity resolution method is invoked.
  49. * </p>
  50. *
  51. * @see org.xml.sax.XMLReader#setEntityResolver
  52. *
  53. * @since SAX 2.0 (extensions 1.1 alpha)
  54. * @author David Brownell
  55. * @version TBD
  56. */
  57. public interface EntityResolver2 extends EntityResolver
  58. {
  59. /**
  60. * Allows applications to provide an external subset for documents
  61. * that don't explicitly define one. Documents with DOCTYPE declarations
  62. * that omit an external subset can thus augment the declarations
  63. * available for validation, entity processing, and attribute processing
  64. * (normalization, defaulting, and reporting types including ID).
  65. * This augmentation is reported
  66. * through the {@link LexicalHandler#startDTD startDTD()} method as if
  67. * the document text had originally included the external subset;
  68. * this callback is made before any internal subset data or errors
  69. * are reported.</p>
  70. *
  71. * <p>This method can also be used with documents that have no DOCTYPE
  72. * declaration. When the root element is encountered,
  73. * but no DOCTYPE declaration has been seen, this method is
  74. * invoked. If it returns a value for the external subset, that root
  75. * element is declared to be the root element, giving the effect of
  76. * splicing a DOCTYPE declaration at the end the prolog of a document
  77. * that could not otherwise be valid. The sequence of parser callbacks
  78. * in that case logically resembles this:</p>
  79. *
  80. * <pre>
  81. * ... comments and PIs from the prolog (as usual)
  82. * startDTD ("rootName", source.getPublicId (), source.getSystemId ());
  83. * startEntity ("[dtd]");
  84. * ... declarations, comments, and PIs from the external subset
  85. * endEntity ("[dtd]");
  86. * endDTD ();
  87. * ... then the rest of the document (as usual)
  88. * startElement (..., "rootName", ...);
  89. * </pre>
  90. *
  91. * <p>Note that the InputSource gets no further resolution.
  92. * Implementations of this method may wish to invoke
  93. * {@link #resolveEntity resolveEntity()} to gain benefits such as use
  94. * of local caches of DTD entities. Also, this method will never be
  95. * used by a (non-validating) processor that is not including external
  96. * parameter entities. </p>
  97. *
  98. * <p>Uses for this method include facilitating data validation when
  99. * interoperating with XML processors that would always require
  100. * undesirable network accesses for external entities, or which for
  101. * other reasons adopt a "no DTDs" policy.
  102. * Non-validation motives include forcing documents to include DTDs so
  103. * that attributes are handled consistently.
  104. * For example, an XPath processor needs to know which attibutes have
  105. * type "ID" before it can process a widely used type of reference.</p>
  106. *
  107. * <p><strong>Warning:</strong> Returning an external subset modifies
  108. * the input document. By providing definitions for general entities,
  109. * it can make a malformed document appear to be well formed.
  110. * </p>
  111. *
  112. * @param name Identifies the document root element. This name comes
  113. * from a DOCTYPE declaration (where available) or from the actual
  114. * root element.
  115. * @param baseURI The document's base URI, serving as an additional
  116. * hint for selecting the external subset. This is always an absolute
  117. * URI, unless it is null because the XMLReader was given an InputSource
  118. * without one.
  119. *
  120. * @return An InputSource object describing the new external subset
  121. * to be used by the parser, or null to indicate that no external
  122. * subset is provided.
  123. *
  124. * @exception SAXException Any SAX exception, possibly wrapping
  125. * another exception.
  126. * @exception IOException Probably indicating a failure to create
  127. * a new InputStream or Reader, or an illegal URL.
  128. */
  129. public InputSource getExternalSubset (String name, String baseURI)
  130. throws SAXException, IOException;
  131. /**
  132. * Allows applications to map references to external entities into input
  133. * sources, or tell the parser it should use conventional URI resolution.
  134. * This method is only called for external entities which have been
  135. * properly declared.
  136. * This method provides more flexibility than the {@link EntityResolver}
  137. * interface, supporting implementations of more complex catalogue
  138. * schemes such as the one defined by the <a href=
  139. "http://www.oasis-open.org/committees/entity/spec-2001-08-06.html"
  140. >OASIS XML Catalogs</a> specification.</p>
  141. *
  142. * <p>Parsers configured to use this resolver method will call it
  143. * to determine the input source to use for any external entity
  144. * being included because of a reference in the XML text.
  145. * That excludes the document entity, and any external entity returned
  146. * by {@link #getExternalSubset getExternalSubset()}.
  147. * When a (non-validating) processor is configured not to include
  148. * a class of entities (parameter or general) through use of feature
  149. * flags, this method is not invoked for such entities. </p>
  150. *
  151. * <p>Note that the entity naming scheme used here is the same one
  152. * used in the {@link LexicalHandler}, or in the {@link
  153. org.xml.sax.ContentHandler#skippedEntity
  154. ContentHandler.skippedEntity()}
  155. * method. </p>
  156. *
  157. * @param name Identifies the external entity being resolved.
  158. * Either "[dtd]" for the external subset, or a name starting
  159. * with "%" to indicate a parameter entity, or else the name of
  160. * a general entity. This is never null when invoked by a SAX2
  161. * parser.
  162. * @param publicId The public identifier of the external entity being
  163. * referenced (normalized as required by the XML specification), or
  164. * null if none was supplied.
  165. * @param baseURI The URI with respect to which relative systemIDs
  166. * are interpreted. This is always an absolute URI, unless it is
  167. * null (likely because the XMLReader was given an InputSource without
  168. * one). This URI is defined by the XML specification to be the one
  169. * associated with the "<" starting the relevant declaration.
  170. * @param systemId The system identifier of the external entity
  171. * being referenced; either a relative or absolute URI.
  172. * This is never null when invoked by a SAX2 parser; only declared
  173. * entities, and any external subset, are resolved by such parsers.
  174. *
  175. * @return An InputSource object describing the new input source to
  176. * be used by the parser. Returning null directs the parser to
  177. * resolve the system ID against the base URI and open a connection
  178. * to resulting URI.
  179. *
  180. * @exception SAXException Any SAX exception, possibly wrapping
  181. * another exception.
  182. * @exception IOException Probably indicating a failure to create
  183. * a new InputStream or Reader, or an illegal URL.
  184. */
  185. public InputSource resolveEntity (
  186. String name,
  187. String publicId,
  188. String baseURI,
  189. String systemId
  190. ) throws SAXException, IOException;
  191. }