org.codehaus.staxmate.in

Class SMFlatteningCursor

java.lang.Object

org.codehaus.staxmate.in.SMInputCursor

org.codehaus.staxmate.in.SMFlatteningCursor

public class SMFlatteningCursor
extends SMInputCursor

Default implementation of generic flat (non-scoped) cursor; cursor that traverse all descendants (children and grandchildren) of a start element.

Differences to SMHierarchicCursor are:

• Flat cursors return XMLStreamConstants.END_ELEMENT nodes (except for the one that closes the outermost level), unless filtered out by the filter, whereas the nested cursor automatically leaves those out.
• Flat cursors can not have child/descendant cursors

Author:

Tatu Saloranta

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CursorBase.State State constants are used for keeping track of state of individual cursors.

Nested classes/interfaces inherited from class org.codehaus.staxmate.in.SMInputCursor

SMInputCursor.Tracking

Field Summary

Fields

Modifier and Type	Field and Description
protected int	_baseDepth Depth the underlying stream reader had when this cursor was created (which is the number of currently open parent elements).
protected SMInputCursor	_childCursor Cursor that has been opened for iterating child nodes of the start element node this cursor points to.
protected SMInputContext	_context
protected SMEvent	_currEvent Event that this cursor currently points to, if valid, or it last pointed to if not (including null if cursor has not yet been advanced).
protected int	_elemCount Number of start elements iterated over by this cursor, including the current one.
protected int	_nodeCount Number of nodes iterated over by this cursor, including the current one.
protected SMElementInfo	_parentTrackedElement Element that the parent of this cursor tracked (if any), when this cursor was created.
protected CursorBase.State	_state Current state of the cursor.
protected org.codehaus.stax2.XMLStreamReader2	_streamReader Underlying stream reader used.
protected SMElementInfo	_trackedElement Element that was last "tracked"; element over which cursor was moved, and of which state has been saved for further use.

Fields inherited from class org.codehaus.staxmate.in.SMInputCursor

mData, mElemInfoFactory, mElemTracking, mFilter

Constructor Summary

Constructors

Constructor and Description
SMFlatteningCursor(SMInputContext ctxt, SMInputCursor parent, SMFilter f)

Method Summary

Methods

Modifier and Type	Method and Description
protected org.codehaus.stax2.XMLStreamReader2	_getStreamReader() Internal method (but available to sub-classes) that allows access to the underlying stream reader.
protected XMLStreamException	_notAccessible(String method) Internal method for throwing a stream exception that indicates that given method can not be called because the cursor does not point to event of expected type.
protected XMLStreamException	_wrongState(String method, SMEvent expState)
SMInputCursor	constructChildCursor(SMFilter f) Abstract method that concrete sub-classes implement, and is used for all instantiation of child cursors by this cursor instance.
SMInputCursor	constructDescendantCursor(SMFilter f) Abstract method that concrete sub-classes implement, and is used for all instantiation of descendant cursors by this cursor instance.
protected String	currentEventStr() Method for constructing human-readable description of the event this cursor points to (if cursor valid) or last pointed to (if not valid; possibly null if cursor has not yet been advanced).
protected static SMEvent	eventObjectByEventId(int type) Note: no checks are done regarding validity of passed-in type.
protected int	getBaseParentCount() This method is needed by flattening cursors when they have child cursors: if so, they can determine their depth relative to child cursor's base parent count (and can not check stream -- as it may have moved -- nor want to have separate field to track this information)
SMEvent	getNext() Main iterating method.
int	getParentCount() Number of parent elements that the token/event cursor points to has, if it points to one.
protected String	getStateDesc()
protected void	invalidate() Method called by the parent cursor, to indicate it has to traverse over xml content and that child cursor as well as all of its descendant cursors (if any) are to be considered invalid.
protected void	rewindPastChild() Method called to skim through the content that the child cursor(s) are pointing to, end return once next call to XMLStreamReader2.next() will return the next event this cursor should see.

