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