View Javadoc
1   /*
2    * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  // XMLReader.java - read an XML document.
27  // http://www.saxproject.org
28  // Written by David Megginson
29  // NO WARRANTY!  This class is in the Public Domain.
30  // $Id: XMLReader.java,v 1.3 2004/11/03 22:55:32 jsuttor Exp $
31  
32  package org.xml.sax;
33  
34  import java.io.IOException;
35  
36  
37  /**
38   * Interface for reading an XML document using callbacks.
39   *
40   * <blockquote>
41   * <em>This module, both source code and documentation, is in the
42   * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
43   * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>;
44   * for further information.
45   * </blockquote>
46   *
47   * <p><strong>Note:</strong> despite its name, this interface does
48   * <em>not</em> extend the standard Java {@link java.io.Reader Reader}
49   * interface, because reading XML is a fundamentally different activity
50   * than reading character data.</p>
51   *
52   * <p>XMLReader is the interface that an XML parser's SAX2 driver must
53   * implement.  This interface allows an application to set and
54   * query features and properties in the parser, to register
55   * event handlers for document processing, and to initiate
56   * a document parse.</p>
57   *
58   * <p>All SAX interfaces are assumed to be synchronous: the
59   * {@link #parse parse} methods must not return until parsing
60   * is complete, and readers must wait for an event-handler callback
61   * to return before reporting the next event.</p>
62   *
63   * <p>This interface replaces the (now deprecated) SAX 1.0 {@link
64   * org.xml.sax.Parser Parser} interface.  The XMLReader interface
65   * contains two important enhancements over the old Parser
66   * interface (as well as some minor ones):</p>
67   *
68   * <ol>
69   * <li>it adds a standard way to query and set features and
70   *  properties; and</li>
71   * <li>it adds Namespace support, which is required for many
72   *  higher-level XML standards.</li>
73   * </ol>
74   *
75   * <p>There are adapters available to convert a SAX1 Parser to
76   * a SAX2 XMLReader and vice-versa.</p>
77   *
78   * @since SAX 2.0
79   * @author David Megginson
80   * @see org.xml.sax.XMLFilter
81   * @see org.xml.sax.helpers.ParserAdapter
82   * @see org.xml.sax.helpers.XMLReaderAdapter
83   */
84  public interface XMLReader
85  {
86  
87  
88      ////////////////////////////////////////////////////////////////////
89      // Configuration.
90      ////////////////////////////////////////////////////////////////////
91  
92  
93      /**
94       * Look up the value of a feature flag.
95       *
96       * <p>The feature name is any fully-qualified URI.  It is
97       * possible for an XMLReader to recognize a feature name but
98       * temporarily be unable to return its value.
99       * Some feature values may be available only in specific
100      * contexts, such as before, during, or after a parse.
101      * Also, some feature values may not be programmatically accessible.
102      * (In the case of an adapter for SAX1 {@link Parser}, there is no
103      * implementation-independent way to expose whether the underlying
104      * parser is performing validation, expanding external entities,
105      * and so forth.) </p>
106      *
107      * <p>All XMLReaders are required to recognize the
108      * http://xml.org/sax/features/namespaces and the
109      * http://xml.org/sax/features/namespace-prefixes feature names.</p>
110      *
111      * <p>Typical usage is something like this:</p>
112      *
113      * <pre>
114      * XMLReader r = new MySAXDriver();
115      *
116      *                         // try to activate validation
117      * try {
118      *   r.setFeature("http://xml.org/sax/features/validation", true);
119      * } catch (SAXException e) {
120      *   System.err.println("Cannot activate validation.");
121      * }
122      *
123      *                         // register event handlers
124      * r.setContentHandler(new MyContentHandler());
125      * r.setErrorHandler(new MyErrorHandler());
126      *
127      *                         // parse the first document
128      * try {
129      *   r.parse("http://www.foo.com/mydoc.xml");
130      * } catch (IOException e) {
131      *   System.err.println("I/O exception reading XML document");
132      * } catch (SAXException e) {
133      *   System.err.println("XML exception reading document.");
134      * }
135      * </pre>
136      *
137      * <p>Implementors are free (and encouraged) to invent their own features,
138      * using names built on their own URIs.</p>
139      *
140      * @param name The feature name, which is a fully-qualified URI.
141      * @return The current value of the feature (true or false).
142      * @exception org.xml.sax.SAXNotRecognizedException If the feature
143      *            value can't be assigned or retrieved.
144      * @exception org.xml.sax.SAXNotSupportedException When the
145      *            XMLReader recognizes the feature name but
146      *            cannot determine its value at this time.
147      * @see #setFeature
148      */
149     public boolean getFeature (String name)
150         throws SAXNotRecognizedException, SAXNotSupportedException;
151 
152 
153     /**
154      * Set the value of a feature flag.
155      *
156      * <p>The feature name is any fully-qualified URI.  It is
157      * possible for an XMLReader to expose a feature value but
158      * to be unable to change the current value.
159      * Some feature values may be immutable or mutable only
160      * in specific contexts, such as before, during, or after
161      * a parse.</p>
162      *
163      * <p>All XMLReaders are required to support setting
164      * http://xml.org/sax/features/namespaces to true and
165      * http://xml.org/sax/features/namespace-prefixes to false.</p>
166      *
167      * @param name The feature name, which is a fully-qualified URI.
168      * @param value The requested value of the feature (true or false).
169      * @exception org.xml.sax.SAXNotRecognizedException If the feature
170      *            value can't be assigned or retrieved.
171      * @exception org.xml.sax.SAXNotSupportedException When the
172      *            XMLReader recognizes the feature name but
173      *            cannot set the requested value.
174      * @see #getFeature
175      */
176     public void setFeature (String name, boolean value)
177         throws SAXNotRecognizedException, SAXNotSupportedException;
178 
179 
180     /**
181      * Look up the value of a property.
182      *
183      * <p>The property name is any fully-qualified URI.  It is
184      * possible for an XMLReader to recognize a property name but
185      * temporarily be unable to return its value.
186      * Some property values may be available only in specific
187      * contexts, such as before, during, or after a parse.</p>
188      *
189      * <p>XMLReaders are not required to recognize any specific
190      * property names, though an initial core set is documented for
191      * SAX2.</p>
192      *
193      * <p>Implementors are free (and encouraged) to invent their own properties,
194      * using names built on their own URIs.</p>
195      *
196      * @param name The property name, which is a fully-qualified URI.
197      * @return The current value of the property.
198      * @exception org.xml.sax.SAXNotRecognizedException If the property
199      *            value can't be assigned or retrieved.
200      * @exception org.xml.sax.SAXNotSupportedException When the
201      *            XMLReader recognizes the property name but
202      *            cannot determine its value at this time.
203      * @see #setProperty
204      */
205     public Object getProperty (String name)
206         throws SAXNotRecognizedException, SAXNotSupportedException;
207 
208 
209     /**
210      * Set the value of a property.
211      *
212      * <p>The property name is any fully-qualified URI.  It is
213      * possible for an XMLReader to recognize a property name but
214      * to be unable to change the current value.
215      * Some property values may be immutable or mutable only
216      * in specific contexts, such as before, during, or after
217      * a parse.</p>
218      *
219      * <p>XMLReaders are not required to recognize setting
220      * any specific property names, though a core set is defined by
221      * SAX2.</p>
222      *
223      * <p>This method is also the standard mechanism for setting
224      * extended handlers.</p>
225      *
226      * @param name The property name, which is a fully-qualified URI.
227      * @param value The requested value for the property.
228      * @exception org.xml.sax.SAXNotRecognizedException If the property
229      *            value can't be assigned or retrieved.
230      * @exception org.xml.sax.SAXNotSupportedException When the
231      *            XMLReader recognizes the property name but
232      *            cannot set the requested value.
233      */
234     public void setProperty (String name, Object value)
235         throws SAXNotRecognizedException, SAXNotSupportedException;
236 
237 
238 
239     ////////////////////////////////////////////////////////////////////
240     // Event handlers.
241     ////////////////////////////////////////////////////////////////////
242 
243 
244     /**
245      * Allow an application to register an entity resolver.
246      *
247      * <p>If the application does not register an entity resolver,
248      * the XMLReader will perform its own default resolution.</p>
249      *
250      * <p>Applications may register a new or different resolver in the
251      * middle of a parse, and the SAX parser must begin using the new
252      * resolver immediately.</p>
253      *
254      * @param resolver The entity resolver.
255      * @see #getEntityResolver
256      */
257     public void setEntityResolver (EntityResolver resolver);
258 
259 
260     /**
261      * Return the current entity resolver.
262      *
263      * @return The current entity resolver, or null if none
264      *         has been registered.
265      * @see #setEntityResolver
266      */
267     public EntityResolver getEntityResolver ();
268 
269 
270     /**
271      * Allow an application to register a DTD event handler.
272      *
273      * <p>If the application does not register a DTD handler, all DTD
274      * events reported by the SAX parser will be silently ignored.</p>
275      *
276      * <p>Applications may register a new or different handler in the
277      * middle of a parse, and the SAX parser must begin using the new
278      * handler immediately.</p>
279      *
280      * @param handler The DTD handler.
281      * @see #getDTDHandler
282      */
283     public void setDTDHandler (DTDHandler handler);
284 
285 
286     /**
287      * Return the current DTD handler.
288      *
289      * @return The current DTD handler, or null if none
290      *         has been registered.
291      * @see #setDTDHandler
292      */
293     public DTDHandler getDTDHandler ();
294 
295 
296     /**
297      * Allow an application to register a content event handler.
298      *
299      * <p>If the application does not register a content handler, all
300      * content events reported by the SAX parser will be silently
301      * ignored.</p>
302      *
303      * <p>Applications may register a new or different handler in the
304      * middle of a parse, and the SAX parser must begin using the new
305      * handler immediately.</p>
306      *
307      * @param handler The content handler.
308      * @see #getContentHandler
309      */
310     public void setContentHandler (ContentHandler handler);
311 
312 
313     /**
314      * Return the current content handler.
315      *
316      * @return The current content handler, or null if none
317      *         has been registered.
318      * @see #setContentHandler
319      */
320     public ContentHandler getContentHandler ();
321 
322 
323     /**
324      * Allow an application to register an error event handler.
325      *
326      * <p>If the application does not register an error handler, all
327      * error events reported by the SAX parser will be silently
328      * ignored; however, normal processing may not continue.  It is
329      * highly recommended that all SAX applications implement an
330      * error handler to avoid unexpected bugs.</p>
331      *
332      * <p>Applications may register a new or different handler in the
333      * middle of a parse, and the SAX parser must begin using the new
334      * handler immediately.</p>
335      *
336      * @param handler The error handler.
337      * @see #getErrorHandler
338      */
339     public void setErrorHandler (ErrorHandler handler);
340 
341 
342     /**
343      * Return the current error handler.
344      *
345      * @return The current error handler, or null if none
346      *         has been registered.
347      * @see #setErrorHandler
348      */
349     public ErrorHandler getErrorHandler ();
350 
351 
352 
353     ////////////////////////////////////////////////////////////////////
354     // Parsing.
355     ////////////////////////////////////////////////////////////////////
356 
357     /**
358      * Parse an XML document.
359      *
360      * <p>The application can use this method to instruct the XML
361      * reader to begin parsing an XML document from any valid input
362      * source (a character stream, a byte stream, or a URI).</p>
363      *
364      * <p>Applications may not invoke this method while a parse is in
365      * progress (they should create a new XMLReader instead for each
366      * nested XML document).  Once a parse is complete, an
367      * application may reuse the same XMLReader object, possibly with a
368      * different input source.
369      * Configuration of the XMLReader object (such as handler bindings and
370      * values established for feature flags and properties) is unchanged
371      * by completion of a parse, unless the definition of that aspect of
372      * the configuration explicitly specifies other behavior.
373      * (For example, feature flags or properties exposing
374      * characteristics of the document being parsed.)
375      * </p>
376      *
377      * <p>During the parse, the XMLReader will provide information
378      * about the XML document through the registered event
379      * handlers.</p>
380      *
381      * <p>This method is synchronous: it will not return until parsing
382      * has ended.  If a client application wants to terminate
383      * parsing early, it should throw an exception.</p>
384      *
385      * @param input The input source for the top-level of the
386      *        XML document.
387      * @exception org.xml.sax.SAXException Any SAX exception, possibly
388      *            wrapping another exception.
389      * @exception java.io.IOException An IO exception from the parser,
390      *            possibly from a byte stream or character stream
391      *            supplied by the application.
392      * @see org.xml.sax.InputSource
393      * @see #parse(java.lang.String)
394      * @see #setEntityResolver
395      * @see #setDTDHandler
396      * @see #setContentHandler
397      * @see #setErrorHandler
398      */
399     public void parse (InputSource input)
400         throws IOException, SAXException;
401 
402 
403     /**
404      * Parse an XML document from a system identifier (URI).
405      *
406      * <p>This method is a shortcut for the common case of reading a
407      * document from a system identifier.  It is the exact
408      * equivalent of the following:</p>
409      *
410      * <pre>
411      * parse(new InputSource(systemId));
412      * </pre>
413      *
414      * <p>If the system identifier is a URL, it must be fully resolved
415      * by the application before it is passed to the parser.</p>
416      *
417      * @param systemId The system identifier (URI).
418      * @exception org.xml.sax.SAXException Any SAX exception, possibly
419      *            wrapping another exception.
420      * @exception java.io.IOException An IO exception from the parser,
421      *            possibly from a byte stream or character stream
422      *            supplied by the application.
423      * @see #parse(org.xml.sax.InputSource)
424      */
425     public void parse (String systemId)
426         throws IOException, SAXException;
427 
428 }