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 
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      */
getFeature(String name)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      */
setFeature(String name, boolean value)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      */
getProperty(String name)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      */
setProperty(String name, Object value)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      */
setEntityResolver(EntityResolver resolver)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      */
getEntityResolver()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      */
setDTDHandler(DTDHandler handler)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      */
getDTDHandler()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      */
setContentHandler(ContentHandler handler)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      */
getContentHandler()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      */
setErrorHandler(ErrorHandler handler)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      */
getErrorHandler()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      */
parse(InputSource input)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      */
parse(String systemId)401     public void parse (String systemId)
402     throws IOException, SAXException;
403 
404 }
405