2
* Copyright 2003-2005 The Apache Software Foundation.
4
* Licensed under the Apache License, Version 2.0 (the "License");
5
* you may not use this file except in compliance with the License.
6
* You may obtain a copy of the License at
8
* http://www.apache.org/licenses/LICENSE-2.0
10
* Unless required by applicable law or agreed to in writing, software
11
* distributed under the License is distributed on an "AS IS" BASIS,
12
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
* See the License for the specific language governing permissions and
14
* limitations under the License.
17
// $Id: SAXParser.java 226208 2005-06-03 18:28:57Z mrglavas $
19
package javax.xml.parsers;
22
import java.io.IOException;
23
import java.io.InputStream;
25
import javax.xml.validation.Schema;
27
import org.xml.sax.HandlerBase;
28
import org.xml.sax.InputSource;
29
import org.xml.sax.Parser;
30
import org.xml.sax.SAXException;
31
import org.xml.sax.SAXNotRecognizedException;
32
import org.xml.sax.SAXNotSupportedException;
33
import org.xml.sax.XMLReader;
34
import org.xml.sax.helpers.DefaultHandler;
38
* Defines the API that wraps an {@link org.xml.sax.XMLReader}
39
* implementation class. In JAXP 1.0, this class wrapped the
40
* {@link org.xml.sax.Parser} interface, however this interface was
41
* replaced by the {@link org.xml.sax.XMLReader}. For ease
42
* of transition, this class continues to support the same name
43
* and interface as well as supporting new methods.
45
* An instance of this class can be obtained from the
46
* {@link javax.xml.parsers.SAXParserFactory#newSAXParser()} method.
47
* Once an instance of this class is obtained, XML can be parsed from
48
* a variety of input sources. These input sources are InputStreams,
49
* Files, URLs, and SAX InputSources.<p>
51
* This static method creates a new factory instance based
52
* on a system property setting or uses the platform default
53
* if no property has been defined.<p>
55
* The system property that controls which Factory implementation
56
* to create is named <code>"javax.xml.parsers.SAXParserFactory"</code>.
57
* This property names a class that is a concrete subclass of this
58
* abstract class. If no property is defined, a platform default
61
* As the content is parsed by the underlying parser, methods of the
62
* given {@link org.xml.sax.HandlerBase} or the
63
* {@link org.xml.sax.helpers.DefaultHandler} are called.<p>
65
* Implementors of this class which wrap an underlaying implementation
66
* can consider using the {@link org.xml.sax.helpers.ParserAdapter}
67
* class to initially adapt their SAX1 impelemntation to work under
70
* @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
71
* @version $Revision: 226208 $, $Date: 2005-06-03 14:28:57 -0400 (Fri, 03 Jun 2005) $
73
public abstract class SAXParser {
75
private static final boolean DEBUG = false;
78
* <p>Protected constructor to prevent instaniation.
79
* Use {@link javax.xml.parsers.SAXParserFactory#newSAXParser()}.</p>
81
protected SAXParser () {
86
* <p>Reset this <code>SAXParser</code> to its original configuration.</p>
88
* <p><code>SAXParser</code> is reset to the same state as when it was created with
89
* {@link SAXParserFactory#newSAXParser()}.
90
* <code>reset()</code> is designed to allow the reuse of existing <code>SAXParser</code>s
91
* thus saving resources associated with the creation of new <code>SAXParser</code>s.</p>
93
* <p>The reset <code>SAXParser</code> is not guaranteed to have the same {@link Schema}
94
* <code>Object</code>, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal
95
* <code>Schema</code>.</p>
101
// implementors should override this method
102
throw new UnsupportedOperationException(
103
"This SAXParser, \"" + this.getClass().getName() + "\", does not support the reset functionality."
104
+ " Specification \"" + this.getClass().getPackage().getSpecificationTitle() + "\""
105
+ " version \"" + this.getClass().getPackage().getSpecificationVersion() + "\""
110
* <p>Parse the content of the given {@link java.io.InputStream}
111
* instance as XML using the specified {@link org.xml.sax.HandlerBase}.
112
* <i> Use of the DefaultHandler version of this method is recommended as
113
* the HandlerBase class has been deprecated in SAX 2.0</i>.</p>
115
* @param is InputStream containing the content to be parsed.
116
* @param hb The SAX HandlerBase to use.
118
* @throws IllegalArgumentException If the given InputStream is null.
119
* @throws SAXException If parse produces a SAX error.
120
* @throws IOException If an IO error occurs interacting with the
121
* <code>InputStream</code>.
123
* @see org.xml.sax.DocumentHandler
125
public void parse(InputStream is, HandlerBase hb)
126
throws SAXException, IOException {
128
throw new IllegalArgumentException("InputStream cannot be null");
131
InputSource input = new InputSource(is);
132
this.parse(input, hb);
136
* <p>Parse the content of the given {@link java.io.InputStream}
137
* instance as XML using the specified {@link org.xml.sax.HandlerBase}.
138
* <i> Use of the DefaultHandler version of this method is recommended as
139
* the HandlerBase class has been deprecated in SAX 2.0</i>.</p>
141
* @param is InputStream containing the content to be parsed.
142
* @param hb The SAX HandlerBase to use.
143
* @param systemId The systemId which is needed for resolving relative URIs.
145
* @throws IllegalArgumentException If the given <code>InputStream</code> is
147
* @throws IOException If any IO error occurs interacting with the
148
* <code>InputStream</code>.
149
* @throws SAXException If any SAX errors occur during processing.
151
* @see org.xml.sax.DocumentHandler version of this method instead.
157
throws SAXException, IOException {
159
throw new IllegalArgumentException("InputStream cannot be null");
162
InputSource input = new InputSource(is);
163
input.setSystemId(systemId);
164
this.parse(input, hb);
168
* Parse the content of the given {@link java.io.InputStream}
169
* instance as XML using the specified
170
* {@link org.xml.sax.helpers.DefaultHandler}.
172
* @param is InputStream containing the content to be parsed.
173
* @param dh The SAX DefaultHandler to use.
175
* @throws IllegalArgumentException If the given InputStream is null.
176
* @throws IOException If any IO errors occur.
177
* @throws SAXException If any SAX errors occur during processing.
179
* @see org.xml.sax.DocumentHandler
181
public void parse(InputStream is, DefaultHandler dh)
182
throws SAXException, IOException {
184
throw new IllegalArgumentException("InputStream cannot be null");
187
InputSource input = new InputSource(is);
188
this.parse(input, dh);
192
* Parse the content of the given {@link java.io.InputStream}
193
* instance as XML using the specified
194
* {@link org.xml.sax.helpers.DefaultHandler}.
196
* @param is InputStream containing the content to be parsed.
197
* @param dh The SAX DefaultHandler to use.
198
* @param systemId The systemId which is needed for resolving relative URIs.
200
* @throws IllegalArgumentException If the given InputStream is null.
201
* @throws IOException If any IO errors occur.
202
* @throws SAXException If any SAX errors occur during processing.
204
* @see org.xml.sax.DocumentHandler version of this method instead.
210
throws SAXException, IOException {
212
throw new IllegalArgumentException("InputStream cannot be null");
215
InputSource input = new InputSource(is);
216
input.setSystemId(systemId);
217
this.parse(input, dh);
221
* Parse the content described by the giving Uniform Resource
222
* Identifier (URI) as XML using the specified
223
* {@link org.xml.sax.HandlerBase}.
224
* <i> Use of the DefaultHandler version of this method is recommended as
225
* the <code>HandlerBase</code> class has been deprecated in SAX 2.0</i>
227
* @param uri The location of the content to be parsed.
228
* @param hb The SAX HandlerBase to use.
230
* @throws IllegalArgumentException If the uri is null.
231
* @throws IOException If any IO errors occur.
232
* @throws SAXException If any SAX errors occur during processing.
234
* @see org.xml.sax.DocumentHandler
236
public void parse(String uri, HandlerBase hb)
237
throws SAXException, IOException {
239
throw new IllegalArgumentException("uri cannot be null");
242
InputSource input = new InputSource(uri);
243
this.parse(input, hb);
247
* Parse the content described by the giving Uniform Resource
248
* Identifier (URI) as XML using the specified
249
* {@link org.xml.sax.helpers.DefaultHandler}.
251
* @param uri The location of the content to be parsed.
252
* @param dh The SAX DefaultHandler to use.
254
* @throws IllegalArgumentException If the uri is null.
255
* @throws IOException If any IO errors occur.
256
* @throws SAXException If any SAX errors occur during processing.
258
* @see org.xml.sax.DocumentHandler
260
public void parse(String uri, DefaultHandler dh)
261
throws SAXException, IOException {
263
throw new IllegalArgumentException("uri cannot be null");
266
InputSource input = new InputSource(uri);
267
this.parse(input, dh);
271
* Parse the content of the file specified as XML using the
272
* specified {@link org.xml.sax.HandlerBase}.
273
* <i> Use of the DefaultHandler version of this method is recommended as
274
* the HandlerBase class has been deprecated in SAX 2.0</i>
276
* @param f The file containing the XML to parse
277
* @param hb The SAX HandlerBase to use.
279
* @throws IllegalArgumentException If the File object is null.
280
* @throws IOException If any IO errors occur.
281
* @throws SAXException If any SAX errors occur during processing.
283
* @see org.xml.sax.DocumentHandler
285
public void parse(File f, HandlerBase hb)
286
throws SAXException, IOException {
288
throw new IllegalArgumentException("File cannot be null");
291
String escapedURI = FilePathToURI.filepath2URI(f.getAbsolutePath());
294
System.out.println("Escaped URI = " + escapedURI);
297
InputSource input = new InputSource(escapedURI);
298
this.parse(input, hb);
302
* Parse the content of the file specified as XML using the
303
* specified {@link org.xml.sax.helpers.DefaultHandler}.
305
* @param f The file containing the XML to parse
306
* @param dh The SAX DefaultHandler to use.
308
* @throws IllegalArgumentException If the File object is null.
309
* @throws IOException If any IO errors occur.
310
* @throws SAXException If any SAX errors occur during processing.
312
* @see org.xml.sax.DocumentHandler
314
public void parse(File f, DefaultHandler dh)
315
throws SAXException, IOException {
317
throw new IllegalArgumentException("File cannot be null");
320
String escapedURI = FilePathToURI.filepath2URI(f.getAbsolutePath());
323
System.out.println("Escaped URI = " + escapedURI);
326
InputSource input = new InputSource(escapedURI);
327
this.parse(input, dh);
331
* Parse the content given {@link org.xml.sax.InputSource}
332
* as XML using the specified
333
* {@link org.xml.sax.HandlerBase}.
334
* <i> Use of the DefaultHandler version of this method is recommended as
335
* the HandlerBase class has been deprecated in SAX 2.0</i>
337
* @param is The InputSource containing the content to be parsed.
338
* @param hb The SAX HandlerBase to use.
340
* @throws IllegalArgumentException If the <code>InputSource</code> object
341
* is <code>null</code>.
342
* @throws IOException If any IO errors occur.
343
* @throws SAXException If any SAX errors occur during processing.
345
* @see org.xml.sax.DocumentHandler
347
public void parse(InputSource is, HandlerBase hb)
348
throws SAXException, IOException {
350
throw new IllegalArgumentException("InputSource cannot be null");
353
Parser parser = this.getParser();
355
parser.setDocumentHandler(hb);
356
parser.setEntityResolver(hb);
357
parser.setErrorHandler(hb);
358
parser.setDTDHandler(hb);
364
* Parse the content given {@link org.xml.sax.InputSource}
365
* as XML using the specified
366
* {@link org.xml.sax.helpers.DefaultHandler}.
368
* @param is The InputSource containing the content to be parsed.
369
* @param dh The SAX DefaultHandler to use.
371
* @throws IllegalArgumentException If the <code>InputSource</code> object
372
* is <code>null</code>.
373
* @throws IOException If any IO errors occur.
374
* @throws SAXException If any SAX errors occur during processing.
376
* @see org.xml.sax.DocumentHandler
378
public void parse(InputSource is, DefaultHandler dh)
379
throws SAXException, IOException {
381
throw new IllegalArgumentException("InputSource cannot be null");
384
XMLReader reader = this.getXMLReader();
386
reader.setContentHandler(dh);
387
reader.setEntityResolver(dh);
388
reader.setErrorHandler(dh);
389
reader.setDTDHandler(dh);
395
* Returns the SAX parser that is encapsultated by the
396
* implementation of this class.
398
* @return The SAX parser that is encapsultated by the
399
* implementation of this class.
401
* @throws SAXException If any SAX errors occur during processing.
403
public abstract org.xml.sax.Parser getParser() throws SAXException;
406
* Returns the {@link org.xml.sax.XMLReader} that is encapsulated by the
407
* implementation of this class.
409
* @return The XMLReader that is encapsulated by the
410
* implementation of this class.
412
* @throws SAXException If any SAX errors occur during processing.
415
public abstract org.xml.sax.XMLReader getXMLReader() throws SAXException;
418
* Indicates whether or not this parser is configured to
419
* understand namespaces.
421
* @return true if this parser is configured to
422
* understand namespaces; false otherwise.
425
public abstract boolean isNamespaceAware();
428
* Indicates whether or not this parser is configured to
429
* validate XML documents.
431
* @return true if this parser is configured to
432
* validate XML documents; false otherwise.
435
public abstract boolean isValidating();
438
* <p>Sets the particular property in the underlying implementation of
439
* {@link org.xml.sax.XMLReader}.
440
* A list of the core features and properties can be found at
441
* <a href="http://sax.sourceforge.net/?selected=get-set">
442
* http://sax.sourceforge.net/?selected=get-set</a>.</p>
444
* @param name The name of the property to be set.
445
* @param value The value of the property to be set.
447
* @throws SAXNotRecognizedException When the underlying XMLReader does
448
* not recognize the property name.
449
* @throws SAXNotSupportedException When the underlying XMLReader
450
* recognizes the property name but doesn't support the property.
452
* @see org.xml.sax.XMLReader#setProperty
454
public abstract void setProperty(String name, Object value)
455
throws SAXNotRecognizedException, SAXNotSupportedException;
458
* <p>Returns the particular property requested for in the underlying
459
* implementation of {@link org.xml.sax.XMLReader}.</p>
461
* @param name The name of the property to be retrieved.
462
* @return Value of the requested property.
464
* @throws SAXNotRecognizedException When the underlying XMLReader does
465
* not recognize the property name.
466
* @throws SAXNotSupportedException When the underlying XMLReader
467
* recognizes the property name but doesn't support the property.
469
* @see org.xml.sax.XMLReader#getProperty
471
public abstract Object getProperty(String name)
472
throws SAXNotRecognizedException, SAXNotSupportedException;
474
/** <p>Get current state of canonicalization.</p>
476
* @return current state canonicalization control
479
public boolean getCanonicalization() {
480
return canonicalState;
484
/** <p>Get a reference to the the {@link Schema} being used by
485
* the XML processor.</p>
487
* <p>If no schema is being used, <code>null</code> is returned.</p>
489
* @return {@link Schema} being used or <code>null</code>
492
* @throws UnsupportedOperationException
493
* For backward compatibility, when implementations for
494
* earlier versions of JAXP is used, this exception will be
499
public Schema getSchema() {
500
throw new UnsupportedOperationException(
501
"This parser does not support specification \""
502
+ this.getClass().getPackage().getSpecificationTitle()
504
+ this.getClass().getPackage().getSpecificationVersion()
510
* <p>Get the XInclude processing mode for this parser.</p>
513
* the return value of
514
* the {@link SAXParserFactory#isXIncludeAware()}
515
* when this parser was created from factory.
517
* @throws UnsupportedOperationException
518
* For backward compatibility, when implementations for
519
* earlier versions of JAXP is used, this exception will be
524
* @see SAXParserFactory#setXIncludeAware(boolean)
526
public boolean isXIncludeAware() {
527
throw new UnsupportedOperationException(
528
"This parser does not support specification \""
529
+ this.getClass().getPackage().getSpecificationTitle()
531
+ this.getClass().getPackage().getSpecificationVersion()
added
removed
javax/xml/parsers/SAXParser.java
