org.apache.axiom.om.impl.builder

Class StAXBuilder

java.lang.Object

org.apache.axiom.om.impl.builder.StAXBuilder

All Implemented Interfaces:

OMXMLParserWrapper

Direct Known Subclasses:

StAXOMBuilder

public abstract class StAXBuilder
extends java.lang.Object
implements OMXMLParserWrapper

OM should be able to be built from any data source. And the model it builds may be a SOAP specific one or just an XML model. This class will give some common functionality of OM Building from StAX.

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	_isClosed
protected boolean	_releaseParserOnClose
protected boolean	cache Field cache
protected java.lang.String	charEncoding
protected CustomBuilder	customBuilderForPayload
protected java.util.Map	customBuilders
protected DataHandlerReader	dataHandlerReader Reference to the DataHandlerReader extension of the parser, or null if the parser doesn't support this extension.
private java.util.Map	discardTracker Stores the stack trace of the code that caused a node to be discarded or consumed.
protected OMDocument	document
protected boolean	done Field done
protected int	elementLevel Element level is the depth of the element.
private static org.apache.commons.logging.Log	log
protected int	maxDepthForCustomBuilders
protected OMFactoryEx	omfactory Field omfactory
protected javax.xml.stream.XMLStreamReader	parser Field parser
protected boolean	parserAccessed Field parserAccessed
protected java.lang.Exception	parserException Stores exceptions thrown by the parser.
protected OMContainerEx	target Field lastNode

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	StAXBuilder() Deprecated.
protected	StAXBuilder(OMFactory ombuilderFactory, javax.xml.stream.XMLStreamReader parser) Constructor StAXBuilder.
protected	StAXBuilder(OMFactory ombuilderFactory, javax.xml.stream.XMLStreamReader parser, java.lang.String characterEncoding) Constructor StAXBuilder.
protected	StAXBuilder(javax.xml.stream.XMLStreamReader parser) Constructor StAXBuilder.

Method Summary

Modifier and Type	Method and Description
void	close() Close this builder.
protected abstract OMDocument	createDocument()
protected void	createDocumentIfNecessary()
protected abstract OMNode	createOMElement() This method is called with the XMLStreamConstants.START_ELEMENT event.
protected OMNode	createOMText(int textType) This method will check whether the text can be optimizable using IS_BINARY flag.
void	debugDiscarded(java.lang.Object container) For internal use only.
void	discard(OMContainer container)
void	discard(OMElement element)
private void	discarded(OMContainerEx container)
int	getAttributeCount() Method getAttributeCount.
java.lang.String	getAttributeName(int arg) Method getAttributeName.
java.lang.String	getAttributeNamespace(int arg) Method getAttributeNamespace.
java.lang.String	getAttributePrefix(int arg) Method getAttributePrefix.
short	getBuilderType() Returns the type of the builder.
java.lang.String	getCharacterEncoding() Returns the encoding style of the XML data
java.lang.String	getCharsetEncoding()
protected CustomBuilder	getCustomBuilder(java.lang.String namespace, java.lang.String localPart) Return CustomBuilder associated with the namespace/localPart
OMDocument	getDocument() Get the document being built by this builder.
java.lang.String	getName() Method getName.
java.lang.String	getNamespace() Method getNamespace.
int	getNamespaceCount() Method getNamespaceCount.
java.lang.String	getNamespacePrefix(int index) Method getNamespacePrefix.
java.lang.String	getNamespaceUri(int index) Method getNamespaceUri.
java.lang.Object	getParser() Get the underlying XMLStreamReader used by this builder.
java.lang.String	getPrefix() Method getPrefix.
java.lang.Object	getReaderProperty(java.lang.String name) Get the value of a feature/property from the underlying XMLStreamReader implementation without accessing the XMLStreamReader.
java.lang.Object	getRegisteredContentHandler() Method getRegisteredContentHandler.
java.lang.String	getText() Method getText.
void	init(java.io.InputStream inputStream, java.lang.String charSetEncoding, java.lang.String url, java.lang.String contentType) Deprecated. Not used anywhere
private void	initParser(javax.xml.stream.XMLStreamReader parser)
boolean	isCache()
boolean	isClosed()
boolean	isCompleted() Method isCompleted.
abstract int	next() Forwards the parser one step further, if parser is not completed yet.
(package private) abstract int	parserNext()
protected void	processAttributes(OMElement node) Method processAttributes.
protected abstract void	processNamespaceData(OMElement node) Method processNamespaceData.
CustomBuilder	registerCustomBuilder(javax.xml.namespace.QName qName, int maxDepth, CustomBuilder customBuilder) Register a CustomBuilder associated with the indicated QName.
CustomBuilder	registerCustomBuilderForPayload(CustomBuilder customBuilder) Register a CustomBuilder for a payload.
void	registerExternalContentHandler(java.lang.Object obj) Method registerExternalContentHandler.
void	releaseParserOnClose(boolean value) Indicate if the parser resource should be release when closed.
void	setCache(boolean b) Method setCache.
void	setOMBuilderFactory(OMFactory ombuilderFactory) Method setOMBuilderFactory.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.axiom.om.OMXMLParserWrapper

