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