com.ctc.wstx.api
Class ReaderConfig

java.lang.Object
  extended by com.ctc.wstx.api.ReaderConfig
All Implemented Interfaces:
InputConfigFlags, XMLStreamProperties

public final class ReaderConfig
extends java.lang.Object
implements InputConfigFlags

Simple configuration container class; passed by reader factory to reader instance created.

In addition to its main task as a configuration container, this class also acts as a wrapper around simple buffer recycling functionality. The reason is that while conceptually this is a separate concern, there are enough commonalities with the life-cycle of this object to make this a very convenience place to add that functionality... (that is: conceptually this is not right, but from pragmatic viewpoint it just makes sense)


Field Summary
protected static java.lang.String IMPL_NAME
           
protected static java.lang.String IMPL_VERSION
           
static int PROP_EVENT_ALLOCATOR
           
 
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
 
Method Summary
 byte[] allocFullBBuffer(int minSize)
           
 char[] allocFullCBuffer(int minSize)
           
 char[] allocMediumCBuffer(int minSize)
           
 char[] allocSmallCBuffer(int minSize)
           
 void clearConfigFlag(int flag)
           
 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 (linefeed conversions, attr value normalizations).
static ReaderConfig createFullDefaults()
           
static ReaderConfig createJ2MEDefaults()
           
 ReaderConfig createNonShared(SymbolTable sym)
           
 void doAutoCloseInput(boolean state)
           
 void doCacheDTDs(boolean state)
           
 void doCacheDTDsByPublicId(boolean state)
           
 void doCoalesceText(boolean state)
           
protected  boolean doesSupportXml11()
           
 void doInternNames(boolean state)
           
 void doInternNsURIs(boolean state)
           
 void doNormalizeAttrValues(boolean state)
           
 void doNormalizeLFs(boolean state)
           
 void doParseLazily(boolean state)
           
 void doPreserveLocation(boolean state)
           
 void doReplaceEntityRefs(boolean state)
           
 void doReportCData(boolean state)
           
 void doReportPrologWhitespace(boolean state)
           
 void doSupportDTDPP(boolean state)
           
 void doSupportDTDs(boolean state)
           
 void doSupportExternalEntities(boolean state)
           
 void doSupportNamespaces(boolean state)
           
 void doValidateWithDTD(boolean state)
           
 void doXmlIdTyping(boolean state)
           
 void doXmlIdUniqChecks(boolean state)
           
 void enableXml11(boolean state)
          Method called to enable or disable 1.1 compliant processing; if disabled, defaults to xml 1.0 compliant processing.
protected  int findPropertyId(java.lang.String propName)
           
protected  int findStdPropertyId(java.lang.String propName)
           
 void freeFullBBuffer(byte[] buffer)
           
 void freeFullCBuffer(char[] buffer)
           
 void freeMediumCBuffer(char[] buffer)
           
 void freeSmallCBuffer(char[] buffer)
           
 java.net.URL getBaseURL()
           
 int getConfigFlags()
           
 java.util.Map getCustomInternalEntities()
           
 int getDtdCacheSize()
          In future this property could/should be made configurable?
 DTDEventListener getDTDEventListener()
           
 javax.xml.stream.XMLResolver getDtdResolver()
           
 javax.xml.stream.XMLResolver getEntityResolver()
           
 int getInputBufferLength()
           
 WstxInputProperties.ParsingMode getInputParsingMode()
           
 java.lang.Object getProperty(int id)
           
 java.lang.Object getProperty(java.lang.String propName)
           
 int getShortestReportedTextSegment()
           
