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 //////////////////////////////////////////////////////////////////// 65 // Configuration. 66 //////////////////////////////////////////////////////////////////// 67 68 69 /** 70 * Look up the value of a feature flag. 71 * 72 * <p>The feature name is any fully-qualified URI. It is 73 * possible for an XMLReader to recognize a feature name but 74 * temporarily be unable to return its value. 75 * Some feature values may be available only in specific 76 * contexts, such as before, during, or after a parse. 77 * Also, some feature values may not be programmatically accessible. 78 * (In the case of an adapter for SAX1 {@link Parser}, there is no 79 * implementation-independent way to expose whether the underlying 80 * parser is performing validation, expanding external entities, 81 * and so forth.) </p> 82 * 83 * <p>All XMLReaders are required to recognize the 84 * http://xml.org/sax/features/namespaces and the 85 * http://xml.org/sax/features/namespace-prefixes feature names.</p> 86 * 87 * <p>Typical usage is something like this:</p> 88 * 89 * <pre> 90 * XMLReader r = new MySAXDriver(); 91 * 92 * // try to activate validation 93 * try { 94 * r.setFeature("http://xml.org/sax/features/validation", true); 95 * } catch (SAXException e) { 96 * System.err.println("Cannot activate validation."); 97 * } 98 * 99 * // register event handlers 100 * r.setContentHandler(new MyContentHandler()); 101 * r.setErrorHandler(new MyErrorHandler()); 102 * 103 * // parse the first document 104 * try { 105 * r.parse("http://www.foo.com/mydoc.xml"); 106 * } catch (IOException e) { 107 * System.err.println("I/O exception reading XML document"); 108 * } catch (SAXException e) { 109 * System.err.println("XML exception reading document."); 110 * } 111 * </pre> 112 * 113 * <p>Implementors are free (and encouraged) to invent their own features, 114 * using names built on their own URIs.</p> 115 * 116 * @param name The feature name, which is a fully-qualified URI. 117 * @return The current value of the feature (true or false). 118 * @exception org.xml.sax.SAXNotRecognizedException If the feature 119 * value can't be assigned or retrieved. 120 * @exception org.xml.sax.SAXNotSupportedException When the 121 * XMLReader recognizes the feature name but 122 * cannot determine its value at this time. 123 * @see #setFeature 124 */ getFeature(String name)125 public boolean getFeature (String name) 126 throws SAXNotRecognizedException, SAXNotSupportedException; 127 128 129 /** 130 * Set the value of a feature flag. 131 * 132 * <p>The feature name is any fully-qualified URI. It is 133 * possible for an XMLReader to expose a feature value but 134 * to be unable to change the current value. 135 * Some feature values may be immutable or mutable only 136 * in specific contexts, such as before, during, or after 137 * a parse.</p> 138 * 139 * <p>All XMLReaders are required to support setting 140 * http://xml.org/sax/features/namespaces to true and 141 * http://xml.org/sax/features/namespace-prefixes to false.</p> 142 * 143 * @param name The feature name, which is a fully-qualified URI. 144 * @param value The requested value of the feature (true or false). 145 * @exception org.xml.sax.SAXNotRecognizedException If the feature 146 * value can't be assigned or retrieved. 147 * @exception org.xml.sax.SAXNotSupportedException When the 148 * XMLReader recognizes the feature name but 149 * cannot set the requested value. 150 * @see #getFeature 151 */ setFeature(String name, boolean value)152 public void setFeature (String name, boolean value) 153 throws SAXNotRecognizedException, SAXNotSupportedException; 154 155 156 /** 157 * Look up the value of a property. 158 * 159 * <p>The property name is any fully-qualified URI. It is 160 * possible for an XMLReader to recognize a property name but 161 * temporarily be unable to return its value. 162 * Some property values may be available only in specific 163 * contexts, such as before, during, or after a parse.</p> 164 * 165 * <p>XMLReaders are not required to recognize any specific 166 * property names, though an initial core set is documented for 167 * SAX2.</p> 168 * 169 * <p>Implementors are free (and encouraged) to invent their own properties, 170 * using names built on their own URIs.</p> 171 * 172 * @param name The property name, which is a fully-qualified URI. 173 * @return The current value of the property. 174 * @exception org.xml.sax.SAXNotRecognizedException If the property 175 * value can't be assigned or retrieved. 176 * @exception org.xml.sax.SAXNotSupportedException When the 177 * XMLReader recognizes the property name but 178 * cannot determine its value at this time. 179 * @see #setProperty 180 */ getProperty(String name)181 public Object getProperty (String name) 182 throws SAXNotRecognizedException, SAXNotSupportedException; 183 184 185 /** 186 * Set the value of a property. 187 * 188 * <p>The property name is any fully-qualified URI. It is 189 * possible for an XMLReader to recognize a property name but 190 * to be unable to change the current value. 191 * Some property values may be immutable or mutable only 192 * in specific contexts, such as before, during, or after 193 * a parse.</p> 194 * 195 * <p>XMLReaders are not required to recognize setting 196 * any specific property names, though a core set is defined by 197 * SAX2.</p> 198 * 199 * <p>This method is also the standard mechanism for setting 200 * extended handlers.</p> 201 * 202 * @param name The property name, which is a fully-qualified URI. 203 * @param value The requested value for the property. 204 * @exception org.xml.sax.SAXNotRecognizedException If the property 205 * value can't be assigned or retrieved. 206 * @exception org.xml.sax.SAXNotSupportedException When the 207 * XMLReader recognizes the property name but 208 * cannot set the requested value. 209 */ setProperty(String name, Object value)210 public void setProperty (String name, Object value) 211 throws SAXNotRecognizedException, SAXNotSupportedException; 212 213 214 215 //////////////////////////////////////////////////////////////////// 216 // Event handlers. 217 //////////////////////////////////////////////////////////////////// 218 219 220 /** 221 * Allow an application to register an entity resolver. 222 * 223 * <p>If the application does not register an entity resolver, 224 * the XMLReader will perform its own default resolution.</p> 225 * 226 * <p>Applications may register a new or different resolver in the 227 * middle of a parse, and the SAX parser must begin using the new 228 * resolver immediately.</p> 229 * 230 * @param resolver The entity resolver. 231 * @see #getEntityResolver 232 */ setEntityResolver(EntityResolver resolver)233 public void setEntityResolver (EntityResolver resolver); 234 235 236 /** 237 * Return the current entity resolver. 238 * 239 * @return The current entity resolver, or null if none 240 * has been registered. 241 * @see #setEntityResolver 242 */ getEntityResolver()243 public EntityResolver getEntityResolver (); 244 245 246 /** 247 * Allow an application to register a DTD event handler. 248 * 249 * <p>If the application does not register a DTD handler, all DTD 250 * events reported by the SAX parser will be silently ignored.</p> 251 * 252 * <p>Applications may register a new or different handler in the 253 * middle of a parse, and the SAX parser must begin using the new 254 * handler immediately.</p> 255 * 256 * @param handler The DTD handler. 257 * @see #getDTDHandler 258 */ setDTDHandler(DTDHandler handler)259 public void setDTDHandler (DTDHandler handler); 260 261 262 /** 263 * Return the current DTD handler. 264 * 265 * @return The current DTD handler, or null if none 266 * has been registered. 267 * @see #setDTDHandler 268 */ getDTDHandler()269 public DTDHandler getDTDHandler (); 270 271 272 /** 273 * Allow an application to register a content event handler. 274 * 275 * <p>If the application does not register a content handler, all 276 * content events reported by the SAX parser will be silently 277 * ignored.</p> 278 * 279 * <p>Applications may register a new or different handler in the 280 * middle of a parse, and the SAX parser must begin using the new 281 * handler immediately.</p> 282 * 283 * @param handler The content handler. 284 * @see #getContentHandler 285 */ setContentHandler(ContentHandler handler)286 public void setContentHandler (ContentHandler handler); 287 288 289 /** 290 * Return the current content handler. 291 * 292 * @return The current content handler, or null if none 293 * has been registered. 294 * @see #setContentHandler 295 */ getContentHandler()296 public ContentHandler getContentHandler (); 297 298 299 /** 300 * Allow an application to register an error event handler. 301 * 302 * <p>If the application does not register an error handler, all 303 * error events reported by the SAX parser will be silently 304 * ignored; however, normal processing may not continue. It is 305 * highly recommended that all SAX applications implement an 306 * error handler to avoid unexpected bugs.</p> 307 * 308 * <p>Applications may register a new or different handler in the 309 * middle of a parse, and the SAX parser must begin using the new 310 * handler immediately.</p> 311 * 312 * @param handler The error handler. 313 * @see #getErrorHandler 314 */ setErrorHandler(ErrorHandler handler)315 public void setErrorHandler (ErrorHandler handler); 316 317 318 /** 319 * Return the current error handler. 320 * 321 * @return The current error handler, or null if none 322 * has been registered. 323 * @see #setErrorHandler 324 */ getErrorHandler()325 public ErrorHandler getErrorHandler (); 326 327 328 329 //////////////////////////////////////////////////////////////////// 330 // Parsing. 331 //////////////////////////////////////////////////////////////////// 332 333 /** 334 * Parse an XML document. 335 * 336 * <p>The application can use this method to instruct the XML 337 * reader to begin parsing an XML document from any valid input 338 * source (a character stream, a byte stream, or a URI).</p> 339 * 340 * <p>Applications may not invoke this method while a parse is in 341 * progress (they should create a new XMLReader instead for each 342 * nested XML document). Once a parse is complete, an 343 * application may reuse the same XMLReader object, possibly with a 344 * different input source. 345 * Configuration of the XMLReader object (such as handler bindings and 346 * values established for feature flags and properties) is unchanged 347 * by completion of a parse, unless the definition of that aspect of 348 * the configuration explicitly specifies other behavior. 349 * (For example, feature flags or properties exposing 350 * characteristics of the document being parsed.) 351 * </p> 352 * 353 * <p>During the parse, the XMLReader will provide information 354 * about the XML document through the registered event 355 * handlers.</p> 356 * 357 * <p>This method is synchronous: it will not return until parsing 358 * has ended. If a client application wants to terminate 359 * parsing early, it should throw an exception.</p> 360 * 361 * @param input The input source for the top-level of the 362 * XML document. 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 org.xml.sax.InputSource 369 * @see #parse(java.lang.String) 370 * @see #setEntityResolver 371 * @see #setDTDHandler 372 * @see #setContentHandler 373 * @see #setErrorHandler 374 */ parse(InputSource input)375 public void parse (InputSource input) 376 throws IOException, SAXException; 377 378 379 /** 380 * Parse an XML document from a system identifier (URI). 381 * 382 * <p>This method is a shortcut for the common case of reading a 383 * document from a system identifier. It is the exact 384 * equivalent of the following:</p> 385 * 386 * <pre> 387 * parse(new InputSource(systemId)); 388 * </pre> 389 * 390 * <p>If the system identifier is a URL, it must be fully resolved 391 * by the application before it is passed to the parser.</p> 392 * 393 * @param systemId The system identifier (URI). 394 * @exception org.xml.sax.SAXException Any SAX exception, possibly 395 * wrapping another exception. 396 * @exception java.io.IOException An IO exception from the parser, 397 * possibly from a byte stream or character stream 398 * supplied by the application. 399 * @see #parse(org.xml.sax.InputSource) 400 */ parse(String systemId)401 public void parse (String systemId) 402 throws IOException, SAXException; 403 404 } 405