Class Stax2EventReaderImpl

  • All Implemented Interfaces:
    java.util.Iterator, javax.xml.stream.XMLEventReader, javax.xml.stream.XMLStreamConstants, XMLEventReader2

    public abstract class Stax2EventReaderImpl
    extends java.lang.Object
    implements XMLEventReader2, javax.xml.stream.XMLStreamConstants
    Almost complete implementation of XMLEventReader2, built on top of a generic XMLStreamReader implementation (using aggregation). Designed to be used by concrete Stax2 implementations to provide full Event API implementation with minimal effort.

    Since there is not much to optimize at this level (API and underlying stream reader pretty much define functionality and optimizations that can be done), implementation is fairly straight forward, with not many surprises.

    Implementation notes: the trickiest things to implement are:

    • Peek() functionality! Geez, why did that have to be part of StAX specs???!
    • Adding START_DOCUMENT event that cursor API does not return explicitly.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static int ERR_GETELEMTEXT_NON_TEXT_EVENT
      Encountered non-textual event (other than closing END_ELEMENT) when collecting text for getElementText()
      protected static int ERR_GETELEMTEXT_NOT_START_ELEM
      Current state when getElementText() called not START_ELEMENT
      protected static int ERR_NEXTTAG_NON_WS_TEXT
      Encountered CHARACTERS or CDATA that contains non-white space char(s), when trying to locate tag with nextTag()
      protected static int ERR_NEXTTAG_WRONG_TYPE
      Encountered non-skippable non-text/element event with nextTag()
      protected javax.xml.stream.util.XMLEventAllocator mAllocator  
      protected javax.xml.stream.events.XMLEvent mPeekedEvent
      Event that has been peeked, ie.
      protected int mPrePeekEvent
      This variable keeps track of the type of the 'previous' event when peeking for the next Event.
      protected XMLStreamReader2 mReader  
      protected int mState
      High-level state indicator, with currently three values: whether we are initializing (need to synthetize START_DOCUMENT), at END_OF_INPUT (end-of-doc), or otherwise, normal operation.
      protected static int STATE_CONTENT  
      protected static int STATE_END_OF_INPUT  
      protected static int STATE_INITIAL  
      • Fields inherited from interface javax.xml.stream.XMLStreamConstants

        ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected javax.xml.stream.XMLStreamException _checkUnwrap​(java.lang.RuntimeException rex)  
      void close()  
      protected javax.xml.stream.events.XMLEvent createNextEvent​(boolean checkEOD, int type)  
      protected javax.xml.stream.events.XMLEvent createStartDocumentEvent()
      Method called to create the very first event (START_DOCUMENT).
      protected java.lang.String findErrorDesc​(int errorType, int currEvent)
      Method used to locate error message description to use.
      java.lang.String getElementText()  
      protected abstract java.lang.String getErrorDesc​(int errorType, int eventType)
      Method called upon encountering a problem that should result in an exception being thrown.
      java.lang.Object getProperty​(java.lang.String name)  
      protected javax.xml.stream.XMLStreamReader getStreamReader()  
      boolean hasNext()  
      boolean hasNextEvent()
      Note: although the interface allows implementations to throw an XMLStreamException, the reference implementation doesn't currently need to.
      abstract boolean isPropertySupported​(java.lang.String name)
      Method similar to XMLInputFactory.isPropertySupported(java.lang.String), used to determine whether a property is supported by the Reader instance.
      java.lang.Object next()  
      javax.xml.stream.events.XMLEvent nextEvent()  
      javax.xml.stream.events.XMLEvent nextTag()  
      javax.xml.stream.events.XMLEvent peek()  
      void remove()
      Note: only here because we implement Iterator interface.
      protected void reportProblem​(java.lang.String msg)  
      protected void reportProblem​(java.lang.String msg, javax.xml.stream.Location loc)  
      abstract boolean setProperty​(java.lang.String name, java.lang.Object value)
      Method that can be used to set per-reader properties; a subset of properties one can set via matching XMLInputFactory2 instance.
      protected void throwEndOfInput()  
      protected void throwUnchecked​(javax.xml.stream.XMLStreamException sex)  
      protected void updateStateEndDocument()
      Method called when we are about to return END_DOCUMENT event.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
      • Methods inherited from interface java.util.Iterator

        forEachRemaining
    • Field Detail

      • ERR_GETELEMTEXT_NOT_START_ELEM

        protected static final int ERR_GETELEMTEXT_NOT_START_ELEM
        Current state when getElementText() called not START_ELEMENT
        See Also:
        Constant Field Values
      • ERR_GETELEMTEXT_NON_TEXT_EVENT

        protected static final int ERR_GETELEMTEXT_NON_TEXT_EVENT
        Encountered non-textual event (other than closing END_ELEMENT) when collecting text for getElementText()
        See Also:
        Constant Field Values
      • ERR_NEXTTAG_NON_WS_TEXT

        protected static final int ERR_NEXTTAG_NON_WS_TEXT
        Encountered CHARACTERS or CDATA that contains non-white space char(s), when trying to locate tag with nextTag()
        See Also:
        Constant Field Values
      • ERR_NEXTTAG_WRONG_TYPE

        protected static final int ERR_NEXTTAG_WRONG_TYPE
        Encountered non-skippable non-text/element event with nextTag()
        See Also:
        Constant Field Values
      • mAllocator

        protected final javax.xml.stream.util.XMLEventAllocator mAllocator
      • mPeekedEvent

        protected javax.xml.stream.events.XMLEvent mPeekedEvent
        Event that has been peeked, ie. loaded without call to nextEvent(); will be returned and cleared by call to nextEvent() (or, returned again if peeked again)
      • mState

        protected int mState
        High-level state indicator, with currently three values: whether we are initializing (need to synthetize START_DOCUMENT), at END_OF_INPUT (end-of-doc), or otherwise, normal operation. Useful in simplifying some methods, as well as to make sure that independent of how stream reader handles things, event reader can reliably detect End-Of-Document.
      • mPrePeekEvent

        protected int mPrePeekEvent
        This variable keeps track of the type of the 'previous' event when peeking for the next Event. It is needed for some functionality, to remember state even when underlying parser has to move to peek the next event.
    • Constructor Detail

      • Stax2EventReaderImpl

        protected Stax2EventReaderImpl​(javax.xml.stream.util.XMLEventAllocator a,
                                       XMLStreamReader2 r)
    • Method Detail

      • isPropertySupported

        public abstract boolean isPropertySupported​(java.lang.String name)
        Description copied from interface: XMLEventReader2
        Method similar to XMLInputFactory.isPropertySupported(java.lang.String), used to determine whether a property is supported by the Reader instance. This means that this method may return false for some properties that the input factory does support: specifically, it should only return true if the value is mutable on per-instance basis. False means that either the property is not recognized, or is not mutable via reader instance.
        Specified by:
        isPropertySupported in interface XMLEventReader2
      • setProperty

        public abstract boolean setProperty​(java.lang.String name,
                                            java.lang.Object value)
        Description copied from interface: XMLEventReader2
        Method that can be used to set per-reader properties; a subset of properties one can set via matching XMLInputFactory2 instance. Exactly which methods are mutable is implementation specific.
        Specified by:
        setProperty in interface XMLEventReader2
        Parameters:
        name - Name of the property to set
        value - Value to set property to.
        Returns:
        True, if the specified property was succesfully set to specified value; false if its value was not changed
      • getErrorDesc

        protected abstract java.lang.String getErrorDesc​(int errorType,
                                                         int eventType)
        Method called upon encountering a problem that should result in an exception being thrown. If non-null String is returned. that will be used as the message of exception thrown; if null, a standard message will be used instead.
        Parameters:
        errorType - Type of the problem, one of ERR_ constants
        eventType - Type of the event that triggered the problem, if any; -1 if not available.
      • close

        public void close()
                   throws javax.xml.stream.XMLStreamException
        Specified by:
        close in interface javax.xml.stream.XMLEventReader
        Throws:
        javax.xml.stream.XMLStreamException
      • getElementText

        public java.lang.String getElementText()
                                        throws javax.xml.stream.XMLStreamException
        Specified by:
        getElementText in interface javax.xml.stream.XMLEventReader
        Throws:
        javax.xml.stream.XMLStreamException
      • getProperty

        public java.lang.Object getProperty​(java.lang.String name)
        Specified by:
        getProperty in interface javax.xml.stream.XMLEventReader
      • hasNext

        public boolean hasNext()
        Specified by:
        hasNext in interface java.util.Iterator
        Specified by:
        hasNext in interface javax.xml.stream.XMLEventReader
      • nextEvent

        public javax.xml.stream.events.XMLEvent nextEvent()
                                                   throws javax.xml.stream.XMLStreamException
        Specified by:
        nextEvent in interface javax.xml.stream.XMLEventReader
        Throws:
        javax.xml.stream.XMLStreamException
      • next

        public java.lang.Object next()
        Specified by:
        next in interface java.util.Iterator
      • nextTag

        public javax.xml.stream.events.XMLEvent nextTag()
                                                 throws javax.xml.stream.XMLStreamException
        Specified by:
        nextTag in interface javax.xml.stream.XMLEventReader
        Throws:
        javax.xml.stream.XMLStreamException
      • peek

        public javax.xml.stream.events.XMLEvent peek()
                                              throws javax.xml.stream.XMLStreamException
        Specified by:
        peek in interface javax.xml.stream.XMLEventReader
        Throws:
        javax.xml.stream.XMLStreamException
      • remove

        public void remove()
        Note: only here because we implement Iterator interface. Will not work, don't bother calling it.
        Specified by:
        remove in interface java.util.Iterator
      • updateStateEndDocument

        protected void updateStateEndDocument()
                                       throws javax.xml.stream.XMLStreamException
        Method called when we are about to return END_DOCUMENT event. Usually this should change state to STATE_END_OF_INPUT, but may vary for some alternative read modes (like multi-document)
        Throws:
        javax.xml.stream.XMLStreamException
        Since:
        4.2
      • hasNextEvent

        public boolean hasNextEvent()
                             throws javax.xml.stream.XMLStreamException

        Note: although the interface allows implementations to throw an XMLStreamException, the reference implementation doesn't currently need to. It's still declared, in case in future there is need to throw such an exception.

        Specified by:
        hasNextEvent in interface XMLEventReader2
        Throws:
        javax.xml.stream.XMLStreamException
      • createNextEvent

        protected javax.xml.stream.events.XMLEvent createNextEvent​(boolean checkEOD,
                                                                   int type)
                                                            throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException
      • _checkUnwrap

        protected javax.xml.stream.XMLStreamException _checkUnwrap​(java.lang.RuntimeException rex)
      • createStartDocumentEvent

        protected javax.xml.stream.events.XMLEvent createStartDocumentEvent()
                                                                     throws javax.xml.stream.XMLStreamException
        Method called to create the very first event (START_DOCUMENT).
        Throws:
        javax.xml.stream.XMLStreamException
      • throwEndOfInput

        protected void throwEndOfInput()
      • throwUnchecked

        protected void throwUnchecked​(javax.xml.stream.XMLStreamException sex)
      • reportProblem

        protected void reportProblem​(java.lang.String msg)
                              throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException
      • reportProblem

        protected void reportProblem​(java.lang.String msg,
                                     javax.xml.stream.Location loc)
                              throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException
      • getStreamReader

        protected javax.xml.stream.XMLStreamReader getStreamReader()
      • findErrorDesc

        protected final java.lang.String findErrorDesc​(int errorType,
                                                       int currEvent)
        Method used to locate error message description to use. Calls sub-classes getErrorDesc() first, and only if no message found, uses default messages defined here.