Class SMInputCursor
- java.lang.Object
-
- org.codehaus.staxmate.in.CursorBase
-
- org.codehaus.staxmate.in.SMInputCursor
-
- Direct Known Subclasses:
SMFlatteningCursor
,SMHierarchicCursor
public abstract class SMInputCursor extends CursorBase
Base class for reader-side cursors that form the main input side abstraction offered by StaxMate. This class offers the main API for applications to use: sub-classes generally just implement abstract methods or override default behavior, but do not offer new public methods. As a result, up-casts are usually not necessary.Implementation Note: as cursors are thin wrappers around
XMLStreamReader2
, and since not all Stax implementations implementXMLStreamReader2
, some wrapping may be needed to expose basic Stax 1.0XMLStreamReader
s as Stax2XMLStreamReader2
readers. But without native support, not all stax2 features may be available for such stream readers. This should usuall not be a problem with cursor functionality, as cursors will try to limit their usage to known working subset, but care must be taken if application code wants to directly access underlying stream reader.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
SMInputCursor.Tracking
Different tracking behaviors available for cursors.-
Nested classes/interfaces inherited from class org.codehaus.staxmate.in.CursorBase
CursorBase.State
-
-
Field Summary
Fields Modifier and Type Field Description protected java.lang.Object
mData
Non-typesafe payload data that applications can use, to pass an extra argument along with cursors.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.-
Fields inherited from class org.codehaus.staxmate.in.CursorBase
_baseDepth, _childCursor, _context, _currEvent, _elemCount, _nodeCount, _parentTrackedElement, _state, _streamReader, _trackedElement
-
-
Constructor Summary
Constructors Constructor Description SMInputCursor(SMInputContext ctxt, SMInputCursor parent, SMFilter filter)
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description private void
_ensureEndElement()
This method can be called to ensure that this cursor gets to point to END_ELEMENT that closes typed element that has been read; usually this works as expected, but during type conversion exceptions handling may not work as expectedprotected void
_markConsumed()
Method to call to notify that textual contents of this cursor have been read; typically when a call has been made that will traverse contents and make stream point to matchingEND_ELEMENT
.private void
_verifyElemAccess(java.lang.String method)
Helper method called by getElemXxxValue methods to ensure that the state is appropriate for the callSMInputCursor
advance()
Method that does whatgetNext()
does, but instead of returning resulting event type, returns this cursor.private static void
appendPathDesc(java.lang.StringBuilder sb, SMElementInfo info, boolean recursive)
javax.xml.stream.events.XMLEvent
asEvent()
Method for accessing information regarding event this cursor points to, as an instance ofXMLEvent
.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 tochildCursor(SMFilterFactory.getElementOnlyFilter());
SMInputCursor
childElementCursor(java.lang.String elemLocalName)
Convenience method; equivalent tochildCursor(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
childElementCursor(javax.xml.namespace.QName elemName)
Convenience method; equivalent tochildCursor(SMFilterFactory.getElementOnlyFilter(elemName));
Will only return START_ELEMENT and END_ELEMENT events, whose element name matches given qname.SMInputCursor
childMixedCursor()
Convenience method; equivalent tochildCursor(SMFilterFactory.getMixedFilter());
java.lang.String
collectDescendantText()
Same as callingcollectDescendantText(boolean)
with 'false': that is, do not include ignorable white space (as determined by DTD or Schema) in the result text.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)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 todescendantCursor(SMFilterFactory.getElementOnlyFilter());
SMInputCursor
descendantElementCursor(java.lang.String elemLocalName)
Convenience method; equivalent todescendantCursor(SMFilterFactory.getElementOnlyFilter(elemLocalName));
.SMInputCursor
descendantElementCursor(javax.xml.namespace.QName elemName)
Convenience method; equivalent todescendantCursor(SMFilterFactory.getElementOnlyFilter(elemName));
Will only return START_ELEMENT and END_ELEMENT events, whose element name matches given qname.SMInputCursor
descendantMixedCursor()
Convenience method; equivalent todescendantCursor(SMFilterFactory.getMixedFilter());
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.byte[]
getAttrBinaryValue(int index)
Method for accessing value of a base64-encoded attribute, using default base64 encoding variant (as perBase64Variants.getDefaultVariant()
.byte[]
getAttrBinaryValue(int index, org.codehaus.stax2.typed.Base64Variant variant)
Method for accessing value of a base64-encoded attribute, using specified base64 encoding variant.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.double
getAttrDoubleValue(int index)
Method for accessing value of specified attribute as double.double
getAttrDoubleValue(int index, double defValue)
Method for accessing value of specified attribute as double.<T extends java.lang.Enum<T>>
TgetAttrEnumValue(int index, java.lang.Class<T> enumType)
Method for accessing value of specified attribute as an Enum value of specified type, if content non-empty.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 offindAttrIndex(java.lang.String, java.lang.String)
andgetAttrIntValue(int)
instead.int
getAttrIntValue(java.lang.String uri, java.lang.String localName, int defValue)
Deprecated.Use combination offindAttrIndex(java.lang.String, java.lang.String)
andgetAttrIntValue(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()
[; otherwiseIllegalArgumentException
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()
[; otherwiseIllegalArgumentException
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.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 for accessing type of the current event (as would be returned bygetCurrEvent()
) as one of event types defined inXMLStreamConstants
(likeXMLStreamConstants.START_ELEMENT
).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 asetData(java.lang.Object)
call.byte[]
getElemBinaryValue()
Method for accessing value current element, which isbase64-encoded binary data, by decoding contents using the default base64 variantbyte[]
getElemBinaryValue(org.codehaus.stax2.typed.Base64Variant variant)
Method for accessing value current element, which isbase64-encoded binary data, by decoding contents using specified variant.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 togetElemBooleanValue()
, but instead of failing on invalid value, returns given default value.double
getElemDoubleValue()
Method that can collect text directly contained within START_ELEMENT currently pointed by this cursor and convert it to a double value.double
getElemDoubleValue(double defValue)
Similar togetElemDoubleValue()
, 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()
<T extends java.lang.Enum<T>>
TgetElemEnumValue(java.lang.Class<T> enumType)
Method that can collect text directly contained within START_ELEMENT currently pointed by this cursor and convert it to one of enumerated values of given type, if textual value non-type, and otherwise to null.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 togetElemIntValue()
, 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 togetElemLongValue()
, 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()
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 whichXMLStreamReader.getText()
can be called.SMElementInfo
getTrackedElement()
boolean
hasLocalName(java.lang.String expName)
Method for verifying whether current named event (one for whichgetLocalName()
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 whichgetLocalName()
can be called) has the specified fully-qualified name or not.boolean
hasName(javax.xml.namespace.QName qname)
Equivalent to callinghasName(String, String)
with namespace URI and local name contained in the argument QNameboolean
isRootCursor()
Method for determining whether this cursor iterates over root level of the underlying stream readervoid
processDescendantText(java.io.Writer w, boolean includeIgnorable)
Method similar tocollectDescendantText(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.void
setData(java.lang.Object o)
Method for assigning per-cursor application-managed data, readable usinggetData()
.void
setElementInfoFactory(ElementInfoFactory f)
Set element info factory used for constructingSMElementInfo
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 whengetNext()
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 org.codehaus.staxmate.in.CursorBase
_constructTypedException, _getStreamReader, _notAccessible, _throwUnexpectedEndDoc, _throwWrongEndElem, _wrongState, currentEventStr, eventObjectByEventId, getBaseParentCount, getStateDesc, invalidate, rewindPastChild
-
-
-
-
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. SeeSMInputCursor.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.
-
-
Constructor Detail
-
SMInputCursor
public SMInputCursor(SMInputContext ctxt, SMInputCursor parent, 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 whengetNext()
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 constructingSMElementInfo
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'sXMLStreamReader.next()
method is called, but not counting child cursors' node counts. Whether END_ELEMENTs (end tags) are included depends on type of cursor: for nested (which do not return events for end tags) they are not counted, but for flattened one (that do return) they are counted as nodes.- 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'sXMLStreamReader.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
-
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 for accessing type of the current event (as would be returned bygetCurrEvent()
) as one of event types defined inXMLStreamConstants
(likeXMLStreamConstants.START_ELEMENT
).
-
isRootCursor
public final boolean isRootCursor()
Method for determining whether this cursor iterates over root level of the underlying stream reader- Specified by:
isRootCursor
in classCursorBase
- 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 content (END_ELEMENT).- Returns:
- True if the cursor is currently valid; false if not
-
getStreamReader
public final 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 perreaderAccessible()
); 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 callinggetCursorLocation()
- 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 whichXMLStreamReader.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
-
collectDescendantText
public final java.lang.String collectDescendantText() throws javax.xml.stream.XMLStreamException
Same as callingcollectDescendantText(boolean)
with 'false': that is, do not include ignorable white space (as determined by DTD or Schema) in the result text.Note: it is not common to have have ignorable white space; it usually results from indentation, but its detection requires DTD/schema-aware processing
- Throws:
javax.xml.stream.XMLStreamException
- Since:
- 2.0.0
-
processDescendantText
public void processDescendantText(java.io.Writer w, boolean includeIgnorable) throws java.io.IOException, javax.xml.stream.XMLStreamException
Method similar tocollectDescendantText(boolean)
, but will write the text to specified Writer instead of collecting it into a String.- Parameters:
w
- Writer to use for outputting text foundincludeIgnorable
- 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 whichgetLocalName()
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 whichgetLocalName()
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
-
hasName
public boolean hasName(javax.xml.namespace.QName qname) throws javax.xml.stream.XMLStreamException
Equivalent to callinghasName(String, String)
with namespace URI and local name contained in the argument QName- Parameters:
qname
- Name to compare name of current event (if any) against.- Throws:
javax.xml.stream.XMLStreamException
- Since:
- 2.0
-
asEvent
public javax.xml.stream.events.XMLEvent asEvent() throws javax.xml.stream.XMLStreamException
Method for accessing information regarding event this cursor points to, as an instance ofXMLEvent
. Depending on underlying input source this may be constructed from scratch (for example, if the input cursor was not constructed fromXMLEventReader
), or accessed from the underlying event reader.Calling this method does not advance the underlying stream or cursor itself.
Note, too, that it is ok to call this method at any time: if the cursor is not in valid state for accessing information null will be returned.
- Returns:
- Information about currently pointed-to input stream event, if we are pointing to one; null otherwise
- Throws:
javax.xml.stream.XMLStreamException
- Since:
- 2.0.0
-
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()
[; otherwiseIllegalArgumentException
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 attributejava.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()
[; otherwiseIllegalArgumentException
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 attributejava.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()
[; otherwiseIllegalArgumentException
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 attributejava.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()
[; otherwiseIllegalArgumentException
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 attributejava.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()
[; otherwiseIllegalArgumentException
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 attributejava.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 callinggetAttrValue(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 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 booleanjava.lang.IllegalArgumentException
- If given attribute index is invalid
-
getAttrBooleanValue
public boolean getAttrBooleanValue(int index, boolean defValue) throws 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 accessdefValue
- 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
-
getAttrIntValue
public int getAttrIntValue(int index) throws 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
-
getAttrIntValue
public int getAttrIntValue(int index, int defValue) throws 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 accessdefValue
- 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
-
getAttrLongValue
public long getAttrLongValue(int index) throws 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
-
getAttrLongValue
public long getAttrLongValue(int index, long defValue) throws 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 accessdefValue
- 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
-
getAttrDoubleValue
public double getAttrDoubleValue(int index) throws javax.xml.stream.XMLStreamException
Method for accessing value of specified attribute as double. Method will only succeed if the attribute value is a valid double, 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 double.java.lang.IllegalArgumentException
- If given attribute index is invalid
-
getAttrDoubleValue
public double getAttrDoubleValue(int index, double defValue) throws javax.xml.stream.XMLStreamException
Method for accessing value of specified attribute as double. If attribute value is not a valid double (as specified by XML Schema specification), will instead return specified "default value".- Parameters:
index
- Index of attribute to accessdefValue
- Value to return if attribute value exists but is not a valid double 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 double.java.lang.IllegalArgumentException
- If given attribute index is invalid
-
getAttrEnumValue
public <T extends java.lang.Enum<T>> T getAttrEnumValue(int index, java.lang.Class<T> enumType) throws javax.xml.stream.XMLStreamException
Method for accessing value of specified attribute as an Enum value of specified type, if content non-empty. If it is empty, will return null. And if non-empty value is not equal to name() of one of Enum values, will throw aTypedXMLStreamException
to indicate the problem.- 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 double.java.lang.IllegalArgumentException
- If given attribute index is invalid
-
getAttrBinaryValue
public byte[] getAttrBinaryValue(int index, org.codehaus.stax2.typed.Base64Variant variant) throws javax.xml.stream.XMLStreamException
Method for accessing value of a base64-encoded attribute, using specified base64 encoding variant.- Throws:
javax.xml.stream.XMLStreamException
- Since:
- 2.2
-
getAttrBinaryValue
public byte[] getAttrBinaryValue(int index) throws javax.xml.stream.XMLStreamException
Method for accessing value of a base64-encoded attribute, using default base64 encoding variant (as perBase64Variants.getDefaultVariant()
.- Throws:
javax.xml.stream.XMLStreamException
- Since:
- 2.2
-
getAttrIntValue
@Deprecated public int getAttrIntValue(java.lang.String uri, java.lang.String localName) throws javax.xml.stream.XMLStreamException
Deprecated.Use combination offindAttrIndex(java.lang.String, java.lang.String)
andgetAttrIntValue(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 offindAttrIndex(java.lang.String, java.lang.String)
andgetAttrIntValue(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 fromcollectDescendantText(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 togetElemBooleanValue()
, 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 togetElemIntValue()
, 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 togetElemLongValue()
, but instead of failing on invalid value, returns given default value.- Throws:
javax.xml.stream.XMLStreamException
-
getElemDoubleValue
public double getElemDoubleValue() 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 double value. For method to work, the value must be legal textual representation of double 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
-
getElemDoubleValue
public double getElemDoubleValue(double defValue) throws javax.xml.stream.XMLStreamException
Similar togetElemDoubleValue()
, but instead of failing on invalid value, returns given default value.- Throws:
javax.xml.stream.XMLStreamException
-
getElemEnumValue
public <T extends java.lang.Enum<T>> T getElemEnumValue(java.lang.Class<T> enumType) throws javax.xml.stream.XMLStreamException
Method that can collect text directly contained within START_ELEMENT currently pointed by this cursor and convert it to one of enumerated values of given type, if textual value non-type, and otherwise to null. If a non-empty value that is not one of legal enumerated values is encountered, aTypedXMLStreamException
is thrown.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 typeorg.codehaus.stax2.typed.TypedXMLStreamException
- if element value is non-empty and not one of allowed values for the enumeration type
-
getElemBinaryValue
public byte[] getElemBinaryValue(org.codehaus.stax2.typed.Base64Variant variant) throws javax.xml.stream.XMLStreamException
Method for accessing value current element, which isbase64-encoded binary data, by decoding contents using specified variant.- Throws:
javax.xml.stream.XMLStreamException
- Since:
- 2.2
-
getElemBinaryValue
public byte[] getElemBinaryValue() throws javax.xml.stream.XMLStreamException
Method for accessing value current element, which isbase64-encoded binary data, by decoding contents using the default base64 variant- Throws:
javax.xml.stream.XMLStreamException
- Since:
- 2.2
-
_verifyElemAccess
private final void _verifyElemAccess(java.lang.String method) throws javax.xml.stream.XMLStreamException
Helper method called by getElemXxxValue methods to ensure that the state is appropriate for the call- Throws:
javax.xml.stream.XMLStreamException
-
_ensureEndElement
private final void _ensureEndElement() throws javax.xml.stream.XMLStreamException
This method can be called to ensure that this cursor gets to point to END_ELEMENT that closes typed element that has been read; usually this works as expected, but during type conversion exceptions handling may not work as expected- Throws:
javax.xml.stream.XMLStreamException
-
getData
public java.lang.Object getData()
Method for accessing application-provided data set previously by asetData(java.lang.Object)
call.
-
setData
public void setData(java.lang.Object o)
Method for assigning per-cursor application-managed data, readable usinggetData()
.
-
getNext
public abstract SMEvent getNext() throws javax.xml.stream.XMLStreamException
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.
- Returns:
- Type of event (from
XMLStreamConstants
, such asXMLStreamConstants.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
- If there are underlying parsing problems.
-
advance
public final SMInputCursor advance() throws javax.xml.stream.XMLStreamException
Method that does whatgetNext()
does, but instead of returning resulting event type, returns this cursor. The main purpose of this method is to allow for chaining calls. This is especially useful right after constructing a root level cursor, and needing to advance it to point to the root element. As such, a common idiom is:SMInputCursor positionedRoot = smFactory.rootElementCursor(file).advance();
which both constructs the root element cursor, and positions it over the root element. Can be similarly used with other kinds of cursors as well, of course- Throws:
javax.xml.stream.XMLStreamException
- Since:
- 2.0
-
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 throwIllegalStateException
; if it does not support concept of child cursors, it will throwUnsupportedOperationException
- 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 throwIllegalStateException
; if it does not support concept of child cursors, it will throwUnsupportedOperationException
- 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 throwIllegalStateException
; if it does not support concept of descendant cursors, it will throwUnsupportedOperationException
- 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 throwIllegalStateException
; if it does not support concept of descendant cursors, it will throwUnsupportedOperationException
- 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 tochildCursor(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 tochildCursor(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 tochildCursor(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 todescendantCursor(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 todescendantCursor(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 todescendantCursor(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 tochildCursor(SMFilterFactory.getMixedFilter());
- Throws:
javax.xml.stream.XMLStreamException
-
descendantMixedCursor
public final SMInputCursor descendantMixedCursor() throws javax.xml.stream.XMLStreamException
Convenience method; equivalent todescendantCursor(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)- Specified by:
constructStreamException
in classCursorBase
-
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 thatconstructStreamException(java.lang.String)
constructs and returns.- Specified by:
throwStreamException
in classCursorBase
- 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.
-
appendPathDesc
private static void appendPathDesc(java.lang.StringBuilder sb, SMElementInfo info, boolean recursive)
-
getCurrEventDesc
protected java.lang.String getCurrEventDesc()
- Specified by:
getCurrEventDesc
in classCursorBase
- 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)- Overrides:
toString
in classCursorBase
-
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
-
_markConsumed
protected void _markConsumed()
Method to call to notify that textual contents of this cursor have been read; typically when a call has been made that will traverse contents and make stream point to matchingEND_ELEMENT
.- Since:
- 2.2
-
-