org.apache.axiom.om.impl.builder
Class StAXOMBuilder

java.lang.Object
  org.apache.axiom.om.impl.builder.StAXBuilder
      org.apache.axiom.om.impl.builder.StAXOMBuilder

All Implemented Interfaces:

OMXMLParserWrapper

Direct Known Subclasses:

StAXSOAPModelBuilder, XOPAwareStAXOMBuilder

public class StAXOMBuilder
extends StAXBuilder

StAX based builder that produces a pure XML infoset compliant object model.

This class supports the XMLStreamReader extension defined by DataHandlerReader as well as the legacy extension mechanism defined in the documentation of XMLStreamReaderUtils.

Error handling

Usually, code that uses StAX directly just stops processing of an XML document once the first parsing error has been reported. However, since Axiom uses deferred parsing, and client code accesses the XML infoset using an object model, things are more complicated. Indeed, if the XML document is not well formed, the corresponding error might be reported as a runtime exception by any call to a method of an OM node.

Typically the client code will have some error handling that will intercept runtime exceptions and take appropriate action. Very often this error handling code might want to access the object model again, for example to log the request that caused the failure. This causes no problem except if the runtime exception was caused by a parsing error, in which case Axiom would again try to pull events from the parser.

This would lead to a situation where Axiom accesses a parser that has reported a parsing error before. While one would expect that after a first error reported by the parser, all subsequent invocations of the parser will fail, this is not the case for all parsers (at least not in all situations). Instead, the parser might be left in an inconsistent state after the error. E.g. AXIOM-34 describes a case where Woodstox encounters an error in XMLStreamReader.getText() but continues to return (incorrect) events afterwards. The explanation for this behaviour might be that the situation described here is quite uncommon when StAX is used directly (i.e. not through Axiom).

To avoid this, the builder remembers exceptions thrown by the parser and rethrows them during a call to next().

Field Summary

Fields inherited from class org.apache.axiom.om.impl.builder.StAXBuilder

_isClosed, _releaseParserOnClose, cache, charEncoding, customBuilderForPayload, customBuilders, dataHandlerReader, document, done, elementLevel, lastNode, maxDepthForCustomBuilders, omfactory, parser, parserAccessed, parserException

Constructor Summary

StAXOMBuilder()
Init() *must* be called after creating the builder using this constructor.

StAXOMBuilder(java.io.InputStream inStream)

StAXOMBuilder(OMFactory ombuilderFactory, javax.xml.stream.XMLStreamReader parser)
Constructor StAXOMBuilder.

StAXOMBuilder(OMFactory factory, javax.xml.stream.XMLStreamReader parser, OMElement element)
Constructor linked to existing element.

StAXOMBuilder(OMFactory factory, javax.xml.stream.XMLStreamReader parser, OMElement element, java.lang.String characterEncoding)
Constructor linked to existing element.

StAXOMBuilder(java.lang.String filePath)

StAXOMBuilder(javax.xml.stream.XMLStreamReader parser)
Constructor StAXOMBuilder.

Method Summary

protected OMNode	createComment() Method createOMText.
protected OMNode	createDTD() Method createDTD.
protected OMNode	createNextOMElement() Creates a new OMElement using either a CustomBuilder or the default Builder mechanism.
protected OMNode	createOMElement() Method createOMElement.
protected OMNode	createPI() Method createPI.
protected java.lang.String	createPrefix()
protected OMNode	createWithCustomBuilder(CustomBuilder customBuilder, OMFactory factory)
protected void	endElement()
OMElement	getDocumentElement() Get the document element, i.e.
OMElement	getDocumentElement(boolean discardDocument) Get the document element, optionally discarding the document.
boolean	isLookahead() Check if the node for the current token has already been created or if the parser is ahead of the builder.
boolean	isNamespaceURIInterning()
protected void	logParserState() Dump the current event of the parser.
boolean	lookahead() This method looks ahead to the next start element.
int	next() Method next.
protected void	processNamespaceData(OMElement node) Method processNamespaceData.
void	setDoDebug(boolean doDebug) Deprecated.
void	setNamespaceURIInterning(boolean b) Set namespace uri interning

Methods inherited from class org.apache.axiom.om.impl.builder.StAXBuilder

close, createOMText, discard, getAttributeCount, getAttributeName, getAttributeNamespace, getAttributePrefix, getBuilderType, getCharacterEncoding, getCharsetEncoding, getCustomBuilder, getDocument, getLastNode, getName, getNamespace, getNamespaceCount, getNamespacePrefix, getNamespaceUri, getParser, getPrefix, getReaderProperty, getRegisteredContentHandler, getText, init, isCache, isClosed, isCompleted, processAttributes, registerCustomBuilder, registerCustomBuilderForPayload, registerExternalContentHandler, releaseParserOnClose, reset, setCache, setOMBuilderFactory

Methods inherited from class java.lang.Object

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

Constructor Detail

StAXOMBuilder

public StAXOMBuilder(OMFactory ombuilderFactory,
                     javax.xml.stream.XMLStreamReader parser)

Constructor StAXOMBuilder.

Parameters:

ombuilderFactory -

parser -

StAXOMBuilder

public StAXOMBuilder(OMFactory factory,
                     javax.xml.stream.XMLStreamReader parser,
                     OMElement element,
                     java.lang.String characterEncoding)

