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 * An object representing an element of a SOAP message that is allowed but not
34 * specifically prescribed by a SOAP specification. This interface serves as the
35 * base interface for those objects that are specifically prescribed by a SOAP
36 * specification.
37 * <p>
38 * Methods in this interface that are required to return SAAJ specific objects
39 * may "silently" replace nodes in the tree as required to successfully return
40 * objects of the correct type. See {@link #getChildElements()} and
41 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
42 * for details.
43 */
44 public interface SOAPElement extends Node, org.w3c.dom.Element {
45
46 /**
47 * Creates a new <code>SOAPElement</code> object initialized with the
48 * given <code>Name</code> object and adds the new element to this
49 * <code>SOAPElement</code> object.
50 * <P>
51 * This method may be deprecated in a future release of SAAJ in favor of
52 * addChildElement(javax.xml.namespace.QName)
53 *
54 * @param name a <code>Name</code> object with the XML name for the
55 * new element
56 *
57 * @return the new <code>SOAPElement</code> object that was created
58 * @exception SOAPException if there is an error in creating the
59 * <code>SOAPElement</code> object
60 * @see SOAPElement#addChildElement(javax.xml.namespace.QName)
61 */
62 public SOAPElement addChildElement(Name name) throws SOAPException;
63
64 /**
65 * Creates a new <code>SOAPElement</code> object initialized with the given
66 * <code>QName</code> object and adds the new element to this <code>SOAPElement</code>
67 * object. The <i>namespace</i>, <i>localname</i> and <i>prefix</i> of the new
68 * <code>SOAPElement</code> are all taken from the <code>qname</code> argument.
69 *
70 * @param qname a <code>QName</code> object with the XML name for the
71 * new element
72 *
73 * @return the new <code>SOAPElement</code> object that was created
74 * @exception SOAPException if there is an error in creating the
75 * <code>SOAPElement</code> object
76 * @see SOAPElement#addChildElement(Name)
77 * @since SAAJ 1.3
78 */
79 public SOAPElement addChildElement(QName qname) throws SOAPException;
80
81 /**
82 * Creates a new <code>SOAPElement</code> object initialized with the
83 * specified local name and adds the new element to this
84 * <code>SOAPElement</code> object.
85 * The new <code>SOAPElement</code> inherits any in-scope default namespace.
86 *
87 * @param localName a <code>String</code> giving the local name for
88 * the element
89 * @return the new <code>SOAPElement</code> object that was created
90 * @exception SOAPException if there is an error in creating the
91 * <code>SOAPElement</code> object
92 */
93 public SOAPElement addChildElement(String localName) throws SOAPException;
94
95 /**
96 * Creates a new <code>SOAPElement</code> object initialized with the
97 * specified local name and prefix and adds the new element to this
156 * new child
157 *
158 * @exception SOAPException if there was an error in adding this
159 * element as a child
160 *
161 * @return an instance representing the new SOAP element that was
162 * actually added to the tree.
163 */
164 public SOAPElement addChildElement(SOAPElement element)
165 throws SOAPException;
166
167 /**
168 * Detaches all children of this <code>SOAPElement</code>.
169 * <p>
170 * This method is useful for rolling back the construction of partially
171 * completed <code>SOAPHeaders</code> and <code>SOAPBodys</code> in
172 * preparation for sending a fault when an error condition is detected. It
173 * is also useful for recycling portions of a document within a SOAP
174 * message.
175 *
176 * @since SAAJ 1.2
177 */
178 public abstract void removeContents();
179
180 /**
181 * Creates a new <code>Text</code> object initialized with the given
182 * <code>String</code> and adds it to this <code>SOAPElement</code> object.
183 *
184 * @param text a <code>String</code> object with the textual content to be added
185 *
186 * @return the <code>SOAPElement</code> object into which
187 * the new <code>Text</code> object was inserted
188 * @exception SOAPException if there is an error in creating the
189 * new <code>Text</code> object or if it is not legal to
190 * attach it as a child to this
191 * <code>SOAPElement</code>
192 */
193 public SOAPElement addTextNode(String text) throws SOAPException;
194
195 /**
196 * Adds an attribute with the specified name and value to this
207 <code>name</code> on this SOAPElement.
208 * @see SOAPElement#addAttribute(javax.xml.namespace.QName, String)
209 */
210 public SOAPElement addAttribute(Name name, String value)
211 throws SOAPException;
212
213 /**
214 * Adds an attribute with the specified name and value to this
215 * <code>SOAPElement</code> object.
216 *
217 * @param qname a <code>QName</code> object with the name of the attribute
218 * @param value a <code>String</code> giving the value of the attribute
219 * @return the <code>SOAPElement</code> object into which the attribute was
220 * inserted
221 *
222 * @exception SOAPException if there is an error in creating the
223 * Attribute, or it is invalid to set
224 an attribute with <code>QName</code>
225 <code>qname</code> on this SOAPElement.
226 * @see SOAPElement#addAttribute(Name, String)
227 * @since SAAJ 1.3
228 */
229 public SOAPElement addAttribute(QName qname, String value)
230 throws SOAPException;
231
232 /**
233 * Adds a namespace declaration with the specified prefix and URI to this
234 * <code>SOAPElement</code> object.
235 *
236 * @param prefix a <code>String</code> giving the prefix of the namespace
237 * @param uri a <code>String</code> giving the uri of the namespace
238 * @return the <code>SOAPElement</code> object into which this
239 * namespace declaration was inserted.
240 *
241 * @exception SOAPException if there is an error in creating the
242 * namespace
243 */
244 public SOAPElement addNamespaceDeclaration(String prefix, String uri)
245 throws SOAPException;
246
247 /**
248 * Returns the value of the attribute with the specified name.
249 *
250 * @param name a <code>Name</code> object with the name of the attribute
251 * @return a <code>String</code> giving the value of the specified
252 * attribute, Null if there is no such attribute
253 * @see SOAPElement#getAttributeValue(javax.xml.namespace.QName)
254 */
255 public String getAttributeValue(Name name);
256
257 /**
258 * Returns the value of the attribute with the specified qname.
259 *
260 * @param qname a <code>QName</code> object with the qname of the attribute
261 * @return a <code>String</code> giving the value of the specified
262 * attribute, Null if there is no such attribute
263 * @see SOAPElement#getAttributeValue(Name)
264 * @since SAAJ 1.3
265 */
266 public String getAttributeValue(QName qname);
267
268 /**
269 * Returns an <code>Iterator</code> over all of the attribute
270 * <code>Name</code> objects in this
271 * <code>SOAPElement</code> object. The iterator can be used to get
272 * the attribute names, which can then be passed to the method
273 * <code>getAttributeValue</code> to retrieve the value of each
274 * attribute.
275 *
276 * @see SOAPElement#getAllAttributesAsQNames()
277 * @return an iterator over the names of the attributes
278 */
279 public Iterator getAllAttributes();
280
281 /**
282 * Returns an <code>Iterator</code> over all of the attributes
283 * in this <code>SOAPElement</code> as <code>QName</code> objects.
284 * The iterator can be used to get the attribute QName, which can then
285 * be passed to the method <code>getAttributeValue</code> to retrieve
286 * the value of each attribute.
287 *
288 * @return an iterator over the QNames of the attributes
289 * @see SOAPElement#getAllAttributes()
290 * @since SAAJ 1.3
291 */
292 public Iterator getAllAttributesAsQNames();
293
294
295 /**
296 * Returns the URI of the namespace that has the given prefix.
297 *
298 * @param prefix a <code>String</code> giving the prefix of the namespace
299 * for which to search
300 * @return a <code>String</code> with the uri of the namespace that has
301 * the given prefix
302 */
303 public String getNamespaceURI(String prefix);
304
305 /**
306 * Returns an <code>Iterator</code> over the namespace prefix
307 * <code>String</code>s declared by this element. The prefixes returned by
308 * this iterator can be passed to the method
309 * <code>getNamespaceURI</code> to retrieve the URI of each namespace.
310 *
311 * @return an iterator over the namespace prefixes in this
312 * <code>SOAPElement</code> object
313 */
314 public Iterator getNamespacePrefixes();
315
316 /**
317 * Returns an <code>Iterator</code> over the namespace prefix
318 * <code>String</code>s visible to this element. The prefixes returned by
319 * this iterator can be passed to the method
320 * <code>getNamespaceURI</code> to retrieve the URI of each namespace.
321 *
322 * @return an iterator over the namespace prefixes are within scope of this
323 * <code>SOAPElement</code> object
324 *
325 * @since SAAJ 1.2
326 */
327 public Iterator getVisibleNamespacePrefixes();
328
329 /**
330 * Creates a <code>QName</code> whose namespace URI is the one associated
331 * with the parameter, <code>prefix</code>, in the context of this
332 * <code>SOAPElement</code>. The remaining elements of the new
333 * <code>QName</code> are taken directly from the parameters,
334 * <code>localName</code> and <code>prefix</code>.
335 *
336 * @param localName
337 * a <code>String</code> containing the local part of the name.
338 * @param prefix
339 * a <code>String</code> containing the prefix for the name.
340 *
341 * @return a <code>QName</code> with the specified <code>localName</code>
342 * and <code>prefix</code>, and with a namespace that is associated
343 * with the <code>prefix</code> in the context of this
344 * <code>SOAPElement</code>. This namespace will be the same as
345 * the one that would be returned by
346 * <code>{@link #getNamespaceURI(String)}</code> if it were given
347 * <code>prefix</code> as it's parameter.
348 *
349 * @exception SOAPException if the <code>QName</code> cannot be created.
350 *
351 * @since SAAJ 1.3
352 */
353 public QName createQName(String localName, String prefix)
354 throws SOAPException;
355 /**
356 * Returns the name of this <code>SOAPElement</code> object.
357 *
358 * @return a <code>Name</code> object with the name of this
359 * <code>SOAPElement</code> object
360 */
361 public Name getElementName();
362
363 /**
364 * Returns the qname of this <code>SOAPElement</code> object.
365 *
366 * @return a <code>QName</code> object with the qname of this
367 * <code>SOAPElement</code> object
368 * @see SOAPElement#getElementName()
369 * @since SAAJ 1.3
370 */
371 public QName getElementQName();
372
373 /**
374 * Changes the name of this <code>Element</code> to <code>newName</code> if
375 * possible. SOAP Defined elements such as SOAPEnvelope, SOAPHeader, SOAPBody
376 * etc. cannot have their names changed using this method. Any attempt to do
377 * so will result in a SOAPException being thrown.
378 *<P>
379 * Callers should not rely on the element instance being renamed as is.
380 * Implementations could end up copying the content of the
381 * <code>SOAPElement</code> to a renamed instance.
382 *
383 * @param newName the new name for the <code>Element</code>.
384 *
385 * @exception SOAPException if changing the name of this <code>Element</code>
386 * is not allowed.
387 * @return The renamed Node
388 *
389 * @since SAAJ 1.3
390 */
391 public SOAPElement setElementQName(QName newName) throws SOAPException;
392
393 /**
394 * Removes the attribute with the specified name.
395 *
396 * @param name the <code>Name</code> object with the name of the
397 * attribute to be removed
398 * @return <code>true</code> if the attribute was
399 * removed successfully; <code>false</code> if it was not
400 * @see SOAPElement#removeAttribute(javax.xml.namespace.QName)
401 */
402 public boolean removeAttribute(Name name);
403
404 /**
405 * Removes the attribute with the specified qname.
406 *
407 * @param qname the <code>QName</code> object with the qname of the
408 * attribute to be removed
409 * @return <code>true</code> if the attribute was
410 * removed successfully; <code>false</code> if it was not
411 * @see SOAPElement#removeAttribute(Name)
412 * @since SAAJ 1.3
413 */
414 public boolean removeAttribute(QName qname);
415
416 /**
417 * Removes the namespace declaration corresponding to the given prefix.
418 *
419 * @param prefix a <code>String</code> giving the prefix for which
420 * to search
421 * @return <code>true</code> if the namespace declaration was
422 * removed successfully; <code>false</code> if it was not
423 */
424 public boolean removeNamespaceDeclaration(String prefix);
425
426 /**
427 * Returns an <code>Iterator</code> over all the immediate child
428 * {@link Node}s of this element. This includes <code>javax.xml.soap.Text</code>
429 * objects as well as <code>SOAPElement</code> objects.
430 * <p>
431 * Calling this method may cause child <code>Element</code>,
432 * <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be
479 * <p>
480 * Calling this method may cause child <code>Element</code>,
481 * <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be
482 * replaced by <code>SOAPElement</code>, <code>SOAPHeaderElement</code>,
483 * <code>SOAPBodyElement</code> or <code>javax.xml.soap.Text</code> nodes as
484 * appropriate for the type of this parent node. As a result the calling
485 * application must treat any existing references to these child nodes that
486 * have been obtained through DOM APIs as invalid and either discard them or
487 * refresh them with the values returned by this <code>Iterator</code>. This
488 * behavior can be avoided by calling the equivalent DOM APIs. See
489 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
490 * for more details.
491 *
492 * @param qname a <code>QName</code> object with the qname of the child
493 * elements to be returned
494 *
495 * @return an <code>Iterator</code> object over all the elements
496 * in this <code>SOAPElement</code> object with the
497 * specified qname
498 * @see SOAPElement#getChildElements(Name)
499 * @since SAAJ 1.3
500 */
501 public Iterator getChildElements(QName qname);
502
503 /**
504 * Sets the encoding style for this <code>SOAPElement</code> object
505 * to one specified.
506 *
507 * @param encodingStyle a <code>String</code> giving the encoding style
508 *
509 * @exception IllegalArgumentException if there was a problem in the
510 * encoding style being set.
511 * @exception SOAPException if setting the encodingStyle is invalid for this SOAPElement.
512 * @see #getEncodingStyle
513 */
514 public void setEncodingStyle(String encodingStyle)
515 throws SOAPException;
516 /**
517 * Returns the encoding style for this <code>SOAPElement</code> object.
518 *
519 * @return a <code>String</code> giving the encoding style
|
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 * An object representing an element of a SOAP message that is allowed but not
34 * specifically prescribed by a SOAP specification. This interface serves as the
35 * base interface for those objects that are specifically prescribed by a SOAP
36 * specification.
37 * <p>
38 * Methods in this interface that are required to return SAAJ specific objects
39 * may "silently" replace nodes in the tree as required to successfully return
40 * objects of the correct type. See {@link #getChildElements()} and
41 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
42 * for details.
43 *
44 * @since 1.6
45 */
46 public interface SOAPElement extends Node, org.w3c.dom.Element {
47
48 /**
49 * Creates a new <code>SOAPElement</code> object initialized with the
50 * given <code>Name</code> object and adds the new element to this
51 * <code>SOAPElement</code> object.
52 * <P>
53 * This method may be deprecated in a future release of SAAJ in favor of
54 * addChildElement(javax.xml.namespace.QName)
55 *
56 * @param name a <code>Name</code> object with the XML name for the
57 * new element
58 *
59 * @return the new <code>SOAPElement</code> object that was created
60 * @exception SOAPException if there is an error in creating the
61 * <code>SOAPElement</code> object
62 * @see SOAPElement#addChildElement(javax.xml.namespace.QName)
63 */
64 public SOAPElement addChildElement(Name name) throws SOAPException;
65
66 /**
67 * Creates a new <code>SOAPElement</code> object initialized with the given
68 * <code>QName</code> object and adds the new element to this <code>SOAPElement</code>
69 * object. The <i>namespace</i>, <i>localname</i> and <i>prefix</i> of the new
70 * <code>SOAPElement</code> are all taken from the <code>qname</code> argument.
71 *
72 * @param qname a <code>QName</code> object with the XML name for the
73 * new element
74 *
75 * @return the new <code>SOAPElement</code> object that was created
76 * @exception SOAPException if there is an error in creating the
77 * <code>SOAPElement</code> object
78 * @see SOAPElement#addChildElement(Name)
79 * @since 1.6, SAAJ 1.3
80 */
81 public SOAPElement addChildElement(QName qname) throws SOAPException;
82
83 /**
84 * Creates a new <code>SOAPElement</code> object initialized with the
85 * specified local name and adds the new element to this
86 * <code>SOAPElement</code> object.
87 * The new <code>SOAPElement</code> inherits any in-scope default namespace.
88 *
89 * @param localName a <code>String</code> giving the local name for
90 * the element
91 * @return the new <code>SOAPElement</code> object that was created
92 * @exception SOAPException if there is an error in creating the
93 * <code>SOAPElement</code> object
94 */
95 public SOAPElement addChildElement(String localName) throws SOAPException;
96
97 /**
98 * Creates a new <code>SOAPElement</code> object initialized with the
99 * specified local name and prefix and adds the new element to this
158 * new child
159 *
160 * @exception SOAPException if there was an error in adding this
161 * element as a child
162 *
163 * @return an instance representing the new SOAP element that was
164 * actually added to the tree.
165 */
166 public SOAPElement addChildElement(SOAPElement element)
167 throws SOAPException;
168
169 /**
170 * Detaches all children of this <code>SOAPElement</code>.
171 * <p>
172 * This method is useful for rolling back the construction of partially
173 * completed <code>SOAPHeaders</code> and <code>SOAPBodys</code> in
174 * preparation for sending a fault when an error condition is detected. It
175 * is also useful for recycling portions of a document within a SOAP
176 * message.
177 *
178 * @since 1.6, SAAJ 1.2
179 */
180 public abstract void removeContents();
181
182 /**
183 * Creates a new <code>Text</code> object initialized with the given
184 * <code>String</code> and adds it to this <code>SOAPElement</code> object.
185 *
186 * @param text a <code>String</code> object with the textual content to be added
187 *
188 * @return the <code>SOAPElement</code> object into which
189 * the new <code>Text</code> object was inserted
190 * @exception SOAPException if there is an error in creating the
191 * new <code>Text</code> object or if it is not legal to
192 * attach it as a child to this
193 * <code>SOAPElement</code>
194 */
195 public SOAPElement addTextNode(String text) throws SOAPException;
196
197 /**
198 * Adds an attribute with the specified name and value to this
209 <code>name</code> on this SOAPElement.
210 * @see SOAPElement#addAttribute(javax.xml.namespace.QName, String)
211 */
212 public SOAPElement addAttribute(Name name, String value)
213 throws SOAPException;
214
215 /**
216 * Adds an attribute with the specified name and value to this
217 * <code>SOAPElement</code> object.
218 *
219 * @param qname a <code>QName</code> object with the name of the attribute
220 * @param value a <code>String</code> giving the value of the attribute
221 * @return the <code>SOAPElement</code> object into which the attribute was
222 * inserted
223 *
224 * @exception SOAPException if there is an error in creating the
225 * Attribute, or it is invalid to set
226 an attribute with <code>QName</code>
227 <code>qname</code> on this SOAPElement.
228 * @see SOAPElement#addAttribute(Name, String)
229 * @since 1.6, SAAJ 1.3
230 */
231 public SOAPElement addAttribute(QName qname, String value)
232 throws SOAPException;
233
234 /**
235 * Adds a namespace declaration with the specified prefix and URI to this
236 * <code>SOAPElement</code> object.
237 *
238 * @param prefix a <code>String</code> giving the prefix of the namespace
239 * @param uri a <code>String</code> giving the uri of the namespace
240 * @return the <code>SOAPElement</code> object into which this
241 * namespace declaration was inserted.
242 *
243 * @exception SOAPException if there is an error in creating the
244 * namespace
245 */
246 public SOAPElement addNamespaceDeclaration(String prefix, String uri)
247 throws SOAPException;
248
249 /**
250 * Returns the value of the attribute with the specified name.
251 *
252 * @param name a <code>Name</code> object with the name of the attribute
253 * @return a <code>String</code> giving the value of the specified
254 * attribute, Null if there is no such attribute
255 * @see SOAPElement#getAttributeValue(javax.xml.namespace.QName)
256 */
257 public String getAttributeValue(Name name);
258
259 /**
260 * Returns the value of the attribute with the specified qname.
261 *
262 * @param qname a <code>QName</code> object with the qname of the attribute
263 * @return a <code>String</code> giving the value of the specified
264 * attribute, Null if there is no such attribute
265 * @see SOAPElement#getAttributeValue(Name)
266 * @since 1.6, SAAJ 1.3
267 */
268 public String getAttributeValue(QName qname);
269
270 /**
271 * Returns an <code>Iterator</code> over all of the attribute
272 * <code>Name</code> objects in this
273 * <code>SOAPElement</code> object. The iterator can be used to get
274 * the attribute names, which can then be passed to the method
275 * <code>getAttributeValue</code> to retrieve the value of each
276 * attribute.
277 *
278 * @see SOAPElement#getAllAttributesAsQNames()
279 * @return an iterator over the names of the attributes
280 */
281 public Iterator getAllAttributes();
282
283 /**
284 * Returns an <code>Iterator</code> over all of the attributes
285 * in this <code>SOAPElement</code> as <code>QName</code> objects.
286 * The iterator can be used to get the attribute QName, which can then
287 * be passed to the method <code>getAttributeValue</code> to retrieve
288 * the value of each attribute.
289 *
290 * @return an iterator over the QNames of the attributes
291 * @see SOAPElement#getAllAttributes()
292 * @since 1.6, SAAJ 1.3
293 */
294 public Iterator getAllAttributesAsQNames();
295
296
297 /**
298 * Returns the URI of the namespace that has the given prefix.
299 *
300 * @param prefix a <code>String</code> giving the prefix of the namespace
301 * for which to search
302 * @return a <code>String</code> with the uri of the namespace that has
303 * the given prefix
304 */
305 public String getNamespaceURI(String prefix);
306
307 /**
308 * Returns an <code>Iterator</code> over the namespace prefix
309 * <code>String</code>s declared by this element. The prefixes returned by
310 * this iterator can be passed to the method
311 * <code>getNamespaceURI</code> to retrieve the URI of each namespace.
312 *
313 * @return an iterator over the namespace prefixes in this
314 * <code>SOAPElement</code> object
315 */
316 public Iterator getNamespacePrefixes();
317
318 /**
319 * Returns an <code>Iterator</code> over the namespace prefix
320 * <code>String</code>s visible to this element. The prefixes returned by
321 * this iterator can be passed to the method
322 * <code>getNamespaceURI</code> to retrieve the URI of each namespace.
323 *
324 * @return an iterator over the namespace prefixes are within scope of this
325 * <code>SOAPElement</code> object
326 *
327 * @since 1.6, SAAJ 1.2
328 */
329 public Iterator getVisibleNamespacePrefixes();
330
331 /**
332 * Creates a <code>QName</code> whose namespace URI is the one associated
333 * with the parameter, <code>prefix</code>, in the context of this
334 * <code>SOAPElement</code>. The remaining elements of the new
335 * <code>QName</code> are taken directly from the parameters,
336 * <code>localName</code> and <code>prefix</code>.
337 *
338 * @param localName
339 * a <code>String</code> containing the local part of the name.
340 * @param prefix
341 * a <code>String</code> containing the prefix for the name.
342 *
343 * @return a <code>QName</code> with the specified <code>localName</code>
344 * and <code>prefix</code>, and with a namespace that is associated
345 * with the <code>prefix</code> in the context of this
346 * <code>SOAPElement</code>. This namespace will be the same as
347 * the one that would be returned by
348 * <code>{@link #getNamespaceURI(String)}</code> if it were given
349 * <code>prefix</code> as it's parameter.
350 *
351 * @exception SOAPException if the <code>QName</code> cannot be created.
352 *
353 * @since 1.6, SAAJ 1.3
354 */
355 public QName createQName(String localName, String prefix)
356 throws SOAPException;
357 /**
358 * Returns the name of this <code>SOAPElement</code> object.
359 *
360 * @return a <code>Name</code> object with the name of this
361 * <code>SOAPElement</code> object
362 */
363 public Name getElementName();
364
365 /**
366 * Returns the qname of this <code>SOAPElement</code> object.
367 *
368 * @return a <code>QName</code> object with the qname of this
369 * <code>SOAPElement</code> object
370 * @see SOAPElement#getElementName()
371 * @since 1.6, SAAJ 1.3
372 */
373 public QName getElementQName();
374
375 /**
376 * Changes the name of this <code>Element</code> to <code>newName</code> if
377 * possible. SOAP Defined elements such as SOAPEnvelope, SOAPHeader, SOAPBody
378 * etc. cannot have their names changed using this method. Any attempt to do
379 * so will result in a SOAPException being thrown.
380 *<P>
381 * Callers should not rely on the element instance being renamed as is.
382 * Implementations could end up copying the content of the
383 * <code>SOAPElement</code> to a renamed instance.
384 *
385 * @param newName the new name for the <code>Element</code>.
386 *
387 * @exception SOAPException if changing the name of this <code>Element</code>
388 * is not allowed.
389 * @return The renamed Node
390 *
391 * @since 1.6, SAAJ 1.3
392 */
393 public SOAPElement setElementQName(QName newName) throws SOAPException;
394
395 /**
396 * Removes the attribute with the specified name.
397 *
398 * @param name the <code>Name</code> object with the name of the
399 * attribute to be removed
400 * @return <code>true</code> if the attribute was
401 * removed successfully; <code>false</code> if it was not
402 * @see SOAPElement#removeAttribute(javax.xml.namespace.QName)
403 */
404 public boolean removeAttribute(Name name);
405
406 /**
407 * Removes the attribute with the specified qname.
408 *
409 * @param qname the <code>QName</code> object with the qname of the
410 * attribute to be removed
411 * @return <code>true</code> if the attribute was
412 * removed successfully; <code>false</code> if it was not
413 * @see SOAPElement#removeAttribute(Name)
414 * @since 1.6, SAAJ 1.3
415 */
416 public boolean removeAttribute(QName qname);
417
418 /**
419 * Removes the namespace declaration corresponding to the given prefix.
420 *
421 * @param prefix a <code>String</code> giving the prefix for which
422 * to search
423 * @return <code>true</code> if the namespace declaration was
424 * removed successfully; <code>false</code> if it was not
425 */
426 public boolean removeNamespaceDeclaration(String prefix);
427
428 /**
429 * Returns an <code>Iterator</code> over all the immediate child
430 * {@link Node}s of this element. This includes <code>javax.xml.soap.Text</code>
431 * objects as well as <code>SOAPElement</code> objects.
432 * <p>
433 * Calling this method may cause child <code>Element</code>,
434 * <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be
481 * <p>
482 * Calling this method may cause child <code>Element</code>,
483 * <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be
484 * replaced by <code>SOAPElement</code>, <code>SOAPHeaderElement</code>,
485 * <code>SOAPBodyElement</code> or <code>javax.xml.soap.Text</code> nodes as
486 * appropriate for the type of this parent node. As a result the calling
487 * application must treat any existing references to these child nodes that
488 * have been obtained through DOM APIs as invalid and either discard them or
489 * refresh them with the values returned by this <code>Iterator</code>. This
490 * behavior can be avoided by calling the equivalent DOM APIs. See
491 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
492 * for more details.
493 *
494 * @param qname a <code>QName</code> object with the qname of the child
495 * elements to be returned
496 *
497 * @return an <code>Iterator</code> object over all the elements
498 * in this <code>SOAPElement</code> object with the
499 * specified qname
500 * @see SOAPElement#getChildElements(Name)
501 * @since 1.6, SAAJ 1.3
502 */
503 public Iterator getChildElements(QName qname);
504
505 /**
506 * Sets the encoding style for this <code>SOAPElement</code> object
507 * to one specified.
508 *
509 * @param encodingStyle a <code>String</code> giving the encoding style
510 *
511 * @exception IllegalArgumentException if there was a problem in the
512 * encoding style being set.
513 * @exception SOAPException if setting the encodingStyle is invalid for this SOAPElement.
514 * @see #getEncodingStyle
515 */
516 public void setEncodingStyle(String encodingStyle)
517 throws SOAPException;
518 /**
519 * Returns the encoding style for this <code>SOAPElement</code> object.
520 *
521 * @return a <code>String</code> giving the encoding style
|