com.ctc.wstx.stax
Class WstxInputFactory

java.lang.Object
  javax.xml.stream.XMLInputFactory
      org.codehaus.stax2.XMLInputFactory2
          com.ctc.wstx.stax.WstxInputFactory

All Implemented Interfaces:

InputConfigFlags, ReaderCreator, XMLStreamProperties

public final class WstxInputFactory
extends XMLInputFactory2
implements ReaderCreator, InputConfigFlags

Factory for creating various StAX objects (stream/event reader, writer).

Currently supported configuration options fall into two categories. First, all properties from XMLInputFactory (such as, say, XMLInputFactory.IS_NAMESPACE_AWARE) are at least recognized, and most are supported. Second, there are additional properties, defined in constant class WstxInputProperties, that are supported. See WstxInputProperties for further explanation of these 'custom' properties.

TODO:

• Pass XMLResolver for readers
• Try to implement reader that takes SAX events as input? (hard to do?)
• Implement reader that takes DOM tree as input

Field Summary

protected javax.xml.stream.util.XMLEventAllocator	mAllocator
protected ReaderConfig	mConfig Current configurations for this factory
protected SimpleCache	mDTDCache

Fields inherited from class org.codehaus.stax2.XMLInputFactory2

P_AUTO_CLOSE_INPUT, P_INTERN_NAMES, P_INTERN_NS_URIS, P_PRESERVE_LOCATION, P_REPORT_CDATA, P_REPORT_PROLOG_WHITESPACE

Fields inherited from class javax.xml.stream.XMLInputFactory

ALLOCATOR, IS_COALESCING, IS_NAMESPACE_AWARE, IS_REPLACING_ENTITY_REFERENCES, IS_SUPPORTING_EXTERNAL_ENTITIES, IS_VALIDATING, REPORTER, RESOLVER, SUPPORT_DTD

Fields inherited from interface com.ctc.wstx.cfg.InputConfigFlags

CFG_AUTO_CLOSE_INPUT, CFG_CACHE_DTDS, CFG_CACHE_DTDS_BY_PUBLIC_ID, CFG_COALESCE_TEXT, CFG_INTERN_NS_URIS, CFG_LAZY_PARSING, CFG_NAMESPACE_AWARE, CFG_NORMALIZE_ATTR_VALUES, CFG_NORMALIZE_LFS, CFG_PRESERVE_LOCATION, CFG_REPLACE_ENTITY_REFS, CFG_REPORT_CDATA, CFG_REPORT_PROLOG_WS, CFG_SUPPORT_DTD, CFG_SUPPORT_DTDPP, CFG_SUPPORT_EXTERNAL_ENTITIES, CFG_VALIDATE_AGAINST_DTD, CFG_VALIDATE_TEXT_CHARS, CFG_XMLID_TYPING, CFG_XMLID_UNIQ_CHECKS

Fields inherited from interface org.codehaus.stax2.XMLStreamProperties

XSP_IMPLEMENTATION_NAME, XSP_IMPLEMENTATION_VERSION, XSP_NAMESPACE_AWARE, XSP_PROBLEM_REPORTER, XSP_SUPPORT_XMLID, XSP_SUPPORTS_XML11, XSP_V_XMLID_FULL, XSP_V_XMLID_NONE, XSP_V_XMLID_TYPING

Constructor Summary

WstxInputFactory()

Method Summary

