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

Modifier and Type	Field and Description
private boolean	doTrace
private static org.apache.commons.logging.Log	log
private int	lookAheadToken
private boolean	namespaceURIInterning
private static int	nsCount Deprecated.

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

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

Constructor Summary

Constructors

Constructor and Description
StAXOMBuilder() Deprecated.
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

Modifier and Type	Method and Description
protected OMElement	constructNode(OMContainer parent, java.lang.String elementName) Instantiate the appropriate OMElement implementation for the current element.
protected OMNode	createComment() Method createOMText.
protected OMDocument	createDocument()
protected OMNode	createDTD() Method createDTD.
protected OMNode	createEntityReference()
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() Deprecated. A builder doesn't need to generate prefixes.
protected OMNode	createWithCustomBuilder(CustomBuilder customBuilder, OMFactory factory)
private void	endElement()
OMElement	getDocumentElement() Get the document element, i.e.
OMElement	getDocumentElement(boolean discardDocument) Get the document element, optionally discarding the document.
private java.lang.String	getDTDText() The getText() method for a DOCTYPE returns the subset of the DOCTYPE (not the direct infoset).
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.
(package private) int	parserNext() Pushes the virtual parser ahead one token.
private void	populateOMElement(OMElement node) Populate element with data from parser START_ELEMENT event.
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, createDocumentIfNecessary, createOMText, debugDiscarded, discard, discard, getAttributeCount, getAttributeName, getAttributeNamespace, getAttributePrefix, getBuilderType, getCharacterEncoding, getCharsetEncoding, getCustomBuilder, getDocument, getName, getNamespace, getNamespaceCount, getNamespacePrefix, getNamespaceUri, getParser, getPrefix, getReaderProperty, getRegisteredContentHandler, getText, init, isCache, isClosed, isCompleted, processAttributes, registerCustomBuilder, registerCustomBuilderForPayload, registerExternalContentHandler, releaseParserOnClose, setCache, setOMBuilderFactory

Methods inherited from class java.lang.Object

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

Field Detail

log

private static final org.apache.commons.logging.Log log

doTrace

private boolean doTrace

nsCount

private static int nsCount

Deprecated.

namespaceURIInterning

private boolean namespaceURIInterning

lookAheadToken

private int lookAheadToken

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

Deprecated.

Method Detail

createDocument

protected OMDocument createDocument()

Specified by:

createDocument in class StAXBuilder

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.

populateOMElement

private void populateOMElement(OMElement node)

Populate element with data from parser START_ELEMENT event. This is used when the source of data for an element needs to be parsed on demand. The supplied element must already be set to the proper name and namespace.

Parameters:

node - element to be populated

createOMElement

protected final OMNode createOMElement()
                                throws OMException

Method createOMElement.

Specified by:

createOMElement in class StAXBuilder

Returns:

Returns OMNode.

Throws:

OMException

constructNode

protected OMElement constructNode(OMContainer parent,
                                  java.lang.String elementName)

Instantiate the appropriate OMElement implementation for the current element. This method may be overridden by subclasses to support model specific OMElement types. The implementation of this method is expected to initialize the OMElement with the specified local name and to add it to the specified parent. However, the implementation should not set the namespace of the element or process the attributes of the element. This is taken care of by the caller of this method.

Parameters:

parent - the parent for the element

elementName - the local name for the element

Returns:

the newly created OMElement; must not be null

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

getDTDText

private java.lang.String getDTDText()
                             throws OMException

The getText() method for a DOCTYPE returns the subset of the DOCTYPE (not the direct infoset). This may force the parser to get information from the network.

Returns:

doctype subset

Throws:

OMException

createPI

protected OMNode createPI()
                   throws OMException

Method createPI.

Returns:

Returns OMNode.

Throws:

OMException

createEntityReference

protected OMNode createEntityReference()

endElement

private 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()

Deprecated. A builder doesn't need to generate prefixes.

setNamespaceURIInterning

public void setNamespaceURIInterning(boolean b)

Set namespace uri interning

Parameters:

b -

isNamespaceURIInterning

public boolean isNamespaceURIInterning()

Returns:

if namespace uri interning

parserNext

int parserNext()
        throws javax.xml.stream.XMLStreamException

Pushes the virtual parser ahead one token. If a look ahead token was calculated it is returned.

Specified by:

parserNext in class StAXBuilder

Returns:

next token

Throws:

javax.xml.stream.XMLStreamException

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