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  * 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</code>

    38  * object.

    39  * <P>

    40  * A <code>SOAPEnvelope</code> object contains an empty

    41  * <code>SOAPHeader</code> object by default. If the <code>SOAPHeader</code>

    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</code> object.

    45  * <PRE>

    46  *      se.getHeader().detachNode();

    47  * </PRE>

    48  *

    49  * A <code>SOAPHeader</code> object is created with the <code>SOAPEnvelope</code>

    50  * method <code>addHeader</code>. 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>

    54  *      se.getHeader().detachNode();

    55  *      SOAPHeader sh = se.addHeader();

    56  * </PRE>

    57  * <P>

    58  * A <code>SOAPHeader</code> object can have only <code>SOAPHeaderElement</code>

    59  * objects as its immediate children. The method <code>addHeaderElement</code>

    60  * creates a new <code>HeaderElement</code> object and adds it to the

    61  * <code>SOAPHeader</code> object. In the following line of code, the

    62  * argument to the method <code>addHeaderElement</code> is a <code>Name</code>

    63  * object that is the name for the new <code>HeaderElement</code> object.

    64  * <PRE>

    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</code> object initialized with the

    74      * specified name and adds it to this <code>SOAPHeader</code> object.

    75      *

    76      * @param name a <code>Name</code> object with the name of the new

    77      *        <code>SOAPHeaderElement</code> object

    78      * @return the new <code>SOAPHeaderElement</code> object that was

    79      *          inserted into this <code>SOAPHeader</code> 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</code> object initialized with the

    88      * specified qname and adds it to this <code>SOAPHeader</code> object.

    89      *

    90      * @param qname a <code>QName</code> object with the qname of the new

    91      *        <code>SOAPHeaderElement</code> object

    92      * @return the new <code>SOAPHeaderElement</code> object that was

    93      *          inserted into this <code>SOAPHeader</code> 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</code> over all the <code>SOAPHeaderElement</code> objects

   103      * in this <code>SOAPHeader</code> object

   104      * that have the specified <i>actor</i> and that have a MustUnderstand attribute

   105      * whose value is equivalent to <code>true</code>.

   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</code> giving the URI of the <code>actor</code> / <code>role</code>

   111      *        for which to search

   112      * @return an <code>Iterator</code> object over all the

   113      *         <code>SOAPHeaderElement</code> objects that contain the specified

   114      *          <code>actor</code> / <code>role</code> 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</code> over all the <code>SOAPHeaderElement</code> objects

   125      * in this <code>SOAPHeader</code> 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</code> 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</code> giving the URI of the <code>actor</code> / <code>role</code>

   140      *        for which to search

   141      * @return an <code>Iterator</code> object over all the

   142      *         <code>SOAPHeaderElement</code> objects that contain the specified

   143      *          <code>actor</code> / <code>role</code>

   144      * @see #extractHeaderElements

   145      * @see SOAPConstants#URI_SOAP_ACTOR_NEXT

   146      */

   147     public Iterator examineHeaderElements(String actor);

   148 

   149     /**

   150      * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects

   151      * in this <code>SOAPHeader</code> object

   152      * that have the specified <i>actor</i> and detaches them

   153      * from this <code>SOAPHeader</code> object.

   154      * <P>

   155      * This method allows an actor to process the parts of the

   156      * <code>SOAPHeader</code> 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</code> giving the URI of the <code>actor</code> / <code>role</code>

   163      *        for which to search

   164      * @return an <code>Iterator</code> object over all the

   165      *         <code>SOAPHeaderElement</code> objects that contain the specified

   166      *          <code>actor</code> / <code>role</code>

   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</code> object initialized

   175      * with the specified name and adds it to this <code>SOAPHeader</code> object.

   176      * This operation is supported only by SOAP 1.2.

   177      *

   178      * @param name a <code>QName</code> object with the name of the

   179      *        <code>SOAPHeaderElement</code> object that was not understood.

   180      * @return the new <code>SOAPHeaderElement</code> object that was

   181      *          inserted into this <code>SOAPHeader</code> 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</code> object initialized

   191      * with the specified List of supported SOAP URIs and adds it to this

   192      * <code>SOAPHeader</code> object.

   193      * This operation is supported on both SOAP 1.1 and SOAP 1.2 header.

   194      *

   195      * @param supportedSOAPURIs an <code>Iterator</code> object with the URIs of SOAP

   196      *          versions supported.

   197      * @return the new <code>SOAPHeaderElement</code> object that was

   198      *          inserted into this <code>SOAPHeader</code> 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</code> object initialized

   207      * with the specified array of supported SOAP URIs and adds it to this

   208      * <code>SOAPHeader</code> 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</code> object that was

   213      *          inserted into this <code>SOAPHeader</code> 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</code> object initialized

   222      * with the specified supported SOAP URI and adds it to this

   223      * <code>SOAPHeader</code> 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</code> object that was

   228      *          inserted into this <code>SOAPHeader</code> 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</code> over all the <code>SOAPHeaderElement</code> objects

   237      * in this <code>SOAPHeader</code> object.

   238      *

   239      * @return an <code>Iterator</code> object over all the

   240      *          <code>SOAPHeaderElement</code> objects contained by this

   241      *          <code>SOAPHeader</code>

   242      * @see #extractAllHeaderElements

   243      *

   244      * @since 1.6, SAAJ 1.2

   245      */

   246     public Iterator examineAllHeaderElements();

   247 

   248     /**

   249      * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects

   250      * in this <code>SOAPHeader</code> object and detaches them

   251      * from this <code>SOAPHeader</code> object.

   252      *

   253      * @return an <code>Iterator</code> object over all the

   254      *          <code>SOAPHeaderElement</code> objects contained by this

   255      *          <code>SOAPHeader</code>

   256      *

   257      * @see #examineAllHeaderElements

   258      *

   259      * @since 1.6, SAAJ 1.2

   260      */

   261     public Iterator extractAllHeaderElements();

   262 

   263 }