Top Description Fields Constructors Methods
org.codehaus.stax2.ri

public abstract Class Stax2EventReaderImpl

extends Object
implements XMLEventReader2, XMLStreamConstants
Class Inheritance
All Implemented Interfaces
javax.xml.stream.XMLStreamConstants, org.codehaus.stax2.XMLEventReader2, javax.xml.stream.XMLEventReader, java.util.Iterator
Imports
java.util.NoSuchElementException, javax.xml.stream.*, javax.xml.stream.events.*, javax.xml.stream.util.XMLEventAllocator, org.codehaus.stax2.XMLEventReader2, .XMLStreamReader2
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

Modifier and TypeField and Description
protected static final int
ERR_GETELEMTEXT_NON_TEXT_EVENT

Encountered non-textual event (other than closing END_ELEMENT) when collecting text for getElementText()

protected static final int
ERR_GETELEMTEXT_NOT_START_ELEM

Current state when getElementText() called not START_ELEMENT

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

protected static final int
ERR_NEXTTAG_WRONG_TYPE

Encountered non-skippable non-text/element event with nextTag()

protected final XMLEventAllocator
mAllocator

protected 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 final 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 final int
STATE_CONTENT

protected static final int
STATE_END_OF_INPUT

protected static final int
STATE_INITIAL

Constructor Summary

AccessConstructor and Description
protected
Stax2EventReaderImpl(XMLEventAllocator a, XMLStreamReader2 r)

Method Summary

Modifier and TypeMethod and Description
protected XMLStreamException
_checkUnwrap(RuntimeException rex)

public void
close()

Implements javax.xml.stream.XMLEventReader.close.

Frees any resources associated with this Reader.
protected XMLEvent
createNextEvent(boolean checkEOD, int type)

protected XMLEvent
createStartDocumentEvent()

Method called to create the very first event (START_DOCUMENT).

protected final String
findErrorDesc(int errorType, int currEvent)

Method used to locate error message description to use.

public String
getElementText()

Implements javax.xml.stream.XMLEventReader.getElementText.

Reads the content of a text-only element.
protected abstract String
getErrorDesc(int
Type of the problem, one of ERR_ constants
errorType, int
Type of the event that triggered the problem, if any; -1 if not available.
eventType)

Method called upon encountering a problem that should result in an exception being thrown.

public Object
getProperty(String
The name of the property
name)

Implements javax.xml.stream.XMLEventReader.getProperty.

Get the value of a feature/property from the underlying implementation
protected XMLStreamReader
getStreamReader()

public boolean
hasNext()

Implements javax.xml.stream.XMLEventReader.hasNext.

Check if there are more events.
public boolean
hasNextEvent()

Implements org.codehaus.stax2.XMLEventReader2.hasNextEvent.

Note

although the interface allows implementations to throw an XMLStreamException, the reference implementation doesn't currently need to.

public abstract boolean
isPropertySupported(String name)

Redeclares org.codehaus.stax2.XMLEventReader2.isPropertySupported.

Method similar to javax.xml.stream.XMLInputFactory#isPropertySupported, used to determine whether a property is supported by the Reader instance.
public Object
next()

Implements java.util.Iterator.next.

Returns the next element in the iteration.
public XMLEvent
nextEvent()

Implements javax.xml.stream.XMLEventReader.nextEvent.

Gets the next XMLEvent.
public XMLEvent
nextTag()

Implements javax.xml.stream.XMLEventReader.nextTag.

Skips any insignificant space events until a START_ELEMENT or END_ELEMENT is reached.
public XMLEvent
peek()

Implements javax.xml.stream.XMLEventReader.peek.

Check the next XMLEvent without reading it from the stream.
public void
remove()

Overrides default java.util.Iterator.remove.

Note

only here because we implement Iterator interface.

protected void
reportProblem(String msg)

protected void
reportProblem(String msg, Location loc)

public abstract boolean
setProperty(String
Name of the property to set
name, Object
Value to set property to.
value)

Redeclares org.codehaus.stax2.XMLEventReader2.setProperty.

Method that can be used to set per-reader properties; a subset of properties one can set via matching org.codehaus.stax2.XMLInputFactory2 instance.
protected void
throwEndOfInput()

protected void
throwUnchecked(XMLStreamException sex)

protected void
updateStateEndDocument()

Method called when we are about to return END_DOCUMENT event.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

ERR_GETELEMTEXT_NON_TEXT_EVENTback to summary
protected static final int ERR_GETELEMTEXT_NON_TEXT_EVENT

Encountered non-textual event (other than closing END_ELEMENT) when collecting text for getElementText()

ERR_GETELEMTEXT_NOT_START_ELEMback to summary
protected static final int ERR_GETELEMTEXT_NOT_START_ELEM

Current state when getElementText() called not START_ELEMENT

ERR_NEXTTAG_NON_WS_TEXTback to summary
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()

ERR_NEXTTAG_WRONG_TYPEback to summary
protected static final int ERR_NEXTTAG_WRONG_TYPE

Encountered non-skippable non-text/element event with nextTag()

mAllocatorback to summary
protected final XMLEventAllocator mAllocator
mPeekedEventback to summary
protected 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)

mPrePeekEventback to summary
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.

mReaderback to summary
protected final XMLStreamReader2 mReader
mStateback to summary
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.

STATE_CONTENTback to summary
protected static final int STATE_CONTENT
STATE_END_OF_INPUTback to summary
protected static final int STATE_END_OF_INPUT
STATE_INITIALback to summary
protected static final int STATE_INITIAL

Constructor Detail

Stax2EventReaderImplback to summary
protected Stax2EventReaderImpl(XMLEventAllocator a, XMLStreamReader2 r)

