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

  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 Details

  - ### StAXUtils

    public StAXUtils()

- ## Method Details

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