Package com.ctc.wstx.api

Class ReaderConfig

  • All Implemented Interfaces:
    InputConfigFlags, org.codehaus.stax2.XMLStreamProperties
    public final class ReaderConfig
extends CommonConfig
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 Detail

      • DEFAULT_MAX_ATTRIBUTES_PER_ELEMENT

        public static final int DEFAULT_MAX_ATTRIBUTES_PER_ELEMENT
        See Also:
        Constant Field Values

      • DEFAULT_MAX_ATTRIBUTE_LENGTH

        public static final int DEFAULT_MAX_ATTRIBUTE_LENGTH
        See Also:
        Constant Field Values

      • DEFAULT_MAX_ELEMENT_DEPTH

        public static final int DEFAULT_MAX_ELEMENT_DEPTH
        See Also:
        Constant Field Values

      • DEFAULT_MAX_ENTITY_DEPTH

        public static final int DEFAULT_MAX_ENTITY_DEPTH
        See Also:
        Constant Field Values

      • DEFAULT_MAX_ENTITY_COUNT

        public static final int DEFAULT_MAX_ENTITY_COUNT
        See Also:
        Constant Field Values

      • PROP_SUPPORT_EXTERNAL_ENTITIES

        static final int PROP_SUPPORT_EXTERNAL_ENTITIES
        See Also:
        Constant Field Values

      • PROP_JAXP_SECURE_PROCESSING

        static final int PROP_JAXP_SECURE_PROCESSING
        See Also:
        Constant Field Values

      • PROP_NORMALIZE_LFS

        static final int PROP_NORMALIZE_LFS
        Note: this entry was deprecated for 4.0 versions up until and including 4.0.7; was brought back for 4.0.8 (and will be retained for 4.1)
        See Also:
        Constant Field Values

      • PROP_CACHE_DTDS_BY_PUBLIC_ID

        static final int PROP_CACHE_DTDS_BY_PUBLIC_ID
        See Also:
        Constant Field Values

      • PROP_TREAT_CHAR_REFS_AS_ENTS

        static final int PROP_TREAT_CHAR_REFS_AS_ENTS
        See Also:
        Constant Field Values

      • PROP_ALLOW_XML11_ESCAPED_CHARS_IN_XML10

        static final int PROP_ALLOW_XML11_ESCAPED_CHARS_IN_XML10
        Since:
        5.2
        See Also:
        Constant Field Values

      • PROP_CUSTOM_INTERNAL_ENTITIES

        static final int PROP_CUSTOM_INTERNAL_ENTITIES
        See Also:
        Constant Field Values

      • PROP_UNDECLARED_ENTITY_RESOLVER

        static final int PROP_UNDECLARED_ENTITY_RESOLVER
        See Also:
        Constant Field Values

      • PROP_MAX_ATTRIBUTES_PER_ELEMENT

        static final int PROP_MAX_ATTRIBUTES_PER_ELEMENT
        See Also:
        Constant Field Values

      • PROP_MAX_CHILDREN_PER_ELEMENT

        static final int PROP_MAX_CHILDREN_PER_ELEMENT
        See Also:
        Constant Field Values

      • MIN_INPUT_BUFFER_LENGTH

        static final int MIN_INPUT_BUFFER_LENGTH
        Need to set a minimum size, since there are some limitations to smallest consequtive block that can be used.
        See Also:
        Constant Field Values

      • DTD_CACHE_SIZE_J2SE

        static final int DTD_CACHE_SIZE_J2SE
        Let's allow caching of just a dozen DTDs... shouldn't really matter, how many DTDs does one really use?
        See Also:
        Constant Field Values

      • DEFAULT_SHORTEST_TEXT_SEGMENT

        static final int DEFAULT_SHORTEST_TEXT_SEGMENT
        By default, let's require minimum of 64 chars to be delivered as shortest partial (piece of) text (CDATA, text) segment; same for both J2ME subset and full readers. Prevents tiniest runts from getting passed
        See Also:
        Constant Field Values

      • DEFAULT_FLAGS_FULL

        static final int DEFAULT_FLAGS_FULL
        Default config flags are converted from individual settings, to conform to StAX 1.0 specifications.
        See Also:
        Constant Field Values

      • DEFAULT_FLAGS_J2ME

        static final int DEFAULT_FLAGS_J2ME
        For now defaults for J2ME flags can be identical to 'full' set; differences are in buffer sizes.
        See Also:
        Constant Field Values

      • sProperties

        static final java.util.HashMap<java.lang.String,​java.lang.Integer> sProperties
        Map to use for converting from String property ids to ints described above; useful to allow use of switch later on.

      • mIsJ2MESubset

        protected final boolean mIsJ2MESubset

      • mConfigFlags

        protected int mConfigFlags
        Bitset that contains state of on/off properties; initialized to defaults, but can be set/cleared.

      • mConfigFlagMods

        protected int mConfigFlagMods
        Bitset that indicates explicit changes to mConfigFlags through calls; empty bit means that the corresponding property has its default value, set bit that an explicit call has been made.

      • PROP_INTERN_NAMES_EXPLICIT

        static final int PROP_INTERN_NAMES_EXPLICIT
        13-Nov-2008, tatus: Need to be able to keep track of whether name-interning has been explicitly enabled/disable or not (not if it's whatever defaults we have)
        See Also:
        Constant Field Values

      • PROP_INTERN_NS_URIS_EXPLICIT

        static final int PROP_INTERN_NS_URIS_EXPLICIT
        See Also:
        Constant Field Values

      • mInputBufferLen

        protected int mInputBufferLen

      • mMinTextSegmentLen

        protected int mMinTextSegmentLen

      • mMaxAttributesPerElement

        protected int mMaxAttributesPerElement

      • mMaxAttributeSize

        protected int mMaxAttributeSize

      • mMaxChildrenPerElement

        protected int mMaxChildrenPerElement

      • mMaxElementDepth

        protected int mMaxElementDepth

      • mMaxElementCount

        protected long mMaxElementCount

      • mMaxCharacters

        protected long mMaxCharacters

      • mMaxTextLength

        protected int mMaxTextLength

      • mMaxEntityDepth

        protected int mMaxEntityDepth

      • mMaxEntityCount

        protected long mMaxEntityCount

      • mBaseURL

        protected java.net.URL mBaseURL
        Base URL to use as the resolution context for relative entity references

      • mParsingMode

        protected WstxInputProperties.ParsingMode mParsingMode
        Parsing mode can be changed from the default xml compliant behavior to one of alternate modes (fragment processing, multiple document processing).

      • mXml11

        protected boolean mXml11
        This boolean flag is set if the input document requires xml 1.1 (or above) compliant processing: default is xml 1.0 compliant. Note that unlike most other properties, this does not come from configuration settings, but from processed document itself.

      • mReporter

        javax.xml.stream.XMLReporter mReporter

      • mDtdResolver

        javax.xml.stream.XMLResolver mDtdResolver

      • mEntityResolver

        javax.xml.stream.XMLResolver mEntityResolver

      • mSpecialProperties

        java.lang.Object[] mSpecialProperties

      • SP_IX_UNDECL_ENT_RESOLVER

        private static final int SP_IX_UNDECL_ENT_RESOLVER
        See Also:
        Constant Field Values

      • SP_IX_DTD_EVENT_LISTENER

        private static final int SP_IX_DTD_EVENT_LISTENER
        See Also:
        Constant Field Values

      • mRecyclerRef

        static final java.lang.ThreadLocal<java.lang.ref.SoftReference<BufferRecycler>> mRecyclerRef
        This ThreadLocal contains a SoftRerefence to a BufferRecycler used to provide a low-cost buffer recycling between Reader instances.

      • mCurrRecycler

        BufferRecycler mCurrRecycler
        This is the actually container of the recyclable buffers. It is obtained via ThreadLocal/SoftReference combination, if one exists, when Config instance is created. If one does not exist, it will created first time a buffer is returned.

    • Constructor Detail

      • ReaderConfig

        private ReaderConfig​(ReaderConfig base,
                     boolean j2meSubset,
                     SymbolTable symbols,
                     int configFlags,
                     int configFlagMods,
                     int inputBufLen,
                     int minTextSegmentLen)

    • Method Detail

      • createJ2MEDefaults

        public static ReaderConfig createJ2MEDefaults()

      • createFullDefaults

        public static ReaderConfig createFullDefaults()

      • 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)
        Specified by:
        findPropertyId in class CommonConfig
        Returns:
        Internal enumerated int matching the String name of the property, if one found: -1 to indicate no match was found.

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

      • willProcessSecurely

        public boolean willProcessSecurely()

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

      • willAllowXml11EscapedCharsInXml10

        public boolean willAllowXml11EscapedCharsInXml10()

      • getInputBufferLength

        public int getInputBufferLength()

      • getShortestReportedTextSegment

        public int getShortestReportedTextSegment()

      • getMaxAttributesPerElement

        public int getMaxAttributesPerElement()

      • getMaxAttributeSize

        public int getMaxAttributeSize()

      • getMaxChildrenPerElement

        public int getMaxChildrenPerElement()

      • getMaxElementDepth

        public int getMaxElementDepth()

      • getMaxElementCount

        public long getMaxElementCount()

      • getMaxEntityDepth

        public int getMaxEntityDepth()

      • getMaxEntityCount

        public long getMaxEntityCount()

      • getMaxCharacters

        public long getMaxCharacters()

      • getMaxTextLength

        public long getMaxTextLength()

      • getCustomInternalEntities

        public java.util.Map<java.lang.String,​EntityDecl> getCustomInternalEntities()

      • findCustomInternalEntity

        public EntityDecl findCustomInternalEntity​(java.lang.String id)

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

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

      • getDTDOverride

        public org.codehaus.stax2.validation.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)

      • doProcessSecurely

        public void doProcessSecurely​(boolean value)
        Method called when {code XMLConstants.FEATURE_SECURE_PROCESSING} is being enabled or disabled.

        Note that disabling (passing {code false} as argument) does not actually change any settings.

        Calls made when true is passed (that is, secure processing enabled):

        • doSupportExternalEntities(false)
        Since:
        5.3

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

      • doAllowXml11EscapedCharsInXml10

        public void doAllowXml11EscapedCharsInXml10​(boolean state)

      • doNormalizeLFs

        public void doNormalizeLFs​(boolean state)

      • setInputBufferLength

        public void setInputBufferLength​(int value)

      • setShortestReportedTextSegment

        public void setShortestReportedTextSegment​(int value)

      • setMaxAttributesPerElement

        public void setMaxAttributesPerElement​(int value)

      • setMaxAttributeSize

        public void setMaxAttributeSize​(int value)

      • setMaxChildrenPerElement

        public void setMaxChildrenPerElement​(int value)

      • setMaxElementDepth

        public void setMaxElementDepth​(int value)

      • setMaxElementCount

        public void setMaxElementCount​(long value)

      • setMaxCharacters

        public void setMaxCharacters​(long value)

      • setMaxTextLength

        public void setMaxTextLength​(int value)

      • setMaxEntityDepth

        public void setMaxEntityDepth​(int value)

      • setMaxEntityCount

        public void setMaxEntityCount​(long value)

      • setCustomInternalEntities

        public void setCustomInternalEntities​(java.util.Map<java.lang.String,​?> m)

      • setXMLReporter

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

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

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

      • setDTDOverride

        public void setDTDOverride​(org.codehaus.stax2.validation.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:

        • None

        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:

        • Disable XMLStreamFactory2.P_LAZY_PARSING (to allow for synchronous error notification by forcing full XML events to be completely parsed when reader's next() is called)

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

      • setConfigFlag

        private void setConfigFlag​(int flag,
                           boolean state)

      • setProperty

        public boolean setProperty​(java.lang.String propName,
                           int id,
                           java.lang.Object value)
        Specified by:
        setProperty in class CommonConfig

      • _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)

      • _getSpecialProperty

        private final java.lang.Object _getSpecialProperty​(int ix)

      • _setSpecialProperty

        private final void _setSpecialProperty​(int ix,
                                       java.lang.Object value)