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 * <sample x='y'>
82 * <value>foo</value>
83 * </sample>
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 * <doc> ::= STARTDOC <attributes> <content> ENDDOC
122 * <element> ::= START <attributes> <content> END
123 * <attributes> ::= ( ATTR | NAMESPACE ) *
124 * <content> ::= ( COMMENT | PROCINST | TEXT | <element> ) *
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 < 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 <!-- -->, <? ?>.
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 <!-- -->, <? ?>. 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) < 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) > 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 <= 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 }
Save This Page