com.ctc.wstx.stax
Class WstxInputFactory

java.lang.Object
  extended by javax.xml.stream.XMLInputFactory
      extended by org.codehaus.stax2.XMLInputFactory2
          extended by 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:


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:

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:

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:

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:

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:

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.