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. 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, maxDepthForCustomBuilders, omfactory, parser, parserAccessed, parserException, target
 
Constructor Summary
StAXOMBuilder()
          Deprecated.  
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  OMElement constructNode(OMContainer parent, 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  String createPrefix()
          Deprecated. A builder doesn't need to generate prefixes.
protected  OMNode createWithCustomBuilder(CustomBuilder customBuilder, OMFactory factory)
           
 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, 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
 

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


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

createPI

protected OMNode createPI()
                   throws OMException
Method createPI.

Returns:
Returns OMNode.
Throws:
OMException

createEntityReference

protected OMNode createEntityReference()

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

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.



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