getDocumentElement, getDocumentElement

Field Detail

log

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

parser

protected javax.xml.stream.XMLStreamReader parser

Field parser

omfactory

protected OMFactoryEx omfactory

Field omfactory

target

protected OMContainerEx target

Field lastNode

done

protected boolean done

Field done

cache

protected boolean cache

Field cache

parserAccessed

protected boolean parserAccessed

Field parserAccessed

document

protected OMDocument document

charEncoding

protected java.lang.String charEncoding

_isClosed

protected boolean _isClosed

_releaseParserOnClose

protected boolean _releaseParserOnClose

customBuilderForPayload

protected CustomBuilder customBuilderForPayload

customBuilders

protected java.util.Map customBuilders

maxDepthForCustomBuilders

protected int maxDepthForCustomBuilders

dataHandlerReader

protected DataHandlerReader dataHandlerReader

Reference to the DataHandlerReader extension of the parser, or null if the parser doesn't support this extension.

elementLevel

protected int elementLevel

Element level is the depth of the element. The root element (i.e. envelope) is defined as 1.

parserException

protected java.lang.Exception parserException

Stores exceptions thrown by the parser. Used to avoid accessing the parser again after is has thrown a parse exception.

discardTracker

private final java.util.Map discardTracker

Stores the stack trace of the code that caused a node to be discarded or consumed. This is only used if debug logging was enabled when builder was created.

Constructor Detail

StAXBuilder

protected StAXBuilder(OMFactory ombuilderFactory,
                      javax.xml.stream.XMLStreamReader parser)

Constructor StAXBuilder. This constructor is used if the parser is at the beginning (START_DOCUMENT).

Parameters:

ombuilderFactory -

parser -

StAXBuilder

protected StAXBuilder(OMFactory ombuilderFactory,
                      javax.xml.stream.XMLStreamReader parser,
                      java.lang.String characterEncoding)

Constructor StAXBuilder. This constructor is used if the parser is not at the START_DOCUMENT.

Parameters:

ombuilderFactory -

parser -

characterEncoding -

StAXBuilder

protected StAXBuilder(javax.xml.stream.XMLStreamReader parser)

Constructor StAXBuilder.

Parameters:

parser -

StAXBuilder

protected StAXBuilder()

Deprecated.

Method Detail

initParser

private void initParser(javax.xml.stream.XMLStreamReader parser)

init

public void init(java.io.InputStream inputStream,
                 java.lang.String charSetEncoding,
                 java.lang.String url,
                 java.lang.String contentType)
          throws OMException

Deprecated. Not used anywhere

Throws:

OMException

setOMBuilderFactory

public void setOMBuilderFactory(OMFactory ombuilderFactory)

Method setOMBuilderFactory.

Parameters:

ombuilderFactory -

processNamespaceData

