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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Blob`
  `getBlobFromElement(XMLStreamReader reader)`
  Get a `Blob` for the binary data encoded in an element.
  `static BlobReader`
  `getBlobReader(XMLStreamReader reader)`
  Get the `BlobReader` 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(BlobReader 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 Details

  - ### getBlobReader

    public static BlobReader getBlobReader(XMLStreamReader reader)
    Get the `BlobReader` extension for a given `XMLStreamReader`, if available.
    Parameters:
      `reader` - the stream reader to get the `BlobReader` extension from
    Returns:
      the implementation of the extension, or `null` if the `XMLStreamReader` doesn't expose base64 encoded binary content as `Blob` objects.

  - ### processGetProperty

    public static Object processGetProperty(BlobReader extension, String propertyName)
    Helper method to implement `XMLStreamReader.getProperty(String)`. This method processes the property defined by `BlobReader.PROPERTY`.
    Parameters:
      `extension` - the reference to the `BlobReader` 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 `BlobReader` extension; `null` if the property doesn't match

  - ### getBlobFromElement

    public static Blob getBlobFromElement(XMLStreamReader reader) throws XMLStreamException
    Get a `Blob` for the binary data encoded in an element. The method supports base64 encoded character data as well as optimized binary data through the `BlobReader` 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