org.apache.axiom.om.util
Class StAXUtils

java.lang.Object
  extended by 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
StAXUtils()
           
 
Method Summary
static XMLStreamReader createNetworkDetachedXMLStreamReader(InputStream in)
          Deprecated. use createXMLStreamReader(StAXParserConfiguration, InputStream) with StAXParserConfiguration.STANDALONE
static XMLStreamReader createNetworkDetachedXMLStreamReader(InputStream in, String encoding)
          Deprecated. use createXMLStreamReader(StAXParserConfiguration, InputStream, String) with StAXParserConfiguration.STANDALONE
static XMLStreamReader createNetworkDetachedXMLStreamReader(Reader in)
          Deprecated. use createXMLStreamReader(StAXParserConfiguration, Reader) with StAXParserConfiguration.STANDALONE
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)
           
static XMLStreamWriter createXMLStreamWriter(OutputStream out, String encoding)
           
static XMLStreamWriter createXMLStreamWriter(StAXWriterConfiguration configuration, OutputStream out)
           
static XMLStreamWriter createXMLStreamWriter(StAXWriterConfiguration configuration, OutputStream out, String encoding)
           
static XMLStreamWriter createXMLStreamWriter(StAXWriterConfiguration configuration, Writer out)
           
static XMLStreamWriter createXMLStreamWriter(Writer out)
           
static String getEventTypeString(int event)
          Deprecated. Use XMLEventUtils.getEventTypeString(int) instead
static XMLInputFactory getNetworkDetachedXMLInputFactory()
          Deprecated. use getXMLInputFactory(StAXParserConfiguration) with StAXParserConfiguration.STANDALONE
static XMLInputFactory getXMLInputFactory()
          Get a cached XMLInputFactory instance using the default configuration and cache policy (i.e. one instance per class loader).
static XMLInputFactory getXMLInputFactory(boolean factoryPerClassLoaderPolicy)
          Get a cached XMLInputFactory instance using the default configuration and the specified cache policy.
static XMLInputFactory getXMLInputFactory(StAXParserConfiguration configuration)
          Get a cached XMLInputFactory instance using the specified configuration and the default cache policy.
static XMLInputFactory getXMLInputFactory(StAXParserConfiguration configuration, boolean factoryPerClassLoaderPolicy)
          Get a cached XMLInputFactory instance using the specified configuration and cache policy.
static XMLOutputFactory getXMLOutputFactory()
          Get a cached XMLOutputFactory instance using the default configuration and cache policy (i.e. one instance per class loader).
static XMLOutputFactory getXMLOutputFactory(boolean factoryPerClassLoaderPolicy)
          Get a cached XMLOutputFactory instance using the default configuration and the specified cache policy.
static XMLOutputFactory getXMLOutputFactory(StAXWriterConfiguration configuration)
          Get a cached XMLOutputFactory instance using the specified configuration and the default cache policy.
static XMLOutputFactory getXMLOutputFactory(StAXWriterConfiguration configuration, boolean factoryPerClassLoaderPolicy)
          Get a cached XMLOutputFactory instance using the specified configuration and cache policy.
static void releaseXMLInputFactory(XMLInputFactory factory)
          Deprecated. Returns an XMLInputFactory instance for reuse.
static void releaseXMLOutputFactory(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 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 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 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 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(XMLInputFactory factory)
Deprecated. Returns an XMLInputFactory instance for reuse.

Parameters:
factory - An XMLInputFactory instance that is available for reuse

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()
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 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 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 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(XMLOutputFactory factory)
Deprecated. Returns an XMLOutputFactory instance for reuse.

Parameters:
factory - An XMLOutputFactory instance that is available for reuse.

createXMLStreamWriter

public static XMLStreamWriter createXMLStreamWriter(OutputStream out)
                                             throws XMLStreamException
Throws:
XMLStreamException

createXMLStreamWriter

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

createXMLStreamWriter

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

createXMLStreamWriter

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

createXMLStreamWriter

public static XMLStreamWriter createXMLStreamWriter(Writer out)
                                             throws XMLStreamException
Throws:
XMLStreamException

createXMLStreamWriter

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

reset

public static void reset()
Deprecated. 


createNetworkDetachedXMLStreamReader

public static XMLStreamReader createNetworkDetachedXMLStreamReader(InputStream in,
                                                                   String encoding)
                                                            throws XMLStreamException
Deprecated. use createXMLStreamReader(StAXParserConfiguration, InputStream, String) with StAXParserConfiguration.STANDALONE

Throws:
XMLStreamException

getNetworkDetachedXMLInputFactory

public static XMLInputFactory getNetworkDetachedXMLInputFactory()
Deprecated. use getXMLInputFactory(StAXParserConfiguration) with StAXParserConfiguration.STANDALONE


createNetworkDetachedXMLStreamReader

public static XMLStreamReader createNetworkDetachedXMLStreamReader(InputStream in)
                                                            throws XMLStreamException
Deprecated. use createXMLStreamReader(StAXParserConfiguration, InputStream) with StAXParserConfiguration.STANDALONE

Throws:
XMLStreamException

createNetworkDetachedXMLStreamReader

public static XMLStreamReader createNetworkDetachedXMLStreamReader(Reader in)
                                                            throws XMLStreamException
Deprecated. use createXMLStreamReader(StAXParserConfiguration, Reader) with StAXParserConfiguration.STANDALONE

Throws:
XMLStreamException

getEventTypeString

public static String getEventTypeString(int event)
Deprecated. Use XMLEventUtils.getEventTypeString(int) instead



Copyright © 2004-2012 The Apache Software Foundation. All Rights Reserved.