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.9 2004/04/26 17:34:34 dmegginson Exp $
6
7package org.xml.sax;
8
9import 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 */
60public 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}
405