org.codehaus.staxmate.in
Class SMInputCursor

java.lang.Object
  org.codehaus.staxmate.in.SMInputCursor

Direct Known Subclasses:

SMFlatteningCursor, SMHierarchicCursor

public abstract class SMInputCursor
extends java.lang.Object

Base class for reader-side cursors that form the main input-side abstraction offered by StaxMate.

Implementation Note: since cursors are thin wrappers around XMLStreamReader2, and since not all Stax implementations implement XMLStreamReader2, some wrapping may be involved in exposing basic Stax 1.0 stream readers as Stax2 stream readers. Without native support, not all stax2 features may be available, but cursors will try to limit their usage to known working subset.

Author:

Tatu Saloranta

Nested Class Summary

static class	CursorBase.State State constants are used for keeping track of state of individual cursors.
static class	SMInputCursor.Tracking Different tracking behaviors available for cursors.

Field Summary

protected int	mBaseDepth Depth the underlying stream reader had when this cursor was created (which is the number of currently open parent elements).
protected SMInputCursor	mChildCursor Cursor that has been opened for iterating child nodes of the start element node this cursor points to.
protected SMEvent	mCurrEvent 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 java.lang.Object	mData Non-typesafe payload data that applications can use, to pass an extra argument along with cursors.
protected int	mElemCount Number of start elements iterated over by this cursor, including the current one.
protected ElementInfoFactory	mElemInfoFactory Optional factory instance that is used to create element info objects if element tracking is enabled.
protected SMInputCursor.Tracking	mElemTracking Whether element information is to be tracked or not, and if it is, how much of it will be stored.
protected SMFilter	mFilter Optional filter object that can be used to filter out events of types caller is not interested in.
protected int	mNodeCount Number of nodes iterated over by this cursor, including the current one.
protected SMElementInfo	mParentTrackedElement Element that the parent of this cursor tracked (if any), when this cursor was created.
protected CursorBase.State	mState Current state of the cursor.
protected org.codehaus.stax2.XMLStreamReader2	mStreamReader Underlying stream reader used.
protected SMElementInfo	mTrackedElement Element that was last "tracked"; element over which cursor was moved, and of which state has been saved for further use.

Constructor Summary

SMInputCursor(SMInputCursor parent, org.codehaus.stax2.XMLStreamReader2 sr, SMFilter filter)

Method Summary

