XMLReader


1   /*
2    * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
3    * Copyright (C) 2006 - Javolution (http://javolution.org/)
4    * All rights reserved.
5    * 
6    * Permission to use, copy, modify, and distribute this software is
7    * freely granted, provided that this notice is preserved.
8    */
9   package javolution.xml.sax;
10  
11  import java.io.IOException  ;
12  
13  import org.xml.sax.DTDHandler  ;
14  import org.xml.sax.EntityResolver  ;
15  import org.xml.sax.ErrorHandler  ;
16  import org.xml.sax.InputSource  ;
17  import org.xml.sax.SAXException  ;
18  import org.xml.sax.SAXNotRecognizedException  ;
19  import org.xml.sax.SAXNotSupportedException  ;
20  
21  /**
22   * SAX2-like interface for reading an XML document using callbacks.
23   *
24   * @author David Megginson
25   * @author <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
26   * @version 4.0, June 16, 2005
27   * @see <a HREF="http://www.saxproject.org"> SAX -- Simple API for XML</a> 
28   */
29  public interface XMLReader {
30  
31      /**
32       * Look up the value of a feature flag.
33       *
34       * <p>The feature name is any fully-qualified URI.  It is
35       * possible for an XMLReader to recognize a feature name but
36       * temporarily be unable to return its value.
37       * Some feature values may be available only in specific
38       * contexts, such as before, during, or after a parse.
39       * Also, some feature values may not be programmatically accessible.
40       * (In the case of an adapter for SAX1 {@link org.xml.sax.Parser}, there 
41       * is no implementation-independent way to expose whether the underlying
42       * parser is performing validation, expanding external entities,
43       * and so forth.) </p>
44       *
45       * <p>All XMLReaders are required to recognize the
46       * http://xml.org/sax/features/namespaces and the
47       * http://xml.org/sax/features/namespace-prefixes feature names.</p>
48       *
49       * <p>Typical usage is something like this:</p>
50       *
51       * <pre>
52       * XMLReader r = new MySAXDriver();
53       *
54       *                         // try to activate validation
55       * try {
56       *   r.setFeature("http://xml.org/sax/features/validation", true);
57       * } catch (SAXException e) {
58       *   System.err.println("Cannot activate validation."); 
59       * }
60       *
61       *                         // register event handlers
62       * r.setContentHandler(new MyContentHandler());
63       * r.setErrorHandler(new MyErrorHandler());
64       *
65       *                         // parse the first document
66       * try {
67       *   r.parse("http://www.foo.com/mydoc.xml");
68       * } catch (IOException e) {
69       *   System.err.println("I/O exception reading XML document");
70       * } catch (SAXException e) {
71       *   System.err.println("XML exception reading document.");
72       * }
73       * </pre>
74       *
75       * <p>Implementors are free (and encouraged) to invent their own features,
76       * using names built on their own URIs.</p>
77       *
78       * @param name The feature name, which is a fully-qualified URI.
79       * @return The current value of the feature (true or false).
80       * @exception org.xml.sax.SAXNotRecognizedException If the feature
81       *            value can't be assigned or retrieved.
82       * @exception org.xml.sax.SAXNotSupportedException When the
83       *            XMLReader recognizes the feature name but 
84       *            cannot determine its value at this time.
85       * @see #setFeature
86       */
87      public boolean getFeature(String   name) throws SAXNotRecognizedException  ,
88              SAXNotSupportedException  ;
89  
90      /**
91       * Set the value of a feature flag.
92       *
93       * <p>The feature name is any fully-qualified URI.  It is
94       * possible for an XMLReader to expose a feature value but
95       * to be unable to change the current value.
96       * Some feature values may be immutable or mutable only 
97       * in specific contexts, such as before, during, or after 
98       * a parse.</p>
99       *
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) throws SAXNotRecognizedException  ,
142             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  , SAXException  ;
322 
323     /**
324      * Parse an XML document from a system identifier (URI).
325      *
326      * <p>This method is a shortcut for the common case of reading a
327      * document from a system identifier.  It is the exact
328      * equivalent of the following:</p>
329      *
330      * <pre>
331      * parse(new InputSource(systemId));
332      * </pre>
333      *
334      * <p>If the system identifier is a URL, it must be fully resolved
335      * by the application before it is passed to the parser.</p>
336      *
337      * @param systemId The system identifier (URI).
338      * @exception org.xml.sax.SAXException Any SAX exception, possibly
339      *            wrapping another exception.
340      * @exception j2me.io.IOException An IO exception from the parser,
341      *            possibly from a byte stream or character stream
342      *            supplied by the application.
343      * @see #parse(org.xml.sax.InputSource)
344      */
345     public void parse(String   systemId) throws IOException  , SAXException  ;
346 
347 }
348
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags