KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > xml > sax > XMLReader


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.2.22.1 2004/05/01 08:34:40 jsuttor Exp $
6

7 package org.xml.sax;
8
9 import java.io.IOException JavaDoc;
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 JavaDoc name)
126         throws SAXNotRecognizedException JavaDoc, SAXNotSupportedException JavaDoc;
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 JavaDoc name, boolean value)
153     throws SAXNotRecognizedException JavaDoc, SAXNotSupportedException JavaDoc;
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 JavaDoc getProperty (String JavaDoc name)
182     throws SAXNotRecognizedException JavaDoc, SAXNotSupportedException JavaDoc;
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 JavaDoc name, Object JavaDoc value)
211     throws SAXNotRecognizedException JavaDoc, SAXNotSupportedException JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc input)
376     throws IOException JavaDoc, SAXException JavaDoc;
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 JavaDoc systemId)
402     throws IOException JavaDoc, SAXException JavaDoc;
403
404 }
405
Popular Tags