net.sf.xolite.impl
Class BaseXMLEventParser

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

All Implemented Interfaces:

NamespaceContext, XMLEventParser

Direct Known Subclasses:

DomXMLEventParser, SaxXMLEventParser

public abstract class BaseXMLEventParser
extends Object
implements XMLEventParser

A base XMLEventParser implementation common to many parsers.

Author:

Olivier Berlanger

Constructor Summary

BaseXMLEventParser()

Method Summary

protected abstract void	addLocationInfo(XMLParseException xpe)
void	delegateParsingTo(XMLSerializable handlerOfSubElements) Delegates the parsing of a XML fragment to an other SaxHandler.
protected void	endElementImpl(String uri, String localName)
NamespaceContext	getCurrentDefinedNamespaces() Get NamespacePrefixResolver mapping the prefix to the namespace URI.
NamespacedName	getCurrentElementName() Get the namespace URI and local name of the current element.
Object	getCustomObject(Object key) Get back any custom object that was put in with the putCustomObject(key, value) method.
XMLObjectFactory	getFactory() Get a factory able to instantiate objects corresponding to XML elements.
XMLSerializable	getLastParsedObject() Get the last object that called endParsing(..) method on the parser.
String	getNamespaceURI(String prefix) Get namespace URI corresponding to the given prefix.
String	getPrefix(String namespaceURI) Get the first prefix mapped to the given namespace.
Iterator<String>	getPrefixes(String namespaceURI) Get all the prefixes mapped to the given namespace.
NamespacedName	getQualifiedName(String qName) Resolve a qualified name to it's namespace URI + local name.
boolean	isFirstEvent() 'true' iff the startElement call is the first one called to the XMLSerializable currently receiving it.
boolean	isLastEvent() 'true' iff the endElement call is the last one called to the XMLSerializable currently receiving it.
XMLSerializable	parseElement(String uri, String localName) Create the XMLSerializable object corresponding to the given XML element, delegates the parsing to it and return the created object.
protected void	pushPrefixMappingInNextLevel(String prefix, String namespaceURI)
void	putCustomObject(Object key, Object value) Put a custom object in an internal Map.
void	setFactory(XMLObjectFactory newFactory) Set the factory to be used by this parser.
protected void	setup(XMLSerializable rootHandler)
protected void	startElementImpl(String uri, String localName)
protected void	tearDown()
void	throwParseException(String message, Throwable cause) Throw an exception with given message and cause.
void	throwUnexpectedElementException(String expectedTags) Throw an exception telling that the current element (the one that was just passed to a startElement(..) or endElement(..) method) is unexpected.
void	throwUnexpectedNamespaceException(String expected) Throw an exception telling that the namespace of the current element (the one that was just passed to a startElement(..) or endElement(..) method) is unexpected.
protected void	transformAndThrowException(Exception source)

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.xolite.XMLEventParser

getAttributeNameIterator, getAttributeNamespaceIterator, getAttributeValue, getAttributeValueNS, getElementText

Constructor Detail

BaseXMLEventParser

public BaseXMLEventParser()

Method Detail

setFactory

public void setFactory(XMLObjectFactory newFactory)

Set the factory to be used by this parser.

Parameters:

newFactory - a factory able to instantiate objects corresponding to XML elements.

getNamespaceURI

public String getNamespaceURI(String prefix)

Get namespace URI corresponding to the given prefix.
Note: the mapped namespace set depends on the currently parsed node.

Specified by:

getNamespaceURI in interface NamespaceContext

See Also:

NamespaceContext.getPrefix(java.lang.String)

getPrefix

public String getPrefix(String namespaceURI)

Get the first prefix mapped to the given namespace.

Specified by:

getPrefix in interface NamespaceContext

See Also:

NamespaceContext.getPrefix(java.lang.String)

getPrefixes

public Iterator<String> getPrefixes(String namespaceURI)

