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 (`XMLInputFactory` and `XMLOutputFactory` objects) by classloader (default) or as singletons. The behavior can be changed using `setFactoryPerClassLoader(boolean)`.

  Default properties for these factories can be specified using `XMLInputFactory.properties` and `XMLOutputFactory.properties` files. When a new factory is instantiated, this class will attempt to load the corresponding file using the context classloader. This class supports properties with boolean, integer and string values. 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 and Description
    `StAXUtils()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static javax.xml.stream.XMLStreamReader` | `createNetworkDetachedXMLStreamReader(InputStream in)` Deprecated. use `createXMLStreamReader(StAXParserConfiguration, InputStream)` with `StAXParserConfiguration.STANDALONE`
    `static javax.xml.stream.XMLStreamReader` | `createNetworkDetachedXMLStreamReader(InputStream in, String encoding)` Deprecated. use `createXMLStreamReader(StAXParserConfiguration, InputStream, String)` with `StAXParserConfiguration.STANDALONE`
    `static javax.xml.stream.XMLStreamReader` | `createNetworkDetachedXMLStreamReader(Reader in)` Deprecated. use `createXMLStreamReader(StAXParserConfiguration, Reader)` with `StAXParserConfiguration.STANDALONE`
    `static javax.xml.stream.XMLStreamReader` | `createXMLStreamReader(InputStream in)`
    `static javax.xml.stream.XMLStreamReader` | `createXMLStreamReader(InputStream in, String encoding)`
    `static javax.xml.stream.XMLStreamReader` | `createXMLStreamReader(Reader in)`
    `static javax.xml.stream.XMLStreamReader` | `createXMLStreamReader(StAXParserConfiguration configuration, InputStream in)`
    `static javax.xml.stream.XMLStreamReader` | `createXMLStreamReader(StAXParserConfiguration configuration, InputStream in, String encoding)`
    `static javax.xml.stream.XMLStreamReader` | `createXMLStreamReader(StAXParserConfiguration configuration, Reader in)`
    `static javax.xml.stream.XMLStreamReader` | `createXMLStreamReader(StAXParserConfiguration configuration, String systemId, InputStream in)`
    `static javax.xml.stream.XMLStreamWriter` | `createXMLStreamWriter(OutputStream out)`
    `static javax.xml.stream.XMLStreamWriter` | `createXMLStreamWriter(OutputStream out, String encoding)`
    `static javax.xml.stream.XMLStreamWriter` | `createXMLStreamWriter(StAXWriterConfiguration configuration, OutputStream out)`
    `static javax.xml.stream.XMLStreamWriter` | `createXMLStreamWriter(StAXWriterConfiguration configuration, OutputStream out, String encoding)`
    `static javax.xml.stream.XMLStreamWriter` | `createXMLStreamWriter(StAXWriterConfiguration configuration, Writer out)`
    `static javax.xml.stream.XMLStreamWriter` | `createXMLStreamWriter(Writer out)`
    `static String` | `getEventTypeString(int event)` Deprecated. Use `XMLEventUtils.getEventTypeString(int)` instead
    `static javax.xml.stream.XMLInputFactory` | `getNetworkDetachedXMLInputFactory()` Deprecated. use `getXMLInputFactory(StAXParserConfiguration)` with `StAXParserConfiguration.STANDALONE`
    `static javax.xml.stream.XMLInputFactory` | `getXMLInputFactory()` Get a cached `XMLInputFactory` instance using the default configuration and cache policy (i.e. one instance per class loader).
    `static javax.xml.stream.XMLInputFactory` | `getXMLInputFactory(boolean factoryPerClassLoaderPolicy)` Get a cached `XMLInputFactory` instance using the default configuration and the specified cache policy.
    `static javax.xml.stream.XMLInputFactory` | `getXMLInputFactory(StAXParserConfiguration configuration)` Get a cached `XMLInputFactory` instance using the specified configuration and the default cache policy.
    `static javax.xml.stream.XMLInputFactory` | `getXMLInputFactory(StAXParserConfiguration configuration, boolean factoryPerClassLoaderPolicy)` Get a cached `XMLInputFactory` instance using the specified configuration and cache policy.
    `static javax.xml.stream.XMLOutputFactory` | `getXMLOutputFactory()` Get a cached `XMLOutputFactory` instance using the default configuration and cache policy (i.e. one instance per class loader).
    `static javax.xml.stream.XMLOutputFactory` | `getXMLOutputFactory(boolean factoryPerClassLoaderPolicy)` Get a cached `XMLOutputFactory` instance using the default configuration and the specified cache policy.
    `static javax.xml.stream.XMLOutputFactory` | `getXMLOutputFactory(StAXWriterConfiguration configuration)` Get a cached `XMLOutputFactory` instance using the specified configuration and the default cache policy.
    `static javax.xml.stream.XMLOutputFactory` | `getXMLOutputFactory(StAXWriterConfiguration configuration, boolean factoryPerClassLoaderPolicy)` Get a cached `XMLOutputFactory` instance using the specified configuration and cache policy.
    `static void` | `releaseXMLInputFactory(javax.xml.stream.XMLInputFactory factory)` Deprecated. Returns an XMLInputFactory instance for reuse.
    `static void` | `releaseXMLOutputFactory(javax.xml.stream.XMLOutputFactory factory)` Deprecated. Returns an XMLOutputFactory instance for reuse.
    `static void` | `reset()` Deprecated.
    `static void` | `setFactoryPerClassLoader(boolean value)` Set the policy for how to maintain the XMLInputFactory and XMLOutputFactory

    - ### 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 javax.xml.stream.XMLInputFactory getXMLInputFactory()

      Get a cached `XMLInputFactory` instance using the default configuration and cache policy (i.e. one instance per class loader).
      Returns:
        an `XMLInputFactory` instance.

    - #### getXMLInputFactory

          public static javax.xml.stream.XMLInputFactory getXMLInputFactory(StAXParserConfiguration configuration)

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

    - #### getXMLInputFactory

          public static javax.xml.stream.XMLInputFactory getXMLInputFactory(boolean factoryPerClassLoaderPolicy)

      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 javax.xml.stream.XMLInputFactory getXMLInputFactory(StAXParserConfiguration configuration,
                                                                            boolean factoryPerClassLoaderPolicy)

      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.

    - #### releaseXMLInputFactory

          public static void releaseXMLInputFactory(javax.xml.stream.XMLInputFactory factory)

      Deprecated. Returns an XMLInputFactory instance for reuse.
      Parameters:
        `factory` - An XMLInputFactory instance that is available for reuse

    - #### createXMLStreamReader

          public static javax.xml.stream.XMLStreamReader createXMLStreamReader(InputStream in,
                                                                               String encoding)
                                                                        throws javax.xml.stream.XMLStreamException

      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### createXMLStreamReader

          public static javax.xml.stream.XMLStreamReader createXMLStreamReader(StAXParserConfiguration configuration,
                                                                               InputStream in,
                                                                               String encoding)
                                                                        throws javax.xml.stream.XMLStreamException

      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### createXMLStreamReader

          public static javax.xml.stream.XMLStreamReader createXMLStreamReader(InputStream in)
                                                                        throws javax.xml.stream.XMLStreamException

      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### createXMLStreamReader

          public static javax.xml.stream.XMLStreamReader createXMLStreamReader(StAXParserConfiguration configuration,
                                                                               InputStream in)
                                                                        throws javax.xml.stream.XMLStreamException

      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### createXMLStreamReader

          public static javax.xml.stream.XMLStreamReader createXMLStreamReader(StAXParserConfiguration configuration,
                                                                               String systemId,
                                                                               InputStream in)
                                                                        throws javax.xml.stream.XMLStreamException

      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### createXMLStreamReader

          public static javax.xml.stream.XMLStreamReader createXMLStreamReader(Reader in)
                                                                        throws javax.xml.stream.XMLStreamException

      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### createXMLStreamReader

          public static javax.xml.stream.XMLStreamReader createXMLStreamReader(StAXParserConfiguration configuration,
                                                                               Reader in)
                                                                        throws javax.xml.stream.XMLStreamException

      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### getXMLOutputFactory

          public static javax.xml.stream.XMLOutputFactory getXMLOutputFactory()

      Get a cached `XMLOutputFactory` instance using the default configuration and cache policy (i.e. one instance per class loader).
      Returns:
        an `XMLOutputFactory` instance.

    - #### getXMLOutputFactory

          public static javax.xml.stream.XMLOutputFactory getXMLOutputFactory(StAXWriterConfiguration configuration)

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

    - #### getXMLOutputFactory

          public static javax.xml.stream.XMLOutputFactory getXMLOutputFactory(boolean factoryPerClassLoaderPolicy)

      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 javax.xml.stream.XMLOutputFactory getXMLOutputFactory(StAXWriterConfiguration configuration,
                                                                              boolean factoryPerClassLoaderPolicy)

      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)

      Set the policy for how to maintain the XMLInputFactory and XMLOutputFactory
      Parameters:
        `value` - (if false, then one singleton...if true...then singleton per class loader (default is true)

    - #### releaseXMLOutputFactory

          public static void releaseXMLOutputFactory(javax.xml.stream.XMLOutputFactory factory)

      Deprecated. Returns an XMLOutputFactory instance for reuse.
      Parameters:
        `factory` - An XMLOutputFactory instance that is available for reuse.

    - #### createXMLStreamWriter

          public static javax.xml.stream.XMLStreamWriter createXMLStreamWriter(OutputStream out)
                                                                        throws javax.xml.stream.XMLStreamException

      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### createXMLStreamWriter

          public static javax.xml.stream.XMLStreamWriter createXMLStreamWriter(StAXWriterConfiguration configuration,
                                                                               OutputStream out)
                                                                        throws javax.xml.stream.XMLStreamException

      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### createXMLStreamWriter

          public static javax.xml.stream.XMLStreamWriter createXMLStreamWriter(OutputStream out,
                                                                               String encoding)
                                                                        throws javax.xml.stream.XMLStreamException

      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### createXMLStreamWriter

          public static javax.xml.stream.XMLStreamWriter createXMLStreamWriter(StAXWriterConfiguration configuration,
                                                                               OutputStream out,
                                                                               String encoding)
                                                                        throws javax.xml.stream.XMLStreamException

      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### createXMLStreamWriter

          public static javax.xml.stream.XMLStreamWriter createXMLStreamWriter(Writer out)
                                                                        throws javax.xml.stream.XMLStreamException

      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### createXMLStreamWriter

          public static javax.xml.stream.XMLStreamWriter createXMLStreamWriter(StAXWriterConfiguration configuration,
                                                                               Writer out)
                                                                        throws javax.xml.stream.XMLStreamException

      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### reset

          public static void reset()

      Deprecated.

    - #### createNetworkDetachedXMLStreamReader

          public static javax.xml.stream.XMLStreamReader createNetworkDetachedXMLStreamReader(InputStream in,
                                                                                              String encoding)
                                                                                       throws javax.xml.stream.XMLStreamException

      Deprecated. use `createXMLStreamReader(StAXParserConfiguration, InputStream, String)` with `StAXParserConfiguration.STANDALONE`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### getNetworkDetachedXMLInputFactory

          public static javax.xml.stream.XMLInputFactory getNetworkDetachedXMLInputFactory()

      Deprecated. use `getXMLInputFactory(StAXParserConfiguration)` with `StAXParserConfiguration.STANDALONE`

    - #### createNetworkDetachedXMLStreamReader

          public static javax.xml.stream.XMLStreamReader createNetworkDetachedXMLStreamReader(InputStream in)
                                                                                       throws javax.xml.stream.XMLStreamException

      Deprecated. use `createXMLStreamReader(StAXParserConfiguration, InputStream)` with `StAXParserConfiguration.STANDALONE`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### createNetworkDetachedXMLStreamReader

          public static javax.xml.stream.XMLStreamReader createNetworkDetachedXMLStreamReader(Reader in)
                                                                                       throws javax.xml.stream.XMLStreamException

      Deprecated. use `createXMLStreamReader(StAXParserConfiguration, Reader)` with `StAXParserConfiguration.STANDALONE`
      Throws:
        `javax.xml.stream.XMLStreamException`

    - #### getEventTypeString

          public static String getEventTypeString(int event)

      Deprecated. Use `XMLEventUtils.getEventTypeString(int)` instead

Copyright © The Apache Software Foundation. All Rights Reserved.