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