001// XMLReader.java - read an XML document. 002// Written by David Megginson, sax@megginson.com 003// NO WARRANTY! This class is in the Public Domain. 004 005// $Id: XMLReader.java,v 1.1 2001/03/05 21:40:06 jstrachan Exp $ 006 007package org.xml.sax; 008 009import java.io.IOException; 010 011 012/** 013 * Interface for reading an XML document using callbacks. 014 * 015 * <blockquote> 016 * <em>This module, both source code and documentation, is in the 017 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 018 * </blockquote> 019 * 020 * <p><strong>Note:</strong> despite its name, this interface does 021 * <em>not</em> extend the standard Java {@link java.io.Reader Reader} 022 * interface, because reading XML is a fundamentally different activity 023 * than reading character data.</p> 024 * 025 * <p>XMLReader is the interface that an XML parser's SAX2 driver must 026 * implement. This interface allows an application to set and 027 * query features and properties in the parser, to register 028 * event handlers for document processing, and to initiate 029 * a document parse.</p> 030 * 031 * <p>All SAX interfaces are assumed to be synchronous: the 032 * {@link #parse parse} methods must not return until parsing 033 * is complete, and readers must wait for an event-handler callback 034 * to return before reporting the next event.</p> 035 * 036 * <p>This interface replaces the (now deprecated) SAX 1.0 {@link 037 * org.xml.sax.Parser Parser} interface. The XMLReader interface 038 * contains two important enhancements over the old Parser 039 * interface:</p> 040 * 041 * <ol> 042 * <li>it adds a standard way to query and set features and 043 * properties; and</li> 044 * <li>it adds Namespace support, which is required for many 045 * higher-level XML standards.</li> 046 * </ol> 047 * 048 * <p>There are adapters available to convert a SAX1 Parser to 049 * a SAX2 XMLReader and vice-versa.</p> 050 * 051 * @since SAX 2.0 052 * @author David Megginson, 053 * <a href="mailto:sax@megginson.com">sax@megginson.com</a> 054 * @version 2.0 055 * @see org.xml.sax.XMLFilter 056 * @see org.xml.sax.helpers.ParserAdapter 057 * @see org.xml.sax.helpers.XMLReaderAdapter 058 */ 059public interface XMLReader 060{ 061 062 063 //////////////////////////////////////////////////////////////////// 064 // Configuration. 065 //////////////////////////////////////////////////////////////////// 066 067 068 /** 069 * Look up the value of a feature. 070 * 071 * <p>The feature name is any fully-qualified URI. It is 072 * possible for an XMLReader to recognize a feature name but 073 * to be unable to return its value; this is especially true 074 * in the case of an adapter for a SAX1 Parser, which has 075 * no way of knowing whether the underlying parser is 076 * performing validation or expanding external entities.</p> 077 * 078 * <p>All XMLReaders are required to recognize the 079 * http://xml.org/sax/features/namespaces and the 080 * http://xml.org/sax/features/namespace-prefixes feature names.</p> 081 * 082 * <p>Some feature values may be available only in specific 083 * contexts, such as before, during, or after a parse.</p> 084 * 085 * <p>Typical usage is something like this:</p> 086 * 087 * <pre> 088 * XMLReader r = new MySAXDriver(); 089 * 090 * // try to activate validation 091 * try { 092 * r.setFeature("http://xml.org/sax/features/validation", true); 093 * } catch (SAXException e) { 094 * System.err.println("Cannot activate validation."); 095 * } 096 * 097 * // register event handlers 098 * r.setContentHandler(new MyContentHandler()); 099 * r.setErrorHandler(new MyErrorHandler()); 100 * 101 * // parse the first document 102 * try { 103 * r.parse("http://www.foo.com/mydoc.xml"); 104 * } catch (IOException e) { 105 * System.err.println("I/O exception reading XML document"); 106 * } catch (SAXException e) { 107 * System.err.println("XML exception reading document."); 108 * } 109 * </pre> 110 * 111 * <p>Implementors are free (and encouraged) to invent their own features, 112 * using names built on their own URIs.</p> 113 * 114 * @param name The feature name, which is a fully-qualified URI. 115 * @return The current state of the feature (true or false). 116 * @exception org.xml.sax.SAXNotRecognizedException When the 117 * XMLReader does not recognize the feature name. 118 * @exception org.xml.sax.SAXNotSupportedException When the 119 * XMLReader recognizes the feature name but 120 * cannot determine its value at this time. 121 * @see #setFeature 122 */ 123 public boolean getFeature (String name) 124 throws SAXNotRecognizedException, SAXNotSupportedException; 125 126 127 /** 128 * Set the state of a feature. 129 * 130 * <p>The feature name is any fully-qualified URI. It is 131 * possible for an XMLReader to recognize a feature name but 132 * to be unable to set its value; this is especially true 133 * in the case of an adapter for a SAX1 {@link org.xml.sax.Parser Parser}, 134 * which has no way of affecting whether the underlying parser is 135 * validating, for example.</p> 136 * 137 * <p>All XMLReaders are required to support setting 138 * http://xml.org/sax/features/namespaces to true and 139 * http://xml.org/sax/features/namespace-prefixes to false.</p> 140 * 141 * <p>Some feature values may be immutable or mutable only 142 * in specific contexts, such as before, during, or after 143 * a parse.</p> 144 * 145 * @param name The feature name, which is a fully-qualified URI. 146 * @param state The requested state of the feature (true or false). 147 * @exception org.xml.sax.SAXNotRecognizedException When the 148 * XMLReader does not recognize the feature name. 149 * @exception org.xml.sax.SAXNotSupportedException When the 150 * XMLReader recognizes the feature name but 151 * cannot set the requested value. 152 * @see #getFeature 153 */ 154 public void setFeature (String name, boolean value) 155 throws SAXNotRecognizedException, SAXNotSupportedException; 156 157 158 /** 159 * Look up the value of a property. 160 * 161 * <p>The property name is any fully-qualified URI. It is 162 * possible for an XMLReader to recognize a property name but 163 * to be unable to return its state; this is especially true 164 * in the case of an adapter for a SAX1 {@link org.xml.sax.Parser 165 * Parser}.</p> 166 * 167 * <p>XMLReaders are not required to recognize any specific 168 * property names, though an initial core set is documented for 169 * SAX2.</p> 170 * 171 * <p>Some property values may be available only in specific 172 * contexts, such as before, during, or after a parse.</p> 173 * 174 * <p>Implementors are free (and encouraged) to invent their own properties, 175 * using names built on their own URIs.</p> 176 * 177 * @param name The property name, which is a fully-qualified URI. 178 * @return The current value of the property. 179 * @exception org.xml.sax.SAXNotRecognizedException When the 180 * XMLReader does not recognize the property name. 181 * @exception org.xml.sax.SAXNotSupportedException When the 182 * XMLReader recognizes the property name but 183 * cannot determine its value at this time. 184 * @see #setProperty 185 */ 186 public Object getProperty (String name) 187 throws SAXNotRecognizedException, SAXNotSupportedException; 188 189 190 /** 191 * Set the value of a property. 192 * 193 * <p>The property name is any fully-qualified URI. It is 194 * possible for an XMLReader to recognize a property name but 195 * to be unable to set its value; this is especially true 196 * in the case of an adapter for a SAX1 {@link org.xml.sax.Parser 197 * Parser}.</p> 198 * 199 * <p>XMLReaders are not required to recognize setting 200 * any specific property names, though a core set is provided with 201 * SAX2.</p> 202 * 203 * <p>Some property values may be immutable or mutable only 204 * in specific contexts, such as before, during, or after 205 * a parse.</p> 206 * 207 * <p>This method is also the standard mechanism for setting 208 * extended handlers.</p> 209 * 210 * @param name The property name, which is a fully-qualified URI. 211 * @param state The requested value for the property. 212 * @exception org.xml.sax.SAXNotRecognizedException When the 213 * XMLReader does not recognize the property name. 214 * @exception org.xml.sax.SAXNotSupportedException When the 215 * XMLReader recognizes the property name but 216 * cannot set the requested value. 217 */ 218 public void setProperty (String name, Object value) 219 throws SAXNotRecognizedException, SAXNotSupportedException; 220 221 222 223 //////////////////////////////////////////////////////////////////// 224 // Event handlers. 225 //////////////////////////////////////////////////////////////////// 226 227 228 /** 229 * Allow an application to register an entity resolver. 230 * 231 * <p>If the application does not register an entity resolver, 232 * the XMLReader will perform its own default resolution.</p> 233 * 234 * <p>Applications may register a new or different resolver in the 235 * middle of a parse, and the SAX parser must begin using the new 236 * resolver immediately.</p> 237 * 238 * @param resolver The entity resolver. 239 * @exception java.lang.NullPointerException If the resolver 240 * argument is null. 241 * @see #getEntityResolver 242 */ 243 public void setEntityResolver (EntityResolver resolver); 244 245 246 /** 247 * Return the current entity resolver. 248 * 249 * @return The current entity resolver, or null if none 250 * has been registered. 251 * @see #setEntityResolver 252 */ 253 public EntityResolver getEntityResolver (); 254 255 256 /** 257 * Allow an application to register a DTD event handler. 258 * 259 * <p>If the application does not register a DTD handler, all DTD 260 * events reported by the SAX parser will be silently ignored.</p> 261 * 262 * <p>Applications may register a new or different handler in the 263 * middle of a parse, and the SAX parser must begin using the new 264 * handler immediately.</p> 265 * 266 * @param handler The DTD handler. 267 * @exception java.lang.NullPointerException If the handler 268 * argument is null. 269 * @see #getDTDHandler 270 */ 271 public void setDTDHandler (DTDHandler handler); 272 273 274 /** 275 * Return the current DTD handler. 276 * 277 * @return The current DTD handler, or null if none 278 * has been registered. 279 * @see #setDTDHandler 280 */ 281 public DTDHandler getDTDHandler (); 282 283 284 /** 285 * Allow an application to register a content event handler. 286 * 287 * <p>If the application does not register a content handler, all 288 * content events reported by the SAX parser will be silently 289 * ignored.</p> 290 * 291 * <p>Applications may register a new or different handler in the 292 * middle of a parse, and the SAX parser must begin using the new 293 * handler immediately.</p> 294 * 295 * @param handler The content handler. 296 * @exception java.lang.NullPointerException If the handler 297 * argument is null. 298 * @see #getContentHandler 299 */ 300 public void setContentHandler (ContentHandler handler); 301 302 303 /** 304 * Return the current content handler. 305 * 306 * @return The current content handler, or null if none 307 * has been registered. 308 * @see #setContentHandler 309 */ 310 public ContentHandler getContentHandler (); 311 312 313 /** 314 * Allow an application to register an error event handler. 315 * 316 * <p>If the application does not register an error handler, all 317 * error events reported by the SAX parser will be silently 318 * ignored; however, normal processing may not continue. It is 319 * highly recommended that all SAX applications implement an 320 * error handler to avoid unexpected bugs.</p> 321 * 322 * <p>Applications may register a new or different handler in the 323 * middle of a parse, and the SAX parser must begin using the new 324 * handler immediately.</p> 325 * 326 * @param handler The error handler. 327 * @exception java.lang.NullPointerException If the handler 328 * argument is null. 329 * @see #getErrorHandler 330 */ 331 public void setErrorHandler (ErrorHandler handler); 332 333 334 /** 335 * Return the current error handler. 336 * 337 * @return The current error handler, or null if none 338 * has been registered. 339 * @see #setErrorHandler 340 */ 341 public ErrorHandler getErrorHandler (); 342 343 344 345 //////////////////////////////////////////////////////////////////// 346 // Parsing. 347 //////////////////////////////////////////////////////////////////// 348 349 /** 350 * Parse an XML document. 351 * 352 * <p>The application can use this method to instruct the XML 353 * reader to begin parsing an XML document from any valid input 354 * source (a character stream, a byte stream, or a URI).</p> 355 * 356 * <p>Applications may not invoke this method while a parse is in 357 * progress (they should create a new XMLReader instead for each 358 * nested XML document). Once a parse is complete, an 359 * application may reuse the same XMLReader object, possibly with a 360 * different input source.</p> 361 * 362 * <p>During the parse, the XMLReader will provide information 363 * about the XML document through the registered event 364 * handlers.</p> 365 * 366 * <p>This method is synchronous: it will not return until parsing 367 * has ended. If a client application wants to terminate 368 * parsing early, it should throw an exception.</p> 369 * 370 * @param source The input source for the top-level of the 371 * XML document. 372 * @exception org.xml.sax.SAXException Any SAX exception, possibly 373 * wrapping another exception. 374 * @exception java.io.IOException An IO exception from the parser, 375 * possibly from a byte stream or character stream 376 * supplied by the application. 377 * @see org.xml.sax.InputSource 378 * @see #parse(java.lang.String) 379 * @see #setEntityResolver 380 * @see #setDTDHandler 381 * @see #setContentHandler 382 * @see #setErrorHandler 383 */ 384 public void parse (InputSource input) 385 throws IOException, SAXException; 386 387 388 /** 389 * Parse an XML document from a system identifier (URI). 390 * 391 * <p>This method is a shortcut for the common case of reading a 392 * document from a system identifier. It is the exact 393 * equivalent of the following:</p> 394 * 395 * <pre> 396 * parse(new InputSource(systemId)); 397 * </pre> 398 * 399 * <p>If the system identifier is a URL, it must be fully resolved 400 * by the application before it is passed to the parser.</p> 401 * 402 * @param systemId The system identifier (URI). 403 * @exception org.xml.sax.SAXException Any SAX exception, possibly 404 * wrapping another exception. 405 * @exception java.io.IOException An IO exception from the parser, 406 * possibly from a byte stream or character stream 407 * supplied by the application. 408 * @see #parse(org.xml.sax.InputSource) 409 */ 410 public void parse (String systemId) 411 throws IOException, SAXException; 412 413} 414 415// end of XMLReader.java