protected org.codehaus.stax2.XMLStreamReader2	_getStreamReader() Internal method (but available to sub-classes) that allows access to the underlying stream reader.
protected javax.xml.stream.XMLStreamException	_notAccessible(java.lang.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 javax.xml.stream.XMLStreamException	_wrongState(java.lang.String method, SMEvent expState)
SMInputCursor	childCursor() Method that will create a new nested cursor for iterating over all (immediate) child nodes of the start element this cursor currently points to.
SMInputCursor	childCursor(SMFilter f) Method that will create a new nested cursor for iterating over all (immediate) child nodes of the start element this cursor currently points to that are passed by the specified filter.
SMInputCursor	childElementCursor() Convenience method; equivalent to childCursor(SMFilterFactory.getElementOnlyFilter());
SMInputCursor	childElementCursor(javax.xml.namespace.QName elemName) Convenience method; equivalent to childCursor(SMFilterFactory.getElementOnlyFilter(elemName)); Will only return START_ELEMENT and END_ELEMENT events, whose element name matches given qname.
SMInputCursor	childElementCursor(java.lang.String elemLocalName) Convenience method; equivalent to childCursor(SMFilterFactory.getElementOnlyFilter(elemName)); Will only return START_ELEMENT and END_ELEMENT events, whose element's local name matches given local name, and that does not belong to a namespace.
SMInputCursor	childMixedCursor() Convenience method; equivalent to childCursor(SMFilterFactory.getMixedFilter());
java.lang.String	collectDescendantText(boolean includeIgnorable) Method that can collect all text contained within START_ELEMENT currently pointed by this cursor.
protected abstract SMInputCursor	constructChildCursor(SMFilter f) Abstract method that concrete sub-classes implement, and is used for all instantiation of child cursors by this cursor instance.
protected abstract 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 SMElementInfo	constructElementInfo(SMElementInfo parent, SMElementInfo prevSibling) Method cursor calls when it needs to track element state information; if so, it calls this method to take a snapshot of the element.
javax.xml.stream.XMLStreamException	constructStreamException(java.lang.String msg) Method for constructing stream exception with given message, and location that matches that of the underlying stream regardless of whether this cursor is valid (that is, will indicate location of the stream which may differ from where this cursor was last valid)
protected java.lang.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).
SMInputCursor	descendantCursor() Method that will create a new nested cursor for iterating over all the descendant (children and grandchildren) nodes of the start element this cursor currently points to.
SMInputCursor	descendantCursor(SMFilter f) Method that will create a new nested cursor for iterating over all the descendant (children and grandchildren) nodes of the start element this cursor currently points to that are accepted by the specified filter.
SMInputCursor	descendantElementCursor() Convenience method; equivalent to descendantCursor(SMFilterFactory.getElementOnlyFilter());
SMInputCursor	descendantElementCursor(javax.xml.namespace.QName elemName) Convenience method; equivalent to descendantCursor(SMFilterFactory.getElementOnlyFilter(elemName)); Will only return START_ELEMENT and END_ELEMENT events, whose element name matches given qname.
SMInputCursor	descendantElementCursor(java.lang.String elemLocalName) Convenience method; equivalent to descendantCursor(SMFilterFactory.getElementOnlyFilter(elemLocalName));.
SMInputCursor	descendantMixedCursor() Convenience method; equivalent to descendantCursor(SMFilterFactory.getMixedFilter());
protected static SMEvent	eventObjectByEventId(int type) Note: no checks are done regarding validity of passed-in type.
int	findAttrIndex(java.lang.String uri, java.lang.String localName) Method that can be called when this cursor points to START_ELEMENT, and which will return index of specified attribute, if it exists for this element.
boolean	getAttrBooleanValue(int index) Method for accessing value of specified attribute as boolean.
boolean	getAttrBooleanValue(int index, boolean defValue) Method for accessing value of specified attribute as boolean.
int	getAttrCount() Method that can be called when this cursor points to START_ELEMENT, and which will return number of attributes with values for the start element.
int	getAttrIntValue(int index) Method for accessing value of specified attribute as integer.
int	getAttrIntValue(int index, int defValue) Method for accessing value of specified attribute as integer.
int	getAttrIntValue(java.lang.String uri, java.lang.String localName) Deprecated. Use combination of findAttrIndex(java.lang.String, java.lang.String) and getAttrIntValue(int) instead.
int	getAttrIntValue(java.lang.String uri, java.lang.String localName, int defValue) Deprecated. Use combination of findAttrIndex(java.lang.String, java.lang.String) and getAttrIntValue(int,int) instead.
java.lang.String	getAttrLocalName(int index) Method that can be called when this cursor points to START_ELEMENT, and returns local name of the attribute at specified index.
long	getAttrLongValue(int index) Method for accessing value of specified attribute as long.
long	getAttrLongValue(int index, long defValue) Method for accessing value of specified attribute as long.
javax.xml.namespace.QName	getAttrName(int index) Method that can be called when this cursor points to START_ELEMENT, and returns fully qualified name of the attribute at specified index.
java.lang.String	getAttrNsUri(int index) Method that can be called when this cursor points to START_ELEMENT, and returns namespace URI of the attribute at specified index (non-empty String if it has one, and empty String if attribute does not belong to a namespace) Index has to be between [0, getAttrCount()[; otherwise IllegalArgumentException will be thrown.
java.lang.String	getAttrPrefix(int index) Method that can be called when this cursor points to START_ELEMENT, and returns namespace prefix of the attribute at specified index (if it has any), or empty String if attribute has no prefix (does not belong to a namespace).
java.lang.String	getAttrValue(int index) Method that can be called when this cursor points to START_ELEMENT, and returns unmodified textual value of the attribute at specified index (non-empty String if it has one, and empty String if attribute does not belong to a namespace) Index has to be between [0, getAttrCount()[; otherwise IllegalArgumentException will be thrown.
java.lang.String	getAttrValue(java.lang.String localName) Convenience accessor method to access an attribute that is not in a namespace (has no prefix).
java.lang.String	getAttrValue(java.lang.String namespaceURI, java.lang.String localName) Method that can be called when this cursor points to START_ELEMENT, and returns unmodified textual value of the specified attribute (if element has it), or null if element has no value for such attribute.
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	getCurrEvent() Returns the type of event this cursor either currently points to (if in valid state), or pointed to (if ever iterated forward), or null if just created.
int	getCurrEventCode() Convenience method doing
protected java.lang.String	getCurrEventDesc()
javax.xml.stream.Location	getCursorLocation() Method to access starting Location of event (as defined by Stax specification) that this cursor points to.
java.lang.Object	getData() Method for accessing application-provided data set previously by a setData(java.lang.Object) call.
int	getDepth() Deprecated. Use getParentCount() instead
boolean	getElemBooleanValue() Method that can collect text directly contained within START_ELEMENT currently pointed by this cursor and convert it to a boolean value.
boolean	getElemBooleanValue(boolean defValue) Similar to getElemBooleanValue(), but instead of failing on invalid value, returns given default value.
int	getElementCount() Method to access number of start elements cursor has traversed (including ones that were filtered out, if any).
ElementInfoFactory	getElementInfoFactory()
SMInputCursor.Tracking	getElementTracking()
int	getElemIntValue() Method that can collect text directly contained within START_ELEMENT currently pointed by this cursor and convert it to a int value.
int	getElemIntValue(int defValue) Similar to getElemIntValue(), but instead of failing on invalid value, returns given default value.
long	getElemLongValue() Method that can collect text directly contained within START_ELEMENT currently pointed by this cursor and convert it to a long value.
long	getElemLongValue(long defValue) Similar to getElemLongValue(), but instead of failing on invalid value, returns given default value.
java.lang.String	getElemStringValue() Method that can collect text directly contained within START_ELEMENT currently pointed by this cursor.
java.lang.String	getLocalName() For events with fully qualified names (START_ELEMENT, END_ELEMENT, ATTRIBUTE, NAMESPACE) returns the local component of the full name; for events with only non-qualified name (PROCESSING_INSTRUCTION, entity and notation declarations, references) returns the name, and for other events, returns null.
javax.xml.stream.Location	getLocation() Deprecated.
abstract SMEvent	getNext() Main iterating method.
int	getNodeCount() Method to access number of nodes cursor has traversed (including ones that were filtered out, if any).
java.lang.String	getNsUri() Method for accessing namespace URI of the START_ELEMENT this cursor points to.
abstract int	getParentCount() Number of parent elements that the token/event cursor points to has, if it points to one.
SMElementInfo	getParentTrackedElement()
java.lang.String	getPathDesc() Method that generates developer-readable description of the logical path of the event this cursor points to, assuming that element tracking is enabled.
java.lang.String	getPrefix() Method for accessing namespace prefix of the START_ELEMENT this cursor points to.
java.lang.String	getPrefixedName() Returns a String representation of either the fully-qualified name (if the event has full name) or the local name (if event does not have full name but has local name); or if no name available, throws stream exception.
javax.xml.namespace.QName	getQName()
protected java.lang.String	getStateDesc()
javax.xml.stream.Location	getStreamLocation() Method to access Location that the underlying stream reader points to.
org.codehaus.stax2.XMLStreamReader2	getStreamReader() Method that can be used to get direct access to the underlying stream reader.
java.lang.String	getText() Method that can be used when this cursor points to a textual event; something for which XMLStreamReader.getText() can be called.
SMElementInfo	getTrackedElement()
boolean	hasLocalName(java.lang.String expName) Method for verifying whether current named event (one for which getLocalName() can be called) has the specified local name or not.
boolean	hasName(java.lang.String expNsURI, java.lang.String expLN) Method for verifying whether current named event (one for which getLocalName() can be called) has the specified fully-qualified name or not.
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.
boolean	isRootCursor()
void	processDescendantText(java.io.Writer w, boolean includeIgnorable) Method similar to collectDescendantText(boolean), but will write the text to specified Writer instead of collecting it into a String.
boolean	readerAccessible() Method that can be used to check whether this cursor is currently valid; that is, it is the cursor that points to the event underlying stream is at.
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.
void	setData(java.lang.Object o) Method for assigning per-cursor application-managed data, readable using getData().
void	setElementInfoFactory(ElementInfoFactory f) Set element info factory used for constructing SMElementInfo instances during traversal for this cursor, as well as all of its children.
void	setElementTracking(SMInputCursor.Tracking tracking) Changes tracking mode of this cursor to the new specified mode.
void	setFilter(SMFilter f) Method for setting filter used for selecting which events are to be returned to the caller when getNext() is called.
void	throwStreamException(java.lang.String msg) Method for constructing and throwing stream exception with given message.
java.lang.String	toString() Overridden implementation will just display description of the event this cursor points to (or last pointed to, if not valid)

Methods inherited from class java.lang.Object

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

Field Detail

mFilter

protected SMFilter mFilter

Optional filter object that can be used to filter out events of types caller is not interested in.

mElemTracking

protected SMInputCursor.Tracking mElemTracking

Whether element information is to be tracked or not, and if it is, how much of it will be stored. See SMInputCursor.Tracking for details.

mElemInfoFactory

protected ElementInfoFactory mElemInfoFactory

Optional factory instance that is used to create element info objects if element tracking is enabled. If null, will use default generation mechanism, implemented by SMInputCursor itself.

Note that by default, this factory will be passed down to child and descendant cursors this cursor creates, so usually one only needs to set the factory of the root cursor.

mData

protected java.lang.Object mData

Non-typesafe payload data that applications can use, to pass an extra argument along with cursors. Not used by the framework itself for anything.

mStreamReader

protected final org.codehaus.stax2.XMLStreamReader2 mStreamReader

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

mBaseDepth

protected final int mBaseDepth

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.

mState

protected CursorBase.State mState

Current state of the cursor.

mCurrEvent

protected SMEvent mCurrEvent

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

mNodeCount

protected int mNodeCount

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

mElemCount

protected int mElemCount

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

mTrackedElement

protected SMElementInfo mTrackedElement

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.

mParentTrackedElement

protected SMElementInfo mParentTrackedElement

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

mChildCursor

protected SMInputCursor mChildCursor

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

SMInputCursor

public SMInputCursor(SMInputCursor parent,
                     org.codehaus.stax2.XMLStreamReader2 sr,
                     SMFilter filter)

Method Detail

setFilter

public final void setFilter(SMFilter f)

Method for setting filter used for selecting which events are to be returned to the caller when getNext() is called.

setElementTracking

public final void setElementTracking(SMInputCursor.Tracking tracking)

Changes tracking mode of this cursor to the new specified mode. Default mode for cursors is the one their parent uses; SMInputCursor.Tracking.NONE for root cursors with no parent.

See also getPathDesc() for information on how to display tracked path/element information.

getElementTracking

public final SMInputCursor.Tracking getElementTracking()

setElementInfoFactory

public final void setElementInfoFactory(ElementInfoFactory f)

Set element info factory used for constructing SMElementInfo instances during traversal for this cursor, as well as all of its children.

getElementInfoFactory

public final ElementInfoFactory getElementInfoFactory()

getNodeCount

public int getNodeCount()

Method to access number of nodes cursor has traversed (including ones that were filtered out, if any). Starts with 0, and is incremented each time underlying stream reader's XMLStreamReader.next() method is called, but not counting child cursors' node counts.

Returns:

Number of nodes (events) cursor has traversed

getElementCount

public int getElementCount()

Method to access number of start elements cursor has traversed (including ones that were filtered out, if any). Starts with 0, and is incremented each time underlying stream reader's XMLStreamReader.next() method is called and has moved over a start element, but not counting child cursors' element counts.

Returns:

Number of start elements cursor has traversed

getDepth

@Deprecated
public final int getDepth()

Deprecated. Use getParentCount() instead

getParentCount

public abstract int getParentCount()

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.

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

getCurrEvent

public SMEvent getCurrEvent()

Returns the type of event this cursor either currently points to (if in valid state), or pointed to (if ever iterated forward), or null if just created.

Returns:

Type of event this cursor points to, if it currently points to one, or last one it pointed to otherwise (if ever pointed to a valid event), or null if neither.

getCurrEventCode

public int getCurrEventCode()

Convenience method doing

isRootCursor

public final boolean isRootCursor()

Returns:

True if this cursor iterates over root level of the underlying stream reader

getTrackedElement

public SMElementInfo getTrackedElement()

Returns:

Information about last "tracked" element; element we have last iterated over when tracking has been enabled.

getParentTrackedElement

public SMElementInfo getParentTrackedElement()

Returns:

Information about the tracked element the parent cursor had, if parent cursor existed and was tracking element information.

readerAccessible

public final boolean readerAccessible()

Method that can be used to check whether this cursor is currently valid; that is, it is the cursor that points to the event underlying stream is at. Only one cursor at any given time is valid in this sense, although other cursors may be made valid by advancing them (and by process invalidating the cursor that was valid at that point). It is also possible that none of cursors is valid at some point: this is the case when formerly valid cursor reached end of its contet (END_ELEMENT).

Returns:

True if the cursor is currently valid; false if not

getStreamReader

public org.codehaus.stax2.XMLStreamReader2 getStreamReader()

Method that can be used to get direct access to the underlying stream reader. Custom sub-classed versions (which can be constructed by overriding this classes factory methods) can choose to block such access, but the default implementation does allow access to it.

Note that this method should not be needed (or extensively used) for regular StaxMate usage, because direct access to the stream may cause cursor's understanding of stream reader state to be incompatible with its actual state.

Returns:

Stream reader the cursor uses for getting XML events

getCursorLocation

public javax.xml.stream.Location getCursorLocation()
                                            throws javax.xml.stream.XMLStreamException

Method to access starting Location of event (as defined by Stax specification) that this cursor points to. Method can only be called if the cursor is valid (as per readerAccessible()); if not, an exception is thrown

Returns:

Location of the event this cursor points to

Throws:

javax.xml.stream.XMLStreamException

getStreamLocation

public javax.xml.stream.Location getStreamLocation()

Method to access Location that the underlying stream reader points to.

Returns:

Location of the event the underlying stream reader points to (independent of whether this cursor points to that event)

getLocation

@Deprecated
public javax.xml.stream.Location getLocation()
                                      throws javax.xml.stream.XMLStreamException

Deprecated.

Same as calling getCursorLocation()

Throws:

javax.xml.stream.XMLStreamException

getText

public java.lang.String getText()
                         throws javax.xml.stream.XMLStreamException

Method that can be used when this cursor points to a textual event; something for which XMLStreamReader.getText() can be called. Note that it does not advance the cursor, or combine multiple textual events.

Returns:

Textual content of the current event that this cursor points to, if any

Throws:

javax.xml.stream.XMLStreamException - if either the underlying parser has problems (possibly including event type not being of textual type, see Stax 1.0 specs for details); or if this cursor does not currently point to an event.

collectDescendantText

public java.lang.String collectDescendantText(boolean includeIgnorable)
                                       throws javax.xml.stream.XMLStreamException

Method that can collect all text contained within START_ELEMENT currently pointed by this cursor. Collection is done recursively through all descendant text (CHARACTER, CDATA; optionally SPACE) nodes, ignoring nodes of other types. After collecting text, cursor will be positioned at the END_ELEMENT matching initial START_ELEMENT and thus needs to be advanced to access the next sibling event.

Parameters:

includeIgnorable - Whether text for events of type SPACE should be ignored in the results or not. If false, SPACE events will be skipped; if true, white space will be included in results.

Throws:

javax.xml.stream.XMLStreamException

processDescendantText

public void processDescendantText(java.io.Writer w,
                                  boolean includeIgnorable)
                           throws java.io.IOException,
                                  javax.xml.stream.XMLStreamException

Method similar to collectDescendantText(boolean), but will write the text to specified Writer instead of collecting it into a String.

Parameters:

w - Writer to use for outputting text found

includeIgnorable - Whether text for events of type SPACE should be ignored in the results or not. If false, SPACE events will be skipped; if true, white space will be included in results.

Throws:

java.io.IOException

javax.xml.stream.XMLStreamException

getQName

public javax.xml.namespace.QName getQName()
                                   throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

getLocalName

public java.lang.String getLocalName()
                              throws javax.xml.stream.XMLStreamException

For events with fully qualified names (START_ELEMENT, END_ELEMENT, ATTRIBUTE, NAMESPACE) returns the local component of the full name; for events with only non-qualified name (PROCESSING_INSTRUCTION, entity and notation declarations, references) returns the name, and for other events, returns null.

Returns:

Local component of the name

Throws:

javax.xml.stream.XMLStreamException

getPrefix

public java.lang.String getPrefix()
                           throws javax.xml.stream.XMLStreamException

Method for accessing namespace prefix of the START_ELEMENT this cursor points to.

Returns:

Prefix of currently pointed-to START_ELEMENT, if it has one; "" if none

Throws:

javax.xml.stream.XMLStreamException - if cursor does not point to START_ELEMENT

getNsUri

public java.lang.String getNsUri()
                          throws javax.xml.stream.XMLStreamException

Method for accessing namespace URI of the START_ELEMENT this cursor points to.

Returns:

Namespace URI of currently pointed-to START_ELEMENT, if it has one; "" if none

Throws:

javax.xml.stream.XMLStreamException - if cursor does not point to START_ELEMENT

getPrefixedName

public java.lang.String getPrefixedName()
                                 throws javax.xml.stream.XMLStreamException

Returns a String representation of either the fully-qualified name (if the event has full name) or the local name (if event does not have full name but has local name); or if no name available, throws stream exception.

Throws:

javax.xml.stream.XMLStreamException

hasLocalName

public boolean hasLocalName(java.lang.String expName)
                     throws javax.xml.stream.XMLStreamException

Method for verifying whether current named event (one for which getLocalName() can be called) has the specified local name or not.

Returns:

True if the local name associated with the event is as expected

Throws:

javax.xml.stream.XMLStreamException

hasName

public boolean hasName(java.lang.String expNsURI,
                       java.lang.String expLN)
                throws javax.xml.stream.XMLStreamException

Method for verifying whether current named event (one for which getLocalName() can be called) has the specified fully-qualified name or not. Both namespace URI and local name must match for the result to be true.

Returns:

True if the fully-qualified name associated with the event is as expected

Throws:

javax.xml.stream.XMLStreamException

getAttrCount

public int getAttrCount()
                 throws javax.xml.stream.XMLStreamException

Method that can be called when this cursor points to START_ELEMENT, and which will return number of attributes with values for the start element. This includes both explicit attribute values and possible implied default values (when DTD support is enabled by the underlying stream reader).

Throws:

javax.xml.stream.XMLStreamException - if either the underlying parser has problems (cursor not valid or not pointing to START_ELEMENT)

findAttrIndex

public int findAttrIndex(java.lang.String uri,
                         java.lang.String localName)
                  throws javax.xml.stream.XMLStreamException

Method that can be called when this cursor points to START_ELEMENT, and which will return index of specified attribute, if it exists for this element. If not, -1 is returned to denote "not found".

Throws:

javax.xml.stream.XMLStreamException - if either the underlying parser has problems (cursor not valid or not pointing to START_ELEMENT)

getAttrName

public javax.xml.namespace.QName getAttrName(int index)
                                      throws javax.xml.stream.XMLStreamException

Method that can be called when this cursor points to START_ELEMENT, and returns fully qualified name of the attribute at specified index. Index has to be between [0, getAttrCount()[; otherwise IllegalArgumentException will be thrown.

Parameters:

index - Index of the attribute

Throws:

javax.xml.stream.XMLStreamException - if either the underlying parser has problems (cursor not valid or not pointing to START_ELEMENT), or if invalid attribute

java.lang.IllegalArgumentException - if attribute index is invalid (less than 0 or greater than the last valid index [getAttributeCount()-1])

getAttrLocalName

public java.lang.String getAttrLocalName(int index)
                                  throws javax.xml.stream.XMLStreamException

Method that can be called when this cursor points to START_ELEMENT, and returns local name of the attribute at specified index. Index has to be between [0, getAttrCount()[; otherwise IllegalArgumentException will be thrown.

Parameters:

index - Index of the attribute

Throws:

javax.xml.stream.XMLStreamException - if either the underlying parser has problems (cursor not valid or not pointing to START_ELEMENT), or if invalid attribute

java.lang.IllegalArgumentException - if attribute index is invalid (less than 0 or greater than the last valid index [getAttributeCount()-1])

getAttrPrefix

public java.lang.String getAttrPrefix(int index)
                               throws javax.xml.stream.XMLStreamException

Method that can be called when this cursor points to START_ELEMENT, and returns namespace prefix of the attribute at specified index (if it has any), or empty String if attribute has no prefix (does not belong to a namespace). Index has to be between [0, getAttrCount()[; otherwise IllegalArgumentException will be thrown.

Parameters:

index - Index of the attribute

Throws:

javax.xml.stream.XMLStreamException - if either the underlying parser has problems (cursor not valid or not pointing to START_ELEMENT), or if invalid attribute

java.lang.IllegalArgumentException - if attribute index is invalid (less than 0 or greater than the last valid index [getAttributeCount()-1])

getAttrNsUri

public java.lang.String getAttrNsUri(int index)
                              throws javax.xml.stream.XMLStreamException

Method that can be called when this cursor points to START_ELEMENT, and returns namespace URI of the attribute at specified index (non-empty String if it has one, and empty String if attribute does not belong to a namespace) Index has to be between [0, getAttrCount()[; otherwise IllegalArgumentException will be thrown.

Parameters:

index - Index of the attribute

Throws:

javax.xml.stream.XMLStreamException - if either the underlying parser has problems (cursor not valid or not pointing to START_ELEMENT), or if invalid attribute

java.lang.IllegalArgumentException - if attribute index is invalid (less than 0 or greater than the last valid index [getAttributeCount()-1])

getAttrValue

public java.lang.String getAttrValue(int index)
                              throws javax.xml.stream.XMLStreamException

Method that can be called when this cursor points to START_ELEMENT, and returns unmodified textual value of the attribute at specified index (non-empty String if it has one, and empty String if attribute does not belong to a namespace) Index has to be between [0, getAttrCount()[; otherwise IllegalArgumentException will be thrown.

Parameters:

index - Index of the attribute

Throws:

javax.xml.stream.XMLStreamException - if either the underlying parser has problems (cursor not valid or not pointing to START_ELEMENT), or if invalid attribute

java.lang.IllegalArgumentException - if attribute index is invalid (less than 0 or greater than the last valid index [getAttributeCount()-1])

getAttrValue

public java.lang.String getAttrValue(java.lang.String localName)
                              throws javax.xml.stream.XMLStreamException

Convenience accessor method to access an attribute that is not in a namespace (has no prefix). Equivalent to calling getAttrValue(String,String) with 'null' for 'namespace URI' argument

Throws:

javax.xml.stream.XMLStreamException

getAttrValue

public java.lang.String getAttrValue(java.lang.String namespaceURI,
                                     java.lang.String localName)
                              throws javax.xml.stream.XMLStreamException

Method that can be called when this cursor points to START_ELEMENT, and returns unmodified textual value of the specified attribute (if element has it), or null if element has no value for such attribute.

Parameters:

namespaceURI - Namespace URI for the attribute, if any; empty String or null if none.

localName - Local name of the attribute to access (in namespace-aware mode: in non-namespace-aware mode, needs to be the full name)

Throws:

javax.xml.stream.XMLStreamException - if either the underlying parser has problems (cursor not valid or not pointing to START_ELEMENT), or if invalid attribute

getAttrBooleanValue

public boolean getAttrBooleanValue(int index)
                            throws java.lang.NumberFormatException,
                                   javax.xml.stream.XMLStreamException

Method for accessing value of specified attribute as boolean. Method will only succeed if the attribute value is a valid boolean, as specified by XML Schema specification (and hence is accessible via Stax2 Typed Access API).

Parameters:

index - Index of attribute to access

Throws:

javax.xml.stream.XMLStreamException - If specified attribute can not be accessed (due to cursor state), or if attribute value is not a valid textual representation of boolean

java.lang.IllegalArgumentException - If given attribute index is invalid

java.lang.NumberFormatException

getAttrBooleanValue

public boolean getAttrBooleanValue(int index,
                                   boolean defValue)
                            throws java.lang.NumberFormatException,
                                   javax.xml.stream.XMLStreamException

Method for accessing value of specified attribute as boolean. If attribute value is not a valid boolean (as specified by XML Schema specification), will instead return specified "default value".

Parameters:

index - Index of attribute to access

defValue - Value to return if attribute value exists but is not a valid boolean value

Throws:

javax.xml.stream.XMLStreamException - If specified attribute can not be accessed (due to cursor state), or if attribute value is not a valid textual representation of boolean.

java.lang.IllegalArgumentException - If given attribute index is invalid

java.lang.NumberFormatException

getAttrIntValue

public int getAttrIntValue(int index)
                    throws java.lang.NumberFormatException,
                           javax.xml.stream.XMLStreamException

Method for accessing value of specified attribute as integer. Method will only succeed if the attribute value is a valid integer, as specified by XML Schema specification (and hence is accessible via Stax2 Typed Access API).

Parameters:

index - Index of attribute to access

Throws:

javax.xml.stream.XMLStreamException - If specified attribute can not be accessed (due to cursor state), or if attribute value is not a valid textual representation of integer.

java.lang.IllegalArgumentException - If given attribute index is invalid

java.lang.NumberFormatException

getAttrIntValue

public int getAttrIntValue(int index,
                           int defValue)
                    throws java.lang.NumberFormatException,
                           javax.xml.stream.XMLStreamException

Method for accessing value of specified attribute as integer. If attribute value is not a valid integer (as specified by XML Schema specification), will instead return specified "default value".

Parameters:

index - Index of attribute to access

defValue - Value to return if attribute value exists but is not a valid integer value

Throws:

javax.xml.stream.XMLStreamException - If specified attribute can not be accessed (due to cursor state), or if attribute value is not a valid textual representation of integer.

java.lang.IllegalArgumentException - If given attribute index is invalid

java.lang.NumberFormatException

getAttrLongValue

public long getAttrLongValue(int index)
                      throws java.lang.NumberFormatException,
                             javax.xml.stream.XMLStreamException

Method for accessing value of specified attribute as long. Method will only succeed if the attribute value is a valid long, as specified by XML Schema specification (and hence is accessible via Stax2 Typed Access API).

Parameters:

index - Index of attribute to access

Throws:

javax.xml.stream.XMLStreamException - If specified attribute can not be accessed (due to cursor state), or if attribute value is not a valid textual representation of long.

java.lang.IllegalArgumentException - If given attribute index is invalid

java.lang.NumberFormatException

getAttrLongValue

public long getAttrLongValue(int index,
                             long defValue)
                      throws java.lang.NumberFormatException,
                             javax.xml.stream.XMLStreamException

Method for accessing value of specified attribute as long. If attribute value is not a valid long (as specified by XML Schema specification), will instead return specified "default value".

Parameters:

index - Index of attribute to access

defValue - Value to return if attribute value exists but is not a valid long value

Throws:

javax.xml.stream.XMLStreamException - If specified attribute can not be accessed (due to cursor state), or if attribute value is not a valid textual representation of long.

java.lang.IllegalArgumentException - If given attribute index is invalid

java.lang.NumberFormatException

getAttrIntValue

@Deprecated
public int getAttrIntValue(java.lang.String uri,
                                      java.lang.String localName)
                    throws javax.xml.stream.XMLStreamException

Deprecated. Use combination of findAttrIndex(java.lang.String, java.lang.String) and getAttrIntValue(int) instead.

Throws:

javax.xml.stream.XMLStreamException

getAttrIntValue

@Deprecated
public int getAttrIntValue(java.lang.String uri,
                                      java.lang.String localName,
                                      int defValue)
                    throws javax.xml.stream.XMLStreamException

Deprecated. Use combination of findAttrIndex(java.lang.String, java.lang.String) and getAttrIntValue(int,int) instead.

Throws:

javax.xml.stream.XMLStreamException

getElemStringValue

public java.lang.String getElemStringValue()
                                    throws javax.xml.stream.XMLStreamException

Method that can collect text directly contained within START_ELEMENT currently pointed by this cursor. This is different from collectDescendantText(boolean) in that it does NOT work for mixed content (child elements are not allowed: comments and processing instructions are allowed and ignored if encountered). If any ignorable white space (as per schema, dtd or so) is encountered, it will be ignored.

The main technical difference to collectDescendantText(boolean) is that this method tries to make use of Stax2 v3.0 Typed Access API, if available, and can thus be more efficient.

Throws:

javax.xml.stream.XMLStreamException - if content is not accessible; may also be thrown if child elements are encountered.

getElemBooleanValue

public boolean getElemBooleanValue()
                            throws javax.xml.stream.XMLStreamException

Method that can collect text directly contained within START_ELEMENT currently pointed by this cursor and convert it to a boolean value. For method to work, the value must be legal textual representation of boolean data type as specified by W3C Schema (as well as Stax2 Typed Access API). Element also can not contain mixed content (child elements; comments and processing instructions are allowed and ignored if encountered).

Throws:

javax.xml.stream.XMLStreamException - if content is not accessible or convertible to required return type

getElemBooleanValue

public boolean getElemBooleanValue(boolean defValue)
                            throws javax.xml.stream.XMLStreamException

Similar to getElemBooleanValue(), but instead of failing on invalid value, returns given default value.

Throws:

javax.xml.stream.XMLStreamException

getElemIntValue

public int getElemIntValue()
                    throws javax.xml.stream.XMLStreamException

Method that can collect text directly contained within START_ELEMENT currently pointed by this cursor and convert it to a int value. For method to work, the value must be legal textual representation of int data type as specified by W3C Schema (as well as Stax2 Typed Access API). Element also can not contain mixed content (child elements; comments and processing instructions are allowed and ignored if encountered).

Throws:

javax.xml.stream.XMLStreamException - if content is not accessible or convertible to required return type

getElemIntValue

public int getElemIntValue(int defValue)
                    throws javax.xml.stream.XMLStreamException

Similar to getElemIntValue(), but instead of failing on invalid value, returns given default value.

Throws:

javax.xml.stream.XMLStreamException

getElemLongValue

public long getElemLongValue()
                      throws javax.xml.stream.XMLStreamException

Method that can collect text directly contained within START_ELEMENT currently pointed by this cursor and convert it to a long value. For method to work, the value must be legal textual representation of long data type as specified by W3C Schema (as well as Stax2 Typed Access API). Element also can not contain mixed content (child elements; comments and processing instructions are allowed and ignored if encountered).

Throws:

javax.xml.stream.XMLStreamException - if content is not accessible or convertible to required return type

getElemLongValue

public long getElemLongValue(long defValue)
                      throws javax.xml.stream.XMLStreamException

Similar to getElemLongValue(), but instead of failing on invalid value, returns given default value.

Throws:

javax.xml.stream.XMLStreamException

getData

public java.lang.Object getData()

Method for accessing application-provided data set previously by a setData(java.lang.Object) call.

setData

public void setData(java.lang.Object o)

Method for assigning per-cursor application-managed data, readable using getData().

getNext

public abstract SMEvent getNext()
                         throws javax.xml.stream.XMLStreamException

Main iterating method.

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:

javax.xml.stream.XMLStreamException

childCursor

public SMInputCursor childCursor(SMFilter f)
                          throws javax.xml.stream.XMLStreamException

Method that will create a new nested cursor for iterating over all (immediate) child nodes of the start element this cursor currently points to that are passed by the specified filter. If cursor does not point to a start element, it will throw IllegalStateException; if it does not support concept of child cursors, it will throw UnsupportedOperationException

Parameters:

f - Filter child cursor is to use for filtering out 'unwanted' nodes; may be null if no filtering is to be done

Throws:

java.lang.IllegalStateException - If cursor can not be created due to the state cursor is in.

java.lang.UnsupportedOperationException - If cursor does not allow creation of child cursors.

javax.xml.stream.XMLStreamException

childCursor

public final SMInputCursor childCursor()
                                throws javax.xml.stream.XMLStreamException

Method that will create a new nested cursor for iterating over all (immediate) child nodes of the start element this cursor currently points to. If cursor does not point to a start element, it will throw IllegalStateException; if it does not support concept of child cursors, it will throw UnsupportedOperationException

Throws:

java.lang.IllegalStateException - If cursor can not be created due to the state cursor is in.

java.lang.UnsupportedOperationException - If cursor does not allow creation of child cursors.

javax.xml.stream.XMLStreamException

descendantCursor

public SMInputCursor descendantCursor(SMFilter f)
                               throws javax.xml.stream.XMLStreamException

Method that will create a new nested cursor for iterating over all the descendant (children and grandchildren) nodes of the start element this cursor currently points to that are accepted by the specified filter. If cursor does not point to a start element, it will throw IllegalStateException; if it does not support concept of descendant cursors, it will throw UnsupportedOperationException

Parameters:

f - Filter child cursor is to use for filtering out 'unwanted' nodes; may be null if no filtering is to be done

Throws:

java.lang.IllegalStateException - If cursor can not be created due to the state cursor is in (or for some cursors, if they never allow creating such cursors)

java.lang.UnsupportedOperationException - If cursor does not allow creation of descendant cursors.

javax.xml.stream.XMLStreamException

descendantCursor

public final SMInputCursor descendantCursor()
                                     throws javax.xml.stream.XMLStreamException

Method that will create a new nested cursor for iterating over all the descendant (children and grandchildren) nodes of the start element this cursor currently points to. If cursor does not point to a start element, it will throw IllegalStateException; if it does not support concept of descendant cursors, it will throw UnsupportedOperationException

Throws:

java.lang.IllegalStateException - If cursor can not be created due to the state cursor is in (or for some cursors, if they never allow creating such cursors)

java.lang.UnsupportedOperationException - If cursor does not allow creation of descendant cursors.

javax.xml.stream.XMLStreamException

childElementCursor

public final SMInputCursor childElementCursor()
                                       throws javax.xml.stream.XMLStreamException

Convenience method; equivalent to childCursor(SMFilterFactory.getElementOnlyFilter());

Throws:

javax.xml.stream.XMLStreamException

childElementCursor

public final SMInputCursor childElementCursor(javax.xml.namespace.QName elemName)
                                       throws javax.xml.stream.XMLStreamException

Convenience method; equivalent to childCursor(SMFilterFactory.getElementOnlyFilter(elemName)); Will only return START_ELEMENT and END_ELEMENT events, whose element name matches given qname.

Throws:

javax.xml.stream.XMLStreamException

childElementCursor

public final SMInputCursor childElementCursor(java.lang.String elemLocalName)
                                       throws javax.xml.stream.XMLStreamException

Convenience method; equivalent to childCursor(SMFilterFactory.getElementOnlyFilter(elemName)); Will only return START_ELEMENT and END_ELEMENT events, whose element's local name matches given local name, and that does not belong to a namespace.

Throws:

javax.xml.stream.XMLStreamException

descendantElementCursor

public final SMInputCursor descendantElementCursor()
                                            throws javax.xml.stream.XMLStreamException

Convenience method; equivalent to descendantCursor(SMFilterFactory.getElementOnlyFilter());

Throws:

javax.xml.stream.XMLStreamException

descendantElementCursor

public final SMInputCursor descendantElementCursor(javax.xml.namespace.QName elemName)
                                            throws javax.xml.stream.XMLStreamException

Convenience method; equivalent to descendantCursor(SMFilterFactory.getElementOnlyFilter(elemName)); Will only return START_ELEMENT and END_ELEMENT events, whose element name matches given qname.

Throws:

javax.xml.stream.XMLStreamException

descendantElementCursor

public final SMInputCursor descendantElementCursor(java.lang.String elemLocalName)
                                            throws javax.xml.stream.XMLStreamException

Convenience method; equivalent to descendantCursor(SMFilterFactory.getElementOnlyFilter(elemLocalName));. Will only return START_ELEMENT and END_ELEMENT events, whose element local name matches given local name, and that do not belong to a namespace

Throws:

javax.xml.stream.XMLStreamException

childMixedCursor

public final SMInputCursor childMixedCursor()
                                     throws javax.xml.stream.XMLStreamException

Convenience method; equivalent to childCursor(SMFilterFactory.getMixedFilter());

Throws:

javax.xml.stream.XMLStreamException

descendantMixedCursor

public final SMInputCursor descendantMixedCursor()
                                          throws javax.xml.stream.XMLStreamException

Convenience method; equivalent to descendantCursor(SMFilterFactory.getMixedFilter());

Throws:

javax.xml.stream.XMLStreamException

constructStreamException

public javax.xml.stream.XMLStreamException constructStreamException(java.lang.String msg)

Method for constructing stream exception with given message, and location that matches that of the underlying stream regardless of whether this cursor is valid (that is, will indicate location of the stream which may differ from where this cursor was last valid)

throwStreamException

public void throwStreamException(java.lang.String msg)
                          throws javax.xml.stream.XMLStreamException

Method for constructing and throwing stream exception with given message. Equivalent to throwing exception that constructStreamException(java.lang.String) constructs and returns.

Throws:

javax.xml.stream.XMLStreamException

getPathDesc

public java.lang.String getPathDesc()

Method that generates developer-readable description of the logical path of the event this cursor points to, assuming that element tracking is enabled. If it is, a path description will be constructed; if not, result will be "." ("unspecified current location").

Note: while results look similar to XPath expressions, they are not accurate (or even valid) XPath. This is partly because of filtering, and partly because of differences between element/node index calculation. The idea is to make it easier to get reasonable idea of logical location, in addition to physical input location.

getCurrEventDesc

protected java.lang.String getCurrEventDesc()

Returns:

Developer-readable description of the event this cursor currently points to.

toString

public java.lang.String toString()

Overridden implementation will just display description of the event this cursor points to (or last pointed to, if not valid)

constructElementInfo

protected SMElementInfo constructElementInfo(SMElementInfo parent,
                                             SMElementInfo prevSibling)
                                      throws javax.xml.stream.XMLStreamException

Method cursor calls when it needs to track element state information; if so, it calls this method to take a snapshot of the element.

Note caller already suppresses calls so that this method is only called when information needs to be preserved. Further, previous element is only passed if such linkage is to be preserved (reason for not always doing it is the increased memory usage).

Finally, note that this method does NOT implement ElementInfoFactory, as its signature does not include the cursor argument, as that's passed as this pointer already.

Throws:

javax.xml.stream.XMLStreamException

constructChildCursor

protected abstract SMInputCursor constructChildCursor(SMFilter f)
                                               throws javax.xml.stream.XMLStreamException

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.

Throws:

javax.xml.stream.XMLStreamException

constructDescendantCursor

protected abstract SMInputCursor constructDescendantCursor(SMFilter f)
                                                    throws javax.xml.stream.XMLStreamException

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.

Throws:

javax.xml.stream.XMLStreamException

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 javax.xml.stream.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:

javax.xml.stream.XMLStreamException

invalidate

protected void invalidate()
                   throws javax.xml.stream.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:

javax.xml.stream.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 javax.xml.stream.XMLStreamException _notAccessible(java.lang.String method)
                                                      throws javax.xml.stream.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:

javax.xml.stream.XMLStreamException

_wrongState

protected javax.xml.stream.XMLStreamException _wrongState(java.lang.String method,
                                                          SMEvent expState)
                                                   throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

getStateDesc

protected java.lang.String getStateDesc()

currentEventStr

protected java.lang.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.