protected abstract void processNamespaceData(OMElement node)

Method processNamespaceData.

Parameters:

node -

processAttributes

protected void processAttributes(OMElement node)

Method processAttributes.

Parameters:

node -

createOMText

protected OMNode createOMText(int textType)

This method will check whether the text can be optimizable using IS_BINARY flag. If that is set then we try to get the data handler.

Parameters:

textType -

Returns:

omNode

discarded

private void discarded(OMContainerEx container)

debugDiscarded

public void debugDiscarded(java.lang.Object container)

For internal use only.

Parameters:

container -

discard

public void discard(OMElement element)
             throws OMException

Specified by:

discard in interface OMXMLParserWrapper

Throws:

OMException

discard

public void discard(OMContainer container)
             throws OMException

Throws:

OMException

getText

public java.lang.String getText()
                         throws OMException

Method getText.

Returns:

Returns String.

Throws:

OMException

getNamespace

public java.lang.String getNamespace()
                              throws OMException

Method getNamespace.

Returns:

Returns String.

Throws:

OMException

getNamespaceCount

public int getNamespaceCount()
                      throws OMException

Method getNamespaceCount.

Returns:

Returns int.

Throws:

OMException

getNamespacePrefix

public java.lang.String getNamespacePrefix(int index)
                                    throws OMException

Method getNamespacePrefix.

Parameters:

index -

Returns:

Returns String.

Throws:

OMException

getNamespaceUri

public java.lang.String getNamespaceUri(int index)
                                 throws OMException

Method getNamespaceUri.

Parameters:

index -

Returns:

Returns String.

Throws:

OMException

setCache

public void setCache(boolean b)

Method setCache.

Specified by:

setCache in interface OMXMLParserWrapper

Parameters:

b -

isCache

public boolean isCache()

Specified by:

isCache in interface OMXMLParserWrapper

Returns:

true if caching

getName

public java.lang.String getName()
                         throws OMException

Method getName.

Returns:

Returns String.

Throws:

OMException

getPrefix

public java.lang.String getPrefix()
                           throws OMException

Method getPrefix.

Returns:

Returns String.

Throws:

OMException

getAttributeCount

public int getAttributeCount()
                      throws OMException

Method getAttributeCount.

Returns:

Returns int.

Throws:

OMException

getAttributeNamespace

public java.lang.String getAttributeNamespace(int arg)
                                       throws OMException

Method getAttributeNamespace.

Parameters:

arg -

Returns:

Returns String.

Throws:

OMException

getAttributeName

public java.lang.String getAttributeName(int arg)
                                  throws OMException

Method getAttributeName.

Parameters:

arg -

Returns:

Returns String.

Throws:

OMException

getAttributePrefix

public java.lang.String getAttributePrefix(int arg)
                                    throws OMException

Method getAttributePrefix.

Parameters:

arg -

Returns:

Returns String.

Throws:

OMException

getParser

public java.lang.Object getParser()

Get the underlying XMLStreamReader used by this builder. Note that for this type of builder, accessing the underlying parser implies that can no longer be used, and any attempt to call next() will result in an exception.

Specified by:

getParser in interface OMXMLParserWrapper

Returns:

The XMLStreamReader object used by this builder. Note that the constraints described in the Javadoc of the reader parameter of the CustomBuilder.create(String, String, OMContainer, XMLStreamReader, OMFactory) method also apply to the stream reader returned by this method, i.e.:

• The caller should use XOPUtils.getXOPEncodedStream(XMLStreamReader) to get an XOP encoded stream from the return value.
• To get access to the bare StAX parser implementation, the caller should use XMLStreamReaderUtils.getOriginalXMLStreamReader(XMLStreamReader).

Throws:

java.lang.IllegalStateException - if the parser has already been accessed

isCompleted

public boolean isCompleted()

Method isCompleted.

Specified by:

isCompleted in interface OMXMLParserWrapper

Returns:

Returns boolean.

createOMElement

