|
|||||||||||||||||||
| Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
| Element.java | - | - | - | - |
|
||||||||||||||
| 1 | /* | |
| 2 | * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved. | |
| 3 | * | |
| 4 | * This software is open source. | |
| 5 | * See the bottom of this file for the licence. | |
| 6 | */ | |
| 7 | ||
| 8 | package org.dom4j; | |
| 9 | ||
| 10 | import java.util.Iterator; | |
| 11 | import java.util.List; | |
| 12 | import java.util.Map; | |
| 13 | ||
| 14 | /** | |
| 15 | * <p> | |
| 16 | * <code>Element</code> interface defines an XML element. An element can have | |
| 17 | * declared namespaces, attributes, child nodes and textual content. | |
| 18 | * </p> | |
| 19 | * | |
| 20 | * <p> | |
| 21 | * Some of this interface is optional. Some implementations may be read-only and | |
| 22 | * not support being modified. Some implementations may not support the parent | |
| 23 | * relationship and methods such as {@link #getParent}or {@link#getDocument}. | |
| 24 | * </p> | |
| 25 | * | |
| 26 | * @author <a href="mailto:jstrachan@apache.org">James Strachan </a> | |
| 27 | * @version $Revision: 1.47 $ | |
| 28 | */ | |
| 29 | public interface Element extends Branch { | |
| 30 | // Name and namespace related methods | |
| 31 | // ------------------------------------------------------------------------- | |
| 32 | ||
| 33 | /** | |
| 34 | * <p> | |
| 35 | * Returns the <code>QName</code> of this element which represents the | |
| 36 | * local name, the qualified name and the <code>Namespace</code>. | |
| 37 | * </p> | |
| 38 | * | |
| 39 | * @return the <code>QName</code> associated with this element | |
| 40 | */ | |
| 41 | QName getQName(); | |
| 42 | ||
| 43 | /** | |
| 44 | * <p> | |
| 45 | * Sets the <code>QName</code> of this element which represents the local | |
| 46 | * name, the qualified name and the <code>Namespace</code>. | |
| 47 | * </p> | |
| 48 | * | |
| 49 | * @param qname | |
| 50 | * is the <code>QName</code> to be associated with this element | |
| 51 | */ | |
| 52 | void setQName(QName qname); | |
| 53 | ||
| 54 | /** | |
| 55 | * <p> | |
| 56 | * Returns the <code>Namespace</code> of this element if one exists | |
| 57 | * otherwise <code>Namespace.NO_NAMESPACE</code> is returned. | |
| 58 | * </p> | |
| 59 | * | |
| 60 | * @return the <code>Namespace</code> associated with this element | |
| 61 | */ | |
| 62 | Namespace getNamespace(); | |
| 63 | ||
| 64 | /** | |
| 65 | * <p> | |
| 66 | * Returns the <code>QName</code> for the given qualified name, using the | |
| 67 | * namespace URI in scope for the given prefix of the qualified name or the | |
| 68 | * default namespace if the qualified name has no prefix. | |
| 69 | * </p> | |
| 70 | * | |
| 71 | * @param qualifiedName | |
| 72 | * DOCUMENT ME! | |
| 73 | * | |
| 74 | * @return the <code>QName</code> for the given qualified name | |
| 75 | */ | |
| 76 | QName getQName(String qualifiedName); | |
| 77 | ||
| 78 | /** | |
| 79 | * <p> | |
| 80 | * Returns the <code>Namespace</code> which is mapped to the given prefix | |
| 81 | * or null if it could not be found. | |
| 82 | * </p> | |
| 83 | * | |
| 84 | * @param prefix | |
| 85 | * DOCUMENT ME! | |
| 86 | * | |
| 87 | * @return the <code>Namespace</code> associated with the given prefix | |
| 88 | */ | |
| 89 | Namespace getNamespaceForPrefix(String prefix); | |
| 90 | ||
| 91 | /** | |
| 92 | * <p> | |
| 93 | * Returns the <code>Namespace</code> which is mapped to the given URI or | |
| 94 | * null if it could not be found. If there is more than one | |
| 95 | * <code>Namespace</code> mapped to the URI, which of them will be | |
| 96 | * returned is undetermined. | |
| 97 | * </p> | |
| 98 | * | |
| 99 | * @param uri | |
| 100 | * DOCUMENT ME! | |
| 101 | * | |
| 102 | * @return the <code>Namespace</code> associated with the given URI | |
| 103 | */ | |
| 104 | Namespace getNamespaceForURI(String uri); | |
| 105 | ||
| 106 | /** | |
| 107 | * <p> | |
| 108 | * Returns the all namespaces which are mapped to the given URI or an empty | |
| 109 | * list if no such namespaces could be found. | |
| 110 | * </p> | |
| 111 | * | |
| 112 | * @param uri | |
| 113 | * DOCUMENT ME! | |
| 114 | * | |
| 115 | * @return the namespaces associated with the given URI | |
| 116 | * | |
| 117 | * @since 1.5 | |
| 118 | */ | |
| 119 | List getNamespacesForURI(String uri); | |
| 120 | ||
| 121 | /** | |
| 122 | * <p> | |
| 123 | * Returns the namespace prefix of this element if one exists otherwise an | |
| 124 | * empty <code>String</code> is returned. | |
| 125 | * </p> | |
| 126 | * | |
| 127 | * @return the prefix of the <code>Namespace</code> of this element or an | |
| 128 | * empty <code>String</code> | |
| 129 | */ | |
| 130 | String getNamespacePrefix(); | |
| 131 | ||
| 132 | /** | |
| 133 | * <p> | |
| 134 | * Returns the URI mapped to the namespace of this element if one exists | |
| 135 | * otherwise an empty <code>String</code> is returned. | |
| 136 | * </p> | |
| 137 | * | |
| 138 | * @return the URI for the <code>Namespace</code> of this element or an | |
| 139 | * empty <code>String</code> | |
| 140 | */ | |
| 141 | String getNamespaceURI(); | |
| 142 | ||
| 143 | /** | |
| 144 | * <p> | |
| 145 | * Returns the fully qualified name of this element. This will be the same | |
| 146 | * as the value returned from {@link #getName}if this element has no | |
| 147 | * namespace attached to this element or an expression of the form | |
| 148 | * | |
| 149 | * <pre> | |
| 150 | * getNamespacePrefix() + ":" + getName() | |
| 151 | * </pre> | |
| 152 | * | |
| 153 | * will be returned. | |
| 154 | * </p> | |
| 155 | * | |
| 156 | * @return the fully qualified name of the element. | |
| 157 | */ | |
| 158 | String getQualifiedName(); | |
| 159 | ||
| 160 | /** | |
| 161 | * <p> | |
| 162 | * Returns any additional namespaces declarations for this element other | |
| 163 | * than namespace returned via the {@link #getNamespace()}method. If no | |
| 164 | * additional namespace declarations are present for this element then an | |
| 165 | * empty list will be returned. The list is backed by the element such that | |
| 166 | * changes to the list will be reflected in the element though the reverse | |
| 167 | * is not the case. | |
| 168 | * </p> | |
| 169 | * | |
| 170 | * @return a list of any additional namespace declarations. | |
| 171 | */ | |
| 172 | List additionalNamespaces(); | |
| 173 | ||
| 174 | /** | |
| 175 | * <p> | |
| 176 | * Returns all the namespaces declared by this element. If no namespaces are | |
| 177 | * declared for this element then an empty list will be returned. The list | |
| 178 | * is backed by the element such that changes to the list will be reflected | |
| 179 | * in the element though the reverse is not the case. | |
| 180 | * </p> | |
| 181 | * | |
| 182 | * @return a list of namespaces declared for this element. | |
| 183 | */ | |
| 184 | List declaredNamespaces(); | |
| 185 | ||
| 186 | // Builder methods | |
| 187 | // ------------------------------------------------------------------------- | |
| 188 | ||
| 189 | /** | |
| 190 | * <p> | |
| 191 | * Adds the attribute value of the given local name. If an attribute already | |
| 192 | * exists for the given name it will be replaced. Attributes with null | |
| 193 | * values are silently ignored. If the value of the attribute is null then | |
| 194 | * this method call will remove any attributes with the given name. | |
| 195 | * </p> | |
| 196 | * | |
| 197 | * @param name | |
| 198 | * is the name of the attribute whose value is to be added or | |
| 199 | * updated | |
| 200 | * @param value | |
| 201 | * is the attribute's value | |
| 202 | * | |
| 203 | * @return this <code>Element</code> instance. | |
| 204 | */ | |
| 205 | Element addAttribute(String name, String value); | |
| 206 | ||
| 207 | /** | |
| 208 | * <p> | |
| 209 | * Adds the attribute value of the given fully qualified name. If an | |
| 210 | * attribute already exists for the given name it will be replaced. | |
| 211 | * Attributes with null values are silently ignored. If the value of the | |
| 212 | * attribute is null then this method call will remove any attributes with | |
| 213 | * the given name. | |
| 214 | * </p> | |
| 215 | * | |
| 216 | * @param qName | |
| 217 | * is the fully qualified name of the attribute whose value is to | |
| 218 | * be added or updated | |
| 219 | * @param value | |
| 220 | * is the attribute's value | |
| 221 | * | |
| 222 | * @return this <code>Element</code> instance. | |
| 223 | */ | |
| 224 | Element addAttribute(QName qName, String value); | |
| 225 | ||
| 226 | /** | |
| 227 | * Adds a new <code>Comment</code> node with the given text to this | |
| 228 | * element. | |
| 229 | * | |
| 230 | * @param comment | |
| 231 | * is the text for the <code>Comment</code> node. | |
| 232 | * | |
| 233 | * @return this <code>Element</code> instance. | |
| 234 | */ | |
| 235 | Element addComment(String comment); | |
| 236 | ||
| 237 | /** | |
| 238 | * Adds a new <code>CDATA</code> node with the given text to this element. | |
| 239 | * | |
| 240 | * @param cdata | |
| 241 | * is the text for the <code>CDATA</code> node. | |
| 242 | * | |
| 243 | * @return this <code>Element</code> instance. | |
| 244 | */ | |
| 245 | Element addCDATA(String cdata); | |
| 246 | ||
| 247 | /** | |
| 248 | * Adds a new <code>Entity</code> node with the given name and text to | |
| 249 | * this element and returns a reference to the new node. | |
| 250 | * | |
| 251 | * @param name | |
| 252 | * is the name for the <code>Entity</code> node. | |
| 253 | * @param text | |
| 254 | * is the text for the <code>Entity</code> node. | |
| 255 | * | |
| 256 | * @return this <code>Element</code> instance. | |
| 257 | */ | |
| 258 | Element addEntity(String name, String text); | |
| 259 | ||
| 260 | /** | |
| 261 | * Adds a namespace to this element for use by its child content | |
| 262 | * | |
| 263 | * @param prefix | |
| 264 | * is the prefix to use, which should not be null or blank | |
| 265 | * @param uri | |
| 266 | * is the namespace URI | |
| 267 | * | |
| 268 | * @return this <code>Element</code> instance. | |
| 269 | */ | |
| 270 | Element addNamespace(String prefix, String uri); | |
| 271 | ||
| 272 | /** | |
| 273 | * Adds a processing instruction for the given target | |
| 274 | * | |
| 275 | * @param target | |
| 276 | * is the target of the processing instruction | |
| 277 | * @param text | |
| 278 | * is the textual data (key/value pairs) of the processing | |
| 279 | * instruction | |
| 280 | * | |
| 281 | * @return this <code>Element</code> instance. | |
| 282 | */ | |
| 283 | Element addProcessingInstruction(String target, String text); | |
| 284 | ||
| 285 | /** | |
| 286 | * Adds a processing instruction for the given target | |
| 287 | * | |
| 288 | * @param target | |
| 289 | * is the target of the processing instruction | |
| 290 | * @param data | |
| 291 | * is a Map of the key / value pairs of the processing | |
| 292 | * instruction | |
| 293 | * | |
| 294 | * @return this <code>Element</code> instance. | |
| 295 | */ | |
| 296 | Element addProcessingInstruction(String target, Map data); | |
| 297 | ||
| 298 | /** | |
| 299 | * Adds a new <code>Text</code> node with the given text to this element. | |
| 300 | * | |
| 301 | * @param text | |
| 302 | * is the text for the <code>Text</code> node. | |
| 303 | * | |
| 304 | * @return this <code>Element</code> instance. | |
| 305 | */ | |
| 306 | Element addText(String text); | |
| 307 | ||
| 308 | // Typesafe modifying methods | |
| 309 | // ------------------------------------------------------------------------- | |
| 310 | ||
| 311 | /** | |
| 312 | * Adds the given <code>Attribute</code> to this element. If the given | |
| 313 | * node already has a parent defined then an | |
| 314 | * <code>IllegalAddException</code> will be thrown. Attributes with null | |
| 315 | * values are silently ignored. | |
| 316 | * | |
| 317 | * <p> | |
| 318 | * If the value of the attribute is null then this method call will remove | |
| 319 | * any attributes with the QName of this attribute. | |
| 320 | * </p> | |
| 321 | * | |
| 322 | * @param attribute | |
| 323 | * is the attribute to be added | |
| 324 | */ | |
| 325 | void add(Attribute attribute); | |
| 326 | ||
| 327 | /** | |
| 328 | * Adds the given <code>CDATA</code> to this element. If the given node | |
| 329 | * already has a parent defined then an <code>IllegalAddException</code> | |
| 330 | * will be thrown. | |
| 331 | * | |
| 332 | * @param cdata | |
| 333 | * is the CDATA to be added | |
| 334 | */ | |
| 335 | void add(CDATA cdata); | |
| 336 | ||
| 337 | /** | |
| 338 | * Adds the given <code>Entity</code> to this element. If the given node | |
| 339 | * already has a parent defined then an <code>IllegalAddException</code> | |
| 340 | * will be thrown. | |
| 341 | * | |
| 342 | * @param entity | |
| 343 | * is the entity to be added | |
| 344 | */ | |
| 345 | void add(Entity entity); | |
| 346 | ||
| 347 | /** | |
| 348 | * Adds the given <code>Text</code> to this element. If the given node | |
| 349 | * already has a parent defined then an <code>IllegalAddException</code> | |
| 350 | * will be thrown. | |
| 351 | * | |
| 352 | * @param text | |
| 353 | * is the text to be added | |
| 354 | */ | |
| 355 | void add(Text text); | |
| 356 | ||
| 357 | /** | |
| 358 | * Adds the given <code>Namespace</code> to this element. If the given | |
| 359 | * node already has a parent defined then an | |
| 360 | * <code>IllegalAddException</code> will be thrown. | |
| 361 | * | |
| 362 | * @param namespace | |
| 363 | * is the namespace to be added | |
| 364 | */ | |
| 365 | void add(Namespace namespace); | |
| 366 | ||
| 367 | /** | |
| 368 | * Removes the given <code>Attribute</code> from this element. | |
| 369 | * | |
| 370 | * @param attribute | |
| 371 | * is the attribute to be removed | |
| 372 | * | |
| 373 | * @return true if the attribute was removed | |
| 374 | */ | |
| 375 | boolean remove(Attribute attribute); | |
| 376 | ||
| 377 | /** | |
| 378 | * Removes the given <code>CDATA</code> if the node is an immediate child | |
| 379 | * of this element. If the given node is not an immediate child of this | |
| 380 | * element then the {@link Node#detach()}method should be used instead. | |
| 381 | * | |
| 382 | * @param cdata | |
| 383 | * is the CDATA to be removed | |
| 384 | * | |
| 385 | * @return true if the cdata was removed | |
| 386 | */ | |
| 387 | boolean remove(CDATA cdata); | |
| 388 | ||
| 389 | /** | |
| 390 | * Removes the given <code>Entity</code> if the node is an immediate child | |
| 391 | * of this element. If the given node is not an immediate child of this | |
| 392 | * element then the {@link Node#detach()}method should be used instead. | |
| 393 | * | |
| 394 | * @param entity | |
| 395 | * is the entity to be removed | |
| 396 | * | |
| 397 | * @return true if the entity was removed | |
| 398 | */ | |
| 399 | boolean remove(Entity entity); | |
| 400 | ||
| 401 | /** | |
| 402 | * Removes the given <code>Namespace</code> if the node is an immediate | |
| 403 | * child of this element. If the given node is not an immediate child of | |
| 404 | * this element then the {@link Node#detach()}method should be used | |
| 405 | * instead. | |
| 406 | * | |
| 407 | * @param namespace | |
| 408 | * is the namespace to be removed | |
| 409 | * | |
| 410 | * @return true if the namespace was removed | |
| 411 | */ | |
| 412 | boolean remove(Namespace namespace); | |
| 413 | ||
| 414 | /** | |
| 415 | * Removes the given <code>Text</code> if the node is an immediate child | |
| 416 | * of this element. If the given node is not an immediate child of this | |
| 417 | * element then the {@link Node#detach()}method should be used instead. | |
| 418 | * | |
| 419 | * @param text | |
| 420 | * is the text to be removed | |
| 421 | * | |
| 422 | * @return true if the text was removed | |
| 423 | */ | |
| 424 | boolean remove(Text text); | |
| 425 | ||
| 426 | // Text methods | |
| 427 | // ------------------------------------------------------------------------- | |
| 428 | ||
| 429 | /** | |
| 430 | * Returns the text value of this element without recursing through child | |
| 431 | * elements. This method iterates through all {@link Text},{@link CDATA} | |
| 432 | * and {@link Entity}nodes that this element contains and appends the text | |
| 433 | * values together. | |
| 434 | * | |
| 435 | * @return the textual content of this Element. Child elements are not | |
| 436 | * navigated. This method does not return null; | |
| 437 | */ | |
| 438 | String getText(); | |
| 439 | ||
| 440 | /** | |
| 441 | * DOCUMENT ME! | |
| 442 | * | |
| 443 | * @return the trimmed text value where whitespace is trimmed and normalised | |
| 444 | * into single spaces. This method does not return null. | |
| 445 | */ | |
| 446 | String getTextTrim(); | |
| 447 | ||
| 448 | /** | |
| 449 | * Returns the XPath string-value of this node. The behaviour of this method | |
| 450 | * is defined in the <a href="http://www.w3.org/TR/xpath">XPath | |
| 451 | * specification </a>. This method returns the string-value of all the | |
| 452 | * contained {@link Text},{@link CDATA},{@link Entity}and {@link | |
| 453 | * Element} nodes all appended together. | |
| 454 | * | |
| 455 | * @return the text from all the child Text and Element nodes appended | |
| 456 | * together. | |
| 457 | */ | |
| 458 | String getStringValue(); | |
| 459 | ||
| 460 | /** | |
| 461 | * Accesses the data of this element which may implement data typing | |
| 462 | * bindings such as XML Schema or Java Bean bindings or will return the same | |
| 463 | * value as {@link #getText} | |
| 464 | * | |
| 465 | * @return DOCUMENT ME! | |
| 466 | */ | |
| 467 | Object getData(); | |
| 468 | ||
| 469 | /** | |
| 470 | * Sets the data value of this element if this element supports data binding | |
| 471 | * or calls {@link #setText}if it doesn't | |
| 472 | * | |
| 473 | * @param data | |
| 474 | * DOCUMENT ME! | |
| 475 | */ | |
| 476 | void setData(Object data); | |
| 477 | ||
| 478 | // Attribute methods | |
| 479 | // ------------------------------------------------------------------------- | |
| 480 | ||
| 481 | /** | |
| 482 | * <p> | |
| 483 | * Returns the {@link Attribute}instances this element contains as a backed | |
| 484 | * {@link List}so that the attributes may be modified directly using the | |
| 485 | * {@link List}interface. The <code>List</code> is backed by the | |
| 486 | * <code>Element</code> so that changes to the list are reflected in the | |
| 487 | * element and vice versa. | |
| 488 | * </p> | |
| 489 | * | |
| 490 | * @return the attributes that this element contains as a <code>List</code> | |
| 491 | */ | |
| 492 | List attributes(); | |
| 493 | ||
| 494 | /** | |
| 495 | * Sets the attributes that this element contains | |
| 496 | * | |
| 497 | * @param attributes | |
| 498 | * DOCUMENT ME! | |
| 499 | */ | |
| 500 | void setAttributes(List attributes); | |
| 501 | ||
| 502 | /** | |
| 503 | * DOCUMENT ME! | |
| 504 | * | |
| 505 | * @return the number of attributes this element contains | |
| 506 | */ | |
| 507 | int attributeCount(); | |
| 508 | ||
| 509 | /** | |
| 510 | * DOCUMENT ME! | |
| 511 | * | |
| 512 | * @return an iterator over the attributes of this element | |
| 513 | */ | |
| 514 | Iterator attributeIterator(); | |
| 515 | ||
| 516 | /** | |
| 517 | * Returns the attribute at the specified indexGets the | |
| 518 | * | |
| 519 | * @param index | |
| 520 | * DOCUMENT ME! | |
| 521 | * | |
| 522 | * @return the attribute at the specified index where index >= 0 and | |
| 523 | * index < number of attributes or throws an | |
| 524 | * IndexOutOfBoundsException if the index is not within the | |
| 525 | * allowable range | |
| 526 | */ | |
| 527 | Attribute attribute(int index); | |
| 528 | ||
| 529 | /** | |
| 530 | * Returns the attribute with the given name | |
| 531 | * | |
| 532 | * @param name | |
| 533 | * DOCUMENT ME! | |
| 534 | * | |
| 535 | * @return the attribute for the given local name in any namespace. If there | |
| 536 | * are more than one attributes with the given local name in | |
| 537 | * different namespaces then the first one is returned. | |
| 538 | */ | |
| 539 | Attribute attribute(String name); | |
| 540 | ||
| 541 | /** | |
| 542 | * DOCUMENT ME! | |
| 543 | * | |
| 544 | * @param qName | |
| 545 | * is the fully qualified name | |
| 546 | * | |
| 547 | * @return the attribute for the given fully qualified name or null if it | |
| 548 | * could not be found. | |
| 549 | */ | |
| 550 | Attribute attribute(QName qName); | |
| 551 | ||
| 552 | /** | |
| 553 | * <p> | |
| 554 | * This returns the attribute value for the attribute with the given name | |
| 555 | * and any namespace or null if there is no such attribute or the empty | |
| 556 | * string if the attribute value is empty. | |
| 557 | * </p> | |
| 558 | * | |
| 559 | * @param name | |
| 560 | * is the name of the attribute value to be returnd | |
| 561 | * | |
| 562 | * @return the value of the attribute, null if the attribute does not exist | |
| 563 | * or the empty string | |
| 564 | */ | |
| 565 | String attributeValue(String name); | |
| 566 | ||
| 567 | /** | |
| 568 | * <p> | |
| 569 | * This returns the attribute value for the attribute with the given name | |
| 570 | * and any namespace or the default value if there is no such attribute | |
| 571 | * value. | |
| 572 | * </p> | |
| 573 | * | |
| 574 | * @param name | |
| 575 | * is the name of the attribute value to be returnd | |
| 576 | * @param defaultValue | |
| 577 | * is the default value to be returned if the attribute has no | |
| 578 | * value defined. | |
| 579 | * | |
| 580 | * @return the value of the attribute or the defaultValue if the attribute | |
| 581 | * has no value defined. | |
| 582 | */ | |
| 583 | String attributeValue(String name, String defaultValue); | |
| 584 | ||
| 585 | /** | |
| 586 | * <p> | |
| 587 | * This returns the attribute value for the attribute with the given fully | |
| 588 | * qualified name or null if there is no such attribute or the empty string | |
| 589 | * if the attribute value is empty. | |
| 590 | * </p> | |
| 591 | * | |
| 592 | * @param qName | |
| 593 | * is the fully qualified name | |
| 594 | * | |
| 595 | * @return the value of the attribute, null if the attribute does not exist | |
| 596 | * or the empty string | |
| 597 | */ | |
| 598 | String attributeValue(QName qName); | |
| 599 | ||
| 600 | /** | |
| 601 | * <p> | |
| 602 | * This returns the attribute value for the attribute with the given fully | |
| 603 | * qualified name or the default value if there is no such attribute value. | |
| 604 | * </p> | |
| 605 | * | |
| 606 | * @param qName | |
| 607 | * is the fully qualified name | |
| 608 | * @param defaultValue | |
| 609 | * is the default value to be returned if the attribute has no | |
| 610 | * value defined. | |
| 611 | * | |
| 612 | * @return the value of the attribute or the defaultValue if the attribute | |
| 613 | * has no value defined. | |
| 614 | */ | |
| 615 | String attributeValue(QName qName, String defaultValue); | |
| 616 | ||
| 617 | /** | |
| 618 | * <p> | |
| 619 | * Sets the attribute value of the given local name. | |
| 620 | * </p> | |
| 621 | * | |
| 622 | * @param name | |
| 623 | * is the name of the attribute whose value is to be added or | |
| 624 | * updated | |
| 625 | * @param value | |
| 626 | * is the attribute's value | |
| 627 | * | |
| 628 | * @deprecated As of version 0.5. Please use {@link | |
| 629 | * #addAttribute(String,String)} instead. WILL BE REMOVED IN | |
| 630 | * dom4j-1.6 !! | |
| 631 | */ | |
| 632 | void setAttributeValue(String name, String value); | |
| 633 | ||
| 634 | /** | |
| 635 | * <p> | |
| 636 | * Sets the attribute value of the given fully qualified name. | |
| 637 | * </p> | |
| 638 | * | |
| 639 | * @param qName | |
| 640 | * is the fully qualified name of the attribute whose value is to | |
| 641 | * be added or updated | |
| 642 | * @param value | |
| 643 | * is the attribute's value | |
| 644 | * | |
| 645 | * @deprecated As of version 0.5. Please use {@link | |
| 646 | * #addAttribute(QName,String)} instead. WILL BE REMOVED IN | |
| 647 | * dom4j-1.6 !! | |
| 648 | */ | |
| 649 | void setAttributeValue(QName qName, String value); | |
| 650 | ||
| 651 | // Content methods | |
| 652 | // ------------------------------------------------------------------------- | |
| 653 | ||
| 654 | /** | |
| 655 | * Returns the first element for the given local name and any namespace. | |
| 656 | * | |
| 657 | * @param name | |
| 658 | * DOCUMENT ME! | |
| 659 | * | |
| 660 | * @return the first element with the given local name | |
| 661 | */ | |
| 662 | Element element(String name); | |
| 663 | ||
| 664 | /** | |
| 665 | * Returns the first element for the given fully qualified name. | |
| 666 | * | |
| 667 | * @param qName | |
| 668 | * is the fully qualified name to search for | |
| 669 | * | |
| 670 | * @return the first element with the given fully qualified name | |
| 671 | */ | |
| 672 | Element element(QName qName); | |
| 673 | ||
| 674 | /** | |
| 675 | * <p> | |
| 676 | * Returns the elements contained in this element. If this element does not | |
| 677 | * contain any elements then this method returns an empty list. The list is | |
| 678 | * backed by the element such that changes to the list will be reflected in | |
| 679 | * the element though the reverse is not the case. | |
| 680 | * </p> | |
| 681 | * | |
| 682 | * @return a list of all the elements in this element. | |
| 683 | */ | |
| 684 | List elements(); | |
| 685 | ||
| 686 | /** | |
| 687 | * <p> | |
| 688 | * Returns the elements contained in this element with the given local name | |
| 689 | * and any namespace. If no elements are found then this method returns an | |
| 690 | * empty list. The list is backed by the element such that changes to the | |
| 691 | * list will be reflected in the element though the reverse is not the case. | |
| 692 | * </p> | |
| 693 | * | |
| 694 | * @param name | |
| 695 | * DOCUMENT ME! | |
| 696 | * | |
| 697 | * @return a list of all the elements in this element for the given local | |
| 698 | * name | |
| 699 | */ | |
| 700 | List elements(String name); | |
| 701 | ||
| 702 | /** | |
| 703 | * <p> | |
| 704 | * Returns the elements contained in this element with the given fully | |
| 705 | * qualified name. If no elements are found then this method returns an | |
| 706 | * empty list. The list is backed by the element such that changes to the | |
| 707 | * list will be reflected in the element though the reverse is not the case. | |
| 708 | * </p> | |
| 709 | * | |
| 710 | * @param qName | |
| 711 | * is the fully qualified name to search for | |
| 712 | * | |
| 713 | * @return a list of all the elements in this element for the given fully | |
| 714 | * qualified name. | |
| 715 | */ | |
| 716 | List elements(QName qName); | |
| 717 | ||
| 718 | /** | |
| 719 | * Returns an iterator over all this elements child elements. | |
| 720 | * | |
| 721 | * @return an iterator over the contained elements | |
| 722 | */ | |
| 723 | Iterator elementIterator(); | |
| 724 | ||
| 725 | /** | |
| 726 | * Returns an iterator over the elements contained in this element which | |
| 727 | * match the given local name and any namespace. | |
| 728 | * | |
| 729 | * @param name | |
| 730 | * DOCUMENT ME! | |
| 731 | * | |
| 732 | * @return an iterator over the contained elements matching the given local | |
| 733 | * name | |
| 734 | */ | |
| 735 | Iterator elementIterator(String name); | |
| 736 | ||
| 737 | /** | |
| 738 | * Returns an iterator over the elements contained in this element which | |
| 739 | * match the given fully qualified name. | |
| 740 | * | |
| 741 | * @param qName | |
| 742 | * is the fully qualified name to search for | |
| 743 | * | |
| 744 | * @return an iterator over the contained elements matching the given fully | |
| 745 | * qualified name | |
| 746 | */ | |
| 747 | Iterator elementIterator(QName qName); | |
| 748 | ||
| 749 | // Helper methods | |
| 750 | // ------------------------------------------------------------------------- | |
| 751 | ||
| 752 | /** | |
| 753 | * DOCUMENT ME! | |
| 754 | * | |
| 755 | * @return true if this element is the root element of a document and this | |
| 756 | * element supports the parent relationship else false. | |
| 757 | */ | |
| 758 | boolean isRootElement(); | |
| 759 | ||
| 760 | /** | |
| 761 | * <p> | |
| 762 | * Returns true if this <code>Element</code> has mixed content. Mixed | |
| 763 | * content means that an element contains both textual data and child | |
| 764 | * elements. | |
| 765 | * </p> | |
| 766 | * | |
| 767 | * @return true if this element contains mixed content. | |
| 768 | */ | |
| 769 | boolean hasMixedContent(); | |
| 770 | ||
| 771 | /** | |
| 772 | * <p> | |
| 773 | * Returns true if this <code>Element</code> has text only content. | |
| 774 | * </p> | |
| 775 | * | |
| 776 | * @return true if this element is empty or only contains text content. | |
| 777 | */ | |
| 778 | boolean isTextOnly(); | |
| 779 | ||
| 780 | /** | |
| 781 | * Appends the attributes of the given element to me. This method behaves | |
| 782 | * like the {@link java.util.Collection#addAll(java.util.Collection)} | |
| 783 | * method. | |
| 784 | * | |
| 785 | * @param element | |
| 786 | * is the element whose attributes will be added to me. | |
| 787 | */ | |
| 788 | void appendAttributes(Element element); | |
| 789 | ||
| 790 | /** | |
| 791 | * <p> | |
| 792 | * Creates a deep copy of this element The new element is detached from its | |
| 793 | * parent, and getParent() on the clone will return null. | |
| 794 | * </p> | |
| 795 | * | |
| 796 | * @return a new deep copy Element | |
| 797 | */ | |
| 798 | Element createCopy(); | |
| 799 | ||
| 800 | /** | |
| 801 | * <p> | |
| 802 | * Creates a deep copy of this element with the given local name The new | |
| 803 | * element is detached from its parent, and getParent() on the clone will | |
| 804 | * return null. | |
| 805 | * </p> | |
| 806 | * | |
| 807 | * @param name | |
| 808 | * DOCUMENT ME! | |
| 809 | * | |
| 810 | * @return a new deep copy Element | |
| 811 | */ | |
| 812 | Element createCopy(String name); | |
| 813 | ||
| 814 | /** | |
| 815 | * <p> | |
| 816 | * Creates a deep copy of this element with the given fully qualified name. | |
| 817 | * The new element is detached from its parent, and getParent() on the clone | |
| 818 | * will return null. | |
| 819 | * </p> | |
| 820 | * | |
| 821 | * @param qName | |
| 822 | * DOCUMENT ME! | |
| 823 | * | |
| 824 | * @return a new deep copy Element | |
| 825 | */ | |
| 826 | Element createCopy(QName qName); | |
| 827 | ||
| 828 | String elementText(String name); | |
| 829 | ||
| 830 | String elementText(QName qname); | |
| 831 | ||
| 832 | String elementTextTrim(String name); | |
| 833 | ||
| 834 | String elementTextTrim(QName qname); | |
| 835 | ||
| 836 | /** | |
| 837 | * Returns a node at the given index suitable for an XPath result set. This | |
| 838 | * means the resulting Node will either be null or it will support the | |
| 839 | * parent relationship. | |
| 840 | * | |
| 841 | * @param index | |
| 842 | * DOCUMENT ME! | |
| 843 | * | |
| 844 | * @return the Node for the given index which will support the parent | |
| 845 | * relationship or null if there is not a node at the given index. | |
| 846 | */ | |
| 847 | Node getXPathResult(int index); | |
| 848 | } | |
| 849 | ||
| 850 | /* | |
| 851 | * Redistribution and use of this software and associated documentation | |
| 852 | * ("Software"), with or without modification, are permitted provided that the | |
| 853 | * following conditions are met: | |
| 854 | * | |
| 855 | * 1. Redistributions of source code must retain copyright statements and | |
| 856 | * notices. Redistributions must also contain a copy of this document. | |
| 857 | * | |
| 858 | * 2. Redistributions in binary form must reproduce the above copyright notice, | |
| 859 | * this list of conditions and the following disclaimer in the documentation | |
| 860 | * and/or other materials provided with the distribution. | |
| 861 | * | |
| 862 | * 3. The name "DOM4J" must not be used to endorse or promote products derived | |
| 863 | * from this Software without prior written permission of MetaStuff, Ltd. For | |
| 864 | * written permission, please contact dom4j-info@metastuff.com. | |
| 865 | * | |
| 866 | * 4. Products derived from this Software may not be called "DOM4J" nor may | |
| 867 | * "DOM4J" appear in their names without prior written permission of MetaStuff, | |
| 868 | * Ltd. DOM4J is a registered trademark of MetaStuff, Ltd. | |
| 869 | * | |
| 870 | * 5. Due credit should be given to the DOM4J Project - http://www.dom4j.org | |
| 871 | * | |
| 872 | * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' AND | |
| 873 | * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
| 874 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
| 875 | * ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS CONTRIBUTORS BE | |
| 876 | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR | |
| 877 | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF | |
| 878 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | |
| 879 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN | |
| 880 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |
| 881 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE | |
| 882 | * POSSIBILITY OF SUCH DAMAGE. | |
| 883 | * | |
| 884 | * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved. | |
| 885 | */ |
|
||||||||||