gnu.xml.stream

Class SAXParser

Implemented Interfaces:
Attributes, Attributes2, Locator, Locator2, XMLReader, XMLReporter, XMLResolver

public class SAXParser
extends SAXParser
implements XMLReader, Attributes2, Locator2, XMLReporter, XMLResolver

JAXP SAX parser using an underlying StAX parser. This parser supports the following additional SAX features and properties:
Features
http://gnu.org/sax/features/xml-baseread/writeIndicates or sets whether XML Base processing is enabled
Properties
http://gnu.org/sax/properties/base-uriread-onlyStringReturns the base URI of the current event
http://gnu.org/sax/properties/document-xml-encodingread-onlyStringReturns the encoding specified in the XML declaration

Constructor Summary

SAXParser()
The basic constructor.

Method Summary

int
getColumnNumber()
Return the column number where the current document event ends.
ContentHandler
getContentHandler()
DTDHandler
getDTDHandler()
String
getEncoding()
EntityResolver
getEntityResolver()
ErrorHandler
getErrorHandler()
boolean
getFeature(String name)
int
getIndex(String qName)
int
getIndex(String uri, String localName)
int
getLength()
int
getLineNumber()
Return the line number where the current document event ends.
String
getLocalName(int index)
Parser
getParser()
Returns the underlying SAX1 parser.
Object
getProperty(String name)
Returns the value of the specified SAX2 parser property.
String
getPublicId()
Return the public identifier for the current document event.
String
getQName(int index)
String
getSystemId()
Return the system identifier for the current document event.
String
getType(int index)
String
getType(String qName)
String
getType(String uri, String localName)
String
getURI(int index)
String
getValue(int index)
String
getValue(String qName)
String
getValue(String uri, String localName)
XMLReader
getXMLReader()
Returns the underlying SAX2 parser.
String
getXMLVersion()
boolean
isDeclared(int index)
Returns false unless the attribute was declared in the DTD.
boolean
isDeclared(String qName)
Returns false unless the attribute was declared in the DTD.
boolean
isDeclared(String uri, String localName)
Returns false unless the attribute was declared in the DTD.
boolean
isNamespaceAware()
Indicates whether this parser is XML Namespace aware.
boolean
isSpecified(int index)
Returns true unless the attribute value was provided by DTD defaulting.
boolean
isSpecified(String qName)
Returns true unless the attribute value was provided by DTD defaulting.
boolean
isSpecified(String uri, String localName)
Returns true unless the attribute value was provided by DTD defaulting.
boolean
isValidating()
Indicates whether this parser will validate its input.
boolean
isXIncludeAware()
Indicates whether this parser is XInclude-aware.
static void
main(String[] args)
void
parse(String systemId)
void
parse(InputSource input)
void
report(String message, String errorType, Object relatedInformation, Location location)
void
reset()
Resets this parser to its original configuration.
XMLEventReader
resolveAsXMLEventReader(String uri)
XMLStreamReader
resolveAsXMLStreamReader(String uri)
Object
resolveEntity(String publicId, String systemId, String baseURI, String namespace)
Returns an input source from which the specified external entity can be read.
void
setContentHandler(ContentHandler handler)
void
setDTDHandler(DTDHandler handler)
void
setEntityResolver(EntityResolver resolver)
void
setErrorHandler(ErrorHandler handler)
void
setFeature(String name, boolean value)
void
setProperty(String name, Object value)
Sets the specified SAX2 parser property.

Methods inherited from class javax.xml.parsers.SAXParser

getParser, getProperty, getSchema, getXMLReader, isNamespaceAware, isValidating, isXIncludeAware, parse, parse, parse, parse, parse, parse, parse, parse, parse, parse, reset, setProperty

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

SAXParser

public SAXParser()
The basic constructor. Object is special, because it has no superclass, so there is no call to super().

Method Details

getColumnNumber

public int getColumnNumber()
Return the column number where the current document event ends. This is one-based number of Java char values since the last line end.

Warning: The return value from the method is intended only as an approximation for the sake of diagnostics; it is not intended to provide sufficient information to edit the character content of the original XML document. For example, when lines contain combining character sequences, wide characters, surrogate pairs, or bi-directional text, the value may not correspond to the column in a text editor's display.

The return value is an approximation of the column number in the document entity or external parsed entity where the markup triggering the event appears.

If possible, the SAX driver should provide the line position of the first character after the text associated with the document event. The first column in each line is column 1.

Specified by:
getColumnNumber in interface Locator
Returns:
The column number, or -1 if none is available.

getContentHandler

public ContentHandler getContentHandler()
Specified by:
getContentHandler in interface XMLReader

getDTDHandler

public DTDHandler getDTDHandler()
Specified by:
getDTDHandler in interface XMLReader

getEncoding

public String getEncoding()
Specified by:
getEncoding in interface Locator2

