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

java.lang.Object
  extended by org.apache.axiom.om.impl.builder.StAXBuilder
      extended by 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. WSCOMMONS-372 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(InputStream inStream)
           
StAXOMBuilder(OMFactory ombuilderFactory, XMLStreamReader parser)
          Constructor StAXOMBuilder.
StAXOMBuilder(OMFactory factory, XMLStreamReader parser, OMElement element)
          Constructor linked to existing element.
StAXOMBuilder(OMFactory factory, XMLStreamReader parser, OMElement element, String characterEncoding)
          Constructor linked to existing element.
StAXOMBuilder(String filePath)
           
StAXOMBuilder(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  String createPrefix()
           
protected  OMNode createWithCustomBuilder(CustomBuilder customBuilder, OMFactory factory)
           
protected  void endElement()
           
 OMElement getDocumentElement()
          Get the document element, i.e. the root element of the document.
 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,
                     XMLStreamReader parser)
Constructor StAXOMBuilder.

Parameters:
ombuilderFactory -
parser -

StAXOMBuilder

public StAXOMBuilder(OMFactory factory,
                     XMLStreamReader parser,
                     OMElement element,
                     String characterEncoding)
Constructor linked to existing element.

Parameters:
factory -
parser -
element -
characterEncoding - of existing element

StAXOMBuilder

public StAXOMBuilder(OMFactory factory,
                     XMLStreamReader parser,
                     OMElement element)
Constructor linked to existing element.

Parameters:
factory -
parser -
element -

StAXOMBuilder

public StAXOMBuilder(String filePath)
              throws XMLStreamException,
                     FileNotFoundException
Parameters:
filePath - - Path to the XML file
Throws:
XMLStreamException
FileNotFoundException

StAXOMBuilder

public StAXOMBuilder(XMLStreamReader parser)
Constructor StAXOMBuilder.

Parameters:
parser -

StAXOMBuilder

public StAXOMBuilder(InputStream inStream)
              throws XMLStreamException
Parameters:
inStream - - instream which contains the XML
Throws:
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().

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



Copyright © 2004-2013 The Apache Software Foundation. All Rights Reserved.