org.apache.axiom.util.stax

## Class XMLStreamReaderUtils

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

-     public class XMLStreamReaderUtils
      extends Object

  Contains utility methods to work with `XMLStreamReader` objects, including the extension defined by `DataHandlerReader`. In addition to `DataHandlerReader` support, this class also provides support for the legacy extension mechanism described below.

  ### Legacy XMLStreamReader extensions for optimized base64 handling

  `XMLStreamReader` instances supporting the legacy extension must conform to the following requirements:

  1. `XMLStreamReader.getProperty(String)` must return `Boolean.TRUE` for the property identified by `OMConstants.IS_DATA_HANDLERS_AWARE`, regardless of the current event. The property is assumed to be immutable and its value must not change during the lifetime of the `XMLStreamReader` implementation.

  2. If the `XMLStreamReader` wishes to expose base64 encoded content using a `DataHandler` object, it must do so using a single `XMLStreamConstants.CHARACTERS` event.

     To maintain compatibility with consumers that are unaware of the extensions described here, the implementation should make sure that `XMLStreamReader.getText()`, `XMLStreamReader.getTextStart()`, `XMLStreamReader.getTextLength()`, `XMLStreamReader.getTextCharacters()`, `XMLStreamReader.getTextCharacters(int, char[], int, int)` and `XMLStreamReader.getElementText()` behave as expected for this type of event, i.e. return the base64 representation of the binary content.

  3. `XMLStreamReader.getProperty(String)` must return `Boolean.TRUE` for the property identified by `OMConstants.IS_BINARY` if the current event is a `XMLStreamConstants.CHARACTERS` event representing base64 encoded binary content and for which a `DataHandler` is available. For all other events, the returned value must be `Boolean.FALSE`.

  4. If for a given event, the implementation returned `Boolean.TRUE` for the `OMConstants.IS_BINARY` property, then a call to `XMLStreamReader.getProperty(String)` with argument `OMConstants.DATA_HANDLER` must return the corresponding `DataHandler` object.

     The `OMConstants.DATA_HANDLER` property is undefined for any other type of event. This implies that the consumer of the `XMLStreamReader` must check the `OMConstants.IS_BINARY` property before retrieving the `OMConstants.DATA_HANDLER` property.

  The extension mechanism described here has been deprecated mainly because it doesn't support deferred loading of the binary content.

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static javax.activation.DataHandler` | `getDataHandlerFromElement(javax.xml.stream.XMLStreamReader reader)` Get a `DataHandler` for the binary data encoded in an element.
    `static DataHandlerReader` | `getDataHandlerReader(javax.xml.stream.XMLStreamReader reader)` Get the `DataHandlerReader` extension for a given `XMLStreamReader`, if available.
    `static Reader` | `getElementTextAsStream(javax.xml.stream.XMLStreamReader reader, boolean allowNonTextChildren)` Get the text content of the current element as a `Reader` object.
    `static javax.xml.stream.XMLStreamReader` | `getOriginalXMLStreamReader(javax.xml.stream.XMLStreamReader parser)` Searches the wrapper and delegate classes to find the original `XMLStreamReader`.
    `static Object` | `processGetProperty(DataHandlerReader extension, String propertyName)` Helper method to implement `XMLStreamReader.getProperty(String)`.
    `static void` | `writeTextTo(javax.xml.stream.XMLStreamReader reader, Writer writer)` Get the character data for the current event from the given reader and write it to the given writer.

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

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

- - ### Method Detail

    - #### getDataHandlerReader

          public static DataHandlerReader getDataHandlerReader(javax.xml.stream.XMLStreamReader reader)

      Get the `DataHandlerReader` extension for a given `XMLStreamReader`, if available. If the `XMLStreamReader` only supports the legacy extension (as described above), then this method will return a compatibility wrapper. Note that this wrapper doesn't support deferred loading of the binary content.
      Parameters:
        `reader` - the stream reader to get the `DataHandlerReader` extension from
      Returns:
        the implementation of the extension, or `null` if the `XMLStreamReader` doesn't expose base64 encoded binary content as `DataHandler` objects.

    - #### processGetProperty

          public static Object processGetProperty(DataHandlerReader extension,
                                                  String propertyName)

      Helper method to implement `XMLStreamReader.getProperty(String)`. This method processes the properties defined by `DataHandlerReader.PROPERTY` and the legacy extension mechanism (as described above). It can therefore be used to make a `XMLStreamReader` implementation compatible with code that expects it to implement this legacy extension.
      Parameters:
        `extension` - the reference to the `DataHandlerReader` extension for the `XMLStreamReader` implementation
        `propertyName` - the name of the property, as passed to the `XMLStreamReader.getProperty(String)` method
      Returns:
        the property value as specified by the `DataHandlerReader` or legacy extension; `null` if the property is not specified by any of these two extensions

    - #### getDataHandlerFromElement

          public static javax.activation.DataHandler getDataHandlerFromElement(javax.xml.stream.XMLStreamReader reader)
                                                                        throws javax.xml.stream.XMLStreamException

      Get a `DataHandler` for the binary data encoded in an element. The method supports base64 encoded character data as well as optimized binary data through the `DataHandlerReader` extension.

      Precondition: the reader is on a `XMLStreamConstants.START_ELEMENT`

      Postcondition: the reader is on the corresponding `XMLStreamConstants.END_ELEMENT`

      Parameters:
        `reader` - the stream to read the data from
      Returns:
        the binary data from the element
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### writeTextTo

          public static void writeTextTo(javax.xml.stream.XMLStreamReader reader,
                                         Writer writer)
                                  throws javax.xml.stream.XMLStreamException,
                                         IOException

      Get the character data for the current event from the given reader and write it to the given writer. The method will try to figure out the most efficient way to copy the data without unnecessary buffering or conversions between strings and character arrays.
      Parameters:
        `reader` - the reader to get the character data from
        `writer` - the writer to write the character data to
      Throws:
        `javax.xml.stream.XMLStreamException` - if the underlying XML source is not well-formed
        `IOException` - if an I/O error occurs when writing the character data
        `IllegalStateException` - if this state is not a valid text state.
      See Also:
        `CharacterDataReader`

    - #### getElementTextAsStream

          public static Reader getElementTextAsStream(javax.xml.stream.XMLStreamReader reader,
                                                      boolean allowNonTextChildren)

      Get the text content of the current element as a `Reader` object.
      Parameters:
        `reader` - The XML stream reader to read the element text from. The reader must be positioned on a `XMLStreamConstants.START_ELEMENT` event.
        `allowNonTextChildren` - If set to `true`, non text child nodes are allowed and skipped. If set to `false` only text nodes are allowed and the presence of any other type of child node will trigger an exception.
      Returns:
        The reader from which the element text can be read. After the reader has reported the end of the stream, the XML stream reader will be positioned on the `XMLStreamConstants.END_ELEMENT` event corresponding to the initial `XMLStreamConstants.START_ELEMENT` event. Calling `Reader.close()` on the returned reader has no effect. Any parser exception will be reported by the reader using `XMLStreamIOException`.
      Throws:
        `IllegalStateException` - if the XML stream reader is not positioned on a `XMLStreamConstants.START_ELEMENT` event

    - #### getOriginalXMLStreamReader

          public static javax.xml.stream.XMLStreamReader getOriginalXMLStreamReader(javax.xml.stream.XMLStreamReader parser)

      Searches the wrapper and delegate classes to find the original `XMLStreamReader`. This method should only be used when a consumer of Axiom really needs to access the original stream reader.
      Parameters:
        `parser` - XMLStreamReader used by Axiom
      Returns:
        original parser

Copyright © The Apache Software Foundation. All Rights Reserved.