Package org.apache.axiom.om.ds

## Class AbstractPullOMDataSource

- java.lang.Object
- - org.apache.axiom.om.ds.AbstractOMDataSource
  - - org.apache.axiom.om.ds.AbstractPullOMDataSource

- All Implemented Interfaces:
    `OMDataSource`, `OMDataSourceExt`
  Direct Known Subclasses:
    `BlobOMDataSource`, `StringOMDataSource`, `WrappedTextNodeOMDataSource`

      public abstract class AbstractPullOMDataSource
      extends AbstractOMDataSource

  Base class for `OMDataSourceExt` implementations that can easily produce the content as an `XMLStreamReader` and that don't implement any kind of optimization for serializing the content.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `AbstractPullOMDataSource()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `isDestructiveWrite()` | Returns true if writing the backing object is destructive.
    `void` | `serialize​(XMLStreamWriter xmlWriter)` | Serializes element data directly to StAX writer.

    - ### Methods inherited from class org.apache.axiom.om.ds.AbstractOMDataSource

      `close, copy, getObject, getProperty, getXMLBytes, getXMLInputStream, hasProperty, serialize, serialize, setProperty`

    - ### 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.OMDataSource

      `getReader`

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

      `isDestructiveRead`

- - ### Constructor Detail

    - #### AbstractPullOMDataSource

          public AbstractPullOMDataSource()

  - ### Method Detail

    - #### isDestructiveWrite

          public final boolean isDestructiveWrite()

      Description copied from interface: `OMDataSourceExt`
      Returns true if writing the backing object is destructive. An example of an object with a destructive write is an InputStream. The owning OMSourcedElement uses this information to detemine if OM tree expansion is needed when writing the OMDataSourceExt.
      Returns:
        boolean

    - #### serialize

          public final void serialize​(XMLStreamWriter xmlWriter)
                               throws XMLStreamException

      Description copied from interface: `OMDataSource`
      Serializes element data directly to StAX writer.

      The implementation of this method must satisfy the following requirements:

      - The implementation MUST NOT not write any start document or end document event, i.e. it MUST NOT use `XMLStreamWriter.writeStartDocument()`, `XMLStreamWriter.writeStartDocument(String)`, `XMLStreamWriter.writeStartDocument(String, String)` or `XMLStreamWriter.writeEndElement()`.
      - The implementation MUST output a single element (hereafter called the root element). It MUST NOT output any other content before or after that element.
      - The implementation MUST specify the namespace URI when writing an element, i.e. it MUST NOT use the namespace unaware methods `XMLStreamWriter.writeStartElement(String)` or `XMLStreamWriter.writeEmptyElement(String)`. On the other hand, it MAY use the namespace unaware `XMLStreamWriter.writeAttribute(String, String)` method, provided that the specified name is an `NCName`.
      - The implementation MUST ensure that the produced XML is well formed with respect to namespaces, i.e. it MUST generate the required namespace declarations using `XMLStreamWriter.writeNamespace(String, String)` and `XMLStreamWriter.writeDefaultNamespace(String)`. It MUST NOT assume that the `XMLStreamWriter` performs any kind of namespace repairing (although that may be the case).
      - In addition the implementation MAY use `XMLStreamWriter.setPrefix(String, String)` and `XMLStreamWriter.setDefaultNamespace(String)` to track the namespace declarations it generates, so that the namespace context maintained by the `XMLStreamWriter` accurately reflects the namespace context in the output document. However, it MUST NOT call these methods before the start of the root element or after the end of the root element.
      - Since the element may be serialized as part of a larger document, the implementation MUST take into account the pre-existing namespace context (which can be queried using `XMLStreamWriter.getPrefix(String)` and `XMLStreamWriter.getNamespaceContext()`). This means that the implementation MUST NOT assume that the empty prefix is bound to the empty namespace URI. Therefore if the implementation outputs elements that have no namespace, it MUST generate namespace declarations of the form `xmlns=""` in the appropriate locations. In addition it MAY use the namespace context information to minimize the number of generated namespace declarations (by reusing already bound prefixes).
      - To produce base64 binary data (that could be optimized using XOP/MTOM), the implementation MUST use one of the following approaches:
        - Use the `DataHandlerWriter` extension (or alternatively the `XMLStreamWriterUtils.writeDataHandler(XMLStreamWriter, DataHandler, String, boolean)` or `XMLStreamWriterUtils.writeDataHandler(XMLStreamWriter, DataHandlerProvider, String, boolean)` utility methods) to write the data to the stream. This is the preferred approach, unless the content is produced by a third party library that is not aware of these APIs.
        - Cast the `XMLStreamWriter` to an `MTOMXMLStreamWriter`, use `MTOMXMLStreamWriter.prepareDataHandler(DataHandler)` and generate the necessary `xop:Include` elements. In this case, the implementation MAY use `MTOMXMLStreamWriter.isOptimized()` to check if XOP/MTOM is enabled at all.
      - The implementation MUST NOT call `XMLStreamWriter.close()`.

      On the other hand, the caller of this method (typically an `OMSourcedElement` instance) must ensure that the following requirements are satisfied:

      - The namespace context information provided by `XMLStreamWriter.getPrefix(String)` and `XMLStreamWriter.getNamespaceContext()` MUST accurately reflect the actual namespace context at the location in the output document where the root element is serialized. Note that this requirement may be relaxed if the caller implements some form of namespace repairing.

      It is assumed that this method consumes the content (i.e. destroys the backing object) unless the data source also implements `OMDataSourceExt` and `OMDataSourceExt.isDestructiveWrite()` returns `false`.

      Parameters:
        `xmlWriter` - destination writer
      Throws:
        `XMLStreamException` - if an exception was thrown by `writer`; implementations should throw unchecked exceptions in all other cases