void	addCachedDTD(DTDId id, DTDSubset extSubset)
void	configureForConvenience() Method to call to make Reader created be as "convenient" to use as possible; ie try to avoid having to deal with some of things like segmented text chunks.
void	configureForLowMemUsage() Method to call to minimize the memory usage of the stream/event reader; both regarding Objects created, and the temporary memory usage during parsing.
void	configureForRoundTripping() Method to call to make Reader try to preserve as much of input formatting as possible, so that round-tripping would be as lossless as possible.
void	configureForSpeed() Method to call to make the Reader created be as fast as possible reading documents, especially for long-running processes where caching is likely to help.
void	configureForXmlConformance() Method to call to make Reader created conform as closely to XML standard as possible, doing all checks and transformations mandated by the XML specification (linefeed conversions, attr value normalizations).
protected javax.xml.stream.util.XMLEventAllocator	createEventAllocator()
javax.xml.stream.XMLEventReader	createFilteredReader(javax.xml.stream.XMLEventReader reader, javax.xml.stream.EventFilter filter)
javax.xml.stream.XMLStreamReader	createFilteredReader(javax.xml.stream.XMLStreamReader reader, javax.xml.stream.StreamFilter filter)
ReaderConfig	createPrivateConfig() Method called to construct a copy of the factory's configuration object, such that two will be unlinked (changes to one are not reflect in the other).
protected XMLStreamReader2	createSR(java.io.File f, boolean forER, boolean autoCloseInput)
XMLStreamReader2	createSR(ReaderConfig cfg, java.lang.String systemId, InputBootstrapper bs, boolean forER, boolean autoCloseInput) Method that is eventually called to create a (full) stream read instance.
protected XMLStreamReader2	createSR(ReaderConfig cfg, java.net.URL src, boolean forER, boolean autoCloseInput)
protected XMLStreamReader2	createSR(javax.xml.transform.Source src, boolean forER) Another internal factory method, used when dealing with a generic Source base type.
protected XMLStreamReader2	createSR(java.lang.String systemId, java.io.InputStream in, java.lang.String enc, boolean forER, boolean autoCloseInput)
protected XMLStreamReader2	createSR(java.lang.String systemId, java.io.Reader r, boolean forER, boolean autoCloseInput)
XMLEventReader2	createXMLEventReader(java.io.File f) Convenience factory method that allows for parsing a document stored in the specified file.
javax.xml.stream.XMLEventReader	createXMLEventReader(java.io.InputStream in)
javax.xml.stream.XMLEventReader	createXMLEventReader(java.io.InputStream in, java.lang.String enc)
javax.xml.stream.XMLEventReader	createXMLEventReader(java.io.Reader r)
javax.xml.stream.XMLEventReader	createXMLEventReader(javax.xml.transform.Source source)
javax.xml.stream.XMLEventReader	createXMLEventReader(java.lang.String systemId, java.io.InputStream in)
javax.xml.stream.XMLEventReader	createXMLEventReader(java.lang.String systemId, java.io.Reader r)
XMLEventReader2	createXMLEventReader(java.net.URL src) Factory method that allows for parsing a document accessible via specified URL.
javax.xml.stream.XMLEventReader	createXMLEventReader(javax.xml.stream.XMLStreamReader sr)
XMLStreamReader2	createXMLStreamReader(java.io.File f) Convenience factory method that allows for parsing a document stored in the specified file.
javax.xml.stream.XMLStreamReader	createXMLStreamReader(java.io.InputStream in)
javax.xml.stream.XMLStreamReader	createXMLStreamReader(java.io.InputStream in, java.lang.String enc)
javax.xml.stream.XMLStreamReader	createXMLStreamReader(java.io.Reader r)
javax.xml.stream.XMLStreamReader	createXMLStreamReader(javax.xml.transform.Source src)
javax.xml.stream.XMLStreamReader	createXMLStreamReader(java.lang.String systemId, java.io.InputStream in)
javax.xml.stream.XMLStreamReader	createXMLStreamReader(java.lang.String systemId, java.io.Reader r)
XMLStreamReader2	createXMLStreamReader(java.net.URL src) Factory method that allows for parsing a document accessible via specified URL.
DTDSubset	findCachedDTD(DTDId id) Method readers created by this factory call, if DTD caching is enabled, to see if an external DTD (subset) has been parsed and cached earlier.
ReaderConfig	getConfig()
javax.xml.stream.util.XMLEventAllocator	getEventAllocator()
java.lang.Object	getProperty(java.lang.String name)
javax.xml.stream.XMLReporter	getXMLReporter()
javax.xml.stream.XMLResolver	getXMLResolver()
boolean	isPropertySupported(java.lang.String name)
void	setEventAllocator(javax.xml.stream.util.XMLEventAllocator allocator)
void	setProperty(java.lang.String propName, java.lang.Object value)
void	setXMLReporter(javax.xml.stream.XMLReporter r)
void	setXMLResolver(javax.xml.stream.XMLResolver r) Note: it's preferable to use Wstx-specific ReaderConfig.setEntityResolver(javax.xml.stream.XMLResolver) instead, if possible, since this just wraps passed in resolver.
void	updateSymbolTable(SymbolTable t) Method individual parsers call to pass back symbol table that they updated, which may be useful for other parser to reuse, instead of previous base symbol table.

