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  * A representation of the SOAP header
  34  * element. A SOAP header element consists of XML data that affects
  35  * the way the application-specific content is processed by the message
  36  * provider. For example, transaction semantics, authentication information,
  37  * and so on, can be specified as the content of a {@code SOAPHeader}
  38  * object.
  39  * <P>
  40  * A {@code SOAPEnvelope} object contains an empty
  41  * {@code SOAPHeader} object by default. If the {@code SOAPHeader}
  42  * object, which is optional, is not needed, it can be retrieved and deleted
  43  * with the following line of code. The variable <i>se</i> is a
  44  * {@code SOAPEnvelope} object.
  45  * <pre>{@code
  46  *      se.getHeader().detachNode();
  47  * }</pre>
  48  *
  49  * A {@code SOAPHeader} object is created with the {@code SOAPEnvelope}
  50  * method {@code addHeader}. This method, which creates a new header and adds it
  51  * to the envelope, may be called only after the existing header has been removed.
  52  *
  53  * <pre>{@code
  54  *      se.getHeader().detachNode();
  55  *      SOAPHeader sh = se.addHeader();
  56  * }</pre>
  57  * <P>
  58  * A {@code SOAPHeader} object can have only {@code SOAPHeaderElement}
  59  * objects as its immediate children. The method {@code addHeaderElement}
  60  * creates a new {@code HeaderElement} object and adds it to the
  61  * {@code SOAPHeader} object. In the following line of code, the
  62  * argument to the method {@code addHeaderElement} is a {@code Name}
  63  * object that is the name for the new {@code HeaderElement} object.
  64  * <pre>{@code
  65  *      SOAPHeaderElement shElement = sh.addHeaderElement(name);
  66  * }</pre>
  67  *
  68  * @see SOAPHeaderElement
  69  * @since 1.6
  70  */
  71 public interface SOAPHeader extends SOAPElement {
  72     /**
  73      * Creates a new {@code SOAPHeaderElement} object initialized with the
  74      * specified name and adds it to this {@code SOAPHeader} object.
  75      *
  76      * @param name a {@code Name} object with the name of the new
  77      *        {@code SOAPHeaderElement} object
  78      * @return the new {@code SOAPHeaderElement} object that was
  79      *          inserted into this {@code SOAPHeader} object
  80      * @exception SOAPException if a SOAP error occurs
  81      * @see SOAPHeader#addHeaderElement(javax.xml.namespace.QName)
  82      */
  83     public SOAPHeaderElement addHeaderElement(Name name)
  84         throws SOAPException;
  85 
  86     /**
  87      * Creates a new {@code SOAPHeaderElement} object initialized with the
  88      * specified qname and adds it to this {@code SOAPHeader} object.
  89      *
  90      * @param qname a {@code QName} object with the qname of the new
  91      *        {@code SOAPHeaderElement} object
  92      * @return the new {@code SOAPHeaderElement} object that was
  93      *          inserted into this {@code SOAPHeader} object
  94      * @exception SOAPException if a SOAP error occurs
  95      * @see SOAPHeader#addHeaderElement(Name)
  96      * @since 1.6, SAAJ 1.3
  97      */
  98     public SOAPHeaderElement addHeaderElement(QName qname)
  99         throws SOAPException;
 100 
 101     /**
 102      * Returns an {@code Iterator} over all the {@code SOAPHeaderElement} objects
 103      * in this {@code SOAPHeader} object
 104      * that have the specified <i>actor</i> and that have a MustUnderstand attribute
 105      * whose value is equivalent to {@code true}.
 106      * <p>
 107      * In SOAP 1.2 the <i>env:actor</i> attribute is replaced by the <i>env:role</i>
 108      * attribute, but with essentially the same semantics.
 109      *
 110      * @param actor a {@code String} giving the URI of the {@code actor} / {@code role}
 111      *        for which to search
 112      * @return an {@code Iterator} object over all the
 113      *         {@code SOAPHeaderElement} objects that contain the specified
 114      *          {@code actor} / {@code role} and are marked as MustUnderstand
 115      * @see #examineHeaderElements
 116      * @see #extractHeaderElements
 117      * @see SOAPConstants#URI_SOAP_ACTOR_NEXT
 118      *
 119      * @since 1.6, SAAJ 1.2
 120      */
 121     public Iterator examineMustUnderstandHeaderElements(String actor);
 122 
 123     /**
 124      * Returns an {@code Iterator} over all the {@code SOAPHeaderElement} objects
 125      * in this {@code SOAPHeader} object
 126      * that have the specified <i>actor</i>.
 127      *
 128      * An <i>actor</i> is a global attribute that indicates the intermediate
 129      * parties that should process a message before it reaches its ultimate
 130      * receiver. An actor receives the message and processes it before sending
 131      * it on to the next actor. The default actor is the ultimate intended
 132      * recipient for the message, so if no actor attribute is included in a
 133      * {@code SOAPHeader} object, it is sent to the ultimate receiver
 134      * along with the message body.
 135      * <p>
 136      * In SOAP 1.2 the <i>env:actor</i> attribute is replaced by the <i>env:role</i>
 137      * attribute, but with essentially the same semantics.
 138      *
 139      * @param actor a {@code String} giving the URI of the {@code actor} / {@code role}
 140      *        for which to search
 141      * @return an {@code Iterator} object over all the
 142      *         {@code SOAPHeaderElement} objects that contain the specified
 143      *          {@code actor} / {@code role}
 144      * @see #extractHeaderElements
 145      * @see SOAPConstants#URI_SOAP_ACTOR_NEXT
 146      */
 147     public Iterator examineHeaderElements(String actor);
 148 
 149     /**
 150      * Returns an {@code Iterator} over all the {@code SOAPHeaderElement} objects
 151      * in this {@code SOAPHeader} object
 152      * that have the specified <i>actor</i> and detaches them
 153      * from this {@code SOAPHeader} object.
 154      * <P>
 155      * This method allows an actor to process the parts of the
 156      * {@code SOAPHeader} object that apply to it and to remove
 157      * them before passing the message on to the next actor.
 158      * <p>
 159      * In SOAP 1.2 the <i>env:actor</i> attribute is replaced by the <i>env:role</i>
 160      * attribute, but with essentially the same semantics.
 161      *
 162      * @param actor a {@code String} giving the URI of the {@code actor} / {@code role}
 163      *        for which to search
 164      * @return an {@code Iterator} object over all the
 165      *         {@code SOAPHeaderElement} objects that contain the specified
 166      *          {@code actor} / {@code role}
 167      *
 168      * @see #examineHeaderElements
 169      * @see SOAPConstants#URI_SOAP_ACTOR_NEXT
 170      */
 171     public Iterator extractHeaderElements(String actor);
 172 
 173     /**
 174      * Creates a new NotUnderstood {@code SOAPHeaderElement} object initialized
 175      * with the specified name and adds it to this {@code SOAPHeader} object.
 176      * This operation is supported only by SOAP 1.2.
 177      *
 178      * @param name a {@code QName} object with the name of the
 179      *        {@code SOAPHeaderElement} object that was not understood.
 180      * @return the new {@code SOAPHeaderElement} object that was
 181      *          inserted into this {@code SOAPHeader} object
 182      * @exception SOAPException if a SOAP error occurs.
 183      * @exception UnsupportedOperationException if this is a SOAP 1.1 Header.
 184      * @since 1.6, SAAJ 1.3
 185      */
 186     public SOAPHeaderElement addNotUnderstoodHeaderElement(QName name)
 187         throws SOAPException;
 188 
 189     /**
 190      * Creates a new Upgrade {@code SOAPHeaderElement} object initialized
 191      * with the specified List of supported SOAP URIs and adds it to this
 192      * {@code SOAPHeader} object.
 193      * This operation is supported on both SOAP 1.1 and SOAP 1.2 header.
 194      *
 195      * @param supportedSOAPURIs an {@code Iterator} object with the URIs of SOAP
 196      *          versions supported.
 197      * @return the new {@code SOAPHeaderElement} object that was
 198      *          inserted into this {@code SOAPHeader} object
 199      * @exception SOAPException if a SOAP error occurs.
 200      * @since 1.6, SAAJ 1.3
 201      */
 202     public SOAPHeaderElement addUpgradeHeaderElement(Iterator supportedSOAPURIs)
 203         throws SOAPException;
 204 
 205     /**
 206      * Creates a new Upgrade {@code SOAPHeaderElement} object initialized
 207      * with the specified array of supported SOAP URIs and adds it to this
 208      * {@code SOAPHeader} object.
 209      * This operation is supported on both SOAP 1.1 and SOAP 1.2 header.
 210      *
 211      * @param  supportedSoapUris an array of the URIs of SOAP versions supported.
 212      * @return the new {@code SOAPHeaderElement} object that was
 213      *          inserted into this {@code SOAPHeader} object
 214      * @exception SOAPException if a SOAP error occurs.
 215      * @since 1.6, SAAJ 1.3
 216      */
 217     public SOAPHeaderElement addUpgradeHeaderElement(String[] supportedSoapUris)
 218         throws SOAPException;
 219 
 220     /**
 221      * Creates a new Upgrade {@code SOAPHeaderElement} object initialized
 222      * with the specified supported SOAP URI and adds it to this
 223      * {@code SOAPHeader} object.
 224      * This operation is supported on both SOAP 1.1 and SOAP 1.2 header.
 225      *
 226      * @param supportedSoapUri the URI of SOAP the version that is supported.
 227      * @return the new {@code SOAPHeaderElement} object that was
 228      *          inserted into this {@code SOAPHeader} object
 229      * @exception SOAPException if a SOAP error occurs.
 230      * @since 1.6, SAAJ 1.3
 231      */
 232     public SOAPHeaderElement addUpgradeHeaderElement(String supportedSoapUri)
 233         throws SOAPException;
 234 
 235     /**
 236      * Returns an {@code Iterator} over all the {@code SOAPHeaderElement} objects
 237      * in this {@code SOAPHeader} object.
 238      *
 239      * @return an {@code Iterator} object over all the
 240      *          {@code SOAPHeaderElement} objects contained by this
 241      *          {@code SOAPHeader}
 242      * @see #extractAllHeaderElements
 243      *
 244      * @since 1.6, SAAJ 1.2
 245      */
 246     public Iterator examineAllHeaderElements();
 247 
 248     /**
 249      * Returns an {@code Iterator} over all the {@code SOAPHeaderElement} objects
 250      * in this {@code SOAPHeader} object and detaches them
 251      * from this {@code SOAPHeader} object.
 252      *
 253      * @return an {@code Iterator} object over all the
 254      *          {@code SOAPHeaderElement} objects contained by this
 255      *          {@code SOAPHeader}
 256      *
 257      * @see #examineAllHeaderElements
 258      *
 259      * @since 1.6, SAAJ 1.2
 260      */
 261     public Iterator extractAllHeaderElements();
 262 
 263 }
--- EOF ---