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  ;
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 }
405
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags