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