Methods inherited from class org.codehaus.staxmate.in.SMInputCursor

_markConsumed, advance, asEvent, childCursor, childCursor, childElementCursor, childElementCursor, childElementCursor, childMixedCursor, collectDescendantText, collectDescendantText, constructElementInfo, constructStreamException, descendantCursor, descendantCursor, descendantElementCursor, descendantElementCursor, descendantElementCursor, descendantMixedCursor, findAttrIndex, getAttrBinaryValue, getAttrBinaryValue, getAttrBooleanValue, getAttrBooleanValue, getAttrCount, getAttrDoubleValue, getAttrDoubleValue, getAttrEnumValue, getAttrIntValue, getAttrIntValue, getAttrIntValue, getAttrIntValue, getAttrLocalName, getAttrLongValue, getAttrLongValue, getAttrName, getAttrNsUri, getAttrPrefix, getAttrValue, getAttrValue, getAttrValue, getCurrEvent, getCurrEventCode, getCurrEventDesc, getCursorLocation, getData, getElemBinaryValue, getElemBinaryValue, getElemBooleanValue, getElemBooleanValue, getElemDoubleValue, getElemDoubleValue, getElementCount, getElementInfoFactory, getElementTracking, getElemEnumValue, getElemIntValue, getElemIntValue, getElemLongValue, getElemLongValue, getElemStringValue, getLocalName, getLocation, getNodeCount, getNsUri, getParentTrackedElement, getPathDesc, getPrefix, getPrefixedName, getQName, getStreamLocation, getStreamReader, getText, getTrackedElement, hasLocalName, hasName, hasName, isRootCursor, processDescendantText, readerAccessible, setData, setElementInfoFactory, setElementTracking, setFilter, throwStreamException, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

_context

protected final SMInputContext _context

_streamReader

protected final org.codehaus.stax2.XMLStreamReader2 _streamReader

Underlying stream reader used. It will either be a native XMLStreamReader2 instance, or a regular (Stax 1.0) XMLStreamReader wrapped in an adapter.

_baseDepth

protected final int _baseDepth

Depth the underlying stream reader had when this cursor was created (which is the number of currently open parent elements). 0 only for root cursor.

_state

protected CursorBase.State _state

Current state of the cursor.

_currEvent

protected SMEvent _currEvent

Event that this cursor currently points to, if valid, or it last pointed to if not (including null if cursor has not yet been advanced).

_nodeCount

protected int _nodeCount

Number of nodes iterated over by this cursor, including the current one.

_elemCount

protected int _elemCount

Number of start elements iterated over by this cursor, including the current one.

_trackedElement

protected SMElementInfo _trackedElement

Element that was last "tracked"; element over which cursor was moved, and of which state has been saved for further use. At this point, it can be null if no elements have yet been iterater over. Alternatively, if it's not null, it may be currently pointed to or not; if it's not, either child cursor is active, or this cursor points to a non-start-element node.

_parentTrackedElement

protected SMElementInfo _parentTrackedElement

Element that the parent of this cursor tracked (if any), when this cursor was created.

_childCursor

protected SMInputCursor _childCursor

Cursor that has been opened for iterating child nodes of the start element node this cursor points to. Needed to keep cursor hierarchy synchronized, independent of which ones are traversed.

Constructor Detail

SMFlatteningCursor

public SMFlatteningCursor(SMInputContext ctxt,
                  SMInputCursor parent,
                  SMFilter f)

Method Detail

getParentCount

public int getParentCount()

Description copied from class: SMInputCursor

Number of parent elements that the token/event cursor points to has, if it points to one. If not, either most recent valid parent count (if cursor is closed), or the depth that it will have once is is advanced. One practical result is that a nested cursor instance will always have a single constant value it returns, whereas flattening cursors can return different values during traversal. Another thing to notice that matching START_ELEMENT and END_ELEMENT will always correspond to the same parent count.

