org.codehaus.stax2.ri

Class Stax2EventReaderImpl

java.lang.Object

org.codehaus.stax2.ri.Stax2EventReaderImpl

All Implemented Interfaces:

Iterator, XMLEventReader, XMLStreamConstants, XMLEventReader2

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:

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

Constructors

Modifier	Constructor and Description
protected	Stax2EventReaderImpl(XMLEventAllocator a, XMLStreamReader2 r)

Method Summary

Methods

Modifier and Type	Method and Description
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()