Package org.apache.axiom.om.util

## Class StAXUtils

- java.lang.Object
- - org.apache.axiom.om.util.StAXUtils

-     public class StAXUtils
      extends Object

  Utility class containing StAX related methods.

  This class defines a set of methods to get `XMLStreamReader` and `XMLStreamWriter` instances. This class caches the corresponding factories, i.e. `XMLInputFactory` and `XMLOutputFactory` objects.

  Default properties for these factories can be specified using `XMLInputFactory.properties` and `XMLOutputFactory.properties` files. These files are loaded using the class loader that loaded the `StAXUtils` class. Properties with boolean, integer and string values are supported. Both standard StAX properties and implementation specific properties can be specified. This feature should be used with care since changing some properties to non default values will break Axiom. Good candidates for `XMLInputFactory.properties` are:

  `javax.xml.stream.isCoalescing`
    Requires the processor to coalesce adjacent character data (text nodes and CDATA sections). This property also controls whether CDATA sections are reported or not.
  `com.ctc.wstx.inputBufferLength`
    Size of input buffer (in chars), to use for reading XML content from input stream/reader. This property is Woodstox specific.
  `com.ctc.wstx.minTextSegment`
    Property to specify shortest non-complete text segment (part of CDATA section or text content) that the parser is allowed to return, if not required to coalesce text. This property is Woodstox specific.

  Good candidates for `XMLOutputFactory.properties` are:

  `com.ctc.wstx.outputEscapeCr`
    Property that determines whether Carriage Return (\r) characters are to be escaped when output or not. If enabled, all instances of of character \r are escaped using a character entity (where possible, that is, within CHARACTERS events, and attribute values). Otherwise they are output as is. The main reason to enable this property is to ensure that carriage returns are preserved as is through parsing, since otherwise they will be converted to canonical XML linefeeds (\n), when occurring along or as part of \r\n pair. This property is Woodstox specific.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `StAXUtils()` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static XMLStreamReader` | `createXMLStreamReader​(InputStream in)` |
    `static XMLStreamReader` | `createXMLStreamReader​(InputStream in, String encoding)` |
    `static XMLStreamReader` | `createXMLStreamReader​(Reader in)` |
    `static XMLStreamReader` | `createXMLStreamReader​(StAXParserConfiguration configuration, InputStream in)` |
    `static XMLStreamReader` | `createXMLStreamReader​(StAXParserConfiguration configuration, InputStream in, String encoding)` |
    `static XMLStreamReader` | `createXMLStreamReader​(StAXParserConfiguration configuration, Reader in)` |
    `static XMLStreamReader` | `createXMLStreamReader​(StAXParserConfiguration configuration, String systemId, InputStream in)` |
    `static XMLStreamWriter` | `createXMLStreamWriter​(OutputStream out)` | Deprecated.
    `static XMLStreamWriter` | `createXMLStreamWriter​(OutputStream out, String encoding)` | Deprecated.
    `static XMLStreamWriter` | `createXMLStreamWriter​(Writer out)` | Deprecated.
    `static XMLStreamWriter` | `createXMLStreamWriter​(StAXWriterConfiguration configuration, OutputStream out)` | Deprecated.
    `static XMLStreamWriter` | `createXMLStreamWriter​(StAXWriterConfiguration configuration, OutputStream out, String encoding)` | Deprecated.
    `static XMLStreamWriter` | `createXMLStreamWriter​(StAXWriterConfiguration configuration, Writer out)` | Deprecated.
    `static XMLInputFactory` | `getXMLInputFactory()` | Get a cached `XMLInputFactory` instance using the default configuration.
    `static XMLInputFactory` | `getXMLInputFactory​(boolean factoryPerClassLoaderPolicy)` | Deprecated.
    `static XMLInputFactory` | `getXMLInputFactory​(StAXParserConfiguration configuration)` | Get a cached `XMLInputFactory` instance using the specified configuration.
    `static XMLInputFactory` | `getXMLInputFactory​(StAXParserConfiguration configuration, boolean factoryPerClassLoaderPolicy)` | Deprecated.
    `static XMLOutputFactory` | `getXMLOutputFactory()` | Deprecated.
    `static XMLOutputFactory` | `getXMLOutputFactory​(boolean factoryPerClassLoaderPolicy)` | Deprecated.
    `static XMLOutputFactory` | `getXMLOutputFactory​(StAXWriterConfiguration configuration)` | Deprecated.
    `static XMLOutputFactory` | `getXMLOutputFactory​(StAXWriterConfiguration configuration, boolean factoryPerClassLoaderPolicy)` | Deprecated.
    `static void` | `setFactoryPerClassLoader​(boolean value)` | Deprecated. Per class loader factories are no longer supported.

    - ### 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

    - #### getXMLInputFactory

          public static XMLInputFactory getXMLInputFactory()

      Get a cached `XMLInputFactory` instance using the default configuration.
      Returns:
        an `XMLInputFactory` instance.

    - #### getXMLInputFactory

          public static XMLInputFactory getXMLInputFactory​(boolean factoryPerClassLoaderPolicy)

      Deprecated.
      Get a cached `XMLInputFactory` instance using the default configuration and the specified cache policy.
      Parameters:
        `factoryPerClassLoaderPolicy` - the cache policy; see `getXMLInputFactory(StAXParserConfiguration, boolean)` for more details
      Returns:
        an `XMLInputFactory` instance.

    - #### getXMLInputFactory

          public static XMLInputFactory getXMLInputFactory​(StAXParserConfiguration configuration,
                                                           boolean factoryPerClassLoaderPolicy)

      Deprecated.
      Get a cached `XMLInputFactory` instance using the specified configuration and cache policy.
      Parameters:
        `configuration` - the configuration applied to the requested factory
        `factoryPerClassLoaderPolicy` - If set to `true`, the factory cached for the current class loader will be returned. If set to `false`, the singleton factory (instantiated using the class loader that loaded `StAXUtils`) will be returned.
      Returns:
        an `XMLInputFactory` instance.

    - #### createXMLStreamReader

          public static XMLStreamReader createXMLStreamReader​(InputStream in,
                                                              String encoding)
                                                       throws XMLStreamException

      Throws:
        `XMLStreamException`

    - #### createXMLStreamReader

          public static XMLStreamReader createXMLStreamReader​(StAXParserConfiguration configuration,
                                                              InputStream in,
                                                              String encoding)
                                                       throws XMLStreamException

      Throws:
        `XMLStreamException`

    - #### createXMLStreamReader

          public static XMLStreamReader createXMLStreamReader​(InputStream in)
                                                       throws XMLStreamException

      Throws:
        `XMLStreamException`

    - #### createXMLStreamReader

          public static XMLStreamReader createXMLStreamReader​(StAXParserConfiguration configuration,
                                                              InputStream in)
                                                       throws XMLStreamException

      Throws:
        `XMLStreamException`

    - #### createXMLStreamReader

          public static XMLStreamReader createXMLStreamReader​(StAXParserConfiguration configuration,
                                                              String systemId,
                                                              InputStream in)
                                                       throws XMLStreamException

      Throws:
        `XMLStreamException`

    - #### createXMLStreamReader

          public static XMLStreamReader createXMLStreamReader​(Reader in)
                                                       throws XMLStreamException

      Throws:
        `XMLStreamException`

    - #### createXMLStreamReader

          public static XMLStreamReader createXMLStreamReader​(StAXParserConfiguration configuration,
                                                              Reader in)
                                                       throws XMLStreamException

      Throws:
        `XMLStreamException`

    - #### getXMLOutputFactory

          public static XMLOutputFactory getXMLOutputFactory()

      Deprecated.
      Get a cached `XMLOutputFactory` instance using the default configuration.
      Returns:
        an `XMLOutputFactory` instance.

    - #### getXMLOutputFactory

          public static XMLOutputFactory getXMLOutputFactory​(boolean factoryPerClassLoaderPolicy)

      Deprecated.
      Get a cached `XMLOutputFactory` instance using the default configuration and the specified cache policy.
      Parameters:
        `factoryPerClassLoaderPolicy` - the cache policy; see `getXMLOutputFactory(StAXWriterConfiguration, boolean)` for more details
      Returns:
        an `XMLOutputFactory` instance.

    - #### getXMLOutputFactory

          public static XMLOutputFactory getXMLOutputFactory​(StAXWriterConfiguration configuration,
                                                             boolean factoryPerClassLoaderPolicy)

      Deprecated.
      Get a cached `XMLOutputFactory` instance using the specified configuration and cache policy.
      Parameters:
        `configuration` - the configuration applied to the requested factory
        `factoryPerClassLoaderPolicy` - If set to `true`, the factory cached for the current class loader will be returned. If set to `false`, the singleton factory (instantiated using the class loader that loaded `StAXUtils`) will be returned.
      Returns:
        an `XMLOutputFactory` instance.

    - #### setFactoryPerClassLoader

          public static void setFactoryPerClassLoader​(boolean value)

      Deprecated.
      Per class loader factories are no longer supported. The code now always uses the class loader that loaded the `StAXUtils` class.

    - #### createXMLStreamWriter

          public static XMLStreamWriter createXMLStreamWriter​(OutputStream out)
                                                       throws XMLStreamException

      Deprecated.
      Throws:
        `XMLStreamException`

    - #### createXMLStreamWriter

          public static XMLStreamWriter createXMLStreamWriter​(StAXWriterConfiguration configuration,
                                                              OutputStream out)
                                                       throws XMLStreamException

      Deprecated.
      Throws:
        `XMLStreamException`

    - #### createXMLStreamWriter

          public static XMLStreamWriter createXMLStreamWriter​(OutputStream out,
                                                              String encoding)
                                                       throws XMLStreamException

      Deprecated.
      Throws:
        `XMLStreamException`

    - #### createXMLStreamWriter

          public static XMLStreamWriter createXMLStreamWriter​(StAXWriterConfiguration configuration,
                                                              OutputStream out,
                                                              String encoding)
                                                       throws XMLStreamException

      Deprecated.
      Throws:
        `XMLStreamException`

    - #### createXMLStreamWriter

          public static XMLStreamWriter createXMLStreamWriter​(Writer out)
                                                       throws XMLStreamException

      Deprecated.
      Throws:
        `XMLStreamException`

    - #### createXMLStreamWriter

          public static XMLStreamWriter createXMLStreamWriter​(StAXWriterConfiguration configuration,
                                                              Writer out)
                                                       throws XMLStreamException

      Deprecated.
      Throws:
        `XMLStreamException`

    - #### getXMLInputFactory

          public static XMLInputFactory getXMLInputFactory​(StAXParserConfiguration configuration)

      Get a cached `XMLInputFactory` instance using the specified configuration.
      Parameters:
        `configuration` - the configuration applied to the requested factory
      Returns:
        an `XMLInputFactory` instance.

    - #### getXMLOutputFactory

          public static XMLOutputFactory getXMLOutputFactory​(StAXWriterConfiguration configuration)

      Deprecated.
      Get a cached `XMLOutputFactory` instance using the specified configuration.
      Parameters:
        `configuration` - the configuration applied to the requested factory
      Returns:
        an `XMLOutputFactory` instance.