Classes

Class	Line #	Total Statements	Complexity	Uncovered Elements	TOTAL Coverage	Actions
XMLReader	60	0	0	0	-1.0 -	Show methods

Class XMLReader

Class XMLReader	Line # 60	Total Statements 0	Complexity 0	Uncovered Elements 0	TOTAL Coverage -1.0 -

 

Contributing tests

Source view

1		// XMLReader.java - read an XML document.
2		// http://www.saxproject.org
3		// Written by David Megginson
4		// NO WARRANTY! This class is in the Public Domain.
5		// $Id: XMLReader.java,v 1.9 2004/04/26 17:34:34 dmegginson Exp $
6
7		package org.xml.sax;
8
9		import java.io.IOException;
10
11
12		/**
13		* Interface for reading an XML document using callbacks.
14		*
15		* <blockquote>
16		* <em>This module, both source code and documentation, is in the
17		* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
18		* See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
19		* for further information.
20		* </blockquote>
21		*
22		* <p><strong>Note:</strong> despite its name, this interface does
23		* <em>not</em> extend the standard Java {@link java.io.Reader Reader}
24		* interface, because reading XML is a fundamentally different activity
25		* than reading character data.</p>
26		*
27		* <p>XMLReader is the interface that an XML parser's SAX2 driver must
28		* implement. This interface allows an application to set and
29		* query features and properties in the parser, to register
30		* event handlers for document processing, and to initiate
31		* a document parse.</p>
32		*
33		* <p>All SAX interfaces are assumed to be synchronous: the
34		* {@link #parse parse} methods must not return until parsing
35		* is complete, and readers must wait for an event-handler callback
36		* to return before reporting the next event.</p>
37		*
38		* <p>This interface replaces the (now deprecated) SAX 1.0 {@link
39		* org.xml.sax.Parser Parser} interface. The XMLReader interface
40		* contains two important enhancements over the old Parser
41		* interface (as well as some minor ones):</p>
42		*
43		* <ol>
44		* <li>it adds a standard way to query and set features and
45		* properties; and</li>
46		* <li>it adds Namespace support, which is required for many
47		* higher-level XML standards.</li>
48		* </ol>
49		*
50		* <p>There are adapters available to convert a SAX1 Parser to
51		* a SAX2 XMLReader and vice-versa.</p>
52		*
53		* @since SAX 2.0
54		* @author David Megginson
55		* @version 2.0.1+ (sax2r3pre1)
56		* @see org.xml.sax.XMLFilter
57		* @see org.xml.sax.helpers.ParserAdapter
58		* @see org.xml.sax.helpers.XMLReaderAdapter
59		*/
		- Uncovered Elements: 0 (0) Complexity: 0 Complexity Density: -
