001 /*
002 * Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 // XMLReader.java - read an XML document.
027 // http://www.saxproject.org
028 // Written by David Megginson
029 // NO WARRANTY! This class is in the Public Domain.
030 // $Id: XMLReader.java,v 1.3 2004/11/03 22:55:32 jsuttor Exp $
031 package org.xml.sax;
032
033 import java.io.IOException;
034
035 /**
036 * Interface for reading an XML document using callbacks.
037 *
038 * <blockquote>
039 * <em>This module, both source code and documentation, is in the
040 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
041 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
042 * for further information.
043 * </blockquote>
044 *
045 * <p><strong>Note:</strong> despite its name, this interface does
046 * <em>not</em> extend the standard Java {@link java.io.Reader Reader}
047 * interface, because reading XML is a fundamentally different activity
048 * than reading character data.</p>
049 *
050 * <p>XMLReader is the interface that an XML parser's SAX2 driver must
051 * implement. This interface allows an application to set and
052 * query features and properties in the parser, to register
053 * event handlers for document processing, and to initiate
054 * a document parse.</p>
055 *
056 * <p>All SAX interfaces are assumed to be synchronous: the
057 * {@link #parse parse} methods must not return until parsing
058 * is complete, and readers must wait for an event-handler callback
059 * to return before reporting the next event.</p>
060 *
061 * <p>This interface replaces the (now deprecated) SAX 1.0 {@link
062 * org.xml.sax.Parser Parser} interface. The XMLReader interface
063 * contains two important enhancements over the old Parser
064 * interface (as well as some minor ones):</p>
065 *
066 * <ol>
067 * <li>it adds a standard way to query and set features and
068 * properties; and</li>
069 * <li>it adds Namespace support, which is required for many
070 * higher-level XML standards.</li>
071 * </ol>
072 *
073 * <p>There are adapters available to convert a SAX1 Parser to
074 * a SAX2 XMLReader and vice-versa.</p>
075 *
076 * @since SAX 2.0
077 * @author David Megginson
078 * @version 2.0.1+ (sax2r3pre1)
079 * @see org.xml.sax.XMLFilter
080 * @see org.xml.sax.helpers.ParserAdapter
081 * @see org.xml.sax.helpers.XMLReaderAdapter
082 */
083 public interface XMLReader {
084
085 ////////////////////////////////////////////////////////////////////
086 // Configuration.
087 ////////////////////////////////////////////////////////////////////
088
089 /**
090 * Look up the value of a feature flag.
091 *
092 * <p>The feature name is any fully-qualified URI. It is
093 * possible for an XMLReader to recognize a feature name but
094 * temporarily be unable to return its value.
095 * Some feature values may be available only in specific
096 * contexts, such as before, during, or after a parse.
097 * Also, some feature values may not be programmatically accessible.
098 * (In the case of an adapter for SAX1 {@link Parser}, there is no
099 * implementation-independent way to expose whether the underlying
100 * parser is performing validation, expanding external entities,
101 * and so forth.) </p>
102 *
103 * <p>All XMLReaders are required to recognize the
104 * http://xml.org/sax/features/namespaces and the
105 * http://xml.org/sax/features/namespace-prefixes feature names.</p>
106 *
107 * <p>Typical usage is something like this:</p>
108 *
109 * <pre>
110 * XMLReader r = new MySAXDriver();
111 *
112 * // try to activate validation
113 * try {
114 * r.setFeature("http://xml.org/sax/features/validation", true);
115 * } catch (SAXException e) {
116 * System.err.println("Cannot activate validation.");
117 * }
118 *
119 * // register event handlers
120 * r.setContentHandler(new MyContentHandler());
121 * r.setErrorHandler(new MyErrorHandler());
122 *
123 * // parse the first document
124 * try {
125 * r.parse("http://www.foo.com/mydoc.xml");
126 * } catch (IOException e) {
127 * System.err.println("I/O exception reading XML document");
128 * } catch (SAXException e) {
129 * System.err.println("XML exception reading document.");
130 * }
131 * </pre>
132 *
133 * <p>Implementors are free (and encouraged) to invent their own features,
134 * using names built on their own URIs.</p>
135 *
136 * @param name The feature name, which is a fully-qualified URI.
137 * @return The current value of the feature (true or false).
138 * @exception org.xml.sax.SAXNotRecognizedException If the feature
139 * value can't be assigned or retrieved.
140 * @exception org.xml.sax.SAXNotSupportedException When the
141 * XMLReader recognizes the feature name but
142 * cannot determine its value at this time.
143 * @see #setFeature
144 */
145 public boolean getFeature(String name)
146 throws SAXNotRecognizedException, SAXNotSupportedException;
147
148 /**
149 * Set the value of a feature flag.
150 *
151 * <p>The feature name is any fully-qualified URI. It is
152 * possible for an XMLReader to expose a feature value but
153 * to be unable to change the current value.
154 * Some feature values may be immutable or mutable only
155 * in specific contexts, such as before, during, or after
156 * a parse.</p>
157 *
158 * <p>All XMLReaders are required to support setting
159 * http://xml.org/sax/features/namespaces to true and
160 * http://xml.org/sax/features/namespace-prefixes to false.</p>
161 *
162 * @param name The feature name, which is a fully-qualified URI.
163 * @param value The requested value of the feature (true or false).
164 * @exception org.xml.sax.SAXNotRecognizedException If the feature
165 * value can't be assigned or retrieved.
166 * @exception org.xml.sax.SAXNotSupportedException When the
167 * XMLReader recognizes the feature name but
168 * cannot set the requested value.
169 * @see #getFeature
170 */
171 public void setFeature(String name, boolean value)
172 throws SAXNotRecognizedException, SAXNotSupportedException;
173
174 /**
175 * Look up the value of a property.
176 *
177 * <p>The property name is any fully-qualified URI. It is
178 * possible for an XMLReader to recognize a property name but
179 * temporarily be unable to return its value.
180 * Some property values may be available only in specific
181 * contexts, such as before, during, or after a parse.</p>
182 *
183 * <p>XMLReaders are not required to recognize any specific
184 * property names, though an initial core set is documented for
185 * SAX2.</p>
186 *
187 * <p>Implementors are free (and encouraged) to invent their own properties,
188 * using names built on their own URIs.</p>
189 *
190 * @param name The property name, which is a fully-qualified URI.
191 * @return The current value of the property.
192 * @exception org.xml.sax.SAXNotRecognizedException If the property
193 * value can't be assigned or retrieved.
194 * @exception org.xml.sax.SAXNotSupportedException When the
195 * XMLReader recognizes the property name but
196 * cannot determine its value at this time.
197 * @see #setProperty
198 */
199 public Object getProperty(String name)
200 throws SAXNotRecognizedException, SAXNotSupportedException;
201
202 /**
203 * Set the value of a property.
204 *
205 * <p>The property name is any fully-qualified URI. It is
206 * possible for an XMLReader to recognize a property name but
207 * to be unable to change the current value.
208 * Some property values may be immutable or mutable only
209 * in specific contexts, such as before, during, or after
210 * a parse.</p>
211 *
212 * <p>XMLReaders are not required to recognize setting
213 * any specific property names, though a core set is defined by
214 * SAX2.</p>
215 *
216 * <p>This method is also the standard mechanism for setting
217 * extended handlers.</p>
218 *
219 * @param name The property name, which is a fully-qualified URI.
220 * @param value The requested value for the property.
221 * @exception org.xml.sax.SAXNotRecognizedException If the property
222 * value can't be assigned or retrieved.
223 * @exception org.xml.sax.SAXNotSupportedException When the
224 * XMLReader recognizes the property name but
225 * cannot set the requested value.
226 */
227 public void setProperty(String name, Object value)
228 throws SAXNotRecognizedException, SAXNotSupportedException;
229
230 ////////////////////////////////////////////////////////////////////
231 // Event handlers.
232 ////////////////////////////////////////////////////////////////////
233
234 /**
235 * Allow an application to register an entity resolver.
236 *
237 * <p>If the application does not register an entity resolver,
238 * the XMLReader will perform its own default resolution.</p>
239 *
240 * <p>Applications may register a new or different resolver in the
241 * middle of a parse, and the SAX parser must begin using the new
242 * resolver immediately.</p>
243 *
244 * @param resolver The entity resolver.
245 * @see #getEntityResolver
246 */
247 public void setEntityResolver(EntityResolver resolver);
248
249 /**
250 * Return the current entity resolver.
251 *
252 * @return The current entity resolver, or null if none
253 * has been registered.
254 * @see #setEntityResolver
255 */
256 public EntityResolver getEntityResolver();
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 * Return the current DTD handler.
275 *
276 * @return The current DTD handler, or null if none
277 * has been registered.
278 * @see #setDTDHandler
279 */
280 public DTDHandler getDTDHandler();
281
282 /**
283 * Allow an application to register a content event handler.
284 *
285 * <p>If the application does not register a content handler, all
286 * content events reported by the SAX parser will be silently
287 * ignored.</p>
288 *
289 * <p>Applications may register a new or different handler in the
290 * middle of a parse, and the SAX parser must begin using the new
291 * handler immediately.</p>
292 *
293 * @param handler The content handler.
294 * @see #getContentHandler
295 */
296 public void setContentHandler(ContentHandler handler);
297
298 /**
299 * Return the current content handler.
300 *
301 * @return The current content handler, or null if none
302 * has been registered.
303 * @see #setContentHandler
304 */
305 public ContentHandler getContentHandler();
306
307 /**
308 * Allow an application to register an error event handler.
309 *
310 * <p>If the application does not register an error handler, all
311 * error events reported by the SAX parser will be silently
312 * ignored; however, normal processing may not continue. It is
313 * highly recommended that all SAX applications implement an
314 * error handler to avoid unexpected bugs.</p>
315 *
316 * <p>Applications may register a new or different handler in the
317 * middle of a parse, and the SAX parser must begin using the new
318 * handler immediately.</p>
319 *
320 * @param handler The error handler.
321 * @see #getErrorHandler
322 */
323 public void setErrorHandler(ErrorHandler handler);
324
325 /**
326 * Return the current error handler.
327 *
328 * @return The current error handler, or null if none
329 * has been registered.
330 * @see #setErrorHandler
331 */
332 public ErrorHandler getErrorHandler();
333
334 ////////////////////////////////////////////////////////////////////
335 // Parsing.
336 ////////////////////////////////////////////////////////////////////
337
338 /**
339 * Parse an XML document.
340 *
341 * <p>The application can use this method to instruct the XML
342 * reader to begin parsing an XML document from any valid input
343 * source (a character stream, a byte stream, or a URI).</p>
344 *
345 * <p>Applications may not invoke this method while a parse is in
346 * progress (they should create a new XMLReader instead for each
347 * nested XML document). Once a parse is complete, an
348 * application may reuse the same XMLReader object, possibly with a
349 * different input source.
350 * Configuration of the XMLReader object (such as handler bindings and
351 * values established for feature flags and properties) is unchanged
352 * by completion of a parse, unless the definition of that aspect of
353 * the configuration explicitly specifies other behavior.
354 * (For example, feature flags or properties exposing
355 * characteristics of the document being parsed.)
356 * </p>
357 *
358 * <p>During the parse, the XMLReader will provide information
359 * about the XML document through the registered event
360 * handlers.</p>
361 *
362 * <p>This method is synchronous: it will not return until parsing
363 * has ended. If a client application wants to terminate
364 * parsing early, it should throw an exception.</p>
365 *
366 * @param input The input source for the top-level of the
367 * XML document.
368 * @exception org.xml.sax.SAXException Any SAX exception, possibly
369 * wrapping another exception.
370 * @exception java.io.IOException An IO exception from the parser,
371 * possibly from a byte stream or character stream
372 * supplied by the application.
373 * @see org.xml.sax.InputSource
374 * @see #parse(java.lang.String)
375 * @see #setEntityResolver
376 * @see #setDTDHandler
377 * @see #setContentHandler
378 * @see #setErrorHandler
379 */
380 public void parse(InputSource input) throws IOException,
381 SAXException;
382
383 /**
384 * Parse an XML document from a system identifier (URI).
385 *
386 * <p>This method is a shortcut for the common case of reading a
387 * document from a system identifier. It is the exact
388 * equivalent of the following:</p>
389 *
390 * <pre>
391 * parse(new InputSource(systemId));
392 * </pre>
393 *
394 * <p>If the system identifier is a URL, it must be fully resolved
395 * by the application before it is passed to the parser.</p>
396 *
397 * @param systemId The system identifier (URI).
398 * @exception org.xml.sax.SAXException Any SAX exception, possibly
399 * wrapping another exception.
400 * @exception java.io.IOException An IO exception from the parser,
401 * possibly from a byte stream or character stream
402 * supplied by the application.
403 * @see #parse(org.xml.sax.InputSource)
404 */
405 public void parse(String systemId) throws IOException, SAXException;
406
407 }
|