API Overview API Index Package Overview Direct link to this page
JDK 1.6
  javax.xml.soap. SOAPElement View Javadoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509

/*
 * $Id: SOAPElement.java,v 1.18 2005/12/07 07:25:37 vj135062 Exp $
 * $Revision: 1.18 $
 * $Date: 2005/12/07 07:25:37 $
 */

/*
 * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */
package javax.xml.soap;

import java.util.Iterator;

import javax.xml.namespace.QName;

/**
 * An object representing an element of a SOAP message that is allowed but not
 * specifically prescribed by a SOAP specification. This interface serves as the
 * base interface for those objects that are specifically prescribed by a SOAP
 * specification.
 * <p>
 * Methods in this interface that are required to return SAAJ specific objects
 * may "silently" replace nodes in the tree as required to successfully return
 * objects of the correct type. See {@link #getChildElements()} and 
 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
 * for details.
 */
public interface SOAPElement extends Node, org.w3c.dom.Element {

    /**
     * Creates a new <code>SOAPElement</code> object initialized with the
     * given <code>Name</code> object and adds the new element to this
     * <code>SOAPElement</code> object.
     * <P>
     * This method may be deprecated in a future release of SAAJ in favor of 
     * addChildElement(javax.xml.namespace.QName)
     *
     * @param name a <code>Name</code> object with the XML name for the
     *        new element
     *
     * @return the new <code>SOAPElement</code> object that was created
     * @exception SOAPException if there is an error in creating the
     *                          <code>SOAPElement</code> object
     * @see SOAPElement#addChildElement(javax.xml.namespace.QName)
     */
    public SOAPElement addChildElement(Name name) throws SOAPException;

    /**
     * Creates a new <code>SOAPElement</code> object initialized with the given 
     * <code>QName</code> object and adds the new element to this <code>SOAPElement</code>
     *  object. The  <i>namespace</i>, <i>localname</i> and <i>prefix</i> of the new 
     * <code>SOAPElement</code> are all taken  from the <code>qname</code> argument.
     * 
     * @param qname a <code>QName</code> object with the XML name for the
     *        new element
     *
     * @return the new <code>SOAPElement</code> object that was created
     * @exception SOAPException if there is an error in creating the
     *                          <code>SOAPElement</code> object
     * @see SOAPElement#addChildElement(Name)
     * @since SAAJ 1.3
     */
    public SOAPElement addChildElement(QName qname) throws SOAPException;

    /**
     * Creates a new <code>SOAPElement</code> object initialized with the
     * specified local name and adds the new element to this
     * <code>SOAPElement</code> object.  
     * The new  <code>SOAPElement</code> inherits any in-scope default namespace.
     *
     * @param localName a <code>String</code> giving the local name for
     *          the element
     * @return the new <code>SOAPElement</code> object that was created
     * @exception SOAPException if there is an error in creating the
     *                          <code>SOAPElement</code> object
     */
    public SOAPElement addChildElement(String localName) throws SOAPException;

    /**
     * Creates a new <code>SOAPElement</code> object initialized with the
     * specified local name and prefix and adds the new element to this
     * <code>SOAPElement</code> object.
     * 
     * @param localName a <code>String</code> giving the local name for
     *        the new element
     * @param prefix a <code>String</code> giving the namespace prefix for
     *        the new element
     *
     * @return the new <code>SOAPElement</code> object that was created
     * @exception SOAPException if the <code>prefix</code> is not valid in the
     *         context of this <code>SOAPElement</code> or  if there is an error in creating the
     *                          <code>SOAPElement</code> object
     */
    public SOAPElement addChildElement(String localName, String prefix)
        throws SOAPException;

    /**
     * Creates a new <code>SOAPElement</code> object initialized with the
     * specified local name, prefix, and URI and adds the new element to this
     * <code>SOAPElement</code> object.
     *
     * @param localName a <code>String</code> giving the local name for
     *        the new element
     * @param prefix a <code>String</code> giving the namespace prefix for
     *        the new element
     * @param uri a <code>String</code> giving the URI of the namespace
     *        to which the new element belongs
     *
     * @return the new <code>SOAPElement</code> object that was created
     * @exception SOAPException if there is an error in creating the
     *                          <code>SOAPElement</code> object
     */
    public SOAPElement addChildElement(String localName, String prefix,
                                       String uri)
        throws SOAPException;

