net.sf.xolite
Interface XMLEventParser

All Superinterfaces:

NamespaceContext

All Known Implementing Classes:

BaseXMLEventParser, DomXMLEventParser, SaxXMLEventParser

public interface XMLEventParser
extends NamespaceContext

Interface for parsing XML with simplified event handling. This class is like a SAX parser keeping itself its state (locator, started elements, prefix mapping, characters, ...) rather than pushing it to a client handler. The result is a simpler document handler with only two methods remaining (@link XMLSerializable).

Although this interface is based on SAX mechanism, it's quite independent from SAX implementation. It doesn't expose any SAX class or interface.

Method Summary

void	delegateParsingTo(XMLSerializable handlerOfSubElements) Delegates the parsing of a XML fragment to an other SaxHandler.
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.
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.
String	getElementText() Get the content of the text buffer.
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.
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.
void	putCustomObject(Object key, Object value) Put a custom object in an internal Map.
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 expectedURI) 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.

Methods inherited from interface javax.xml.namespace.NamespaceContext

getNamespaceURI, getPrefix, getPrefixes

Method Detail

getCurrentDefinedNamespaces

NamespaceContext getCurrentDefinedNamespaces()

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.

delegateParsingTo

void delegateParsingTo(XMLSerializable handlerOfSubElements)
                       throws XMLParseException

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.

Parameters:

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

Throws:

XMLParseException

parseElement

XMLSerializable parseElement(String uri,
                             String localName)
                             throws XMLParseException

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;
 

Throws:

XMLParseException

getLastParsedObject

XMLSerializable getLastParsedObject()
                                    throws XMLParseException

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

Returns:

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

Throws:

XMLParseException

getQualifiedName

NamespacedName getQualifiedName(String qName)
                                throws XMLParseException

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).

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.

getElementText

String getElementText()

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.

getFactory

XMLObjectFactory getFactory()
                            throws XMLParseException

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.

Returns:

a factory able to instantiate objects corresponding to XML elements.

Throws:

XMLParseException - if the factory is not defined.

putCustomObject

void putCustomObject(Object key,
                     Object value)

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

Parameters:

key - key of the custom object.

value - custom object.

getCustomObject

Object getCustomObject(Object key)

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

Parameters:

key - key of the custom object.

Returns:

the custom object.

getCurrentElementName

NamespacedName getCurrentElementName()

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

Returns:

the namespace URI and local name of the current element.

isFirstEvent

boolean isFirstEvent()

'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.

Returns:

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

isLastEvent

boolean isLastEvent()

'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.

Returns:

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

throwUnexpectedNamespaceException

void throwUnexpectedNamespaceException(String expectedURI)
                                       throws XMLParseException

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.

Parameters:

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

Throws:

XMLParseException

throwUnexpectedElementException

void throwUnexpectedElementException(String expectedTags)
                                     throws XMLParseException

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.

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

void throwParseException(String message,
                         Throwable cause)
                         throws XMLParseException

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.

Parameters:

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

cause - the exception cause

Throws:

XMLParseException

getAttributeValue

String getAttributeValue(String attrName)
                         throws XMLParseException

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

String getAttributeValueNS(String attrNamespaceURI,
                           String attrName)
                           throws XMLParseException

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

Iterator<String> getAttributeNamespaceIterator()
                                               throws XMLParseException

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

Iterator<String> getAttributeNameIterator(String attrNamespaceURI)
                                          throws XMLParseException

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