org.codehaus.stax2.ri
Class Stax2EventReaderImpl

java.lang.Object
  extended by org.codehaus.stax2.ri.Stax2EventReaderImpl
All Implemented Interfaces:
Iterator, XMLEventReader, XMLStreamConstants, XMLEventReader2
Direct Known Subclasses:
WstxEventReader

public abstract class Stax2EventReaderImpl
extends Object
implements XMLEventReader2, 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:


Field Summary
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  XMLEventAllocator mAllocator
           
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
 
Constructor Summary
protected Stax2EventReaderImpl(XMLEventAllocator a, XMLStreamReader2 r)
           
 
Method Summary
 void close()
           
protected  XMLEvent createNextEvent(boolean checkEOD, int type)
           
protected  XMLEvent createStartDocumentEvent()
          Method called to create the very first event (START_DOCUMENT).
 String getElementText()
           
protected abstract  String getErrorDesc(int errorType, int eventType)
          Method called upon encountering a problem that should result in an exception being thrown.
 Object getProperty(String name)
           
protected  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(String name)
          Method similar to XMLInputFactory.isPropertySupported(java.lang.String), used to determine whether a property is supported by the Reader instance.
 Object next()
           
 XMLEvent nextEvent()
           
 XMLEvent nextTag()
           
 XMLEvent peek()
           
 void remove()
          Note: only here because we implement Iterator interface.
protected  void reportProblem(String msg)
           
protected  void reportProblem(String msg, Location loc)
           
abstract  boolean setProperty(String name, 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 throwUnchecked(XMLStreamException sex)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

STATE_INITIAL

protected static final int STATE_INITIAL
See Also:
Constant Field Values

STATE_END_OF_INPUT

protected static final int STATE_END_OF_INPUT
See Also:
Constant Field Values

STATE_CONTENT

protected static final int STATE_CONTENT
See Also:
Constant Field Values

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 XMLEventAllocator mAllocator

mReader

protected final XMLStreamReader2 mReader

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(XMLEventAllocator a,
                               XMLStreamReader2 r)
Method Detail

isPropertySupported

public abstract boolean isPropertySupported(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(String name,
                                    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 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 XMLStreamException
Specified by:
close in interface XMLEventReader
Throws:
XMLStreamException

getElementText

public String getElementText()
                      throws XMLStreamException
Specified by:
getElementText in interface XMLEventReader
Throws:
XMLStreamException

getProperty

public Object getProperty(String name)
Specified by:
getProperty in interface XMLEventReader

hasNext

public boolean hasNext()
Specified by:
hasNext in interface Iterator
Specified by:
hasNext in interface XMLEventReader

nextEvent

public XMLEvent nextEvent()
                   throws XMLStreamException
Specified by:
nextEvent in interface XMLEventReader
Throws:
XMLStreamException

next

public Object next()
Specified by:
next in interface Iterator

nextTag

public XMLEvent nextTag()
                 throws XMLStreamException
Specified by:
nextTag in interface XMLEventReader
Throws:
XMLStreamException

peek

public XMLEvent peek()
              throws XMLStreamException
Specified by:
peek in interface XMLEventReader
Throws:
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 Iterator

hasNextEvent

public boolean hasNextEvent()
                     throws 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:
XMLStreamException

createNextEvent

protected XMLEvent createNextEvent(boolean checkEOD,
                                   int type)
                            throws XMLStreamException
Throws:
XMLStreamException

createStartDocumentEvent

protected XMLEvent createStartDocumentEvent()
                                     throws XMLStreamException
Method called to create the very first event (START_DOCUMENT).

Throws:
XMLStreamException

throwUnchecked

protected void throwUnchecked(XMLStreamException sex)

reportProblem

protected void reportProblem(String msg)
                      throws XMLStreamException
Throws:
XMLStreamException

reportProblem

protected void reportProblem(String msg,
                             Location loc)
                      throws XMLStreamException
Throws:
XMLStreamException

getStreamReader

protected XMLStreamReader getStreamReader()