Mercurial > jdk8-mips64-public > jaxws / file comparison

comparison: src/share/jaxws_classes/javax/xml/soap/SOAPHeader.java

src/share/jaxws_classes/javax/xml/soap/SOAPHeader.java

changeset 286
f50545b5e2f1
child 368
0989ad8c0860
equal deleted inserted replaced
284:88b85470e72c 286:f50545b5e2f1
1 /*
2 * Copyright (c) 2004, 2011, 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 */
70 public interface SOAPHeader extends SOAPElement {
71 /**
72 * Creates a new <code>SOAPHeaderElement</code> object initialized with the
73 * specified name and adds it to this <code>SOAPHeader</code> object.
74 *
75 * @param name a <code>Name</code> object with the name of the new
76 * <code>SOAPHeaderElement</code> object
77 * @return the new <code>SOAPHeaderElement</code> object that was
78 * inserted into this <code>SOAPHeader</code> object
79 * @exception SOAPException if a SOAP error occurs
80 * @see SOAPHeader#addHeaderElement(javax.xml.namespace.QName)
81 */
82 public SOAPHeaderElement addHeaderElement(Name name)
83 throws SOAPException;
84
85 /**
86 * Creates a new <code>SOAPHeaderElement</code> object initialized with the
87 * specified qname and adds it to this <code>SOAPHeader</code> object.
88 *
89 * @param qname a <code>QName</code> object with the qname of the new
90 * <code>SOAPHeaderElement</code> object
91 * @return the new <code>SOAPHeaderElement</code> object that was
92 * inserted into this <code>SOAPHeader</code> object
93 * @exception SOAPException if a SOAP error occurs
94 * @see SOAPHeader#addHeaderElement(Name)
95 * @since SAAJ 1.3
96 */
97 public SOAPHeaderElement addHeaderElement(QName qname)
98 throws SOAPException;
99
100 /**
101 * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
102 * in this <code>SOAPHeader</code> object
103 * that have the specified <i>actor</i> and that have a MustUnderstand attribute
104 * whose value is equivalent to <code>true</code>.
105 * <p>
106 * In SOAP 1.2 the <i>env:actor</i> attribute is replaced by the <i>env:role</i>
107 * attribute, but with essentially the same semantics.
108 *
109 * @param actor a <code>String</code> giving the URI of the <code>actor</code> / <code>role</code>
110 * for which to search
111 * @return an <code>Iterator</code> object over all the
112 * <code>SOAPHeaderElement</code> objects that contain the specified
113 * <code>actor</code> / <code>role</code> and are marked as MustUnderstand
114 * @see #examineHeaderElements
115 * @see #extractHeaderElements
116 * @see SOAPConstants#URI_SOAP_ACTOR_NEXT
117 *
118 * @since SAAJ 1.2
119 */
120 public Iterator examineMustUnderstandHeaderElements(String actor);
121
122 /**
123 * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
124 * in this <code>SOAPHeader</code> object
125 * that have the specified <i>actor</i>.
126 *
127 * An <i>actor</i> is a global attribute that indicates the intermediate
128 * parties that should process a message before it reaches its ultimate
129 * receiver. An actor receives the message and processes it before sending
130 * it on to the next actor. The default actor is the ultimate intended
131 * recipient for the message, so if no actor attribute is included in a
132 * <code>SOAPHeader</code> object, it is sent to the ultimate receiver
133 * along with the message body.
134 * <p>
135 * In SOAP 1.2 the <i>env:actor</i> attribute is replaced by the <i>env:role</i>
136 * attribute, but with essentially the same semantics.
137 *
138 * @param actor a <code>String</code> giving the URI of the <code>actor</code> / <code>role</code>
139 * for which to search
140 * @return an <code>Iterator</code> object over all the
141 * <code>SOAPHeaderElement</code> objects that contain the specified
142 * <code>actor</code> / <code>role</code>
143 * @see #extractHeaderElements
144 * @see SOAPConstants#URI_SOAP_ACTOR_NEXT
145 */
146 public Iterator examineHeaderElements(String actor);
147
148 /**
149 * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
150 * in this <code>SOAPHeader</code> object
151 * that have the specified <i>actor</i> and detaches them
152 * from this <code>SOAPHeader</code> object.
153 * <P>
154 * This method allows an actor to process the parts of the
155 * <code>SOAPHeader</code> object that apply to it and to remove
156 * them before passing the message on to the next actor.
157 * <p>
158 * In SOAP 1.2 the <i>env:actor</i> attribute is replaced by the <i>env:role</i>
159 * attribute, but with essentially the same semantics.
160 *
161 * @param actor a <code>String</code> giving the URI of the <code>actor</code> / <code>role</code>
162 * for which to search
163 * @return an <code>Iterator</code> object over all the
164 * <code>SOAPHeaderElement</code> objects that contain the specified
165 * <code>actor</code> / <code>role</code>
166 *
167 * @see #examineHeaderElements
168 * @see SOAPConstants#URI_SOAP_ACTOR_NEXT
169 */
170 public Iterator extractHeaderElements(String actor);
171
172 /**
173 * Creates a new NotUnderstood <code>SOAPHeaderElement</code> object initialized
174 * with the specified name and adds it to this <code>SOAPHeader</code> object.
175 * This operation is supported only by SOAP 1.2.
176 *
177 * @param name a <code>QName</code> object with the name of the
178 * <code>SOAPHeaderElement</code> object that was not understood.
179 * @return the new <code>SOAPHeaderElement</code> object that was
180 * inserted into this <code>SOAPHeader</code> object
181 * @exception SOAPException if a SOAP error occurs.
182 * @exception UnsupportedOperationException if this is a SOAP 1.1 Header.
183 * @since SAAJ 1.3
184 */
185 public SOAPHeaderElement addNotUnderstoodHeaderElement(QName name)
186 throws SOAPException;
187
188 /**
189 * Creates a new Upgrade <code>SOAPHeaderElement</code> object initialized
190 * with the specified List of supported SOAP URIs and adds it to this
191 * <code>SOAPHeader</code> object.
192 * This operation is supported on both SOAP 1.1 and SOAP 1.2 header.
193 *
194 * @param supportedSOAPURIs an <code>Iterator</code> object with the URIs of SOAP
195 * versions supported.
196 * @return the new <code>SOAPHeaderElement</code> object that was
197 * inserted into this <code>SOAPHeader</code> object
198 * @exception SOAPException if a SOAP error occurs.
199 * @since SAAJ 1.3
200 */
201 public SOAPHeaderElement addUpgradeHeaderElement(Iterator supportedSOAPURIs)
202 throws SOAPException;
203
204 /**
205 * Creates a new Upgrade <code>SOAPHeaderElement</code> object initialized
206 * with the specified array of supported SOAP URIs and adds it to this
207 * <code>SOAPHeader</code> object.
208 * This operation is supported on both SOAP 1.1 and SOAP 1.2 header.
209 *
210 * @param supportedSoapUris an array of the URIs of SOAP versions supported.
211 * @return the new <code>SOAPHeaderElement</code> object that was
212 * inserted into this <code>SOAPHeader</code> object
213 * @exception SOAPException if a SOAP error occurs.
214 * @since SAAJ 1.3
215 */
216 public SOAPHeaderElement addUpgradeHeaderElement(String[] supportedSoapUris)
217 throws SOAPException;
218
219 /**
220 * Creates a new Upgrade <code>SOAPHeaderElement</code> object initialized
221 * with the specified supported SOAP URI and adds it to this
222 * <code>SOAPHeader</code> object.
223 * This operation is supported on both SOAP 1.1 and SOAP 1.2 header.
224 *
225 * @param supportedSoapUri the URI of SOAP the version that is supported.
226 * @return the new <code>SOAPHeaderElement</code> object that was
227 * inserted into this <code>SOAPHeader</code> object
228 * @exception SOAPException if a SOAP error occurs.
229 * @since SAAJ 1.3
230 */
231 public SOAPHeaderElement addUpgradeHeaderElement(String supportedSoapUri)
232 throws SOAPException;
233
234 /**
235 * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
236 * in this <code>SOAPHeader</code> object.
237 *
238 * @return an <code>Iterator</code> object over all the
239 * <code>SOAPHeaderElement</code> objects contained by this
240 * <code>SOAPHeader</code>
241 * @see #extractAllHeaderElements
242 *
243 * @since SAAJ 1.2
244 */
245 public Iterator examineAllHeaderElements();
246
247 /**
248 * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
249 * in this <code>SOAPHeader</code> object and detaches them
250 * from this <code>SOAPHeader</code> object.
251 *
252 * @return an <code>Iterator</code> object over all the
253 * <code>SOAPHeaderElement</code> objects contained by this
254 * <code>SOAPHeader</code>
255 *
256 * @see #examineAllHeaderElements
257 *
258 * @since SAAJ 1.2
259 */
260 public Iterator extractAllHeaderElements();
261
262 }

Mercurial Repository: jdk8-mips64-public/jaxws

mercurial