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 226184 2005-04-08 10:53:24Z neeraj $
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 }