1 /* 2 * Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.xml.soap; 27 28 import java.util.Iterator; 29 30 import javax.xml.namespace.QName; 31 32 /** 33 * An object representing an element of a SOAP message that is allowed but not 34 * specifically prescribed by a SOAP specification. This interface serves as the 35 * base interface for those objects that are specifically prescribed by a SOAP 36 * specification. 37 * <p> 38 * Methods in this interface that are required to return SAAJ specific objects 39 * may "silently" replace nodes in the tree as required to successfully return 40 * objects of the correct type. See {@link #getChildElements()} and 41 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap</a>} 42 * for details. 43 * 44 * @since 1.6 45 */ 46 public interface SOAPElement extends Node, org.w3c.dom.Element { 47 48 /** 49 * Creates a new {@code SOAPElement} object initialized with the 50 * given {@code Name} object and adds the new element to this 51 * {@code SOAPElement} object. 52 * <P> 53 * This method may be deprecated in a future release of SAAJ in favor of 54 * addChildElement(javax.xml.namespace.QName) 55 * 56 * @param name a {@code Name} object with the XML name for the 57 * new element 58 * 59 * @return the new {@code SOAPElement} object that was created 60 * @exception SOAPException if there is an error in creating the 61 * {@code SOAPElement} object 62 * @see SOAPElement#addChildElement(javax.xml.namespace.QName) 63 */ 64 public SOAPElement addChildElement(Name name) throws SOAPException; 65 66 /** 67 * Creates a new {@code SOAPElement} object initialized with the given 68 * {@code QName} object and adds the new element to this {@code SOAPElement} 69 * object. The <i>namespace</i>, <i>localname</i> and <i>prefix</i> of the new 70 * {@code SOAPElement} are all taken from the {@code qname} argument. 71 * 72 * @param qname a {@code QName} object with the XML name for the 73 * new element 74 * 75 * @return the new {@code SOAPElement} object that was created 76 * @exception SOAPException if there is an error in creating the 77 * {@code SOAPElement} object 78 * @see SOAPElement#addChildElement(Name) 79 * @since 1.6, SAAJ 1.3 80 */ 81 public SOAPElement addChildElement(QName qname) throws SOAPException; 82 83 /** 84 * Creates a new {@code SOAPElement} object initialized with the 85 * specified local name and adds the new element to this 86 * {@code SOAPElement} object. 87 * The new {@code SOAPElement} inherits any in-scope default namespace. 88 * 89 * @param localName a {@code String} giving the local name for 90 * the element 91 * @return the new {@code SOAPElement} object that was created 92 * @exception SOAPException if there is an error in creating the 93 * {@code SOAPElement} object 94 */ 95 public SOAPElement addChildElement(String localName) throws SOAPException; 96 97 /** 98 * Creates a new {@code SOAPElement} object initialized with the 99 * specified local name and prefix and adds the new element to this 100 * {@code SOAPElement} object. 101 * 102 * @param localName a {@code String} giving the local name for 103 * the new element 104 * @param prefix a {@code String} giving the namespace prefix for 105 * the new element 106 * 107 * @return the new {@code SOAPElement} object that was created 108 * @exception SOAPException if the {@code prefix} is not valid in the 109 * context of this {@code SOAPElement} or if there is an error in creating the 110 * {@code SOAPElement} object 111 */ 112 public SOAPElement addChildElement(String localName, String prefix) 113 throws SOAPException; 114 115 /** 116 * Creates a new {@code SOAPElement} object initialized with the 117 * specified local name, prefix, and URI and adds the new element to this 118 * {@code SOAPElement} object. 119 * 120 * @param localName a {@code String} giving the local name for 121 * the new element 122 * @param prefix a {@code String} giving the namespace prefix for 123 * the new element 124 * @param uri a {@code String} giving the URI of the namespace 125 * to which the new element belongs 126 * 127 * @return the new {@code SOAPElement} object that was created 128 * @exception SOAPException if there is an error in creating the 129 * {@code SOAPElement} object 130 */ 131 public SOAPElement addChildElement(String localName, String prefix, 132 String uri) 133 throws SOAPException; 134 135 /** 136 * Add a {@code SOAPElement} as a child of this 137 * {@code SOAPElement} instance. The {@code SOAPElement} 138 * is expected to be created by a 139 * {@code SOAPFactory}. Callers should not rely on the 140 * element instance being added as is into the XML 141 * tree. Implementations could end up copying the content 142 * of the {@code SOAPElement} passed into an instance of 143 * a different {@code SOAPElement} implementation. For 144 * instance if {@code addChildElement()} is called on a 145 * {@code SOAPHeader}, {@code element} will be copied 146 * into an instance of a {@code SOAPHeaderElement}. 147 * 148 * <P>The fragment rooted in {@code element} is either added 149 * as a whole or not at all, if there was an error. 150 * 151 * <P>The fragment rooted in {@code element} cannot contain 152 * elements named "Envelope", "Header" or "Body" and in the SOAP 153 * namespace. Any namespace prefixes present in the fragment 154 * should be fully resolved using appropriate namespace 155 * declarations within the fragment itself. 156 * 157 * @param element the {@code SOAPElement} to be added as a 158 * new child 159 * 160 * @exception SOAPException if there was an error in adding this 161 * element as a child 162 * 163 * @return an instance representing the new SOAP element that was 164 * actually added to the tree. 165 */ 166 public SOAPElement addChildElement(SOAPElement element) 167 throws SOAPException; 168 169 /** 170 * Detaches all children of this {@code SOAPElement}. 171 * <p> 172 * This method is useful for rolling back the construction of partially 173 * completed {@code SOAPHeaders} and {@code SOAPBodys} in 174 * preparation for sending a fault when an error condition is detected. It 175 * is also useful for recycling portions of a document within a SOAP 176 * message. 177 * 178 * @since 1.6, SAAJ 1.2 179 */ 180 public abstract void removeContents(); 181 182 /** 183 * Creates a new {@code Text} object initialized with the given 184 * {@code String} and adds it to this {@code SOAPElement} object. 185 * 186 * @param text a {@code String} object with the textual content to be added 187 * 188 * @return the {@code SOAPElement} object into which 189 * the new {@code Text} object was inserted 190 * @exception SOAPException if there is an error in creating the 191 * new {@code Text} object or if it is not legal to 192 * attach it as a child to this 193 * {@code SOAPElement} 194 */ 195 public SOAPElement addTextNode(String text) throws SOAPException; 196 197 /** 198 * Adds an attribute with the specified name and value to this 199 * {@code SOAPElement} object. 200 * 201 * @param name a {@code Name} object with the name of the attribute 202 * @param value a {@code String} giving the value of the attribute 203 * @return the {@code SOAPElement} object into which the attribute was 204 * inserted 205 * 206 * @exception SOAPException if there is an error in creating the 207 * Attribute, or it is invalid to set 208 an attribute with {@code Name} 209 {@code name} on this SOAPElement. 210 * @see SOAPElement#addAttribute(javax.xml.namespace.QName, String) 211 */ 212 public SOAPElement addAttribute(Name name, String value) 213 throws SOAPException; 214 215 /** 216 * Adds an attribute with the specified name and value to this 217 * {@code SOAPElement} object. 218 * 219 * @param qname a {@code QName} object with the name of the attribute 220 * @param value a {@code String} giving the value of the attribute 221 * @return the {@code SOAPElement} object into which the attribute was 222 * inserted 223 * 224 * @exception SOAPException if there is an error in creating the 225 * Attribute, or it is invalid to set 226 an attribute with {@code QName} 227 {@code qname} on this SOAPElement. 228 * @see SOAPElement#addAttribute(Name, String) 229 * @since 1.6, SAAJ 1.3 230 */ 231 public SOAPElement addAttribute(QName qname, String value) 232 throws SOAPException; 233 234 /** 235 * Adds a namespace declaration with the specified prefix and URI to this 236 * {@code SOAPElement} object. 237 * 238 * @param prefix a {@code String} giving the prefix of the namespace 239 * @param uri a {@code String} giving the uri of the namespace 240 * @return the {@code SOAPElement} object into which this 241 * namespace declaration was inserted. 242 * 243 * @exception SOAPException if there is an error in creating the 244 * namespace 245 */ 246 public SOAPElement addNamespaceDeclaration(String prefix, String uri) 247 throws SOAPException; 248 249 /** 250 * Returns the value of the attribute with the specified name. 251 * 252 * @param name a {@code Name} object with the name of the attribute 253 * @return a {@code String} giving the value of the specified 254 * attribute, Null if there is no such attribute 255 * @see SOAPElement#getAttributeValue(javax.xml.namespace.QName) 256 */ 257 public String getAttributeValue(Name name); 258 259 /** 260 * Returns the value of the attribute with the specified qname. 261 * 262 * @param qname a {@code QName} object with the qname of the attribute 263 * @return a {@code String} giving the value of the specified 264 * attribute, Null if there is no such attribute 265 * @see SOAPElement#getAttributeValue(Name) 266 * @since 1.6, SAAJ 1.3 267 */ 268 public String getAttributeValue(QName qname); 269 270 /** 271 * Returns an {@code Iterator} over all of the attribute 272 * {@code Name} objects in this 273 * {@code SOAPElement} object. The iterator can be used to get 274 * the attribute names, which can then be passed to the method 275 * {@code getAttributeValue} to retrieve the value of each 276 * attribute. 277 * 278 * @see SOAPElement#getAllAttributesAsQNames() 279 * @return an iterator over the names of the attributes 280 */ 281 public Iterator getAllAttributes(); 282 283 /** 284 * Returns an {@code Iterator} over all of the attributes 285 * in this {@code SOAPElement} as {@code QName} objects. 286 * The iterator can be used to get the attribute QName, which can then 287 * be passed to the method {@code getAttributeValue} to retrieve 288 * the value of each attribute. 289 * 290 * @return an iterator over the QNames of the attributes 291 * @see SOAPElement#getAllAttributes() 292 * @since 1.6, SAAJ 1.3 293 */ 294 public Iterator getAllAttributesAsQNames(); 295 296 297 /** 298 * Returns the URI of the namespace that has the given prefix. 299 * 300 * @param prefix a {@code String} giving the prefix of the namespace 301 * for which to search 302 * @return a {@code String} with the uri of the namespace that has 303 * the given prefix 304 */ 305 public String getNamespaceURI(String prefix); 306 307 /** 308 * Returns an {@code Iterator} over the namespace prefix 309 * {@code String}s declared by this element. The prefixes returned by 310 * this iterator can be passed to the method 311 * {@code getNamespaceURI} to retrieve the URI of each namespace. 312 * 313 * @return an iterator over the namespace prefixes in this 314 * {@code SOAPElement} object 315 */ 316 public Iterator getNamespacePrefixes(); 317 318 /** 319 * Returns an {@code Iterator} over the namespace prefix 320 * {@code String}s visible to this element. The prefixes returned by 321 * this iterator can be passed to the method 322 * {@code getNamespaceURI} to retrieve the URI of each namespace. 323 * 324 * @return an iterator over the namespace prefixes are within scope of this 325 * {@code SOAPElement} object 326 * 327 * @since 1.6, SAAJ 1.2 328 */ 329 public Iterator getVisibleNamespacePrefixes(); 330 331 /** 332 * Creates a {@code QName} whose namespace URI is the one associated 333 * with the parameter, {@code prefix}, in the context of this 334 * {@code SOAPElement}. The remaining elements of the new 335 * {@code QName} are taken directly from the parameters, 336 * {@code localName} and {@code prefix}. 337 * 338 * @param localName 339 * a {@code String} containing the local part of the name. 340 * @param prefix 341 * a {@code String} containing the prefix for the name. 342 * 343 * @return a {@code QName} with the specified {@code localName} 344 * and {@code prefix}, and with a namespace that is associated 345 * with the {@code prefix} in the context of this 346 * {@code SOAPElement}. This namespace will be the same as 347 * the one that would be returned by 348 * <code>{@link #getNamespaceURI(String)}</code> if it were given 349 * {@code prefix} as it's parameter. 350 * 351 * @exception SOAPException if the {@code QName} cannot be created. 352 * 353 * @since 1.6, SAAJ 1.3 354 */ 355 public QName createQName(String localName, String prefix) 356 throws SOAPException; 357 /** 358 * Returns the name of this {@code SOAPElement} object. 359 * 360 * @return a {@code Name} object with the name of this 361 * {@code SOAPElement} object 362 */ 363 public Name getElementName(); 364 365 /** 366 * Returns the qname of this {@code SOAPElement} object. 367 * 368 * @return a {@code QName} object with the qname of this 369 * {@code SOAPElement} object 370 * @see SOAPElement#getElementName() 371 * @since 1.6, SAAJ 1.3 372 */ 373 public QName getElementQName(); 374 375 /** 376 * Changes the name of this {@code Element} to {@code newName} if 377 * possible. SOAP Defined elements such as SOAPEnvelope, SOAPHeader, SOAPBody 378 * etc. cannot have their names changed using this method. Any attempt to do 379 * so will result in a SOAPException being thrown. 380 *<P> 381 * Callers should not rely on the element instance being renamed as is. 382 * Implementations could end up copying the content of the 383 * {@code SOAPElement} to a renamed instance. 384 * 385 * @param newName the new name for the {@code Element}. 386 * 387 * @exception SOAPException if changing the name of this {@code Element} 388 * is not allowed. 389 * @return The renamed Node 390 * 391 * @since 1.6, SAAJ 1.3 392 */ 393 public SOAPElement setElementQName(QName newName) throws SOAPException; 394 395 /** 396 * Removes the attribute with the specified name. 397 * 398 * @param name the {@code Name} object with the name of the 399 * attribute to be removed 400 * @return {@code true} if the attribute was 401 * removed successfully; {@code false} if it was not 402 * @see SOAPElement#removeAttribute(javax.xml.namespace.QName) 403 */ 404 public boolean removeAttribute(Name name); 405 406 /** 407 * Removes the attribute with the specified qname. 408 * 409 * @param qname the {@code QName} object with the qname of the 410 * attribute to be removed 411 * @return {@code true} if the attribute was 412 * removed successfully; {@code false} if it was not 413 * @see SOAPElement#removeAttribute(Name) 414 * @since 1.6, SAAJ 1.3 415 */ 416 public boolean removeAttribute(QName qname); 417 418 /** 419 * Removes the namespace declaration corresponding to the given prefix. 420 * 421 * @param prefix a {@code String} giving the prefix for which 422 * to search 423 * @return {@code true} if the namespace declaration was 424 * removed successfully; {@code false} if it was not 425 */ 426 public boolean removeNamespaceDeclaration(String prefix); 427 428 /** 429 * Returns an {@code Iterator} over all the immediate child 430 * {@link Node}s of this element. This includes {@code javax.xml.soap.Text} 431 * objects as well as {@code SOAPElement} objects. 432 * <p> 433 * Calling this method may cause child {@code Element}, 434 * {@code SOAPElement} and {@code org.w3c.dom.Text} nodes to be 435 * replaced by {@code SOAPElement}, {@code SOAPHeaderElement}, 436 * {@code SOAPBodyElement} or {@code javax.xml.soap.Text} nodes as 437 * appropriate for the type of this parent node. As a result the calling 438 * application must treat any existing references to these child nodes that 439 * have been obtained through DOM APIs as invalid and either discard them or 440 * refresh them with the values returned by this {@code Iterator}. This 441 * behavior can be avoided by calling the equivalent DOM APIs. See 442 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap</a>} 443 * for more details. 444 * 445 * @return an iterator with the content of this {@code SOAPElement} 446 * object 447 */ 448 public Iterator getChildElements(); 449 450 /** 451 * Returns an {@code Iterator} over all the immediate child 452 * {@link Node}s of this element with the specified name. All of these 453 * children will be {@code SOAPElement} nodes. 454 * <p> 455 * Calling this method may cause child {@code Element}, 456 * {@code SOAPElement} and {@code org.w3c.dom.Text} nodes to be 457 * replaced by {@code SOAPElement}, {@code SOAPHeaderElement}, 458 * {@code SOAPBodyElement} or {@code javax.xml.soap.Text} nodes as 459 * appropriate for the type of this parent node. As a result the calling 460 * application must treat any existing references to these child nodes that 461 * have been obtained through DOM APIs as invalid and either discard them or 462 * refresh them with the values returned by this {@code Iterator}. This 463 * behavior can be avoided by calling the equivalent DOM APIs. See 464 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap</a>} 465 * for more details. 466 * 467 * @param name a {@code Name} object with the name of the child 468 * elements to be returned 469 * 470 * @return an {@code Iterator} object over all the elements 471 * in this {@code SOAPElement} object with the 472 * specified name 473 * @see SOAPElement#getChildElements(javax.xml.namespace.QName) 474 */ 475 public Iterator getChildElements(Name name); 476 477 /** 478 * Returns an {@code Iterator} over all the immediate child 479 * {@link Node}s of this element with the specified qname. All of these 480 * children will be {@code SOAPElement} nodes. 481 * <p> 482 * Calling this method may cause child {@code Element}, 483 * {@code SOAPElement} and {@code org.w3c.dom.Text} nodes to be 484 * replaced by {@code SOAPElement}, {@code SOAPHeaderElement}, 485 * {@code SOAPBodyElement} or {@code javax.xml.soap.Text} nodes as 486 * appropriate for the type of this parent node. As a result the calling 487 * application must treat any existing references to these child nodes that 488 * have been obtained through DOM APIs as invalid and either discard them or 489 * refresh them with the values returned by this {@code Iterator}. This 490 * behavior can be avoided by calling the equivalent DOM APIs. See 491 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap</a>} 492 * for more details. 493 * 494 * @param qname a {@code QName} object with the qname of the child 495 * elements to be returned 496 * 497 * @return an {@code Iterator} object over all the elements 498 * in this {@code SOAPElement} object with the 499 * specified qname 500 * @see SOAPElement#getChildElements(Name) 501 * @since 1.6, SAAJ 1.3 502 */ 503 public Iterator getChildElements(QName qname); 504 505 /** 506 * Sets the encoding style for this {@code SOAPElement} object 507 * to one specified. 508 * 509 * @param encodingStyle a {@code String} giving the encoding style 510 * 511 * @exception IllegalArgumentException if there was a problem in the 512 * encoding style being set. 513 * @exception SOAPException if setting the encodingStyle is invalid for this SOAPElement. 514 * @see #getEncodingStyle 515 */ 516 public void setEncodingStyle(String encodingStyle) 517 throws SOAPException; 518 /** 519 * Returns the encoding style for this {@code SOAPElement} object. 520 * 521 * @return a {@code String} giving the encoding style 522 * 523 * @see #setEncodingStyle 524 */ 525 public String getEncodingStyle(); 526 }