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