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.1 2004/12/23 22:38:42 mark Exp $
006    
007    package org.xml.sax;
008    
009    import 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     */
060    public 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    }