org.apache.axiom.util.stax

## Class XMLStreamWriterUtils

- java.lang.Object
- - org.apache.axiom.util.stax.XMLStreamWriterUtils

-     public class XMLStreamWriterUtils
      extends Object

  Contains utility methods to work with `XMLStreamWriter` objects.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `XMLStreamWriterUtils()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static DataHandlerWriter` | `getDataHandlerWriter(javax.xml.stream.XMLStreamWriter writer)` Get the `DataHandlerWriter` extension for a given `XMLStreamWriter`.
    `static void` | `writeBase64(javax.xml.stream.XMLStreamWriter writer, javax.activation.DataHandler dh)` Write base64 encoded data to a stream writer.
    `static void` | `writeDataHandler(javax.xml.stream.XMLStreamWriter writer, DataHandlerProvider dataHandlerProvider, String contentID, boolean optimize)` Write binary content to the stream.
    `static void` | `writeDataHandler(javax.xml.stream.XMLStreamWriter writer, javax.activation.DataHandler dataHandler, String contentID, boolean optimize)` Write binary content to the stream.
    `static void` | `writeDTD(javax.xml.stream.XMLStreamWriter writer, String rootName, String publicId, String systemId, String internalSubset)` Prepare the `DOCTYPE` declaration using the provided information and output it using `XMLStreamWriter.writeDTD(String)`.

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

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

- - ### Constructor Detail

    - #### XMLStreamWriterUtils

          public XMLStreamWriterUtils()

  - ### Method Detail

    - #### writeBase64

          public static void writeBase64(javax.xml.stream.XMLStreamWriter writer,
                                         javax.activation.DataHandler dh)
                                  throws IOException,
                                         javax.xml.stream.XMLStreamException

      Write base64 encoded data to a stream writer. This will result in one or more `XMLStreamConstants.CHARACTERS` events to be written to the stream (or zero events if the data handler produces an empty byte sequence), i.e. the data is streamed from the data handler directly to the stream writer. Since no in-memory base64 representation of the entire binary data is built, this method is suitable for very large amounts of data.

      Note that this method will always serialize the data as base64 encoded character data. Serialization code should prefer using `writeDataHandler(XMLStreamWriter, DataHandler, String, boolean)` or `writeDataHandler(XMLStreamWriter, DataHandlerProvider, String, boolean)` to enable optimization (if supported by the `XMLStreamWriter`).

      Parameters:
        `writer` - the stream writer to write the data to
        `dh` - the data handler containing the data to encode
      Throws:
        `IOException` - if an error occurs when reading the data from the data handler
        `javax.xml.stream.XMLStreamException` - if an error occurs when writing the base64 encoded data to the stream

    - #### getDataHandlerWriter

          public static DataHandlerWriter getDataHandlerWriter(javax.xml.stream.XMLStreamWriter writer)

      Get the `DataHandlerWriter` extension for a given `XMLStreamWriter`. If the writer exposes the extension, a reference to the extension interface implementation is returned. If the writer doesn't expose the extension, this method returns an instance of the extension interface that emulates the extension (by writing the binary data as base64 character data to the stream).
      Parameters:
        `writer` - the stream for which the method should return the `DataHandlerWriter` extension
      Returns:
        a reference to the extension interface exposed by the writer or an implementation the emulates the extension; the return value is never `null`

    - #### writeDataHandler

          public static void writeDataHandler(javax.xml.stream.XMLStreamWriter writer,
                                              javax.activation.DataHandler dataHandler,
                                              String contentID,
                                              boolean optimize)
                                       throws IOException,
                                              javax.xml.stream.XMLStreamException

      Write binary content to the stream. Depending on the supplied `XMLStreamWriter`, the content will be written as base64 encoded character data or using an optimization scheme such as XOP/MTOM. The method attempts to submit the binary content using the `DataHandlerWriter` extension. If the writer doesn't expose this extension, the method will fall back to `writeBase64(XMLStreamWriter, DataHandler)`.

      Please refer to the documentation of `DataHandlerWriter` for a more detailed description of the semantics of the different arguments.

      Parameters:
        `writer` - the stream writer to write the data to
        `dataHandler` - the binary content to write
        `contentID` - an existing content ID for the binary data
        `optimize` - indicates whether the content is eligible for optimization
      Throws:
        `IOException` - if an error occurs while reading from the data handler
        `javax.xml.stream.XMLStreamException` - if an error occurs while writing to the underlying stream

    - #### writeDataHandler

          public static void writeDataHandler(javax.xml.stream.XMLStreamWriter writer,
                                              DataHandlerProvider dataHandlerProvider,
                                              String contentID,
                                              boolean optimize)
                                       throws IOException,
                                              javax.xml.stream.XMLStreamException

      Write binary content to the stream. This method is similar to `writeDataHandler(XMLStreamWriter, DataHandler, String, boolean)`, but supports deferred loading of the data handler.
      Parameters:
        `writer` - the stream writer to write the data to
        `dataHandlerProvider` - the binary content to write
        `contentID` - an existing content ID for the binary data
        `optimize` - indicates whether the content is eligible for optimization
      Throws:
        `IOException` - if an error occurs while reading from the data handler
        `javax.xml.stream.XMLStreamException` - if an error occurs while writing to the underlying stream

    - #### writeDTD

          public static void writeDTD(javax.xml.stream.XMLStreamWriter writer,
                                      String rootName,
                                      String publicId,
                                      String systemId,
                                      String internalSubset)
                               throws javax.xml.stream.XMLStreamException

      Prepare the `DOCTYPE` declaration using the provided information and output it using `XMLStreamWriter.writeDTD(String)`.
      Parameters:
        `writer` - the stream writer to write the `DOCTYPE` declaration to
        `rootName` - the root name, i.e. the name immediately following the `DOCTYPE` keyword
        `publicId` - the public ID of the external subset, or `null` if there is no external subset or no public ID has been specified for the external subset
        `systemId` - the system ID of the external subset, or `null` if there is no external subset
        `internalSubset` - the internal subset, or `null` if there is none
      Throws:
        `javax.xml.stream.XMLStreamException` - if an error occurs while writing to the stream

Copyright © The Apache Software Foundation. All Rights Reserved.