    /**
     * Add a <code>SOAPElement</code> as a child of this
     * <code>SOAPElement</code> instance. The <code>SOAPElement</code>
     * is expected to be created by a
     * <code>SOAPFactory</code>. Callers should not rely on the
     * element instance being added as is into the XML
     * tree. Implementations could end up copying the content
     * of the <code>SOAPElement</code> passed into an instance of
     * a different <code>SOAPElement</code> implementation. For
     * instance if <code>addChildElement()</code> is called on a
     * <code>SOAPHeader</code>, <code>element</code> will be copied
     * into an instance of a <code>SOAPHeaderElement</code>.
     *
     * <P>The fragment rooted in <code>element</code> is either added
     * as a whole or not at all, if there was an error.
     *
     * <P>The fragment rooted in <code>element</code> cannot contain
     * elements named "Envelope", "Header" or "Body" and in the SOAP
     * namespace. Any namespace prefixes present in the fragment
     * should be fully resolved using appropriate namespace
     * declarations within the fragment itself.
     *
     * @param element the <code>SOAPElement</code> to be added as a
     *                new child
     *
     * @exception SOAPException if there was an error in adding this
     *                          element as a child
     *
     * @return an instance representing the new SOAP element that was
     *         actually added to the tree.
     */
    public SOAPElement addChildElement(SOAPElement element)
        throws SOAPException;

    /**
     * Detaches all children of this <code>SOAPElement</code>.
     * <p>
     * This method is useful for rolling back the construction of partially 
     * completed <code>SOAPHeaders</code> and <code>SOAPBodys</code> in 
     * preparation for sending a fault when an error condition is detected. It 
     * is also useful for recycling portions of a document within a SOAP 
     * message.
     * 
     * @since SAAJ 1.2
     */
    public abstract void removeContents();

    /**
     * Creates a new <code>Text</code> object initialized with the given
     * <code>String</code> and adds it to this <code>SOAPElement</code> object.
     *
     * @param text a <code>String</code> object with the textual content to be added
     *
     * @return the <code>SOAPElement</code> object into which
     *         the new <code>Text</code> object was inserted
     * @exception SOAPException if there is an error in creating the
     *                    new <code>Text</code> object or if it is not legal to
     *                      attach it as a child to this 
     *                      <code>SOAPElement</code>
     */
    public SOAPElement addTextNode(String text) throws SOAPException;

    /**
     * Adds an attribute with the specified name and value to this
     * <code>SOAPElement</code> object.
     *
     * @param name a <code>Name</code> object with the name of the attribute
     * @param value a <code>String</code> giving the value of the attribute
     * @return the <code>SOAPElement</code> object into which the attribute was
     *         inserted
     *
     * @exception SOAPException if there is an error in creating the
     *                          Attribute, or it is invalid to set 
                                an attribute with <code>Name</code> 
                                 <code>name</code> on this SOAPElement.
     * @see SOAPElement#addAttribute(javax.xml.namespace.QName, String)
     */
    public SOAPElement addAttribute(Name name, String value)
        throws SOAPException;

    /**
     * Adds an attribute with the specified name and value to this
     * <code>SOAPElement</code> object.
     *
     * @param qname a <code>QName</code> object with the name of the attribute
     * @param value a <code>String</code> giving the value of the attribute
     * @return the <code>SOAPElement</code> object into which the attribute was
     *         inserted
     *
     * @exception SOAPException if there is an error in creating the
     *                          Attribute, or it is invalid to set
                                an attribute with <code>QName</code> 
                                <code>qname</code> on this SOAPElement.
     * @see SOAPElement#addAttribute(Name, String)
     * @since SAAJ 1.3
     */
    public SOAPElement addAttribute(QName qname, String value)
        throws SOAPException;

    /**
     * Adds a namespace declaration with the specified prefix and URI to this
     * <code>SOAPElement</code> object.
     *
     * @param prefix a <code>String</code> giving the prefix of the namespace
     * @param uri a <code>String</code> giving the uri of the namespace
     * @return the <code>SOAPElement</code> object into which this
     *          namespace declaration was inserted.
     *
     * @exception SOAPException if there is an error in creating the
     *                          namespace
     */
    public SOAPElement addNamespaceDeclaration(String prefix, String uri)
        throws SOAPException;

    /**
     * Returns the value of the attribute with the specified name.
     *
     * @param name a <code>Name</code> object with the name of the attribute
     * @return a <code>String</code> giving the value of the specified
     *         attribute, Null if there is no such attribute
     * @see SOAPElement#getAttributeValue(javax.xml.namespace.QName)
     */
    public String getAttributeValue(Name name);
    
    /**
     * Returns the value of the attribute with the specified qname.
     *
     * @param qname a <code>QName</code> object with the qname of the attribute
     * @return a <code>String</code> giving the value of the specified
     *         attribute, Null if there is no such attribute
     * @see SOAPElement#getAttributeValue(Name)
     * @since SAAJ 1.3
     */
    public String getAttributeValue(QName qname);

