Source for org.xml.sax.XMLReader

   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: }