1 /*
   2  * Copyright (c) 2004, 2015, 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 javax.xml.soap} for details.
  42  *
  43  * @since 1.6
  44  */
  45 public 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 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 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 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 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 may 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 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 may 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 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 may 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 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 }
--- EOF ---