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.

Field Summary

Fields

Modifier and Type	Field and Description
private static java.util.Map	inputFactoryMap
private static java.util.Map	inputFactoryPerCLMap
private static boolean	isFactoryPerClassLoader
private static org.apache.commons.logging.Log	log
private static java.util.Map	outputFactoryMap
private static java.util.Map	outputFactoryPerCLMap

Constructor Summary

Constructors

Constructor and Description
StAXUtils()

Method Summary

Modifier and Type	Method and Description
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.XMLStreamReader	createXMLStreamReader(StAXParserConfiguration configuration, java.lang.String systemId, java.io.InputStream 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)
private static java.lang.ClassLoader	getContextClassLoader()
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
private static javax.xml.stream.XMLInputFactory	getXMLInputFactory_perClassLoader(StAXParserConfiguration configuration)
private static javax.xml.stream.XMLInputFactory	getXMLInputFactory_singleton(StAXParserConfiguration configuration)
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.
private static javax.xml.stream.XMLOutputFactory	getXMLOutputFactory_perClassLoader(StAXWriterConfiguration configuration)
private static javax.xml.stream.XMLOutputFactory	getXMLOutputFactory_singleton(StAXWriterConfiguration configuration)
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.
(package private) static java.util.Map	loadFactoryProperties(java.lang.String name) Load factory properties from a resource.
private static javax.xml.stream.XMLInputFactory	newXMLInputFactory(java.lang.ClassLoader classLoader, StAXParserConfiguration configuration)
private static javax.xml.stream.XMLOutputFactory	newXMLOutputFactory(java.lang.ClassLoader classLoader, StAXWriterConfiguration configuration)
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

Field Detail

log

private static final org.apache.commons.logging.Log log

isFactoryPerClassLoader

private static boolean isFactoryPerClassLoader

inputFactoryMap

private static final java.util.Map inputFactoryMap

outputFactoryMap

private static final java.util.Map outputFactoryMap

inputFactoryPerCLMap

private static final java.util.Map inputFactoryPerCLMap

outputFactoryPerCLMap

private static final java.util.Map outputFactoryPerCLMap

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(StAXParserConfiguration configuration,
                                                                     java.lang.String systemId,
                                                                     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.

loadFactoryProperties

static java.util.Map loadFactoryProperties(java.lang.String name)

Load factory properties from a resource. The context class loader is used to locate the resource. The method converts boolean and integer values to the right Java types. All other values are returned as strings.

Parameters:

name -

Returns:

newXMLInputFactory

private static javax.xml.stream.XMLInputFactory newXMLInputFactory(java.lang.ClassLoader classLoader,
                                                                   StAXParserConfiguration configuration)

getXMLInputFactory_perClassLoader

private static javax.xml.stream.XMLInputFactory getXMLInputFactory_perClassLoader(StAXParserConfiguration configuration)

Returns:

XMLInputFactory for the current classloader

getXMLInputFactory_singleton

private static javax.xml.stream.XMLInputFactory getXMLInputFactory_singleton(StAXParserConfiguration configuration)

Returns:

singleton XMLInputFactory loaded with the StAXUtils classloader

newXMLOutputFactory

private static javax.xml.stream.XMLOutputFactory newXMLOutputFactory(java.lang.ClassLoader classLoader,
                                                                     StAXWriterConfiguration configuration)

getXMLOutputFactory_perClassLoader

private static javax.xml.stream.XMLOutputFactory getXMLOutputFactory_perClassLoader(StAXWriterConfiguration configuration)

Returns:

XMLOutputFactory for the current classloader

getXMLOutputFactory_singleton

private static javax.xml.stream.XMLOutputFactory getXMLOutputFactory_singleton(StAXWriterConfiguration configuration)

Returns:

XMLOutputFactory singleton loaded with the StAXUtils classloader

getContextClassLoader

private static java.lang.ClassLoader getContextClassLoader()

Returns:

Trhead Context ClassLoader

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