1. // XMLReader.java - read an XML document.
  2. // Written by David Megginson, sax@megginson.com
  3. // NO WARRANTY! This class is in the Public Domain.
  4. // $Id: XMLReader.java,v 1.2 2001/08/01 06:43:18 tcng Exp $
  5. package org.xml.sax;
  6. import java.io.IOException;
  7. /**
  8. * Interface for reading an XML document using callbacks.
  9. *
  10. * <blockquote>
  11. * <em>This module, both source code and documentation, is in the
  12. * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
  13. * </blockquote>
  14. *
  15. * <p><strong>Note:</strong> despite its name, this interface does
  16. * <em>not</em> extend the standard Java {@link java.io.Reader Reader}
  17. * interface, because reading XML is a fundamentally different activity
  18. * than reading character data.</p>
  19. *
  20. * <p>XMLReader is the interface that an XML parser's SAX2 driver must
  21. * implement. This interface allows an application to set and
  22. * query features and properties in the parser, to register
  23. * event handlers for document processing, and to initiate
  24. * a document parse.</p>
  25. *
  26. * <p>All SAX interfaces are assumed to be synchronous: the
  27. * {@link #parse parse} methods must not return until parsing
  28. * is complete, and readers must wait for an event-handler callback
  29. * to return before reporting the next event.</p>
  30. *
  31. * <p>This interface replaces the (now deprecated) SAX 1.0 {@link
  32. * org.xml.sax.Parser Parser} interface. The XMLReader interface
  33. * contains two important enhancements over the old Parser
  34. * interface:</p>
  35. *
  36. * <ol>
  37. * <li>it adds a standard way to query and set features and
  38. * properties; and</li>
  39. * <li>it adds Namespace support, which is required for many
  40. * higher-level XML standards.</li>
  41. * </ol>
  42. *
  43. * <p>There are adapters available to convert a SAX1 Parser to
  44. * a SAX2 XMLReader and vice-versa.</p>
  45. *
  46. * @since SAX 2.0
  47. * @author David Megginson,
  48. * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
  49. * @version 2.0
  50. * @see org.xml.sax.XMLFilter
  51. * @see org.xml.sax.helpers.ParserAdapter
  52. * @see org.xml.sax.helpers.XMLReaderAdapter
  53. */
  54. public interface XMLReader
  55. {
  56. ////////////////////////////////////////////////////////////////////
  57. // Configuration.
  58. ////////////////////////////////////////////////////////////////////
  59. /**
  60. * Look up the value of a feature.
  61. *
  62. * <p>The feature name is any fully-qualified URI. It is
  63. * possible for an XMLReader to recognize a feature name but
  64. * to be unable to return its value; this is especially true
  65. * in the case of an adapter for a SAX1 Parser, which has
  66. * no way of knowing whether the underlying parser is
  67. * performing validation or expanding external entities.</p>
  68. *
  69. * <p>All XMLReaders are required to recognize the
  70. * http://xml.org/sax/features/namespaces and the
  71. * http://xml.org/sax/features/namespace-prefixes feature names.</p>
  72. *
  73. * <p>Some feature values may be available only in specific
  74. * contexts, such as before, during, or after a parse.</p>
  75. *
  76. * <p>Typical usage is something like this:</p>
  77. *
  78. * <pre>
  79. * XMLReader r = new MySAXDriver();
  80. *
  81. * // try to activate validation
  82. * try {
  83. * r.setFeature("http://xml.org/sax/features/validation", true);
  84. * } catch (SAXException e) {
  85. * System.err.println("Cannot activate validation.");
  86. * }
  87. *
  88. * // register event handlers
  89. * r.setContentHandler(new MyContentHandler());
  90. * r.setErrorHandler(new MyErrorHandler());
  91. *
  92. * // parse the first document
  93. * try {
  94. * r.parse("http://www.foo.com/mydoc.xml");
  95. * } catch (IOException e) {
  96. * System.err.println("I/O exception reading XML document");
  97. * } catch (SAXException e) {
  98. * System.err.println("XML exception reading document.");
  99. * }
  100. * </pre>
  101. *
  102. * <p>Implementors are free (and encouraged) to invent their own features,
  103. * using names built on their own URIs.</p>
  104. *
  105. * @param name The feature name, which is a fully-qualified URI.
  106. * @return The current state of the feature (true or false).
  107. * @exception org.xml.sax.SAXNotRecognizedException When the
  108. * XMLReader does not recognize the feature name.
  109. * @exception org.xml.sax.SAXNotSupportedException When the
  110. * XMLReader recognizes the feature name but
  111. * cannot determine its value at this time.
  112. * @see #setFeature
  113. */
  114. public boolean getFeature (String name)
  115. throws SAXNotRecognizedException, SAXNotSupportedException;
  116. /**
  117. * Set the state of a feature.
  118. *
  119. * <p>The feature name is any fully-qualified URI. It is
  120. * possible for an XMLReader to recognize a feature name but
  121. * to be unable to set its value; this is especially true
  122. * in the case of an adapter for a SAX1 {@link org.xml.sax.Parser Parser},
  123. * which has no way of affecting whether the underlying parser is
  124. * validating, for example.</p>
  125. *
  126. * <p>All XMLReaders are required to support setting
  127. * http://xml.org/sax/features/namespaces to true and
  128. * http://xml.org/sax/features/namespace-prefixes to false.</p>
  129. *
  130. * <p>Some feature values may be immutable or mutable only
  131. * in specific contexts, such as before, during, or after
  132. * a parse.</p>
  133. *
  134. * @param name The feature name, which is a fully-qualified URI.
  135. * @param state The requested state of the feature (true or false).
  136. * @exception org.xml.sax.SAXNotRecognizedException When the
  137. * XMLReader does not recognize the feature name.
  138. * @exception org.xml.sax.SAXNotSupportedException When the
  139. * XMLReader recognizes the feature name but
  140. * cannot set the requested value.
  141. * @see #getFeature
  142. */
  143. public void setFeature (String name, boolean value)
  144. throws SAXNotRecognizedException, SAXNotSupportedException;
  145. /**
  146. * Look up the value of a property.
  147. *
  148. * <p>The property name is any fully-qualified URI. It is
  149. * possible for an XMLReader to recognize a property name but
  150. * to be unable to return its state; this is especially true
  151. * in the case of an adapter for a SAX1 {@link org.xml.sax.Parser
  152. * Parser}.</p>
  153. *
  154. * <p>XMLReaders are not required to recognize any specific
  155. * property names, though an initial core set is documented for
  156. * SAX2.</p>
  157. *
  158. * <p>Some property values may be available only in specific
  159. * contexts, such as before, during, or after a parse.</p>
  160. *
  161. * <p>Implementors are free (and encouraged) to invent their own properties,
  162. * using names built on their own URIs.</p>
  163. *
  164. * @param name The property name, which is a fully-qualified URI.
  165. * @return The current value of the property.
  166. * @exception org.xml.sax.SAXNotRecognizedException When the
  167. * XMLReader does not recognize the property name.
  168. * @exception org.xml.sax.SAXNotSupportedException When the
  169. * XMLReader recognizes the property name but
  170. * cannot determine its value at this time.
  171. * @see #setProperty
  172. */
  173. public Object getProperty (String name)
  174. throws SAXNotRecognizedException, SAXNotSupportedException;
  175. /**
  176. * Set the value of a property.
  177. *
  178. * <p>The property name is any fully-qualified URI. It is
  179. * possible for an XMLReader to recognize a property name but
  180. * to be unable to set its value; this is especially true
  181. * in the case of an adapter for a SAX1 {@link org.xml.sax.Parser
  182. * Parser}.</p>
  183. *
  184. * <p>XMLReaders are not required to recognize setting
  185. * any specific property names, though a core set is provided with
  186. * SAX2.</p>
  187. *
  188. * <p>Some property values may be immutable or mutable only
  189. * in specific contexts, such as before, during, or after
  190. * a parse.</p>
  191. *
  192. * <p>This method is also the standard mechanism for setting
  193. * extended handlers.</p>
  194. *
  195. * @param name The property name, which is a fully-qualified URI.
  196. * @param state The requested value for the property.
  197. * @exception org.xml.sax.SAXNotRecognizedException When the
  198. * XMLReader does not recognize the property name.
  199. * @exception org.xml.sax.SAXNotSupportedException When the
  200. * XMLReader recognizes the property name but
  201. * cannot set the requested value.
  202. */
  203. public void setProperty (String name, Object value)
  204. throws SAXNotRecognizedException, SAXNotSupportedException;
  205. ////////////////////////////////////////////////////////////////////
  206. // Event handlers.
  207. ////////////////////////////////////////////////////////////////////
  208. /**
  209. * Allow an application to register an entity resolver.
  210. *
  211. * <p>If the application does not register an entity resolver,
  212. * the XMLReader will perform its own default resolution.</p>
  213. *
  214. * <p>Applications may register a new or different resolver in the
  215. * middle of a parse, and the SAX parser must begin using the new
  216. * resolver immediately.</p>
  217. *
  218. * @param resolver The entity resolver.
  219. * @exception java.lang.NullPointerException If the resolver
  220. * argument is null.
  221. * @see #getEntityResolver
  222. */
  223. public void setEntityResolver (EntityResolver resolver);
  224. /**
  225. * Return the current entity resolver.
  226. *
  227. * @return The current entity resolver, or null if none
  228. * has been registered.
  229. * @see #setEntityResolver
  230. */
  231. public EntityResolver getEntityResolver ();
  232. /**
  233. * Allow an application to register a DTD event handler.
  234. *
  235. * <p>If the application does not register a DTD handler, all DTD
  236. * events reported by the SAX parser will be silently ignored.</p>
  237. *
  238. * <p>Applications may register a new or different handler in the
  239. * middle of a parse, and the SAX parser must begin using the new
  240. * handler immediately.</p>
  241. *
  242. * @param handler The DTD handler.
  243. * @exception java.lang.NullPointerException If the handler
  244. * argument is null.
  245. * @see #getDTDHandler
  246. */
  247. public void setDTDHandler (DTDHandler handler);
  248. /**
  249. * Return the current DTD handler.
  250. *
  251. * @return The current DTD handler, or null if none
  252. * has been registered.
  253. * @see #setDTDHandler
  254. */
  255. public DTDHandler getDTDHandler ();
  256. /**
  257. * Allow an application to register a content event handler.
  258. *
  259. * <p>If the application does not register a content handler, all
  260. * content events reported by the SAX parser will be silently
  261. * ignored.</p>
  262. *
  263. * <p>Applications may register a new or different handler in the
  264. * middle of a parse, and the SAX parser must begin using the new
  265. * handler immediately.</p>
  266. *
  267. * @param handler The content handler.
  268. * @exception java.lang.NullPointerException If the handler
  269. * argument is null.
  270. * @see #getContentHandler
  271. */
  272. public void setContentHandler (ContentHandler handler);
  273. /**
  274. * Return the current content handler.
  275. *
  276. * @return The current content handler, or null if none
  277. * has been registered.
  278. * @see #setContentHandler
  279. */
  280. public ContentHandler getContentHandler ();
  281. /**
  282. * Allow an application to register an error event handler.
  283. *
  284. * <p>If the application does not register an error handler, all
  285. * error events reported by the SAX parser will be silently
  286. * ignored; however, normal processing may not continue. It is
  287. * highly recommended that all SAX applications implement an
  288. * error handler to avoid unexpected bugs.</p>
  289. *
  290. * <p>Applications may register a new or different handler in the
  291. * middle of a parse, and the SAX parser must begin using the new
  292. * handler immediately.</p>
  293. *
  294. * @param handler The error handler.
  295. * @exception java.lang.NullPointerException If the handler
  296. * argument is null.
  297. * @see #getErrorHandler
  298. */
  299. public void setErrorHandler (ErrorHandler handler);
  300. /**
  301. * Return the current error handler.
  302. *
  303. * @return The current error handler, or null if none
  304. * has been registered.
  305. * @see #setErrorHandler
  306. */
  307. public ErrorHandler getErrorHandler ();
  308. ////////////////////////////////////////////////////////////////////
  309. // Parsing.
  310. ////////////////////////////////////////////////////////////////////
  311. /**
  312. * Parse an XML document.
  313. *
  314. * <p>The application can use this method to instruct the XML
  315. * reader to begin parsing an XML document from any valid input
  316. * source (a character stream, a byte stream, or a URI).</p>
  317. *
  318. * <p>Applications may not invoke this method while a parse is in
  319. * progress (they should create a new XMLReader instead for each
  320. * nested XML document). Once a parse is complete, an
  321. * application may reuse the same XMLReader object, possibly with a
  322. * different input source.</p>
  323. *
  324. * <p>During the parse, the XMLReader will provide information
  325. * about the XML document through the registered event
  326. * handlers.</p>
  327. *
  328. * <p>This method is synchronous: it will not return until parsing
  329. * has ended. If a client application wants to terminate
  330. * parsing early, it should throw an exception.</p>
  331. *
  332. * @param source The input source for the top-level of the
  333. * XML document.
  334. * @exception org.xml.sax.SAXException Any SAX exception, possibly
  335. * wrapping another exception.
  336. * @exception java.io.IOException An IO exception from the parser,
  337. * possibly from a byte stream or character stream
  338. * supplied by the application.
  339. * @see org.xml.sax.InputSource
  340. * @see #parse(java.lang.String)
  341. * @see #setEntityResolver
  342. * @see #setDTDHandler
  343. * @see #setContentHandler
  344. * @see #setErrorHandler
  345. */
  346. public void parse (InputSource input)
  347. throws IOException, SAXException;
  348. /**
  349. * Parse an XML document from a system identifier (URI).
  350. *
  351. * <p>This method is a shortcut for the common case of reading a
  352. * document from a system identifier. It is the exact
  353. * equivalent of the following:</p>
  354. *
  355. * <pre>
  356. * parse(new InputSource(systemId));
  357. * </pre>
  358. *
  359. * <p>If the system identifier is a URL, it must be fully resolved
  360. * by the application before it is passed to the parser.</p>
  361. *
  362. * @param systemId The system identifier (URI).
  363. * @exception org.xml.sax.SAXException Any SAX exception, possibly
  364. * wrapping another exception.
  365. * @exception java.io.IOException An IO exception from the parser,
  366. * possibly from a byte stream or character stream
  367. * supplied by the application.
  368. * @see #parse(org.xml.sax.InputSource)
  369. */
  370. public void parse (String systemId)
  371. throws IOException, SAXException;
  372. }
  373. // end of XMLReader.java