    /**
     * Returns an <code>Iterator</code> over all of the attribute 
     * <code>Name</code> objects in this
     * <code>SOAPElement</code> object. The iterator can be used to get
     * the attribute names, which can then be passed to the method
     * <code>getAttributeValue</code> to retrieve the value of each
     * attribute.
     *
     * @see SOAPElement#getAllAttributesAsQNames()
     * @return an iterator over the names of the attributes
     */
    public Iterator getAllAttributes();

    /**
     * Returns an <code>Iterator</code> over all of the attributes
     * in this <code>SOAPElement</code>  as <code>QName</code> objects. 
     * The iterator can be used to get the attribute QName, which can then 
     * be passed to the method <code>getAttributeValue</code> to retrieve 
     * the value of each attribute.
     *
     * @return an iterator over the QNames of the attributes
     * @see SOAPElement#getAllAttributes()
     * @since SAAJ 1.3
     */
    public Iterator getAllAttributesAsQNames();

    
    /**
     * Returns the URI of the namespace that has the given prefix.
     *
     * @param prefix a <code>String</code> giving the prefix of the namespace
     *        for which to search 
     * @return a <code>String</code> with the uri of the namespace that has
     *        the given prefix
     */
    public String getNamespaceURI(String prefix);

    /**
     * Returns an <code>Iterator</code> over the namespace prefix
     * <code>String</code>s declared by this element. The prefixes returned by
     * this iterator can be passed to the method
     * <code>getNamespaceURI</code> to retrieve the URI of each namespace.
     *
     * @return an iterator over the namespace prefixes in this
     *         <code>SOAPElement</code> object
     */
    public Iterator getNamespacePrefixes();

    /**
     * Returns an <code>Iterator</code> over the namespace prefix
     * <code>String</code>s visible to this element. The prefixes returned by
     * this iterator can be passed to the method
     * <code>getNamespaceURI</code> to retrieve the URI of each namespace.
     *
     * @return an iterator over the namespace prefixes are within scope of this
     *         <code>SOAPElement</code> object
     * 
     * @since SAAJ 1.2
     */
    public Iterator getVisibleNamespacePrefixes();
    
    /**
     * Creates a <code>QName</code> whose namespace URI is the one associated
     * with the parameter, <code>prefix</code>, in the context of this
     * <code>SOAPElement</code>. The remaining elements of the new 
     * <code>QName</code> are taken directly from the parameters, 
     * <code>localName</code> and <code>prefix</code>. 
     * 
     * @param localName
     *          a <code>String</code> containing the local part of the name.
     * @param prefix
     *          a <code>String</code> containing the prefix for the name.
     * 
     * @return a <code>QName</code> with the specified <code>localName</code>
     *          and <code>prefix</code>, and with a namespace that is associated
     *          with the <code>prefix</code> in the context of this 
     *          <code>SOAPElement</code>. This namespace will be the same as
     *          the one that would be returned by 
     *          <code>{@link #getNamespaceURI(String)}</code> if it were given 
     *          <code>prefix</code> as it's parameter.
     * 
     * @exception SOAPException if the <code>QName</code> cannot be created.
     * 
     * @since SAAJ 1.3 
     */
    public QName createQName(String localName, String prefix)
        throws SOAPException;
    /**
     * Returns the name of this <code>SOAPElement</code> object.
     *
     * @return a <code>Name</code> object with the name of this
     *         <code>SOAPElement</code> object
     */
    public Name getElementName();
    
    /**
     * Returns the qname of this <code>SOAPElement</code> object.
     *
     * @return a <code>QName</code> object with the qname of this
     *         <code>SOAPElement</code> object
     * @see SOAPElement#getElementName()
     * @since SAAJ 1.3
     */
    public QName getElementQName();

    /**
    * Changes the name of this <code>Element</code> to <code>newName</code> if 
    * possible. SOAP Defined elements such as SOAPEnvelope, SOAPHeader, SOAPBody 
    * etc. cannot have their names changed using this method. Any attempt to do 
    * so will result in a  SOAPException being thrown.
    *<P>
    * Callers should not rely on the element instance being renamed as is. 
    * Implementations could end up copying the content of the 
    * <code>SOAPElement</code> to a renamed instance.
    * 
    * @param newName the new name for the <code>Element</code>.
    * 
    * @exception SOAPException if changing the name of this <code>Element</code>
    *                          is not allowed.
    * @return The renamed Node
    * 
    * @since SAAJ 1.3
    */
   public SOAPElement setElementQName(QName newName) throws SOAPException;
    
   /**
     * Removes the attribute with the specified name.
     *
     * @param name the <code>Name</code> object with the name of the
     *        attribute to be removed
     * @return <code>true</code> if the attribute was
     *         removed successfully; <code>false</code> if it was not
     * @see SOAPElement#removeAttribute(javax.xml.namespace.QName)
     */
    public boolean removeAttribute(Name name);

