javax.xml.parsers

## Class SAXParser

- java.lang.Object
- - javax.xml.parsers.SAXParser

-     public abstract class SAXParser
      extends java.lang.Object

  Defines the API that wraps an `XMLReader` implementation class. In JAXP 1.0, this class wrapped the `Parser` interface, however this interface was replaced by the `XMLReader`. For ease of transition, this class continues to support the same name and interface as well as supporting new methods. An instance of this class can be obtained from the `SAXParserFactory.newSAXParser()` method. Once an instance of this class is obtained, XML can be parsed from a variety of input sources. These input sources are InputStreams, Files, URLs, and SAX InputSources.

  This static method creates a new factory instance based on a system property setting or uses the platform default if no property has been defined.

  The system property that controls which Factory implementation to create is named `"javax.xml.parsers.SAXParserFactory"`. This property names a class that is a concrete subclass of this abstract class. If no property is defined, a platform default will be used.

  As the content is parsed by the underlying parser, methods of the given `HandlerBase` or the `DefaultHandler` are called.

  Implementors of this class which wrap an underlaying implementation can consider using the `ParserAdapter` class to initially adapt their SAX1 implementation to work under this revised class.

  Version:
    $Revision: 584483 $, $Date: 2007-10-13 22:54:48 -0400 (Sat, 13 Oct 2007) $
  Author:
    Jeff Suttor

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `SAXParser()` Protected constructor to prevent instantiation.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract Parser` | `getParser()` Returns the SAX parser that is encapsulated by the implementation of this class.
    `abstract java.lang.Object` | `getProperty(java.lang.String name)` Returns the particular property requested for in the underlying implementation of `XMLReader`.
    `Schema` | `getSchema()` Get a reference to the the `Schema` being used by the XML processor.
    `abstract XMLReader` | `getXMLReader()` Returns the `XMLReader` that is encapsulated by the implementation of this class.
    `abstract boolean` | `isNamespaceAware()` Indicates whether or not this parser is configured to understand namespaces.
    `abstract boolean` | `isValidating()` Indicates whether or not this parser is configured to validate XML documents.
    `boolean` | `isXIncludeAware()` Get the XInclude processing mode for this parser.
    `void` | `parse(java.io.File f, DefaultHandler dh)` Parse the content of the file specified as XML using the specified `DefaultHandler`.
    `void` | `parse(java.io.File f, HandlerBase hb)` Parse the content of the file specified as XML using the specified `HandlerBase`.
    `void` | `parse(InputSource is, DefaultHandler dh)` Parse the content given `InputSource` as XML using the specified `DefaultHandler`.
    `void` | `parse(InputSource is, HandlerBase hb)` Parse the content given `InputSource` as XML using the specified `HandlerBase`.
    `void` | `parse(java.io.InputStream is, DefaultHandler dh)` Parse the content of the given `InputStream` instance as XML using the specified `DefaultHandler`.
    `void` | `parse(java.io.InputStream is, DefaultHandler dh, java.lang.String systemId)` Parse the content of the given `InputStream` instance as XML using the specified `DefaultHandler`.
    `void` | `parse(java.io.InputStream is, HandlerBase hb)` Parse the content of the given `InputStream` instance as XML using the specified `HandlerBase`.
    `void` | `parse(java.io.InputStream is, HandlerBase hb, java.lang.String systemId)` Parse the content of the given `InputStream` instance as XML using the specified `HandlerBase`.
    `void` | `parse(java.lang.String uri, DefaultHandler dh)` Parse the content described by the giving Uniform Resource Identifier (URI) as XML using the specified `DefaultHandler`.
    `void` | `parse(java.lang.String uri, HandlerBase hb)` Parse the content described by the giving Uniform Resource Identifier (URI) as XML using the specified `HandlerBase`.
    `void` | `reset()` Reset this `SAXParser` to its original configuration.
    `abstract void` | `setProperty(java.lang.String name, java.lang.Object value)` Sets the particular property in the underlying implementation of `XMLReader`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### SAXParser

          protected SAXParser()

      Protected constructor to prevent instantiation. Use `SAXParserFactory.newSAXParser()`.

  - ### Method Detail

    - #### reset

          public void reset()

      Reset this `SAXParser` to its original configuration.

      `SAXParser` is reset to the same state as when it was created with `SAXParserFactory.newSAXParser()`. `reset()` is designed to allow the reuse of existing `SAXParser`s thus saving resources associated with the creation of new `SAXParser`s.

      The reset `SAXParser` is not guaranteed to have the same `Schema` `Object`, e.g. `Object.equals(Object obj)`. It is guaranteed to have a functionally equal `Schema`.

      Since:
        1.5

    - #### parse

          public void parse(java.io.InputStream is,
                            HandlerBase hb)
                     throws SAXException,
                            java.io.IOException

      Parse the content of the given `InputStream` instance as XML using the specified `HandlerBase`. Use of the DefaultHandler version of this method is recommended as the HandlerBase class has been deprecated in SAX 2.0.

      Parameters:
        `is` - InputStream containing the content to be parsed.
        `hb` - The SAX HandlerBase to use.
      Throws:
        `java.lang.IllegalArgumentException` - If the given InputStream is null.
        `SAXException` - If parse produces a SAX error.
        `java.io.IOException` - If an IO error occurs interacting with the `InputStream`.
      See Also:
        `DocumentHandler`

    - #### parse

          public void parse(java.io.InputStream is,
                            HandlerBase hb,
                            java.lang.String systemId)
                     throws SAXException,
                            java.io.IOException

      Parse the content of the given `InputStream` instance as XML using the specified `HandlerBase`. Use of the DefaultHandler version of this method is recommended as the HandlerBase class has been deprecated in SAX 2.0.

      Parameters:
        `is` - InputStream containing the content to be parsed.
        `hb` - The SAX HandlerBase to use.
        `systemId` - The systemId which is needed for resolving relative URIs.
      Throws:
        `java.lang.IllegalArgumentException` - If the given `InputStream` is `null`.
        `java.io.IOException` - If any IO error occurs interacting with the `InputStream`.
        `SAXException` - If any SAX errors occur during processing.
      See Also:
        `version of this method instead.`

    - #### parse

          public void parse(java.io.InputStream is,
                            DefaultHandler dh)
                     throws SAXException,
                            java.io.IOException

      Parse the content of the given `InputStream` instance as XML using the specified `DefaultHandler`.
      Parameters:
        `is` - InputStream containing the content to be parsed.
        `dh` - The SAX DefaultHandler to use.
      Throws:
        `java.lang.IllegalArgumentException` - If the given InputStream is null.
        `java.io.IOException` - If any IO errors occur.
        `SAXException` - If any SAX errors occur during processing.
      See Also:
        `DocumentHandler`

    - #### parse

          public void parse(java.io.InputStream is,
                            DefaultHandler dh,
                            java.lang.String systemId)
                     throws SAXException,
                            java.io.IOException

      Parse the content of the given `InputStream` instance as XML using the specified `DefaultHandler`.
      Parameters:
        `is` - InputStream containing the content to be parsed.
        `dh` - The SAX DefaultHandler to use.
        `systemId` - The systemId which is needed for resolving relative URIs.
      Throws:
        `java.lang.IllegalArgumentException` - If the given InputStream is null.
        `java.io.IOException` - If any IO errors occur.
        `SAXException` - If any SAX errors occur during processing.
      See Also:
        `version of this method instead.`

    - #### parse

          public void parse(java.lang.String uri,
                            HandlerBase hb)
                     throws SAXException,
                            java.io.IOException

      Parse the content described by the giving Uniform Resource Identifier (URI) as XML using the specified `HandlerBase`. Use of the DefaultHandler version of this method is recommended as the `HandlerBase` class has been deprecated in SAX 2.0
      Parameters:
        `uri` - The location of the content to be parsed.
        `hb` - The SAX HandlerBase to use.
      Throws:
        `java.lang.IllegalArgumentException` - If the uri is null.
        `java.io.IOException` - If any IO errors occur.
        `SAXException` - If any SAX errors occur during processing.
      See Also:
        `DocumentHandler`

    - #### parse

          public void parse(java.lang.String uri,
                            DefaultHandler dh)
                     throws SAXException,
                            java.io.IOException

      Parse the content described by the giving Uniform Resource Identifier (URI) as XML using the specified `DefaultHandler`.
      Parameters:
        `uri` - The location of the content to be parsed.
        `dh` - The SAX DefaultHandler to use.
      Throws:
        `java.lang.IllegalArgumentException` - If the uri is null.
        `java.io.IOException` - If any IO errors occur.
        `SAXException` - If any SAX errors occur during processing.
      See Also:
        `DocumentHandler`

    - #### parse

          public void parse(java.io.File f,
                            HandlerBase hb)
                     throws SAXException,
                            java.io.IOException

      Parse the content of the file specified as XML using the specified `HandlerBase`. Use of the DefaultHandler version of this method is recommended as the HandlerBase class has been deprecated in SAX 2.0
      Parameters:
        `f` - The file containing the XML to parse
        `hb` - The SAX HandlerBase to use.
      Throws:
        `java.lang.IllegalArgumentException` - If the File object is null.
        `java.io.IOException` - If any IO errors occur.
        `SAXException` - If any SAX errors occur during processing.
      See Also:
        `DocumentHandler`

    - #### parse

          public void parse(java.io.File f,
                            DefaultHandler dh)
                     throws SAXException,
                            java.io.IOException

      Parse the content of the file specified as XML using the specified `DefaultHandler`.
      Parameters:
        `f` - The file containing the XML to parse
        `dh` - The SAX DefaultHandler to use.
      Throws:
        `java.lang.IllegalArgumentException` - If the File object is null.
        `java.io.IOException` - If any IO errors occur.
        `SAXException` - If any SAX errors occur during processing.
      See Also:
        `DocumentHandler`

    - #### parse

          public void parse(InputSource is,
                            HandlerBase hb)
                     throws SAXException,
                            java.io.IOException

      Parse the content given `InputSource` as XML using the specified `HandlerBase`. Use of the DefaultHandler version of this method is recommended as the HandlerBase class has been deprecated in SAX 2.0
      Parameters:
        `is` - The InputSource containing the content to be parsed.
        `hb` - The SAX HandlerBase to use.
      Throws:
        `java.lang.IllegalArgumentException` - If the `InputSource` object is `null`.
        `java.io.IOException` - If any IO errors occur.
        `SAXException` - If any SAX errors occur during processing.
      See Also:
        `DocumentHandler`

    - #### parse

          public void parse(InputSource is,
                            DefaultHandler dh)
                     throws SAXException,
                            java.io.IOException

      Parse the content given `InputSource` as XML using the specified `DefaultHandler`.
      Parameters:
        `is` - The InputSource containing the content to be parsed.
        `dh` - The SAX DefaultHandler to use.
      Throws:
        `java.lang.IllegalArgumentException` - If the `InputSource` object is `null`.
        `java.io.IOException` - If any IO errors occur.
        `SAXException` - If any SAX errors occur during processing.
      See Also:
        `DocumentHandler`

    - #### getParser

          public abstract Parser getParser()
                                    throws SAXException

      Returns the SAX parser that is encapsulated by the implementation of this class.
      Returns:
        The SAX parser that is encapsulated by the implementation of this class.
      Throws:
        `SAXException` - If any SAX errors occur during processing.

    - #### getXMLReader

          public abstract XMLReader getXMLReader()
                                          throws SAXException

      Returns the `XMLReader` that is encapsulated by the implementation of this class.
      Returns:
        The XMLReader that is encapsulated by the implementation of this class.
      Throws:
        `SAXException` - If any SAX errors occur during processing.

    - #### isNamespaceAware

          public abstract boolean isNamespaceAware()

      Indicates whether or not this parser is configured to understand namespaces.
      Returns:
        true if this parser is configured to understand namespaces; false otherwise.

    - #### isValidating

          public abstract boolean isValidating()

      Indicates whether or not this parser is configured to validate XML documents.
      Returns:
        true if this parser is configured to validate XML documents; false otherwise.

    - #### setProperty

          public abstract void setProperty(java.lang.String name,
                                           java.lang.Object value)
                                    throws SAXNotRecognizedException,
                                           SAXNotSupportedException

      Sets the particular property in the underlying implementation of `XMLReader`. A list of the core features and properties can be found at http://sax.sourceforge.net/?selected=get-set.

      Parameters:
        `name` - The name of the property to be set.
        `value` - The value of the property to be set.
      Throws:
        `SAXNotRecognizedException` - When the underlying XMLReader does not recognize the property name.
        `SAXNotSupportedException` - When the underlying XMLReader recognizes the property name but doesn't support the property.
      See Also:
        `XMLReader.setProperty(java.lang.String, java.lang.Object)`

    - #### getProperty

          public abstract java.lang.Object getProperty(java.lang.String name)
                                                throws SAXNotRecognizedException,
                                                       SAXNotSupportedException

      Returns the particular property requested for in the underlying implementation of `XMLReader`.

      Parameters:
        `name` - The name of the property to be retrieved.
      Returns:
        Value of the requested property.
      Throws:
        `SAXNotRecognizedException` - When the underlying XMLReader does not recognize the property name.
        `SAXNotSupportedException` - When the underlying XMLReader recognizes the property name but doesn't support the property.
      See Also:
        `XMLReader.getProperty(java.lang.String)`

    - #### getSchema

          public Schema getSchema()

      Get a reference to the the `Schema` being used by the XML processor.

      If no schema is being used, `null` is returned.

      Returns:
        `Schema` being used or `null` if none in use
      Throws:
        `java.lang.UnsupportedOperationException` - For backward compatibility, when implementations for earlier versions of JAXP is used, this exception will be thrown.
      Since:
        1.5

    - #### isXIncludeAware

          public boolean isXIncludeAware()

      Get the XInclude processing mode for this parser.

      Returns:
        the return value of the `SAXParserFactory.isXIncludeAware()` when this parser was created from factory.
      Throws:
        `java.lang.UnsupportedOperationException` - For backward compatibility, when implementations for earlier versions of JAXP is used, this exception will be thrown.
      Since:
        1.5
      See Also:
        `SAXParserFactory.setXIncludeAware(boolean)`

Copyright © 1999-2010 The Apache Software Foundation. All Rights Reserved.