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