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