Methods inherited from class javax.xml.stream.XMLInputFactory

newInstance, newInstance

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

mConfig

protected final ReaderConfig mConfig

Current configurations for this factory

mAllocator

protected javax.xml.stream.util.XMLEventAllocator mAllocator

mDTDCache

protected SimpleCache mDTDCache

Constructor Detail

WstxInputFactory

public WstxInputFactory()

Method Detail

findCachedDTD

public DTDSubset findCachedDTD(DTDId id)

Method readers created by this factory call, if DTD caching is enabled, to see if an external DTD (subset) has been parsed and cached earlier.

Specified by:

findCachedDTD in interface ReaderCreator

updateSymbolTable

public void updateSymbolTable(SymbolTable t)

Method individual parsers call to pass back symbol table that they updated, which may be useful for other parser to reuse, instead of previous base symbol table.

Note: parser is only to call this method, if passed-in symbol table was modified, ie new entry/ies were added in addition to whatever was in root table.

Specified by:

updateSymbolTable in interface ReaderCreator

addCachedDTD

public void addCachedDTD(DTDId id,
                         DTDSubset extSubset)

Specified by:

addCachedDTD in interface ReaderCreator

createFilteredReader

public javax.xml.stream.XMLEventReader createFilteredReader(javax.xml.stream.XMLEventReader reader,
                                                            javax.xml.stream.EventFilter filter)

Specified by:

createFilteredReader in class javax.xml.stream.XMLInputFactory

createFilteredReader

public javax.xml.stream.XMLStreamReader createFilteredReader(javax.xml.stream.XMLStreamReader reader,
                                                             javax.xml.stream.StreamFilter filter)
                                                      throws javax.xml.stream.XMLStreamException

Specified by:

createFilteredReader in class javax.xml.stream.XMLInputFactory

Throws:

javax.xml.stream.XMLStreamException

createXMLEventReader

public javax.xml.stream.XMLEventReader createXMLEventReader(java.io.InputStream in)
                                                     throws javax.xml.stream.XMLStreamException

Specified by:

createXMLEventReader in class javax.xml.stream.XMLInputFactory

Throws:

javax.xml.stream.XMLStreamException

createXMLEventReader

public javax.xml.stream.XMLEventReader createXMLEventReader(java.io.InputStream in,
                                                            java.lang.String enc)
                                                     throws javax.xml.stream.XMLStreamException

Specified by:

createXMLEventReader in class javax.xml.stream.XMLInputFactory

Throws:

javax.xml.stream.XMLStreamException

createXMLEventReader

public javax.xml.stream.XMLEventReader createXMLEventReader(java.io.Reader r)
                                                     throws javax.xml.stream.XMLStreamException

Specified by:

createXMLEventReader in class javax.xml.stream.XMLInputFactory

Throws:

javax.xml.stream.XMLStreamException

createXMLEventReader

public javax.xml.stream.XMLEventReader createXMLEventReader(javax.xml.transform.Source source)
                                                     throws javax.xml.stream.XMLStreamException

Specified by:

createXMLEventReader in class javax.xml.stream.XMLInputFactory

Throws:

javax.xml.stream.XMLStreamException

createXMLEventReader

public javax.xml.stream.XMLEventReader createXMLEventReader(java.lang.String systemId,
                                                            java.io.InputStream in)
                                                     throws javax.xml.stream.XMLStreamException

Specified by:

createXMLEventReader in class javax.xml.stream.XMLInputFactory

Throws:

javax.xml.stream.XMLStreamException

createXMLEventReader

public javax.xml.stream.XMLEventReader createXMLEventReader(java.lang.String systemId,
                                                            java.io.Reader r)
                                                     throws javax.xml.stream.XMLStreamException