protected  java.lang.Object getStdProperty(int id)
           
 SymbolTable getSymbols()
           
 javax.xml.stream.XMLResolver getUndeclaredEntityResolver()
           
 javax.xml.stream.XMLReporter getXMLReporter()
           
 javax.xml.stream.XMLResolver getXMLResolver()
           
 boolean hasConfigFlags(int flags)
           
 boolean inputParsingModeDocuments()
           
 boolean inputParsingModeFragment()
           
 boolean isPropertySupported(java.lang.String propName)
           
 boolean isXml11()
           
 void resetState()
          Unlike name suggests there is also some limited state information associated with the config object.
 void setBaseURL(java.net.URL baseURL)
           
 void setConfigFlag(int flag)
           
 void setConfigFlags(int flags)
           
 void setCustomInternalEntities(java.util.Map m)
           
 void setDTDEventListener(DTDEventListener l)
           
 void setDtdResolver(javax.xml.stream.XMLResolver r)
           
 void setEntityResolver(javax.xml.stream.XMLResolver r)
           
 void setInputBufferLength(int value)
           
 void setInputParsingMode(WstxInputProperties.ParsingMode mode)
           
 boolean setProperty(java.lang.String propName, int id, java.lang.Object value)
           
 boolean setProperty(java.lang.String propName, java.lang.Object value)
           
 void setShortestReportedTextSegment(int value)
           
protected  boolean setStdProperty(java.lang.String propName, int id, java.lang.Object value)
           
 void setUndeclaredEntityResolver(javax.xml.stream.XMLResolver r)
           
 void setXMLReporter(javax.xml.stream.XMLReporter r)
           
 void setXMLResolver(javax.xml.stream.XMLResolver r)
          Note: for better granularity, you should call setEntityResolver(javax.xml.stream.XMLResolver) and setDtdResolver(javax.xml.stream.XMLResolver) instead.
 boolean willAutoCloseInput()
           
 boolean willCacheDTDs()
           
 boolean willCacheDTDsByPublicId()
           
 boolean willCoalesceText()
           
 boolean willDoXmlIdTyping()
           
 boolean willDoXmlIdUniqChecks()
           
 boolean willInternNames()
           
 boolean willInternNsURIs()
           
 boolean willNormalizeAttrValues()
           
 boolean willNormalizeLFs()
           
 boolean willParseLazily()
           
 boolean willPreserveLocation()
           
 boolean willReplaceEntityRefs()
           
 boolean willReportCData()
           
 boolean willReportPrologWhitespace()
           
 boolean willSupportDTDPP()
           
 boolean willSupportDTDs()
           
 boolean willSupportExternalEntities()
           
 boolean willSupportNamespaces()
           
 boolean willValidateWithDTD()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PROP_EVENT_ALLOCATOR

public static final int PROP_EVENT_ALLOCATOR
See Also:
Constant Field Values

IMPL_NAME

protected static final java.lang.String IMPL_NAME
See Also:
Constant Field Values

IMPL_VERSION

protected static final java.lang.String IMPL_VERSION
See Also:
Constant Field Values
Method Detail

createJ2MEDefaults

public static ReaderConfig createJ2MEDefaults()

createFullDefaults

public static ReaderConfig createFullDefaults()

createNonShared

public ReaderConfig createNonShared(SymbolTable sym)

resetState

public void resetState()
Unlike name suggests there is also some limited state information associated with the config object. If these objects are reused, that state needs to be reset between reuses, to avoid carrying over incorrect state.


findPropertyId

protected int findPropertyId(java.lang.String propName)
Returns:
Internal enumerated int matching the String name of the property, if one found: -1 to indicate no match was found.

getSymbols

public SymbolTable getSymbols()

getDtdCacheSize

public int getDtdCacheSize()
In future this property could/should be made configurable?


getConfigFlags

public int getConfigFlags()

hasConfigFlags

public boolean hasConfigFlags(int flags)

willCoalesceText

public boolean willCoalesceText()

willSupportNamespaces

public boolean willSupportNamespaces()

willReplaceEntityRefs

public boolean willReplaceEntityRefs()

willSupportExternalEntities

public boolean willSupportExternalEntities()

willSupportDTDs

public boolean willSupportDTDs()

willValidateWithDTD

public boolean willValidateWithDTD()

willNormalizeLFs

public boolean willNormalizeLFs()

willNormalizeAttrValues

public boolean willNormalizeAttrValues()

willInternNames

public boolean willInternNames()

willInternNsURIs

public boolean willInternNsURIs()

willReportCData

public boolean willReportCData()

willReportPrologWhitespace

public boolean willReportPrologWhitespace()

willCacheDTDs

