org.apache.axiom.om.impl.builder

## Class StAXBuilder

- java.lang.Object
- - org.apache.axiom.om.impl.builder.StAXBuilder

- All Implemented Interfaces:
    CustomBuilderSupport, OMXMLParserWrapper
  Direct Known Subclasses:
    StAXOMBuilder

      public abstract class StAXBuilder
      extends Object
      implements OMXMLParserWrapper, CustomBuilderSupport

  Internal implementation class.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `_isClosed`
    `protected boolean` | `cache` Field cache
    `protected String` | `charEncoding`
    `protected CustomBuilder` | `customBuilderForPayload`
    `protected Map<QName,CustomBuilder>` | `customBuilders`
    `protected DataHandlerReader` | `dataHandlerReader` Reference to the `DataHandlerReader` extension of the parser, or `null` if the parser doesn't support this extension.
    `protected OMDocument` | `document`
    `protected boolean` | `done` Field done
    `protected int` | `elementLevel` Tracks the depth of the node identified by `target`.
    `protected int` | `maxDepthForCustomBuilders`
    `protected OMFactoryEx` | `omfactory` Field omfactory
    `protected javax.xml.stream.XMLStreamReader` | `parser` Field parser
    `protected boolean` | `parserAccessed` Field parserAccessed
    `protected 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 omFactory, javax.xml.stream.XMLStreamReader parser)` Deprecated.
    `protected` | `StAXBuilder(OMFactory omFactory, javax.xml.stream.XMLStreamReader parser, Detachable detachable, Closeable closeable)` For internal use only.
    `protected` | `StAXBuilder(OMFactory omFactory, javax.xml.stream.XMLStreamReader parser, String encoding)` Deprecated.
    `protected` | `StAXBuilder(OMFactory omFactory, javax.xml.stream.XMLStreamReader parser, String encoding, Detachable detachable, Closeable closeable)` For internal use only.
    `protected` | `StAXBuilder(javax.xml.stream.XMLStreamReader parser)` Deprecated.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    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(Object container)` For internal use only.
    `void` | `detach()` Detach this builder from its underlying source, so that the state of the source object can be changed without impact on the object model produced by this builder.
    `javax.xml.stream.XMLStreamReader` | `disableCaching()` For internal use only.
    `void` | `discard(OMContainer container)`
    `void` | `discard(OMElement element)`
    `int` | `getAttributeCount()` Method getAttributeCount.
    `String` | `getAttributeName(int arg)` Method getAttributeName.
    `String` | `getAttributeNamespace(int arg)` Method getAttributeNamespace.
    `String` | `getAttributePrefix(int arg)` Method getAttributePrefix.
    `short` | `getBuilderType()` Returns the type of the builder.
    `String` | `getCharacterEncoding()` Returns the encoding style of the XML data
    `String` | `getCharsetEncoding()`
    `protected CustomBuilder` | `getCustomBuilder(String namespace, String localPart)` Return CustomBuilder associated with the namespace/localPart
    `OMDocument` | `getDocument()` Get the document being built by this builder.
    `String` | `getName()` Method getName.
    `String` | `getNamespace()` Method getNamespace.
    `int` | `getNamespaceCount()` Method getNamespaceCount.
    `String` | `getNamespacePrefix(int index)` Method getNamespacePrefix.
    `String` | `getNamespaceUri(int index)` Method getNamespaceUri.
    `Object` | `getParser()` Get the underlying `XMLStreamReader` used by this builder.
    `String` | `getPrefix()` Method getPrefix.
    `Object` | `getReaderProperty(String name)` Get the value of a feature/property from the underlying XMLStreamReader implementation without accessing the XMLStreamReader. https://issues.apache.org/jira/browse/AXIOM-348
    `Object` | `getRegisteredContentHandler()` Method getRegisteredContentHandler.
    `String` | `getText()` Method getText.
    `void` | `init(InputStream inputStream, String charSetEncoding, String url, String contentType)` Deprecated. Not used anywhere
    `boolean` | `isCache()`
    `boolean` | `isClosed()`
    `boolean` | `isCompleted()` Method isCompleted.
    `abstract int` | `next()` Forwards the parser one step further, if parser is not completed yet.
    `protected void` | `processAttributes(OMElement node)` Method processAttributes.
    `protected abstract void` | `processNamespaceData(OMElement node)` Method processNamespaceData.
    `void` | `reenableCaching(OMContainer container)` For internal use only.
    `CustomBuilder` | `registerCustomBuilder(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(Object obj)` Method registerExternalContentHandler.
    `void` | `releaseParserOnClose(boolean value)` Deprecated. As of Axiom 1.2.15, the builder always releases the parser.
    `void` | `setAutoClose(boolean autoClose)` For internal use only.
    `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

    - #### 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 String charEncoding

    - #### _isClosed

          protected boolean _isClosed

    - #### customBuilderForPayload

          protected CustomBuilder customBuilderForPayload

    - #### customBuilders

          protected Map<QName,CustomBuilder> 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

      Tracks the depth of the node identified by `target`. By definition, the level of the root element is defined as 1. Note that if caching is disabled, then this depth may be different from the actual depth reached by the underlying parser.

    - #### parserException

          protected Exception parserException

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

  - ### Constructor Detail

    - #### StAXBuilder

          protected StAXBuilder(OMFactory omFactory,
                                javax.xml.stream.XMLStreamReader parser,
                                String encoding,
                                Detachable detachable,
                                Closeable closeable)

      For internal use only.

    - #### StAXBuilder

          protected StAXBuilder(OMFactory omFactory,
                                javax.xml.stream.XMLStreamReader parser,
                                Detachable detachable,
                                Closeable closeable)

      For internal use only.

    - #### StAXBuilder

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

      Deprecated.

    - #### StAXBuilder

          protected StAXBuilder(OMFactory omFactory,
                                javax.xml.stream.XMLStreamReader parser,
                                String encoding)

      Deprecated.

    - #### StAXBuilder

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

      Deprecated.

    - #### StAXBuilder

          protected StAXBuilder()

      Deprecated.

  - ### Method Detail

    - #### init

          public void init(InputStream inputStream,
                           String charSetEncoding,
                           String url,
                           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

    - #### debugDiscarded

          public void debugDiscarded(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 String getText()
                         throws OMException

      Method getText.
      Returns:
        Returns String.
      Throws:
        `OMException`

    - #### getNamespace

          public 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 String getNamespacePrefix(int index)
                                    throws OMException

      Method getNamespacePrefix.
      Parameters:
        `index` -
      Returns:
        Returns String.
      Throws:
        `OMException`

    - #### getNamespaceUri

          public 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 String getName()
                         throws OMException

      Method getName.
      Returns:
        Returns String.
      Throws:
        `OMException`

    - #### getPrefix

          public 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 String getAttributeNamespace(int arg)
                                       throws OMException

      Method getAttributeNamespace.
      Parameters:
        `arg` -
      Returns:
        Returns String.
      Throws:
        `OMException`

    - #### getAttributeName

          public String getAttributeName(int arg)
                                  throws OMException

      Method getAttributeName.
      Parameters:
        `arg` -
      Returns:
        Returns String.
      Throws:
        `OMException`

    - #### getAttributePrefix

          public String getAttributePrefix(int arg)
                                    throws OMException

      Method getAttributePrefix.
      Parameters:
        `arg` -
      Returns:
        Returns String.
      Throws:
        `OMException`

    - #### getParser

          public 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:
        `IllegalStateException` - if the parser has already been accessed

    - #### disableCaching

          public javax.xml.stream.XMLStreamReader disableCaching()

      For internal use only.

    - #### reenableCaching

          public void reenableCaching(OMContainer container)

      For internal use only.

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

    - #### 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(QName qName,
                                                     int maxDepth,
                                                     CustomBuilder customBuilder)

      Description copied from interface: `CustomBuilderSupport`
      Register a CustomBuilder associated with the indicated QName. The CustomBuilder will be used when an element of that qname is encountered.
      Specified by:
        `registerCustomBuilder` in interface `CustomBuilderSupport`
        `maxDepth` - indicate the maximum depth that this qname will be found. (root = 0)
      Returns:
        replaced CustomBuilder or null

    - #### registerCustomBuilderForPayload

          public CustomBuilder registerCustomBuilderForPayload(CustomBuilder customBuilder)

      Description copied from interface: `CustomBuilderSupport`
      Register a CustomBuilder for a payload. The payload is defined as the elements inside a SOAPBody or the document element of a REST message.
      Specified by:
        `registerCustomBuilderForPayload` in interface `CustomBuilderSupport`
      Returns:
        replaced CustomBuilder or null

    - #### getCustomBuilder

          protected CustomBuilder getCustomBuilder(String namespace,
                                                   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(Object obj)

      Method registerExternalContentHandler.
      Specified by:
        `registerExternalContentHandler` in interface `OMXMLParserWrapper`
      Parameters:
        `obj` -

    - #### getRegisteredContentHandler

          public 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 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 Object getReaderProperty(String name)
                                   throws 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:
        `IllegalArgumentException`

    - #### getCharacterEncoding

          public String getCharacterEncoding()

      Returns the encoding style of the XML data
      Specified by:
        `getCharacterEncoding` in interface `OMXMLParserWrapper`
      Returns:
        the character encoding, defaults to "UTF-8"

    - #### setAutoClose

          public void setAutoClose(boolean autoClose)

      For internal use only.
      Parameters:
        `autoClose` -

    - #### isClosed

          public boolean isClosed()

      Returns:
        if parser is closed

    - #### releaseParserOnClose

          public void releaseParserOnClose(boolean value)

      Deprecated. As of Axiom 1.2.15, the builder always releases the parser.

    - #### detach

          public void detach()
                      throws OMException

      Description copied from interface: `OMXMLParserWrapper`
      Detach this builder from its underlying source, so that the state of the source object can be changed without impact on the object model produced by this builder. The effect of this method depends on the type of source object passed to `OMXMLBuilderFactory` to create the builder:

      Actions performed by the `OMXMLParserWrapper.detach()` method
      Source object type | Action performed by this method
      --- | ---
      `InputStream`, `Reader`, `StreamSource` with `InputStream` or `Reader` | The remaining unprocessed content of the stream is read into memory so that it can be safely closed. Note that this method doesn't close the stream; this is the responsibility of the caller.
      `StreamSource` with system ID and no stream | The remaining unprocessed content of the document is read into memory and the associated stream is closed.
      `Node`, `DOMSource`, `SAXSource` | The object model is built completely.
      `Attachments` | All MIME parts are fetched so that the stream from which the `Attachments` object has been created can safely be closed.

      Specified by:
        `detach` in interface `OMXMLParserWrapper`
      Throws:
        `OMException`

Copyright © The Apache Software Foundation. All Rights Reserved.