Specified by:

createXMLEventReader in class javax.xml.stream.XMLInputFactory

Throws:

javax.xml.stream.XMLStreamException

createXMLEventReader

public javax.xml.stream.XMLEventReader createXMLEventReader(javax.xml.stream.XMLStreamReader sr)
                                                     throws javax.xml.stream.XMLStreamException

Specified by:

createXMLEventReader in class javax.xml.stream.XMLInputFactory

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamReader

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

Specified by:

createXMLStreamReader in class javax.xml.stream.XMLInputFactory

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamReader

public javax.xml.stream.XMLStreamReader createXMLStreamReader(java.io.InputStream in,
                                                              java.lang.String enc)
                                                       throws javax.xml.stream.XMLStreamException

Specified by:

createXMLStreamReader in class javax.xml.stream.XMLInputFactory

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamReader

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

Specified by:

createXMLStreamReader in class javax.xml.stream.XMLInputFactory

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamReader

public javax.xml.stream.XMLStreamReader createXMLStreamReader(javax.xml.transform.Source src)
                                                       throws javax.xml.stream.XMLStreamException

Specified by:

createXMLStreamReader in class javax.xml.stream.XMLInputFactory

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamReader

public javax.xml.stream.XMLStreamReader createXMLStreamReader(java.lang.String systemId,
                                                              java.io.InputStream in)
                                                       throws javax.xml.stream.XMLStreamException

Specified by:

createXMLStreamReader in class javax.xml.stream.XMLInputFactory

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamReader

public javax.xml.stream.XMLStreamReader createXMLStreamReader(java.lang.String systemId,
                                                              java.io.Reader r)
                                                       throws javax.xml.stream.XMLStreamException

Specified by:

createXMLStreamReader in class javax.xml.stream.XMLInputFactory

Throws:

javax.xml.stream.XMLStreamException

getProperty

public java.lang.Object getProperty(java.lang.String name)

Specified by:

getProperty in class javax.xml.stream.XMLInputFactory

setProperty

public void setProperty(java.lang.String propName,
                        java.lang.Object value)

Specified by:

setProperty in class javax.xml.stream.XMLInputFactory

getEventAllocator

public javax.xml.stream.util.XMLEventAllocator getEventAllocator()

Specified by:

getEventAllocator in class javax.xml.stream.XMLInputFactory

getXMLReporter

public javax.xml.stream.XMLReporter getXMLReporter()

Specified by:

getXMLReporter in class javax.xml.stream.XMLInputFactory

getXMLResolver

public javax.xml.stream.XMLResolver getXMLResolver()

Specified by:

getXMLResolver in class javax.xml.stream.XMLInputFactory

isPropertySupported

public boolean isPropertySupported(java.lang.String name)

Specified by:

isPropertySupported in class javax.xml.stream.XMLInputFactory

setEventAllocator

public void setEventAllocator(javax.xml.stream.util.XMLEventAllocator allocator)

Specified by:

setEventAllocator in class javax.xml.stream.XMLInputFactory

setXMLReporter

public void setXMLReporter(javax.xml.stream.XMLReporter r)

Specified by:

setXMLReporter in class javax.xml.stream.XMLInputFactory

setXMLResolver

public void setXMLResolver(javax.xml.stream.XMLResolver r)

Note: it's preferable to use Wstx-specific ReaderConfig.setEntityResolver(javax.xml.stream.XMLResolver) instead, if possible, since this just wraps passed in resolver.

Specified by:

setXMLResolver in class javax.xml.stream.XMLInputFactory

createXMLEventReader

public XMLEventReader2 createXMLEventReader(java.net.URL src)
                                     throws javax.xml.stream.XMLStreamException

Description copied from class: XMLInputFactory2

Factory method that allows for parsing a document accessible via specified URL. Note that URL may refer to all normal URL accessible resources, from files to web- and ftp-accessible documents.

Specified by:

createXMLEventReader in class XMLInputFactory2

Throws:

javax.xml.stream.XMLStreamException

createXMLEventReader

