All Superinterfaces:: XmlTokenSource

All Known Implementing Classes:: Cursor

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

Nested Class Summary

Nested Classes
Modifier and Type	Interface	Description
`static interface`	`XmlCursor.ChangeStamp`	Represents the state of a dcoument at a particular point in time.
`static class`	`XmlCursor.TokenType`	An enumeration that identifies the type of an XML token.
`static class`	`XmlCursor.XmlBookmark`	Subclasses of XmlBookmark can be used to annotate an XML document.
`static interface`	`XmlCursor.XmlMark`	An abstract `XmlCursor` factory.

Method Summary

Modifier and Type	Method	Description
`void`	`addToSelection()`	Appends the current location of the cursor to the selection.
`void`	`beginElement(String localName)`	Inserts a new element around this cursor, giving the element the specified local name.
`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.
`void`	`beginElement(QName name)`	Inserts a new element around this cursor, giving the element the specified qualified name.
`void`	`clearBookmark(Object key)`	Clears the bookmark whose key is specified, if the bookmark exists at this cursor's location.
`void`	`clearSelections()`	Clears this cursor's selection, but does not modify the document.
`int`	`comparePosition(XmlCursor cursor)`	Returns an integer indicating whether this cursor is before, after, or at the same position as the specified cursor.
`int`	`copyChars(int maxCharacterCount, XmlCursor toHere)`	Copies characters to the position immediately after the specified cursor.
`boolean`	`copyXml(XmlCursor toHere)`	Copies the XML immediately after this cursor to the location specified by the toHere cursor.
`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.
`XmlCursor.TokenType`	`currentTokenType()`	Returns the type of the current token.
`void`	`dispose()`	Deallocates resources needed to manage the cursor, rendering this cursor inoperable.
`XmlCursor`	`execQuery(String query)`	Executes the specified XQuery expression against the XML this cursor is in.
`XmlCursor`	`execQuery(String query, XmlOptions options)`	Executes the specified XQuery expression against the XML this cursor is in, and using the specified options.
`void`	`getAllBookmarkRefs(Collection listToFill)`	Retrieves all the bookmarks at this location, adding them to the specified collection.
`void`	`getAllNamespaces(Map<String,String> addToThis)`	Adds to the specified map, all the namespaces in scope at the container where this cursor is positioned.
`String`	`getAttributeText(QName attrName)`	When at a START or STARTDOC, returns the attribute text for the given attribute.
`XmlCursor.XmlBookmark`	`getBookmark(Object key)`	Retrieves the bookmark with the specified key at this cursor's location.
`String`	`getChars()`	Returns characters to the right of the cursor up to the next token.
`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.
`XmlCursor.ChangeStamp`	`getDocChangeStamp()`	Returns the current change stamp for the document the current cursor is in.
`QName`	`getName()`	Returns the name of the current token.
`XmlObject`	`getObject()`	Returns the strongly-typed XmlObject at the current START, STARTDOC, or ATTR.
`int`	`getSelectionCount()`	Returns the count of the current selection.
`String`	`getTextValue()`	Gets the text value of the current document, element, attribute, comment, procinst or text token.
`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.
`boolean`	`hasNextSelection()`	Returns whether or not there is a next selection.
`boolean`	`hasNextToken()`	True if there is a next token.
`boolean`	`hasPrevToken()`	True if there is a previous token.
`void`	`insertAttribute(String localName)`	Inserts a new attribute immediately before this cursor's location, giving it the specified local name.
`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.
`void`	`insertAttribute(QName name)`	Inserts a new attribute immediately before this cursor's location, giving it the specified name.
`void`	`insertAttributeWithValue(String Name, String value)`	Inserts a new attribute immediately before this cursor's location, giving it the specified value and name.
`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.
`void`	`insertAttributeWithValue(QName name, String value)`	Inserts an attribute immediately before the cursor's location, giving it the specified name and value.
`void`	`insertChars(String text)`	Inserts the specified text immediately before this cursor's location.
`void`	`insertComment(String text)`	Inserts an XML comment immediately before the cursor's location, giving it the specified content.
`void`	`insertElement(String localName)`	Inserts an element immediately before this cursor's location, giving the element the specified local name.
`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
`void`	`insertElement(QName name)`	Inserts an element immediately before this cursor's location, giving the element the specified qualified name.
`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.
`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.
`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.
`void`	`insertNamespace(String prefix, String namespace)`	Inserts a namespace declaration immediately before the cursor's location, giving it the specified prefix and URI.
`void`	`insertProcInst(String target, String text)`	Inserts an XML processing instruction immediately before the cursor's location, giving it the specified target and text.
`boolean`	`isAnyAttr()`	True if this token is any attribute.
`boolean`	`isAtSamePositionAs(XmlCursor cursor)`	Determines if this cursor is at the same position as the specified cursor.
`boolean`	`isAttr()`	True if this token is an ATTR token type, meaning just before an attribute.
`boolean`	`isComment()`	True if this token is a COMMENT token type, meaning just before a comment.
`boolean`	`isContainer()`	True if this token is a container token.
`boolean`	`isEnd()`	True if this token is an END token type, meaning just before an element's end.
`boolean`	`isEnddoc()`	True if this token is an ENDDOC token type, meaning at the very end of the document.
`boolean`	`isFinish()`	True if this token is a finish token.
`boolean`	`isInSameDocument(XmlCursor cursor)`	Determines if the specified cursor is in the same document as this cursor.
`boolean`	`isLeftOf(XmlCursor cursor)`	Determines if this cursor is to the left of (or before) the specified cursor.
`boolean`	`isNamespace()`	True if this token is a NAMESPACE token type, meaning just before a namespace declaration.
`boolean`	`isProcinst()`	True if this token is a PROCINST token type, meaning just before a processing instruction.
`boolean`	`isRightOf(XmlCursor cursor)`	Determines if this cursor is to the right of (or after) the specified cursor.
`boolean`	`isStart()`	True if this token is a START token type, meaning just before an element's start.
`boolean`	`isStartdoc()`	True if the current token is a STARTDOC token type, meaning at the very root of the document.
`boolean`	`isText()`	True if the this token is a TEXT token type, meaning just before or inside text.
`int`	`moveChars(int maxCharacterCount, XmlCursor toHere)`	Moves characters immediately after this cursor to the position immediately after the specified cursor.
`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.
`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.
`String`	`namespaceForPrefix(String prefix)`	Returns the namespace URI indicated by the given prefix.
`boolean`	`pop()`	Restores the cursor location most recently saved with the push() method.
`String`	`prefixForNamespace(String namespaceURI)`	Returns a prefix that can be used to indicate a namespace URI.
`XmlCursor.TokenType`	`prevTokenType()`	Returns the type of the previous token.
`void`	`push()`	Saves the current location of this cursor on an internal stack of saved positions (independent of selection).
`boolean`	`removeAttribute(QName attrName)`	When at a START or STARTDOC, removes the attribute with the given name.
`int`	`removeChars(int maxCharacterCount)`	Removes characters up to the specified maximum number, counting right from this cursor's location to the character at maxCharacterCount.
`boolean`	`removeXml()`	Removes the XML that is immediately after this cursor.
`boolean`	`removeXmlContents()`	Removes the contents of the container (STARTDOC OR START) immediately after this cursor.
`void`	`selectPath(String path)`	Executes the specified XPath expression against the XML that this cursor is in.
`void`	`selectPath(String path, XmlOptions options)`	Executes the specified XPath expression against the XML that this cursor is in.
`boolean`	`setAttributeText(QName attrName, String value)`	When at a START or STARTDOC, sets the attribute text for the given attribute.
`void`	`setBookmark(XmlCursor.XmlBookmark bookmark)`	Sets a bookmark to the document at this cursor's location.
`void`	`setName(QName name)`	Sets the name of the current token.
`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.
`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.
`boolean`	`toBookmark(XmlCursor.XmlBookmark bookmark)`	Moves this cursor to the same position as the bookmark.
`boolean`	`toChild(int index)`	Moves the cursor to the child element specified by index.
`boolean`	`toChild(String name)`	Moves the cursor to the first child element of the specified name in no namespace.
`boolean`	`toChild(String namespace, String name)`	Moves the cursor to the first child element of the specified name in the specified namespace.
`boolean`	`toChild(QName name)`	Moves the cursor to the first child element of the specified qualified name.
`boolean`	`toChild(QName name, int index)`	Moves the cursor to the specified index child element of the specified name, where that element is the .
`boolean`	`toCursor(XmlCursor moveTo)`	Moves this cursor to the same position as the moveTo cursor.
`void`	`toEndDoc()`	Moves the cursor to the ENDDOC token, which is the end of the document.
`XmlCursor.TokenType`	`toEndToken()`	Moves the cursor to the END or ENDDOC token corresponding to the current START or STARTDOC, and returns END or ENDDOC.
`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.
`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.
`XmlCursor.TokenType`	`toFirstContentToken()`	Moves the cursor to the first token in the content of the current START or STARTDOC.
`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.
`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.
`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.
`XmlCursor.XmlBookmark`	`toNextBookmark(Object key)`	Moves this cursor to the location after its current position where a bookmark with the given key exists.
`int`	`toNextChar(int maxCharacterCount)`	Moves the cursor forward by the specified number of characters, and stops at the next non-TEXT token.
`boolean`	`toNextSelection()`	Moves this cursor to the next location in the selection, if any.
`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.
`boolean`	`toNextSibling(String name)`	Moves the cursor to the next sibling element of the specified name in no namespace.
`boolean`	`toNextSibling(String namespace, String name)`	Moves the cursor to the next sibling element of the specified name in the specified namespace.
`boolean`	`toNextSibling(QName name)`	Moves the cursor to the next sibling element of the specified qualified name.
`XmlCursor.TokenType`	`toNextToken()`	Moves the cursor to the next token.
`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.
`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.
`XmlCursor.XmlBookmark`	`toPrevBookmark(Object key)`	Moves this cursor to the location before its current position where a bookmark with the given key exists.
`int`	`toPrevChar(int maxCharacterCount)`	Moves the cursor backwards by the number of characters given.
`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.
`XmlCursor.TokenType`	`toPrevToken()`	Moves the cursor to the previous token.
`boolean`	`toSelection(int i)`	Moves this cursor to the specified location in the selection.
`void`	`toStartDoc()`	Moves the cursor to the STARTDOC token, which is the root of the document.

Methods inherited from interface org.apache.xmlbeans.XmlTokenSource

documentProperties, dump, getDomNode, monitor, newCursor, newDomNode, newDomNode, newInputStream, newInputStream, newReader, newReader, newXMLStreamReader, newXMLStreamReader, save, save, save, save, save, save, save, save, xmlText, xmlText

Method Details
- dispose
  
  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.
- toCursor
  
  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.
- push
  
  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.
- pop
  
  boolean pop()
  
  Restores the cursor location most recently saved with the push() method.
  
  Returns:
  
  true if there was a location to restore; otherwise, false.
- selectPath
  
  void selectPath(String path)
  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 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");
  
  Note that this method does not support top-level XPath functions.
  Parameters:
  
  path - The path expression to execute.
  
  Throws:
  
  XmlRuntimeException - If the query expression is invalid.
- selectPath
  
  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");
  
  Note that this method does not support top-level XPath functions.
  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.
  
  Throws:
  
  XmlRuntimeException - If the query expression is invalid.
- hasNextSelection
  
  boolean hasNextSelection()
  
  Returns whether or not there is a next selection.
  
  Returns:
  
  true if there is a next selection; otherwise, false.
- toNextSelection
  
  boolean toNextSelection()
  
  Moves this cursor to the next location in the selection, if any. See the selectPath(java.lang.String) and addToSelection() methods.
  
  Returns:
  
  true if the cursor moved; otherwise, false.
- toSelection
  
  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.
- getSelectionCount
  
  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.
- addToSelection
  
  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.
- clearSelections
  
  void clearSelections()
  
  Clears this cursor's selection, but does not modify the document.
- toBookmark
  
  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.
- toNextBookmark
  
  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.
- toPrevBookmark
  
  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.
- getName
  
  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 "".
  In the following example, xmlObject represents an XML instance whose root element is not preceded by any other XML. This code prints the root element name (here, the local name, or name without URI).
  XmlCursor cursor = xmlObject.newCursor(); cursor.toFirstContentToken(); String elementName = cursor.getName().getLocalPart(); System.out.println(elementName);
  Returns:
  
  The name of the XML at this cursor's location; null if there is no name.
- setName
  
  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.
- namespaceForPrefix
  
  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.
- prefixForNamespace
  
  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.
- getAllNamespaces
  
  void getAllNamespaces(Map<String,String> 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.
- getObject
  
  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.
- currentTokenType
  
  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.
- isStartdoc
  
  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.
- isEnddoc
  
  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.
- isStart
  
  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.
- isEnd
  
  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.
- isText
  
  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.
- isAttr
  
  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.
- isNamespace
  
  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.
- isComment
  
  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.
- isProcinst
  
  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.
- isContainer
  
  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.
- isFinish
  
  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.
- isAnyAttr
  
  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.
- prevTokenType
  
  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.
- hasNextToken
  
  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
  
  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.
- toNextToken
  
  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.
- toPrevToken
  
  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.
- toFirstContentToken
  
  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.
- toEndToken
  
  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.
- toNextChar
  
  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.
- toPrevChar
  
  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.
- toNextSibling
  
  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.
- toPrevSibling
  
  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.
- toParent
  
  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.
- toFirstChild
  
  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.
- toLastChild
  
  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.
- toChild
  
  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
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the name is not a valid local name.
- toChild
  
  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
  
  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
  
  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.
- toNextSibling
  
  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
  
  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
  
  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.
- toFirstAttribute
  
  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.
  
  If the cursor is on a STARTDOC of a document-fragment, this method will move it to the first top level attribute if one exists.
  
  xmlns attributes (namespace declarations) are not considered attributes by this function.
  
  The cursor must be on a START or STARTDOC (in the case of a document fragment with top level attributes) for this method to succeed.
  Example for looping through attributes:
  XmlCursor cursor = ... //cursor on START or STARTDOC if (cursor.toFirstAttribute()) { do { // do something using attribute's name and value cursor.getName(); cursor.getTextValue(); } while (cursor.toNextAttribute()); }
  Returns:
  
  true if the cursor was moved; otherwise, false.
- toLastAttribute
  
  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.
- toNextAttribute
  
  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.
  
  See Also:
  
  toFirstAttribute()
- toPrevAttribute
  
  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.
- getAttributeText
  
  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.
- setAttributeText
  
  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.
- removeAttribute
  
  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.
- getTextValue
  
  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, including namespaces, this returns the attribute value.
  
  For comments and processing instructions, this returns the text content of the comment or PI, not including the delimiting sequences , <? ?>. For a PI, the name of the PI is also not included.
  
  The value of an empty tag is the empty string.
  
  If the current token is END or ENDDOC, this throws an IllegalStateException.
  
  Returns:
  
  The text value of the current token if the token's type is START, STARTDOC, TEXT, ATTR, COMMENT, PROCINST, or NAMESPACE; null if the type is NONE.
- getTextValue
  
  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, including namespaces, 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 , <? ?>. For a PI, the text will not include the name of the PI.
  
  If the current token is END or ENDDOC, this throws an IllegalStateException.
  
  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. A negative value specifies that all characters should be copied.
  
  Returns:
  
  The actual number of characters copied; 0 if no characters were copied.
- setTextValue
  
  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.
  
  Throws:
  
  IllegalStateException - If the token type at this cursor's location is not START, STARTDOC, ATTR, COMMENT or PROCINST.
- setTextValue
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the token type at this cursor's location is not START, STARTDOC, ATTR, COMMENT or PROCINST.
- getChars
  
  String getChars()
  
  Returns characters to the right of the cursor up to the next token.
- getChars
  
  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.
- toStartDoc
  
  void toStartDoc()
  
  Moves the cursor to the STARTDOC token, which is the root of the document.
- toEndDoc
  
  void toEndDoc()
  
  Moves the cursor to the ENDDOC token, which is the end of the document.
- isInSameDocument
  
  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.
- comparePosition
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the specified cursor is not in the same document as this cursor.
- isLeftOf
  
  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.
- isAtSamePositionAs
  
  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.
- isRightOf
  
  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.
- execQuery
  
  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.
  
  Throws:
  
  XmlRuntimeException - If the query expression is invalid.
- execQuery
  
  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.
  
  Throws:
  
  XmlRuntimeException - If the query expression is invalid.
- getDocChangeStamp
  
  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.
- setBookmark
  
  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.
- getBookmark
  
  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.
- clearBookmark
  
  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.
- getAllBookmarkRefs
  
  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.
- removeXml
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the cursor is at a STARTDOC token.
- moveXml
  
  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. This only happens when the XML to be moved contains the target of the move.
  
  Throws:
  
  IllegalArgumentException - If the operation is not allowed at the cursor's location. This includes attempting to move an end token or the document as a whole. Also, moving to a location before the start document or moving an attribute to a location other than after another attribute or start token will throw.
- copyXml
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the operation is not allowed at the cursor's location.
- removeXmlContents
  
  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.
- moveXmlContents
  
  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.
- copyXmlContents
  
  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.
- removeChars
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the operation is not allowed at the cursor's location.
- moveChars
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the operation is not allowed at the cursor's location.
- copyChars
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the operation is not allowed at the cursor's location.
- insertChars
  
  void insertChars(String text)
  
  Inserts the specified text immediately before this cursor's location.
  
  Parameters:
  
  text - The text to insert.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- insertElement
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- insertElement
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- insertElement
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- beginElement
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- beginElement
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- beginElement
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- insertElementWithText
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- insertElementWithText
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- insertElementWithText
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- insertAttribute
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- insertAttribute
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- insertAttribute
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- insertAttributeWithValue
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- insertAttributeWithValue
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- insertAttributeWithValue
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- insertNamespace
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- insertComment
  
  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.
  
  Throws:
  
  IllegalArgumentException - If the insertion is not allowed at the cursor's location.
- insertProcInst
  
  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.
  
  Throws:
  
  IllegalStateException - If the insertion is not allowed at the cursor's location.

Interface XmlCursor

Nested Class Summary

Method Summary

Methods inherited from interface org.apache.xmlbeans.XmlTokenSource

Method Details