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 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 String IMPL_NAME
           
protected static String IMPL_VERSION
          This is "major.minor" version used for purposes of determining the feature set.
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_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
 
Method Summary
protected  boolean _hasConfigFlag(int flag)
           
protected  boolean _hasExplicitConfigFlag(int flag)
          Method similar to _hasConfigFlag(int), but that will only return true if in addition to being set, flag has been explicitly modified (i.e.
 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()
           
protected  boolean doesSupportXmlId()
           
 void doInternNames(boolean state)
           
 void doInternNsURIs(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 doTreatCharRefsAsEnts(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.
 EntityDecl findCustomInternalEntity(String id)
           
protected  int findPropertyId(String propName)
           
protected  int findStdPropertyId(String propName)
           
 void freeFullBBuffer(byte[] buffer)
           
 void freeFullCBuffer(char[] buffer)
           
 void freeMediumCBuffer(char[] buffer)
           
 void freeSmallCBuffer(char[] buffer)
           
 URL getBaseURL()
           
 int getConfigFlags()
           
 Map getCustomInternalEntities()
           
 int getDtdCacheSize()
          In future this property could/should be made configurable?
 DTDEventListener getDTDEventListener()
           
 DTDValidationSchema getDTDOverride()
           
 XMLResolver getDtdResolver()
           
 XMLResolver getEntityResolver()
           
static String getImplName()
          Method used to figure out the official implementation name for input/output/validation factories.
static String getImplVersion()
          Method used to figure out the official implementation version for input/output/validation factories.
 int getInputBufferLength()
           
 WstxInputProperties.ParsingMode getInputParsingMode()
           
 Object getProperty(int id)
           
 Object getProperty(String propName)
           
 int getShortestReportedTextSegment()
           
protected  Object getStdProperty(int id)
           
 SymbolTable getSymbols()
           
 XMLResolver getUndeclaredEntityResolver()
           
 XMLReporter getXMLReporter()
           
 XMLResolver getXMLResolver()
           
 boolean hasInternNamesBeenEnabled()
          Special accessor to use to verify whether name interning has explicitly been enabled; true if call was been made to set it to true; false otherwise (default, or set to false)
 boolean hasInternNsURIsBeenEnabled()
           
 boolean inputParsingModeDocuments()
           
 boolean inputParsingModeFragment()
           
 boolean isPropertySupported(String propName)
           
 boolean isXml11()
           
protected  void reportUnknownProperty(String propName)
           
 void resetState()
          Unlike name suggests there is also some limited state information associated with the config object.
protected  boolean returnNullForDefaultNamespace()
           
 Object safeGetProperty(String propName)
           
 void setBaseURL(URL baseURL)
           
 void setConfigFlag(int flag)
           
 void setCustomInternalEntities(Map m)
           
 void setDTDEventListener(DTDEventListener l)
           
 void setDTDOverride(DTDValidationSchema schema)
           
 void setDtdResolver(XMLResolver r)
           
 void setEntityResolver(XMLResolver r)
           
 void setInputBufferLength(int value)
           
 void setInputParsingMode(WstxInputProperties.ParsingMode mode)
           
 boolean setProperty(String propName, int id, Object value)
           
 boolean setProperty(String propName, Object value)
           
 void setShortestReportedTextSegment(int value)
           
protected  boolean setStdProperty(String propName, int id, Object value)
           
 void setUndeclaredEntityResolver(XMLResolver r)
           
 void setXMLReporter(XMLReporter r)
           
 void setXMLResolver(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 willNormalizeLFs()
           
 boolean willParseLazily()
           
 boolean willPreserveLocation()
           
 boolean willReplaceEntityRefs()
           
 boolean willReportCData()
           
 boolean willReportPrologWhitespace()
           
 boolean willSupportDTDPP()
           
 boolean willSupportDTDs()
           
 boolean willSupportExternalEntities()
           
 boolean willSupportNamespaces()
           
 boolean willTreatCharRefsAsEnts()
           
 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 String IMPL_NAME
See Also:
Constant Field Values

IMPL_VERSION

protected static final String IMPL_VERSION
This is "major.minor" version used for purposes of determining the feature set. Patch level is not included, since those should not affect API or feature set. Using applications should be prepared to take additional levels, however, just not depend on those being available.

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(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()

willCoalesceText

public boolean willCoalesceText()

willSupportNamespaces

public boolean willSupportNamespaces()

willReplaceEntityRefs

public boolean willReplaceEntityRefs()

willSupportExternalEntities

public boolean willSupportExternalEntities()

willSupportDTDs

public boolean willSupportDTDs()

willValidateWithDTD

public boolean willValidateWithDTD()

willReportCData

public boolean willReportCData()

willParseLazily

public boolean willParseLazily()

willInternNames

public boolean willInternNames()

willInternNsURIs

public boolean willInternNsURIs()

willPreserveLocation

public boolean willPreserveLocation()

willAutoCloseInput

public boolean willAutoCloseInput()

willReportPrologWhitespace

public boolean willReportPrologWhitespace()

willCacheDTDs

public boolean willCacheDTDs()

willCacheDTDsByPublicId

public boolean willCacheDTDsByPublicId()

willDoXmlIdTyping

public boolean willDoXmlIdTyping()

willDoXmlIdUniqChecks

public boolean willDoXmlIdUniqChecks()

willSupportDTDPP

public boolean willSupportDTDPP()

willNormalizeLFs

public boolean willNormalizeLFs()

willTreatCharRefsAsEnts

public boolean willTreatCharRefsAsEnts()

getInputBufferLength

public int getInputBufferLength()

getShortestReportedTextSegment

public int getShortestReportedTextSegment()

getCustomInternalEntities

public Map getCustomInternalEntities()

findCustomInternalEntity

public EntityDecl findCustomInternalEntity(String id)

getXMLReporter

public XMLReporter getXMLReporter()

getXMLResolver

public XMLResolver getXMLResolver()

getDtdResolver

public XMLResolver getDtdResolver()

getEntityResolver

public XMLResolver getEntityResolver()

getUndeclaredEntityResolver

public XMLResolver getUndeclaredEntityResolver()

getBaseURL

public 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()

getDTDOverride

public DTDValidationSchema getDTDOverride()

hasInternNamesBeenEnabled

public boolean hasInternNamesBeenEnabled()
Special accessor to use to verify whether name interning has explicitly been enabled; true if call was been made to set it to true; false otherwise (default, or set to false)


hasInternNsURIsBeenEnabled

public boolean hasInternNsURIsBeenEnabled()

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)

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)

doTreatCharRefsAsEnts

public void doTreatCharRefsAsEnts(boolean state)

doNormalizeLFs

public void doNormalizeLFs(boolean state)

setInputBufferLength

public void setInputBufferLength(int value)

setShortestReportedTextSegment

public void setShortestReportedTextSegment(int value)

setCustomInternalEntities

public void setCustomInternalEntities(Map m)

setXMLReporter

public void setXMLReporter(XMLReporter r)

setXMLResolver

public void setXMLResolver(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(XMLResolver r)

setEntityResolver

public void setEntityResolver(XMLResolver r)

setUndeclaredEntityResolver

public void setUndeclaredEntityResolver(XMLResolver r)

setBaseURL

public void setBaseURL(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)

setDTDOverride

public void setDTDOverride(DTDValidationSchema schema)

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:

  • Enable P_CACHE_DTDS.
  • Enable XMLStremaFactory2.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:

  • 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)
  • Sets P_TREAT_CHAR_REFS_AS_ENTS to true, so the all the original character references are reported with their position, original text, and the replacement text.


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 Object getProperty(int id)

setProperty

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

_hasConfigFlag

protected boolean _hasConfigFlag(int flag)

_hasExplicitConfigFlag

protected boolean _hasExplicitConfigFlag(int flag)
Method similar to _hasConfigFlag(int), but that will only return true if in addition to being set, flag has been explicitly modified (i.e. setProperty has been called to modify it)


getProperty

public Object getProperty(String propName)

isPropertySupported

public boolean isPropertySupported(String propName)

setProperty

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

reportUnknownProperty

protected void reportUnknownProperty(String propName)

safeGetProperty

public final Object safeGetProperty(String propName)

getImplName

public static String getImplName()
Method used to figure out the official implementation name for input/output/validation factories.


getImplVersion

public static String getImplVersion()
Method used to figure out the official implementation version for input/output/validation factories.


doesSupportXml11

protected boolean doesSupportXml11()

doesSupportXmlId

protected boolean doesSupportXmlId()

returnNullForDefaultNamespace

protected boolean returnNullForDefaultNamespace()

findStdPropertyId

protected int findStdPropertyId(String propName)

setStdProperty

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

getStdProperty

protected Object getStdProperty(int id)