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

  • Field Details

    • _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 org.codehaus.staxmate.in.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 Details

  • Method Details

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