org.apache.axiom.om.impl

## Class MTOMXMLStreamWriter

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

- All Implemented Interfaces:
    javax.xml.stream.XMLStreamWriter

      public class MTOMXMLStreamWriter
      extends Object
      implements javax.xml.stream.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 and Description
    `MTOMXMLStreamWriter(OutputStream outStream, OMOutputFormat format)`
    `MTOMXMLStreamWriter(OutputStream outStream, OMOutputFormat format, boolean preserveAttachments)` Creates a new MTOMXMLStreamWriter with specified encoding.
    `MTOMXMLStreamWriter(javax.xml.stream.XMLStreamWriter xmlWriter)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()`
    `void` | `flush()` Flush is overridden to trigger the attachment serialization
    `String` | `getCharSetEncoding()` Returns the character set encoding scheme.
    `String` | `getContentType()`
    `String` | `getMimeBoundary()`
    `NamespaceContext` | `getNamespaceContext()`
    `String` | `getNextContentId()`
    `OMOutputFormat` | `getOutputFormat()` Get the output format used by this writer.
    `OutputStream` | `getOutputStream()` Get the underlying `OutputStream` for this writer, if available.
    `String` | `getPrefix(String string)`
    `Object` | `getProperty(String string)`
    `String` | `getRootContentId()`
    `javax.xml.stream.XMLStreamWriter` | `getXmlStreamWriter()`
    `String` | `getXmlVersion()`
    `boolean` | `isIgnoreXMLDeclaration()`
    `boolean` | `isOptimized()` Check if MTOM is enabled.
    `boolean` | `isOptimizedThreshold(OMText node)` Deprecated. 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`. If this is not possible, then `prepareDataHandler(DataHandler)` should be used. All the aforementioned methods take into account the settings defined in `OMOutputFormat` to determine whether the binary data should be optimized or not. Therefore, there is not need for this method anymore.
    `String` | `prepareDataHandler(javax.activation.DataHandler dataHandler)` Prepare a `DataHandler` for serialization without using the `DataHandlerWriter` API.
    `XMLStreamWriterFilter` | `removeFilter()`
    `void` | `setCharSetEncoding(String charSetEncoding)`
    `void` | `setDefaultNamespace(String string)`
    `void` | `setDoOptimize(boolean b)`
    `void` | `setFilter(XMLStreamWriterFilter filter)`
    `void` | `setIgnoreXMLDeclaration(boolean ignoreXMLDeclaration)`
    `void` | `setNamespaceContext(NamespaceContext namespaceContext)`
    `void` | `setOutputFormat(OMOutputFormat format)`
    `void` | `setPrefix(String string, String string1)`
    `void` | `setSoap11(boolean b)`
    `void` | `setXmlStreamWriter(javax.xml.stream.XMLStreamWriter xmlWriter)`
    `void` | `setXmlVersion(String xmlVersion)`
    `void` | `writeAttribute(String string, String string1)`
    `void` | `writeAttribute(String string, String string1, String string2)`
    `void` | `writeAttribute(String string, String string1, String string2, String string3)`
    `void` | `writeCData(String string)`
    `void` | `writeCharacters(char[] chars, int i, int i1)`
    `void` | `writeCharacters(String string)`
    `void` | `writeComment(String string)`
    `void` | `writeDefaultNamespace(String string)`
    `void` | `writeDTD(String string)`
    `void` | `writeEmptyElement(String string)`
    `void` | `writeEmptyElement(String string, String string1)`
    `void` | `writeEmptyElement(String string, String string1, String string2)`
    `void` | `writeEndDocument()`
    `void` | `writeEndElement()`
    `void` | `writeEntityRef(String string)`
    `void` | `writeNamespace(String string, String string1)`
    `void` | `writeOptimized(OMText node)` Deprecated. 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`. If this is not possible, then `prepareDataHandler(DataHandler)` should be used.
    `void` | `writeProcessingInstruction(String string)`
    `void` | `writeProcessingInstruction(String string, String string1)`
    `void` | `writeStartDocument()`
    `void` | `writeStartDocument(String string)`
    `void` | `writeStartDocument(String string, String string1)`
    `void` | `writeStartElement(String string)`
    `void` | `writeStartElement(String string, String string1)`
    `void` | `writeStartElement(String string, String string1, String string2)`

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

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

