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

Author:

Tatu Saloranta

Field Summary

Fields

Modifier and Type	Field	Description
protected XMLEventAllocator	mAllocator
protected ReaderConfig	mConfig	Current configurations for this factory
protected SimpleCache<DTDId,DTDSubset>	mDTDCache

Fields inherited from class org.codehaus.stax2.XMLInputFactory2

P_AUTO_CLOSE_INPUT, P_DTD_OVERRIDE, P_INTERN_NAMES, P_INTERN_NS_URIS, P_LAZY_PARSING, 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_NAMES, CFG_INTERN_NS_URIS, CFG_LAZY_PARSING, CFG_NAMESPACE_AWARE, 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_TREAT_CHAR_REFS_AS_ENTS, CFG_VALIDATE_AGAINST_DTD, 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

Constructors

Constructor	Description
WstxInputFactory()

Method Summary

Modifier and Type	Method	Description
void	addCachedDTD(DTDId id, DTDSubset extSubset)
void	addSymbol(String symbol)	Method that can be used to ensure that specified symbol is contained in the shared symbol table.
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 XMLEventAllocator	createEventAllocator()
XMLEventReader	createFilteredReader(XMLEventReader reader, EventFilter filter)
XMLStreamReader	createFilteredReader(XMLStreamReader reader, 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).
XMLStreamReader2	createSR(ReaderConfig cfg, SystemId systemId, InputBootstrapper bs, boolean forER, boolean autoCloseInput)
XMLStreamReader2	createSR(ReaderConfig cfg, 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, URL src, boolean forER, boolean autoCloseInput)
protected XMLStreamReader2	createSR(SystemId systemId, InputStream in, String enc, boolean forER, boolean autoCloseInput)
protected XMLStreamReader2	createSR(SystemId systemId, Reader r, boolean forER, boolean autoCloseInput)
protected XMLStreamReader2	createSR(File f, boolean forER, boolean autoCloseInput)
protected XMLStreamReader2	createSR(Source src, boolean forER)	Another internal factory method, used when dealing with a generic Source base type.
XMLEventReader2	createXMLEventReader(File f)	Convenience factory method that allows for parsing a document stored in the specified file.
XMLEventReader	createXMLEventReader(InputStream in)
XMLEventReader	createXMLEventReader(InputStream in, String enc)
XMLEventReader	createXMLEventReader(Reader r)
XMLEventReader	createXMLEventReader(String systemId, InputStream in)
XMLEventReader	createXMLEventReader(String systemId, Reader r)
XMLEventReader2	createXMLEventReader(URL src)	Factory method that allows for parsing a document accessible via specified URL.
XMLEventReader	createXMLEventReader(XMLStreamReader sr)
XMLEventReader	createXMLEventReader(Source source)
XMLStreamReader2	createXMLStreamReader(File f)	Convenience factory method that allows for parsing a document stored in the specified file.
XMLStreamReader	createXMLStreamReader(InputStream in)
XMLStreamReader	createXMLStreamReader(InputStream in, String enc)
XMLStreamReader	createXMLStreamReader(Reader r)
XMLStreamReader	createXMLStreamReader(String systemId, InputStream in)
XMLStreamReader	createXMLStreamReader(String systemId, Reader r)
XMLStreamReader2	createXMLStreamReader(URL src)	Factory method that allows for parsing a document accessible via specified URL.
XMLStreamReader	createXMLStreamReader(Source src)
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()
XMLEventAllocator	getEventAllocator()
Object	getProperty(String name)
XMLReporter	getXMLReporter()
XMLResolver	getXMLResolver()
boolean	isPropertySupported(String name)
void	setEventAllocator(XMLEventAllocator allocator)
void	setProperty(String propName, Object value)
void	setXMLReporter(XMLReporter r)
void	setXMLResolver(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

newDefaultFactory, newFactory, newFactory, 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 XMLEventAllocator mAllocator

mDTDCache

protected SimpleCache<DTDId,DTDSubset> mDTDCache

Constructor Detail

WstxInputFactory

public WstxInputFactory()

Method Detail

addSymbol

public void addSymbol(String symbol)

Method that can be used to ensure that specified symbol is contained in the shared symbol table. This may occasionally be useful in pre-populating symbols; although it is unlikely to be commonly useful.

Since:

4.2.1

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 XMLEventReader createFilteredReader(XMLEventReader reader,
                                           EventFilter filter)

Specified by:

createFilteredReader in class XMLInputFactory

createFilteredReader

public XMLStreamReader createFilteredReader(XMLStreamReader reader,
                                            StreamFilter filter)
                                     throws XMLStreamException

Specified by:

createFilteredReader in class XMLInputFactory

Throws:

XMLStreamException

createXMLEventReader

public XMLEventReader createXMLEventReader(InputStream in)
                                    throws XMLStreamException

Specified by:

createXMLEventReader in class XMLInputFactory

Throws:

XMLStreamException

createXMLEventReader

public XMLEventReader createXMLEventReader(InputStream in,
                                           String enc)
                                    throws XMLStreamException

Specified by:

createXMLEventReader in class XMLInputFactory

Throws:

XMLStreamException

createXMLEventReader

public XMLEventReader createXMLEventReader(Reader r)
                                    throws XMLStreamException

Specified by:

createXMLEventReader in class XMLInputFactory

Throws:

XMLStreamException

createXMLEventReader

public XMLEventReader createXMLEventReader(Source source)
                                    throws XMLStreamException

Specified by:

createXMLEventReader in class XMLInputFactory

Throws:

XMLStreamException

createXMLEventReader

public XMLEventReader createXMLEventReader(String systemId,
                                           InputStream in)
                                    throws XMLStreamException

Specified by:

createXMLEventReader in class XMLInputFactory

Throws:

XMLStreamException

createXMLEventReader

public XMLEventReader createXMLEventReader(String systemId,
                                           Reader r)
                                    throws XMLStreamException

Specified by:

createXMLEventReader in class XMLInputFactory

Throws:

XMLStreamException

createXMLEventReader

public XMLEventReader createXMLEventReader(XMLStreamReader sr)
                                    throws XMLStreamException

Specified by:

createXMLEventReader in class XMLInputFactory

Throws:

XMLStreamException

createXMLStreamReader

public XMLStreamReader createXMLStreamReader(InputStream in)
                                      throws XMLStreamException

Specified by:

createXMLStreamReader in class XMLInputFactory

Throws:

XMLStreamException

createXMLStreamReader

public XMLStreamReader createXMLStreamReader(InputStream in,
                                             String enc)
                                      throws XMLStreamException

Specified by:

createXMLStreamReader in class XMLInputFactory

Throws:

XMLStreamException

createXMLStreamReader

public XMLStreamReader createXMLStreamReader(Reader r)
                                      throws XMLStreamException

Specified by:

createXMLStreamReader in class XMLInputFactory

Throws:

XMLStreamException

createXMLStreamReader

public XMLStreamReader createXMLStreamReader(Source src)
                                      throws XMLStreamException

Specified by:

createXMLStreamReader in class XMLInputFactory

Throws:

XMLStreamException

createXMLStreamReader

public XMLStreamReader createXMLStreamReader(String systemId,
                                             InputStream in)
                                      throws XMLStreamException

Specified by:

createXMLStreamReader in class XMLInputFactory

Throws:

XMLStreamException

createXMLStreamReader

public XMLStreamReader createXMLStreamReader(String systemId,
                                             Reader r)
                                      throws XMLStreamException

Specified by:

createXMLStreamReader in class XMLInputFactory

Throws:

XMLStreamException

getProperty

public Object getProperty(String name)

Specified by:

getProperty in class XMLInputFactory

setProperty

public void setProperty(String propName,
                        Object value)

Specified by:

setProperty in class XMLInputFactory

getEventAllocator

public XMLEventAllocator getEventAllocator()

Specified by:

getEventAllocator in class XMLInputFactory

getXMLReporter

public XMLReporter getXMLReporter()

Specified by:

getXMLReporter in class XMLInputFactory

getXMLResolver

public XMLResolver getXMLResolver()

Specified by:

getXMLResolver in class XMLInputFactory

isPropertySupported

public boolean isPropertySupported(String name)

Specified by:

isPropertySupported in class XMLInputFactory

setEventAllocator

public void setEventAllocator(XMLEventAllocator allocator)

Specified by:

setEventAllocator in class XMLInputFactory

setXMLReporter

public void setXMLReporter(XMLReporter r)

Specified by:

setXMLReporter in class XMLInputFactory

setXMLResolver

public void setXMLResolver(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 XMLInputFactory

createXMLEventReader

public XMLEventReader2 createXMLEventReader(URL src)
                                     throws 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:

XMLStreamException

createXMLEventReader

public XMLEventReader2 createXMLEventReader(File f)
                                     throws 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:

XMLStreamException

createXMLStreamReader

public XMLStreamReader2 createXMLStreamReader(URL src)
                                       throws 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:

XMLStreamException

createXMLStreamReader

public XMLStreamReader2 createXMLStreamReader(File f)
                                       throws XMLStreamException

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

Specified by:

createXMLStreamReader in class XMLInputFactory2

Throws:

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,
                                 String systemId,
                                 InputBootstrapper bs,
                                 boolean forER,
                                 boolean autoCloseInput)
                          throws 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:

XMLStreamException

createSR

public XMLStreamReader2 createSR(ReaderConfig cfg,
                                 SystemId systemId,
                                 InputBootstrapper bs,
                                 boolean forER,
                                 boolean autoCloseInput)
                          throws XMLStreamException

Throws:

XMLStreamException

createSR

protected XMLStreamReader2 createSR(SystemId systemId,
                                    InputStream in,
                                    String enc,
                                    boolean forER,
                                    boolean autoCloseInput)
                             throws XMLStreamException

Throws:

XMLStreamException

createSR

protected XMLStreamReader2 createSR(ReaderConfig cfg,
                                    URL src,
                                    boolean forER,
                                    boolean autoCloseInput)
                             throws XMLStreamException

Throws:

XMLStreamException

createSR

protected XMLStreamReader2 createSR(SystemId systemId,
                                    Reader r,
                                    boolean forER,
                                    boolean autoCloseInput)
                             throws XMLStreamException

Throws:

XMLStreamException

createSR

protected XMLStreamReader2 createSR(File f,
                                    boolean forER,
                                    boolean autoCloseInput)
                             throws XMLStreamException

Throws:

XMLStreamException

createSR

protected XMLStreamReader2 createSR(Source src,
                                    boolean forER)
                             throws 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.

Parameters:

forER - True, if the reader is being constructed to be used by an event reader; false if it is not (or the purpose is not known)

Throws:

XMLStreamException

createEventAllocator

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