60		public interface XMLReader
61		{
62
63
64		////////////////////////////////////////////////////////////////////
65		// Configuration.
66		////////////////////////////////////////////////////////////////////
67
68
69		/**
70		* Look up the value of a feature flag.
71		*
72		* <p>The feature name is any fully-qualified URI. It is
73		* possible for an XMLReader to recognize a feature name but
74		* temporarily be unable to return its value.
75		* Some feature values may be available only in specific
76		* contexts, such as before, during, or after a parse.
77		* Also, some feature values may not be programmatically accessible.
78		* (In the case of an adapter for SAX1 {@link Parser}, there is no
79		* implementation-independent way to expose whether the underlying
80		* parser is performing validation, expanding external entities,
81		* and so forth.) </p>
82		*
83		* <p>All XMLReaders are required to recognize the
84		* http://xml.org/sax/features/namespaces and the
85		* http://xml.org/sax/features/namespace-prefixes feature names.</p>
86		*
87		* <p>Typical usage is something like this:</p>
88		*
89		* <pre>
90		* XMLReader r = new MySAXDriver();
91		*
92		* // try to activate validation
93		* try {
94		* r.setFeature("http://xml.org/sax/features/validation", true);
95		* } catch (SAXException e) {
96		* System.err.println("Cannot activate validation.");
97		* }
98		*
99		* // register event handlers
100		* r.setContentHandler(new MyContentHandler());
101		* r.setErrorHandler(new MyErrorHandler());
102		*
103		* // parse the first document
104		* try {
105		* r.parse("http://www.foo.com/mydoc.xml");
106		* } catch (IOException e) {
107		* System.err.println("I/O exception reading XML document");
108		* } catch (SAXException e) {
109		* System.err.println("XML exception reading document.");
110		* }
111		* </pre>
112		*
113		* <p>Implementors are free (and encouraged) to invent their own features,
114		* using names built on their own URIs.</p>
115		*
116		* @param name The feature name, which is a fully-qualified URI.
117		* @return The current value of the feature (true or false).
118		* @exception org.xml.sax.SAXNotRecognizedException If the feature
119		* value can't be assigned or retrieved.
120		* @exception org.xml.sax.SAXNotSupportedException When the
121		* XMLReader recognizes the feature name but
122		* cannot determine its value at this time.
123		* @see #setFeature
124		*/
125		public boolean getFeature (String name)
126		throws SAXNotRecognizedException, SAXNotSupportedException;
127
128
129		/**
130		* Set the value of a feature flag.
131		*
132		* <p>The feature name is any fully-qualified URI. It is
133		* possible for an XMLReader to expose a feature value but
134		* to be unable to change the current value.
135		* Some feature values may be immutable or mutable only
136		* in specific contexts, such as before, during, or after
137		* a parse.</p>
138		*
139		* <p>All XMLReaders are required to support setting
140		* http://xml.org/sax/features/namespaces to true and
141		* http://xml.org/sax/features/namespace-prefixes to false.</p>
142		*
143		* @param name The feature name, which is a fully-qualified URI.
144		* @param value The requested value of the feature (true or false).
145		* @exception org.xml.sax.SAXNotRecognizedException If the feature
146		* value can't be assigned or retrieved.
147		* @exception org.xml.sax.SAXNotSupportedException When the
148		* XMLReader recognizes the feature name but
149		* cannot set the requested value.
150		* @see #getFeature
151		*/
152		public void setFeature (String name, boolean value)
153		throws SAXNotRecognizedException, SAXNotSupportedException;
154
155
156		/**
157		* Look up the value of a property.
158		*
159		* <p>The property name is any fully-qualified URI. It is
160		* possible for an XMLReader to recognize a property name but
161		* temporarily be unable to return its value.
162		* Some property values may be available only in specific
163		* contexts, such as before, during, or after a parse.</p>
164		*
165		* <p>XMLReaders are not required to recognize any specific
166		* property names, though an initial core set is documented for
167		* SAX2.</p>
168		*
169		* <p>Implementors are free (and encouraged) to invent their own properties,
170		* using names built on their own URIs.</p>
171		*
172		* @param name The property name, which is a fully-qualified URI.
173		* @return The current value of the property.
174		* @exception org.xml.sax.SAXNotRecognizedException If the property
175		* value can't be assigned or retrieved.
176		* @exception org.xml.sax.SAXNotSupportedException When the
177		* XMLReader recognizes the property name but
178		* cannot determine its value at this time.
179		* @see #setProperty
180		*/
181		public Object getProperty (String name)
182		throws SAXNotRecognizedException, SAXNotSupportedException;
183
184
185		/**
186		* Set the value of a property.
187		*
188		* <p>The property name is any fully-qualified URI. It is
189		* possible for an XMLReader to recognize a property name but
190		* to be unable to change the current value.
191		* Some property values may be immutable or mutable only
192		* in specific contexts, such as before, during, or after
193		* a parse.</p>
194		*
195		* <p>XMLReaders are not required to recognize setting
196		* any specific property names, though a core set is defined by
197		* SAX2.</p>
198		*
199		* <p>This method is also the standard mechanism for setting
200		* extended handlers.</p>
201		*
202		* @param name The property name, which is a fully-qualified URI.
203		* @param value The requested value for the property.
204		* @exception org.xml.sax.SAXNotRecognizedException If the property
205		* value can't be assigned or retrieved.
206		* @exception org.xml.sax.SAXNotSupportedException When the
207		* XMLReader recognizes the property name but
208		* cannot set the requested value.
209		*/
210		public void setProperty (String name, Object value)
211		throws SAXNotRecognizedException, SAXNotSupportedException;
212
213
214
215		////////////////////////////////////////////////////////////////////
216		// Event handlers.
217		////////////////////////////////////////////////////////////////////
218
219
220		/**
221		* Allow an application to register an entity resolver.
222		*
223		* <p>If the application does not register an entity resolver,
224		* the XMLReader will perform its own default resolution.</p>
225		*
226		* <p>Applications may register a new or different resolver in the
227		* middle of a parse, and the SAX parser must begin using the new
228		* resolver immediately.</p>
229		*
230		* @param resolver The entity resolver.
231		* @see #getEntityResolver
232		*/
233		public void setEntityResolver (EntityResolver resolver);
234
235
236		/**
237		* Return the current entity resolver.
238		*
239		* @return The current entity resolver, or null if none
240		* has been registered.
241		* @see #setEntityResolver
242		*/
243		public EntityResolver getEntityResolver ();
244
245
246		/**
247		* Allow an application to register a DTD event handler.
248		*
249		* <p>If the application does not register a DTD handler, all DTD
250		* events reported by the SAX parser will be silently ignored.</p>
251		*
252		* <p>Applications may register a new or different handler in the
253		* middle of a parse, and the SAX parser must begin using the new
254		* handler immediately.</p>
255		*
256		* @param handler The DTD handler.
257		* @see #getDTDHandler
258		*/
259		public void setDTDHandler (DTDHandler handler);
260
261
262		/**
263		* Return the current DTD handler.
264		*
265		* @return The current DTD handler, or null if none
266		* has been registered.
267		* @see #setDTDHandler
268		*/
269		public DTDHandler getDTDHandler ();
270
271
272		/**
273		* Allow an application to register a content event handler.
274		*
275		* <p>If the application does not register a content handler, all
276		* content events reported by the SAX parser will be silently
277		* ignored.</p>
278		*
279		* <p>Applications may register a new or different handler in the
280		* middle of a parse, and the SAX parser must begin using the new
281		* handler immediately.</p>
282		*
283		* @param handler The content handler.
284		* @see #getContentHandler
285		*/
286		public void setContentHandler (ContentHandler handler);
287
288
289		/**
290		* Return the current content handler.
291		*
292		* @return The current content handler, or null if none
293		* has been registered.
294		* @see #setContentHandler
295		*/
296		public ContentHandler getContentHandler ();
297
298
299		/**
300		* Allow an application to register an error event handler.
301		*
302		* <p>If the application does not register an error handler, all
303		* error events reported by the SAX parser will be silently
304		* ignored; however, normal processing may not continue. It is
305		* highly recommended that all SAX applications implement an
306		* error handler to avoid unexpected bugs.</p>
307		*
308		* <p>Applications may register a new or different handler in the
309		* middle of a parse, and the SAX parser must begin using the new
310		* handler immediately.</p>
311		*
312		* @param handler The error handler.
313		* @see #getErrorHandler
314		*/
315		public void setErrorHandler (ErrorHandler handler);
316
317
318		/**
319		* Return the current error handler.
320		*
321		* @return The current error handler, or null if none
322		* has been registered.
323		* @see #setErrorHandler
324		*/
325		public ErrorHandler getErrorHandler ();
326
327
328
329		////////////////////////////////////////////////////////////////////
330		// Parsing.
331		////////////////////////////////////////////////////////////////////
332
333		/**
334		* Parse an XML document.
335		*
336		* <p>The application can use this method to instruct the XML
337		* reader to begin parsing an XML document from any valid input
338		* source (a character stream, a byte stream, or a URI).</p>
339		*
340		* <p>Applications may not invoke this method while a parse is in
341		* progress (they should create a new XMLReader instead for each
342		* nested XML document). Once a parse is complete, an
343		* application may reuse the same XMLReader object, possibly with a
344		* different input source.
345		* Configuration of the XMLReader object (such as handler bindings and
346		* values established for feature flags and properties) is unchanged
347		* by completion of a parse, unless the definition of that aspect of
348		* the configuration explicitly specifies other behavior.
349		* (For example, feature flags or properties exposing
350		* characteristics of the document being parsed.)
351		* </p>
352		*
353		* <p>During the parse, the XMLReader will provide information
354		* about the XML document through the registered event
355		* handlers.</p>
356		*
357		* <p>This method is synchronous: it will not return until parsing
358		* has ended. If a client application wants to terminate
359		* parsing early, it should throw an exception.</p>
360		*
361		* @param input The input source for the top-level of the
362		* XML document.
363		* @exception org.xml.sax.SAXException Any SAX exception, possibly
364		* wrapping another exception.
365		* @exception java.io.IOException An IO exception from the parser,
366		* possibly from a byte stream or character stream
367		* supplied by the application.
368		* @see org.xml.sax.InputSource
369		* @see #parse(java.lang.String)
370		* @see #setEntityResolver
371		* @see #setDTDHandler
372		* @see #setContentHandler
373		* @see #setErrorHandler
374		*/
375		public void parse (InputSource input)
376		throws IOException, SAXException;
377
378
379		/**
380		* Parse an XML document from a system identifier (URI).
381		*
382		* <p>This method is a shortcut for the common case of reading a
383		* document from a system identifier. It is the exact
384		* equivalent of the following:</p>
385		*
386		* <pre>
387		* parse(new InputSource(systemId));
388		* </pre>
389		*
390		* <p>If the system identifier is a URL, it must be fully resolved
391		* by the application before it is passed to the parser.</p>
392		*
393		* @param systemId The system identifier (URI).
394		* @exception org.xml.sax.SAXException Any SAX exception, possibly
395		* wrapping another exception.
396		* @exception java.io.IOException An IO exception from the parser,
397		* possibly from a byte stream or character stream
398		* supplied by the application.
399		* @see #parse(org.xml.sax.InputSource)
400		*/
401		public void parse (String systemId)
402		throws IOException, SAXException;
403
404		}