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