public XMLEventReader2 createXMLEventReader(java.io.File f)
                                     throws javax.xml.stream.XMLStreamException

Description copied from class: XMLInputFactory2

Convenience factory method that allows for parsing a document stored in the specified file.

Specified by:

createXMLEventReader in class XMLInputFactory2

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamReader

public XMLStreamReader2 createXMLStreamReader(java.net.URL src)
                                       throws javax.xml.stream.XMLStreamException

Description copied from class: XMLInputFactory2

Factory method that allows for parsing a document accessible via specified URL. Note that URL may refer to all normal URL accessible resources, from files to web- and ftp-accessible documents.

Specified by:

createXMLStreamReader in class XMLInputFactory2

Throws:

javax.xml.stream.XMLStreamException

createXMLStreamReader

public XMLStreamReader2 createXMLStreamReader(java.io.File f)
                                       throws javax.xml.stream.XMLStreamException

Convenience factory method that allows for parsing a document stored in the specified file.

Specified by:

createXMLStreamReader in class XMLInputFactory2

Throws:

javax.xml.stream.XMLStreamException

configureForXmlConformance

public void configureForXmlConformance()

Description copied from class: XMLInputFactory2

Method to call to make Reader created conform as closely to XML standard as possible, doing all checks and transformations mandated by the XML specification (linefeed conversions, attr value normalizations).

Regarding the default StAX property settings, implementations are suggested to do following:

• Enable SUPPORT_DTD property.
• Enable IS_NAMESPACE_AWARE
• Enable IS_REPLACING_ENTITY_REFERENCES
• Enable IS_SUPPORTING_EXTERNAL_ENTITIES

All the other standard settings should be left as is.

In addition, implementations should set implementation-dependant settings appropriately, to be as strict as possible with regards to XML specification mandated checks and transformations.

Specified by:

configureForXmlConformance in class XMLInputFactory2

configureForConvenience

public void configureForConvenience()

Description copied from class: XMLInputFactory2

Method to call to make Reader created be as "convenient" to use as possible; ie try to avoid having to deal with some of things like segmented text chunks. This may incur some slight performance penalties, but should not affect XML conformance.

Regarding the default StAX property settings, implementations are suggested to do following:

• Enable IS_COALESCING (text coalescing)
• Enable IS_REPLACING_ENTITY_REFERENCES
• Disable P_REPORT_PROLOG_WHITESPACE (StAX2); so that the application need not skip possible SPACE (and COMMENT, PROCESSING_INSTRUCTION) events.
• Enable P_REPORT_ALL_TEXT_AS_CHARACTERS (StAX2)
• Enable P_PRESERVE_LOCATION (StAX2)

All the other standard settings should be left as is.

In addition, implementations should set implementation-dependant settings appropriately as well.

Specified by:

configureForConvenience in class XMLInputFactory2

configureForSpeed

public void configureForSpeed()

Description copied from class: XMLInputFactory2

Method to call to make the Reader created be as fast as possible reading documents, especially for long-running processes where caching is likely to help. This means reducing amount of information collected (ignorable white space in prolog/epilog, accurate Location information for Event API), and possibly even including simplifying handling of XML-specified transformations (skip attribute value and text linefeed normalization). Potential downsides are somewhat increased memory usage (for full-sized input buffers), and reduced XML conformance (will not do some of transformations).

Regarding the default StAX property settings, implementations are suggested to do following:

• Disable IS_COALESCING (text coalescing)
• Disable P_PRESERVE_LOCATION (StAX2)
• Disable P_REPORT_PROLOG_WHITESPACE (StAX2)
• Enable P_INTERN_NAMES (StAX2)
• Enable P_INTERN_NS_URIS (StAX2)

All the other standard settings should be left as is.

In addition, implementations should set implementation-dependant settings appropriately as well.

Specified by:

configureForSpeed in class XMLInputFactory2

configureForLowMemUsage

public void configureForLowMemUsage()

Description copied from class: XMLInputFactory2

Method to call to minimize the memory usage of the stream/event reader; both regarding Objects created, and the temporary memory usage during parsing. This generally incurs some performance penalties, due to using smaller input buffers.

