XmlCursor Interface
- public interface XmlCursor
extends XmlTokenSource
Represents a position between two logical tokens in an XML document.
The tokens themselves are not exposed as objects, but their type and properties
are discoverable through methods on the cursor. In particular, the general
category of token is represented by a XmlCursor.TokenType
.
You use an XmlCursor instance to navigate through and manipulate an XML
instance document.
Once you obtain an XML document, you can create a cursor to represent
a specific place in the XML. Because you can use a cursor with or
without a schema corresponding to the XML, cursors are an ideal
way to handle XML without a schema. You can create a new cursor by
calling the newCursor
method
exposed by an object representing
the XML, whether it was parsed into a strong type compiled from
schema or an XmlObject
(as in the no-schema case).
With an XmlCursor, you can also:
- Execute XQuery and XPath expressions against the XML with the
execQuery and selectPath methods.
- Edit and reshape the document by inserting, moving, copying, and removing
XML.
- Insert bookmarks that "stick" to the XML at the cursor's
position even if the cursor or XML moves.
- Get and set values for containers (elements and whole documents),
attributes, processing instructions, and comments.
A cursor moves through XML by moving past tokens. A
token represents a category of XML markup, such as the start of an element,
its end, an attribute, comment, and so on. XmlCursor methods such as
toNextToken, toNextSibling, toParent, and so on move the cursor
among tokens. Each token's category is of a particular type, represented
by one of the nine types defined by the XmlCursor.TokenType
class.
When you get a new cursor for a whole instance document, the cursor is
intially located before the STARTDOC token. This token, which has no analogy
in the XML specification, is present in this logical model of XML
so that you may distinguish between the document as a whole
and the content of the document. Terminating the document is an ENDDOC
token. This token is also not part of the XML specification. A cursor
located immediately before this token is at the very end of the document.
It is not possible to position the cursor after the ENDDOC token.
Thus, the STARTDOC and ENDDOC tokens are effectively "bookends" for the content of
the document.
For example, for the following XML, if you were the navigate a cursor
through the XML document using toNextToken(), the list of token types that
follows represents the token sequence you would encounter.
<sample x='y'>
<value>foo</value>
</sample>
STARTDOC
START (sample)
ATTR (x='y')
TEXT ("\n ")
START (value)
TEXT ("foo")
END (value)
TEXT ("\n")
END (sample)
ENDDOC
When there are no more tokens available, hasNextToken() returns
false and toNextToken() returns the special token type NONE and does not move
the cursor.
The currentTokenType()
method
will return the type of the token that is immediately after the cursor.
You can also use a number of convenience methods that test for a particular
token type. These include the methods isStart(),
isStartdoc(), isText(), isAttr(), and so on. Each returns a boolean
value indicating whether the token that follows the cursor is the type
in question.
A few other methods determine whether the token is of a kind that may include
multiple token types. The isAnyAttr() method, for example, returns true if
the token immediately following the cursor is any kind of attribute,
including those of the ATTR token type and xmlns attributes.
Legitimate sequences of tokens for an XML document are described
by the following Backus-Naur Form (BNF):
<doc> ::= STARTDOC <attributes> <content> ENDDOC
<element> ::= START <attributes> <content> END
<attributes> ::= ( ATTR | NAMESPACE ) *
<content> ::= ( COMMENT | PROCINST | TEXT | <element> ) *
Note that a legitimate sequence is STARTDOC ENDDOC, the result of
creating a brand new instance of an empty document. Also note that
attributes may only follow container tokens (STARTDOC or START)
-
All Superinterfaces
-
XmlTokenSource
public void |
-
addToSelection ()
- Appends the current location of the cursor to the selection.
|
public void |
-
beginElement (QName name)
- Inserts a new element around this cursor, giving the element the specified
qualified name.
|
public void |
-
beginElement (String localName)
- Inserts a new element around this cursor, giving the element the specified
local name.
|
public void |
-
beginElement (String localName, String uri)
- Inserts a new element around this cursor, giving the element the specified
local name and associating it with the specified namespace.
|
public void |
-
clearBookmark (Object key)
- Clears the bookmark whose key is specified, if the bookmark
exists at this cursor's location.
|
public void |
-
clearSelections ()
- Clears this cursor's selection, but does not modify the document.
|
public int |
-
comparePosition (XmlCursor cursor)
- Returns an integer indicating whether this cursor is before,
after, or at the same position as the specified cursor.
|
public int |
-
copyChars (int maxCharacterCount, XmlCursor toHere)
- Copies characters to the position immediately after the specified cursor.
|
public boolean |
-
copyXml (XmlCursor toHere)
- Copies the XML immediately after this cursor to the location
specified by the toHere cursor.
|
public boolean |
-
copyXmlContents (XmlCursor toHere)
- Copies the contents of the container (STARTDOC OR START) immediately to
the right of the cursor to the location specified by the toHere cursor.
|
public XmlCursor.TokenType |
-
currentTokenType ()
- Returns the type of the current token.
|
public void |
-
dispose ()
- Deallocates resources needed to manage the cursor, rendering this cursor
inoperable.
|
public XmlCursor |
-
execQuery (String query)
- Executes the specified XQuery expression against the XML this
cursor is in.
|
public XmlCursor |
-
execQuery (String query, XmlOptions options)
- Executes the specified XQuery expression against the XML this
cursor is in, and using the specified options.
|
public void |
-
getAllBookmarkRefs (Collection listToFill)
- Retrieves all the bookmarks at this location, adding them to
the specified collection.
|
public void |
-
getAllNamespaces (Map addToThis)
- Adds to the specified map, all the namespaces in scope at the container
where this cursor is positioned.
|
public String |
-
getAttributeText (QName attrName)
- When at a START or STARTDOC, returns the attribute text for the given
attribute.
|
public XmlCursor.XmlBookmark |
-
getBookmark (Object key)
- Retrieves the bookmark with the specified key
at this cursor's location.
|
public String |
-
getChars ()
- Returns characters to the right of the cursor up to the next token.
|
public int |
-
getChars (char[] returnedChars, int offset, int maxCharacterCount)
- Copies characters up to the specified maximum number, counting right from
this cursor's location to the character at maxCharacterCount.
|
public XmlCursor.ChangeStamp |
-
getDocChangeStamp ()
- Returns the current change stamp for the document the current cursor is in.
|
public QName |
-
getName ()
- Returns the name of the current token.
|
public XmlObject |
-
getObject ()
- Returns the strongly-typed XmlObject at the current START,
STARTDOC, or ATTR.
|
public int |
-
getSelectionCount ()
- Returns the count of the current selection.
|
public String |
-
getTextValue ()
- Gets the text value of the current document, element, attribute,
comment, procinst or text token.
|
public int |
-
getTextValue (char[] returnedChars, int offset, int maxCharacterCount)
- Copies the text value of the current document, element, attribute,
comment, processing instruction or text token, counting right from
this cursor's location up to maxCharacterCount,
and copies the returned text into returnedChars.
|
public boolean |
-
hasNextSelection ()
- Returns whether or not there is a next selection.
|
public boolean |
-
hasNextToken ()
- True if there is a next token.
|
public boolean |
-
hasPrevToken ()
- True if there is a previous token.
|
public void |
-
insertAttribute (String localName)
- Inserts a new attribute immediately before this cursor's location, giving it
the specified local name.
|
public void |
-
insertAttribute (String localName, String uri)
- Inserts a new attribute immediately before this cursor's location, giving it
the specified local name and associating it with the specified namespace.
|
public void |
-
insertAttribute (QName name)
- Inserts a new attribute immediately before this cursor's location, giving it
the specified name.
|
public void |
-
insertAttributeWithValue (String Name, String value)
- Inserts a new attribute immediately before this cursor's location, giving it
the specified value and name.
|
public void |
-
insertAttributeWithValue (String name, String uri, String value)
- Inserts an attribute immediately before the cursor's location, giving it
the specified name and value, and associating it with the specified namespace.
|
public void |
-
insertAttributeWithValue (QName name, String value)
- Inserts an attribute immediately before the cursor's location, giving it
the specified name and value.
|
public void |
-
insertChars (String text)
- Inserts the specified text immediately before this cursor's location.
|
public void |
-
insertComment (String text)
- Inserts an XML comment immediately before the cursor's location,
giving it the specified content.
|
public void |
-
insertElement (QName name)
- Inserts an element immediately before this cursor's location, giving
the element the specified qualified name.
|
public void |
-
insertElement (String localName)
- Inserts an element immediately before this cursor's location, giving
the element the specified local name.
|
public void |
-
insertElement (String localName, String uri)
- Inserts a new element immediately before this cursor's location, giving the
element the specified local name and associating it with specified namespace
|
public void |
-
insertElementWithText (QName name, String text)
- Inserts a new element immediately before this cursor's location, giving the
element the specified qualified name and content.
|
public void |
-
insertElementWithText (String localName, String text)
- Inserts a new element immediately before this cursor's location, giving the
element the specified local name and content.
|
public void |
-
insertElementWithText (String localName, String uri, String text)
- Inserts a new element immediately before this cursor's location, giving the
element the specified local name, associating it with the specified namespace,
and giving it the specified content.
|
public void |
-
insertNamespace (String prefix, String namespace)
- Inserts a namespace declaration immediately before the cursor's location,
giving it the specified prefix and URI.
|
public void |
-
insertProcInst (String target, String text)
- Inserts an XML processing instruction immediately before the cursor's location,
giving it the specified target and text.
|
public boolean |
-
isAnyAttr ()
- True if this token is any attribute.
|
public boolean |
-
isAtSamePositionAs (XmlCursor cursor)
- Determines if this cursor is at the same position as
the specified cursor.
|
public boolean |
-
isAttr ()
- True if this token is an ATTR token type, meaning
just before an attribute.
|
public boolean |
-
isComment ()
- True if this token is a COMMENT token type, meaning
just before a comment.
|
public boolean |
-
isContainer ()
- True if this token is a container token.
|
public boolean |
-
isEnd ()
- True if this token is an END token type, meaning
just before an element's end.
|
public boolean |
-
isEnddoc ()
- True if this token is an ENDDOC token type, meaning
at the very end of the document.
|
public boolean |
-
isFinish ()
- True if this token is a finish token.
|
public boolean |
-
isInSameDocument (XmlCursor cursor)
- Determines if the specified cursor is in the same document as
this cursor.
|
public boolean |
-
isLeftOf (XmlCursor cursor)
- Determines if this cursor is to the left of (or before)
the specified cursor.
|
public boolean |
-
isNamespace ()
- True if this token is a NAMESPACE token type, meaning
just before a namespace declaration.
|
public boolean |
-
isProcinst ()
- True if this token is a PROCINST token type, meaning
just before a processing instruction.
|
public boolean |
-
isRightOf (XmlCursor cursor)
- Determines if this cursor is to the right of (or after)
the specified cursor.
|
public boolean |
-
isStart ()
- True if this token is a START token type, meaning
just before an element's start.
|
public boolean |
-
isStartdoc ()
- True if the current token is a STARTDOC token type, meaning
at the very root of the document.
|
public boolean |
-
isText ()
- True if the this token is a TEXT token type, meaning
just before or inside text.
|
public int |
-
moveChars (int maxCharacterCount, XmlCursor toHere)
- Moves characters immediately after this cursor to the position immediately
after the specified cursor.
|
public boolean |
-
moveXml (XmlCursor toHere)
- Moves the XML immediately after this cursor to the location
specified by the toHere cursor, shifting XML at that location
to the right to make room.
|
public boolean |
-
moveXmlContents (XmlCursor toHere)
- Moves the contents of the container (STARTDOC OR START) immediately after
this cursor to the location specified by the toHere cursor.
|
public String |
-
namespaceForPrefix (String prefix)
- Returns the namespace URI indicated by the given prefix.
|
public boolean |
-
pop ()
- Restores the cursor location most recently saved with the push() method.
|
public String |
-
prefixForNamespace (String namespaceURI)
- Returns a prefix that can be used to indicate a namespace URI.
|
public XmlCursor.TokenType |
-
prevTokenType ()
- Returns the type of the previous token.
|
public void |
-
push ()
- Saves the current location of this cursor on an internal stack of saved
positions (independent of selection).
|
public boolean |
-
removeAttribute (QName attrName)
- When at a START or STARTDOC, removes the attribute with the given name.
|
public int |
-
removeChars (int maxCharacterCount)
- Removes characters up to the specified maximum number, counting right from
this cursor's location to the character at maxCharacterCount.
|
public boolean |
-
removeXml ()
- Removes the XML that is immediately after this cursor.
|
public boolean |
-
removeXmlContents ()
- Removes the contents of the container (STARTDOC OR START) immediately after
this cursor.
|
public void |
-
selectPath (String path)
- Executes the specified XPath expression against the XML that this
cursor is in.
|
public void |
-
selectPath (String path, XmlOptions options)
- Executes the specified XPath expression against the XML that this
cursor is in.
|
public boolean |
-
setAttributeText (QName attrName, String value)
- When at a START or STARTDOC, sets the attribute text for the given
attribute.
|
public void |
-
setBookmark (XmlCursor.XmlBookmark bookmark)
- Sets a bookmark to the document at this cursor's location.
|
public void |
-
setName (QName name)
- Sets the name of the current token.
|
public void |
-
setTextValue (String text)
- Sets the text value of the XML at this cursor's location if that XML's
token type is START, STARTDOC, ATTR, COMMENT or PROCINST.
|
public void |
-
setTextValue (char[] sourceChars, int offset, int length)
- Sets the text value of the XML at this cursor's location (if that XML's
token type is START, STARTDOC, ATTR, COMMENT or PROCINST) to the
contents of the specified character array.
|
public boolean |
-
toBookmark (XmlCursor.XmlBookmark bookmark)
- Moves this cursor to the same position as the bookmark.
|
public boolean |
-
toChild (String name)
- Moves the cursor to the first child element of the specified name in
no namespace.
|
public boolean |
-
toChild (String namespace, String name)
- Moves the cursor to the first child element of the specified name in the
specified namespace.
|
public boolean |
-
toChild (QName name)
- Moves the cursor to the first child element of the specified qualified name.
|
public boolean |
-
toChild (int index)
- Moves the cursor to the child element specified by index.
|
public boolean |
-
toChild (QName name, int index)
- Moves the cursor to the specified index child element of the
specified name, where that element is the .
|
public boolean |
-
toCursor (XmlCursor moveTo)
- Moves this cursor to the same position as the moveTo cursor.
|
public void |
-
toEndDoc ()
- Moves the cursor to the ENDDOC token, which is the end
of the document.
|
public XmlCursor.TokenType |
-
toEndToken ()
- Moves the cursor to the END or ENDDOC token corresponding to the
current START or STARTDOC, and returns END or ENDDOC.
|
public boolean |
-
toFirstAttribute ()
- Moves the cursor to the first attribute of this element, or
returns false and does not move the cursor if there are no
attributes.
|
public boolean |
-
toFirstChild ()
- Moves the cursor to the first child element, or returns false and
does not move the cursor if there are no element children.
|
public XmlCursor.TokenType |
-
toFirstContentToken ()
- Moves the cursor to the first token in the content of the current
START or STARTDOC.
|
public boolean |
-
toLastAttribute ()
- Moves the cursor to the last attribute of this element, or
returns false and does not move the cursor if there are no
attributes.
|
public boolean |
-
toLastChild ()
- Moves the cursor to the last element child, or returns false and
does not move the cursor if there are no element children.
|
public boolean |
-
toNextAttribute ()
- Moves the cursor to the next sibling attribute, or returns
false and does not move the cursor if there is no next
sibling attribute.
|
public XmlCursor.XmlBookmark |
-
toNextBookmark (Object key)
- Moves this cursor to the location after its current position
where a bookmark with the given key exists.
|
public int |
-
toNextChar (int maxCharacterCount)
- Moves the cursor forward by the specified number of characters, and
stops at the next non-TEXT token.
|
public boolean |
-
toNextSelection ()
- Moves this cursor to the next location in the selection,
if any.
|
public boolean |
-
toNextSibling ()
- Moves the cursor to the next sibling element, or returns
false and does not move the cursor if there is no next sibling
element.
|
public boolean |
-
toNextSibling (String name)
- Moves the cursor to the next sibling element of the specified name in no
namespace.
|
public boolean |
-
toNextSibling (String namespace, String name)
- Moves the cursor to the next sibling element of the specified name
in the specified namespace.
|
public boolean |
-
toNextSibling (QName name)
- Moves the cursor to the next sibling element of the specified
qualified name.
|
public XmlCursor.TokenType |
-
toNextToken ()
- Moves the cursor to the next token.
|
public boolean |
-
toParent ()
- Moves the cursor to the parent element or STARTDOC, or returns
false and does not move the cursor if there is no parent.
|
public boolean |
-
toPrevAttribute ()
- Moves the cursor to the previous sibling attribute, or returns
false and does not move the cursor if there is no previous
sibling attribute.
|
public XmlCursor.XmlBookmark |
-
toPrevBookmark (Object key)
- Moves this cursor to the location before its current position
where a bookmark with the given key exists.
|
public int |
-
toPrevChar (int maxCharacterCount)
- Moves the cursor backwards by the number of characters given.
|
public boolean |
-
toPrevSibling ()
- Moves the cursor to the previous sibling element, or returns
false and does not move the cursor if there is no previous sibling
element.
|
public XmlCursor.TokenType |
-
toPrevToken ()
- Moves the cursor to the previous token.
|
public boolean |
-
toSelection (int i)
- Moves this cursor to the specified location in the selection.
|
public void |
-
toStartDoc ()
- Moves the cursor to the STARTDOC token, which is the
root of the document.
|
Methods from interface com.bea.xml.XmlTokenSource |
documentProperties , monitor , newCursor , newDomNode , newDomNode , newInputStream , newInputStream , newReader , newReader , newXMLInputStream , newXMLInputStream , save , save , save , save , save , save , save , save , xmlText , xmlText
|
addToSelection() Method
public void addToSelection()
Appends the current location of the cursor to the selection.
See also the selectPath() method. You can use this as an
alternative to calling the selectPath method when you want
to define your own selection.
beginElement(QName) Method
public void beginElement(QName
name)
Inserts a new element around this cursor, giving the element the specified
qualified name. After the element is inserted, this cursor is between its start
and end. This cursor can then be used to insert additional XML into
the new element.
Parameters
-
name
- The qualified name for the new element.
beginElement(String) Method
public void beginElement(String
localName)
Inserts a new element around this cursor, giving the element the specified
local name. After the element is inserted, this cursor is between its start
and end. This cursor can then be used to insert additional XML into
the new element.
Parameters
-
localName
- The local name for the new element.
beginElement(String, String) Method
public void beginElement(String
localName,
String
uri)
Inserts a new element around this cursor, giving the element the specified
local name and associating it with the specified namespace. After the element
is inserted, this cursor is between its start and end. This cursor
can then be used to insert additional XML into the new element.
Parameters
-
localName
- The local name for the new element.
-
uri
- The URI for the new element's namespace.
clearBookmark(Object) Method
public void clearBookmark(Object
key)
Clears the bookmark whose key is specified, if the bookmark
exists at this cursor's location.
Parameters
-
key
- The for the bookmark to clear.
clearSelections() Method
public void clearSelections()
Clears this cursor's selection, but does not modify the document.
comparePosition(XmlCursor) Method
public int comparePosition(XmlCursor
cursor)
Returns an integer indicating whether this cursor is before,
after, or at the same position as the specified cursor.
a.comparePosition(b) < 0
means a is to the left of b.
a.comparePosition(b) == 0
means a is at the same position as b.
a.comparePosition(b) > 0
means a is to the right of b.
The sort order of cursors in the document is the token order.
For example, if cursor "a" is at a START token and the cursor "b"
is at a token within the contents of the same element, then
a.comparePosition(b) will return -1, meaning that the position
of a is before b.
Parameters
-
cursor
- The cursor whose position should be compared
with this cursor.
Returns
- 1 if this cursor is after the specified cursor; 0 if
this cursor is at the same position as the specified cursor;
-1 if this cursor is before the specified cursor.
copyChars(int, XmlCursor) Method
public int copyChars(int maxCharacterCount,
XmlCursor
toHere)
Copies characters to the position immediately after the specified cursor.
Characters are counted to the right up to the specified maximum number.
XML after the destination cursor is shifted to the right to make room.
Parameters
-
maxCharacterCount
- The maximum number of characters after this cursor's
location to copy.
-
toHere
- The cursor to which the characters should be copied.
Returns
- The actual number of characters copied.
copyXml(XmlCursor) Method
public boolean copyXml(XmlCursor
toHere)
Copies the XML immediately after this cursor to the location
specified by the toHere cursor. For the TEXT, ATTR, NAMESPACE,
COMMENT and PROCINST tokens, a single token is copied. For a start token,
the element and all of its contents are copied. For all other tokens, this
is a no-op.
The cursors and bookmarks located in the XML that was copied are also copied
to the new location.
Parameters
-
toHere
- The cursor at the location to which the XML should
be copied.
Returns
- true if anything was copied; false if the token supports the operation,
but nothing was copied.
copyXmlContents(XmlCursor) Method
public boolean copyXmlContents(XmlCursor
toHere)
Copies the contents of the container (STARTDOC OR START) immediately to
the right of the cursor to the location specified by the toHere cursor.
For all other situations, returns false. Does not copy attributes or
namespaces.
Parameters
-
toHere
- The cursor at the location to which the XML should
be copied.
Returns
- true if anything was copied; otherwise, false.
currentTokenType() Method
public XmlCursor.TokenType
currentTokenType()
Returns the type of the current token. By definition, the current
token is the token immediately to the right of the cursor.
If you're in the middle of text, before a character, you get TEXT.
You can't dive into the text of an ATTR, COMMENT or PROCINST.
As an alternative, it may be more convenient for you to use one of the
methods that test for a particular token type. These include the methods
isStart(), isStartdoc(), isText(), isAttr(), and so on. Each returns a boolean
value indicating whether the token that follows the cursor is the type
in question.
Returns
- The TokenType instance for the token at the cursor's current
location.
dispose() Method
public void dispose()
Deallocates resources needed to manage the cursor, rendering this cursor
inoperable. Because cursors are managed by a mechanism which stores the
XML, simply letting a cursor go out of scope and having the garbage collector
attempt to reclaim it may not produce desirable performance.
So, explicitly disposing a cursor allows the underlying implementation
to release its responsibility of maintaining its position.
After a cursor has been disposed, it may not be used again. It can
throw IllegalStateException or NullPointerException if used after
disposal.
execQuery(String) Method
public XmlCursor
execQuery(String
query)
Executes the specified XQuery expression against the XML this
cursor is in.
The query may be a String or a compiled query. You can precompile
an XQuery expression using the XmlBeans.compileQuery method.
The root referred to by the expression should be given as
a dot. The following is an example path expression:
XmlCursor results = cursor.execQuery("purchase-order/line-item[price <= 20.00]");
Parameters
-
query
- The XQuery expression to execute.
Returns
- A cursor containing the results of the query.
execQuery(String, XmlOptions) Method
public XmlCursor
execQuery(String
query,
XmlOptions
options)
Executes the specified XQuery expression against the XML this
cursor is in, and using the specified options.
Parameters
-
query
- The XQuery expression to execute.
-
options
- Options for the query. For example, you can call
the
XmlOptions.setXqueryCurrentNodeVar(String)
method to specify a particular name for the query expression
variable that indicates the context node.
getAllBookmarkRefs(Collection) Method
public void getAllBookmarkRefs(Collection
listToFill)
Retrieves all the bookmarks at this location, adding them to
the specified collection. Bookmarks held by weak references are
added to this collection as Weak referenced objects pointing to the
bookmark.
Parameters
-
listToFill
- The collection that will contain bookmarks
returned by this method.
getAllNamespaces(Map) Method
public void getAllNamespaces(Map
addToThis)
Adds to the specified map, all the namespaces in scope at the container
where this cursor is positioned. This method is useful for
container tokens only.
Parameters
-
addToThis
- The Map to add the namespaces to.
getAttributeText(QName) Method
public String
getAttributeText(QName
attrName)
When at a START or STARTDOC, returns the attribute text for the given
attribute. When not at a START or STARTDOC or the attribute does not
exist, returns null.
Parameters
-
attrName
- The name of the attribute whose value is requested.
Returns
- The attribute's value if it has one; otherwise, null.
getBookmark(Object) Method
public XmlCursor.XmlBookmark
getBookmark(Object
key)
Retrieves the bookmark with the specified key
at this cursor's location. If there is no bookmark whose key is
given by the specified key at the current position, null is returned.
If the getKey
method is not overridden on
the bookmark, then the bookmark's class is used as the key.
Parameters
-
key
- The key for the bookmark to retrieve.
Returns
- The requested bookmark; null if there is no bookmark
corresponding to the specified key.
getChars() Method
public String
getChars()
Returns characters to the right of the cursor up to the next token.
getChars(char[], int, int) Method
public int getChars(char[] returnedChars,
int offset,
int maxCharacterCount)
Copies characters up to the specified maximum number, counting right from
this cursor's location to the character at maxCharacterCount. The
returned characters are added to returnedChars, with the first
character copied to the offset position. The maxCharacterCount
parameter should be less than or equal to the length of returnedChars
minus offset. Copies a number of characters, which is
either maxCharacterCount or the number of characters up to the next token,
whichever is less.
Parameters
-
returnedChars
- A character array to hold the returned characters.
-
offset
- The position within returnedChars at which the first of the
returned characters should be added.
-
maxCharacterCount
- The maximum number of characters after this cursor's
location to return.
Returns
- The actual number of characters returned; 0 if no characters
were returned or if the current token is not TEXT.
getDocChangeStamp() Method
public XmlCursor.ChangeStamp
getDocChangeStamp()
Returns the current change stamp for the document the current cursor is in.
This change stamp can be queried at a later point in time to find out
if the document has changed.
Returns
- The change stamp for the document the current cursor is in.
getName() Method
public QName
getName()
Returns the name of the current token. Names may be associated with
START, ATTR, NAMESPACE or PROCINST. Returns null if there is no
name associated with the current token. For START and ATTR, the
name returned identifies the name of the element or attribute.
For NAMESPACE, the local part of the name is the prefix, while
the URI is the namespace defined. For PROCINST, the local part
is the target and the uri is "".
Returns
- The name of the XML at this cursor's location; null if there
is no name.
getObject() Method
public XmlObject
getObject()
Returns the strongly-typed XmlObject at the current START,
STARTDOC, or ATTR.
The strongly-typed object can be cast to the strongly-typed
XBean interface corresponding to the XML Schema Type given
by result.getSchemaType().
If a more specific type cannot be determined, an XmlObject
whose schema type is anyType will be returned.
Returns
- The strongly-typed object at the cursor's current location;
null if the current location is not a START, STARTDOC, or ATTR.
getSelectionCount() Method
public int getSelectionCount()
Returns the count of the current selection. See also the selectPath()
and addToSelection() methods.
You may experience better performance if you use the iteration
model using the toNextSelection method, rather than
the indexing model using the getSelectionCount and
toSelection methods.
Returns
- A number indicating the size of the current selection.
getTextValue() Method
public String
getTextValue()
Gets the text value of the current document, element, attribute,
comment, procinst or text token.
When getting the text value of an element, non-text content such
as comments and processing instructions are ignored and text is concatenated.
For elements that have nested element children, this
returns the concatenated text of all mixed content and the
text of all the element children, recursing in first-to-last
depthfirst order.
For attributes, this returns the attribute value.
For comments and processing instructions, this returns the text contents
of the comment or PI, not including the delimiting sequences <!-- -->, <? ?>.
If the current token is not a START, STARTDOC, TEXT, ATTR, COMMENT, or
PROCINST, this returns null. The value of an empty tag is the
empty string.
Returns
- The text value of the current token, if the token's type is
START, STARTDOC, TEXT, ATTR, COMMENT, or PROCINST; null if the type is
END, ENDDOC, NONE, or NAMESPACE.
getTextValue(char[], int, int) Method
public int getTextValue(char[] returnedChars,
int offset,
int maxCharacterCount)
Copies the text value of the current document, element, attribute,
comment, processing instruction or text token, counting right from
this cursor's location up to maxCharacterCount,
and copies the returned text into returnedChars.
When getting the text value of an element, non-text content such
as comments and processing instructions are ignored and text is concatenated.
For elements that have nested element children, this
returns the concatenated text of all mixed content and the
text of all the element children, recursing in first-to-last
depthfirst order.
For attributes, this returns the attribute value.
For comments and processing instructions, this returns the text contents
of the comment or PI, not including the delimiting sequences <!-- -->, <? ?>.
If the current token is END, ENDDOC, or NAMESPACE, this returns 0.
The value of an empty tag is the empty string.
Parameters
-
returnedChars
- A character array to hold the returned characters.
-
offset
- The position within returnedChars to which the first of the
returned characters should be copied.
-
maxCharacterCount
- The maximum number of characters after this cursor's
location to copy.
Returns
- The actual number of characters copied; 0 if no characters
were copied.
hasNextSelection() Method
public boolean hasNextSelection()
Returns whether or not there is a next selection.
Returns
- true if there is a next selection; otherwise, false.
hasNextToken() Method
public boolean hasNextToken()
True if there is a next token. When this is false, as when the cursor is
at the ENDDOC token, the toNextToken() method returns NONE and does not
move the cursor.
Returns
- true if there is a next token; otherwise, false.
hasPrevToken() Method
public boolean hasPrevToken()
True if there is a previous token. When this is false, toPrevToken
returns NONE and does not move the cursor.
Returns
- true if there is a previous token; otherwise, false.
insertAttribute(String) Method
public void insertAttribute(String
localName)
Inserts a new attribute immediately before this cursor's location, giving it
the specified local name.
Parameters
-
localName
- The local name for the new attribute.
insertAttribute(String, String) Method
public void insertAttribute(String
localName,
String
uri)
Inserts a new attribute immediately before this cursor's location, giving it
the specified local name and associating it with the specified namespace.
Parameters
-
localName
- The local name for the new attribute.
-
uri
- The URI for the new attribute's namespace.
insertAttribute(QName) Method
public void insertAttribute(QName
name)
Inserts a new attribute immediately before this cursor's location, giving it
the specified name.
Parameters
-
name
- The local name for the new attribute.
insertAttributeWithValue(String, String) Method
public void insertAttributeWithValue(String
Name,
String
value)
Inserts a new attribute immediately before this cursor's location, giving it
the specified value and name.
Parameters
-
Name
- The local name for the new attribute.
-
value
- The value for the new attribute.
insertAttributeWithValue(String, String, String) Method
public void insertAttributeWithValue(String
name,
String
uri,
String
value)
Inserts an attribute immediately before the cursor's location, giving it
the specified name and value, and associating it with the specified namespace.
Parameters
-
name
- The name for the new attribute.
-
uri
- The URI for the new attribute's namespace.
-
value
- The value for the new attribute.
insertAttributeWithValue(QName, String) Method
public void insertAttributeWithValue(QName
name,
String
value)
Inserts an attribute immediately before the cursor's location, giving it
the specified name and value.
Parameters
-
name
- The name for the new attribute.
-
value
- The value for the new attribute.
insertChars(String) Method
public void insertChars(String
text)
Inserts the specified text immediately before this cursor's location.
Parameters
-
text
- The text to insert.
insertComment(String) Method
public void insertComment(String
text)
Inserts an XML comment immediately before the cursor's location,
giving it the specified content.
Parameters
-
text
- The new comment's content.
insertElement(QName) Method
public void insertElement(QName
name)
Inserts an element immediately before this cursor's location, giving
the element the specified qualified name.
Parameters
-
name
- The qualified name for the element.
insertElement(String) Method
public void insertElement(String
localName)
Inserts an element immediately before this cursor's location, giving
the element the specified local name.
Parameters
-
localName
- The local name for the new element.
insertElement(String, String) Method
public void insertElement(String
localName,
String
uri)
Inserts a new element immediately before this cursor's location, giving the
element the specified local name and associating it with specified namespace
Parameters
-
localName
- The local name for the new element.
-
uri
- The URI for the new element's namespace.
insertElementWithText(QName, String) Method
public void insertElementWithText(QName
name,
String
text)
Inserts a new element immediately before this cursor's location, giving the
element the specified qualified name and content.
Parameters
-
name
- The qualified name for the new element.
-
text
- The content for the new element.
insertElementWithText(String, String) Method
public void insertElementWithText(String
localName,
String
text)
Inserts a new element immediately before this cursor's location, giving the
element the specified local name and content.
Parameters
-
localName
- The local name for the new element.
-
text
- The content for the new element.
insertElementWithText(String, String, String) Method
public void insertElementWithText(String
localName,
String
uri,
String
text)
Inserts a new element immediately before this cursor's location, giving the
element the specified local name, associating it with the specified namespace,
and giving it the specified content.
Parameters
-
localName
- The local name for the new element.
-
uri
- The URI for the new element's namespace.
-
text
- The content for the new element.
insertNamespace(String, String) Method
public void insertNamespace(String
prefix,
String
namespace)
Inserts a namespace declaration immediately before the cursor's location,
giving it the specified prefix and URI.
Parameters
-
prefix
- The prefix for the namespace.
-
namespace
- The URI for the namespace.
insertProcInst(String, String) Method
public void insertProcInst(String
target,
String
text)
Inserts an XML processing instruction immediately before the cursor's location,
giving it the specified target and text.
Parameters
-
target
- The target for the processing instruction.
-
text
- The new processing instruction's text.
isAnyAttr() Method
public boolean isAnyAttr()
True if this token is any attribute. This includes an ATTR token type and
the NAMESPACE token type attribute.
Returns
- true if the current cursor is at any attribute; otherwise, false.
isAtSamePositionAs(XmlCursor) Method
public boolean isAtSamePositionAs(XmlCursor
cursor)
Determines if this cursor is at the same position as
the specified cursor. Note that this is the same as
a.comparePosition(b) == 0
Parameters
-
cursor
- The cursor whose position should be compared
with this cursor.
Returns
- true if this cursor is at the same position as
the specified cursor; otherwise, false.
isAttr() Method
public boolean isAttr()
True if this token is an ATTR token type, meaning
just before an attribute.
Returns
- true if this token is an ATTR token type;
otherwise, false.
isComment() Method
public boolean isComment()
True if this token is a COMMENT token type, meaning
just before a comment.
Returns
- true if this token is a COMMENT token type;
otherwise, false.
isContainer() Method
public boolean isContainer()
True if this token is a container token. The STARTDOC and START
token types are containers. Containers, including documents and elements,
have the same content model. In other words, a document and an element
may have the same contents. For example, a document may contain attributes
or text, without any child elements.
Returns
- true if this token is a container token; otherwise, false.
isEnd() Method
public boolean isEnd()
True if this token is an END token type, meaning
just before an element's end.
Returns
- true if this token is an END token type;
otherwise, false.
isEnddoc() Method
public boolean isEnddoc()
True if this token is an ENDDOC token type, meaning
at the very end of the document.
Returns
- true if this token is an ENDDOC token type;
otherwise, false.
isFinish() Method
public boolean isFinish()
True if this token is a finish token. A finish token can be an ENDDOC
or END token type.
Returns
- true if this token is a finish token; otherwise, false.
isInSameDocument(XmlCursor) Method
public boolean isInSameDocument(XmlCursor
cursor)
Determines if the specified cursor is in the same document as
this cursor.
Parameters
-
cursor
- The cursor that may be in the same document
as this cursor.
Returns
- true if the specified cursor is in the same document;
otherwise, false.
isLeftOf(XmlCursor) Method
public boolean isLeftOf(XmlCursor
cursor)
Determines if this cursor is to the left of (or before)
the specified cursor. Note that this is the same as
a.comparePosition(b) < 0
Parameters
-
cursor
- The cursor whose position should be compared
with this cursor.
Returns
- true if this cursor is to the left of the specified
cursor; otherwise, false.
isNamespace() Method
public boolean isNamespace()
True if this token is a NAMESPACE token type, meaning
just before a namespace declaration.
Returns
- true if this token is a NAMESPACE token type;
otherwise, false.
isProcinst() Method
public boolean isProcinst()
True if this token is a PROCINST token type, meaning
just before a processing instruction.
Returns
- true if this token is a PROCINST token type;
otherwise, false.
isRightOf(XmlCursor) Method
public boolean isRightOf(XmlCursor
cursor)
Determines if this cursor is to the right of (or after)
the specified cursor. Note that this is the same as
a.comparePosition(b) > 0
Parameters
-
cursor
- The cursor whose position should be compared
with this cursor.
Returns
- true if this cursor is to the right of the specified
cursor; otherwise, false.
isStart() Method
public boolean isStart()
True if this token is a START token type, meaning
just before an element's start.
Returns
- true if this token is a START token type;
otherwise, false.
isStartdoc() Method
public boolean isStartdoc()
True if the current token is a STARTDOC token type, meaning
at the very root of the document.
Returns
- true if this token is a STARTDOC token type;
otherwise, false.
isText() Method
public boolean isText()
True if the this token is a TEXT token type, meaning
just before or inside text.
Returns
- true if this token is a TEXT token type;
otherwise, false.
moveChars(int, XmlCursor) Method
public int moveChars(int maxCharacterCount,
XmlCursor
toHere)
Moves characters immediately after this cursor to the position immediately
after the specified cursor. Characters are counted to the right up to the
specified maximum number. XML after the destination cursor is
shifted to the right to make room. The space remaining from moving the
characters collapses up to this cursor.
Parameters
-
maxCharacterCount
- The maximum number of characters after this cursor's
location to move.
-
toHere
- The cursor to which the characters should be moved.
Returns
- The actual number of characters moved.
moveXml(XmlCursor) Method
public boolean moveXml(XmlCursor
toHere)
Moves the XML immediately after this cursor to the location
specified by the toHere cursor, shifting XML at that location
to the right to make room. For the TEXT, ATTR, NAMESPACE,
COMMENT and PROCINST tokens, a single token is moved. For a start token, the
element and all of its contents are moved. For all other tokens, this
is a no-op.
The bookmarks located in the XML that was moved also move to the
new location; the cursors don't move with the content.
Parameters
-
toHere
- The cursor at the location to which the XML should
be moved.
Returns
- true if anything was moved; false only if the cursor is
just before END or ENDDOC token.
moveXmlContents(XmlCursor) Method
public boolean moveXmlContents(XmlCursor
toHere)
Moves the contents of the container (STARTDOC OR START) immediately after
this cursor to the location specified by the toHere cursor.
For all other situations, returns false. Does not move attributes or
namespaces.
Parameters
-
toHere
- The cursor at the location to which the XML should be moved.
Returns
- true if anything was moved; otherwise, false.
namespaceForPrefix(String) Method
public String
namespaceForPrefix(String
prefix)
Returns the namespace URI indicated by the given prefix. The current
context must be at a START or STARTDOC. Namespace prefix mappings
are queried for the mappings defined at the current container first,
then parents are queried. The prefix can be "" or null to indicate
a search for the default namespace. To conform with the
XML spec, the default namespace will return the no-namespace ("")
if it is not mapped.
Note that this queries the current state of the document. When the
document is persisted, the saving mechanism may synthesize namespaces
(ns1, ns2, and so on) for the purposes of persistence. These namepaces are
only present in the serialized form, and are not reflected back into
the document being saved.
Parameters
-
prefix
- The namespace prefix for the requested namespace.
Returns
- The URI for corresponding to the specified prefix if it
exists; otherwise, null.
pop() Method
public boolean pop()
Restores the cursor location most recently saved with the push() method.
Returns
- true if there was a location to restore; otherwise, false.
prefixForNamespace(String) Method
public String
prefixForNamespace(String
namespaceURI)
Returns a prefix that can be used to indicate a namespace URI. The
current context must be at a START or STARTDOC. If there is an
existing prefix that indicates the URI in the current context, that
prefix may be returned. Otherwise, a new prefix for the URI will be
defined by adding an xmlns attribute to the current container or a
parent container.
Note that this queries the current state of the document. When the
document is persisted, the saving mechanism may synthesize namespaces
(ns1, ns2, and so on) for the purposes of persistence. These namepaces are
only present in the serialized form, and are not reflected back into
the document being saved.
Parameters
-
namespaceURI
- The namespace URI corresponding to the requested
prefix.
Returns
- The prefix corresponding to the specified URI if it exists;
otherwise, a newly generated prefix.
prevTokenType() Method
public XmlCursor.TokenType
prevTokenType()
Returns the type of the previous token. By definition, the previous
token is the token immediately to the left of the cursor.
If you're in the middle of text, after a character, you get TEXT.
Returns
- The TokenType instance for the token immediately before the
token at the cursor's current location.
push() Method
public void push()
Saves the current location of this cursor on an internal stack of saved
positions (independent of selection). This location may be restored
later by calling the pop() method.
removeAttribute(QName) Method
public boolean removeAttribute(QName
attrName)
When at a START or STARTDOC, removes the attribute with the given name.
Parameters
-
attrName
- The name of the attribute that should be removed.
Returns
- true if the attribute was removed; otherwise, false.
removeChars(int) Method
public int removeChars(int maxCharacterCount)
Removes characters up to the specified maximum number, counting right from
this cursor's location to the character at maxCharacterCount. The
space remaining from removing the characters collapses up to this cursor.
Parameters
-
maxCharacterCount
- The maximum number of characters after this cursor's
location to remove.
Returns
- The actual number of characters removed.
removeXml() Method
public boolean removeXml()
Removes the XML that is immediately after this cursor.
For the TEXT, ATTR, NAMESPACE, COMMENT and PROCINST tokens, a single
token is removed. For a START token, the corresponding element and all
of its contents are removed. For all other tokens, this is a no-op.
You cannot remove a STARTDOC.
The cursors located in the XML that was removed all collapse to the
same location. All bookmarks in this XML will be orphaned.
Returns
- true if anything was removed; false only if the cursor is
just before END or ENDDOC token.
removeXmlContents() Method
public boolean removeXmlContents()
Removes the contents of the container (STARTDOC OR START) immediately after
this cursor. For all other situations, returns false. Does
not remove attributes or namspaces.
Returns
- true if anything was copied; otherwise, false.
selectPath(String) Method
public void selectPath(String
path)
Executes the specified XPath expression against the XML that this
cursor is in. The cursors position does not change. To navigate to the
selections, use hasNextSelection and toNextSelection (similar to
java.util.Iterator).
The root referred to by the expression should be given as
a dot. The following is an example path expression:
cursor.selectPath("./purchase-order/line-item[price <= 20.00]");
Parameters
-
path
- The path expression to execute.
selectPath(String, XmlOptions) Method
public void selectPath(String
path,
XmlOptions
options)
Executes the specified XPath expression against the XML that this
cursor is in. The cursor's position does not change. To navigate to the
selections, use hasNextSelection and toNextSelection (similar to
java.util.Iterator).
The root referred to by the expression should be given as
a dot. The following is an example path expression:
cursor.selectPath("./purchase-order/line-item[price <= 20.00]");
Parameters
-
path
- The path expression to execute.
-
options
- Options for the query. For example, you can call
the
XmlOptions.setXqueryCurrentNodeVar(String)
method to specify a particular name for the query expression
variable that indicates the context node.
setAttributeText(QName, String) Method
public boolean setAttributeText(QName
attrName,
String
value)
When at a START or STARTDOC, sets the attribute text for the given
attribute. When not at a START or STARTDOC returns false.
If the attribute does not exist, one is created.
Parameters
-
attrName
- The name of the attribute whose value is being set.
-
value
- The new value for the attribute.
Returns
- true if the new value was set; otherwise, false.
setBookmark(XmlCursor.XmlBookmark) Method
public void setBookmark(XmlCursor.XmlBookmark
bookmark)
Sets a bookmark to the document at this cursor's location.
The bookmark is attached to the token in the tree immediately
after the cursor. If the tree is manipulated to move
that object to a different place, the bookmark moves with it.
If the tree is manipulated to delete that token from the
tree, the bookmark is orphaned. Copy operations do not copy
bookmarks.
Parameters
-
bookmark
- The bookmark to set.
setName(QName) Method
public void setName(QName
name)
Sets the name of the current token. This token can be START, NAMESPACE,
ATTR or PROCINST.
Parameters
-
name
- The new name for the current token.
setTextValue(String) Method
public void setTextValue(String
text)
Sets the text value of the XML at this cursor's location if that XML's
token type is START, STARTDOC, ATTR, COMMENT or PROCINST.
For elements that have nested children this first removes all
the content of the element and replaces it with the given text.
Parameters
-
text
- The text to use as a new value.
setTextValue(char[], int, int) Method
public void setTextValue(char[] sourceChars,
int offset,
int length)
Sets the text value of the XML at this cursor's location (if that XML's
token type is START, STARTDOC, ATTR, COMMENT or PROCINST) to the
contents of the specified character array.
For elements that have nested children this first removes all
the content of the element and replaces it with the given text.
Parameters
-
sourceChars
- A character array containing the XML's new value.
-
offset
- The position within sourceChars from which the first of
the source characters should be copied.
-
length
- The maximum number of characters to set as the XML's new
value.
toBookmark(XmlCursor.XmlBookmark) Method
public boolean toBookmark(XmlCursor.XmlBookmark
bookmark)
Moves this cursor to the same position as the bookmark. If the
bookmark is in a different document from this cursor or if the
bookmark is orphaned, this cursor
will not be moved, and false will be returned.
Parameters
-
bookmark
- The bookmark at the location to which this
cursor should be moved.
Returns
- true if the cursor moved; otherwise, false.
toChild(String) Method
public boolean toChild(String
name)
Moves the cursor to the first child element of the specified name in
no namespace.
Parameters
-
name
- The name of the element to move the cursor to.
Returns
- true if the cursor was moved; otherwise, false.
toChild(String, String) Method
public boolean toChild(String
namespace,
String
name)
Moves the cursor to the first child element of the specified name in the
specified namespace.
Parameters
-
namespace
- The namespace URI for the element to move the cursor
to.
-
name
- The name of the element to move to.
Returns
- true if the cursor was moved; otherwise, false.
toChild(QName) Method
public boolean toChild(QName
name)
Moves the cursor to the first child element of the specified qualified name.
Parameters
-
name
- The name of the element to move the cursor to.
toChild(int) Method
public boolean toChild(int index)
Moves the cursor to the child element specified by index.
Parameters
-
index
- The position of the element in the sequence of child
elements.
Returns
- true if the cursor was moved; otherwise, false.
toChild(QName, int) Method
public boolean toChild(QName
name,
int index)
Moves the cursor to the specified index child element of the
specified name, where that element is the .
Parameters
-
name
- The name of the child element to move the cursor to.
-
index
- The position of the element in the sequence of child
elements.
Returns
- true if the cursor was moved; otherwise, false.
toCursor(XmlCursor) Method
public boolean toCursor(XmlCursor
moveTo)
Moves this cursor to the same position as the moveTo cursor. if the
moveTo cursor is in a different document from this cursor, this cursor
will not be moved, and false returned.
Parameters
-
moveTo
- The cursor at the location to which this cursor
should be moved.
Returns
- true if the cursor moved; otherwise, false.
toEndDoc() Method
public void toEndDoc()
Moves the cursor to the ENDDOC token, which is the end
of the document.
toEndToken() Method
public XmlCursor.TokenType
toEndToken()
Moves the cursor to the END or ENDDOC token corresponding to the
current START or STARTDOC, and returns END or ENDDOC.
If the current token is not a START or STARTDOC, the cursor is not
moved and NONE is returned.
Returns
- The new current token type.
toFirstAttribute() Method
public boolean toFirstAttribute()
Moves the cursor to the first attribute of this element, or
returns false and does not move the cursor if there are no
attributes. The order of attributes is arbitrary, but stable.
xmlns attributes (namespace declarations) are not considered
attributes by this function.
The cursor must be on a START or STARTDOC for this method to
succeed.
Returns
- true if the cursor was moved; otherwise, false.
toFirstChild() Method
public boolean toFirstChild()
Moves the cursor to the first child element, or returns false and
does not move the cursor if there are no element children.
If the cursor is not currently in an element, it moves into the
first child element of the next element.
Returns
- true if the cursor was moved; otherwise, false.
toFirstContentToken() Method
public XmlCursor.TokenType
toFirstContentToken()
Moves the cursor to the first token in the content of the current
START or STARTDOC. That is, the first token after all ATTR and NAMESPACE
tokens associated with this START.
If the current token is not a START or STARTDOC, the cursor is not
moved and NONE is returned. If the current START or STARTDOC
has no content, the cursor is moved to the END or ENDDOC token.
Returns
- The new current token type.
toLastAttribute() Method
public boolean toLastAttribute()
Moves the cursor to the last attribute of this element, or
returns false and does not move the cursor if there are no
attributes. The order of attributes is arbitrary, but stable.
xmlns attributes (namespace declarations) are not considered
attributes by this function.
The cursor must be on a START or STARTDOC for this method
to succeed.
Returns
- true if the cursor was moved; otherwise, false.
toLastChild() Method
public boolean toLastChild()
Moves the cursor to the last element child, or returns false and
does not move the cursor if there are no element children.
Returns
- true if the cursor was moved; otherwise, false.
toNextAttribute() Method
public boolean toNextAttribute()
Moves the cursor to the next sibling attribute, or returns
false and does not move the cursor if there is no next
sibling attribute. The order of attributes is arbitrary, but stable.
xmlns attributes (namespace declarations) are not considered
attributes by this function.
The cursor must be on an attribute for this method to succeed.
Returns
- true if the cursor was moved; otherwise, false.
toNextBookmark(Object) Method
public XmlCursor.XmlBookmark
toNextBookmark(Object
key)
Moves this cursor to the location after its current position
where a bookmark with the given key exists. Returns false if no
such bookmark exists.
Parameters
-
key
- The key held by the next bookmark at the location to
which this cursor should be moved.
Returns
- The next corresponding bookmark, if it exists; null if there
is no next bookmark with the specified key.
toNextChar(int) Method
public int toNextChar(int maxCharacterCount)
Moves the cursor forward by the specified number of characters, and
stops at the next non-TEXT token. Returns the number of characters
actually moved across, which is guaranteed to be less than or equal to
maxCharacterCount. If there is no further text, or if
there is no text at all, returns zero.
Note this does not dive into attribute values, comment contents,
processing instruction contents, etc., but only content text.
You can pass maxCharacterCount < 0 to move over all the text to the
right. This has the same effect as toNextToken, but returns the amount
of text moved over.
Parameters
-
maxCharacterCount
- The maximum number of characters by which
the cursor should be moved.
Returns
- The actual number of characters by which the cursor was moved;
0 if the cursor was not moved.
toNextSelection() Method
public boolean toNextSelection()
Moves this cursor to the next location in the selection,
if any. See the selectPath() and addToSelection() methods.
Returns
- true if the cursor moved; otherwise, false.
toNextSibling() Method
public boolean toNextSibling()
Moves the cursor to the next sibling element, or returns
false and does not move the cursor if there is no next sibling
element. (By definition the position of an element is the same
as the position of its START token.)
If the current token is not s START, the cursor will be
moved to the next START without moving out of the scope of the
current element.
Returns
- true if the cursor was moved; otherwise, false.
toNextSibling(String) Method
public boolean toNextSibling(String
name)
Moves the cursor to the next sibling element of the specified name in no
namespace.
Parameters
-
name
- The name of the element to move the cursor to.
Returns
- true if the cursor was moved; otherwise, false.
toNextSibling(String, String) Method
public boolean toNextSibling(String
namespace,
String
name)
Moves the cursor to the next sibling element of the specified name
in the specified namespace.
Parameters
-
namespace
- The namespace URI for the element to move the cursor
to.
-
name
- The name of the element to move the cursor to.
Returns
- true if the cursor was moved; otherwise, false.
toNextSibling(QName) Method
public boolean toNextSibling(QName
name)
Moves the cursor to the next sibling element of the specified
qualified name.
Parameters
-
name
- The name of the element to move the cursor to.
Returns
- true if the cursor was moved; otherwise, false.
toNextToken() Method
public XmlCursor.TokenType
toNextToken()
Moves the cursor to the next token. When there are no more tokens
available, hasNextToken returns false and toNextToken() returns
NONE and does not move the cursor. Returns the token type
of the token to the right of the cursor upon a successful move.
Returns
- The token type for the next token if the cursor was moved;
otherwise, NONE.
toParent() Method
public boolean toParent()
Moves the cursor to the parent element or STARTDOC, or returns
false and does not move the cursor if there is no parent.
Works if you're in attributes or content. Returns false only if at
STARTDOC. Note that the parent of an END token is the corresponding
START token.
Returns
- true if the cursor was moved; false if the cursor is at the STARTDOC
token.
toPrevAttribute() Method
public boolean toPrevAttribute()
Moves the cursor to the previous sibling attribute, or returns
false and does not move the cursor if there is no previous
sibling attribute. The order of attributes is arbitrary, but stable.
xmlns attributes (namespace declarations) are not considered
attributes by this function.
The cursor must be on an attribute for this method to succeed.
Returns
- true if the cursor was moved; otherwise, false.
toPrevBookmark(Object) Method
public XmlCursor.XmlBookmark
toPrevBookmark(Object
key)
Moves this cursor to the location before its current position
where a bookmark with the given key exists. Returns false if no
such bookmark exists.
Parameters
-
key
- The key held by the previous bookmark at the location to
which this cursor should be moved.
Returns
- The previous corresponding bookmark, if it exists; null if
there is no previous bookmark with the specified key.
toPrevChar(int) Method
public int toPrevChar(int maxCharacterCount)
Moves the cursor backwards by the number of characters given. Has
similar characteristics to the toNextChar
method.
Parameters
-
maxCharacterCount
- The maximum number of characters by which
the cursor should be moved.
Returns
- The actual number of characters by which the cursor was moved;
0 if the cursor was not moved.
toPrevSibling() Method
public boolean toPrevSibling()
Moves the cursor to the previous sibling element, or returns
false and does not move the cursor if there is no previous sibling
element. (By definition the position of an element is the same
as the position of its START token.)
Returns
- true if the cursor was moved; otherwise, false.
toPrevToken() Method
public XmlCursor.TokenType
toPrevToken()
Moves the cursor to the previous token. When there is no
previous token, returns NONE, otherwise returns the token
to the left of the new position of the cursor.
Returns
- The token type for the previous token if the cursor was moved;
otherwise, NONE.
toSelection(int) Method
public boolean toSelection(int i)
Moves this cursor to the specified location in the selection.
If i is less than zero or greater than or equal to the selection
count, this method returns false.
See also the selectPath() and addToSelection() methods.
Parameters
-
i
- The index of the desired location.
Returns
- true if the cursor was moved; otherwise, false.
toStartDoc() Method
public void toStartDoc()
Moves the cursor to the STARTDOC token, which is the
root of the document.