| Frames | No Frames |
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.1 2004/12/23 22:38:42 mark 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 401: public void parse (String systemId) 402: throws IOException, SAXException; 403: 404: }