StaxUtils (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.util.xml

## Class StaxUtils

- java.lang.Object
- - org.springframework.util.xml.StaxUtils

-     public abstract class StaxUtils
      extends Object

  Convenience methods for working with the StAX API.

  In particular, methods for using StAX (`javax.xml.stream`) in combination with the TrAX API (`javax.xml.transform`), and converting StAX readers/writers into SAX readers/handlers and vice-versa.

  Since:
    3.0
  Author:
    Arjen Poutsma, Juergen Hoeller

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `StaxUtils()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static ContentHandler` | `createContentHandler(XMLEventWriter eventWriter)` Create a SAX `ContentHandler` that writes events to the given StAX `XMLEventWriter`.
    `static ContentHandler` | `createContentHandler(XMLStreamWriter streamWriter)` Create a SAX `ContentHandler` that writes to the given StAX `XMLStreamWriter`.
    `static Result` | `createCustomStaxResult(XMLEventWriter eventWriter)` Create a custom, non-JAXP 1.4 StAX `Result` for the given `XMLEventWriter`.
    `static Result` | `createCustomStaxResult(XMLStreamWriter streamWriter)` Create a custom, non-JAXP 1.4 StAX `Result` for the given `XMLStreamWriter`.
    `static Source` | `createCustomStaxSource(XMLEventReader eventReader)` Create a custom, non-JAXP 1.4 StAX `Source` for the given `XMLEventReader`.
    `static Source` | `createCustomStaxSource(XMLStreamReader streamReader)` Create a custom, non-JAXP 1.4 StAX `Source` for the given `XMLStreamReader`.
    `static XMLStreamReader` | `createEventStreamReader(XMLEventReader eventReader)` Return a `XMLStreamReader` that reads from a `XMLEventReader`.
    `static XMLStreamWriter` | `createEventStreamWriter(XMLEventWriter eventWriter)` Return a `XMLStreamWriter` that writes to a `XMLEventWriter`.
    `static XMLStreamWriter` | `createEventStreamWriter(XMLEventWriter eventWriter, XMLEventFactory eventFactory)` Return a `XMLStreamWriter` that writes to a `XMLEventWriter`.
    `static Result` | `createStaxResult(XMLEventWriter eventWriter)` Create a StAX `Result` for the given `XMLEventWriter`.
    `static Result` | `createStaxResult(XMLStreamWriter streamWriter)` Create a StAX `Result` for the given `XMLStreamWriter`.
    `static Source` | `createStaxSource(XMLEventReader eventReader)` Create a StAX `Source` for the given `XMLEventReader`.
    `static Source` | `createStaxSource(XMLStreamReader streamReader)` Create a StAX `Source` for the given `XMLStreamReader`.
    `static XMLReader` | `createXMLReader(XMLEventReader eventReader)` Create a SAX `XMLReader` that reads from the given StAX `XMLEventReader`.
    `static XMLReader` | `createXMLReader(XMLStreamReader streamReader)` Create a SAX `XMLReader` that reads from the given StAX `XMLStreamReader`.
    `static XMLEventReader` | `getXMLEventReader(Source source)` Return the `XMLEventReader` for the given StAX Source.
    `static XMLEventWriter` | `getXMLEventWriter(Result result)` Return the `XMLEventWriter` for the given StAX Result.
    `static XMLStreamReader` | `getXMLStreamReader(Source source)` Return the `XMLStreamReader` for the given StAX Source.
    `static XMLStreamWriter` | `getXMLStreamWriter(Result result)` Return the `XMLStreamWriter` for the given StAX Result.
    `static boolean` | `isStaxResult(Result result)` Indicate whether the given `Result` is a StAX Result.
    `static boolean` | `isStaxSource(Source source)` Indicate whether the given `Source` is a StAX Source.

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

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

- - ### Constructor Detail

    - #### StaxUtils

          public StaxUtils()

  - ### Method Detail

    - #### createCustomStaxSource

          public static Source createCustomStaxSource(XMLStreamReader streamReader)

      Create a custom, non-JAXP 1.4 StAX `Source` for the given `XMLStreamReader`.
      Parameters:
        `streamReader` - the StAX stream reader
      Returns:
        a source wrapping the `streamReader`

    - #### createStaxSource

          public static Source createStaxSource(XMLStreamReader streamReader)

      Create a StAX `Source` for the given `XMLStreamReader`.

      If JAXP 1.4 is available, this method returns a `StAXSource`; otherwise it returns a custom StAX Source.

      Parameters:
        `streamReader` - the StAX stream reader
      Returns:
        a source wrapping the `streamReader`
      See Also:
        `createCustomStaxSource(XMLStreamReader)`

    - #### createCustomStaxSource

          public static Source createCustomStaxSource(XMLEventReader eventReader)

      Create a custom, non-JAXP 1.4 StAX `Source` for the given `XMLEventReader`.
      Parameters:
        `eventReader` - the StAX event reader
      Returns:
        a source wrapping the `eventReader`

    - #### createStaxSource

          public static Source createStaxSource(XMLEventReader eventReader)
                                         throws XMLStreamException

      Create a StAX `Source` for the given `XMLEventReader`.

      If JAXP 1.4 is available, this method returns a `StAXSource`; otherwise it returns a custom StAX Source.

      Parameters:
        `eventReader` - the StAX event reader
      Returns:
        a source wrapping the `eventReader`
      Throws:
        `XMLStreamException` - in case of StAX errors
      See Also:
        `createCustomStaxSource(XMLEventReader)`

    - #### isStaxSource

          public static boolean isStaxSource(Source source)

      Indicate whether the given `Source` is a StAX Source.
      Returns:
        `true` if `source` is a custom StAX source or JAXP 1.4 `StAXSource`; `false` otherwise.

    - #### createCustomStaxResult

          public static Result createCustomStaxResult(XMLStreamWriter streamWriter)

      Create a custom, non-JAXP 1.4 StAX `Result` for the given `XMLStreamWriter`.
      Parameters:
        `streamWriter` - the StAX stream writer
      Returns:
        a source wrapping the `streamWriter`

    - #### createStaxResult

          public static Result createStaxResult(XMLStreamWriter streamWriter)

      Create a StAX `Result` for the given `XMLStreamWriter`.

      If JAXP 1.4 is available, this method returns a `StAXResult`; otherwise it returns a custom StAX Result.

      Parameters:
        `streamWriter` - the StAX stream writer
      Returns:
        a result wrapping the `streamWriter`
      See Also:
        `createCustomStaxResult(XMLStreamWriter)`

    - #### createCustomStaxResult

          public static Result createCustomStaxResult(XMLEventWriter eventWriter)

      Create a custom, non-JAXP 1.4 StAX `Result` for the given `XMLEventWriter`.
      Parameters:
        `eventWriter` - the StAX event writer
      Returns:
        a source wrapping the `eventWriter`

    - #### createStaxResult

          public static Result createStaxResult(XMLEventWriter eventWriter)
                                         throws XMLStreamException

      Create a StAX `Result` for the given `XMLEventWriter`.

      If JAXP 1.4 is available, this method returns a `StAXResult`; otherwise it returns a custom StAX Result.

      Parameters:
        `eventWriter` - the StAX event writer
      Returns:
        a result wrapping `streamReader`
      Throws:
        `XMLStreamException` - in case of StAX errors
      See Also:
        `createCustomStaxResult(XMLEventWriter)`

    - #### isStaxResult

          public static boolean isStaxResult(Result result)

      Indicate whether the given `Result` is a StAX Result.
      Returns:
        `true` if `result` is a custom Stax Result or JAXP 1.4 `StAXResult`; `false` otherwise.

    - #### getXMLStreamReader

          public static XMLStreamReader getXMLStreamReader(Source source)

      Return the `XMLStreamReader` for the given StAX Source.
      Parameters:
        `source` - a custom StAX Source or JAXP 1.4 `StAXSource`
      Returns:
        the `XMLStreamReader`
      Throws:
        `IllegalArgumentException` - if `source` is neither a custom StAX Source nor JAXP 1.4 `StAXSource`

    - #### getXMLEventReader

          public static XMLEventReader getXMLEventReader(Source source)

      Return the `XMLEventReader` for the given StAX Source.
      Parameters:
        `source` - a custom StAX Source or JAXP 1.4 `StAXSource`
      Returns:
        the `XMLEventReader`
      Throws:
        `IllegalArgumentException` - if `source` is neither a custom StAX Source nor a JAXP 1.4 `StAXSource`

    - #### getXMLStreamWriter

          public static XMLStreamWriter getXMLStreamWriter(Result result)

      Return the `XMLStreamWriter` for the given StAX Result.
      Parameters:
        `result` - a custom StAX Result or JAXP 1.4 `StAXResult`
      Returns:
        the `XMLStreamReader`
      Throws:
        `IllegalArgumentException` - if `source` is neither a custom StAX Result nor a JAXP 1.4 `StAXResult`

    - #### getXMLEventWriter

          public static XMLEventWriter getXMLEventWriter(Result result)

      Return the `XMLEventWriter` for the given StAX Result.
      Parameters:
        `result` - a custom StAX Result or JAXP 1.4 `StAXResult`
      Returns:
        the `XMLStreamReader`
      Throws:
        `IllegalArgumentException` - if `source` is neither a custom StAX Result nor a JAXP 1.4 `StAXResult`

    - #### createContentHandler

          public static ContentHandler createContentHandler(XMLStreamWriter streamWriter)

      Create a SAX `ContentHandler` that writes to the given StAX `XMLStreamWriter`.
      Parameters:
        `streamWriter` - the StAX stream writer
      Returns:
        a content handler writing to the `streamWriter`

    - #### createContentHandler

          public static ContentHandler createContentHandler(XMLEventWriter eventWriter)

      Create a SAX `ContentHandler` that writes events to the given StAX `XMLEventWriter`.
      Parameters:
        `eventWriter` - the StAX event writer
      Returns:
        a content handler writing to the `eventWriter`

    - #### createXMLReader

          public static XMLReader createXMLReader(XMLStreamReader streamReader)

      Create a SAX `XMLReader` that reads from the given StAX `XMLStreamReader`.
      Parameters:
        `streamReader` - the StAX stream reader
      Returns:
        a XMLReader reading from the `streamWriter`

    - #### createXMLReader

          public static XMLReader createXMLReader(XMLEventReader eventReader)

      Create a SAX `XMLReader` that reads from the given StAX `XMLEventReader`.
      Parameters:
        `eventReader` - the StAX event reader
      Returns:
        a XMLReader reading from the `eventWriter`

    - #### createEventStreamReader

          public static XMLStreamReader createEventStreamReader(XMLEventReader eventReader)
                                                         throws XMLStreamException

      Return a `XMLStreamReader` that reads from a `XMLEventReader`. Useful, because the StAX `XMLInputFactory` allows one to create a event reader from a stream reader, but not vice-versa.
      Returns:
        a stream reader that reads from an event reader
      Throws:
        `XMLStreamException`

    - #### createEventStreamWriter

          public static XMLStreamWriter createEventStreamWriter(XMLEventWriter eventWriter)

      Return a `XMLStreamWriter` that writes to a `XMLEventWriter`.
      Returns:
        a stream writer that writes to an event writer
      Since:
        3.2

    - #### createEventStreamWriter

          public static XMLStreamWriter createEventStreamWriter(XMLEventWriter eventWriter,
                                                XMLEventFactory eventFactory)

      Return a `XMLStreamWriter` that writes to a `XMLEventWriter`.
      Returns:
        a stream writer that writes to an event writer
      Since:
        3.0.5