protected abstract OMNode createOMElement()
                                   throws OMException

This method is called with the XMLStreamConstants.START_ELEMENT event.

Returns:

Returns OMNode.

Throws:

OMException

parserNext

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

Throws:

javax.xml.stream.XMLStreamException

next

public abstract int next()
                  throws OMException

Forwards the parser one step further, if parser is not completed yet. If this is called after parser is done, then throw an OMException. If the cache is set to false, then returns the event, *without* building the OM tree. If the cache is set to true, then handles all the events within this, and builds the object structure appropriately and returns the event.

Specified by:

next in interface OMXMLParserWrapper

Returns:

Returns int.

Throws:

OMException

registerCustomBuilder

public CustomBuilder registerCustomBuilder(javax.xml.namespace.QName qName,
                                           int maxDepth,
                                           CustomBuilder customBuilder)

Register a CustomBuilder associated with the indicated QName. The CustomBuilder will be used when an element of that qname is encountered.

Parameters:

qName -

maxDepth - indicate the maximum depth that this qname will be found. (root = 0)

customBuilder -

Returns:

replaced CustomBuilder or null

registerCustomBuilderForPayload

public CustomBuilder registerCustomBuilderForPayload(CustomBuilder customBuilder)

Register a CustomBuilder for a payload. The payload is defined as the elements inside a SOAPBody or the document element of a REST message.

Parameters:

customBuilder -

Returns:

replaced CustomBuilder or null

getCustomBuilder

protected CustomBuilder getCustomBuilder(java.lang.String namespace,
                                         java.lang.String localPart)

Return CustomBuilder associated with the namespace/localPart

Parameters:

namespace -

localPart -

Returns:

CustomBuilder or null

getBuilderType

public short getBuilderType()

Description copied from interface: OMXMLParserWrapper

Returns the type of the builder. Can be either OMConstants.PUSH_TYPE_BUILDER or OMConstants.PULL_TYPE_BUILDER.

Specified by:

getBuilderType in interface OMXMLParserWrapper

Returns:

Returns short.

registerExternalContentHandler

public void registerExternalContentHandler(java.lang.Object obj)

Method registerExternalContentHandler.

Specified by:

registerExternalContentHandler in interface OMXMLParserWrapper

Parameters:

obj -

getRegisteredContentHandler

public java.lang.Object getRegisteredContentHandler()

Method getRegisteredContentHandler.

Specified by:

getRegisteredContentHandler in interface OMXMLParserWrapper

Returns:

Returns Object.

createDocument

protected abstract OMDocument createDocument()

createDocumentIfNecessary

protected void createDocumentIfNecessary()

getDocument

public OMDocument getDocument()

Description copied from interface: OMXMLParserWrapper

Get the document being built by this builder.

Specified by:

getDocument in interface OMXMLParserWrapper

Returns:

the OMDocument instance

getCharsetEncoding

public java.lang.String getCharsetEncoding()

close

public void close()

Description copied from interface: OMXMLParserWrapper

Close this builder. This method frees the resources associated with this builder. In particular, it releases the resources held by the underlying parser. This method does not close the underlying input source.

Specified by:

close in interface OMXMLParserWrapper

getReaderProperty

public java.lang.Object getReaderProperty(java.lang.String name)
                                   throws java.lang.IllegalArgumentException

Get the value of a feature/property from the underlying XMLStreamReader implementation without accessing the XMLStreamReader. https://issues.apache.org/jira/browse/AXIOM-348

Parameters:

name -

Returns:

TODO

Throws:

java.lang.IllegalArgumentException

getCharacterEncoding

public java.lang.String getCharacterEncoding()

Returns the encoding style of the XML data

Specified by:

getCharacterEncoding in interface OMXMLParserWrapper

Returns:

the character encoding, defaults to "UTF-8"

isClosed

public boolean isClosed()

Returns:

if parser is closed

releaseParserOnClose

public void releaseParserOnClose(boolean value)

Indicate if the parser resource should be release when closed.

Parameters:

value - boolean