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 1.4, 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 }