- 001
// XMLReader.java - read an XML document. - 002// http://www.saxproject.org
- 003// Written by David Megginson
- 004// NO WARRANTY! This class is in the Public Domain.
- 005// $Id: XMLReader.java,v 1.3 2004/11/03 22:55:32 jsuttor 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 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
- 019 * for further information.
- 020 * </blockquote>
- 021 *
- 022 * <p><strong>Note:</strong> despite its name, this interface does
- 023 * <em>not</em> extend the standard Java {@link java.io.Reader Reader}
- 024 * interface, because reading XML is a fundamentally different activity
- 025 * than reading character data.</p>
- 026 *
- 027 * <p>XMLReader is the interface that an XML parser's SAX2 driver must
- 028 * implement. This interface allows an application to set and
- 029 * query features and properties in the parser, to register
- 030 * event handlers for document processing, and to initiate
- 031 * a document parse.</p>
- 032 *
- 033 * <p>All SAX interfaces are assumed to be synchronous: the
- 034 * {@link #parse parse} methods must not return until parsing
- 035 * is complete, and readers must wait for an event-handler callback
- 036 * to return before reporting the next event.</p>
- 037 *
- 038 * <p>This interface replaces the (now deprecated) SAX 1.0 {@link
- 039 * org.xml.sax.Parser Parser} interface. The XMLReader interface
- 040 * contains two important enhancements over the old Parser
- 041 * interface (as well as some minor ones):</p>
- 042 *
- 043 * <ol>
- 044 * <li>it adds a standard way to query and set features and
- 045 * properties; and</li>
- 046 * <li>it adds Namespace support, which is required for many
- 047 * higher-level XML standards.</li>
- 048 * </ol>
- 049 *
- 050 * <p>There are adapters available to convert a SAX1 Parser to
- 051 * a SAX2 XMLReader and vice-versa.</p>
- 052 *
- 053 * @since SAX 2.0
- 054 * @author David Megginson
- 055 * @version 2.0.1+ (sax2r3pre1)
- 056 * @see org.xml.sax.XMLFilter
- 057 * @see org.xml.sax.helpers.ParserAdapter
- 058 * @see org.xml.sax.helpers.XMLReaderAdapter
- 059
*/ - 060public interface XMLReader
- 061{
- 062
- 063
- 064 ////////////////////////////////////////////////////////////////////
- 065 // Configuration.
- 066 ////////////////////////////////////////////////////////////////////
- 067
- 068
- 069 /**
- 070 * Look up the value of a feature flag.
- 071 *
- 072 * <p>The feature name is any fully-qualified URI. It is
- 073 * possible for an XMLReader to recognize a feature name but
- 074 * temporarily be unable to return its value.
- 075 * Some feature values may be available only in specific
- 076 * contexts, such as before, during, or after a parse.
- 077 * Also, some feature values may not be programmatically accessible.
- 078 * (In the case of an adapter for SAX1 {@link Parser}, there is no
- 079 * implementation-independent way to expose whether the underlying
- 080 * parser is performing validation, expanding external entities,
- 081 * and so forth.) </p>
- 082 *
- 083 * <p>All XMLReaders are required to recognize the
- 084 * http://xml.org/sax/features/namespaces and the
- 085 * http://xml.org/sax/features/namespace-prefixes feature names.</p>
- 086 *
- 087 * <p>Typical usage is something like this:</p>
- 088 *
- 089 * <pre>
- 090 * XMLReader r = new MySAXDriver();
- 091 *
- 092 * // try to activate validation
- 093 * try {
- 094 * r.setFeature("http://xml.org/sax/features/validation", true);
- 095 * } catch (SAXException e) {
- 096 * System.err.println("Cannot activate validation.");
- 097 * }
- 098 *
- 099 * // 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}
