org.codehaus.stax2.ri

Class Stax2EventReaderImpl

java.lang.Object

org.codehaus.stax2.ri.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 and 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
private 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

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Stax2EventReaderImpl(javax.xml.stream.util.XMLEventAllocator a, XMLStreamReader2 r)

Method Summary

Modifier and Type	Method and Description
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).
private 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.
private void	throwEndOfInput()
protected void	throwUnchecked(javax.xml.stream.XMLStreamException sex)

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

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 javax.xml.stream.util.XMLEventAllocator mAllocator

mReader

protected final XMLStreamReader2 mReader

mPeekedEvent

private 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

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

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

private 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

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