org.apache.axiom.ext.stax.datahandler

## Interface DataHandlerWriter

- All Known Implementing Classes:
    XOPEncodingStreamWriter

      public interface DataHandlerWriter

  Extension interface for `XMLStreamWriter` implementations that can receive base64 encoded binary content as `DataHandler` objects. A stream writer implementing this extension may write the binary data as base64 encoded character data or using some optimization such as XOP/MTOM.

  All the requirements specified in `org.apache.axiom.ext.stax` apply to this extension interface. In particular, a consumer MUST use `XMLStreamWriter.getProperty(String)` with the property name defined by `PROPERTY` to get a reference to this extension interface.

  The interface defines two methods to write binary content, one that takes a `DataHandler` argument and one with a `DataHandlerProvider` argument. The first should be used when the content is immediately available, while the second supports deferred loading of the data handler. The meaning of the `contentID` and `optimize` arguments is the same for both methods:

  `contentID`
    A content ID of the binary content, if available. The semantics of this argument are similar to those defined for the return value of the `DataHandlerReader.getContentID()` method:
    - This argument should only be set if a content ID has been used previously in an interaction with another component or system. The caller SHOULD NOT generate a new content ID solely for the purpose of invoking the extension.
    - The argument must be a raw content ID.
    - The implementation MUST NOT make any assumption about the uniqueness or validity of the content ID. It MAY ignore the supplied value.
  `optimize`
    Specifies if binary content is eligible for optimization (e.g. using XOP) or if it should be serialized as base64. This is only an indication and the implementation MAY choose to override this value or ignore it entirely.
  Instead of interacting directly with this extension interface, the consumer may use the `XMLStreamWriterUtils.writeDataHandler(javax.xml.stream.XMLStreamWriter, DataHandler, String, boolean)` or `XMLStreamWriterUtils.writeDataHandler(javax.xml.stream.XMLStreamWriter, DataHandlerProvider, String, boolean)` utility methods. These methods make the processing of binary data entirely transparent for the caller.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `PROPERTY` The name of the property used to look up this extension interface from a `XMLStreamWriter` implementation.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `writeDataHandler(DataHandlerProvider dataHandlerProvider, String contentID, boolean optimize)` Write binary content to the stream.
    `void` | `writeDataHandler(javax.activation.DataHandler dataHandler, String contentID, boolean optimize)` Write binary content to the stream.

- - ### Field Detail

    - #### PROPERTY

          static final String PROPERTY

      The name of the property used to look up this extension interface from a `XMLStreamWriter` implementation.

  - ### Method Detail

    - #### writeDataHandler

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

      Write binary content to the stream. The implementation may choose to write the data as base64 encoded character data or using an optimization protocol such as XOP/MTOM.
      Parameters:
        `dataHandler` - the binary content to write
        `contentID` - an existing content ID for the binary data (see above)
        `optimize` - indicates whether the content is eligible for optimization (see above)
      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

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

      Write binary content to the stream. This method allows the implementation to defer loading of the content. More precisely, if the implementation decides to use an optimization scheme such as XOP, then the content will not be written immediately to the underlying stream, but only after the XML infoset is complete. If the caller uses this method, the implementation can defer the actual loading of the binary content.
      Parameters:
        `dataHandlerProvider` - the binary content to write
        `contentID` - an existing content ID for the binary data (see above)
        `optimize` - indicates whether the content is eligible for optimization (see above)
      Throws:
        `IOException` - If an error occurs while reading from the data handler. Since the implementation is free to override the supplied `optimize` argument, it may attempt to load the binary data immediately. Because this operation may fail, the method must declare this exception.
        `javax.xml.stream.XMLStreamException` - if an error occurs while writing to the underlying stream

Copyright © The Apache Software Foundation. All Rights Reserved.