Package org.apache.axiom.om.impl

## Class MTOMXMLStreamWriter

- java.lang.Object
- - org.apache.axiom.om.impl.MTOMXMLStreamWriter

- All Implemented Interfaces:
    `XMLStreamWriter`

      public abstract class MTOMXMLStreamWriter
      extends Object
      implements XMLStreamWriter

  MTOMXMLStreamWriter is an XML + Attachments stream writer. For the moment this assumes that transport takes the decision of whether to optimize or not by looking at whether the MTOM optimize is enabled and also looking at the OM tree whether it has any optimizable content.

- - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `abstract String` | `getCharSetEncoding()` | Returns the character set encoding scheme.
    `abstract OMOutputFormat` | `getOutputFormat()` | Get the output format used by this writer.
    `abstract OutputStream` | `getOutputStream()` | Get the underlying `OutputStream` for this writer, if available.
    `abstract boolean` | `isOptimized()` | Check if MTOM is enabled.
    `abstract String` | `prepareDataHandler​(DataHandler dataHandler)` | Prepare a `DataHandler` for serialization without using the `DataHandlerWriter` API.

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface javax.xml.stream.XMLStreamWriter

      `close, flush, getNamespaceContext, getPrefix, getProperty, setDefaultNamespace, setNamespaceContext, setPrefix, writeAttribute, writeAttribute, writeAttribute, writeCData, writeCharacters, writeCharacters, writeComment, writeDefaultNamespace, writeDTD, writeEmptyElement, writeEmptyElement, writeEmptyElement, writeEndDocument, writeEndElement, writeEntityRef, writeNamespace, writeProcessingInstruction, writeProcessingInstruction, writeStartDocument, writeStartDocument, writeStartDocument, writeStartElement, writeStartElement, writeStartElement`

- - ### Constructor Detail

    - #### MTOMXMLStreamWriter

          public MTOMXMLStreamWriter()

  - ### Method Detail

    - #### isOptimized

          public abstract boolean isOptimized()

      Check if MTOM is enabled.

      Note that serialization code should use `XMLStreamWriterUtils.writeDataHandler(XMLStreamWriter, DataHandler, String, boolean)` or `XMLStreamWriterUtils.writeDataHandler(XMLStreamWriter, DataHandlerProvider, String, boolean)` to submit any binary content and let this writer decide whether the content should be written as base64 encoded character data or using `xop:Include`. This makes optimization entirely transparent for the caller and there should be no need to check if the writer is producing MTOM. However, in some cases this is not possible, such as when integrating with 3rd party libraries. The serialization code should then use `prepareDataHandler(DataHandler)` so that it can write `xop:Include` elements directly to the stream. In that case, the code may use the `isOptimized()` method check if MTOM is enabled at all.

      Returns:
        `true` if MTOM is enabled, `false` otherwise

    - #### prepareDataHandler

          public abstract String prepareDataHandler​(DataHandler dataHandler)

      Prepare a `DataHandler` for serialization without using the `DataHandlerWriter` API. The method first determines whether the binary data represented by the `DataHandler` should be optimized or inlined. If the data should not be optimized, then the method returns `null` and the caller is expected to use `XMLStreamWriter.writeCharacters(String)` or `XMLStreamWriter.writeCharacters(char[], int, int)` to write the base64 encoded data to the stream. If the data should be optimized, then the method returns a content ID and the caller is expected to generate an `xop:Include` element referring to that content ID.

      This method should only be used to integrate Axiom with third party libraries that support XOP. In all other cases, `XMLStreamWriterUtils.writeDataHandler(XMLStreamWriter, DataHandler, String, boolean)` or `XMLStreamWriterUtils.writeDataHandler(XMLStreamWriter, DataHandlerProvider, String, boolean)` should be used to write base64Binary values and the application code should never generate `xop:Include` elements itself.

      Parameters:
        `dataHandler` - the `DataHandler` that the caller intends to write to the stream
      Returns:
        the content ID that the caller must use in the `xop:Include` element or `null` if the base64 encoded data should not be optimized

    - #### getCharSetEncoding

          public abstract String getCharSetEncoding()

      Returns the character set encoding scheme. If the value of the charSetEncoding is not set then the default will be returned.
      Returns:
        Returns encoding.

    - #### getOutputFormat

          public abstract OMOutputFormat getOutputFormat()

      Get the output format used by this writer.

      The caller should use the returned instance in a read-only way, i.e. he should not modify the settings of the output format. Any attempt to do so will lead to unpredictable results.

      Returns:
        the output format used by this writer

    - #### getOutputStream

          public abstract OutputStream getOutputStream()
                                                throws XMLStreamException

      Get the underlying `OutputStream` for this writer, if available. This method allows a node (perhaps an `OMSourcedElement`) to write its content directly to the byte stream.

      WARNING: This method should be used with extreme care. The caller must be prepared to handle the following issues:

      - The caller must use the right charset encoding when writing to the stream.
      - The caller should avoid writing byte order marks to the stream.
      - The caller must be aware of the fact that a default namespace might have been set in the context where the byte stream is requested. If the XML data written to the stream contains unqualified elements, then the caller must make sure that the default namespace is redeclared as appropriate.
      Returns:
        the underlying byte stream, or `null` if the stream is not accessible
      Throws:
        `XMLStreamException`