For example, here are expected return values for an example XML document:

  <!-- Comment outside tree --> [0]
  <root> [0]
    Text [1]
    <branch> [1]
      Inner text [2]
      <child /> [2]/[2]
    </branch> [1]
  </root> [0]

Numbers in bracket are depths that would be returned when the cursor points to the node.

Note: depths are different from what many other xml processing APIs (such as Stax and XmlPull)return.

Specified by:

getParentCount in class SMInputCursor

Returns:

Number of enclosing nesting levels, ie. number of parent start elements for the node that cursor currently points to (or, in case of initial state, that it will point to if scope has node(s)).

getNext

public SMEvent getNext()
                throws XMLStreamException

Description copied from class: SMInputCursor

Main iterating method. Will try to advance the cursor to the next visible event (visibility defined by the filter cursor is configured with, if any), and return event type. If no such events are available, will return null.

Note that one side-effect of calling this method is to invalidate the child cursor, if one was active. This is done by iterating over any events child cursor (and its descendants if any) might expose.

Specified by:

getNext in class SMInputCursor

Returns:

Type of event (from XMLStreamConstants, such as XMLStreamConstants.START_ELEMENT, if a new node was iterated over; null when there are no more nodes this cursor can iterate over.

Throws:

XMLStreamException - If there are underlying parsing problems.

constructChildCursor

public SMInputCursor constructChildCursor(SMFilter f)

Description copied from class: SMInputCursor

Abstract method that concrete sub-classes implement, and is used for all instantiation of child cursors by this cursor instance.

Note that custom cursor implementations can be used by overriding this method.

Specified by:

constructChildCursor in class SMInputCursor

constructDescendantCursor

public SMInputCursor constructDescendantCursor(SMFilter f)

Description copied from class: SMInputCursor

Abstract method that concrete sub-classes implement, and is used for all instantiation of descendant cursors by this cursor instance.

Note that custom cursor implementations can be used by overriding this method.

Specified by:

constructDescendantCursor in class SMInputCursor

getBaseParentCount

protected final int getBaseParentCount()

This method is needed by flattening cursors when they have child cursors: if so, they can determine their depth relative to child cursor's base parent count (and can not check stream -- as it may have moved -- nor want to have separate field to track this information)

rewindPastChild

protected final void rewindPastChild()
                              throws XMLStreamException

Method called to skim through the content that the child cursor(s) are pointing to, end return once next call to XMLStreamReader2.next() will return the next event this cursor should see.

Throws:

XMLStreamException

invalidate

protected void invalidate()
                   throws XMLStreamException

Method called by the parent cursor, to indicate it has to traverse over xml content and that child cursor as well as all of its descendant cursors (if any) are to be considered invalid.

Throws:

XMLStreamException

_getStreamReader

protected final org.codehaus.stax2.XMLStreamReader2 _getStreamReader()

Internal method (but available to sub-classes) that allows access to the underlying stream reader.

eventObjectByEventId

protected static final SMEvent eventObjectByEventId(int type)

Note: no checks are done regarding validity of passed-in type.

Returns:

SMEvent matching given type

_notAccessible

protected XMLStreamException _notAccessible(String method)
                                     throws XMLStreamException

Internal method for throwing a stream exception that indicates that given method can not be called because the cursor does not point to event of expected type. This can be either because cursor is invalid (doesn't point to any event), or because it points to "wrong" event type. Distinction is reflected in the exception message.

Throws:

XMLStreamException

_wrongState

protected XMLStreamException _wrongState(String method,
                             SMEvent expState)
                                  throws XMLStreamException

Throws:

XMLStreamException

getStateDesc

protected String getStateDesc()

currentEventStr

protected String currentEventStr()

Method for constructing human-readable description of the event this cursor points to (if cursor valid) or last pointed to (if not valid; possibly null if cursor has not yet been advanced).

Returns:

Human-readable description of the underlying Stax event this cursor points to.