SOAPHeader


1   /*
2    * $Id: SOAPHeader.java,v 1.14 2005/04/05 22:46:27 mk125090 Exp $
3    * $Revision: 1.14 $
4    * $Date: 2005/04/05 22:46:27 $
5    */
6   
7   /*
8    * The contents of this file are subject to the terms
9    * of the Common Development and Distribution License
10   * (the License).  You may not use this file except in
11   * compliance with the License.
12   * 
13   * You can obtain a copy of the license at
14   * https://glassfish.dev.java.net/public/CDDLv1.0.html.
15   * See the License for the specific language governing
16   * permissions and limitations under the License.
17   * 
18   * When distributing Covered Code, include this CDDL
19   * Header Notice in each file and include the License file
20   * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
21   * If applicable, add the following below the CDDL Header,
22   * with the fields enclosed by brackets [] replaced by
23   * you own identifying information:
24   * "Portions Copyrighted [year] [name of copyright owner]"
25   * 
26   * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
27   */
28  package javax.xml.soap;
29  
30  import java.util.Iterator  ;
31  
32  import javax.xml.namespace.QName  ;
33  
34  /**
35   * A representation of the SOAP header
36   * element. A SOAP header element consists of XML data that affects
37   * the way the application-specific content is processed by the message
38   * provider. For example, transaction semantics, authentication information,
39   * and so on, can be specified as the content of a <code>SOAPHeader</code>
40   * object.
41   * <P>
42   * A <code>SOAPEnvelope</code> object contains an empty
43   * <code>SOAPHeader</code> object by default. If the <code>SOAPHeader</code>
44   * object, which is optional, is not needed, it can be retrieved and deleted
45   * with the following line of code. The variable <i>se</i> is a
46   * <code>SOAPEnvelope</code> object.
47   * <PRE>
48   *      se.getHeader().detachNode();
49   * </PRE>
50   *
51   * A <code>SOAPHeader</code> object is created with the <code>SOAPEnvelope</code>
52   * method <code>addHeader</code>. This method, which creates a new header and adds it
53   * to the envelope, may be called only after the existing header has been removed.
54   *
55   * <PRE>
56   *      se.getHeader().detachNode();
57   *      SOAPHeader sh = se.addHeader();
58   * </PRE>
59   * <P>
60   * A <code>SOAPHeader</code> object can have only <code>SOAPHeaderElement</code>
61   * objects as its immediate children. The method <code>addHeaderElement</code>
62   * creates a new <code>HeaderElement</code> object and adds it to the
63   * <code>SOAPHeader</code> object. In the following line of code, the
64   * argument to the method <code>addHeaderElement</code> is a <code>Name</code>
65   * object that is the name for the new <code>HeaderElement</code> object.
66   * <PRE>
67   *      SOAPHeaderElement shElement = sh.addHeaderElement(name);
68   * </PRE>
69   *
70   * @see SOAPHeaderElement
71   */
72  public interface SOAPHeader extends SOAPElement   {
73      /**
74       * Creates a new <code>SOAPHeaderElement</code> object initialized with the
75       * specified name and adds it to this <code>SOAPHeader</code> object.
76       *
77       * @param name a <code>Name</code> object with the name of the new
78       *        <code>SOAPHeaderElement</code> object
79       * @return the new <code>SOAPHeaderElement</code> object that was
80       *          inserted into this <code>SOAPHeader</code> object
81       * @exception SOAPException if a SOAP error occurs
82       * @see SOAPHeader#addHeaderElement(javax.xml.namespace.QName)
83       */
84      public SOAPHeaderElement   addHeaderElement(Name   name)
85          throws SOAPException  ;
86  
87      /**
88       * Creates a new <code>SOAPHeaderElement</code> object initialized with the
89       * specified qname and adds it to this <code>SOAPHeader</code> object.
90       *
91       * @param qname a <code>QName</code> object with the qname of the new
92       *        <code>SOAPHeaderElement</code> object
93       * @return the new <code>SOAPHeaderElement</code> object that was
94       *          inserted into this <code>SOAPHeader</code> object
95       * @exception SOAPException if a SOAP error occurs
96       * @see SOAPHeader#addHeaderElement(Name)
97       * @since SAAJ 1.3
98       */
99      public SOAPHeaderElement   addHeaderElement(QName   qname)
100         throws SOAPException  ;
101 
102     /**
103      * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
104      * in this <code>SOAPHeader</code> object
105      * that have the specified <i>actor</i> and that have a MustUnderstand attribute
106      * whose value is equivalent to <code>true</code>.
107      * <p>
108      * In SOAP 1.2 the <i>env:actor</i> attribute is replaced by the <i>env:role</i> 
109      * attribute, but with essentially the same semantics.
110      *
111      * @param actor a <code>String</code> giving the URI of the <code>actor</code> / <code>role</code>
112      *        for which to search
113      * @return an <code>Iterator</code> object over all the
114      *         <code>SOAPHeaderElement</code> objects that contain the specified
115      *          <code>actor</code> / <code>role</code> and are marked as MustUnderstand
116      * @see #examineHeaderElements
117      * @see #extractHeaderElements
118      * @see SOAPConstants#URI_SOAP_ACTOR_NEXT
119      *
120      * @since SAAJ 1.2
121      */
122     public Iterator   examineMustUnderstandHeaderElements(String   actor);
123 
124     /**
125      * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
126      * in this <code>SOAPHeader</code> object
127      * that have the specified <i>actor</i>.
128      *
129      * An <i>actor</i> is a global attribute that indicates the intermediate
130      * parties that should process a message before it reaches its ultimate
131      * receiver. An actor receives the message and processes it before sending
132      * it on to the next actor. The default actor is the ultimate intended
133      * recipient for the message, so if no actor attribute is included in a
134      * <code>SOAPHeader</code> object, it is sent to the ultimate receiver
135      * along with the message body.
136      * <p>
137      * In SOAP 1.2 the <i>env:actor</i> attribute is replaced by the <i>env:role</i> 
138      * attribute, but with essentially the same semantics.
139      *
140      * @param actor a <code>String</code> giving the URI of the <code>actor</code> / <code>role</code>
141      *        for which to search
142      * @return an <code>Iterator</code> object over all the
143      *         <code>SOAPHeaderElement</code> objects that contain the specified
144      *          <code>actor</code> / <code>role</code>
145      * @see #extractHeaderElements
146      * @see SOAPConstants#URI_SOAP_ACTOR_NEXT
147      */
148     public Iterator   examineHeaderElements(String   actor);
149 
150     /**
151      * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
152      * in this <code>SOAPHeader</code> object
153      * that have the specified <i>actor</i> and detaches them
154      * from this <code>SOAPHeader</code> object.
155      * <P>
156      * This method allows an actor to process the parts of the
157      * <code>SOAPHeader</code> object that apply to it and to remove
158      * them before passing the message on to the next actor.
159      * <p>
160      * In SOAP 1.2 the <i>env:actor</i> attribute is replaced by the <i>env:role</i> 
161      * attribute, but with essentially the same semantics.
162      *
163      * @param actor a <code>String</code> giving the URI of the <code>actor</code> / <code>role</code>
164      *        for which to search
165      * @return an <code>Iterator</code> object over all the
166      *         <code>SOAPHeaderElement</code> objects that contain the specified
167      *          <code>actor</code> / <code>role</code>
168      *
169      * @see #examineHeaderElements
170      * @see SOAPConstants#URI_SOAP_ACTOR_NEXT
171      */
172     public Iterator   extractHeaderElements(String   actor);
173 
174     /**
175      * Creates a new NotUnderstood <code>SOAPHeaderElement</code> object initialized
176      * with the specified name and adds it to this <code>SOAPHeader</code> object.
177      * This operation is supported only by SOAP 1.2.
178      *
179      * @param name a <code>QName</code> object with the name of the
180      *        <code>SOAPHeaderElement</code> object that was not understood.
181      * @return the new <code>SOAPHeaderElement</code> object that was
182      *          inserted into this <code>SOAPHeader</code> object
183      * @exception SOAPException if a SOAP error occurs.
184      * @exception UnsupportedOperationException if this is a SOAP 1.1 Header.
185      * @since SAAJ 1.3
186      */
187     public SOAPHeaderElement   addNotUnderstoodHeaderElement(QName   name)
188         throws SOAPException  ;
189 
190     /**
191      * Creates a new Upgrade <code>SOAPHeaderElement</code> object initialized
192      * with the specified List of supported SOAP URIs and adds it to this
193      * <code>SOAPHeader</code> object.
194      * This operation is supported on both SOAP 1.1 and SOAP 1.2 header.
195      *
196      * @param supportedSOAPURIs an <code>Iterator</code> object with the URIs of SOAP
197      *          versions supported.
198      * @return the new <code>SOAPHeaderElement</code> object that was
199      *          inserted into this <code>SOAPHeader</code> object
200      * @exception SOAPException if a SOAP error occurs.
201      * @since SAAJ 1.3
202      */
203     public SOAPHeaderElement   addUpgradeHeaderElement(Iterator   supportedSOAPURIs)
204         throws SOAPException  ;
205 
206     /**
207      * Creates a new Upgrade <code>SOAPHeaderElement</code> object initialized
208      * with the specified array of supported SOAP URIs and adds it to this
209      * <code>SOAPHeader</code> object.
210      * This operation is supported on both SOAP 1.1 and SOAP 1.2 header.
211      *
212      * @param  supportedSoapUris an array of the URIs of SOAP versions supported.
213      * @return the new <code>SOAPHeaderElement</code> object that was
214      *          inserted into this <code>SOAPHeader</code> object
215      * @exception SOAPException if a SOAP error occurs.
216      * @since SAAJ 1.3
217      */
218     public SOAPHeaderElement   addUpgradeHeaderElement(String  [] supportedSoapUris)
219         throws SOAPException  ;
220 
221     /**
222      * Creates a new Upgrade <code>SOAPHeaderElement</code> object initialized
223      * with the specified supported SOAP URI and adds it to this
224      * <code>SOAPHeader</code> object.
225      * This operation is supported on both SOAP 1.1 and SOAP 1.2 header.
226      *
227      * @param supportedSoapUri the URI of SOAP the version that is supported.
228      * @return the new <code>SOAPHeaderElement</code> object that was
229      *          inserted into this <code>SOAPHeader</code> object
230      * @exception SOAPException if a SOAP error occurs.
231      * @since SAAJ 1.3
232      */
233     public SOAPHeaderElement   addUpgradeHeaderElement(String   supportedSoapUri)
234         throws SOAPException  ;
235 
236     /**
237      * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
238      * in this <code>SOAPHeader</code> object.
239      *
240      * @return an <code>Iterator</code> object over all the
241      *          <code>SOAPHeaderElement</code> objects contained by this
242      *          <code>SOAPHeader</code>
243      * @see #extractAllHeaderElements
244      *
245      * @since SAAJ 1.2
246      */
247     public Iterator   examineAllHeaderElements();
248 
249     /**
250      * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
251      * in this <code>SOAPHeader</code> object and detaches them
252      * from this <code>SOAPHeader</code> object.
253      *
254      * @return an <code>Iterator</code> object over all the
255      *          <code>SOAPHeaderElement</code> objects contained by this
256      *          <code>SOAPHeader</code>
257      *
258      * @see #examineAllHeaderElements
259      *
260      * @since SAAJ 1.2
261      */
262     public Iterator   extractAllHeaderElements();
263 
264 }
265 
266 
267
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags