KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > parsers > SAXParser


1 // $Id: SAXParser.java,v 1.28.12.1.2.1 2004/05/02 04:30:56 jsuttor Exp $
2
/*
3  * @(#)SAXParser.java 1.19 04/07/26
4  *
5  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
6  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
7  */

8
9 package javax.xml.parsers;
10
11 import java.io.File JavaDoc;
12 import java.io.IOException JavaDoc;
13 import java.io.InputStream JavaDoc;
14
15 import javax.xml.validation.Schema JavaDoc;
16
17 import org.xml.sax.HandlerBase JavaDoc;
18 import org.xml.sax.InputSource JavaDoc;
19 import org.xml.sax.Parser JavaDoc;
20 import org.xml.sax.SAXException JavaDoc;
21 import org.xml.sax.SAXNotRecognizedException JavaDoc;
22 import org.xml.sax.SAXNotSupportedException JavaDoc;
23 import org.xml.sax.XMLReader JavaDoc;
24 import org.xml.sax.helpers.DefaultHandler JavaDoc;
25
26
27 /**
28  * Defines the API that wraps an {@link org.xml.sax.XMLReader}
29  * implementation class. In JAXP 1.0, this class wrapped the
30  * {@link org.xml.sax.Parser} interface, however this interface was
31  * replaced by the {@link org.xml.sax.XMLReader}. For ease
32  * of transition, this class continues to support the same name
33  * and interface as well as supporting new methods.
34  *
35  * An instance of this class can be obtained from the
36  * {@link javax.xml.parsers.SAXParserFactory#newSAXParser()} method.
37  * Once an instance of this class is obtained, XML can be parsed from
38  * a variety of input sources. These input sources are InputStreams,
39  * Files, URLs, and SAX InputSources.<p>
40  *
41  * This static method creates a new factory instance based
42  * on a system property setting or uses the platform default
43  * if no property has been defined.<p>
44  *
45  * The system property that controls which Factory implementation
46  * to create is named <code>&quot;javax.xml.parsers.SAXParserFactory&quot;</code>.
47  * This property names a class that is a concrete subclass of this
48  * abstract class. If no property is defined, a platform default
49  * will be used.</p>
50  *
51  * As the content is parsed by the underlying parser, methods of the
52  * given {@link org.xml.sax.HandlerBase} or the
53  * {@link org.xml.sax.helpers.DefaultHandler} are called.<p>
54  *
55  * Implementors of this class which wrap an underlaying implementation
56  * can consider using the {@link org.xml.sax.helpers.ParserAdapter}
57  * class to initially adapt their SAX1 impelemntation to work under
58  * this revised class.
59  *
60  * @author <a HREF="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
61  * @version $Revision: 1.28.12.1.2.1 $, $Date: 2004/05/02 04:30:56 $
62  */

63 public abstract class SAXParser {
64         
65     /**
66      * <p>Protected constructor to prevent instaniation.
67      * Use {@link javax.xml.parsers.SAXParserFactory#newSAXParser()}.</p>
68      */

69     protected SAXParser () {
70     
71     }
72
73     /**
74      * <p>Reset this <code>SAXParser</code> to its original configuration.</p>
75      *
76      * <p><code>SAXParser</code> is reset to the same state as when it was created with
77      * {@link SAXParserFactory#newSAXParser()}.
78      * <code>reset()</code> is designed to allow the reuse of existing <code>SAXParser</code>s
79      * thus saving resources associated with the creation of new <code>SAXParser</code>s.</p>
80      *
81      * <p>The reset <code>SAXParser</code> is not guaranteed to have the same {@link Schema}
82      * <code>Object</code>, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal
83      * <code>Schema</code>.</p>
84      *
85      * @since 1.5
86      */

87     public void reset() {
88
89         // implementors should override this method
90
throw new UnsupportedOperationException JavaDoc(
91             "This SAXParser, \"" + this.getClass().getName() + "\", does not support the reset functionality."
92             + " Specification \"" + this.getClass().getPackage().getSpecificationTitle() + "\""
93             + " version \"" + this.getClass().getPackage().getSpecificationVersion() + "\""
94             );
95     }
96
97     /**
98      * <p>Parse the content of the given {@link java.io.InputStream}
99      * instance as XML using the specified {@link org.xml.sax.HandlerBase}.
100      * <i> Use of the DefaultHandler version of this method is recommended as
101      * the HandlerBase class has been deprecated in SAX 2.0</i>.</p>
102      *
103      * @param is InputStream containing the content to be parsed.
104      * @param hb The SAX HandlerBase to use.
105      *
106      * @throws IllegalArgumentException If the given InputStream is null.
107      * @throws SAXException If parse produces a SAX error.
108      * @throws IOException If an IO error occurs interacting with the
109      * <code>InputStream</code>.
110      *
111      * @see org.xml.sax.DocumentHandler
112      */

113     public void parse(InputStream JavaDoc is, HandlerBase JavaDoc hb)
114         throws SAXException JavaDoc, IOException JavaDoc {
115         if (is == null) {
116             throw new IllegalArgumentException JavaDoc("InputStream cannot be null");
117         }
118
119         InputSource JavaDoc input = new InputSource JavaDoc(is);
120         this.parse(input, hb);
121     }
122
123     /**
124      * <p>Parse the content of the given {@link java.io.InputStream}
125      * instance as XML using the specified {@link org.xml.sax.HandlerBase}.
126      * <i> Use of the DefaultHandler version of this method is recommended as
127      * the HandlerBase class has been deprecated in SAX 2.0</i>.</p>
128      *
129      * @param is InputStream containing the content to be parsed.
130      * @param hb The SAX HandlerBase to use.
131      * @param systemId The systemId which is needed for resolving relative URIs.
132      *
133      * @throws IllegalArgumentException If the given <code>InputStream</code> is
134      * <code>null</code>.
135      * @throws IOException If any IO error occurs interacting with the
136      * <code>InputStream</code>.
137      * @throws SAXException If any SAX errors occur during processing.
138      *
139      * @see org.xml.sax.DocumentHandler version of this method instead.
140      */

141     public void parse(
142         InputStream JavaDoc is,
143         HandlerBase JavaDoc hb,
144         String JavaDoc systemId)
145         throws SAXException JavaDoc, IOException JavaDoc {
146         if (is == null) {
147             throw new IllegalArgumentException JavaDoc("InputStream cannot be null");
148         }
149
150         InputSource JavaDoc input = new InputSource JavaDoc(is);
151         input.setSystemId(systemId);
152         this.parse(input, hb);
153     }
154    
155     /**
156      * Parse the content of the given {@link java.io.InputStream}
157      * instance as XML using the specified
158      * {@link org.xml.sax.helpers.DefaultHandler}.
159      *
160      * @param is InputStream containing the content to be parsed.
161      * @param dh The SAX DefaultHandler to use.
162      *
163      * @throws IllegalArgumentException If the given InputStream is null.
164      * @throws IOException If any IO errors occur.
165      * @throws SAXException If any SAX errors occur during processing.
166      *
167      * @see org.xml.sax.DocumentHandler
168      */

169     public void parse(InputStream JavaDoc is, DefaultHandler JavaDoc dh)
170         throws SAXException JavaDoc, IOException JavaDoc {
171         if (is == null) {
172             throw new IllegalArgumentException JavaDoc("InputStream cannot be null");
173         }
174
175         InputSource JavaDoc input = new InputSource JavaDoc(is);
176         this.parse(input, dh);
177     }
178
179     /**
180      * Parse the content of the given {@link java.io.InputStream}
181      * instance as XML using the specified
182      * {@link org.xml.sax.helpers.DefaultHandler}.
183      *
184      * @param is InputStream containing the content to be parsed.
185      * @param dh The SAX DefaultHandler to use.
186      * @param systemId The systemId which is needed for resolving relative URIs.
187      *
188      * @throws IllegalArgumentException If the given InputStream is null.
189      * @throws IOException If any IO errors occur.
190      * @throws SAXException If any SAX errors occur during processing.
191      *
192      * @see org.xml.sax.DocumentHandler version of this method instead.
193      */

194     public void parse(
195         InputStream JavaDoc is,
196         DefaultHandler JavaDoc dh,
197         String JavaDoc systemId)
198         throws SAXException JavaDoc, IOException JavaDoc {
199         if (is == null) {
200             throw new IllegalArgumentException JavaDoc("InputStream cannot be null");
201         }
202
203         InputSource JavaDoc input = new InputSource JavaDoc(is);
204         input.setSystemId(systemId);
205         this.parse(input, dh);
206     }
207
208     /**
209      * Parse the content described by the giving Uniform Resource
210      * Identifier (URI) as XML using the specified
211      * {@link org.xml.sax.HandlerBase}.
212      * <i> Use of the DefaultHandler version of this method is recommended as
213      * the <code>HandlerBase</code> class has been deprecated in SAX 2.0</i>
214      *
215      * @param uri The location of the content to be parsed.
216      * @param hb The SAX HandlerBase to use.
217      *
218      * @throws IllegalArgumentException If the uri is null.
219      * @throws IOException If any IO errors occur.
220      * @throws SAXException If any SAX errors occur during processing.
221      *
222      * @see org.xml.sax.DocumentHandler
223      */

224     public void parse(String JavaDoc uri, HandlerBase JavaDoc hb)
225         throws SAXException JavaDoc, IOException JavaDoc {
226         if (uri == null) {
227             throw new IllegalArgumentException JavaDoc("uri cannot be null");
228         }
229
230         InputSource JavaDoc input = new InputSource JavaDoc(uri);
231         this.parse(input, hb);
232     }
233   
234     /**
235      * Parse the content described by the giving Uniform Resource
236      * Identifier (URI) as XML using the specified
237      * {@link org.xml.sax.helpers.DefaultHandler}.
238      *
239      * @param uri The location of the content to be parsed.
240      * @param dh The SAX DefaultHandler to use.
241      *
242      * @throws IllegalArgumentException If the uri is null.
243      * @throws IOException If any IO errors occur.
244      * @throws SAXException If any SAX errors occur during processing.
245      *
246      * @see org.xml.sax.DocumentHandler
247      */

248     public void parse(String JavaDoc uri, DefaultHandler JavaDoc dh)
249         throws SAXException JavaDoc, IOException JavaDoc {
250         if (uri == null) {
251             throw new IllegalArgumentException JavaDoc("uri cannot be null");
252         }
253
254         InputSource JavaDoc input = new InputSource JavaDoc(uri);
255         this.parse(input, dh);
256     }
257     
258     /**
259      * Parse the content of the file specified as XML using the
260      * specified {@link org.xml.sax.HandlerBase}.
261      * <i> Use of the DefaultHandler version of this method is recommended as
262      * the HandlerBase class has been deprecated in SAX 2.0</i>
263      *
264      * @param f The file containing the XML to parse
265      * @param hb The SAX HandlerBase to use.
266      *
267      * @throws IllegalArgumentException If the File object is null.
268      * @throws IOException If any IO errors occur.
269      * @throws SAXException If any SAX errors occur during processing.
270      *
271      * @see org.xml.sax.DocumentHandler
272      */

273     public void parse(File JavaDoc f, HandlerBase JavaDoc hb)
274         throws SAXException JavaDoc, IOException JavaDoc {
275         if (f == null) {
276             throw new IllegalArgumentException JavaDoc("File cannot be null");
277         }
278
279         String JavaDoc uri = "file:" + f.getAbsolutePath();
280         if (File.separatorChar == '\\') {
281             uri = uri.replace('\\', '/');
282         }
283         InputSource JavaDoc input = new InputSource JavaDoc(uri);
284         this.parse(input, hb);
285     }
286     
287     /**
288      * Parse the content of the file specified as XML using the
289      * specified {@link org.xml.sax.helpers.DefaultHandler}.
290      *
291      * @param f The file containing the XML to parse
292      * @param dh The SAX DefaultHandler to use.
293      *
294      * @throws IllegalArgumentException If the File object is null.
295      * @throws IOException If any IO errors occur.
296      * @throws SAXException If any SAX errors occur during processing.
297      *
298      * @see org.xml.sax.DocumentHandler
299      */

300     public void parse(File JavaDoc f, DefaultHandler JavaDoc dh)
301         throws SAXException JavaDoc, IOException JavaDoc {
302         if (f == null) {
303             throw new IllegalArgumentException JavaDoc("File cannot be null");
304         }
305
306         String JavaDoc uri = "file:" + f.getAbsolutePath();
307         if (File.separatorChar == '\\') {
308             uri = uri.replace('\\', '/');
309         }
310         InputSource JavaDoc input = new InputSource JavaDoc(uri);
311         this.parse(input, dh);
312     }
313     
314     /**
315      * Parse the content given {@link org.xml.sax.InputSource}
316      * as XML using the specified
317      * {@link org.xml.sax.HandlerBase}.
318      * <i> Use of the DefaultHandler version of this method is recommended as
319      * the HandlerBase class has been deprecated in SAX 2.0</i>
320      *
321      * @param is The InputSource containing the content to be parsed.
322      * @param hb The SAX HandlerBase to use.
323      *
324      * @throws IllegalArgumentException If the <code>InputSource</code> object
325      * is <code>null</code>.
326      * @throws IOException If any IO errors occur.
327      * @throws SAXException If any SAX errors occur during processing.
328      *
329      * @see org.xml.sax.DocumentHandler
330      */

331     public void parse(InputSource JavaDoc is, HandlerBase JavaDoc hb)
332         throws SAXException JavaDoc, IOException JavaDoc {
333         if (is == null) {
334             throw new IllegalArgumentException JavaDoc("InputSource cannot be null");
335         }
336
337         Parser JavaDoc parser = this.getParser();
338         if (hb != null) {
339             parser.setDocumentHandler(hb);
340             parser.setEntityResolver(hb);
341             parser.setErrorHandler(hb);
342             parser.setDTDHandler(hb);
343         }
344         parser.parse(is);
345     }
346     
347     /**
348      * Parse the content given {@link org.xml.sax.InputSource}
349      * as XML using the specified
350      * {@link org.xml.sax.helpers.DefaultHandler}.
351      *
352      * @param is The InputSource containing the content to be parsed.
353      * @param dh The SAX DefaultHandler to use.
354      *
355      * @throws IllegalArgumentException If the <code>InputSource</code> object
356      * is <code>null</code>.
357      * @throws IOException If any IO errors occur.
358      * @throws SAXException If any SAX errors occur during processing.
359      *
360      * @see org.xml.sax.DocumentHandler
361      */

362     public void parse(InputSource JavaDoc is, DefaultHandler JavaDoc dh)
363         throws SAXException JavaDoc, IOException JavaDoc {
364         if (is == null) {
365             throw new IllegalArgumentException JavaDoc("InputSource cannot be null");
366         }
367
368         XMLReader JavaDoc reader = this.getXMLReader();
369         if (dh != null) {
370             reader.setContentHandler(dh);
371             reader.setEntityResolver(dh);
372             reader.setErrorHandler(dh);
373             reader.setDTDHandler(dh);
374         }
375         reader.parse(is);
376     }
377     
378     /**
379      * Returns the SAX parser that is encapsultated by the
380      * implementation of this class.
381      *
382      * @return The SAX parser that is encapsultated by the
383      * implementation of this class.
384      *
385      * @throws SAXException If any SAX errors occur during processing.
386      */

387     public abstract org.xml.sax.Parser JavaDoc getParser() throws SAXException JavaDoc;
388
389     /**
390      * Returns the {@link org.xml.sax.XMLReader} that is encapsulated by the
391      * implementation of this class.
392      *
393      * @return The XMLReader that is encapsulated by the
394      * implementation of this class.
395      *
396      * @throws SAXException If any SAX errors occur during processing.
397      */

398
399     public abstract org.xml.sax.XMLReader JavaDoc getXMLReader() throws SAXException JavaDoc;
400     
401     /**
402      * Indicates whether or not this parser is configured to
403      * understand namespaces.
404      *
405      * @return true if this parser is configured to
406      * understand namespaces; false otherwise.
407      */

408     
409     public abstract boolean isNamespaceAware();
410
411     /**
412      * Indicates whether or not this parser is configured to
413      * validate XML documents.
414      *
415      * @return true if this parser is configured to
416      * validate XML documents; false otherwise.
417      */

418     
419     public abstract boolean isValidating();
420
421     /**
422      * <p>Sets the particular property in the underlying implementation of
423      * {@link org.xml.sax.XMLReader}.
424      * A list of the core features and properties can be found at
425      * <a HREF="http://sax.sourceforge.net/?selected=get-set">
426      * http://sax.sourceforge.net/?selected=get-set</a>.</p>
427      *
428      * @param name The name of the property to be set.
429      * @param value The value of the property to be set.
430      *
431      * @throws SAXNotRecognizedException When the underlying XMLReader does
432      * not recognize the property name.
433      * @throws SAXNotSupportedException When the underlying XMLReader
434      * recognizes the property name but doesn't support the property.
435      *
436      * @see org.xml.sax.XMLReader#setProperty
437      */

438     public abstract void setProperty(String JavaDoc name, Object JavaDoc value)
439         throws SAXNotRecognizedException JavaDoc, SAXNotSupportedException JavaDoc;
440
441     /**
442      * <p>Returns the particular property requested for in the underlying
443      * implementation of {@link org.xml.sax.XMLReader}.</p>
444      *
445      * @param name The name of the property to be retrieved.
446      * @return Value of the requested property.
447      *
448      * @throws SAXNotRecognizedException When the underlying XMLReader does
449      * not recognize the property name.
450      * @throws SAXNotSupportedException When the underlying XMLReader
451      * recognizes the property name but doesn't support the property.
452      *
453      * @see org.xml.sax.XMLReader#getProperty
454      */

455     public abstract Object JavaDoc getProperty(String JavaDoc name)
456         throws SAXNotRecognizedException JavaDoc, SAXNotSupportedException JavaDoc;
457
458     /** <p>Get current state of canonicalization.</p>
459      *
460      * @return current state canonicalization control
461      */

462     /*
463     public boolean getCanonicalization() {
464         return canonicalState;
465     }
466     */

467
468     /** <p>Get a reference to the the {@link Schema} being used by
469      * the XML processor.</p>
470      *
471      * <p>If no schema is being used, <code>null</code> is returned.</p>
472      *
473      * @return {@link Schema} being used or <code>null</code>
474      * if none in use
475      *
476      * @throws UnsupportedOperationException
477      * For backward compatibility, when implementations for
478      * earlier versions of JAXP is used, this exception will be
479      * thrown.
480      *
481      * @since 1.5
482      */

483     public Schema JavaDoc getSchema() {
484         throw new UnsupportedOperationException JavaDoc(
485             "This parser does not support specification \""
486             + this.getClass().getPackage().getSpecificationTitle()
487             + "\" version \""
488             + this.getClass().getPackage().getSpecificationVersion()
489             + "\""
490             );
491     }
492     
493     /**
494      * <p>Get the XInclude processing mode for this parser.</p>
495      *
496      * @return
497      * the return value of
498      * the {@link SAXParserFactory#isXIncludeAware()}
499      * when this parser was created from factory.
500      *
501      * @throws UnsupportedOperationException
502      * For backward compatibility, when implementations for
503      * earlier versions of JAXP is used, this exception will be
504      * thrown.
505      *
506      * @since 1.5
507      *
508      * @see SAXParserFactory#setXIncludeAware(boolean)
509      */

510     public boolean isXIncludeAware() {
511         throw new UnsupportedOperationException JavaDoc(
512             "This parser does not support specification \""
513             + this.getClass().getPackage().getSpecificationTitle()
514             + "\" version \""
515             + this.getClass().getPackage().getSpecificationVersion()
516             + "\""
517             );
518     }
519 }
520
Popular Tags