Method Detail

_checkUnwrapback to summary
protected XMLStreamException _checkUnwrap(RuntimeException rex)
closeback to summary
public void close() throws XMLStreamException

Implements javax.xml.stream.XMLEventReader.close.

Doc from javax.xml.stream.XMLEventReader.close.

Frees any resources associated with this Reader. This method does not close the underlying input source.

Annotations
@Override
Exceptions
XMLStreamException:
if there are errors freeing associated resources
createNextEventback to summary
protected XMLEvent createNextEvent(boolean checkEOD, int type) throws XMLStreamException
createStartDocumentEventback to summary
protected XMLEvent createStartDocumentEvent() throws XMLStreamException

Method called to create the very first event (START_DOCUMENT).

findErrorDescback to summary
protected final 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.

getElementTextback to summary
public String getElementText() throws XMLStreamException

Implements javax.xml.stream.XMLEventReader.getElementText.

Doc from javax.xml.stream.XMLEventReader.getElementText.

Reads the content of a text-only element. Precondition: the current event is START_ELEMENT. Postcondition: The current event is the corresponding END_ELEMENT.

Returns:String

the text of the element

Annotations
@Override
Exceptions
XMLStreamException:
if the current event is not a START_ELEMENT or if a non text element is encountered
getErrorDescback to summary
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:int

Type of the problem, one of ERR_ constants

eventType:int

Type of the event that triggered the problem, if any; -1 if not available.

getPropertyback to summary
public Object getProperty(String name)

Implements javax.xml.stream.XMLEventReader.getProperty.

Doc from javax.xml.stream.XMLEventReader.getProperty.

Get the value of a feature/property from the underlying implementation

Parameters
name:String

The name of the property

Returns:Object

The value of the property

Annotations
@Override
getStreamReaderback to summary
protected XMLStreamReader getStreamReader()
hasNextback to summary
public boolean hasNext()

Implements javax.xml.stream.XMLEventReader.hasNext.

Doc from javax.xml.stream.XMLEventReader.hasNext.

Check if there are more events. Returns true if there are more events and false otherwise.

Returns:boolean

true if the event reader has more events, false otherwise

Annotations
@Override
hasNextEventback to summary
public boolean hasNextEvent() throws XMLStreamException

Implements org.codehaus.stax2.XMLEventReader2.hasNextEvent.

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.

Annotations
@Override
isPropertySupportedback to summary
public abstract boolean isPropertySupported(String name)

Redeclares org.codehaus.stax2.XMLEventReader2.isPropertySupported.

Doc from org.codehaus.stax2.XMLEventReader2.isPropertySupported.

Method similar to javax.xml.stream.XMLInputFactory#isPropertySupported, 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.

Annotations
@Override
nextback to summary
public Object next()

Implements java.util.Iterator.next.

Doc from java.util.Iterator.next.

Returns the next element in the iteration.

Returns:Object

the next element in the iteration

Annotations
@Override
nextEventback to summary
public XMLEvent nextEvent() throws XMLStreamException

Implements javax.xml.stream.XMLEventReader.nextEvent.

Doc from javax.xml.stream.XMLEventReader.nextEvent.

Gets the next XMLEvent. The initial event is StartDocument.

Returns:XMLEvent

the next XMLEvent

Annotations
@Override
Exceptions
XMLStreamException:
if there is an error with the underlying XML.
nextTagback to summary
public XMLEvent nextTag() throws XMLStreamException

Implements javax.xml.stream.XMLEventReader.nextTag.

Doc from javax.xml.stream.XMLEventReader.nextTag.

Skips any insignificant space events until a START_ELEMENT or END_ELEMENT is reached. If anything other than space characters are encountered, an exception is thrown. This method should be used when processing element-only content because the parser is not able to recognize ignorable whitespace if the DTD is missing or not interpreted.

Returns:XMLEvent

a START_ELEMENT or END_ELEMENT

Annotations
@Override
Exceptions
XMLStreamException:
if anything other than space characters are encountered
peekback to summary
public XMLEvent peek() throws XMLStreamException

Implements javax.xml.stream.XMLEventReader.peek.

Doc from javax.xml.stream.XMLEventReader.peek.

Check the next XMLEvent without reading it from the stream. Returns null if the stream is at EOF or has no more XMLEvents. A call to peek() will be equal to the next return of next().

Returns:XMLEvent

the next XMLEvent

Annotations
@Override
Exceptions
XMLStreamException:
if an error occurs
removeback to summary
public void remove()

Overrides default java.util.Iterator.remove.

Note

only here because we implement Iterator interface. Will not work, don't bother calling it.

Annotations
@Override
reportProblemback to summary
protected void reportProblem(String msg) throws XMLStreamException
reportProblemback to summary
protected void reportProblem(String msg, Location loc) throws XMLStreamException
setPropertyback to summary
public abstract boolean setProperty(String name, Object value)

Redeclares org.codehaus.stax2.XMLEventReader2.setProperty.

Doc from org.codehaus.stax2.XMLEventReader2.setProperty.

Method that can be used to set per-reader properties; a subset of properties one can set via matching org.codehaus.stax2.XMLInputFactory2 instance. Exactly which methods are mutable is implementation specific.

Parameters
name:String

Name of the property to set

value:Object

Value to set property to.

Returns:boolean

True, if the specified property was succesfully set to specified value; false if its value was not changed

Annotations
@Override
throwEndOfInputback to summary
protected void throwEndOfInput()
throwUncheckedback to summary
protected void throwUnchecked(XMLStreamException sex)
updateStateEndDocumentback to summary
protected void updateStateEndDocument() throws 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)

Since
4.2