1 /*
2 * Copyright (c) 2004, 2017, 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<SOAPHeaderElement> 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<SOAPHeaderElement> 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<SOAPHeaderElement> 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<String> 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<SOAPHeaderElement> 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<SOAPHeaderElement> extractAllHeaderElements();
262
263 }