net.sf.xolite.sax
Class SaxXMLEventParser

java.lang.Object
  net.sf.xolite.impl.BaseXMLEventParser
      net.sf.xolite.sax.SaxXMLEventParser

All Implemented Interfaces:

NamespaceContext, XMLEventParser

public class SaxXMLEventParser
extends BaseXMLEventParser

A XMLEventParser implementation based on a SAX parser.

Author:

Olivier Berlanger

Constructor Summary

SaxXMLEventParser()
Build a StreamXMLEventParser using the system-default SAXParser configured to be namespace aware and perform no validation.

SaxXMLEventParser(String schemaLocations)
Build a StreamXMLEventParser using the system-default SAXParser configured to be namespace aware and perform validation using the provided schema locations.

SaxXMLEventParser(XMLReader rdr)
Build a SimpleSaxParser using the given XMLReader.

Method Summary

protected void	addLocationInfo(XMLParseException xpe)
protected void	endElementImpl(String uri, String localName)
Iterator<String>	getAttributeNameIterator(String attrNamespaceURI) Get an iterator on names of all the attributes present in the current element and belonging to the given namespace.
Iterator<String>	getAttributeNamespaceIterator() Get an iterator on namespaces of all the attributes present in the current element.
String	getAttributeValue(String attrName) Get an attribute value.
String	getAttributeValueNS(String attrNamespaceURI, String attrName) Get value of an attribute with namespace.
String	getElementText() Get the content of the text buffer.
Locator	getLocator() Get the current SAX locator (for reporting SAXParseException).
ContentHandler	initForExternalRead(XMLSerializable rootHandler)
XMLSerializable	parse(File f) Parse the given file to java objects.
void	parse(File f, XMLSerializable rootHandler) Parse a file to java objects using the given XMLSerializable as root handler (as object representing the root element).
XMLSerializable	parse(InputSource src) Parse the given input source to java objects.
void	parse(InputSource src, XMLSerializable rootHandler) Parse an input source to java objects using the given XMLSerializable as root handler (as object representing the root element).
XMLSerializable	parse(InputStream is) Parse the given input stream to java objects.
void	parse(InputStream is, XMLSerializable rootHandler) Parse an input stream to java objects using the given XMLSerializable as root handler (as object representing the root element).
XMLSerializable	parse(URL url) Parse the given URL content to java objects.
void	parse(URL url, XMLSerializable rootHandler) Parse an URL content to java objects using the given XMLSerializable as root handler (as object representing the root element).
protected void	pushPrefixMappingInNextLevel(String newPrefix, String newNamespaceURI) Rem: overridden just to increase visibility.
protected void	transformAndThrowException(Exception source)

Methods inherited from class net.sf.xolite.impl.BaseXMLEventParser

delegateParsingTo, getCurrentDefinedNamespaces, getCurrentElementName, getCustomObject, getFactory, getLastParsedObject, getNamespaceURI, getPrefix, getPrefixes, getQualifiedName, isFirstEvent, isLastEvent, parseElement, putCustomObject, setFactory, setup, startElementImpl, tearDown, throwParseException, throwUnexpectedElementException, throwUnexpectedNamespaceException

Methods inherited from class java.lang.Object

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

Constructor Detail

SaxXMLEventParser

public SaxXMLEventParser()

Build a StreamXMLEventParser using the system-default SAXParser configured to be namespace aware and perform no validation.

See Also:

SAXParserFactory, SAXParser

SaxXMLEventParser

public SaxXMLEventParser(String schemaLocations)

Build a StreamXMLEventParser using the system-default SAXParser configured to be namespace aware and perform validation using the provided schema locations. The 'schemaLocations' string must be a suite of pair 'namespace URI' + 'schema location URL' separated by spaces (just as the value of the standard 'xsi:schemaLocation' xml attribute).

