org.apache.axiom.om

## Interface OMContainer

- All Superinterfaces:
    OMInformationItem, OMSerializable
  All Known Subinterfaces:
    OMContainerEx, OMDocument, OMElement, OMElementEx, OMSourcedElement, SOAPBody, SOAPEnvelope, SOAPFault, SOAPFaultClassifier, SOAPFaultCode, SOAPFaultDetail, SOAPFaultNode, SOAPFaultReason, SOAPFaultRole, SOAPFaultSubCode, SOAPFaultText, SOAPFaultValue, SOAPHeader, SOAPHeaderBlock, SOAPMessage

      public interface OMContainer
      extends OMSerializable

  Captures the operations related to containment shared by both a document and an element.

  Exposes the ability to add, find, and iterate over the children of a document or element.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addChild(OMNode omNode)` Adds the given node as the last child of this container.
    `OMXMLParserWrapper` | `getBuilder()` Returns the builder object.
    `Iterator` | `getChildren()` Returns an iterator for the children of the container.
    `Iterator` | `getChildrenWithLocalName(String localName)` Returns an iterator for child nodes matching the local name.
    `Iterator` | `getChildrenWithName(QName elementQName)` Returns an iterator for child nodes matching the given QName.
    `Iterator` | `getChildrenWithNamespaceURI(String uri)` Returns an iterator for child nodes matching the namespace uri.
    `Iterator` | `getDescendants(boolean includeSelf)` Get an iterator over all descendants of the container.
    `OMElement` | `getFirstChildWithName(QName qname)` Returns the first child in document order that matches the given QName.
    `OMNode` | `getFirstOMChild()` Gets the first child.
    `SAXResult` | `getSAXResult()` Get a `SAXResult` object that can be used to append child nodes to this container.
    `SAXSource` | `getSAXSource(boolean cache)` Get a `SAXSource` representation for this node.
    `javax.xml.stream.XMLStreamReader` | `getXMLStreamReader()` Get a pull parser representation of this element with caching enabled.
    `javax.xml.stream.XMLStreamReader` | `getXMLStreamReader(boolean cache)` Get a pull parser representation of this information item.
    `javax.xml.stream.XMLStreamReader` | `getXMLStreamReader(boolean cache, OMXMLStreamReaderConfiguration configuration)` Get a pull parser representation of this information item.
    `javax.xml.stream.XMLStreamReader` | `getXMLStreamReaderWithoutCaching()` Get a pull parser representation of this element with caching disabled.
    `void` | `removeChildren()` Remove all children from this container.
    `void` | `serialize(OutputStream output)` Serialize the node with caching enabled.
    `void` | `serialize(OutputStream output, OMOutputFormat format)` Serialize the node with caching enabled.
    `void` | `serialize(Writer writer)` Serialize the node with caching enabled.
    `void` | `serialize(Writer writer, OMOutputFormat format)` Serialize the node with caching enabled.
    `void` | `serializeAndConsume(OutputStream output)` Serialize the node without caching.
    `void` | `serializeAndConsume(OutputStream output, OMOutputFormat format)` Serialize the node without caching.
    `void` | `serializeAndConsume(Writer writer)` Serialize the node without caching.
    `void` | `serializeAndConsume(Writer writer, OMOutputFormat format)` Serialize the node without caching.

    - ### Methods inherited from interface org.apache.axiom.om.OMSerializable

      `build, close, isComplete, serialize, serialize, serializeAndConsume`

    - ### Methods inherited from interface org.apache.axiom.om.OMInformationItem

      `clone, getOMFactory`

- - ### Method Detail

    - #### getBuilder

          OMXMLParserWrapper getBuilder()

      Returns the builder object.
      Returns:
        Returns the builder object used to construct the underlying XML infoset on the fly.

    - #### addChild

          void addChild(OMNode omNode)

      Adds the given node as the last child of this container.

      The method may throw an `OMException` if the node is not allowed at this position of the document.

      Parameters:
        `omNode` - the node to be added to this container

    - #### getChildrenWithName

          Iterator getChildrenWithName(QName elementQName)

      Returns an iterator for child nodes matching the given QName.
      Parameters:
        `elementQName` - The QName specifying namespace and local name to match.
      Returns:
        Returns an iterator of `OMElement` items that match the given QName

    - #### getChildrenWithLocalName

          Iterator getChildrenWithLocalName(String localName)

      Returns an iterator for child nodes matching the local name.
      Parameters:
        `localName` -
      Returns:
        Returns an iterator of `OMElement` items that match the given localName

    - #### getChildrenWithNamespaceURI

          Iterator getChildrenWithNamespaceURI(String uri)

      Returns an iterator for child nodes matching the namespace uri.
      Parameters:
        `uri` -
      Returns:
        Returns an iterator of `OMElement` items that match the given uri

    - #### getFirstChildWithName

          OMElement getFirstChildWithName(QName qname)
                                   throws OMException

      Returns the first child in document order that matches the given QName. The QName filter is applied in the same way as by the `getChildrenWithName(QName)` method.
      Parameters:
        `qname` - The QName to use for matching.
      Returns:
        The first child element in document order that matches the `qname` criteria, or `null` if none is found.
      Throws:
        `OMException` - If an error occurs during deferred parsing.
      See Also:
        `getChildrenWithName(QName)`

    - #### getChildren

          Iterator getChildren()

      Returns an iterator for the children of the container.
      Returns:
        Returns a `Iterator` of children, all of which implement `OMNode`.
      See Also:
        `getFirstChildWithName(javax.xml.namespace.QName)`, `getChildrenWithName(javax.xml.namespace.QName)`

    - #### getDescendants

          Iterator getDescendants(boolean includeSelf)

      Get an iterator over all descendants of the container. The items are returned in document order. Note that attributes and namespace declarations are not considered descendants.
      Parameters:
        `includeSelf` - `true` if the iterator should also return the container itself; `false` if the first item returned by the iterator should be the first child of the container
      Returns:
        an iterator over the descendants of this container

    - #### getFirstOMChild

          OMNode getFirstOMChild()

      Gets the first child.
      Returns:
        Returns the first child. May return null if the container has no children.

    - #### removeChildren

          void removeChildren()

      Remove all children from this container. This method has the same effect as the following code:

           for (Iterator it = container.getChildren(); it.hasNext(); ) {
               it.next();
               it.remove();
           }

      However, the implementation may do this in an optimized way. In particular, if the node is incomplete, it may choose not to instantiate child node that would become unreachable anyway.

    - #### serialize

          void serialize(OutputStream output)
                  throws javax.xml.stream.XMLStreamException

      Serialize the node with caching enabled.

      This method will always serialize the infoset as plain XML. In particular, any `OMText` containing optimized binary will be inlined using base64 encoding.

      Parameters:
        `output` - the byte stream to write the serialized infoset to
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### serialize

          void serialize(Writer writer)
                  throws javax.xml.stream.XMLStreamException

      Serialize the node with caching enabled.

      This method will always serialize the infoset as plain XML. In particular, any `OMText` containing optimized binary will be inlined using base64 encoding.

      Parameters:
        `writer` - the character stream to write the serialized infoset to
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### serialize

          void serialize(OutputStream output,
                         OMOutputFormat format)
                  throws javax.xml.stream.XMLStreamException

      Serialize the node with caching enabled.

      The format of the output is controlled by the provided `OMOutputFormat` object. In particular, `OMOutputFormat.setDoOptimize(boolean)` can be used to instruct this method to produce an XOP/MTOM encoded MIME message.

      Parameters:
        `output` - the byte stream to write the serialized infoset to
        `format` - the output format to use
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### serialize

          void serialize(Writer writer,
                         OMOutputFormat format)
                  throws javax.xml.stream.XMLStreamException

      Serialize the node with caching enabled.
      Parameters:
        `writer` - the character stream to write the serialized infoset to
        `format` - the output format to use
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### serializeAndConsume

          void serializeAndConsume(OutputStream output)
                            throws javax.xml.stream.XMLStreamException

      Serialize the node without caching.

      This method will always serialize the infoset as plain XML. In particular, any `OMText` containing optimized binary will be inlined using base64 encoding.

      Parameters:
        `output` - the byte stream to write the serialized infoset to
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### serializeAndConsume

          void serializeAndConsume(Writer writer)
                            throws javax.xml.stream.XMLStreamException

      Serialize the node without caching.

      This method will always serialize the infoset as plain XML. In particular, any `OMText` containing optimized binary will be inlined using base64 encoding.

      Parameters:
        `writer` - the character stream to write the serialized infoset to
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### serializeAndConsume

          void serializeAndConsume(OutputStream output,
                                   OMOutputFormat format)
                            throws javax.xml.stream.XMLStreamException

      Serialize the node without caching.

      The format of the output is controlled by the provided `OMOutputFormat` object. In particular, `OMOutputFormat.setDoOptimize(boolean)` can be used to instruct this method to produce an XOP/MTOM encoded MIME message.

      Parameters:
        `output` - the byte stream to write the serialized infoset to
        `format` - the output format to use
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### serializeAndConsume

          void serializeAndConsume(Writer writer,
                                   OMOutputFormat format)
                            throws javax.xml.stream.XMLStreamException

      Serialize the node without caching.
      Parameters:
        `writer` - the character stream to write the serialized infoset to
        `format` - the output format to use
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### getXMLStreamReader

          javax.xml.stream.XMLStreamReader getXMLStreamReader()

      Get a pull parser representation of this element with caching enabled. This method has the same effect as `getXMLStreamReader(boolean)` with `cache` set to `true`.
      Returns:
        an `XMLStreamReader` representation of this element

    - #### getXMLStreamReaderWithoutCaching

          javax.xml.stream.XMLStreamReader getXMLStreamReaderWithoutCaching()

      Get a pull parser representation of this element with caching disabled. This method has the same effect as `getXMLStreamReader(boolean)` with `cache` set to `false`.
      Returns:
        an `XMLStreamReader` representation of this element

    - #### getXMLStreamReader

          javax.xml.stream.XMLStreamReader getXMLStreamReader(boolean cache)

      Get a pull parser representation of this information item. This methods creates an `XMLStreamReader` instance that produces a sequence of StAX events for this container and its content. The sequence of events is independent of the state of this element and the value of the `cache` parameter, but the side effects of calling this method and consuming the reader are different:

      Side effects of consuming events from the reader returned by `getXMLStreamReader(boolean)`
      State | `cache` | Side effects
      --- | --- | ---
      The element is fully built (or was created programmatically). | `true` | No side effects. The reader will synthesize StAX events from the object model.
      `false`
      The element is partially built, i.e. deferred parsing is taking place. | `true` | When a StAX event is requested from the reader, it will built the information item (if necessary) and synthesize the StAX event. If the caller completely consumes the reader, the element will be completely built. Otherwise it will be partially built.
      `false` | The reader will delegate to the underlying parser starting from the event corresponding to the last information item that has been built. In other words, after synthesizing a number of events, the reader will switch to delegation mode (also called "pull through" mode). This will consume the part of the object model from which the reader was requested. An attempt to access that part of the object model afterwards will result in a `NodeUnavailableException`. Other parts of the object model can be accessed in a normal way once the reader has been completely consumed or closed.

      To free any resources associated with the returned reader, the caller MUST invoke the `XMLStreamReader.close()` method.

      The returned reader MAY implement the extension defined by `DataHandlerReader` and any binary content will be reported using this extension. More precisely, if the object model contains an `OMText` instance with `OMText.isBinary()` returning `true` (or would contain such an instance after it has been fully built), then its data will always be exposed through this extension.

      The caller MUST NOT make any other assumption about the returned reader, in particular about its runtime type.

      Note (non normative): For various reasons, existing code based on Axiom versions prior to 1.2.9 makes assumptions on the returned reader that should no longer be considered valid:

      - Some code uses the `OMXMLStreamReader` interface of the returned reader to switch off MTOM inlining using `OMXMLStreamReader.setInlineMTOM(boolean)`. This has now been deprecated and it is recommended to use `XOPEncodingStreamReader` instead.
      - Some existing code uses the `OMAttachmentAccessor` interface of the returned reader to fetch attachments using `OMAttachmentAccessor.getDataHandler(String)`. There is no reason anymore to do so:
        - When `OMXMLStreamReader.setInlineMTOM(boolean)` is used to disable MTOM inlining, `OMAttachmentAccessor.getDataHandler(String)` must be used to retrieve the binary content. The fact that this method is deprecated removes the need for this.
        - In Axiom versions prior to 1.2.9, the sequence of events was inconsistent if the underlying stream is XOP encoded and caching is disabled (see AXIOM-255). This made it necessary for the caller to (partially) handle the XOP processing and to use `OMAttachmentAccessor.getDataHandler(String)` to retrieve the binary content. Starting with 1.2.9 this is no longer be the case: as specified above, the sequence of events is independent of the state of the object model and the value of the `cache` parameter, and all binary content is reported through the `DataHandlerReader` extension.
        - Finally, it should be noted that `OMAttachmentAccessor.getDataHandler(String)` doesn't give access to the attachments in the SwA case (neither in 1.2.9 nor in previous versions).

      Code making any of these assumptions should be fixed, so that only `XMLStreamReader` and `DataHandlerReader` are used (and if necessary, `XOPEncodingStreamReader`).

      Parameters:
        `cache` - indicates if caching should be enabled
      Returns:
        an `XMLStreamReader` representation of this information item

    - #### getXMLStreamReader

          javax.xml.stream.XMLStreamReader getXMLStreamReader(boolean cache,
                                                              OMXMLStreamReaderConfiguration configuration)

      Get a pull parser representation of this information item. This method is similar to `getXMLStreamReader(boolean)`, but accepts an `OMXMLStreamReaderConfiguration` object that allows to specify additional options and to customize the behavior of the returned reader.
      Parameters:
        `cache` - indicates if caching should be enabled
        `configuration` - additional configuration options; see the Javadoc of `OMXMLStreamReaderConfiguration` for more information about the available options
      Returns:
        an `XMLStreamReader` representation of this information item

    - #### getSAXSource

          SAXSource getSAXSource(boolean cache)

      Get a `SAXSource` representation for this node. This method can be used to integrate Axiom with APIs and third party libraries that don't support StAX. In particular it can be used with the `Transformer` API.

      The returned object supports all events defined by `ContentHandler` and `LexicalHandler`. `DTDHandler` and `DeclHandler` are not supported.

      If the node is an element and has a parent which is not a document, care is taken to properly generate `ContentHandler.startPrefixMapping(String, String)` and `ContentHandler.endPrefixMapping(String)` events also for namespace mappings declared on the ancestors of the element. To understand why this is important, consider the following example:

          <root xmlns:ns="urn:ns"><element attr="ns:someThing"/><root>

      In that case, to correctly interpret the attribute value, the SAX content handler must be aware of the namespace mapping for the `ns` prefix, even if the serialization starts only at the child element.

      No other form of namespace repairing is performed.

      Parameters:
        `cache` - Indicates if caching should be enabled. If set to `false`, the returned `SAXSource` may only be used once, and using it may have the side effect of consuming the original content of this node.
      Returns:
        a `SAXSource` representation of this element

    - #### getSAXResult

          SAXResult getSAXResult()

      Get a `SAXResult` object that can be used to append child nodes to this container. Note that existing child nodes will not be removed. In order to replace the content of the container, call `removeChildren()` first.

      The SAX content handler linked to the returned `SAXResult` supports `ContentHandler`, `LexicalHandler`, `DeclHandler` and `DTDHandler`. DTD related events are processed in the following way:

      - A `LexicalHandler.startDTD(String, String, String)` events will create an `OMDocType` if the container is an `OMDocument`. If the container is an `OMElement`, the event will be ignored silently.
      - Entity references are always replaced, i.e. no `OMEntityReference` objects are created for `LexicalHandler.startEntity(String)` events.

      Nodes created by the `ContentHandler` linked to the returned `SAXResult` will have the same characteristics as programmatically created nodes; in particular they will have no associated builder.

      Returns:
        the `SAXResult` object
      See Also:
        `OMXMLBuilderFactory.createOMBuilder(SAXSource, boolean)`, `OMXMLBuilderFactory.createOMBuilder(OMFactory, SAXSource, boolean)`

Copyright © The Apache Software Foundation. All Rights Reserved.