Regarding the default StAX property settings, implementations are suggested to do following:

• Disable IS_COALECING (text coalescing, can force longer internal result buffers to be used)
• Disable P_PRESERVE_LOCATION (StAX) to reduce temporary memory usage.

All the other standard settings should be left as is.

In addition, implementations should set implementation-dependant settings appropriately so that the memory usage is minimized.

Specified by:

configureForLowMemUsage in class XMLInputFactory2

configureForRoundTripping

public void configureForRoundTripping()

Description copied from class: XMLInputFactory2

Method to call to make Reader try to preserve as much of input formatting as possible, so that round-tripping would be as lossless as possible. This means that the matching writer should be able to reproduce output as closely matching input format as possible (most implementations won't be able to provide 100% vis-a-vis; white space between attributes is generally lost, as well as use of character entities).

Regarding the default StAX property settings, implementations are suggested to do following:

• Disable IS_COALESCING (to prevent CDATA and Text segments from getting combined)
• Disable IS_REPLACING_ENTITY_REFERENCES to allow for preserving explicitly declared general entity references (that is, there is no way to preserve character entities, or pre-defined entities like 'gt', 'lt', 'amp', 'apos' and 'quot').
• Disable P_REPORT_ALL_TEXT_AS_CHARACTERS (StAX2) (so that CDATA sections are not reported as 'normal' text)
• Enable P_REPORT_PROLOG_WHITESPACE (StAX2)

All the other standard settings should be left as is.

In addition, implementations should set implementation-dependant settings appropriately as well.

Specified by:

configureForRoundTripping in class XMLInputFactory2

getConfig

public ReaderConfig getConfig()

createSR

public XMLStreamReader2 createSR(ReaderConfig cfg,
                                 java.lang.String systemId,
                                 InputBootstrapper bs,
                                 boolean forER,
                                 boolean autoCloseInput)
                          throws javax.xml.stream.XMLStreamException

Method that is eventually called to create a (full) stream read instance.

Note: defined as public method because it needs to be called by SAX implementation.

Parameters:

systemId - System id used for this reader (if any)

bs - Bootstrapper to use for creating actual underlying physical reader

forER - Flag to indicate whether it will be used via Event API (will affect some configuration settings), true if it will be, false if not (or not known)

autoCloseInput - Whether the underlying input source should be actually closed when encountering EOF, or when close() is called. Will be true for input sources that are automatically managed by stream reader (input streams created for URL and File arguments, or when configuration settings indicate auto-closing is to be enabled (the default value is false as per Stax 1.0 specs).

Throws:

javax.xml.stream.XMLStreamException

createSR

protected XMLStreamReader2 createSR(java.lang.String systemId,
                                    java.io.InputStream in,
                                    java.lang.String enc,
                                    boolean forER,
                                    boolean autoCloseInput)
                             throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

createSR

protected XMLStreamReader2 createSR(ReaderConfig cfg,
                                    java.net.URL src,
                                    boolean forER,
                                    boolean autoCloseInput)
                             throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

createSR

protected XMLStreamReader2 createSR(java.lang.String systemId,
                                    java.io.Reader r,
                                    boolean forER,
                                    boolean autoCloseInput)
                             throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

createSR

protected XMLStreamReader2 createSR(java.io.File f,
                                    boolean forER,
                                    boolean autoCloseInput)
                             throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

createSR

protected XMLStreamReader2 createSR(javax.xml.transform.Source src,
                                    boolean forER)
                             throws javax.xml.stream.XMLStreamException

Another internal factory method, used when dealing with a generic Source base type. One thing worth noting is that 'auto-closing' will be enabled if the input source or Reader is constructed (and thus owned) by Woodstox.

Throws:

javax.xml.stream.XMLStreamException

createEventAllocator

protected javax.xml.stream.util.XMLEventAllocator createEventAllocator()

createPrivateConfig

public ReaderConfig createPrivateConfig()

Method called to construct a copy of the factory's configuration object, such that two will be unlinked (changes to one are not reflect in the other).

Note: only public so that other woodstox components outside of this package can access it.