Caution: This setup works with Sun JRE default parser (Xerces) but is not guaranteed to work if you (or a library you're using) have changed the default XML parser implementation.
In this case, you have to setup a validating parser yourself (following your parser documentation) and pass it to the SaxXMLEventParser(XMLReader) constructor.

Parameters:

schemaLocations - the schema location expressed as in the standard 'xsi:schemaLocation' xml attributes. You can use the X-O lite SchemaLocation helper to build this string if your schema is in your application jar.

See Also:

SAXParserFactory, SAXParser, SchemaLocation

SaxXMLEventParser

public SaxXMLEventParser(XMLReader rdr)

Build a SimpleSaxParser using the given XMLReader. The XMLReader must be correctly configured, this class will not change it's configuration (namespace aware, validating, ...).

Method Detail

initForExternalRead

public ContentHandler initForExternalRead(XMLSerializable rootHandler)

parse

public XMLSerializable parse(File f)
                      throws XMLParseException

Parse the given file to java objects.
This method will succeed only if a factory knowing the class of the root element is defined.

Parameters:

f - file containing the XML to parse.

Throws:

XMLParseException - if the source cannot be read or contains an invalid XML document.

parse

public void parse(File f,
                  XMLSerializable rootHandler)
           throws XMLParseException

Parse a file to java objects using the given XMLSerializable as root handler (as object representing the root element).

Parameters:

f - file containing the XML to parse.

rootHandler - the root handler.

Throws:

XMLParseException - if the source cannot be read or contains an invalid XML document.

parse

public XMLSerializable parse(InputStream is)
                      throws XMLParseException

Parse the given input stream to java objects.
This method will succeed only if a factory knowing the class of the root element is defined.

Parameters:

is - input stream containing the XML to parse.

Throws:

XMLParseException - if the source cannot be read or contains an invalid XML document.

parse

public void parse(InputStream is,
                  XMLSerializable rootHandler)
           throws XMLParseException

Parse an input stream to java objects using the given XMLSerializable as root handler (as object representing the root element).

Parameters:

is - input stream containing the XML to parse.

rootHandler - the root handler.

Throws:

XMLParseException - if the source cannot be read or contains an invalid XML document.

parse

public XMLSerializable parse(URL url)
                      throws XMLParseException

Parse the given URL content to java objects.
This method will succeed only if a factory knowing the class of the root element is defined.

Parameters:

url - URL pointing to file containing the XML to parse.

Throws:

XMLParseException - if the source cannot be read or contains an invalid XML document.

parse

public void parse(URL url,
                  XMLSerializable rootHandler)
           throws XMLParseException

Parse an URL content to java objects using the given XMLSerializable as root handler (as object representing the root element).

Parameters:

url - URL pointing to file containing the XML to parse.

rootHandler - the root handler.

Throws:

XMLParseException - if the source cannot be read or contains an invalid XML document.

parse

public XMLSerializable parse(InputSource src)
                      throws XMLParseException

Parse the given input source to java objects.
This method will succeed only if a factory knowing the class of the root element is defined.

Parameters:

src - input source for the SAX parsing.

Throws:

XMLParseException - if the source cannot be read or contains an invalid XML document.

parse

public void parse(InputSource src,
                  XMLSerializable rootHandler)
           throws XMLParseException

Parse an input source to java objects using the given XMLSerializable as root handler (as object representing the root element).

Parameters:

src - input source for the SAX parsing.

rootHandler - the root handler.

Throws:

XMLParseException - if the source cannot be read or contains an invalid XML document.

getLocator

public Locator getLocator()

Get the current SAX locator (for reporting SAXParseException). This Locator is not null only when parsing.

getElementText

public String getElementText()

Description copied from interface: XMLEventParser

Get the content of the text buffer. Usually, this method is called when the end of the element (containing the text) is notified by a SAX event.

Use the ElementText helper class to get, parse, validate and format easily the element text.

Calling this method from a startElement notification is useful only when parsing XML with mixed content. In this case you got the text just before the started element.

Returns:

the text data of the current XML element.

addLocationInfo

protected void addLocationInfo(XMLParseException xpe)

Specified by:

addLocationInfo in class BaseXMLEventParser

transformAndThrowException

protected void transformAndThrowException(Exception source)
                                   throws XMLParseException

Overrides:

transformAndThrowException in class BaseXMLEventParser

Throws:

XMLParseException

getAttributeValue

public String getAttributeValue(String attrName)
                         throws XMLParseException

Description copied from interface: XMLEventParser

Get an attribute value. If the requested attribute is not defined (because it is optional), null is returned.

Parameters:

attrName - the name of the attribute.

Returns:

the requested attribute value.

Throws:

XMLParseException

getAttributeValueNS

public String getAttributeValueNS(String attrNamespaceURI,
                                  String attrName)
                           throws XMLParseException

Description copied from interface: XMLEventParser

Get value of an attribute with namespace. If the requested attribute is not defined (because it is optional), the null is returned.

This method allows to specify the namespace of the attribute. In most of the case attributes are not associated to namespaces. It is not necessary because attributes definitions are, in most of the case, local to the definition of the element containing it. So this method should be rarely used (use the corresponding method without namespace parameter). Examples of attributes using namespaces are: 'xml:lang' or 'xmlns:prefix'. To get values of those attributes you must provide the namespace URI.

Parameters:

attrNamespaceURI - the namespace URI of the attribute.

attrName - the name of the attribute.

Returns:

the requested attribute value.

Throws:

XMLParseException

getAttributeNamespaceIterator

public Iterator<String> getAttributeNamespaceIterator()
                                               throws XMLParseException

Description copied from interface: XMLEventParser

Get an iterator on namespaces of all the attributes present in the current element.

Returns:

Iterator on namespaces of all the attributes present in the current element.

Throws:

XMLParseException

getAttributeNameIterator

public Iterator<String> getAttributeNameIterator(String attrNamespaceURI)
                                          throws XMLParseException

Description copied from interface: XMLEventParser

Get an iterator on names of all the attributes present in the current element and belonging to the given namespace.
Use null as namespace for attributes not bound to a namespace (i.e. most of the attributes).

Parameters:

attrNamespaceURI - namespace of the attributes or null for attributes without namespaces.

Returns:

Iterator on names of all the attributes present in the current element and belonging to the given namespace.

Throws:

XMLParseException

endElementImpl

protected void endElementImpl(String uri,
                              String localName)
                       throws Exception

Overrides:

endElementImpl in class BaseXMLEventParser

Throws:

Exception

pushPrefixMappingInNextLevel

protected void pushPrefixMappingInNextLevel(String newPrefix,
                                            String newNamespaceURI)

Rem: overridden just to increase visibility.

Overrides:

pushPrefixMappingInNextLevel in class BaseXMLEventParser