getEntityResolver

public EntityResolver getEntityResolver()
Specified by:
getEntityResolver in interface XMLReader

getErrorHandler

public ErrorHandler getErrorHandler()
Specified by:
getErrorHandler in interface XMLReader

getFeature

public boolean getFeature(String name)
            throws SAXNotRecognizedException,
                   SAXNotSupportedException
Specified by:
getFeature in interface XMLReader

getIndex

public int getIndex(String qName)
Specified by:
getIndex in interface Attributes

getIndex

public int getIndex(String uri,
                    String localName)
Specified by:
getIndex in interface Attributes

getLength

public int getLength()
Specified by:
getLength in interface Attributes

getLineNumber

public int getLineNumber()
Return the line number where the current document event ends. Lines are delimited by line ends, which are defined in the XML specification.

Warning: The return value from the method is intended only as an approximation for the sake of diagnostics; it is not intended to provide sufficient information to edit the character content of the original XML document. In some cases, these "line" numbers match what would be displayed as columns, and in others they may not match the source text due to internal entity expansion.

The return value is an approximation of the line number in the document entity or external parsed entity where the markup triggering the event appears.

If possible, the SAX driver should provide the line position of the first character after the text associated with the document event. The first line is line 1.

Specified by:
getLineNumber in interface Locator
Returns:
The line number, or -1 if none is available.

getLocalName

public String getLocalName(int index)
Specified by:
getLocalName in interface Attributes

getParser

public Parser getParser()
            throws SAXException
Returns the underlying SAX1 parser.
Overrides:
getParser in interface SAXParser

getProperty

public Object getProperty(String name)
            throws SAXNotRecognizedException,
                   SAXNotSupportedException
Returns the value of the specified SAX2 parser property.
Specified by:
getProperty in interface XMLReader
Overrides:
getProperty in interface SAXParser
Parameters:
name - the name of the property

getPublicId

public String getPublicId()
Return the public identifier for the current document event.

The return value is the public identifier of the document entity or of the external parsed entity in which the markup triggering the event appears.

Specified by:
getPublicId in interface Locator
Returns:
A string containing the public identifier, or null if none is available.

getQName

public String getQName(int index)
Specified by:
getQName in interface Attributes

getSystemId

public String getSystemId()
Return the system identifier for the current document event.

The return value is the system identifier of the document entity or of the external parsed entity in which the markup triggering the event appears.

If the system identifier is a URL, the parser must resolve it fully before passing it to the application. For example, a file name must always be provided as a file:... URL, and other kinds of relative URI are also resolved against their bases.

Specified by:
getSystemId in interface Locator
Returns:
A string containing the system identifier, or null if none is available.

getType

public String getType(int index)
Specified by:
getType in interface Attributes

getType

public String getType(String qName)
Specified by:
getType in interface Attributes

getType

public String getType(String uri,
                      String localName)
Specified by:
getType in interface Attributes

getURI

public String getURI(int index)
Specified by:
getURI in interface Attributes

getValue

public String getValue(int index)
Specified by:
getValue in interface Attributes

getValue

public String getValue(String qName)
Specified by:
getValue in interface Attributes

getValue

public String getValue(String uri,
                       String localName)
Specified by:
getValue in interface Attributes

getXMLReader

public XMLReader getXMLReader()
            throws SAXException
Returns the underlying SAX2 parser.
Overrides:
getXMLReader in interface SAXParser
Since:
1.1

getXMLVersion

public String getXMLVersion()
Specified by:
getXMLVersion in interface Locator2

isDeclared

public boolean isDeclared(int index)
Returns false unless the attribute was declared in the DTD. This helps distinguish two kinds of attributes that SAX reports as CDATA: ones that were declared (and hence are usually valid), and those that were not (and which are never valid).
Specified by:
isDeclared in interface Attributes2
Parameters:
index - The attribute index (zero-based).
Returns:
true if the attribute was declared in the DTD, false otherwise.
Throws:
ArrayIndexOutOfBoundsException - When the supplied index does not identify an attribute.

isDeclared

public boolean isDeclared(String qName)
Returns false unless the attribute was declared in the DTD. This helps distinguish two kinds of attributes that SAX reports as CDATA: ones that were declared (and hence are usually valid), and those that were not (and which are never valid).
Specified by:
isDeclared in interface Attributes2
Parameters:
qName - The XML qualified (prefixed) name.
Returns:
true if the attribute was declared in the DTD, false otherwise.
Throws:
IllegalArgumentException - When the supplied name does not identify an attribute.

isDeclared

public boolean isDeclared(String uri,
                          String localName)
Returns false unless the attribute was declared in the DTD. This helps distinguish two kinds of attributes that SAX reports as CDATA: ones that were declared (and hence are usually valid), and those that were not (and which are never valid).