    /**
     * Removes the attribute with the specified qname.
     *
     * @param qname the <code>QName</code> object with the qname of the
     *        attribute to be removed
     * @return <code>true</code> if the attribute was
     *         removed successfully; <code>false</code> if it was not
     * @see SOAPElement#removeAttribute(Name)
     * @since SAAJ 1.3
     */
    public boolean removeAttribute(QName qname);

    /**
     * Removes the namespace declaration corresponding to the given prefix.
     *
     * @param prefix a <code>String</code> giving the prefix for which
     *        to search
     * @return <code>true</code> if the namespace declaration was
     *         removed successfully; <code>false</code> if it was not
     */
    public boolean removeNamespaceDeclaration(String prefix);

    /**
     * Returns an <code>Iterator</code> over all the immediate child
     * {@link Node}s of this element. This includes <code>javax.xml.soap.Text</code>
     * objects as well as <code>SOAPElement</code> objects.
     * <p>
     * Calling this method may cause child <code>Element</code>, 
     * <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be 
     * replaced by <code>SOAPElement</code>, <code>SOAPHeaderElement</code>, 
     * <code>SOAPBodyElement</code> or <code>javax.xml.soap.Text</code> nodes as
     * appropriate for the type of this parent node. As a result the calling 
     * application must treat any existing references to these child nodes that 
     * have been obtained through DOM APIs as invalid and either discard them or
     * refresh them with the values returned by this <code>Iterator</code>. This 
     * behavior can be avoided by calling the equivalent DOM APIs. See
     * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
     * for more details.
     *
     * @return an iterator with the content of this <code>SOAPElement</code>
     *         object
     */
    public Iterator getChildElements();

    /**
     * Returns an <code>Iterator</code> over all the immediate child
     * {@link Node}s of this element with the specified name. All of these 
     * children will be <code>SOAPElement</code> nodes.
     * <p>
     * Calling this method may cause child <code>Element</code>, 
     * <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be 
     * replaced by <code>SOAPElement</code>, <code>SOAPHeaderElement</code>, 
     * <code>SOAPBodyElement</code> or <code>javax.xml.soap.Text</code> nodes as
     * appropriate for the type of this parent node. As a result the calling 
     * application must treat any existing references to these child nodes that 
     * have been obtained through DOM APIs as invalid and either discard them or
     * refresh them with the values returned by this <code>Iterator</code>. This 
     * behavior can be avoided by calling the equivalent DOM APIs. See
     * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
     * for more details.
     * 
     * @param name a <code>Name</code> object with the name of the child
     *        elements to be returned
     *
     * @return an <code>Iterator</code> object over all the elements
     *         in this <code>SOAPElement</code> object with the
     *         specified name
     * @see SOAPElement#getChildElements(javax.xml.namespace.QName)
     */
    public Iterator getChildElements(Name name);

    /**
     * Returns an <code>Iterator</code> over all the immediate child
     * {@link Node}s of this element with the specified qname. All of these 
     * children will be <code>SOAPElement</code> nodes.
     * <p>
     * Calling this method may cause child <code>Element</code>, 
     * <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be 
     * replaced by <code>SOAPElement</code>, <code>SOAPHeaderElement</code>, 
     * <code>SOAPBodyElement</code> or <code>javax.xml.soap.Text</code> nodes as
     * appropriate for the type of this parent node. As a result the calling 
     * application must treat any existing references to these child nodes that 
     * have been obtained through DOM APIs as invalid and either discard them or
     * refresh them with the values returned by this <code>Iterator</code>. This 
     * behavior can be avoided by calling the equivalent DOM APIs. See
     * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
     * for more details.
     * 
     * @param qname a <code>QName</code> object with the qname of the child
     *        elements to be returned
     *
     * @return an <code>Iterator</code> object over all the elements
     *         in this <code>SOAPElement</code> object with the
     *         specified qname
     * @see SOAPElement#getChildElements(Name)
     * @since SAAJ 1.3     
     */
    public Iterator getChildElements(QName qname);

    /**
     * Sets the encoding style for this <code>SOAPElement</code> object
     * to one specified.
     *
     * @param encodingStyle a <code>String</code> giving the encoding style
     *
     * @exception IllegalArgumentException if there was a problem in the
     *            encoding style being set.
     * @exception SOAPException if setting the encodingStyle is invalid for this SOAPElement.
     * @see #getEncodingStyle
     */
    public void setEncodingStyle(String encodingStyle)
        throws SOAPException;
    /**
     * Returns the encoding style for this <code>SOAPElement</code> object.
     *
     * @return a <code>String</code> giving the encoding style
     *
     * @see #setEncodingStyle
     */
    public String getEncodingStyle();
}

Generated By: JavaOnTracks Doclet 0.1.4     ©Thibaut Colar