public boolean willCacheDTDs()

willCacheDTDsByPublicId

public boolean willCacheDTDsByPublicId()

willParseLazily

public boolean willParseLazily()

willDoXmlIdTyping

public boolean willDoXmlIdTyping()

willDoXmlIdUniqChecks

public boolean willDoXmlIdUniqChecks()

willPreserveLocation

public boolean willPreserveLocation()

willAutoCloseInput

public boolean willAutoCloseInput()

willSupportDTDPP

public boolean willSupportDTDPP()

getInputBufferLength

public int getInputBufferLength()

getShortestReportedTextSegment

public int getShortestReportedTextSegment()

getCustomInternalEntities

public java.util.Map getCustomInternalEntities()

getXMLReporter

public javax.xml.stream.XMLReporter getXMLReporter()

getXMLResolver

public javax.xml.stream.XMLResolver getXMLResolver()

getDtdResolver

public javax.xml.stream.XMLResolver getDtdResolver()

getEntityResolver

public javax.xml.stream.XMLResolver getEntityResolver()

getUndeclaredEntityResolver

public javax.xml.stream.XMLResolver getUndeclaredEntityResolver()

getBaseURL

public java.net.URL getBaseURL()

getInputParsingMode

public WstxInputProperties.ParsingMode getInputParsingMode()

inputParsingModeDocuments

public boolean inputParsingModeDocuments()

inputParsingModeFragment

public boolean inputParsingModeFragment()

isXml11

public boolean isXml11()
Returns:
True if the input well-formedness and validation checks should be done according to xml 1.1 specification; false if xml 1.0 specification.

getDTDEventListener

public DTDEventListener getDTDEventListener()

setConfigFlags

public void setConfigFlags(int flags)

setConfigFlag

public void setConfigFlag(int flag)

clearConfigFlag

public void clearConfigFlag(int flag)

doCoalesceText

public void doCoalesceText(boolean state)

doSupportNamespaces

public void doSupportNamespaces(boolean state)

doReplaceEntityRefs

public void doReplaceEntityRefs(boolean state)

doSupportExternalEntities

public void doSupportExternalEntities(boolean state)

doSupportDTDs

public void doSupportDTDs(boolean state)

doValidateWithDTD

public void doValidateWithDTD(boolean state)

doNormalizeLFs

public void doNormalizeLFs(boolean state)

doNormalizeAttrValues

public void doNormalizeAttrValues(boolean state)

doInternNames

public void doInternNames(boolean state)

doInternNsURIs

public void doInternNsURIs(boolean state)

doReportPrologWhitespace

public void doReportPrologWhitespace(boolean state)

doReportCData

public void doReportCData(boolean state)

doCacheDTDs

public void doCacheDTDs(boolean state)

doCacheDTDsByPublicId

public void doCacheDTDsByPublicId(boolean state)

doParseLazily

public void doParseLazily(boolean state)

doXmlIdTyping

public void doXmlIdTyping(boolean state)

doXmlIdUniqChecks

public void doXmlIdUniqChecks(boolean state)

doPreserveLocation

public void doPreserveLocation(boolean state)

doAutoCloseInput

public void doAutoCloseInput(boolean state)

doSupportDTDPP

public void doSupportDTDPP(boolean state)

setInputBufferLength

public void setInputBufferLength(int value)

setShortestReportedTextSegment

public void setShortestReportedTextSegment(int value)

setCustomInternalEntities

public void setCustomInternalEntities(java.util.Map m)

setXMLReporter

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

setXMLResolver

public void setXMLResolver(javax.xml.stream.XMLResolver r)
Note: for better granularity, you should call setEntityResolver(javax.xml.stream.XMLResolver) and setDtdResolver(javax.xml.stream.XMLResolver) instead.


setDtdResolver

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

setEntityResolver

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

setUndeclaredEntityResolver

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

setBaseURL

public void setBaseURL(java.net.URL baseURL)

setInputParsingMode

public void setInputParsingMode(WstxInputProperties.ParsingMode mode)

enableXml11

public void enableXml11(boolean state)
Method called to enable or disable 1.1 compliant processing; if disabled, defaults to xml 1.0 compliant processing.