Constructor linked to existing element.

Parameters:

factory -

parser -

element -

characterEncoding - of existing element

StAXOMBuilder

public StAXOMBuilder(OMFactory factory,
                     javax.xml.stream.XMLStreamReader parser,
                     OMElement element)

Constructor linked to existing element.

Parameters:

factory -

parser -

element -

StAXOMBuilder

public StAXOMBuilder(java.lang.String filePath)
              throws javax.xml.stream.XMLStreamException,
                     java.io.FileNotFoundException

Parameters:

filePath - - Path to the XML file

Throws:

javax.xml.stream.XMLStreamException

java.io.FileNotFoundException

StAXOMBuilder

public StAXOMBuilder(javax.xml.stream.XMLStreamReader parser)

Constructor StAXOMBuilder.

Parameters:

parser -

StAXOMBuilder

public StAXOMBuilder(java.io.InputStream inStream)
              throws javax.xml.stream.XMLStreamException

Parameters:

inStream - - instream which contains the XML

Throws:

javax.xml.stream.XMLStreamException

StAXOMBuilder

public StAXOMBuilder()

Init() *must* be called after creating the builder using this constructor.

Method Detail

next

public int next()
         throws OMException

Method next.

Specified by:

next in interface OMXMLParserWrapper

Specified by:

next in class StAXBuilder

Returns:

Returns int.

Throws:

OMException

createNextOMElement

protected OMNode createNextOMElement()

Creates a new OMElement using either a CustomBuilder or the default Builder mechanism.

Returns:

TODO

createWithCustomBuilder

protected OMNode createWithCustomBuilder(CustomBuilder customBuilder,
                                         OMFactory factory)

logParserState

protected void logParserState()

Dump the current event of the parser.

createOMElement

protected OMNode createOMElement()
                          throws OMException

Method createOMElement.

Specified by:

createOMElement in class StAXBuilder

Returns:

Returns OMNode.

Throws:

OMException

createComment

protected OMNode createComment()
                        throws OMException

Method createOMText.

Returns:

Returns OMNode.

Throws:

OMException

createDTD

protected OMNode createDTD()
                    throws OMException

Method createDTD.

Returns:

Returns OMNode.

Throws:

OMException

createPI

protected OMNode createPI()
                   throws OMException

Method createPI.

Returns:

Returns OMNode.

Throws:

OMException

endElement

protected void endElement()

getDocumentElement

public OMElement getDocumentElement()

Description copied from interface: OMXMLParserWrapper

Get the document element, i.e. the root element of the document. Using this method is equivalent to using OMDocument.getOMDocumentElement() on the document returned by OMXMLParserWrapper.getDocument().

Note that this method will never return null (except in the very special case where the document has been requested before and the document element has been removed explicitly): if the document being parsed has no document element, then this will result in a parser error, i.e. an OMException will be thrown.

Returns:

the document element

getDocumentElement

public OMElement getDocumentElement(boolean discardDocument)

Description copied from interface: OMXMLParserWrapper

Get the document element, optionally discarding the document. The return value of this method is the same as OMXMLParserWrapper.getDocumentElement(). However, if the discardDocument parameter is set to true, then the document element is removed from the document and the document itself is discarded. In contrast to using OMNode.detach() this will not build the element. The implementation also ensures that the element is not built when it is added to another OM tree. This makes it possible to add the content of a document to an existing OM tree while preserving the deferred parsing feature. It is even possible to create an OM tree where different subtrees are associated with different builder instances.

Parameters:

discardDocument - specifies whether the document should be discarded

Returns:

the document element

processNamespaceData

protected void processNamespaceData(OMElement node)

Method processNamespaceData.

Specified by:

processNamespaceData in class StAXBuilder

Parameters:

node -

setDoDebug

public void setDoDebug(boolean doDebug)

Deprecated.

Parameters:

doDebug -

createPrefix

protected java.lang.String createPrefix()

setNamespaceURIInterning

public void setNamespaceURIInterning(boolean b)

Set namespace uri interning

Parameters:

b -

isNamespaceURIInterning

public boolean isNamespaceURIInterning()

Returns:

if namespace uri interning

lookahead

public boolean lookahead()

This method looks ahead to the next start element.

Returns:

true if successful

isLookahead

public boolean isLookahead()

Check if the node for the current token has already been created or if the parser is ahead of the builder.

Returns:

A return value of true indicates that the parser is one token ahead of the builder, i.e. that the node for the current token has not been created yet. In this case StAXBuilder.getLastNode() returns the node corresponding to the previous token. This state can only be reached by a call to lookahead(), and the current token is always a START_ELEMENT. The information related to that element can be obtained by calls to StAXBuilder.getName(), StAXBuilder.getNamespace(), StAXBuilder.getPrefix(), StAXBuilder.getAttributeCount(), StAXBuilder.getAttributeName(int), StAXBuilder.getAttributeNamespace(int), StAXBuilder.getAttributePrefix(int), StAXBuilder.getNamespaceCount(), StAXBuilder.getNamespacePrefix(int) and StAXBuilder.getNamespaceUri(int).

A return value of false indicates that the node corresponding to the current token hold by the parser has already been created, i.e. StAXBuilder.getLastNode() returns the node corresponding to the current token.