001 /*
002 * Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.parsers;
027
028 import java.io.File;
029 import java.io.IOException;
030 import java.io.InputStream;
031
032 import javax.xml.validation.Schema;
033
034 import org.xml.sax.HandlerBase;
035 import org.xml.sax.InputSource;
036 import org.xml.sax.Parser;
037 import org.xml.sax.SAXException;
038 import org.xml.sax.SAXNotRecognizedException;
039 import org.xml.sax.SAXNotSupportedException;
040 import org.xml.sax.XMLReader;
041 import org.xml.sax.helpers.DefaultHandler;
042
043 /**
044 * Defines the API that wraps an {@link org.xml.sax.XMLReader}
045 * implementation class. In JAXP 1.0, this class wrapped the
046 * {@link org.xml.sax.Parser} interface, however this interface was
047 * replaced by the {@link org.xml.sax.XMLReader}. For ease
048 * of transition, this class continues to support the same name
049 * and interface as well as supporting new methods.
050 *
051 * An instance of this class can be obtained from the
052 * {@link javax.xml.parsers.SAXParserFactory#newSAXParser()} method.
053 * Once an instance of this class is obtained, XML can be parsed from
054 * a variety of input sources. These input sources are InputStreams,
055 * Files, URLs, and SAX InputSources.<p>
056 *
057 * This static method creates a new factory instance based
058 * on a system property setting or uses the platform default
059 * if no property has been defined.<p>
060 *
061 * The system property that controls which Factory implementation
062 * to create is named <code>"javax.xml.parsers.SAXParserFactory"</code>.
063 * This property names a class that is a concrete subclass of this
064 * abstract class. If no property is defined, a platform default
065 * will be used.</p>
066 *
067 * As the content is parsed by the underlying parser, methods of the
068 * given {@link org.xml.sax.HandlerBase} or the
069 * {@link org.xml.sax.helpers.DefaultHandler} are called.<p>
070 *
071 * Implementors of this class which wrap an underlaying implementation
072 * can consider using the {@link org.xml.sax.helpers.ParserAdapter}
073 * class to initially adapt their SAX1 implementation to work under
074 * this revised class.
075 *
076 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
077 * @version $Revision: 1.6 $, $Date: 2007/01/27 01:26:27 $
078 */
079 public abstract class SAXParser {
080
081 /**
082 * <p>Protected constructor to prevent instaniation.
083 * Use {@link javax.xml.parsers.SAXParserFactory#newSAXParser()}.</p>
084 */
085 protected SAXParser() {
086
087 }
088
089 /**
090 * <p>Reset this <code>SAXParser</code> to its original configuration.</p>
091 *
092 * <p><code>SAXParser</code> is reset to the same state as when it was created with
093 * {@link SAXParserFactory#newSAXParser()}.
094 * <code>reset()</code> is designed to allow the reuse of existing <code>SAXParser</code>s
095 * thus saving resources associated with the creation of new <code>SAXParser</code>s.</p>
096 *
097 * <p>The reset <code>SAXParser</code> is not guaranteed to have the same {@link Schema}
098 * <code>Object</code>, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal
099 * <code>Schema</code>.</p>
100 *
101 * @throws UnsupportedOperationException When Implementations do not
102 * override this method
103 *
104 * @since 1.5
105 */
106 public void reset() {
107
108 // implementors should override this method
109 throw new UnsupportedOperationException("This SAXParser, \""
110 + this .getClass().getName()
111 + "\", does not support the reset functionality."
112 + " Specification \""
113 + this .getClass().getPackage().getSpecificationTitle()
114 + "\""
115 + " version \""
116 + this .getClass().getPackage()
117 .getSpecificationVersion() + "\"");
118 }
119
120 /**
121 * <p>Parse the content of the given {@link java.io.InputStream}
122 * instance as XML using the specified {@link org.xml.sax.HandlerBase}.
123 * <i> Use of the DefaultHandler version of this method is recommended as
124 * the HandlerBase class has been deprecated in SAX 2.0</i>.</p>
125 *
126 * @param is InputStream containing the content to be parsed.
127 * @param hb The SAX HandlerBase to use.
128 *
129 * @throws IllegalArgumentException If the given InputStream is null.
130 * @throws SAXException If parse produces a SAX error.
131 * @throws IOException If an IO error occurs interacting with the
132 * <code>InputStream</code>.
133 *
134 * @see org.xml.sax.DocumentHandler
135 */
136 public void parse(InputStream is, HandlerBase hb)
137 throws SAXException, IOException {
138 if (is == null) {
139 throw new IllegalArgumentException(
140 "InputStream cannot be null");
141 }
142
143 InputSource input = new InputSource(is);
144 this .parse(input, hb);
145 }
146
147 /**
148 * <p>Parse the content of the given {@link java.io.InputStream}
149 * instance as XML using the specified {@link org.xml.sax.HandlerBase}.
150 * <i> Use of the DefaultHandler version of this method is recommended as
151 * the HandlerBase class has been deprecated in SAX 2.0</i>.</p>
152 *
153 * @param is InputStream containing the content to be parsed.
154 * @param hb The SAX HandlerBase to use.
155 * @param systemId The systemId which is needed for resolving relative URIs.
156 *
157 * @throws IllegalArgumentException If the given <code>InputStream</code> is
158 * <code>null</code>.
159 * @throws IOException If any IO error occurs interacting with the
160 * <code>InputStream</code>.
161 * @throws SAXException If any SAX errors occur during processing.
162 *
163 * @see org.xml.sax.DocumentHandler version of this method instead.
164 */
165 public void parse(InputStream is, HandlerBase hb, String systemId)
166 throws SAXException, IOException {
167 if (is == null) {
168 throw new IllegalArgumentException(
169 "InputStream cannot be null");
170 }
171
172 InputSource input = new InputSource(is);
173 input.setSystemId(systemId);
174 this .parse(input, hb);
175 }
176
177 /**
178 * Parse the content of the given {@link java.io.InputStream}
179 * instance as XML using the specified
180 * {@link org.xml.sax.helpers.DefaultHandler}.
181 *
182 * @param is InputStream containing the content to be parsed.
183 * @param dh The SAX DefaultHandler to use.
184 *
185 * @throws IllegalArgumentException If the given InputStream is null.
186 * @throws IOException If any IO errors occur.
187 * @throws SAXException If any SAX errors occur during processing.
188 *
189 * @see org.xml.sax.DocumentHandler
190 */
191 public void parse(InputStream is, DefaultHandler dh)
192 throws SAXException, IOException {
193 if (is == null) {
194 throw new IllegalArgumentException(
195 "InputStream cannot be null");
196 }
197
198 InputSource input = new InputSource(is);
199 this .parse(input, dh);
200 }
201
202 /**
203 * Parse the content of the given {@link java.io.InputStream}
204 * instance as XML using the specified
205 * {@link org.xml.sax.helpers.DefaultHandler}.
206 *
207 * @param is InputStream containing the content to be parsed.
208 * @param dh The SAX DefaultHandler to use.
209 * @param systemId The systemId which is needed for resolving relative URIs.
210 *
211 * @throws IllegalArgumentException If the given InputStream is null.
212 * @throws IOException If any IO errors occur.
213 * @throws SAXException If any SAX errors occur during processing.
214 *
215 * @see org.xml.sax.DocumentHandler version of this method instead.
216 */
217 public void parse(InputStream is, DefaultHandler dh, String systemId)
218 throws SAXException, IOException {
219 if (is == null) {
220 throw new IllegalArgumentException(
221 "InputStream cannot be null");
222 }
223
224 InputSource input = new InputSource(is);
225 input.setSystemId(systemId);
226 this .parse(input, dh);
227 }
228
229 /**
230 * Parse the content described by the giving Uniform Resource
231 * Identifier (URI) as XML using the specified
232 * {@link org.xml.sax.HandlerBase}.
233 * <i> Use of the DefaultHandler version of this method is recommended as
234 * the <code>HandlerBase</code> class has been deprecated in SAX 2.0</i>
235 *
236 * @param uri The location of the content to be parsed.
237 * @param hb The SAX HandlerBase to use.
238 *
239 * @throws IllegalArgumentException If the uri is null.
240 * @throws IOException If any IO errors occur.
241 * @throws SAXException If any SAX errors occur during processing.
242 *
243 * @see org.xml.sax.DocumentHandler
244 */
245 public void parse(String uri, HandlerBase hb) throws SAXException,
246 IOException {
247 if (uri == null) {
248 throw new IllegalArgumentException("uri cannot be null");
249 }
250
251 InputSource input = new InputSource(uri);
252 this .parse(input, hb);
253 }
254
255 /**
256 * Parse the content described by the giving Uniform Resource
257 * Identifier (URI) as XML using the specified
258 * {@link org.xml.sax.helpers.DefaultHandler}.
259 *
260 * @param uri The location of the content to be parsed.
261 * @param dh The SAX DefaultHandler to use.
262 *
263 * @throws IllegalArgumentException If the uri is null.
264 * @throws IOException If any IO errors occur.
265 * @throws SAXException If any SAX errors occur during processing.
266 *
267 * @see org.xml.sax.DocumentHandler
268 */
269 public void parse(String uri, DefaultHandler dh)
270 throws SAXException, IOException {
271 if (uri == null) {
272 throw new IllegalArgumentException("uri cannot be null");
273 }
274
275 InputSource input = new InputSource(uri);
276 this .parse(input, dh);
277 }
278
279 /**
280 * Parse the content of the file specified as XML using the
281 * specified {@link org.xml.sax.HandlerBase}.
282 * <i> Use of the DefaultHandler version of this method is recommended as
283 * the HandlerBase class has been deprecated in SAX 2.0</i>
284 *
285 * @param f The file containing the XML to parse
286 * @param hb The SAX HandlerBase to use.
287 *
288 * @throws IllegalArgumentException If the File object is null.
289 * @throws IOException If any IO errors occur.
290 * @throws SAXException If any SAX errors occur during processing.
291 *
292 * @see org.xml.sax.DocumentHandler
293 */
294 public void parse(File f, HandlerBase hb) throws SAXException,
295 IOException {
296 if (f == null) {
297 throw new IllegalArgumentException("File cannot be null");
298 }
299
300 //convert file to appropriate URI, f.toURI().toASCIIString()
301 //converts the URI to string as per rule specified in
302 //RFC 2396,
303 InputSource input = new InputSource(f.toURI().toASCIIString());
304 this .parse(input, hb);
305 }
306
307 /**
308 * Parse the content of the file specified as XML using the
309 * specified {@link org.xml.sax.helpers.DefaultHandler}.
310 *
311 * @param f The file containing the XML to parse
312 * @param dh The SAX DefaultHandler to use.
313 *
314 * @throws IllegalArgumentException If the File object is null.
315 * @throws IOException If any IO errors occur.
316 * @throws SAXException If any SAX errors occur during processing.
317 *
318 * @see org.xml.sax.DocumentHandler
319 */
320 public void parse(File f, DefaultHandler dh) throws SAXException,
321 IOException {
322 if (f == null) {
323 throw new IllegalArgumentException("File cannot be null");
324 }
325
326 //convert file to appropriate URI, f.toURI().toASCIIString()
327 //converts the URI to string as per rule specified in
328 //RFC 2396,
329 InputSource input = new InputSource(f.toURI().toASCIIString());
330 this .parse(input, dh);
331 }
332
333 /**
334 * Parse the content given {@link org.xml.sax.InputSource}
335 * as XML using the specified
336 * {@link org.xml.sax.HandlerBase}.
337 * <i> Use of the DefaultHandler version of this method is recommended as
338 * the HandlerBase class has been deprecated in SAX 2.0</i>
339 *
340 * @param is The InputSource containing the content to be parsed.
341 * @param hb The SAX HandlerBase to use.
342 *
343 * @throws IllegalArgumentException If the <code>InputSource</code> object
344 * is <code>null</code>.
345 * @throws IOException If any IO errors occur.
346 * @throws SAXException If any SAX errors occur during processing.
347 *
348 * @see org.xml.sax.DocumentHandler
349 */
350 public void parse(InputSource is, HandlerBase hb)
351 throws SAXException, IOException {
352 if (is == null) {
353 throw new IllegalArgumentException(
354 "InputSource cannot be null");
355 }
356
357 Parser parser = this .getParser();
358 if (hb != null) {
359 parser.setDocumentHandler(hb);
360 parser.setEntityResolver(hb);
361 parser.setErrorHandler(hb);
362 parser.setDTDHandler(hb);
363 }
364 parser.parse(is);
365 }
366
367 /**
368 * Parse the content given {@link org.xml.sax.InputSource}
369 * as XML using the specified
370 * {@link org.xml.sax.helpers.DefaultHandler}.
371 *
372 * @param is The InputSource containing the content to be parsed.
373 * @param dh The SAX DefaultHandler to use.
374 *
375 * @throws IllegalArgumentException If the <code>InputSource</code> object
376 * is <code>null</code>.
377 * @throws IOException If any IO errors occur.
378 * @throws SAXException If any SAX errors occur during processing.
379 *
380 * @see org.xml.sax.DocumentHandler
381 */
382 public void parse(InputSource is, DefaultHandler dh)
383 throws SAXException, IOException {
384 if (is == null) {
385 throw new IllegalArgumentException(
386 "InputSource cannot be null");
387 }
388
389 XMLReader reader = this .getXMLReader();
390 if (dh != null) {
391 reader.setContentHandler(dh);
392 reader.setEntityResolver(dh);
393 reader.setErrorHandler(dh);
394 reader.setDTDHandler(dh);
395 }
396 reader.parse(is);
397 }
398
399 /**
400 * Returns the SAX parser that is encapsultated by the
401 * implementation of this class.
402 *
403 * @return The SAX parser that is encapsultated by the
404 * implementation of this class.
405 *
406 * @throws SAXException If any SAX errors occur during processing.
407 */
408 public abstract org.xml.sax.Parser getParser() throws SAXException;
409
410 /**
411 * Returns the {@link org.xml.sax.XMLReader} that is encapsulated by the
412 * implementation of this class.
413 *
414 * @return The XMLReader that is encapsulated by the
415 * implementation of this class.
416 *
417 * @throws SAXException If any SAX errors occur during processing.
418 */
419
420 public abstract org.xml.sax.XMLReader getXMLReader()
421 throws SAXException;
422
423 /**
424 * Indicates whether or not this parser is configured to
425 * understand namespaces.
426 *
427 * @return true if this parser is configured to
428 * understand namespaces; false otherwise.
429 */
430
431 public abstract boolean isNamespaceAware();
432
433 /**
434 * Indicates whether or not this parser is configured to
435 * validate XML documents.
436 *
437 * @return true if this parser is configured to
438 * validate XML documents; false otherwise.
439 */
440
441 public abstract boolean isValidating();
442
443 /**
444 * <p>Sets the particular property in the underlying implementation of
445 * {@link org.xml.sax.XMLReader}.
446 * A list of the core features and properties can be found at
447 * <a href="http://sax.sourceforge.net/?selected=get-set">
448 * http://sax.sourceforge.net/?selected=get-set</a>.</p>
449 *
450 * @param name The name of the property to be set.
451 * @param value The value of the property to be set.
452 *
453 * @throws SAXNotRecognizedException When the underlying XMLReader does
454 * not recognize the property name.
455 * @throws SAXNotSupportedException When the underlying XMLReader
456 * recognizes the property name but doesn't support the property.
457 *
458 * @see org.xml.sax.XMLReader#setProperty
459 */
460 public abstract void setProperty(String name, Object value)
461 throws SAXNotRecognizedException, SAXNotSupportedException;
462
463 /**
464 * <p>Returns the particular property requested for in the underlying
465 * implementation of {@link org.xml.sax.XMLReader}.</p>
466 *
467 * @param name The name of the property to be retrieved.
468 * @return Value of the requested property.
469 *
470 * @throws SAXNotRecognizedException When the underlying XMLReader does
471 * not recognize the property name.
472 * @throws SAXNotSupportedException When the underlying XMLReader
473 * recognizes the property name but doesn't support the property.
474 *
475 * @see org.xml.sax.XMLReader#getProperty
476 */
477 public abstract Object getProperty(String name)
478 throws SAXNotRecognizedException, SAXNotSupportedException;
479
480 /** <p>Get current state of canonicalization.</p>
481 *
482 * @return current state canonicalization control
483 */
484 /*
485 public boolean getCanonicalization() {
486 return canonicalState;
487 }
488 */
489
490 /** <p>Get a reference to the the {@link Schema} being used by
491 * the XML processor.</p>
492 *
493 * <p>If no schema is being used, <code>null</code> is returned.</p>
494 *
495 * @return {@link Schema} being used or <code>null</code>
496 * if none in use
497 *
498 * @throws UnsupportedOperationException When implementation does not
499 * override this method
500 *
501 * @since 1.5
502 */
503 public Schema getSchema() {
504 throw new UnsupportedOperationException(
505 "This parser does not support specification \""
506 + this .getClass().getPackage()
507 .getSpecificationTitle()
508 + "\" version \""
509 + this .getClass().getPackage()
510 .getSpecificationVersion() + "\"");
511 }
512
513 /**
514 * <p>Get the XInclude processing mode for this parser.</p>
515 *
516 * @return
517 * the return value of
518 * the {@link SAXParserFactory#isXIncludeAware()}
519 * when this parser was created from factory.
520 *
521 * @throws UnsupportedOperationException When implementation does not
522 * override this method
523 *
524 * @since 1.5
525 *
526 * @see SAXParserFactory#setXIncludeAware(boolean)
527 */
528 public boolean isXIncludeAware() {
529 throw new UnsupportedOperationException(
530 "This parser does not support specification \""
531 + this .getClass().getPackage()
532 .getSpecificationTitle()
533 + "\" version \""
534 + this .getClass().getPackage()
535 .getSpecificationVersion() + "\"");
536 }
537 }
|