public class StAXOMBuilder extends StAXBuilder
This class supports the XMLStreamReader
extension defined by
DataHandlerReader
as well as the legacy extension mechanism
defined in the documentation of XMLStreamReaderUtils
.
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()
.
_isClosed, _releaseParserOnClose, cache, charEncoding, customBuilderForPayload, customBuilders, dataHandlerReader, document, done, elementLevel, maxDepthForCustomBuilders, omfactory, parser, parserAccessed, parserException, target
Constructor and Description |
---|
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.
|
Modifier and Type | Method and Description |
---|---|
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.
|
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
|
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
public StAXOMBuilder(OMFactory ombuilderFactory, XMLStreamReader parser)
ombuilderFactory
- parser
- public StAXOMBuilder(OMFactory factory, XMLStreamReader parser, OMElement element, String characterEncoding)
factory
- parser
- element
- characterEncoding
- of existing elementpublic StAXOMBuilder(OMFactory factory, XMLStreamReader parser, OMElement element)
factory
- parser
- element
- public StAXOMBuilder(String filePath) throws XMLStreamException, FileNotFoundException
filePath
- - Path to the XML fileXMLStreamException
FileNotFoundException
public StAXOMBuilder(XMLStreamReader parser)
parser
- public StAXOMBuilder(InputStream inStream) throws XMLStreamException
inStream
- - instream which contains the XMLXMLStreamException
public StAXOMBuilder()
protected OMDocument createDocument()
createDocument
in class StAXBuilder
public int next() throws OMException
next
in interface OMXMLParserWrapper
next
in class StAXBuilder
OMException
protected OMNode createNextOMElement()
protected OMNode createWithCustomBuilder(CustomBuilder customBuilder, OMFactory factory)
protected void logParserState()
protected final OMNode createOMElement() throws OMException
createOMElement
in class StAXBuilder
OMException
protected OMElement constructNode(OMContainer parent, String elementName)
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.parent
- the parent for the elementelementName
- the local name for the elementOMElement
; must not be null
protected OMNode createComment() throws OMException
OMException
protected OMNode createDTD() throws OMException
OMException
protected OMNode createPI() throws OMException
OMException
protected OMNode createEntityReference()
public OMElement getDocumentElement()
OMXMLParserWrapper
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.
public OMElement getDocumentElement(boolean discardDocument)
OMXMLParserWrapper
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.discardDocument
- specifies whether the document should be discardedprotected void processNamespaceData(OMElement node)
processNamespaceData
in class StAXBuilder
node
- public void setDoDebug(boolean doDebug)
doDebug
- protected String createPrefix()
public void setNamespaceURIInterning(boolean b)
b
- public boolean isNamespaceURIInterning()
public boolean lookahead()
public boolean isLookahead()
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–2021 The Apache Software Foundation. All rights reserved.