src/javax/xml/parsers/SAXParser.java

Print this page




  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>&quot;javax.xml.parsers.SAXParserFactory&quot;</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>&quot;javax.xml.parsers.SAXParserFactory&quot;</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