org.apache.axiom.om.util
Class StAXUtils

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

public class StAXUtils
extends java.lang.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

StAXUtils()

Method Summary

static javax.xml.stream.XMLStreamReader	createNetworkDetachedXMLStreamReader(java.io.InputStream in) Deprecated. use createXMLStreamReader(StAXParserConfiguration, InputStream) with StAXParserConfiguration.STANDALONE
static javax.xml.stream.XMLStreamReader	createNetworkDetachedXMLStreamReader(java.io.InputStream in, java.lang.String encoding) Deprecated. use createXMLStreamReader(StAXParserConfiguration, InputStream, String) with StAXParserConfiguration.STANDALONE
static javax.xml.stream.XMLStreamReader	createNetworkDetachedXMLStreamReader(java.io.Reader in) Deprecated. use createXMLStreamReader(StAXParserConfiguration, Reader) with StAXParserConfiguration.STANDALONE
static javax.xml.stream.XMLStreamReader	createXMLStreamReader(java.io.InputStream in)
static javax.xml.stream.XMLStreamReader	createXMLStreamReader(java.io.InputStream in, java.lang.String encoding)
static javax.xml.stream.XMLStreamReader	createXMLStreamReader(java.io.Reader in)
static javax.xml.stream.XMLStreamReader	createXMLStreamReader(StAXParserConfiguration configuration, java.io.InputStream in)
static javax.xml.stream.XMLStreamReader	createXMLStreamReader(StAXParserConfiguration configuration, java.io.InputStream in, java.lang.String encoding)
static javax.xml.stream.XMLStreamReader	createXMLStreamReader(StAXParserConfiguration configuration, java.io.Reader in)
static javax.xml.stream.XMLStreamWriter	createXMLStreamWriter(java.io.OutputStream out)
static javax.xml.stream.XMLStreamWriter	createXMLStreamWriter(java.io.OutputStream out, java.lang.String encoding)
static javax.xml.stream.XMLStreamWriter	createXMLStreamWriter(StAXWriterConfiguration configuration, java.io.OutputStream out)
static javax.xml.stream.XMLStreamWriter	createXMLStreamWriter(StAXWriterConfiguration configuration, java.io.OutputStream out, java.lang.String encoding)
static javax.xml.stream.XMLStreamWriter	createXMLStreamWriter(StAXWriterConfiguration configuration, java.io.Writer out)
static javax.xml.stream.XMLStreamWriter	createXMLStreamWriter(java.io.Writer out)
static java.lang.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.
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.
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(java.io.InputStream in,
                                                                     java.lang.String encoding)
                                                              throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamReader

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

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamReader

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

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamReader

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

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamReader

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

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamReader

public static javax.xml.stream.XMLStreamReader createXMLStreamReader(StAXParserConfiguration configuration,
                                                                     java.io.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(java.io.OutputStream out)
                                                              throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamWriter

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

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamWriter

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

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamWriter

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

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamWriter

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

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamWriter

public static javax.xml.stream.XMLStreamWriter createXMLStreamWriter(StAXWriterConfiguration configuration,
                                                                     java.io.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(java.io.InputStream in,
                                                                                    java.lang.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(java.io.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(java.io.Reader in)
                                                                             throws javax.xml.stream.XMLStreamException

Deprecated. use createXMLStreamReader(StAXParserConfiguration, Reader) with StAXParserConfiguration.STANDALONE

Throws:

javax.xml.stream.XMLStreamException

getEventTypeString

public static java.lang.String getEventTypeString(int event)

Deprecated. Use XMLEventUtils.getEventTypeString(int) instead