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
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
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 }
|
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
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
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 }
|