- - ### Constructor Detail

    - #### MTOMXMLStreamWriter

          public MTOMXMLStreamWriter(javax.xml.stream.XMLStreamWriter xmlWriter)

    - #### MTOMXMLStreamWriter

          public MTOMXMLStreamWriter(OutputStream outStream,
                                     OMOutputFormat format)
                              throws javax.xml.stream.XMLStreamException,
                                     javax.xml.stream.FactoryConfigurationError

      Throws:
        `javax.xml.stream.XMLStreamException`
        `javax.xml.stream.FactoryConfigurationError`

    - #### MTOMXMLStreamWriter

          public MTOMXMLStreamWriter(OutputStream outStream,
                                     OMOutputFormat format,
                                     boolean preserveAttachments)
                              throws javax.xml.stream.XMLStreamException,
                                     javax.xml.stream.FactoryConfigurationError

      Creates a new MTOMXMLStreamWriter with specified encoding.
      Parameters:
        `outStream` -
        `format` -
        `preserveAttachments` - specifies whether attachments must be preserved or can be consumed (i.e. streamed) during serialization; if set to `false` then `DataHandlerExt.readOnce()` or an equivalent method may be used to get the data for an attachment
      Throws:
        `javax.xml.stream.XMLStreamException`
        `javax.xml.stream.FactoryConfigurationError`
      See Also:
        `OMOutputFormat.DEFAULT_CHAR_SET_ENCODING`

  - ### Method Detail

    - #### writeStartElement

          public void writeStartElement(String string)
                                 throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeStartElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeStartElement

          public void writeStartElement(String string,
                                        String string1)
                                 throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeStartElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeStartElement

          public void writeStartElement(String string,
                                        String string1,
                                        String string2)
                                 throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeStartElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEmptyElement

          public void writeEmptyElement(String string,
                                        String string1)
                                 throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeEmptyElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEmptyElement

          public void writeEmptyElement(String string,
                                        String string1,
                                        String string2)
                                 throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeEmptyElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEmptyElement

          public void writeEmptyElement(String string)
                                 throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeEmptyElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEndElement

          public void writeEndElement()
                               throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeEndElement` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEndDocument

          public void writeEndDocument()
                                throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeEndDocument` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### close

          public void close()
                     throws javax.xml.stream.XMLStreamException

      Specified by:
        `close` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### flush

          public void flush()
                     throws javax.xml.stream.XMLStreamException

      Flush is overridden to trigger the attachment serialization
      Specified by:
        `flush` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeAttribute

          public void writeAttribute(String string,
                                     String string1)
                              throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeAttribute` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeAttribute

          public void writeAttribute(String string,
                                     String string1,
                                     String string2,
                                     String string3)
                              throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeAttribute` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeAttribute

          public void writeAttribute(String string,
                                     String string1,
                                     String string2)
                              throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeAttribute` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeNamespace

          public void writeNamespace(String string,
                                     String string1)
                              throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeNamespace` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeDefaultNamespace

          public void writeDefaultNamespace(String string)
                                     throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeDefaultNamespace` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeComment

          public void writeComment(String string)
                            throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeComment` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeProcessingInstruction

          public void writeProcessingInstruction(String string)
                                          throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeProcessingInstruction` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeProcessingInstruction

          public void writeProcessingInstruction(String string,
                                                 String string1)
                                          throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeProcessingInstruction` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeCData

          public void writeCData(String string)
                          throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeCData` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeDTD

          public void writeDTD(String string)
                        throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeDTD` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeEntityRef

          public void writeEntityRef(String string)
                              throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeEntityRef` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeStartDocument

          public void writeStartDocument()
                                  throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeStartDocument` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeStartDocument

          public void writeStartDocument(String string)
                                  throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeStartDocument` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeStartDocument

          public void writeStartDocument(String string,
                                         String string1)
                                  throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeStartDocument` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeCharacters

          public void writeCharacters(String string)
                               throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeCharacters` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeCharacters

          public void writeCharacters(char[] chars,
                                      int i,
                                      int i1)
                               throws javax.xml.stream.XMLStreamException

      Specified by:
        `writeCharacters` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### getPrefix

          public String getPrefix(String string)
                           throws javax.xml.stream.XMLStreamException

      Specified by:
        `getPrefix` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### setPrefix

          public void setPrefix(String string,
                                String string1)
                         throws javax.xml.stream.XMLStreamException

      Specified by:
        `setPrefix` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### setDefaultNamespace

          public void setDefaultNamespace(String string)
                                   throws javax.xml.stream.XMLStreamException

      Specified by:
        `setDefaultNamespace` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### setNamespaceContext

          public void setNamespaceContext(NamespaceContext namespaceContext)
                                   throws javax.xml.stream.XMLStreamException

      Specified by:
        `setNamespaceContext` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### getNamespaceContext

          public NamespaceContext getNamespaceContext()

      Specified by:
        `getNamespaceContext` in interface `javax.xml.stream.XMLStreamWriter`

    - #### getProperty

          public Object getProperty(String string)
                             throws IllegalArgumentException

      Specified by:
        `getProperty` in interface `javax.xml.stream.XMLStreamWriter`
      Throws:
        `IllegalArgumentException`

    - #### isOptimized

          public 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

    - #### getContentType

          public String getContentType()

    - #### writeOptimized

          public void writeOptimized(OMText node)

      Deprecated. 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`. If this is not possible, then `prepareDataHandler(DataHandler)` should be used.

    - #### isOptimizedThreshold

          public boolean isOptimizedThreshold(OMText node)

      Deprecated. 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`. If this is not possible, then `prepareDataHandler(DataHandler)` should be used. All the aforementioned methods take into account the settings defined in `OMOutputFormat` to determine whether the binary data should be optimized or not. Therefore, there is not need for this method anymore.

    - #### prepareDataHandler

          public String prepareDataHandler(javax.activation.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 `writeCharacters(String)` or `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

    - #### setXmlStreamWriter

          public void setXmlStreamWriter(javax.xml.stream.XMLStreamWriter xmlWriter)

    - #### getXmlStreamWriter

          public javax.xml.stream.XMLStreamWriter getXmlStreamWriter()

    - #### getMimeBoundary

          public String getMimeBoundary()

    - #### getRootContentId

          public String getRootContentId()

    - #### getNextContentId

          public String getNextContentId()

    - #### getCharSetEncoding

          public 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.

    - #### setCharSetEncoding

          public void setCharSetEncoding(String charSetEncoding)

    - #### getXmlVersion

          public String getXmlVersion()

    - #### setXmlVersion

          public void setXmlVersion(String xmlVersion)

    - #### setSoap11

          public void setSoap11(boolean b)

    - #### isIgnoreXMLDeclaration

          public boolean isIgnoreXMLDeclaration()

    - #### setIgnoreXMLDeclaration

          public void setIgnoreXMLDeclaration(boolean ignoreXMLDeclaration)

    - #### setDoOptimize

          public void setDoOptimize(boolean b)

    - #### getOutputFormat

          public 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

    - #### setOutputFormat

          public void setOutputFormat(OMOutputFormat format)

    - #### getOutputStream

          public OutputStream getOutputStream()
                                       throws javax.xml.stream.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:
        `javax.xml.stream.XMLStreamException`

    - #### setFilter

          public void setFilter(XMLStreamWriterFilter filter)

    - #### removeFilter

          public XMLStreamWriterFilter removeFilter()

Copyright © The Apache Software Foundation. All Rights Reserved.