Get all the prefixes mapped to the given namespace.

Specified by:

getPrefixes in interface NamespaceContext

See Also:

NamespaceContext.getPrefixes(java.lang.String)

getCurrentElementName

public NamespacedName getCurrentElementName()

Description copied from interface: XMLEventParser

Get the namespace URI and local name of the current element.

Specified by:

getCurrentElementName in interface XMLEventParser

Returns:

the namespace URI and local name of the current element.

getCurrentDefinedNamespaces

public NamespaceContext getCurrentDefinedNamespaces()

Description copied from interface: XMLEventParser

Get NamespacePrefixResolver mapping the prefix to the namespace URI. A copy of the current mapping object of this parser at the moment of the call is returned.

Specified by:

getCurrentDefinedNamespaces in interface XMLEventParser

delegateParsingTo

public void delegateParsingTo(XMLSerializable handlerOfSubElements)
                       throws XMLParseException

Description copied from interface: XMLEventParser

Delegates the parsing of a XML fragment to an other SaxHandler. When this handler have finished to parse the data belonging to it, it will call the endParsing(..) method and the current parser will receive again the XML parsing events.
This method should be called from inside a startElement(..) method, the same startElement method (with same parameters) is called against the delegated (handlerOfSubElements) object by the parser.

Specified by:

delegateParsingTo in interface XMLEventParser

Parameters:

handlerOfSubElements - the XMLSerializable that will receive the next 'simplified SAX' events from the XMLEventParser.

Throws:

XMLParseException

parseElement

public XMLSerializable parseElement(String uri,
                                    String localName)
                             throws XMLParseException

Description copied from interface: XMLEventParser

Create the XMLSerializable object corresponding to the given XML element, delegates the parsing to it and return the created object.
Note: when returned the created object has not yet finished it's parsing. Only the first startElement(..) method has been called on it.
This method will work only if there is a factory defined and this factory knows the given element. It is equivalent to:

 XMLSerializable child = parser.getFactory().createObject(uri, localName, parser);
 parser.delegateParsingTo(child, uri, localName);
 return child;
 

Specified by:

parseElement in interface XMLEventParser

Throws:

XMLParseException

isFirstEvent

public boolean isFirstEvent()

Description copied from interface: XMLEventParser

'true' iff the startElement call is the first one called to the XMLSerializable currently receiving it.
This method can be useful for recursive XML when an object can contain itself. In this case, when startElement is called the parsed object can use this method to know if the notified event is the start of itself or the start of a direct sub-object.
Calling this method makes sense only from inside a startElement method implementation.

Specified by:

isFirstEvent in interface XMLEventParser

Returns:

true iff it's the first time startElement is called against the XMLSerializable.

isLastEvent

public boolean isLastEvent()

Description copied from interface: XMLEventParser

'true' iff the endElement call is the last one called to the XMLSerializable currently receiving it.
This method can be useful for recursive XML when an object can contain itself. In this case, when endElement is called, the parsed object can use this method to know if the notified event is the end of itself or the end of a direct sub-object.
Calling this method makes sense only from inside a endElement method implementation.

Specified by:

isLastEvent in interface XMLEventParser

Returns:

true iff it's the first time startElement is called against the XMLSerializable.

getLastParsedObject

public XMLSerializable getLastParsedObject()
                                    throws XMLParseException

Description copied from interface: XMLEventParser

Get the last object that called endParsing(..) method on the parser.

Specified by:

getLastParsedObject in interface XMLEventParser

Returns:

the last object that called endParsing(..) method on the parser.

Throws:

XMLParseException

getQualifiedName

public NamespacedName getQualifiedName(String qName)
                                throws XMLParseException

Description copied from interface: XMLEventParser

Resolve a qualified name to it's namespace URI + local name. As the SAX parser does it automatically for elements tags or attributes, this method is useful only for elements/attributes values containing qualified names.

