libjava/org/xml/sax/XMLReader.java

   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
   6 // $Id: XMLReader.java,v 1.3.2.5 2002/01/29 21:34:14 dbrownell Exp $
   7
   8 package org.xml.sax;
   9
  10 import java.io.IOException;
  11
  12
  13 /**
  14  * Interface for reading an XML document using callbacks.
  15  *
  16  * <blockquote>
  17  * <em>This module, both source code and documentation, is in the
  18  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
  19  * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
  20  * for further information.
  21  * </blockquote>
  22  *
  23  * <p><strong>Note:</strong> despite its name, this interface does
  24  * <em>not</em> extend the standard Java {@link java.io.Reader Reader}
  25  * interface, because reading XML is a fundamentally different activity
  26  * than reading character data.</p>
  27  *
  28  * <p>XMLReader is the interface that an XML parser's SAX2 driver must
  29  * implement.  This interface allows an application to set and
  30  * query features and properties in the parser, to register
  31  * event handlers for document processing, and to initiate
  32  * a document parse.</p>
  33  *
  34  * <p>All SAX interfaces are assumed to be synchronous: the
  35  * {@link #parse parse} methods must not return until parsing
  36  * is complete, and readers must wait for an event-handler callback
  37  * to return before reporting the next event.</p>
  38  *
  39  * <p>This interface replaces the (now deprecated) SAX 1.0 {@link
  40  * org.xml.sax.Parser Parser} interface.  The XMLReader interface
  41  * contains two important enhancements over the old Parser
  42  * interface (as well as some minor ones):</p>
  43  *
  44  * <ol>
  45  * <li>it adds a standard way to query and set features and
  46  *  properties; and</li>
  47  * <li>it adds Namespace support, which is required for many
  48  *  higher-level XML standards.</li>
  49  * </ol>
  50  *
  51  * <p>There are adapters available to convert a SAX1 Parser to
  52  * a SAX2 XMLReader and vice-versa.</p>
  53  *
  54  * @since SAX 2.0
  55  * @author David Megginson
  56  * @version 2.0.1 (sax2r2)
  57  * @see org.xml.sax.XMLFilter
  58  * @see org.xml.sax.helpers.ParserAdapter
  59  * @see org.xml.sax.helpers.XMLReaderAdapter
  60  */
  61 public interface XMLReader
  62 {
  63
  64 \f
  65     ////////////////////////////////////////////////////////////////////
  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 \f
 216     ////////////////////////////////////////////////////////////////////
 217     // Event handlers.
 218     ////////////////////////////////////////////////////////////////////
 219
 220
 221     /**
 222      * Allow an application to register an entity resolver.
 223      *
 224      * <p>If the application does not register an entity resolver,
 225      * the XMLReader will perform its own default resolution.</p>
 226      *
 227      * <p>Applications may register a new or different resolver in the
 228      * middle of a parse, and the SAX parser must begin using the new
 229      * resolver immediately.</p>
 230      *
 231      * @param resolver The entity resolver.
 232      * @see #getEntityResolver
 233      */
 234     public void setEntityResolver (EntityResolver resolver);
 235
 236
 237     /**
 238      * Return the current entity resolver.
 239      *
 240      * @return The current entity resolver, or null if none
 241      *         has been registered.
 242      * @see #setEntityResolver
 243      */
 244     public EntityResolver getEntityResolver ();
 245
 246
 247     /**
 248      * Allow an application to register a DTD event handler.
 249      *
 250      * <p>If the application does not register a DTD handler, all DTD
 251      * events reported by the SAX parser will be silently ignored.</p>
 252      *
 253      * <p>Applications may register a new or different handler in the
 254      * middle of a parse, and the SAX parser must begin using the new
 255      * handler immediately.</p>
 256      *
 257      * @param handler The DTD handler.
 258      * @see #getDTDHandler
 259      */
 260     public void setDTDHandler (DTDHandler handler);
 261
 262
 263     /**
 264      * Return the current DTD handler.
 265      *
 266      * @return The current DTD handler, or null if none
 267      *         has been registered.
 268      * @see #setDTDHandler
 269      */
 270     public DTDHandler getDTDHandler ();
 271
 272
 273     /**
 274      * Allow an application to register a content event handler.
 275      *
 276      * <p>If the application does not register a content handler, all
 277      * content events reported by the SAX parser will be silently
 278      * ignored.</p>
 279      *
 280      * <p>Applications may register a new or different handler in the
 281      * middle of a parse, and the SAX parser must begin using the new
 282      * handler immediately.</p>
 283      *
 284      * @param handler The content handler.
 285      * @see #getContentHandler
 286      */
 287     public void setContentHandler (ContentHandler handler);
 288
 289
 290     /**
 291      * Return the current content handler.
 292      *
 293      * @return The current content handler, or null if none
 294      *         has been registered.
 295      * @see #setContentHandler
 296      */
 297     public ContentHandler getContentHandler ();
 298
 299
 300     /**
 301      * Allow an application to register an error event handler.
 302      *
 303      * <p>If the application does not register an error handler, all
 304      * error events reported by the SAX parser will be silently
 305      * ignored; however, normal processing may not continue.  It is
 306      * highly recommended that all SAX applications implement an
 307      * error handler to avoid unexpected bugs.</p>
 308      *
 309      * <p>Applications may register a new or different handler in the
 310      * middle of a parse, and the SAX parser must begin using the new
 311      * handler immediately.</p>
 312      *
 313      * @param handler The error handler.
 314      * @see #getErrorHandler
 315      */
 316     public void setErrorHandler (ErrorHandler handler);
 317
 318
 319     /**
 320      * Return the current error handler.
 321      *
 322      * @return The current error handler, or null if none
 323      *         has been registered.
 324      * @see #setErrorHandler
 325      */
 326     public ErrorHandler getErrorHandler ();
 327
 328
 329 \f
 330     ////////////////////////////////////////////////////////////////////
 331     // Parsing.
 332     ////////////////////////////////////////////////////////////////////
 333
 334     /**
 335      * Parse an XML document.
 336      *
 337      * <p>The application can use this method to instruct the XML
 338      * reader to begin parsing an XML document from any valid input
 339      * source (a character stream, a byte stream, or a URI).</p>
 340      *
 341      * <p>Applications may not invoke this method while a parse is in
 342      * progress (they should create a new XMLReader instead for each
 343      * nested XML document).  Once a parse is complete, an
 344      * application may reuse the same XMLReader object, possibly with a
 345      * different input source.</p>
 346      *
 347      * <p>During the parse, the XMLReader will provide information
 348      * about the XML document through the registered event
 349      * handlers.</p>
 350      *
 351      * <p>This method is synchronous: it will not return until parsing
 352      * has ended.  If a client application wants to terminate
 353      * parsing early, it should throw an exception.</p>
 354      *
 355      * @param source The input source for the top-level of the
 356      *        XML document.
 357      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 358      *            wrapping another exception.
 359      * @exception java.io.IOException An IO exception from the parser,
 360      *            possibly from a byte stream or character stream
 361      *            supplied by the application.
 362      * @see org.xml.sax.InputSource
 363      * @see #parse(java.lang.String)
 364      * @see #setEntityResolver
 365      * @see #setDTDHandler
 366      * @see #setContentHandler
 367      * @see #setErrorHandler
 368      */
 369     public void parse (InputSource input)
 370         throws IOException, SAXException;
 371
 372
 373     /**
 374      * Parse an XML document from a system identifier (URI).
 375      *
 376      * <p>This method is a shortcut for the common case of reading a
 377      * document from a system identifier.  It is the exact
 378      * equivalent of the following:</p>
 379      *
 380      * <pre>
 381      * parse(new InputSource(systemId));
 382      * </pre>
 383      *
 384      * <p>If the system identifier is a URL, it must be fully resolved
 385      * by the application before it is passed to the parser.</p>
 386      *
 387      * @param systemId The system identifier (URI).
 388      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 389      *            wrapping another exception.
 390      * @exception java.io.IOException An IO exception from the parser,
 391      *            possibly from a byte stream or character stream
 392      *            supplied by the application.
 393      * @see #parse(org.xml.sax.InputSource)
 394      */
 395     public void parse (String systemId)
 396         throws IOException, SAXException;
 397
 398 }