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