52 * An instance of this class can be obtained from the 53 * {@link javax.xml.parsers.SAXParserFactory#newSAXParser()} method. 54 * Once an instance of this class is obtained, XML can be parsed from 55 * a variety of input sources. These input sources are InputStreams, 56 * Files, URLs, and SAX InputSources.<p> 57 * 58 * This static method creates a new factory instance based 59 * on a system property setting or uses the platform default 60 * if no property has been defined.<p> 61 * 62 * The system property that controls which Factory implementation 63 * to create is named <code>"javax.xml.parsers.SAXParserFactory"</code>. 64 * This property names a class that is a concrete subclass of this 65 * abstract class. If no property is defined, a platform default 66 * will be used.</p> 67 * 68 * As the content is parsed by the underlying parser, methods of the 69 * given {@link org.xml.sax.HandlerBase} or the 70 * {@link org.xml.sax.helpers.DefaultHandler} are called.<p> 71 * 72 * Implementors of this class which wrap an underlaying implementation 73 * can consider using the {@link org.xml.sax.helpers.ParserAdapter} 74 * class to initially adapt their SAX1 implementation to work under 75 * this revised class. 76 * 77 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> 78 */ 79 public abstract class SAXParser { 80 81 /** 82 * <p>Protected constructor to prevent instaniation. 83 * Use {@link javax.xml.parsers.SAXParserFactory#newSAXParser()}.</p> 84 */ 85 protected SAXParser () { 86 87 } 88 89 /** 90 * <p>Reset this <code>SAXParser</code> to its original configuration.</p> 91 * 92 * <p><code>SAXParser</code> is reset to the same state as when it was created with 93 * {@link SAXParserFactory#newSAXParser()}. 94 * <code>reset()</code> is designed to allow the reuse of existing <code>SAXParser</code>s 95 * thus saving resources associated with the creation of new <code>SAXParser</code>s.</p> 96 * 97 * <p>The reset <code>SAXParser</code> is not guaranteed to have the same {@link Schema} 98 * <code>Object</code>, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal 99 * <code>Schema</code>.</p> 100 * 101 * @throws UnsupportedOperationException When Implementations do not 102 * override this method 376 * 377 * @see org.xml.sax.DocumentHandler 378 */ 379 public void parse(InputSource is, DefaultHandler dh) 380 throws SAXException, IOException { 381 if (is == null) { 382 throw new IllegalArgumentException("InputSource cannot be null"); 383 } 384 385 XMLReader reader = this.getXMLReader(); 386 if (dh != null) { 387 reader.setContentHandler(dh); 388 reader.setEntityResolver(dh); 389 reader.setErrorHandler(dh); 390 reader.setDTDHandler(dh); 391 } 392 reader.parse(is); 393 } 394 395 /** 396 * Returns the SAX parser that is encapsultated by the 397 * implementation of this class. 398 * 399 * @return The SAX parser that is encapsultated by the 400 * implementation of this class. 401 * 402 * @throws SAXException If any SAX errors occur during processing. 403 */ 404 public abstract org.xml.sax.Parser getParser() throws SAXException; 405 406 /** 407 * Returns the {@link org.xml.sax.XMLReader} that is encapsulated by the 408 * implementation of this class. 409 * 410 * @return The XMLReader that is encapsulated by the 411 * implementation of this class. 412 * 413 * @throws SAXException If any SAX errors occur during processing. 414 */ 415 416 public abstract org.xml.sax.XMLReader getXMLReader() throws SAXException; 417 418 /** 419 * Indicates whether or not this parser is configured to | 52 * An instance of this class can be obtained from the 53 * {@link javax.xml.parsers.SAXParserFactory#newSAXParser()} method. 54 * Once an instance of this class is obtained, XML can be parsed from 55 * a variety of input sources. These input sources are InputStreams, 56 * Files, URLs, and SAX InputSources.<p> 57 * 58 * This static method creates a new factory instance based 59 * on a system property setting or uses the platform default 60 * if no property has been defined.<p> 61 * 62 * The system property that controls which Factory implementation 63 * to create is named <code>"javax.xml.parsers.SAXParserFactory"</code>. 64 * This property names a class that is a concrete subclass of this 65 * abstract class. If no property is defined, a platform default 66 * will be used.</p> 67 * 68 * As the content is parsed by the underlying parser, methods of the 69 * given {@link org.xml.sax.HandlerBase} or the 70 * {@link org.xml.sax.helpers.DefaultHandler} are called.<p> 71 * 72 * Implementors of this class which wrap an underlying implementation 73 * can consider using the {@link org.xml.sax.helpers.ParserAdapter} 74 * class to initially adapt their SAX1 implementation to work under 75 * this revised class. 76 * 77 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> 78 */ 79 public abstract class SAXParser { 80 81 /** 82 * <p>Protected constructor to prevent instantiation. 83 * Use {@link javax.xml.parsers.SAXParserFactory#newSAXParser()}.</p> 84 */ 85 protected SAXParser () { 86 87 } 88 89 /** 90 * <p>Reset this <code>SAXParser</code> to its original configuration.</p> 91 * 92 * <p><code>SAXParser</code> is reset to the same state as when it was created with 93 * {@link SAXParserFactory#newSAXParser()}. 94 * <code>reset()</code> is designed to allow the reuse of existing <code>SAXParser</code>s 95 * thus saving resources associated with the creation of new <code>SAXParser</code>s.</p> 96 * 97 * <p>The reset <code>SAXParser</code> is not guaranteed to have the same {@link Schema} 98 * <code>Object</code>, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal 99 * <code>Schema</code>.</p> 100 * 101 * @throws UnsupportedOperationException When Implementations do not 102 * override this method 376 * 377 * @see org.xml.sax.DocumentHandler 378 */ 379 public void parse(InputSource is, DefaultHandler dh) 380 throws SAXException, IOException { 381 if (is == null) { 382 throw new IllegalArgumentException("InputSource cannot be null"); 383 } 384 385 XMLReader reader = this.getXMLReader(); 386 if (dh != null) { 387 reader.setContentHandler(dh); 388 reader.setEntityResolver(dh); 389 reader.setErrorHandler(dh); 390 reader.setDTDHandler(dh); 391 } 392 reader.parse(is); 393 } 394 395 /** 396 * Returns the SAX parser that is encapsulated by the 397 * implementation of this class. 398 * 399 * @return The SAX parser that is encapsulated by the 400 * implementation of this class. 401 * 402 * @throws SAXException If any SAX errors occur during processing. 403 */ 404 public abstract org.xml.sax.Parser getParser() throws SAXException; 405 406 /** 407 * Returns the {@link org.xml.sax.XMLReader} that is encapsulated by the 408 * implementation of this class. 409 * 410 * @return The XMLReader that is encapsulated by the 411 * implementation of this class. 412 * 413 * @throws SAXException If any SAX errors occur during processing. 414 */ 415 416 public abstract org.xml.sax.XMLReader getXMLReader() throws SAXException; 417 418 /** 419 * Indicates whether or not this parser is configured to |