Package 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`.

- - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static DataHandler` | `getDataHandlerFromElement​(XMLStreamReader reader)` | Get a `DataHandler` for the binary data encoded in an element.
    `static DataHandlerReader` | `getDataHandlerReader​(XMLStreamReader reader)` | Get the `DataHandlerReader` extension for a given `XMLStreamReader`, if available.
    `static Reader` | `getElementTextAsStream​(XMLStreamReader reader, boolean allowNonTextChildren)` | Get the text content of the current element as a `Reader` object.
    `static XMLStreamReader` | `getOriginalXMLStreamReader​(XMLStreamReader parser)` | Deprecated. As of version 1.3.0, Axiom no longer permits access to the original stream reader.
    `static Object` | `processGetProperty​(DataHandlerReader extension, String propertyName)` | Helper method to implement `XMLStreamReader.getProperty(String)`.
    `static void` | `writeTextTo​(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​(XMLStreamReader reader)

      Get the `DataHandlerReader` extension for a given `XMLStreamReader`, if available.
      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 property defined by `DataHandlerReader.PROPERTY`.
      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` extension; `null` if the property doesn't match

    - #### getDataHandlerFromElement

          public static DataHandler getDataHandlerFromElement​(XMLStreamReader reader)
                                                       throws 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:
        `XMLStreamException`

    - #### writeTextTo

          public static void writeTextTo​(XMLStreamReader reader,
                                         Writer writer)
                                  throws 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:
        `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​(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 XMLStreamReader getOriginalXMLStreamReader​(XMLStreamReader parser)

      Deprecated.
      As of version 1.3.0, Axiom no longer permits access to the original stream reader.
      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