To map the prefix, this method will use the prefix mappings of the parsed document. If no prefix mapping is defined for a given prefix, an exception is thrown. When no prefix is defined, this method will try to find the default prefix mapping, but if no default mapping is defined, no exception is thrown (in this case, the URI of the returned NamespacedName is null).

Specified by:

getQualifiedName in interface XMLEventParser

Parameters:

qName - a qualified name (like: "xs:element").

Returns:

NamespacedName containing the namespace URI and the local name of the given qualified name. (the prefix is not kept).

Throws:

XMLParseException - If the qualified name contains a prefix not mapped to a namespace.

getFactory

public XMLObjectFactory getFactory()
                            throws XMLParseException

Description copied from interface: XMLEventParser

Get a factory able to instantiate objects corresponding to XML elements. This method never returns null, if the factory is not defined an exception is thrown.

Specified by:

getFactory in interface XMLEventParser

Returns:

a factory able to instantiate objects corresponding to XML elements.

Throws:

XMLParseException - if the factory is not defined.

getCustomObject

public Object getCustomObject(Object key)

Description copied from interface: XMLEventParser

Get back any custom object that was put in with the putCustomObject(key, value) method.

Specified by:

getCustomObject in interface XMLEventParser

Parameters:

key - key of the custom object.

Returns:

the custom object.

putCustomObject

public void putCustomObject(Object key,
                            Object value)

Description copied from interface: XMLEventParser

Put a custom object in an internal Map.
It can be retrieved later with getCustomObject(key) method.

Specified by:

putCustomObject in interface XMLEventParser

Parameters:

key - key of the custom object.

value - custom object.

throwUnexpectedNamespaceException

public void throwUnexpectedNamespaceException(String expected)
                                       throws XMLParseException

Description copied from interface: XMLEventParser

Throw an exception telling that the namespace of the current element (the one that was just passed to a startElement(..) or endElement(..) method) is unexpected. If the expected namespace URI is passed as parameter, it is added in the message.
The current location of the parser (current element tag, current line, current column, file name) is added to the message if available.

Specified by:

throwUnexpectedNamespaceException in interface XMLEventParser

Parameters:

expected - the expected namespace URI. If null, no expected namespace URI is mentioned in the exception message.

Throws:

XMLParseException

throwUnexpectedElementException

public void throwUnexpectedElementException(String expectedTags)
                                     throws XMLParseException

Description copied from interface: XMLEventParser

Throw an exception telling that the current element (the one that was just passed to a startElement(..) or endElement(..) method) is unexpected. If the expected tags are passed as parameter, they are added in the message.
The current location of the parser (current element tag, current line, current column, file name) is added to the message if available.

Specified by:

throwUnexpectedElementException in interface XMLEventParser

Parameters:

expectedTags - the expected element tag(s). If you expect several different tags, you can enumerate them in this parameter (for example by separating them with commas). It is simply added in the exception message. If null, no expected tags are mentioned in the exception message.

Throws:

XMLParseException

throwParseException

public void throwParseException(String message,
                                Throwable cause)
                         throws XMLParseException

Description copied from interface: XMLEventParser

Throw an exception with given message and cause.
The current location of the parser (current element tag, current line, current column, file name) is added to the message if available.

Specified by:

throwParseException in interface XMLEventParser

Parameters:

message - the exception message (rem: parser location is added).

cause - the exception cause

Throws:

XMLParseException

transformAndThrowException

protected void transformAndThrowException(Exception source)
                                   throws XMLParseException

Throws:

XMLParseException

addLocationInfo

protected abstract void addLocationInfo(XMLParseException xpe)

setup

protected void setup(XMLSerializable rootHandler)

tearDown

protected void tearDown()

pushPrefixMappingInNextLevel

protected void pushPrefixMappingInNextLevel(String prefix,
                                            String namespaceURI)

startElementImpl

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

Throws:

Exception

endElementImpl

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

Throws:

Exception