FileDocCategorySizeDatePackage
SAXParser.javaAPI DocJava SE 6 API19479Tue Jun 10 00:27:08 BST 2008javax.xml.parsers

SAXParser

public abstract class SAXParser extends Object
Defines the API that wraps an {@link org.xml.sax.XMLReader} implementation class. In JAXP 1.0, this class wrapped the {@link org.xml.sax.Parser} interface, however this interface was replaced by the {@link org.xml.sax.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 {@link javax.xml.parsers.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 {@link org.xml.sax.HandlerBase} or the {@link org.xml.sax.helpers.DefaultHandler} are called.

Implementors of this class which wrap an underlaying implementation can consider using the {@link org.xml.sax.helpers.ParserAdapter} class to initially adapt their SAX1 impelemntation to work under this revised class.

author
Jeff Suttor
version
$Revision: 1.4 $, $Date: 2005/11/03 19:34:15 $

Fields Summary
Constructors Summary
protected SAXParser()

Protected constructor to prevent instaniation. Use {@link javax.xml.parsers.SAXParserFactory#newSAXParser()}.
Methods Summary
public abstract org.xml.sax.ParsergetParser()
Returns the SAX parser that is encapsultated by the implementation of this class.

return
The SAX parser that is encapsultated by the implementation of this class.
throws
SAXException If any SAX errors occur during processing.

public abstract java.lang.ObjectgetProperty(java.lang.String name)
Returns the particular property requested for in the underlying
implementation of {@link org.xml.sax.XMLReader}.
param
name The name of the property to be retrieved.
return
Value of the requested property.
throws
SAXNotRecognizedException When the underlying XMLReader does
not recognize the property name.
throws
SAXNotSupportedException When the underlying XMLReader
recognizes the property name but doesn't support the property.
see
org.xml.sax.XMLReader#getProperty
public javax.xml.validation.SchemagetSchema()
Get a reference to the the {@link Schema} being used by
the XML processor.



If no schema is being used, null is returned.
return
{@link Schema} being used or null
if none in use
throws
UnsupportedOperationException When implementation does not
override this method
since
1.5
        throw new UnsupportedOperationException(
            "This parser does not support specification \""
            + this.getClass().getPackage().getSpecificationTitle()
            + "\" version \""
            + this.getClass().getPackage().getSpecificationVersion()
            + "\""
            );
    
public abstract org.xml.sax.XMLReadergetXMLReader()
Returns the {@link org.xml.sax.XMLReader} that is encapsulated by the
implementation of this class.
return
The XMLReader that is encapsulated by the
implementation of this class.
throws
SAXException If any SAX errors occur during processing.
public abstract booleanisNamespaceAware()
Indicates whether or not this parser is configured to
understand namespaces.
return
true if this parser is configured to
understand namespaces; false otherwise.
public abstract booleanisValidating()
Indicates whether or not this parser is configured to
validate XML documents.
return
true if this parser is configured to
validate XML documents; false otherwise.
public booleanisXIncludeAware()
Get the XInclude processing mode for this parser.
return
the return value of
the {@link SAXParserFactory#isXIncludeAware()}
when this parser was created from factory.
throws
UnsupportedOperationException When implementation does not
override this method
since
1.5
see
SAXParserFactory#setXIncludeAware(boolean)
        throw new UnsupportedOperationException(
            "This parser does not support specification \""
            + this.getClass().getPackage().getSpecificationTitle()
            + "\" version \""
            + this.getClass().getPackage().getSpecificationVersion()
            + "\""
            );
    
public voidparse(java.io.File f, org.xml.sax.helpers.DefaultHandler dh)
Parse the content of the file specified as XML using the
specified {@link org.xml.sax.helpers.DefaultHandler}.
param
f The file containing the XML to parse
param
dh The SAX DefaultHandler to use.
throws
IllegalArgumentException If the File object is null.
throws
IOException If any IO errors occur.
throws
SAXException If any SAX errors occur during processing.
see
org.xml.sax.DocumentHandler
        if (f == null) {
            throw new IllegalArgumentException("File cannot be null");
        }

        //convert file to appropriate URI, f.toURI().toASCIIString() 
        //converts the URI to string as per rule specified in
        //RFC 2396,
        InputSource input = new InputSource(f.toURI().toASCIIString());   
        this.parse(input, dh);
    
public voidparse(org.xml.sax.InputSource is, org.xml.sax.HandlerBase hb)
Parse the content given {@link org.xml.sax.InputSource}
as XML using the specified
{@link org.xml.sax.HandlerBase}.
 Use of the DefaultHandler version of this method is recommended as
the HandlerBase class has been deprecated in SAX 2.0
param
is The InputSource containing the content to be parsed.
param
hb The SAX HandlerBase to use.
throws
IllegalArgumentException If the InputSource object
is null.
throws
IOException If any IO errors occur.
throws
SAXException If any SAX errors occur during processing.
see
org.xml.sax.DocumentHandler
        if (is == null) {
            throw new IllegalArgumentException("InputSource cannot be null");
        }

        Parser parser = this.getParser();
        if (hb != null) {
            parser.setDocumentHandler(hb);
            parser.setEntityResolver(hb);
            parser.setErrorHandler(hb);
            parser.setDTDHandler(hb);
        }
        parser.parse(is);
    
public voidparse(org.xml.sax.InputSource is, org.xml.sax.helpers.DefaultHandler dh)
Parse the content given {@link org.xml.sax.InputSource}
as XML using the specified
{@link org.xml.sax.helpers.DefaultHandler}.
param
is The InputSource containing the content to be parsed.
param
dh The SAX DefaultHandler to use.
throws
IllegalArgumentException If the InputSource object
is null.
throws
IOException If any IO errors occur.
throws
SAXException If any SAX errors occur during processing.
see
org.xml.sax.DocumentHandler
        if (is == null) {
            throw new IllegalArgumentException("InputSource cannot be null");
        }

        XMLReader reader = this.getXMLReader();
        if (dh != null) {
            reader.setContentHandler(dh);
            reader.setEntityResolver(dh);
            reader.setErrorHandler(dh);
            reader.setDTDHandler(dh);
        }
        reader.parse(is);
    
public voidparse(java.io.InputStream is, org.xml.sax.HandlerBase hb)
Parse the content of the given {@link java.io.InputStream}
instance as XML using the specified {@link org.xml.sax.HandlerBase}.
 Use of the DefaultHandler version of this method is recommended as
the HandlerBase class has been deprecated in SAX 2.0.
param
is InputStream containing the content to be parsed.
param
hb The SAX HandlerBase to use.
throws
IllegalArgumentException If the given InputStream is null.
throws
SAXException If parse produces a SAX error.
throws
IOException If an IO error occurs interacting with the
InputStream.
see
org.xml.sax.DocumentHandler
        if (is == null) {
            throw new IllegalArgumentException("InputStream cannot be null");
        }

        InputSource input = new InputSource(is);
        this.parse(input, hb);
    
public voidparse(java.io.InputStream is, org.xml.sax.HandlerBase hb, java.lang.String systemId)
Parse the content of the given {@link java.io.InputStream}
instance as XML using the specified {@link org.xml.sax.HandlerBase}.
 Use of the DefaultHandler version of this method is recommended as
the HandlerBase class has been deprecated in SAX 2.0.
param
is InputStream containing the content to be parsed.
param
hb The SAX HandlerBase to use.
param
systemId The systemId which is needed for resolving relative URIs.
throws
IllegalArgumentException If the given InputStream is
null.
throws
IOException If any IO error occurs interacting with the
InputStream.
throws
SAXException If any SAX errors occur during processing.
see
org.xml.sax.DocumentHandler version of this method instead.
        if (is == null) {
            throw new IllegalArgumentException("InputStream cannot be null");
        }

        InputSource input = new InputSource(is);
        input.setSystemId(systemId);
        this.parse(input, hb);
    
public voidparse(java.io.InputStream is, org.xml.sax.helpers.DefaultHandler dh)
Parse the content of the given {@link java.io.InputStream}
instance as XML using the specified
{@link org.xml.sax.helpers.DefaultHandler}.
param
is InputStream containing the content to be parsed.
param
dh The SAX DefaultHandler to use.
throws
IllegalArgumentException If the given InputStream is null.
throws
IOException If any IO errors occur.
throws
SAXException If any SAX errors occur during processing.
see
org.xml.sax.DocumentHandler
        if (is == null) {
            throw new IllegalArgumentException("InputStream cannot be null");
        }

        InputSource input = new InputSource(is);
        this.parse(input, dh);
    
public voidparse(java.io.InputStream is, org.xml.sax.helpers.DefaultHandler dh, java.lang.String systemId)
Parse the content of the given {@link java.io.InputStream}
instance as XML using the specified
{@link org.xml.sax.helpers.DefaultHandler}.
param
is InputStream containing the content to be parsed.
param
dh The SAX DefaultHandler to use.
param
systemId The systemId which is needed for resolving relative URIs.
throws
IllegalArgumentException If the given InputStream is null.
throws
IOException If any IO errors occur.
throws
SAXException If any SAX errors occur during processing.
see
org.xml.sax.DocumentHandler version of this method instead.
        if (is == null) {
            throw new IllegalArgumentException("InputStream cannot be null");
        }

        InputSource input = new InputSource(is);
        input.setSystemId(systemId);
        this.parse(input, dh);
    
public voidparse(java.lang.String uri, org.xml.sax.HandlerBase hb)
Parse the content described by the giving Uniform Resource
Identifier (URI) as XML using the specified
{@link org.xml.sax.HandlerBase}.
 Use of the DefaultHandler version of this method is recommended as
the HandlerBase class has been deprecated in SAX 2.0
param
uri The location of the content to be parsed.
param
hb The SAX HandlerBase to use.
throws
IllegalArgumentException If the uri is null.
throws
IOException If any IO errors occur.
throws
SAXException If any SAX errors occur during processing.
see
org.xml.sax.DocumentHandler
        if (uri == null) {
            throw new IllegalArgumentException("uri cannot be null");
        }

        InputSource input = new InputSource(uri);
        this.parse(input, hb);
    
public voidparse(java.lang.String uri, org.xml.sax.helpers.DefaultHandler dh)
Parse the content described by the giving Uniform Resource
Identifier (URI) as XML using the specified
{@link org.xml.sax.helpers.DefaultHandler}.
param
uri The location of the content to be parsed.
param
dh The SAX DefaultHandler to use.
throws
IllegalArgumentException If the uri is null.
throws
IOException If any IO errors occur.
throws
SAXException If any SAX errors occur during processing.
see
org.xml.sax.DocumentHandler
        if (uri == null) {
            throw new IllegalArgumentException("uri cannot be null");
        }

        InputSource input = new InputSource(uri);
        this.parse(input, dh);
    
public voidparse(java.io.File f, org.xml.sax.HandlerBase hb)
Parse the content of the file specified as XML using the
specified {@link org.xml.sax.HandlerBase}.
 Use of the DefaultHandler version of this method is recommended as
the HandlerBase class has been deprecated in SAX 2.0
param
f The file containing the XML to parse
param
hb The SAX HandlerBase to use.
throws
IllegalArgumentException If the File object is null.
throws
IOException If any IO errors occur.
throws
SAXException If any SAX errors occur during processing.
see
org.xml.sax.DocumentHandler
        if (f == null) {
            throw new IllegalArgumentException("File cannot be null");
        }

        //convert file to appropriate URI, f.toURI().toASCIIString() 
        //converts the URI to string as per rule specified in
        //RFC 2396,
        InputSource input = new InputSource(f.toURI().toASCIIString());   
        this.parse(input, hb);
    
public voidreset()
Reset this SAXParser to its original configuration.



SAXParser is reset to the same state as when it was created with
{@link SAXParserFactory#newSAXParser()}.
reset() is designed to allow the reuse of existing SAXParsers
thus saving resources associated with the creation of new SAXParsers.



The reset SAXParser is not guaranteed to have the same {@link Schema}
Object, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal
Schema.
throws
UnsupportedOperationException When Implementations do not
override this method
since
1.5

		// implementors should override this method
		throw new UnsupportedOperationException(
			"This SAXParser, \"" + this.getClass().getName() + "\", does not support the reset functionality."
			+ "  Specification \"" + this.getClass().getPackage().getSpecificationTitle() + "\""
			+ " version \"" + this.getClass().getPackage().getSpecificationVersion() + "\""
			);
	
public abstract voidsetProperty(java.lang.String name, java.lang.Object value)
Sets the particular property in the underlying implementation of
{@link org.xml.sax.XMLReader}.
A list of the core features and properties can be found at

http://sax.sourceforge.net/?selected=get-set.
param
name The name of the property to be set.
param
value The value of the property to be set.
throws
SAXNotRecognizedException When the underlying XMLReader does
not recognize the property name.
throws
SAXNotSupportedException When the underlying XMLReader
recognizes the property name but doesn't support the property.
see
org.xml.sax.XMLReader#setProperty