setDTDEventListener

public void setDTDEventListener(DTDEventListener l)

configureForXmlConformance

public void configureForXmlConformance()
Method to call to make Reader created conform as closely to XML standard as possible, doing all checks and transformations mandated (linefeed conversions, attr value normalizations). See XMLInputFactory2.configureForXmlConformance() for required settings for standard StAX/StAX properties.

In addition to the standard settings, following Woodstox-specific settings are also done:

Notes: Does NOT change 'performance' settings (buffer sizes, DTD caching, coalescing, interning, accurate location info).


configureForConvenience

public 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. This may incur some slight performance penalties, but should not affect XML conformance. See XMLInputFactory2.configureForConvenience() for required settings for standard StAX/StAX properties.

In addition to the standard settings, following Woodstox-specific settings are also done:


configureForSpeed

public 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. See XMLInputFactory2.configureForSpeed() for required settings for standard StAX/StAX properties.

In addition to the standard settings, following Woodstox-specific settings are also done:

  • Disable P_NORMALIZE_LFS
  • Disable P_NORMALIZE_ATTR_VALUES
  • Enable P_CACHE_DTDS.
  • Enable P_LAZY_PARSING (can improve performance especially when skipping text segments)
  • Disable Xml:id uniqueness checks (and leave typing as is)
  • Set lowish value for P_MIN_TEXT_SEGMENT, to allow reader to optimize segment length it uses (and possibly avoids one copy operation in the process)
  • Increase P_INPUT_BUFFER_LENGTH a bit from default, to allow for longer consequtive read operations; also reduces cases where partial text segments are on input buffer boundaries.


configureForLowMemUsage

public 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. This generally incurs some performance penalties, due to using smaller input buffers.

See XMLInputFactory2.configureForLowMemUsage() for required settings for standard StAX/StAX properties.

In addition to the standard settings, following Woodstox-specific settings are also done:

  • Disable P_CACHE_DTDS
  • Enable P_PARSE_LAZILY
  • Resets P_MIN_TEXT_SEGMENT to the (somewhat low) default value.
  • Reduces P_INPUT_BUFFER_LENGTH a bit from the default


configureForRoundTripping

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

See XMLInputFactory2.configureForLowMemUsage() for required settings for standard StAX/StAX properties.

In addition to the standard settings, following Woodstox-specific settings are also done:

  • Disable P_NORMALIZE_LFS
  • Disable P_NORMALIZE_ATTR_VALUES
  • Increases P_MIN_TEXT_SEGMENT to the maximum value so that all original text segment chunks are reported without segmentation (but without coalescing with adjacent CDATA segments)


allocSmallCBuffer

public char[] allocSmallCBuffer(int minSize)

freeSmallCBuffer

public void freeSmallCBuffer(char[] buffer)

allocMediumCBuffer

public char[] allocMediumCBuffer(int minSize)

freeMediumCBuffer

public void freeMediumCBuffer(char[] buffer)

allocFullCBuffer

public char[] allocFullCBuffer(int minSize)

freeFullCBuffer

public void freeFullCBuffer(char[] buffer)

allocFullBBuffer

public byte[] allocFullBBuffer(int minSize)

freeFullBBuffer

public void freeFullBBuffer(byte[] buffer)

getProperty

public java.lang.Object getProperty(int id)

setProperty

public boolean setProperty(java.lang.String propName,
                           int id,
                           java.lang.Object value)

getProperty

public final java.lang.Object getProperty(java.lang.String propName)

isPropertySupported

public final boolean isPropertySupported(java.lang.String propName)

setProperty

public final boolean setProperty(java.lang.String propName,
                                 java.lang.Object value)
Returns:
True, if the specified property was succesfully set to specified value; false if its value was not changed

doesSupportXml11

protected boolean doesSupportXml11()

findStdPropertyId

protected int findStdPropertyId(java.lang.String propName)

setStdProperty

protected boolean setStdProperty(java.lang.String propName,
                                 int id,
                                 java.lang.Object value)

getStdProperty

protected java.lang.Object getStdProperty(int id)