Home » xmlbeans-2.5.0-src » org.apache » xmlbeans » [javadoc | source]

    1   /*   Copyright 2004 The Apache Software Foundation
    2    *
    3    *   Licensed under the Apache License, Version 2.0 (the "License");
    4    *   you may not use this file except in compliance with the License.
    5    *   You may obtain a copy of the License at
    6    *
    7    *       http://www.apache.org/licenses/LICENSE-2.0
    8    *
    9    *   Unless required by applicable law or agreed to in writing, software
   10    *   distributed under the License is distributed on an "AS IS" BASIS,
   11    *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   12    *   See the License for the specific language governing permissions and
   13    *  limitations under the License.
   14    */
   15   
   16   package org.apache.xmlbeans;
   17   
   18   import java.lang.ref.Reference;
   19   import java.lang.ref.WeakReference;
   20   import java.util.Collection;
   21   import java.util.Map;
   22   import javax.xml.namespace.QName;
   23   
   24   /**
   25    * Represents a position between two logical tokens in an XML document. 
   26    * 
   27    * The tokens themselves are not exposed as objects, but their type and properties
   28    * are discoverable through methods on the cursor.  In particular, the general
   29    * category of token is represented by a {@link XmlCursor.TokenType TokenType}.<br/><br/>
   30    * 
   31    * You use an XmlCursor instance to navigate through and manipulate an XML 
   32    * instance document. 
   33    * Once you obtain an XML document, you can create a cursor to represent 
   34    * a specific place in the XML. Because you can use a cursor with or 
   35    * without a schema corresponding to the XML, cursors are an ideal 
   36    * way to handle XML without a schema. You can create a new cursor by
   37    * calling the {@link XmlTokenSource#newCursor() newCursor} method 
   38    * exposed by an object representing
   39    * the XML, whether it was parsed into a strong type compiled from 
   40    * schema or an {@link XmlObject XmlObject} (as in the no-schema case).<br/><br/>
   41    * 
   42    * With an XmlCursor, you can also: <br/><br/>
   43    * 
   44    * <ul>
   45    * <li>Execute XQuery and XPath expressions against the XML with the
   46    * execQuery and selectPath methods.</li>
   47    * 
   48    * <li>Edit and reshape the document by inserting, moving, copying, and removing
   49    * XML.</li>
   50    * 
   51    * <li>Insert bookmarks that "stick" to the XML at the cursor's
   52    * position even if the cursor or XML moves.</li>
   53   
   54    * <li>Get and set values for containers (elements and whole documents),
   55    * attributes, processing instructions, and comments.</li>
   56    * </ul>
   57    * 
   58    * A cursor moves through XML by moving past tokens. A
   59    * token represents a category of XML markup, such as the start of an element, 
   60    * its end, an attribute, comment, and so on. XmlCursor methods such as
   61    * toNextToken, toNextSibling, toParent, and so on move the cursor 
   62    * among tokens. Each token's category is of a particular <em>type</em>, represented 
   63    * by one of the nine types defined by the {@link XmlCursor.TokenType TokenType} class. <br/><br/>
   64    * 
   65    * When you get a new cursor for a whole instance document, the cursor is
   66    * intially located before the STARTDOC token. This token, which has no analogy
   67    * in the XML specification, is present in this logical model of XML
   68    * so that you may distinguish between the document as a whole
   69    * and the content of the document. Terminating the document is an ENDDOC
   70    * token. This token is also not part of the XML specification. A cursor 
   71    * located immediately before this token is at the very end of the document. 
   72    * It is not possible to position the cursor after the ENDDOC token. 
   73    * Thus, the STARTDOC and ENDDOC tokens are effectively "bookends" for the content of 
   74    * the document.<br/><br/>
   75    * 
   76    * For example, for the following XML, if you were the navigate a cursor
   77    * through the XML document using toNextToken(), the list of token types that 
   78    * follows represents the token sequence you would encounter. <br/><br/>
   79    * 
   80    * <pre>
   81    * &lt;sample x='y'&gt;
   82    *     &lt;value&gt;foo&lt;/value&gt;
   83    * &lt;/sample&gt;
   84    * </pre>
   85    * 
   86    * STARTDOC <br/>
   87    * START (sample) <br/>
   88    * ATTR (x='y') <br/>
   89    * TEXT ("\n    ") <br/>
   90    * START (value) <br/>
   91    * TEXT ("foo") <br/>
   92    * END (value) <br/>
   93    * TEXT ("\n") <br/>
   94    * END (sample)<br/>
   95    * ENDDOC <br/><br/>
   96    *
   97    * When there are no more tokens available, hasNextToken() returns
   98    * false and toNextToken() returns the special token type NONE and does not move
   99    * the cursor.
  100    * <br/><br/>
  101    * 
  102    * The {@link #currentTokenType() currentTokenType()} method 
  103    * will return the type of the token that is immediately after the cursor. 
  104    * You can also use a number of convenience methods that test for a particular 
  105    * token type. These include the methods isStart(), 
  106    * isStartdoc(), isText(), isAttr(), and so on. Each returns a boolean 
  107    * value indicating whether the token that follows the cursor is the type 
  108    * in question. 
  109    * <br/><br/>
  110    * 
  111    * A few other methods determine whether the token is of a kind that may include 
  112    * multiple token types. The isAnyAttr() method, for example, returns true if
  113    * the token immediately following the cursor is any kind of attribute, 
  114    * including those of the ATTR token type and xmlns attributes.
  115    * <br/><br/>
  116    * 
  117    * Legitimate sequences of tokens for an XML document are described
  118    * by the following Backus-Naur Form (BNF): <br/>
  119    * 
  120    * <pre>
  121    * &lt;doc&gt; ::= STARTDOC &lt;attributes&gt; &lt;content&gt; ENDDOC
  122    * &lt;element&gt; ::= START &lt;attributes&gt; &lt;content&gt; END
  123    * &lt;attributes&gt; ::= ( ATTR | NAMESPACE ) *
  124    * &lt;content&gt; ::= ( COMMENT | PROCINST | TEXT | &lt;element&gt; ) *
  125    * </pre>
  126    * 
  127    * Note that a legitimate sequence is STARTDOC ENDDOC, the result of 
  128    * creating a brand new instance of an empty document. Also note that 
  129    * attributes may only follow container tokens (STARTDOC or START)
  130    */
  131   public interface XmlCursor extends XmlTokenSource
  132   {
  133       /**
  134        * An enumeration that identifies the type of an XML token.
  135        */
  136       public static final class TokenType
  137       {
  138           public String toString ( ) { return _name;  }
  139   
  140           /**
  141            * Returns one of the INT_ values defined in this class.
  142            */
  143           public int intValue ( ) { return _value; }
  144           
  145           /** No token.  See {@link #intValue}. */ 
  146           public static final int INT_NONE      = 0;
  147           /** The start-document token.  See {@link #intValue}. */ 
  148           public static final int INT_STARTDOC  = 1;
  149           /** The end-document token.  See {@link #intValue}. */ 
  150           public static final int INT_ENDDOC    = 2;
  151           /** The start-element token.  See {@link #intValue}. */ 
  152           public static final int INT_START     = 3;
  153           /** The end-element token.  See {@link #intValue}. */ 
  154           public static final int INT_END       = 4;
  155           /** The text token.  See {@link #intValue}. */ 
  156           public static final int INT_TEXT      = 5;
  157           /** The attribute token.  See {@link #intValue}. */ 
  158           public static final int INT_ATTR      = 6;
  159           /** The namespace declaration token.  See {@link #intValue}. */ 
  160           public static final int INT_NAMESPACE = 7;
  161           /** The comment token.  See {@link #intValue}. */ 
  162           public static final int INT_COMMENT   = 8;
  163           /** The processing instruction token.  See {@link #intValue}. */ 
  164           public static final int INT_PROCINST  = 9;
  165           
  166           /** True if no token. */
  167           public boolean isNone      ( ) { return this == NONE;      }
  168           /** True if is start-document token. */
  169           public boolean isStartdoc  ( ) { return this == STARTDOC;  }
  170           /** True if is end-document token. */
  171           public boolean isEnddoc    ( ) { return this == ENDDOC;    }
  172           /** True if is start-element token. */
  173           public boolean isStart     ( ) { return this == START;     }
  174           /** True if is end-element token. */
  175           public boolean isEnd       ( ) { return this == END;       }
  176           /** True if is text token. */
  177           public boolean isText      ( ) { return this == TEXT;      }
  178           /** True if is attribute token. */
  179           public boolean isAttr      ( ) { return this == ATTR;      }
  180           /** True if is namespace declaration token. */
  181           public boolean isNamespace ( ) { return this == NAMESPACE; }
  182           /** True if is comment token. */
  183           public boolean isComment   ( ) { return this == COMMENT;   }
  184           /** True if is processing instruction token. */
  185           public boolean isProcinst  ( ) { return this == PROCINST;  }
  186   
  187           /** True if is start-document or start-element token */
  188           public boolean isContainer ( ) { return this == STARTDOC  || this == START; }
  189           /** True if is end-document or end-element token */
  190           public boolean isFinish    ( ) { return this == ENDDOC    || this == END;   }
  191           /** True if is attribute or namespace declaration token */
  192           public boolean isAnyAttr   ( ) { return this == NAMESPACE || this == ATTR;  }
  193   
  194           /** The singleton no-token type */
  195           public static final TokenType NONE      = new TokenType( "NONE",      INT_NONE      );
  196           /** The singleton start-document token type */
  197           public static final TokenType STARTDOC  = new TokenType( "STARTDOC",  INT_STARTDOC  );
  198           /** The singleton start-document token type */
  199           public static final TokenType ENDDOC    = new TokenType( "ENDDOC",    INT_ENDDOC    );
  200           /** The singleton start-element token type */
  201           public static final TokenType START     = new TokenType( "START",     INT_START     );
  202           /** The singleton end-element token type */
  203           public static final TokenType END       = new TokenType( "END",       INT_END       );
  204           /** The singleton text token type */
  205           public static final TokenType TEXT      = new TokenType( "TEXT",      INT_TEXT      );
  206           /** The singleton attribute token type */
  207           public static final TokenType ATTR      = new TokenType( "ATTR",      INT_ATTR      );
  208           /** The singleton namespace declaration token type */
  209           public static final TokenType NAMESPACE = new TokenType( "NAMESPACE", INT_NAMESPACE );
  210           /** The singleton comment token type */
  211           public static final TokenType COMMENT   = new TokenType( "COMMENT",   INT_COMMENT   );
  212           /** The singleton processing instruction token type */
  213           public static final TokenType PROCINST  = new TokenType( "PROCINST",  INT_PROCINST  );
  214   
  215           private TokenType ( String name, int value )
  216           {
  217               _name = name;
  218               _value = value;
  219           }
  220           
  221           private String _name;
  222           private int    _value;
  223       }
  224   
  225       /**
  226        * Deallocates resources needed to manage the cursor, rendering this cursor
  227        * inoperable. Because cursors are managed by a mechanism which stores the 
  228        * XML, simply letting a cursor go out of scope and having the garbage collector
  229        * attempt to reclaim it may not produce desirable performance.<br/><br/>
  230        *
  231        * So, explicitly disposing a cursor allows the underlying implementation
  232        * to release its responsibility of maintaining its position.<br/><br/>
  233        *
  234        * After a cursor has been disposed, it may not be used again.  It can
  235        * throw IllegalStateException or NullPointerException if used after
  236        * disposal.<br/><br/>
  237        */
  238   
  239       void dispose ( );
  240       
  241       /**
  242        * Moves this cursor to the same position as the moveTo cursor.  if the
  243        * moveTo cursor is in a different document from this cursor, this cursor
  244        * will not be moved, and false returned.
  245        * 
  246        * @param  moveTo  The cursor at the location to which this cursor
  247        * should be moved.
  248        * @return  true if the cursor moved; otherwise, false.
  249        */
  250   
  251       boolean toCursor ( XmlCursor moveTo );
  252       
  253       /**
  254        * Saves the current location of this cursor on an internal stack of saved
  255        * positions (independent of selection). This location may be restored
  256        * later by calling the pop() method.
  257        */
  258   
  259       void push ( );
  260   
  261       /**
  262        * Restores the cursor location most recently saved with the push() method.
  263        * 
  264        * @return  true if there was a location to restore; otherwise, false.
  265        */
  266   
  267       boolean pop ( );
  268   
  269       /**
  270        * Executes the specified XPath expression against the XML that this 
  271        * cursor is in.  The cursor's position does not change.  To navigate to the
  272        * selections, use {@link #hasNextSelection} and {@link #toNextSelection} (similar to
  273        * {@link java.util.Iterator}).<br/><br/>
  274        * 
  275        * The root referred to by the expression should be given as 
  276        * a dot. The following is an example path expression:
  277        * <pre>
  278        * cursor.selectPath("./purchase-order/line-item");
  279        * </pre>
  280        *
  281        * Note that this method does not support top-level XPath functions.
  282        * 
  283        * @param  path  The path expression to execute.
  284        * @throws  XmlRuntimeException  If the query expression is invalid.
  285        */
  286       void selectPath ( String path );
  287   
  288       /**
  289        * Executes the specified XPath expression against the XML that this 
  290        * cursor is in. The cursor's position does not change.  To navigate to the
  291        * selections, use hasNextSelection and toNextSelection (similar to
  292        * java.util.Iterator).<br/><br/>
  293        * 
  294        * The root referred to by the expression should be given as 
  295        * a dot. The following is an example path expression:
  296        * <pre>
  297        * cursor.selectPath("./purchase-order/line-item");
  298        * </pre>
  299        *
  300        * Note that this method does not support top-level XPath functions.
  301        * 
  302        * @param  path  The path expression to execute.
  303        * @param  options  Options for the query. For example, you can call 
  304        * the {@link XmlOptions#setXqueryCurrentNodeVar(String) XmlOptions.setXqueryCurrentNodeVar(String)}
  305        * method to specify a particular name for the query expression 
  306        * variable that indicates the context node.
  307        * @throws  XmlRuntimeException  If the query expression is invalid.
  308        */
  309       void selectPath ( String path, XmlOptions options );
  310   
  311       /**
  312        * Returns whether or not there is a next selection.
  313        * 
  314        * @return  true if there is a next selection; otherwise, false.
  315        */
  316   
  317       boolean hasNextSelection ( );
  318       
  319       /**
  320        * Moves this cursor to the next location in the selection, 
  321        * if any. See the {@link #selectPath} and {@link #addToSelection} methods.
  322        * 
  323        * @return  true if the cursor moved; otherwise, false.
  324        */
  325   
  326       boolean toNextSelection ( );
  327      
  328       /**
  329        * Moves this cursor to the specified location in the selection. 
  330        * If i is less than zero or greater than or equal to the selection
  331        * count, this method returns false.
  332        *  
  333        * See also the selectPath() and addToSelection() methods.
  334        * 
  335        * @param  i  The index of the desired location.
  336        * @return  true if the cursor was moved; otherwise, false.
  337        */
  338   
  339       boolean toSelection ( int i );
  340       
  341       /**
  342        * Returns the count of the current selection. See also the selectPath() 
  343        * and addToSelection() methods.
  344        * 
  345        * You may experience better performance if you use the iteration
  346        * model using the toNextSelection method, rather than 
  347        * the indexing model using the getSelectionCount and 
  348        * toSelection methods.
  349        * 
  350        * @return  A number indicating the size of the current selection.
  351        */
  352   
  353       int getSelectionCount ( );
  354   
  355       
  356       /**
  357        * Appends the current location of the cursor to the selection.  
  358        * See also the selectPath() method. You can use this as an 
  359        * alternative to calling the selectPath method when you want
  360        * to define your own selection.
  361        */
  362   
  363       void addToSelection ( );
  364       
  365       /**
  366        * Clears this cursor's selection, but does not modify the document.
  367        */
  368       void clearSelections ( );    
  369       
  370       /**
  371        * Moves this cursor to the same position as the bookmark.  If the
  372        * bookmark is in a different document from this cursor or if the 
  373        * bookmark is orphaned, this cursor
  374        * will not be moved, and false will be returned.
  375        * 
  376        * @param  bookmark  The bookmark at the location to which this
  377        * cursor should be moved.
  378        * @return  true if the cursor moved; otherwise, false.
  379        */
  380   
  381       boolean toBookmark ( XmlBookmark bookmark );
  382   
  383       /**
  384        * Moves this cursor to the location after its current position
  385        * where a bookmark with the given key exists.  Returns false if no
  386        * such bookmark exists.
  387        * 
  388        * @param  key  The key held by the next bookmark at the location to 
  389        * which this cursor should be moved.
  390        * @return  The next corresponding bookmark, if it exists; null if there
  391        * is no next bookmark with the specified key.
  392        */
  393   
  394       XmlBookmark toNextBookmark ( Object key );
  395       
  396       /**
  397        * Moves this cursor to the location before its current position
  398        * where a bookmark with the given key exists.  Returns false if no
  399        * such bookmark exists.
  400        * 
  401        * @param  key  The key held by the previous bookmark at the location to 
  402        * which this cursor should be moved.
  403        * @return  The previous corresponding bookmark, if it exists; null if 
  404        * there is no previous bookmark with the specified key.
  405        */
  406   
  407       XmlBookmark toPrevBookmark ( Object key );
  408       
  409       /**
  410        * Returns the name of the current token. Names may be associated with
  411        * START, ATTR, NAMESPACE or PROCINST. Returns null if there is no
  412        * name associated with the current token. For START and ATTR, the 
  413        * name returned identifies the name of the element or attribute. 
  414        * For NAMESPACE, the local part of the name is the prefix, while 
  415        * the URI is the namespace defined. For PROCINST, the local part 
  416        * is the target and the uri is "".
  417        * <p>
  418        * In the following example, <code>xmlObject</code> represents
  419        * an XML instance whose root element is not preceded by any other XML.
  420        * This code prints the root element name (here, the local name, or 
  421        * name without URI).
  422        * <pre>
  423        * XmlCursor cursor = xmlObject.newCursor();
  424        * cursor.toFirstContentToken();
  425        * String elementName = cursor.getName().getLocalPart();
  426        * System.out.println(elementName);
  427        * </pre>
  428        *
  429        * @return  The name of the XML at this cursor's location; null if there
  430        * is no name.
  431        */
  432   
  433       QName getName ( );
  434       
  435       /**
  436        * Sets the name of the current token. This token can be START, NAMESPACE,
  437        * ATTR or PROCINST.
  438        * 
  439        * @param  name  The new name for the current token.
  440        */
  441   
  442       void setName ( QName name );
  443       
  444       /**
  445        * Returns the namespace URI indicated by the given prefix. The current
  446        * context must be at a START or STARTDOC. Namespace prefix mappings
  447        * are queried for the mappings defined at the current container first,
  448        * then parents are queried. The prefix can be "" or null to indicate
  449        * a search for the default namespace.  To conform with the
  450        * XML spec, the default namespace will return the no-namespace ("")
  451        * if it is not mapped.<br/><br/>
  452        * 
  453        * Note that this queries the current state of the document. When the 
  454        * document is persisted, the saving mechanism may synthesize namespaces 
  455        * (ns1, ns2, and so on) for the purposes of persistence. These namepaces are 
  456        * only present in the serialized form, and are not reflected back into 
  457        * the document being saved.
  458        * 
  459        * @param  prefix  The namespace prefix for the requested namespace.
  460        * @return  The URI for corresponding to the specified prefix if it
  461        * exists; otherwise, null.
  462        */
  463       String namespaceForPrefix ( String prefix );
  464   
  465       /**
  466        * Returns a prefix that can be used to indicate a namespace URI.  The
  467        * current context must be at a START or STARTDOC.  If there is an
  468        * existing prefix that indicates the URI in the current context, that
  469        * prefix may be returned. Otherwise, a new prefix for the URI will be
  470        * defined by adding an xmlns attribute to the current container or a
  471        * parent container.
  472        * 
  473        * Note that this queries the current state of the document. When the 
  474        * document is persisted, the saving mechanism may synthesize namespaces 
  475        * (ns1, ns2, and so on) for the purposes of persistence. These namepaces are 
  476        * only present in the serialized form, and are not reflected back into 
  477        * the document being saved.
  478        * 
  479        * @param  namespaceURI  The namespace URI corresponding to the requested
  480        * prefix.
  481        * @return  The prefix corresponding to the specified URI if it exists; 
  482        * otherwise, a newly generated prefix.
  483        */
  484       String prefixForNamespace ( String namespaceURI );
  485       
  486       /**
  487        * Adds to the specified map, all the namespaces in scope at the container
  488        * where this cursor is positioned. This method is useful for 
  489        * container tokens only.
  490        * 
  491        * @param  addToThis  The Map to add the namespaces to.
  492        */
  493   
  494       void getAllNamespaces ( Map addToThis );
  495   
  496       /**
  497        * Returns the strongly-typed XmlObject at the current START,
  498        * STARTDOC, or ATTR. <br/><br/>
  499        * 
  500        * The strongly-typed object can be cast to the strongly-typed
  501        * XBean interface corresponding to the XML Schema Type given
  502        * by result.getSchemaType().<br/><br/>
  503        *
  504        * If a more specific type cannot be determined, an XmlObject
  505        * whose schema type is anyType will be returned.
  506        * 
  507        * @return  The strongly-typed object at the cursor's current location;
  508        * null if the current location is not a START, STARTDOC, or ATTR.
  509        */
  510   
  511       XmlObject getObject ( );
  512       
  513       /**
  514        * Returns the type of the current token. By definition, the current
  515        * token is the token immediately to the right of the cursor. 
  516        * If you're in the middle of text, before a character, you get TEXT.
  517        * You can't dive into the text of an ATTR, COMMENT or PROCINST.<br/><br/>
  518        * 
  519        * As an alternative, it may be more convenient for you to use one of the 
  520        * methods that test for a particular token type. These include the methods 
  521        * isStart(), isStartdoc(), isText(), isAttr(), and so on. Each returns a boolean 
  522        * value indicating whether the token that follows the cursor is the type 
  523        * in question. 
  524        * <br/><br/>
  525        *
  526        * @return  The TokenType instance for the token at the cursor's current
  527        * location.
  528        */
  529   
  530       TokenType currentTokenType ( );
  531       
  532       /**
  533        * True if the current token is a STARTDOC token type, meaning 
  534        * at the very root of the document.
  535        * 
  536        * @return  true if this token is a STARTDOC token type; 
  537        * otherwise, false.
  538        */
  539   
  540       boolean isStartdoc ( );
  541       
  542       /**
  543        * True if this token is an ENDDOC token type, meaning 
  544        * at the very end of the document.
  545        * 
  546        * @return  true if this token is an ENDDOC token type; 
  547        * otherwise, false.
  548        */
  549   
  550       boolean isEnddoc ( );
  551       
  552       /**
  553        * True if this token is a START token type, meaning 
  554        * just before an element's start.
  555        * 
  556        * @return  true if this token is a START token type; 
  557        * otherwise, false.
  558        */
  559   
  560       boolean isStart ( );
  561       
  562       /**
  563        * True if this token is an END token type, meaning 
  564        * just before an element's end.
  565        * 
  566        * @return  true if this token is an END token type; 
  567        * otherwise, false.
  568        */
  569   
  570       boolean isEnd ( );
  571       
  572       /**
  573        * True if the this token is a TEXT token type, meaning 
  574        * just before or inside text.
  575        * 
  576        * @return  true if this token is a TEXT token type; 
  577        * otherwise, false.
  578        */
  579   
  580       boolean isText ( );
  581       
  582       /**
  583        * True if this token is an ATTR token type, meaning 
  584        * just before an attribute.
  585        * 
  586        * @return  true if this token is an ATTR token type; 
  587        * otherwise, false.
  588        */
  589   
  590       boolean isAttr ( );
  591       
  592       /**
  593        * True if this token is a NAMESPACE token type, meaning 
  594        * just before a namespace declaration.
  595        * 
  596        * @return  true if this token is a NAMESPACE token type; 
  597        * otherwise, false.
  598        */
  599   
  600       boolean isNamespace ( );
  601       
  602       /**
  603        * True if this token is a COMMENT token type, meaning 
  604        * just before a comment.
  605        * 
  606        * @return  true if this token is a COMMENT token type; 
  607        * otherwise, false.
  608        */
  609   
  610       boolean isComment ( );
  611       
  612       /**
  613        * True if this token is a PROCINST token type, meaning 
  614        * just before a processing instruction.
  615        * 
  616        * @return  true if this token is a PROCINST token type; 
  617        * otherwise, false.
  618        */
  619   
  620       boolean isProcinst ( );
  621       
  622       /**
  623        * True if this token is a container token. The STARTDOC and START 
  624        * token types are containers. Containers, including documents and elements,
  625        * have the same content model. In other words, a document and an element 
  626        * may have the same contents. For example, a document may contain attributes 
  627        * or text, without any child elements.
  628        * 
  629        * @return  true if this token is a container token; otherwise, false.
  630        */
  631   
  632       boolean isContainer ( );
  633       
  634       /**
  635        * True if this token is a finish token. A finish token can be an ENDDOC
  636        * or END token type.
  637   
  638        * @return  true if this token is a finish token; otherwise, false.
  639        */
  640   
  641       boolean isFinish ( );
  642       
  643       /**
  644        * True if this token is any attribute. This includes an ATTR token type and
  645        * the NAMESPACE token type attribute.
  646        * 
  647        * @return  true if the current cursor is at any attribute; otherwise, false.
  648        */
  649   
  650       boolean isAnyAttr ( );
  651       
  652       /**
  653        * Returns the type of the previous token. By definition, the previous
  654        * token is the token immediately to the left of the cursor.<br/><br/>
  655        *
  656        * If you're in the middle of text, after a character, you get TEXT.
  657        * 
  658        * @return  The TokenType instance for the token immediately before the 
  659        * token at the cursor's current location.
  660        */
  661   
  662       TokenType prevTokenType ( );
  663       
  664       /**
  665        * True if there is a next token. When this is false, as when the cursor is
  666        * at the ENDDOC token, the toNextToken() method returns NONE and does not 
  667        * move the cursor.
  668        * 
  669        * @return  true if there is a next token; otherwise, false.
  670        */
  671   
  672       boolean hasNextToken ( );
  673   
  674   
  675       /**
  676        * True if there is a previous token. When this is false, toPrevToken
  677        * returns NONE and does not move the cursor.
  678        * 
  679        * @return  true if there is a previous token; otherwise, false.
  680        */
  681   
  682       boolean hasPrevToken ( );
  683       
  684       /**
  685        * Moves the cursor to the next token. When there are no more tokens 
  686        * available, hasNextToken returns false and toNextToken() returns 
  687        * NONE and does not move the cursor. Returns the token type 
  688        * of the token to the right of the cursor upon a successful move.
  689        * 
  690        * @return  The token type for the next token if the cursor was moved;
  691        * otherwise, NONE.
  692        */
  693   
  694       TokenType toNextToken ( );
  695   
  696       /**
  697        * Moves the cursor to the previous token. When there is no
  698        * previous token, returns NONE, otherwise returns the token
  699        * to the left of the new position of the cursor.
  700        * 
  701        * @return  The token type for the previous token if the cursor was moved;
  702        * otherwise, NONE.
  703        */
  704   
  705       TokenType toPrevToken ( );
  706       
  707       /**
  708        * Moves the cursor to the first token in the content of the current
  709        * START or STARTDOC. That is, the first token after all ATTR and NAMESPACE
  710        * tokens associated with this START.<br/><br/>
  711        *
  712        * If the current token is not a START or STARTDOC, the cursor is not
  713        * moved and NONE is returned. If the current START or STARTDOC
  714        * has no content, the cursor is moved to the END or ENDDOC token.<br/><br/>
  715        * 
  716        * @return  The new current token type.
  717        */
  718   
  719       TokenType toFirstContentToken ( );
  720   
  721   
  722       /**
  723        * Moves the cursor to the END or ENDDOC token corresponding to the
  724        * current START or STARTDOC, and returns END or ENDDOC. <br/><br/>
  725        *
  726        * If the current token is not a START or STARTDOC, the cursor is not
  727        * moved and NONE is returned.
  728        * 
  729        * @return  The new current token type.
  730        */
  731   
  732       TokenType toEndToken ( );
  733       
  734       /**
  735        * Moves the cursor forward by the specified number of characters, and
  736        * stops at the next non-TEXT token. Returns the number of characters
  737        * actually moved across, which is guaranteed to be less than or equal to  
  738        * <em>maxCharacterCount</em>. If there is no further text, or if 
  739        * there is no text at all, returns zero.<br/><br/>
  740        *
  741        * Note this does not dive into attribute values, comment contents,
  742        * processing instruction contents, etc., but only content text.<br/><br/>
  743        *
  744        * You can pass maxCharacterCount &lt; 0 to move over all the text to the 
  745        * right. This has the same effect as toNextToken, but returns the amount 
  746        * of text moved over.
  747        *
  748        * @param  maxCharacterCount  The maximum number of characters by which
  749        * the cursor should be moved.
  750        * @return  The actual number of characters by which the cursor was moved; 
  751        * 0 if the cursor was not moved.
  752        */
  753   
  754       int toNextChar ( int maxCharacterCount );
  755       
  756       /**
  757        * Moves the cursor backwards by the number of characters given.  Has
  758        * similar characteristics to the {@link #toNextChar(int) toNextChar} method.
  759        * 
  760        * @param  maxCharacterCount  The maximum number of characters by which
  761        * the cursor should be moved.
  762        * @return  The actual number of characters by which the cursor was moved; 
  763        * 0 if the cursor was not moved.
  764        */
  765   
  766       int toPrevChar ( int maxCharacterCount );
  767   
  768       /**
  769        * Moves the cursor to the next sibling element, or returns
  770        * false and does not move the cursor if there is no next sibling
  771        * element. (By definition the position of an element is the same
  772        * as the position of its START token.)
  773        *
  774        * If the current token is not s START, the cursor will be 
  775        * moved to the next START without moving out of the scope of the 
  776        * current element.
  777        * 
  778        * @return  true if the cursor was moved; otherwise, false.
  779        */
  780   
  781       boolean toNextSibling ( );
  782       
  783       /**
  784        * Moves the cursor to the previous sibling element, or returns
  785        * false and does not move the cursor if there is no previous sibling
  786        * element. (By definition the position of an element is the same
  787        * as the position of its START token.)
  788        * 
  789        * @return  true if the cursor was moved; otherwise, false.
  790        */
  791   
  792       boolean toPrevSibling ( );
  793   
  794       /**
  795        * Moves the cursor to the parent element or STARTDOC, or returns
  796        * false and does not move the cursor if there is no parent.<br/><br/>
  797        *
  798        * Works if you're in attributes or content. Returns false only if at
  799        * STARTDOC. Note that the parent of an END token is the corresponding
  800        * START token.
  801        * 
  802        * @return  true if the cursor was moved; false if the cursor is at the STARTDOC
  803        * token.
  804        */
  805   
  806       boolean toParent ( );
  807   
  808       /**
  809        * Moves the cursor to the first child element, or returns false and
  810        * does not move the cursor if there are no element children. <br/><br/>
  811        *
  812        * If the cursor is not currently in an element, it moves into the 
  813        * first child element of the next element.
  814        * 
  815        * @return  true if the cursor was moved; otherwise, false.
  816        */
  817   
  818       boolean toFirstChild ( );
  819       
  820       /**
  821        * Moves the cursor to the last element child, or returns false and
  822        * does not move the cursor if there are no element children.
  823        * 
  824        * @return  true if the cursor was moved; otherwise, false.
  825        */
  826   
  827       boolean toLastChild ( );
  828       
  829       /**
  830        * Moves the cursor to the first child element of the specified name in 
  831        * no namespace.
  832        * 
  833        * @param  name  The name of the element to move the cursor to.
  834        * @return  true if the cursor was moved; otherwise, false.
  835        */
  836   
  837       boolean toChild ( String name );
  838       
  839       /**
  840        * Moves the cursor to the first child element of the specified name in the 
  841        * specified namespace.
  842        * 
  843        * @param  namespace  The namespace URI for the element to move the cursor 
  844        * to.
  845        * @param  name  The name of the element to move to.
  846        * @return  true if the cursor was moved; otherwise, false.
  847        * @throws  IllegalArgumentException  If the name is not a valid local name.
  848        */
  849   
  850       boolean toChild ( String namespace, String name );
  851   
  852       /**
  853        * Moves the cursor to the first child element of the specified qualified name.
  854        * 
  855        * @param  name  The name of the element to move the cursor to.
  856        */
  857   
  858       boolean toChild ( QName name );
  859   
  860       /**
  861        * Moves the cursor to the child element specified by <em>index</em>.
  862        * 
  863        * @param  index  The position of the element in the sequence of child 
  864        * elements.
  865        * @return  true if the cursor was moved; otherwise, false.
  866        */
  867   
  868       boolean toChild ( int index );
  869       
  870       /**
  871        * Moves the cursor to the specified <em>index</em> child element of the 
  872        * specified name, where that element is the .
  873        * 
  874        * @param  name  The name of the child element to move the cursor to.
  875        * @param  index  The position of the element in the sequence of child
  876        * elements.
  877        * @return  true if the cursor was moved; otherwise, false.
  878        */
  879   
  880       boolean toChild ( QName name, int index );
  881       
  882       /**
  883        * Moves the cursor to the next sibling element of the specified name in no
  884        * namespace.
  885        * 
  886        * @param  name  The name of the element to move the cursor to.
  887        * @return  true if the cursor was moved; otherwise, false.
  888        */
  889   
  890       boolean toNextSibling ( String name );
  891       
  892       /**
  893        * Moves the cursor to the next sibling element of the specified name 
  894        * in the specified namespace.
  895        * 
  896        * @param  namespace  The namespace URI for the element to move the cursor
  897        * to.
  898        * @param  name  The name of the element to move the cursor to.
  899        * @return  true if the cursor was moved; otherwise, false.
  900        */
  901   
  902       boolean toNextSibling ( String namespace, String name );
  903   
  904       
  905       /**
  906        * Moves the cursor to the next sibling element of the specified 
  907        * qualified name.
  908        * 
  909        * @param  name  The name of the element to move the cursor to.
  910        * @return  true if the cursor was moved; otherwise, false.
  911        */
  912   
  913       boolean toNextSibling ( QName name );
  914   
  915       /**
  916        * Moves the cursor to the first attribute of this element, or
  917        * returns false and does not move the cursor if there are no
  918        * attributes. The order of attributes is arbitrary, but stable.<br/><br/>
  919        *
  920        * If the cursor is on a STARTDOC of a document-fragment, this method will
  921        * move it to the first top level attribute if one exists.<br></br>
  922        *
  923        * xmlns attributes (namespace declarations) are not considered 
  924        * attributes by this function.<br/><br/>
  925        *
  926        * The cursor must be on a START or STARTDOC (in the case of a
  927        * document fragment with top level attributes) for this method to
  928        * succeed.
  929        *
  930        * Example for looping through attributes:
  931        * <pre>
  932        *      XmlCursor cursor = ... //cursor on START or STARTDOC
  933        *      if (cursor.toFirstAttribute())
  934        *      {
  935        *          do
  936        *          {
  937        *              // do something using attribute's name and value
  938        *              cursor.getName();
  939        *              cursor.getTextValue();
  940        *          }
  941        *          while (cursor.toNextAttribute());
  942        *      }
  943        * </pre>
  944        * 
  945        * @return  true if the cursor was moved; otherwise, false.
  946        */
  947   
  948       boolean toFirstAttribute ( );
  949       
  950       /**
  951        * Moves the cursor to the last attribute of this element, or
  952        * returns false and does not move the cursor if there are no
  953        * attributes. The order of attributes is arbitrary, but stable.<br/><br/>
  954        *
  955        * xmlns attributes (namespace declarations) are not considered 
  956        * attributes by this function.<br/><br/>
  957        *
  958        * The cursor must be on a START or STARTDOC for this method
  959        * to succeed.
  960        * 
  961        * @return  true if the cursor was moved; otherwise, false.
  962        */
  963   
  964       boolean toLastAttribute ( );
  965   
  966       /**
  967        * Moves the cursor to the next sibling attribute, or returns
  968        * false and does not move the cursor if there is no next
  969        * sibling attribute. The order of attributes is arbitrary, but stable.<br/><br/>
  970        * 
  971        * xmlns attributes (namespace declarations) are not considered 
  972        * attributes by this function.<br/><br/>
  973        *
  974        * The cursor must be on an attribute for this method to succeed.
  975        * @see #toFirstAttribute()
  976        *
  977        * @return  true if the cursor was moved; otherwise, false.
  978        */
  979   
  980       boolean toNextAttribute ( );
  981   
  982       /**
  983        * Moves the cursor to the previous sibling attribute, or returns
  984        * false and does not move the cursor if there is no previous
  985        * sibling attribute. The order of attributes is arbitrary, but stable.<br/><br/>
  986        * 
  987        * xmlns attributes (namespace declarations) are not considered 
  988        * attributes by this function.<br/><br/>
  989        *
  990        * The cursor must be on an attribute for this method to succeed.
  991        * 
  992        * @return  true if the cursor was moved; otherwise, false.
  993        */
  994   
  995       boolean toPrevAttribute ( );
  996       
  997       /**
  998        * When at a START or STARTDOC, returns the attribute text for the given
  999        * attribute. When not at a START or STARTDOC or the attribute does not
 1000        * exist, returns null.  
 1001        * 
 1002        * @param  attrName  The name of the attribute whose value is requested.
 1003        * @return  The attribute's value if it has one; otherwise, null.
 1004        */
 1005   
 1006       String getAttributeText ( QName attrName );
 1007       
 1008       /**
 1009        * When at a START or STARTDOC, sets the attribute text for the given
 1010        * attribute. When not at a START or STARTDOC returns false.
 1011        * If the attribute does not exist, one is created.
 1012        * 
 1013        * @param  attrName  The name of the attribute whose value is being set.
 1014        * @param  value  The new value for the attribute.
 1015        * @return  true if the new value was set; otherwise, false.
 1016        */
 1017   
 1018       boolean setAttributeText ( QName attrName, String value );
 1019     
 1020       /**
 1021        * When at a START or STARTDOC, removes the attribute with the given name.
 1022        * 
 1023        * @param  attrName  The name of the attribute that should be removed.
 1024        * @return  true if the attribute was removed; otherwise, false.
 1025        */
 1026   
 1027       boolean removeAttribute ( QName attrName );
 1028   
 1029       /**
 1030        * Gets the text value of the current document, element, attribute,
 1031        * comment, procinst or text token. <br/><br/>
 1032        *
 1033        * When getting the text value of an element, non-text content such
 1034        * as comments and processing instructions are ignored and text is concatenated.
 1035        * For elements that have nested element children, this
 1036        * returns the concatenated text of all mixed content and the
 1037        * text of all the element children, recursing in first-to-last
 1038        * depthfirst order.<br/><br/>
 1039        *
 1040        * For attributes, including namespaces, this returns the attribute value.<br/><br/>
 1041        *
 1042        * For comments and processing instructions, this returns the text content 
 1043        * of the comment or PI, not including the delimiting sequences &lt;!-- --&gt;, &lt;? ?&gt;.
 1044        * For a PI, the name of the PI is also not included.
 1045        *<br/><br/>
 1046        * The value of an empty tag is the empty string.<br/><br/>
 1047        *
 1048        * If the current token is END or ENDDOC, this throws an {@link java.lang.IllegalStateException}.<br/><br/>     
 1049        * 
 1050        * @return  The text value of the current token if the token's type is
 1051        * START, STARTDOC, TEXT, ATTR, COMMENT, PROCINST, or NAMESPACE; null 
 1052        * if the type is NONE.
 1053        */
 1054   
 1055       String getTextValue ( );
 1056       
 1057       /**
 1058        * Copies the text value of the current document, element, attribute,
 1059        * comment, processing instruction or text token, counting right from 
 1060        * this cursor's location up to <em>maxCharacterCount</em>,
 1061        * and copies the returned text into <em>returnedChars</em>. <br/><br/>
 1062        * 
 1063        * When getting the text value of an element, non-text content such
 1064        * as comments and processing instructions are ignored and text is concatenated.
 1065        * For elements that have nested element children, this
 1066        * returns the concatenated text of all mixed content and the
 1067        * text of all the element children, recursing in first-to-last
 1068        * depthfirst order.<br/><br/>
 1069        *
 1070        * For attributes, including namespaces, this returns the attribute value.<br/><br/>
 1071        *
 1072        * For comments and processing instructions, this returns the text contents 
 1073        * of the comment or PI, not including the delimiting sequences &lt;!-- --&gt;, &lt;? ?&gt;. For
 1074        * a PI, the text will not include the name of the PI.<br/><br/>
 1075        * 
 1076        * If the current token is END or ENDDOC, this throws an {@link java.lang.IllegalStateException}.<br/><br/>
 1077        *
 1078        * The value of an empty tag is the empty string.<br/><br/>
 1079        * 
 1080        * @param  returnedChars  A character array to hold the returned characters.
 1081        * @param  offset  The position within returnedChars to which the first of the 
 1082        * returned characters should be copied.
 1083        * @param  maxCharacterCount  The maximum number of characters after this cursor's 
 1084        * location to copy. A negative value specifies that all characters should be copied.
 1085        * @return  The actual number of characters copied; 0 if no characters 
 1086        * were copied.
 1087        */
 1088   
 1089       int getTextValue ( char[] returnedChars, int offset, int maxCharacterCount );
 1090       
 1091       /**
 1092        * Returns the characters of the current TEXT token.  If the current token
 1093        * is not TEXT, returns "".  If in the middle of a TEXT token, returns
 1094        * those chars to the right of the cursor of the TEXT token.
 1095        * 
 1096        * @return  The requested text; an empty string if the current token type is
 1097        * not TEXT.
 1098        */
 1099   
 1100       /**
 1101        * Sets the text value of the XML at this cursor's location if that XML's
 1102        * token type is START, STARTDOC, ATTR, COMMENT or PROCINST. <br/><br/>
 1103        *
 1104        * For elements that have nested children this first removes all
 1105        * the content of the element and replaces it with the given text.
 1106        * 
 1107        * @param  text  The text to use as a new value.
 1108        * @throws  java.lang.IllegalStateException  If the token type at this
 1109        * cursor's location is not START, STARTDOC, ATTR, COMMENT or
 1110        * PROCINST.
 1111        */
 1112       void setTextValue ( String text );
 1113       
 1114       /**
 1115        * Sets the text value of the XML at this cursor's location (if that XML's
 1116        * token type is START, STARTDOC, ATTR, COMMENT or PROCINST) to the 
 1117        * contents of the specified character array. <br/><br/>
 1118        *
 1119        * For elements that have nested children this first removes all
 1120        * the content of the element and replaces it with the given text.
 1121        * 
 1122        * @param  sourceChars  A character array containing the XML's new value.
 1123        * @param  offset  The position within sourceChars from which the first of 
 1124        * the source characters should be copied.
 1125        * @param  length  The maximum number of characters to set as the XML's new
 1126        * value.
 1127        * @throws  java.lang.IllegalArgumentException  If the token type at this
 1128        * cursor's location is not START, STARTDOC, ATTR, COMMENT or
 1129        * PROCINST.
 1130        */
 1131       void setTextValue ( char[] sourceChars, int offset, int length );
 1132   
 1133       /**
 1134        * Returns characters to the right of the cursor up to the next token.
 1135        */
 1136       String getChars ( );
 1137       
 1138       /**
 1139        * Copies characters up to the specified maximum number, counting right from 
 1140        * this cursor's location to the character at <em>maxCharacterCount</em>.  The 
 1141        * returned characters are added to <em>returnedChars</em>, with the first
 1142        * character copied to the <em>offset</em> position. The <em>maxCharacterCount</em> 
 1143        * parameter should be less than or equal to the length of <em>returnedChars</em> 
 1144        * minus <em>offset</em>. Copies a number of characters, which is 
 1145        * either <em>maxCharacterCount</em> or the number of characters up to the next token, 
 1146        * whichever is less.
 1147        * 
 1148        * @param  returnedChars  A character array to hold the returned characters.
 1149        * @param  offset  The position within returnedChars at which the first of the 
 1150        * returned characters should be added.
 1151        * @param  maxCharacterCount  The maximum number of characters after this cursor's 
 1152        * location to return.
 1153        * @return  The actual number of characters returned; 0 if no characters 
 1154        * were returned or if the current token is not TEXT. 
 1155        */
 1156   
 1157       int getChars ( char[] returnedChars, int offset, int maxCharacterCount );
 1158       
 1159       /**
 1160        * Moves the cursor to the STARTDOC token, which is the 
 1161        * root of the document.
 1162        */
 1163   
 1164       void toStartDoc ( );
 1165       
 1166       /**
 1167        * Moves the cursor to the ENDDOC token, which is the end
 1168        * of the document.
 1169        */
 1170   
 1171       void toEndDoc ( );
 1172       
 1173       /**
 1174        * Determines if the specified cursor is in the same document as
 1175        * this cursor.
 1176        * 
 1177        * @param  cursor  The cursor that may be in the same document
 1178        * as this cursor.
 1179        * @return  true if the specified cursor is in the same document;
 1180        * otherwise, false.
 1181        */
 1182   
 1183       boolean isInSameDocument ( XmlCursor cursor );
 1184   
 1185       /**
 1186        * Returns an integer indicating whether this cursor is before, 
 1187        * after, or at the same position as the specified cursor. <br/><br/>
 1188        * 
 1189        * <code>a.comparePosition(b) < 0</code> means a is to the left of b.<br/>
 1190        * <code>a.comparePosition(b) == 0</code> means a is at the same position as b.<br/>
 1191        * <code>a.comparePosition(b) > 0</code> means a is to the right of b.<br/><br/>
 1192        *
 1193        * The sort order of cursors in the document is the token order.
 1194        * For example, if cursor "a" is at a START token and the cursor "b"
 1195        * is at a token within the contents of the same element, then
 1196        * a.comparePosition(b) will return -1, meaning that the position
 1197        * of a is before b.
 1198        * 
 1199        * @param  cursor  The cursor whose position should be compared
 1200        * with this cursor.
 1201        * @return  1 if this cursor is after the specified cursor; 0 if 
 1202        * this cursor is at the same position as the specified cursor; 
 1203        * -1 if this cursor is before the specified cursor.
 1204        * @throws  java.lang.IllegalArgumentException  If the specified
 1205        * cursor is not in the same document as this cursor.
 1206        */
 1207   
 1208       int comparePosition ( XmlCursor cursor );
 1209       
 1210       /**
 1211        * Determines if this cursor is to the left of (or before)
 1212        * the specified cursor. Note that this is the same as 
 1213        * <code>a.comparePosition(b) &lt; 0 </code>
 1214        * 
 1215        * @param  cursor  The cursor whose position should be compared
 1216        * with this cursor.
 1217        * @return  true if this cursor is to the left of the specified
 1218        * cursor; otherwise, false.
 1219        */
 1220   
 1221       boolean isLeftOf ( XmlCursor cursor );
 1222       
 1223       /**
 1224        * Determines if this cursor is at the same position as
 1225        * the specified cursor. Note that this is the same as 
 1226        * <code>a.comparePosition(b) == 0 </code>
 1227        * 
 1228        * @param  cursor  The cursor whose position should be compared
 1229        * with this cursor.
 1230        * @return  true if this cursor is at the same position as 
 1231        * the specified cursor; otherwise, false.
 1232        */
 1233   
 1234       boolean isAtSamePositionAs ( XmlCursor cursor );
 1235       
 1236       /**
 1237        * Determines if this cursor is to the right of (or after)
 1238        * the specified cursor. Note that this is the same as 
 1239        * <code>a.comparePosition(b) &gt; 0 </code>
 1240        * 
 1241        * @param  cursor  The cursor whose position should be compared
 1242        * with this cursor.
 1243        * @return  true if this cursor is to the right of the specified
 1244        * cursor; otherwise, false.
 1245        */
 1246   
 1247       boolean isRightOf ( XmlCursor cursor );
 1248       
 1249       /**
 1250        * Executes the specified XQuery expression against the XML this
 1251        * cursor is in. <br/><br/>
 1252        * 
 1253        * The query may be a String or a compiled query. You can precompile
 1254        * an XQuery expression using the XmlBeans.compileQuery method. <br/><br>
 1255        * 
 1256        * The root referred to by the expression should be given as 
 1257        * a dot. The following is an example path expression:
 1258        * <pre>
 1259        * XmlCursor results = cursor.execQuery("purchase-order/line-item[price &lt;= 20.00]");
 1260        * </pre>
 1261        * 
 1262        * @param  query  The XQuery expression to execute.
 1263        * @return  A cursor containing the results of the query.
 1264        * @throws  XmlRuntimeException  If the query expression is invalid.
 1265        */
 1266   
 1267       XmlCursor execQuery ( String query );
 1268       
 1269       /**
 1270        * Executes the specified XQuery expression against the XML this
 1271        * cursor is in, and using the specified options. <br/><br/>
 1272        * 
 1273        * @param  query  The XQuery expression to execute.
 1274        * @param  options  Options for the query. For example, you can call 
 1275        * the {@link XmlOptions#setXqueryCurrentNodeVar(String) XmlOptions.setXqueryCurrentNodeVar(String)}
 1276        * method to specify a particular name for the query expression 
 1277        * variable that indicates the context node.
 1278        * @throws  XmlRuntimeException  If the query expression is invalid.
 1279        */
 1280   
 1281       XmlCursor execQuery ( String query, XmlOptions options );
 1282       
 1283       /**
 1284        * Represents the state of a dcoument at a particular point
 1285        * in time.  It is used to determine if a document has been changed
 1286        * since that point in time.
 1287        */
 1288       interface ChangeStamp
 1289       {
 1290           /**
 1291            * Returns whether or not the document assoiated with this ChangeStamp
 1292            * has been altered since the ChangeStamp had been created.
 1293            */
 1294           public boolean hasChanged ( );
 1295       }
 1296       
 1297       /**
 1298        * Returns the current change stamp for the document the current cursor is in. 
 1299        * This change stamp can be queried at a later point in time to find out
 1300        * if the document has changed.
 1301        * 
 1302        * @return  The change stamp for the document the current cursor is in.
 1303        */
 1304       ChangeStamp getDocChangeStamp ( );
 1305       
 1306       /**
 1307        * Subclasses of XmlBookmark can be used to annotate an XML document.
 1308        * This class is abstract to prevent parties from inadvertently 
 1309        * interfering with each others' bookmarks without explicitly
 1310        * sharing a bookmark class.
 1311        */
 1312   
 1313       abstract class XmlBookmark
 1314       {
 1315           /**
 1316            * Constructs a strongly-referenced bookmark.
 1317            */ 
 1318           public XmlBookmark ( ) { this( false ); }
 1319           
 1320           /**
 1321            * Constructs a bookmark.
 1322            * @param weak true if the document's reference to the bookmark should be a WeakReference
 1323            */ 
 1324           public XmlBookmark ( boolean weak )
 1325           {
 1326               _ref = weak ? new WeakReference( this ) : null;
 1327           }
 1328           
 1329           /**
 1330            * Call the createCursor method to create a new cursor which is
 1331            * positioned at the same splace as the bookmark.  It is much more
 1332            * efficient to call toBookmark on an existing cursor than it
 1333            * is to create a new cursor.  However, toBookmark may fail if the
 1334            * bookmark is in a different document than the cursor.  It is
 1335            * under these circumstances where createCursor needs to be called
 1336            * on the bookmark.  Subsequent navigations to bookmark
 1337            * positions should attempt to reuse the last cursor to
 1338            * improve performace.
 1339            */
 1340           public final XmlCursor createCursor ( )
 1341           {
 1342               return _currentMark == null ? null : _currentMark.createCursor();
 1343           }
 1344   
 1345           /**
 1346            * Moves the given cursor to this bookmark, and returns it.
 1347            */ 
 1348           public final XmlCursor toBookmark ( XmlCursor c )
 1349           {
 1350               return c == null || !c.toBookmark( this ) ? createCursor() : c;
 1351           }
 1352   
 1353           /**
 1354            * The default key for bookmarks is the class which implements
 1355            * them.  This way, multiple parties using bookmarks in the
 1356            * same instance document will not interfere with eachother.
 1357            * One can, however, override getKey() to use a key other than
 1358            * the class.
 1359            */
 1360           public Object getKey ( )
 1361           {
 1362               return this.getClass();
 1363           }
 1364           
 1365           /**
 1366            * The mark is set by the host document; it is capable of
 1367            * returning an XmlCursor implementation at the location of
 1368            * the bookmark.
 1369            */ 
 1370           public       XmlMark   _currentMark;
 1371           
 1372           /**
 1373            * If non-null, the ref is used by the host document
 1374            * to maintain a reference to the bookmark.  If it is a weak
 1375            * reference, the host document will not prevent the Bookmark
 1376            * from being garbage collected.
 1377            */ 
 1378           public final Reference _ref;
 1379       }
 1380   
 1381       /**
 1382        * An abstract {@link XmlCursor} factory.
 1383        * Implementations of XmlCursor implement XmlMark to be able to
 1384        * reconstitute a cursor from a bookmark. When content moves between
 1385        * implementations, the XmlMark is set to the implmentation's which
 1386        * recieves the new content.
 1387        */
 1388   
 1389       interface XmlMark
 1390       {
 1391           XmlCursor createCursor ( );
 1392       }
 1393   
 1394       /**
 1395        * Sets a bookmark to the document at this cursor's location.
 1396        *
 1397        * The bookmark is attached to the token in the tree immediately 
 1398        * after the cursor. If the tree is manipulated to move
 1399        * that object to a different place, the bookmark moves with it.
 1400        * If the tree is manipulated to delete that token from the
 1401        * tree, the bookmark is orphaned. Copy operations do not copy
 1402        * bookmarks.
 1403        * 
 1404        * @param  bookmark  The bookmark to set.
 1405        */
 1406   
 1407       void setBookmark ( XmlBookmark bookmark );
 1408       
 1409       /**
 1410        * Retrieves the bookmark with the specified key 
 1411        * at this cursor's location. If there is no bookmark whose key is 
 1412        * given by the specified key at the current position, null is returned. 
 1413        * If the {@link XmlCursor.XmlBookmark#getKey() getKey} method is not overridden on 
 1414        * the bookmark, then the bookmark's class is used as the key.
 1415        * 
 1416        * @param  key  The key for the bookmark to retrieve.
 1417        * @return  The requested bookmark; null if there is no bookmark
 1418        * corresponding to the specified key.
 1419        */
 1420   
 1421       XmlBookmark getBookmark ( Object key );
 1422       
 1423       /**
 1424        * Clears the bookmark whose key is specified, if the bookmark
 1425        * exists at this cursor's location.
 1426        * 
 1427        * @param  key  The for the bookmark to clear.
 1428        */
 1429   
 1430       void clearBookmark ( Object key );
 1431   
 1432       /**
 1433        * Retrieves all the bookmarks at this location, adding them to
 1434        * the specified collection. Bookmarks held by weak references are
 1435        * added to this collection as Weak referenced objects pointing to the
 1436        * bookmark.
 1437        * 
 1438        * @param  listToFill  The collection that will contain bookmarks
 1439        * returned by this method.
 1440        */
 1441   
 1442       void getAllBookmarkRefs ( Collection listToFill );
 1443   
 1444       /**
 1445        * Removes the XML that is immediately after this cursor.
 1446        * 
 1447        * For the TEXT, ATTR, NAMESPACE, COMMENT and PROCINST tokens, a single 
 1448        * token is removed. For a START token, the corresponding element and all 
 1449        * of its contents are removed. For all other tokens, this is a no-op. 
 1450        * You cannot remove a STARTDOC.
 1451        * 
 1452        * The cursors located in the XML that was removed all collapse to the 
 1453        * same location. All bookmarks in this XML will be orphaned.
 1454        * 
 1455        * @return true if anything was removed; false only if the cursor is 
 1456        * just before END or ENDDOC token.
 1457        * @throws java.lang.IllegalArgumentException  If the cursor is at a 
 1458        * STARTDOC token.
 1459        */
 1460   
 1461       boolean removeXml ( );
 1462   
 1463       /**
 1464        * Moves the XML immediately after this cursor to the location
 1465        * specified by the <em>toHere</em> cursor, shifting XML at that location 
 1466        * to the right to make room. For the TEXT, ATTR, NAMESPACE, 
 1467        * COMMENT and PROCINST tokens, a single token is moved. For a start token, the
 1468        * element and all of its contents are moved. For all other tokens, this
 1469        * is a no-op.
 1470        * 
 1471        * The bookmarks located in the XML that was moved also move to the
 1472        * new location; the cursors don't move with the content.
 1473        * 
 1474        * @param  toHere  The cursor at the location to which the XML should
 1475        * be moved.
 1476        * @return true if anything was moved.  This only happens when the XML to be
 1477        * moved contains the target of the move.
 1478        * @throws java.lang.IllegalArgumentException  If the operation is not allowed
 1479        * at the cursor's location.  This includes attempting to move an end token or the
 1480        * document as a whole.  Also, moving to a location before the start document or moving
 1481        * an attribute to a location other than after another attribute or start token
 1482        * will throw.
 1483        */
 1484   
 1485       boolean moveXml ( XmlCursor toHere );
 1486       
 1487       /**
 1488        * Copies the XML immediately after this cursor to the location
 1489        * specified by the <em>toHere</em> cursor. For the TEXT, ATTR, NAMESPACE, 
 1490        * COMMENT and PROCINST tokens, a single token is copied.  For a start token, 
 1491        * the element and all of its contents are copied. For all other tokens, this
 1492        * is a no-op.
 1493        * 
 1494        * The cursors and bookmarks located in the XML that was copied are also copied 
 1495        * to the new location.
 1496        * 
 1497        * @param  toHere  The cursor at the location to which the XML should
 1498        * be copied.
 1499        * @return true if anything was copied; false if the token supports the operation,
 1500        * but nothing was copied.
 1501        * @throws java.lang.IllegalArgumentException  If the operation is not allowed
 1502        * at the cursor's location.
 1503        */
 1504   
 1505       boolean copyXml ( XmlCursor toHere );
 1506       
 1507       /**
 1508        * Removes the contents of the container (STARTDOC OR START) immediately after
 1509        * this cursor. For all other situations, returns false. Does
 1510        * not remove attributes or namspaces.
 1511        * 
 1512        * @return true if anything was copied; otherwise, false.
 1513        */
 1514   
 1515       boolean removeXmlContents ( );
 1516   
 1517       /**
 1518        * Moves the contents of the container (STARTDOC OR START) immediately after
 1519        * this cursor to the location specified by the <em>toHere</em> cursor.
 1520        * For all other situations, returns false. Does not move attributes or
 1521        * namespaces.
 1522        * 
 1523        * @param  toHere  The cursor at the location to which the XML should be moved.
 1524        * @return true if anything was moved; otherwise, false.
 1525        */
 1526       boolean moveXmlContents ( XmlCursor toHere );
 1527       
 1528       /**
 1529        * Copies the contents of the container (STARTDOC OR START) immediately to
 1530        * the right of the cursor to the location specified by the <em>toHere</em> cursor.
 1531        * For all other situations, returns false.  Does not copy attributes or
 1532        * namespaces.
 1533        * 
 1534        * @param  toHere  The cursor at the location to which the XML should
 1535        * be copied.
 1536        * @return true if anything was copied; otherwise, false.
 1537        */
 1538       boolean copyXmlContents ( XmlCursor toHere );
 1539       
 1540       /**
 1541        * Removes characters up to the specified maximum number, counting right from 
 1542        * this cursor's location to the character at <em>maxCharacterCount</em>. The 
 1543        * space remaining from removing the characters collapses up to this cursor.
 1544        * 
 1545        * @param  maxCharacterCount  The maximum number of characters after this cursor's 
 1546        * location to remove.
 1547        * @return  The actual number of characters removed.
 1548        * @throws java.lang.IllegalArgumentException  If the operation is not allowed
 1549        * at the cursor's location.
 1550        */
 1551   
 1552       int removeChars ( int maxCharacterCount );
 1553   
 1554       /**
 1555        * Moves characters immediately after this cursor to the position immediately 
 1556        * after the specified cursor. Characters are counted to the right up to the
 1557        * specified maximum number. XML after the destination cursor is 
 1558        * shifted to the right to make room. The space remaining from moving the 
 1559        * characters collapses up to this cursor.
 1560        * 
 1561        * @param  maxCharacterCount  The maximum number of characters after this cursor's 
 1562        * location to move.
 1563        * @param  toHere  The cursor to which the characters should be moved.
 1564        * @return  The actual number of characters moved.
 1565        * @throws java.lang.IllegalArgumentException  If the operation is not allowed
 1566        * at the cursor's location.
 1567        */
 1568   
 1569       int moveChars ( int maxCharacterCount, XmlCursor toHere );
 1570   
 1571       /**
 1572        * Copies characters to the position immediately after the specified cursor.
 1573        * Characters are counted to the right up to the specified maximum number. 
 1574        * XML after the destination cursor is shifted to the right to make room.
 1575        * 
 1576        * @param  maxCharacterCount  The maximum number of characters after this cursor's 
 1577        * location to copy.
 1578        * @param  toHere  The cursor to which the characters should be copied.
 1579        * @return  The actual number of characters copied.
 1580        * @throws java.lang.IllegalArgumentException  If the operation is not allowed
 1581        * at the cursor's location.
 1582        */
 1583   
 1584       int copyChars ( int maxCharacterCount, XmlCursor toHere );
 1585   
 1586       /**
 1587        * Inserts the specified text immediately before this cursor's location.
 1588        * 
 1589        * @param  text  The text to insert.
 1590        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1591        * at the cursor's location.
 1592        */
 1593   
 1594       void insertChars ( String text );
 1595       
 1596       /**
 1597        * Inserts an element immediately before this cursor's location, giving 
 1598        * the element the specified qualified name.
 1599        * 
 1600        * @param  name  The qualified name for the element.
 1601        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1602        * at the cursor's location.
 1603        */
 1604   
 1605       void insertElement ( QName name );
 1606   
 1607       /**
 1608        * Inserts an element immediately before this cursor's location, giving 
 1609        * the element the specified local name.
 1610        * 
 1611        * @param  localName  The local name for the new element.
 1612        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1613        * at the cursor's location.
 1614        */
 1615   
 1616       void insertElement ( String localName );
 1617   
 1618       /**
 1619        * Inserts a new element immediately before this cursor's location, giving the
 1620        * element the specified local name and associating it with specified namespace 
 1621        * 
 1622        * @param  localName  The local name for the new element.
 1623        * @param  uri  The URI for the new element's namespace.
 1624        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1625        * at the cursor's location.
 1626        */
 1627   
 1628       void insertElement ( String localName, String uri );
 1629       
 1630       /**
 1631        * Inserts a new element around this cursor, giving the element the specified 
 1632        * qualified name. After the element is inserted, this cursor is between its start 
 1633        * and end. This cursor can then be used to insert additional XML into 
 1634        * the new element.
 1635        * 
 1636        * @param  name  The qualified name for the new element.
 1637        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1638        * at the cursor's location.
 1639        */
 1640   
 1641       void beginElement ( QName name );
 1642   
 1643       /**
 1644        * Inserts a new element around this cursor, giving the element the specified 
 1645        * local name. After the element is inserted, this cursor is between its start 
 1646        * and end. This cursor can then be used to insert additional XML into 
 1647        * the new element.
 1648        * 
 1649        * @param  localName  The local name for the new element.
 1650        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1651        * at the cursor's location.
 1652        */
 1653   
 1654       void beginElement ( String localName );
 1655   
 1656       /**
 1657        * Inserts a new element around this cursor, giving the element the specified 
 1658        * local name and associating it with the specified namespace. After the element 
 1659        * is inserted, this cursor is between its start and end. This cursor 
 1660        * can then be used to insert additional XML into the new element.
 1661        * 
 1662        * @param  localName  The local name for the new element.
 1663        * @param  uri  The URI for the new element's namespace.
 1664        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1665        * at the cursor's location.
 1666        */
 1667   
 1668       void beginElement ( String localName, String uri );
 1669       
 1670       /**
 1671        * Inserts a new element immediately before this cursor's location, giving the
 1672        * element the specified qualified name and content.
 1673        * 
 1674        * @param  name  The qualified name for the new element.
 1675        * @param  text  The content for the new element.
 1676        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1677        * at the cursor's location.
 1678        */
 1679   
 1680       void insertElementWithText ( QName name, String text );
 1681   
 1682       /**
 1683        * Inserts a new element immediately before this cursor's location, giving the
 1684        * element the specified local name and content.
 1685        * 
 1686        * @param  localName  The local name for the new element.
 1687        * @param  text  The content for the new element.
 1688        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1689        * at the cursor's location.
 1690        */
 1691   
 1692       void insertElementWithText ( String localName, String text );
 1693   
 1694       /**
 1695        * Inserts a new element immediately before this cursor's location, giving the
 1696        * element the specified local name, associating it with the specified namespace, 
 1697        * and giving it the specified content.
 1698        * 
 1699        * @param  localName  The local name for the new element.
 1700        * @param  uri  The URI for the new element's namespace.
 1701        * @param  text  The content for the new element.
 1702        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1703        * at the cursor's location.
 1704        */
 1705   
 1706       void insertElementWithText ( String localName, String uri, String text );
 1707       
 1708       /**
 1709        * Inserts a new attribute immediately before this cursor's location, giving it
 1710        * the specified local name.
 1711        * 
 1712        * @param  localName  The local name for the new attribute.
 1713        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1714        * at the cursor's location.
 1715        */
 1716   
 1717       void insertAttribute ( String localName );
 1718   
 1719       /**
 1720        * Inserts a new attribute immediately before this cursor's location, giving it
 1721        * the specified local name and associating it with the specified namespace.
 1722        * 
 1723        * @param  localName  The local name for the new attribute.
 1724        * @param  uri  The URI for the new attribute's namespace.
 1725        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1726        * at the cursor's location.
 1727        */
 1728   
 1729       void insertAttribute ( String localName, String uri );
 1730   
 1731       /**
 1732        * Inserts a new attribute immediately before this cursor's location, giving it
 1733        * the specified name.
 1734        * 
 1735        * @param  name  The local name for the new attribute.
 1736        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1737        * at the cursor's location.
 1738        */
 1739   
 1740       void insertAttribute ( QName name );
 1741   
 1742       /**
 1743        * Inserts a new attribute immediately before this cursor's location, giving it
 1744        * the specified value and name.
 1745        * 
 1746        * @param  Name  The local name for the new attribute.
 1747        * @param  value  The value for the new attribute.
 1748        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1749        * at the cursor's location.
 1750        */
 1751   
 1752       void insertAttributeWithValue ( String Name, String value );
 1753   
 1754       /**
 1755        * Inserts an attribute immediately before the cursor's location, giving it
 1756        * the specified name and value, and associating it with the specified namespace.
 1757        * 
 1758        * @param  name  The name for the new attribute.
 1759        * @param  uri  The URI for the new attribute's namespace.
 1760        * @param  value  The value for the new attribute.
 1761        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1762        * at the cursor's location.
 1763        */
 1764   
 1765       void insertAttributeWithValue ( String name, String uri, String value );
 1766   
 1767       /**
 1768        * Inserts an attribute immediately before the cursor's location, giving it
 1769        * the specified name and value.
 1770        * 
 1771        * @param  name  The name for the new attribute.
 1772        * @param  value  The value for the new attribute.
 1773        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1774        * at the cursor's location.
 1775        */
 1776   
 1777       void insertAttributeWithValue ( QName name, String value );
 1778       
 1779       /**
 1780        * Inserts a namespace declaration immediately before the cursor's location, 
 1781        * giving it the specified prefix and URI.
 1782        * 
 1783        * @param  prefix  The prefix for the namespace.
 1784        * @param  namespace  The URI for the namespace.
 1785        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1786        * at the cursor's location.
 1787        */
 1788   
 1789       void insertNamespace ( String prefix, String namespace );
 1790       
 1791       /**
 1792        * Inserts an XML comment immediately before the cursor's location, 
 1793        * giving it the specified content.
 1794        * 
 1795        * @param  text  The new comment's content.
 1796        * @throws java.lang.IllegalArgumentException  If the insertion is not allowed
 1797        * at the cursor's location.
 1798        */
 1799   
 1800       void insertComment ( String text );
 1801   
 1802       /**
 1803        * Inserts an XML processing instruction immediately before the cursor's location, 
 1804        * giving it the specified target and text.
 1805        * 
 1806        * @param  target  The target for the processing instruction.
 1807        * @param  text  The new processing instruction's text.
 1808        * @throws java.lang.IllegalStateException  If the insertion is not allowed
 1809        * at the cursor's location.
 1810        */
 1811   
 1812       void insertProcInst ( String target, String text );
 1813   }

Home » xmlbeans-2.5.0-src » org.apache » xmlbeans » [javadoc | source]