Remember that since DTDs do not "understand" namespaces, the namespace URI associated with an attribute may not have come from the DTD. The declaration will have applied to the attribute's qName.

Specified by:
isDeclared in interface Attributes2
Parameters:
uri - The Namespace URI, or the empty string if the name has no Namespace URI.
localName - The attribute's local name.
Returns:
true if the attribute was declared in the DTD, false otherwise.
Throws:
IllegalArgumentException - When the supplied names do not identify an attribute.

isNamespaceAware

public boolean isNamespaceAware()
Indicates whether this parser is XML Namespace aware.
Overrides:
isNamespaceAware in interface SAXParser

isSpecified

public boolean isSpecified(int index)
Returns true unless the attribute value was provided by DTD defaulting.
Specified by:
isSpecified in interface Attributes2
Parameters:
index - The attribute index (zero-based).
Returns:
true if the value was found in the XML text, false if the value was provided by DTD defaulting.
Throws:
ArrayIndexOutOfBoundsException - When the supplied index does not identify an attribute.

isSpecified

public boolean isSpecified(String qName)
Returns true unless the attribute value was provided by DTD defaulting.
Specified by:
isSpecified in interface Attributes2
Parameters:
qName - The XML qualified (prefixed) name.
Returns:
true if the value was found in the XML text, false if the value was provided by DTD defaulting.
Throws:
IllegalArgumentException - When the supplied name does not identify an attribute.

isSpecified

public boolean isSpecified(String uri,
                           String localName)
Returns true unless the attribute value was provided by DTD defaulting.

Remember that since DTDs do not "understand" namespaces, the namespace URI associated with an attribute may not have come from the DTD. The declaration will have applied to the attribute's qName.

Specified by:
isSpecified in interface Attributes2
Parameters:
uri - The Namespace URI, or the empty string if the name has no Namespace URI.
localName - The attribute's local name.
Returns:
true if the value was found in the XML text, false if the value was provided by DTD defaulting.
Throws:
IllegalArgumentException - When the supplied names do not identify an attribute.

isValidating

public boolean isValidating()
Indicates whether this parser will validate its input.
Overrides:
isValidating in interface SAXParser

isXIncludeAware

public boolean isXIncludeAware()
Indicates whether this parser is XInclude-aware.
Overrides:
isXIncludeAware in interface SAXParser
Since:
1.3

main

public static void main(String[] args)
            throws Exception

parse

public void parse(String systemId)
            throws IOException,
                   SAXException
Specified by:
parse in interface XMLReader

parse

public void parse(InputSource input)
            throws IOException,
                   SAXException
Specified by:
parse in interface XMLReader

report

public void report(String message,
                   String errorType,
                   Object relatedInformation,
                   Location location)
            throws XMLStreamException
Specified by:
report in interface XMLReporter

reset

public void reset()
Resets this parser to its original configuration.
Overrides:
reset in interface SAXParser
Since:
1.3

resolveAsXMLEventReader

public XMLEventReader resolveAsXMLEventReader(String uri)
            throws XMLStreamException

resolveAsXMLStreamReader

public XMLStreamReader resolveAsXMLStreamReader(String uri)
            throws XMLStreamException

resolveEntity

public Object resolveEntity(String publicId,
                            String systemId,
                            String baseURI,
                            String namespace)
            throws XMLStreamException
Returns an input source from which the specified external entity can be read. The following return types are possible:
  1. java.io.InputStream
  2. javax.xml.stream.XMLStreamReader
  3. java.xml.stream.XMLEventReader
If null is returned, the processor will attempt to resolve the entity itself.
Specified by:
resolveEntity in interface XMLResolver
Parameters:
baseURI - the absolute base URI of the referring entity
namespace - the namespace of the external entity

setContentHandler

public void setContentHandler(ContentHandler handler)
Specified by:
setContentHandler in interface XMLReader

setDTDHandler

public void setDTDHandler(DTDHandler handler)
Specified by:
setDTDHandler in interface XMLReader

setEntityResolver

public void setEntityResolver(EntityResolver resolver)
Specified by:
setEntityResolver in interface XMLReader

setErrorHandler

public void setErrorHandler(ErrorHandler handler)
Specified by:
setErrorHandler in interface XMLReader

setFeature

public void setFeature(String name,
                       boolean value)
            throws SAXNotRecognizedException,
                   SAXNotSupportedException
Specified by:
setFeature in interface XMLReader

setProperty

public void setProperty(String name,
                        Object value)
            throws SAXNotRecognizedException,
                   SAXNotSupportedException
Sets the specified SAX2 parser property.
Specified by:
setProperty in interface XMLReader
Overrides:
setProperty in interface SAXParser
Parameters:
name - the name of the property
value - the value of the property

SAXParser.java -- Copyright (C) 2005, 2006, 2007 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.