org.apache.xmlbeans.XmlCursor Maven / Gradle / Ivy
/* Copyright 2004 The Apache Software Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.xmlbeans;
import java.lang.ref.Reference;
import java.lang.ref.WeakReference;
import java.util.Collection;
import java.util.Map;
import javax.xml.namespace.QName;
/**
* 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 {@link XmlCursor.TokenType 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 {@link XmlTokenSource#newCursor() newCursor} method
* exposed by an object representing
* the XML, whether it was parsed into a strong type compiled from
* schema or an {@link XmlObject 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 {@link XmlCursor.TokenType 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 {@link #currentTokenType() 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)
*/
public interface XmlCursor extends XmlTokenSource
{
/**
* An enumeration that identifies the type of an XML token.
*/
public static final class TokenType
{
public String toString ( ) { return _name; }
/**
* Returns one of the INT_ values defined in this class.
*/
public int intValue ( ) { return _value; }
/** No token. See {@link #intValue}. */
public static final int INT_NONE = 0;
/** The start-document token. See {@link #intValue}. */
public static final int INT_STARTDOC = 1;
/** The end-document token. See {@link #intValue}. */
public static final int INT_ENDDOC = 2;
/** The start-element token. See {@link #intValue}. */
public static final int INT_START = 3;
/** The end-element token. See {@link #intValue}. */
public static final int INT_END = 4;
/** The text token. See {@link #intValue}. */
public static final int INT_TEXT = 5;
/** The attribute token. See {@link #intValue}. */
public static final int INT_ATTR = 6;
/** The namespace declaration token. See {@link #intValue}. */
public static final int INT_NAMESPACE = 7;
/** The comment token. See {@link #intValue}. */
public static final int INT_COMMENT = 8;
/** The processing instruction token. See {@link #intValue}. */
public static final int INT_PROCINST = 9;
/** True if no token. */
public boolean isNone ( ) { return this == NONE; }
/** True if is start-document token. */
public boolean isStartdoc ( ) { return this == STARTDOC; }
/** True if is end-document token. */
public boolean isEnddoc ( ) { return this == ENDDOC; }
/** True if is start-element token. */
public boolean isStart ( ) { return this == START; }
/** True if is end-element token. */
public boolean isEnd ( ) { return this == END; }
/** True if is text token. */
public boolean isText ( ) { return this == TEXT; }
/** True if is attribute token. */
public boolean isAttr ( ) { return this == ATTR; }
/** True if is namespace declaration token. */
public boolean isNamespace ( ) { return this == NAMESPACE; }
/** True if is comment token. */
public boolean isComment ( ) { return this == COMMENT; }
/** True if is processing instruction token. */
public boolean isProcinst ( ) { return this == PROCINST; }
/** True if is start-document or start-element token */
public boolean isContainer ( ) { return this == STARTDOC || this == START; }
/** True if is end-document or end-element token */
public boolean isFinish ( ) { return this == ENDDOC || this == END; }
/** True if is attribute or namespace declaration token */
public boolean isAnyAttr ( ) { return this == NAMESPACE || this == ATTR; }
/** The singleton no-token type */
public static final TokenType NONE = new TokenType( "NONE", INT_NONE );
/** The singleton start-document token type */
public static final TokenType STARTDOC = new TokenType( "STARTDOC", INT_STARTDOC );
/** The singleton start-document token type */
public static final TokenType ENDDOC = new TokenType( "ENDDOC", INT_ENDDOC );
/** The singleton start-element token type */
public static final TokenType START = new TokenType( "START", INT_START );
/** The singleton end-element token type */
public static final TokenType END = new TokenType( "END", INT_END );
/** The singleton text token type */
public static final TokenType TEXT = new TokenType( "TEXT", INT_TEXT );
/** The singleton attribute token type */
public static final TokenType ATTR = new TokenType( "ATTR", INT_ATTR );
/** The singleton namespace declaration token type */
public static final TokenType NAMESPACE = new TokenType( "NAMESPACE", INT_NAMESPACE );
/** The singleton comment token type */
public static final TokenType COMMENT = new TokenType( "COMMENT", INT_COMMENT );
/** The singleton processing instruction token type */
public static final TokenType PROCINST = new TokenType( "PROCINST", INT_PROCINST );
private TokenType ( String name, int value )
{
_name = name;
_value = value;
}
private String _name;
private int _value;
}
/**
* 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.
*/
void dispose ( );
/**
* 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.
*
* @param moveTo The cursor at the location to which this cursor
* should be moved.
* @return true if the cursor moved; otherwise, false.
*/
boolean toCursor ( XmlCursor moveTo );
/**
* 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.
*/
void push ( );
/**
* Restores the cursor location most recently saved with the push() method.
*
* @return true if there was a location to restore; otherwise, false.
*/
boolean pop ( );
/**
* 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 {@link #hasNextSelection} and {@link #toNextSelection} (similar to
* {@link 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.
*
* @param path The path expression to execute.
* @throws XmlRuntimeException If the query expression is invalid.
*/
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
* 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.
*
* @param path The path expression to execute.
* @param options Options for the query. For example, you can call
* the {@link XmlOptions#setXqueryCurrentNodeVar(String) 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.
*/
void selectPath ( String path, XmlOptions options );
/**
* Returns whether or not there is a next selection.
*
* @return true if there is a next selection; otherwise, false.
*/
boolean hasNextSelection ( );
/**
* Moves this cursor to the next location in the selection,
* if any. See the {@link #selectPath} and {@link #addToSelection} methods.
*
* @return true if the cursor moved; otherwise, false.
*/
boolean toNextSelection ( );
/**
* 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.
*
* @param i The index of the desired location.
* @return true if the cursor was moved; otherwise, false.
*/
boolean toSelection ( int i );
/**
* 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.
*
* @return A number indicating the size of the current selection.
*/
int getSelectionCount ( );
/**
* 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.
*/
void addToSelection ( );
/**
* Clears this cursor's selection, but does not modify the document.
*/
void clearSelections ( );
/**
* 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.
*
* @param bookmark The bookmark at the location to which this
* cursor should be moved.
* @return true if the cursor moved; otherwise, false.
*/
boolean toBookmark ( XmlBookmark bookmark );
/**
* 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.
*
* @param key The key held by the next bookmark at the location to
* which this cursor should be moved.
* @return The next corresponding bookmark, if it exists; null if there
* is no next bookmark with the specified key.
*/
XmlBookmark toNextBookmark ( 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.
*
* @param key The key held by the previous bookmark at the location to
* which this cursor should be moved.
* @return The previous corresponding bookmark, if it exists; null if
* there is no previous bookmark with the specified key.
*/
XmlBookmark toPrevBookmark ( Object key );
/**
* 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);
*
*
* @return The name of the XML at this cursor's location; null if there
* is no name.
*/
QName getName ( );
/**
* Sets the name of the current token. This token can be START, NAMESPACE,
* ATTR or PROCINST.
*
* @param name The new name for the current token.
*/
void setName ( QName name );
/**
* 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.
*
* @param prefix The namespace prefix for the requested namespace.
* @return The URI for corresponding to the specified prefix if it
* exists; otherwise, null.
*/
String namespaceForPrefix ( String prefix );
/**
* 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.
*
* @param namespaceURI The namespace URI corresponding to the requested
* prefix.
* @return The prefix corresponding to the specified URI if it exists;
* otherwise, a newly generated prefix.
*/
String prefixForNamespace ( String namespaceURI );
/**
* 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.
*
* @param addToThis The Map to add the namespaces to.
*/
void getAllNamespaces ( Map addToThis );
/**
* 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.
*
* @return The strongly-typed object at the cursor's current location;
* null if the current location is not a START, STARTDOC, or ATTR.
*/
XmlObject getObject ( );
/**
* 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.
*
*
* @return The TokenType instance for the token at the cursor's current
* location.
*/
TokenType currentTokenType ( );
/**
* True if the current token is a STARTDOC token type, meaning
* at the very root of the document.
*
* @return true if this token is a STARTDOC token type;
* otherwise, false.
*/
boolean isStartdoc ( );
/**
* True if this token is an ENDDOC token type, meaning
* at the very end of the document.
*
* @return true if this token is an ENDDOC token type;
* otherwise, false.
*/
boolean isEnddoc ( );
/**
* True if this token is a START token type, meaning
* just before an element's start.
*
* @return true if this token is a START token type;
* otherwise, false.
*/
boolean isStart ( );
/**
* True if this token is an END token type, meaning
* just before an element's end.
*
* @return true if this token is an END token type;
* otherwise, false.
*/
boolean isEnd ( );
/**
* True if the this token is a TEXT token type, meaning
* just before or inside text.
*
* @return true if this token is a TEXT token type;
* otherwise, false.
*/
boolean isText ( );
/**
* True if this token is an ATTR token type, meaning
* just before an attribute.
*
* @return true if this token is an ATTR token type;
* otherwise, false.
*/
boolean isAttr ( );
/**
* True if this token is a NAMESPACE token type, meaning
* just before a namespace declaration.
*
* @return true if this token is a NAMESPACE token type;
* otherwise, false.
*/
boolean isNamespace ( );
/**
* True if this token is a COMMENT token type, meaning
* just before a comment.
*
* @return true if this token is a COMMENT token type;
* otherwise, false.
*/
boolean isComment ( );
/**
* True if this token is a PROCINST token type, meaning
* just before a processing instruction.
*
* @return true if this token is a PROCINST token type;
* otherwise, false.
*/
boolean isProcinst ( );
/**
* 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.
*
* @return true if this token is a container token; otherwise, false.
*/
boolean isContainer ( );
/**
* True if this token is a finish token. A finish token can be an ENDDOC
* or END token type.
* @return true if this token is a finish token; otherwise, false.
*/
boolean isFinish ( );
/**
* True if this token is any attribute. This includes an ATTR token type and
* the NAMESPACE token type attribute.
*
* @return true if the current cursor is at any attribute; otherwise, false.
*/
boolean isAnyAttr ( );
/**
* 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.
*
* @return The TokenType instance for the token immediately before the
* token at the cursor's current location.
*/
TokenType prevTokenType ( );
/**
* 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.
*
* @return true if there is a next token; otherwise, false.
*/
boolean hasNextToken ( );
/**
* True if there is a previous token. When this is false, toPrevToken
* returns NONE and does not move the cursor.
*
* @return true if there is a previous token; otherwise, false.
*/
boolean hasPrevToken ( );
/**
* 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.
*
* @return The token type for the next token if the cursor was moved;
* otherwise, NONE.
*/
TokenType toNextToken ( );
/**
* 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.
*
* @return The token type for the previous token if the cursor was moved;
* otherwise, NONE.
*/
TokenType toPrevToken ( );
/**
* 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.
*
* @return The new current token type.
*/
TokenType toFirstContentToken ( );
/**
* 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.
*
* @return The new current token type.
*/
TokenType toEndToken ( );
/**
* 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.
*
* @param maxCharacterCount The maximum number of characters by which
* the cursor should be moved.
* @return The actual number of characters by which the cursor was moved;
* 0 if the cursor was not moved.
*/
int toNextChar ( int maxCharacterCount );
/**
* Moves the cursor backwards by the number of characters given. Has
* similar characteristics to the {@link #toNextChar(int) toNextChar} method.
*
* @param maxCharacterCount The maximum number of characters by which
* the cursor should be moved.
* @return The actual number of characters by which the cursor was moved;
* 0 if the cursor was not moved.
*/
int toPrevChar ( int maxCharacterCount );
/**
* 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.
*
* @return true if the cursor was moved; otherwise, false.
*/
boolean toNextSibling ( );
/**
* 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.)
*
* @return true if the cursor was moved; otherwise, false.
*/
boolean toPrevSibling ( );
/**
* 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.
*
* @return true if the cursor was moved; false if the cursor is at the STARTDOC
* token.
*/
boolean toParent ( );
/**
* 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.
*
* @return true if the cursor was moved; otherwise, false.
*/
boolean toFirstChild ( );
/**
* Moves the cursor to the last element child, or returns false and
* does not move the cursor if there are no element children.
*
* @return true if the cursor was moved; otherwise, false.
*/
boolean toLastChild ( );
/**
* Moves the cursor to the first child element of the specified name in
* no namespace.
*
* @param name The name of the element to move the cursor to.
* @return true if the cursor was moved; otherwise, false.
*/
boolean toChild ( String name );
/**
* Moves the cursor to the first child element of the specified name in the
* specified namespace.
*
* @param namespace The namespace URI for the element to move the cursor
* to.
* @param name The name of the element to move to.
* @return true if the cursor was moved; otherwise, false.
* @throws IllegalArgumentException If the name is not a valid local name.
*/
boolean toChild ( String namespace, String name );
/**
* Moves the cursor to the first child element of the specified qualified name.
*
* @param name The name of the element to move the cursor to.
*/
boolean toChild ( QName name );
/**
* Moves the cursor to the child element specified by index.
*
* @param index The position of the element in the sequence of child
* elements.
* @return true if the cursor was moved; otherwise, false.
*/
boolean toChild ( int index );
/**
* Moves the cursor to the specified index child element of the
* specified name, where that element is the .
*
* @param name The name of the child element to move the cursor to.
* @param index The position of the element in the sequence of child
* elements.
* @return true if the cursor was moved; otherwise, false.
*/
boolean toChild ( QName name, int index );
/**
* Moves the cursor to the next sibling element of the specified name in no
* namespace.
*
* @param name The name of the element to move the cursor to.
* @return true if the cursor was moved; otherwise, false.
*/
boolean toNextSibling ( String name );
/**
* Moves the cursor to the next sibling element of the specified name
* in the specified namespace.
*
* @param namespace The namespace URI for the element to move the cursor
* to.
* @param name The name of the element to move the cursor to.
* @return true if the cursor was moved; otherwise, false.
*/
boolean toNextSibling ( String namespace, String name );
/**
* Moves the cursor to the next sibling element of the specified
* qualified name.
*
* @param name The name of the element to move the cursor to.
* @return true if the cursor was moved; otherwise, false.
*/
boolean toNextSibling ( QName name );
/**
* 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());
* }
*
*
* @return true if the cursor was moved; otherwise, false.
*/
boolean toFirstAttribute ( );
/**
* 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.
*
* @return true if the cursor was moved; otherwise, false.
*/
boolean toLastAttribute ( );
/**
* 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.
* @see #toFirstAttribute()
*
* @return true if the cursor was moved; otherwise, false.
*/
boolean toNextAttribute ( );
/**
* 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.
*
* @return true if the cursor was moved; otherwise, false.
*/
boolean toPrevAttribute ( );
/**
* 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.
*
* @param attrName The name of the attribute whose value is requested.
* @return The attribute's value if it has one; otherwise, null.
*/
String getAttributeText ( QName attrName );
/**
* 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.
*
* @param attrName The name of the attribute whose value is being set.
* @param value The new value for the attribute.
* @return true if the new value was set; otherwise, false.
*/
boolean setAttributeText ( QName attrName, String value );
/**
* When at a START or STARTDOC, removes the attribute with the given name.
*
* @param attrName The name of the attribute that should be removed.
* @return true if the attribute was removed; otherwise, false.
*/
boolean removeAttribute ( QName attrName );
/**
* 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 {@link java.lang.IllegalStateException}.
*
* @return 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.
*/
String getTextValue ( );
/**
* 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 {@link java.lang.IllegalStateException}.
*
* The value of an empty tag is the empty string.
*
* @param returnedChars A character array to hold the returned characters.
* @param offset The position within returnedChars to which the first of the
* returned characters should be copied.
* @param maxCharacterCount The maximum number of characters after this cursor's
* location to copy. A negative value specifies that all characters should be copied.
* @return The actual number of characters copied; 0 if no characters
* were copied.
*/
int getTextValue ( char[] returnedChars, int offset, int maxCharacterCount );
/**
* Returns the characters of the current TEXT token. If the current token
* is not TEXT, returns "". If in the middle of a TEXT token, returns
* those chars to the right of the cursor of the TEXT token.
*
* @return The requested text; an empty string if the current token type is
* not 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.
*
* @param text The text to use as a new value.
* @throws java.lang.IllegalStateException If the token type at this
* cursor's location is not START, STARTDOC, ATTR, COMMENT or
* PROCINST.
*/
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) 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.
*
* @param sourceChars A character array containing the XML's new value.
* @param offset The position within sourceChars from which the first of
* the source characters should be copied.
* @param length The maximum number of characters to set as the XML's new
* value.
* @throws java.lang.IllegalArgumentException If the token type at this
* cursor's location is not START, STARTDOC, ATTR, COMMENT or
* PROCINST.
*/
void setTextValue ( char[] sourceChars, int offset, int length );
/**
* Returns characters to the right of the cursor up to the next token.
*/
String getChars ( );
/**
* 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.
*
* @param returnedChars A character array to hold the returned characters.
* @param offset The position within returnedChars at which the first of the
* returned characters should be added.
* @param maxCharacterCount The maximum number of characters after this cursor's
* location to return.
* @return The actual number of characters returned; 0 if no characters
* were returned or if the current token is not TEXT.
*/
int getChars ( char[] returnedChars, int offset, int maxCharacterCount );
/**
* Moves the cursor to the STARTDOC token, which is the
* root of the document.
*/
void toStartDoc ( );
/**
* Moves the cursor to the ENDDOC token, which is the end
* of the document.
*/
void toEndDoc ( );
/**
* Determines if the specified cursor is in the same document as
* this cursor.
*
* @param cursor The cursor that may be in the same document
* as this cursor.
* @return true if the specified cursor is in the same document;
* otherwise, false.
*/
boolean isInSameDocument ( 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.
*
* @param cursor The cursor whose position should be compared
* with this cursor.
* @return 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 java.lang.IllegalArgumentException If the specified
* cursor is not in the same document as this cursor.
*/
int comparePosition ( 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
*
* @param cursor The cursor whose position should be compared
* with this cursor.
* @return true if this cursor is to the left of the specified
* cursor; otherwise, false.
*/
boolean isLeftOf ( 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
*
* @param cursor The cursor whose position should be compared
* with this cursor.
* @return true if this cursor is at the same position as
* the specified cursor; otherwise, false.
*/
boolean isAtSamePositionAs ( 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
*
* @param cursor The cursor whose position should be compared
* with this cursor.
* @return true if this cursor is to the right of the specified
* cursor; otherwise, false.
*/
boolean isRightOf ( XmlCursor cursor );
/**
* 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]");
*
*
* @param query The XQuery expression to execute.
* @return A cursor containing the results of the query.
* @throws XmlRuntimeException If the query expression is invalid.
*/
XmlCursor execQuery ( String query );
/**
* Executes the specified XQuery expression against the XML this
* cursor is in, and using the specified options.
*
* @param query The XQuery expression to execute.
* @param options Options for the query. For example, you can call
* the {@link XmlOptions#setXqueryCurrentNodeVar(String) 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.
*/
XmlCursor execQuery ( String query, XmlOptions options );
/**
* Represents the state of a dcoument at a particular point
* in time. It is used to determine if a document has been changed
* since that point in time.
*/
interface ChangeStamp
{
/**
* Returns whether or not the document assoiated with this ChangeStamp
* has been altered since the ChangeStamp had been created.
*/
public boolean hasChanged ( );
}
/**
* 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.
*
* @return The change stamp for the document the current cursor is in.
*/
ChangeStamp getDocChangeStamp ( );
/**
* Subclasses of XmlBookmark can be used to annotate an XML document.
* This class is abstract to prevent parties from inadvertently
* interfering with each others' bookmarks without explicitly
* sharing a bookmark class.
*/
abstract class XmlBookmark
{
/**
* Constructs a strongly-referenced bookmark.
*/
public XmlBookmark ( ) { this( false ); }
/**
* Constructs a bookmark.
* @param weak true if the document's reference to the bookmark should be a WeakReference
*/
public XmlBookmark ( boolean weak )
{
_ref = weak ? new WeakReference( this ) : null;
}
/**
* Call the createCursor method to create a new cursor which is
* positioned at the same splace as the bookmark. It is much more
* efficient to call toBookmark on an existing cursor than it
* is to create a new cursor. However, toBookmark may fail if the
* bookmark is in a different document than the cursor. It is
* under these circumstances where createCursor needs to be called
* on the bookmark. Subsequent navigations to bookmark
* positions should attempt to reuse the last cursor to
* improve performace.
*/
public final XmlCursor createCursor ( )
{
return _currentMark == null ? null : _currentMark.createCursor();
}
/**
* Moves the given cursor to this bookmark, and returns it.
*/
public final XmlCursor toBookmark ( XmlCursor c )
{
return c == null || !c.toBookmark( this ) ? createCursor() : c;
}
/**
* The default key for bookmarks is the class which implements
* them. This way, multiple parties using bookmarks in the
* same instance document will not interfere with eachother.
* One can, however, override getKey() to use a key other than
* the class.
*/
public Object getKey ( )
{
return this.getClass();
}
/**
* The mark is set by the host document; it is capable of
* returning an XmlCursor implementation at the location of
* the bookmark.
*/
public XmlMark _currentMark;
/**
* If non-null, the ref is used by the host document
* to maintain a reference to the bookmark. If it is a weak
* reference, the host document will not prevent the Bookmark
* from being garbage collected.
*/
public final Reference _ref;
}
/**
* An abstract {@link XmlCursor} factory.
* Implementations of XmlCursor implement XmlMark to be able to
* reconstitute a cursor from a bookmark. When content moves between
* implementations, the XmlMark is set to the implmentation's which
* recieves the new content.
*/
interface XmlMark
{
XmlCursor createCursor ( );
}
/**
* 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.
*
* @param bookmark The bookmark to set.
*/
void setBookmark ( XmlBookmark bookmark );
/**
* 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 {@link XmlCursor.XmlBookmark#getKey() getKey} method is not overridden on
* the bookmark, then the bookmark's class is used as the key.
*
* @param key The key for the bookmark to retrieve.
* @return The requested bookmark; null if there is no bookmark
* corresponding to the specified key.
*/
XmlBookmark getBookmark ( Object key );
/**
* Clears the bookmark whose key is specified, if the bookmark
* exists at this cursor's location.
*
* @param key The for the bookmark to clear.
*/
void clearBookmark ( Object key );
/**
* 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.
*
* @param listToFill The collection that will contain bookmarks
* returned by this method.
*/
void getAllBookmarkRefs ( Collection listToFill );
/**
* 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.
*
* @return true if anything was removed; false only if the cursor is
* just before END or ENDDOC token.
* @throws java.lang.IllegalArgumentException If the cursor is at a
* STARTDOC token.
*/
boolean removeXml ( );
/**
* 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.
*
* @param toHere The cursor at the location to which the XML should
* be moved.
* @return true if anything was moved. This only happens when the XML to be
* moved contains the target of the move.
* @throws java.lang.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.
*/
boolean moveXml ( 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.
*
* @param toHere The cursor at the location to which the XML should
* be copied.
* @return true if anything was copied; false if the token supports the operation,
* but nothing was copied.
* @throws java.lang.IllegalArgumentException If the operation is not allowed
* at the cursor's location.
*/
boolean copyXml ( XmlCursor toHere );
/**
* 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.
*
* @return true if anything was copied; otherwise, false.
*/
boolean removeXmlContents ( );
/**
* 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.
*
* @param toHere The cursor at the location to which the XML should be moved.
* @return true if anything was moved; otherwise, false.
*/
boolean moveXmlContents ( 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.
*
* @param toHere The cursor at the location to which the XML should
* be copied.
* @return true if anything was copied; otherwise, false.
*/
boolean copyXmlContents ( XmlCursor toHere );
/**
* 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.
*
* @param maxCharacterCount The maximum number of characters after this cursor's
* location to remove.
* @return The actual number of characters removed.
* @throws java.lang.IllegalArgumentException If the operation is not allowed
* at the cursor's location.
*/
int removeChars ( int maxCharacterCount );
/**
* 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.
*
* @param maxCharacterCount The maximum number of characters after this cursor's
* location to move.
* @param toHere The cursor to which the characters should be moved.
* @return The actual number of characters moved.
* @throws java.lang.IllegalArgumentException If the operation is not allowed
* at the cursor's location.
*/
int moveChars ( 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.
*
* @param maxCharacterCount The maximum number of characters after this cursor's
* location to copy.
* @param toHere The cursor to which the characters should be copied.
* @return The actual number of characters copied.
* @throws java.lang.IllegalArgumentException If the operation is not allowed
* at the cursor's location.
*/
int copyChars ( int maxCharacterCount, XmlCursor toHere );
/**
* Inserts the specified text immediately before this cursor's location.
*
* @param text The text to insert.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void insertChars ( String text );
/**
* Inserts an element immediately before this cursor's location, giving
* the element the specified qualified name.
*
* @param name The qualified name for the element.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void insertElement ( QName name );
/**
* Inserts an element immediately before this cursor's location, giving
* the element the specified local name.
*
* @param localName The local name for the new element.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void insertElement ( String localName );
/**
* Inserts a new element immediately before this cursor's location, giving the
* element the specified local name and associating it with specified namespace
*
* @param localName The local name for the new element.
* @param uri The URI for the new element's namespace.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void insertElement ( String localName, String uri );
/**
* 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.
*
* @param name The qualified name for the new element.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void beginElement ( QName name );
/**
* 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.
*
* @param localName The local name for the new element.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void beginElement ( String localName );
/**
* 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.
*
* @param localName The local name for the new element.
* @param uri The URI for the new element's namespace.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void beginElement ( String localName, String uri );
/**
* Inserts a new element immediately before this cursor's location, giving the
* element the specified qualified name and content.
*
* @param name The qualified name for the new element.
* @param text The content for the new element.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void insertElementWithText ( QName name, String text );
/**
* Inserts a new element immediately before this cursor's location, giving the
* element the specified local name and content.
*
* @param localName The local name for the new element.
* @param text The content for the new element.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void insertElementWithText ( String localName, 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.
*
* @param localName The local name for the new element.
* @param uri The URI for the new element's namespace.
* @param text The content for the new element.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void insertElementWithText ( String localName, String uri, String text );
/**
* Inserts a new attribute immediately before this cursor's location, giving it
* the specified local name.
*
* @param localName The local name for the new attribute.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void insertAttribute ( String localName );
/**
* Inserts a new attribute immediately before this cursor's location, giving it
* the specified local name and associating it with the specified namespace.
*
* @param localName The local name for the new attribute.
* @param uri The URI for the new attribute's namespace.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void insertAttribute ( String localName, String uri );
/**
* Inserts a new attribute immediately before this cursor's location, giving it
* the specified name.
*
* @param name The local name for the new attribute.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void insertAttribute ( QName name );
/**
* Inserts a new attribute immediately before this cursor's location, giving it
* the specified value and name.
*
* @param Name The local name for the new attribute.
* @param value The value for the new attribute.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void insertAttributeWithValue ( String Name, 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.
*
* @param name The name for the new attribute.
* @param uri The URI for the new attribute's namespace.
* @param value The value for the new attribute.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void insertAttributeWithValue ( String name, String uri, String value );
/**
* Inserts an attribute immediately before the cursor's location, giving it
* the specified name and value.
*
* @param name The name for the new attribute.
* @param value The value for the new attribute.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void insertAttributeWithValue ( QName name, String value );
/**
* Inserts a namespace declaration immediately before the cursor's location,
* giving it the specified prefix and URI.
*
* @param prefix The prefix for the namespace.
* @param namespace The URI for the namespace.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void insertNamespace ( String prefix, String namespace );
/**
* Inserts an XML comment immediately before the cursor's location,
* giving it the specified content.
*
* @param text The new comment's content.
* @throws java.lang.IllegalArgumentException If the insertion is not allowed
* at the cursor's location.
*/
void insertComment ( String text );
/**
* Inserts an XML processing instruction immediately before the cursor's location,
* giving it the specified target and text.
*
* @param target The target for the processing instruction.
* @param text The new processing instruction's text.
* @throws java.lang.IllegalStateException If the insertion is not allowed
* at the cursor's location.
*/
void insertProcInst ( String target, String text );
}