libjava/external/sax/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 // $Id: XMLReader.java,v 1.1 2005/02/02 00:41:51 tromey 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 \f
  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 \f
 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 \f
 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 }