1 /*
2 * $Id: SOAPElement.java,v 1.18 2005/12/07 07:25:37 vj135062 Exp $
3 * $Revision: 1.18 $
4 * $Date: 2005/12/07 07:25:37 $
5 */
6
7 /*
8 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
9 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
10 *
11 * This code is free software; you can redistribute it and/or modify it
12 * under the terms of the GNU General Public License version 2 only, as
13 * published by the Free Software Foundation. Sun designates this
14 * particular file as subject to the "Classpath" exception as provided
15 * by Sun in the LICENSE file that accompanied this code.
16 *
17 * This code is distributed in the hope that it will be useful, but WITHOUT
18 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
20 * version 2 for more details (a copy is included in the LICENSE file that
21 * accompanied this code).
22 *
23 * You should have received a copy of the GNU General Public License version
24 * 2 along with this work; if not, write to the Free Software Foundation,
25 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
26 *
27 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
28 * CA 95054 USA or visit www.sun.com if you need additional information or
29 * have any questions.
30 */
31 package javax.xml.soap;
32
33 import java.util.Iterator;
34
35 import javax.xml.namespace.QName;
36
37 /**
38 * An object representing an element of a SOAP message that is allowed but not
39 * specifically prescribed by a SOAP specification. This interface serves as the
40 * base interface for those objects that are specifically prescribed by a SOAP
41 * specification.
42 * <p>
43 * Methods in this interface that are required to return SAAJ specific objects
44 * may "silently" replace nodes in the tree as required to successfully return
45 * objects of the correct type. See {@link #getChildElements()} and
46 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
47 * for details.
48 */
49 public interface SOAPElement extends Node, org.w3c.dom.Element {
50
51 /**
52 * Creates a new <code>SOAPElement</code> object initialized with the
53 * given <code>Name</code> object and adds the new element to this
54 * <code>SOAPElement</code> object.
55 * <P>
56 * This method may be deprecated in a future release of SAAJ in favor of
57 * addChildElement(javax.xml.namespace.QName)
58 *
59 * @param name a <code>Name</code> object with the XML name for the
60 * new element
61 *
62 * @return the new <code>SOAPElement</code> object that was created
63 * @exception SOAPException if there is an error in creating the
64 * <code>SOAPElement</code> object
65 * @see SOAPElement#addChildElement(javax.xml.namespace.QName)
66 */
67 public SOAPElement addChildElement(Name name) throws SOAPException;
68
69 /**
70 * Creates a new <code>SOAPElement</code> object initialized with the given
71 * <code>QName</code> object and adds the new element to this <code>SOAPElement</code>
72 * object. The <i>namespace</i>, <i>localname</i> and <i>prefix</i> of the new
73 * <code>SOAPElement</code> are all taken from the <code>qname</code> argument.
74 *
75 * @param qname a <code>QName</code> object with the XML name for the
76 * new element
77 *
78 * @return the new <code>SOAPElement</code> object that was created
79 * @exception SOAPException if there is an error in creating the
80 * <code>SOAPElement</code> object
81 * @see SOAPElement#addChildElement(Name)
82 * @since SAAJ 1.3
83 */
84 public SOAPElement addChildElement(QName qname) throws SOAPException;
85
86 /**
87 * Creates a new <code>SOAPElement</code> object initialized with the
88 * specified local name and adds the new element to this
89 * <code>SOAPElement</code> object.
90 * The new <code>SOAPElement</code> inherits any in-scope default namespace.
91 *
92 * @param localName a <code>String</code> giving the local name for
93 * the element
94 * @return the new <code>SOAPElement</code> object that was created
95 * @exception SOAPException if there is an error in creating the
96 * <code>SOAPElement</code> object
97 */
98 public SOAPElement addChildElement(String localName) throws SOAPException;
99
100 /**
101 * Creates a new <code>SOAPElement</code> object initialized with the
102 * specified local name and prefix and adds the new element to this
103 * <code>SOAPElement</code> object.
104 *
105 * @param localName a <code>String</code> giving the local name for
106 * the new element
107 * @param prefix a <code>String</code> giving the namespace prefix for
108 * the new element
109 *
110 * @return the new <code>SOAPElement</code> object that was created
111 * @exception SOAPException if the <code>prefix</code> is not valid in the
112 * context of this <code>SOAPElement</code> or if there is an error in creating the
113 * <code>SOAPElement</code> object
114 */
115 public SOAPElement addChildElement(String localName, String prefix)
116 throws SOAPException;
117
118 /**
119 * Creates a new <code>SOAPElement</code> object initialized with the
120 * specified local name, prefix, and URI and adds the new element to this
121 * <code>SOAPElement</code> object.
122 *
123 * @param localName a <code>String</code> giving the local name for
124 * the new element
125 * @param prefix a <code>String</code> giving the namespace prefix for
126 * the new element
127 * @param uri a <code>String</code> giving the URI of the namespace
128 * to which the new element belongs
129 *
130 * @return the new <code>SOAPElement</code> object that was created
131 * @exception SOAPException if there is an error in creating the
132 * <code>SOAPElement</code> object
133 */
134 public SOAPElement addChildElement(String localName, String prefix,
135 String uri)
136 throws SOAPException;
137
138 /**
139 * Add a <code>SOAPElement</code> as a child of this
140 * <code>SOAPElement</code> instance. The <code>SOAPElement</code>
141 * is expected to be created by a
142 * <code>SOAPFactory</code>. Callers should not rely on the
143 * element instance being added as is into the XML
144 * tree. Implementations could end up copying the content
145 * of the <code>SOAPElement</code> passed into an instance of
146 * a different <code>SOAPElement</code> implementation. For
147 * instance if <code>addChildElement()</code> is called on a
148 * <code>SOAPHeader</code>, <code>element</code> will be copied
149 * into an instance of a <code>SOAPHeaderElement</code>.
150 *
151 * <P>The fragment rooted in <code>element</code> is either added
152 * as a whole or not at all, if there was an error.
153 *
154 * <P>The fragment rooted in <code>element</code> cannot contain
155 * elements named "Envelope", "Header" or "Body" and in the SOAP
156 * namespace. Any namespace prefixes present in the fragment
157 * should be fully resolved using appropriate namespace
158 * declarations within the fragment itself.
159 *
160 * @param element the <code>SOAPElement</code> to be added as a
161 * new child
162 *
163 * @exception SOAPException if there was an error in adding this
164 * element as a child
165 *
166 * @return an instance representing the new SOAP element that was
167 * actually added to the tree.
168 */
169 public SOAPElement addChildElement(SOAPElement element)
170 throws SOAPException;
171
172 /**
173 * Detaches all children of this <code>SOAPElement</code>.
174 * <p>
175 * This method is useful for rolling back the construction of partially
176 * completed <code>SOAPHeaders</code> and <code>SOAPBodys</code> in
177 * preparation for sending a fault when an error condition is detected. It
178 * is also useful for recycling portions of a document within a SOAP
179 * message.
180 *
181 * @since SAAJ 1.2
182 */
183 public abstract void removeContents();
184
185 /**
186 * Creates a new <code>Text</code> object initialized with the given
187 * <code>String</code> and adds it to this <code>SOAPElement</code> object.
188 *
189 * @param text a <code>String</code> object with the textual content to be added
190 *
191 * @return the <code>SOAPElement</code> object into which
192 * the new <code>Text</code> object was inserted
193 * @exception SOAPException if there is an error in creating the
194 * new <code>Text</code> object or if it is not legal to
195 * attach it as a child to this
196 * <code>SOAPElement</code>
197 */
198 public SOAPElement addTextNode(String text) throws SOAPException;
199
200 /**
201 * Adds an attribute with the specified name and value to this
202 * <code>SOAPElement</code> object.
203 *
204 * @param name a <code>Name</code> object with the name of the attribute
205 * @param value a <code>String</code> giving the value of the attribute
206 * @return the <code>SOAPElement</code> object into which the attribute was
207 * inserted
208 *
209 * @exception SOAPException if there is an error in creating the
210 * Attribute, or it is invalid to set
211 an attribute with <code>Name</code>
212 <code>name</code> on this SOAPElement.
213 * @see SOAPElement#addAttribute(javax.xml.namespace.QName, String)
214 */
215 public SOAPElement addAttribute(Name name, String value)
216 throws SOAPException;
217
218 /**
219 * Adds an attribute with the specified name and value to this
220 * <code>SOAPElement</code> object.
221 *
222 * @param qname a <code>QName</code> object with the name of the attribute
223 * @param value a <code>String</code> giving the value of the attribute
224 * @return the <code>SOAPElement</code> object into which the attribute was
225 * inserted
226 *
227 * @exception SOAPException if there is an error in creating the
228 * Attribute, or it is invalid to set
229 an attribute with <code>QName</code>
230 <code>qname</code> on this SOAPElement.
231 * @see SOAPElement#addAttribute(Name, String)
232 * @since SAAJ 1.3
233 */
234 public SOAPElement addAttribute(QName qname, String value)
235 throws SOAPException;
236
237 /**
238 * Adds a namespace declaration with the specified prefix and URI to this
239 * <code>SOAPElement</code> object.
240 *
241 * @param prefix a <code>String</code> giving the prefix of the namespace
242 * @param uri a <code>String</code> giving the uri of the namespace
243 * @return the <code>SOAPElement</code> object into which this
244 * namespace declaration was inserted.
245 *
246 * @exception SOAPException if there is an error in creating the
247 * namespace
248 */
249 public SOAPElement addNamespaceDeclaration(String prefix, String uri)
250 throws SOAPException;
251
252 /**
253 * Returns the value of the attribute with the specified name.
254 *
255 * @param name a <code>Name</code> object with the name of the attribute
256 * @return a <code>String</code> giving the value of the specified
257 * attribute, Null if there is no such attribute
258 * @see SOAPElement#getAttributeValue(javax.xml.namespace.QName)
259 */
260 public String getAttributeValue(Name name);
261
262 /**
263 * Returns the value of the attribute with the specified qname.
264 *
265 * @param qname a <code>QName</code> object with the qname of the attribute
266 * @return a <code>String</code> giving the value of the specified
267 * attribute, Null if there is no such attribute
268 * @see SOAPElement#getAttributeValue(Name)
269 * @since SAAJ 1.3
270 */
271 public String getAttributeValue(QName qname);
272
273 /**
274 * Returns an <code>Iterator</code> over all of the attribute
275 * <code>Name</code> objects in this
276 * <code>SOAPElement</code> object. The iterator can be used to get
277 * the attribute names, which can then be passed to the method
278 * <code>getAttributeValue</code> to retrieve the value of each
279 * attribute.
280 *
281 * @see SOAPElement#getAllAttributesAsQNames()
282 * @return an iterator over the names of the attributes
283 */
284 public Iterator getAllAttributes();
285
286 /**
287 * Returns an <code>Iterator</code> over all of the attributes
288 * in this <code>SOAPElement</code> as <code>QName</code> objects.
289 * The iterator can be used to get the attribute QName, which can then
290 * be passed to the method <code>getAttributeValue</code> to retrieve
291 * the value of each attribute.
292 *
293 * @return an iterator over the QNames of the attributes
294 * @see SOAPElement#getAllAttributes()
295 * @since SAAJ 1.3
296 */
297 public Iterator getAllAttributesAsQNames();
298
299
300 /**
301 * Returns the URI of the namespace that has the given prefix.
302 *
303 * @param prefix a <code>String</code> giving the prefix of the namespace
304 * for which to search
305 * @return a <code>String</code> with the uri of the namespace that has
306 * the given prefix
307 */
308 public String getNamespaceURI(String prefix);
309
310 /**
311 * Returns an <code>Iterator</code> over the namespace prefix
312 * <code>String</code>s declared by this element. The prefixes returned by
313 * this iterator can be passed to the method
314 * <code>getNamespaceURI</code> to retrieve the URI of each namespace.
315 *
316 * @return an iterator over the namespace prefixes in this
317 * <code>SOAPElement</code> object
318 */
319 public Iterator getNamespacePrefixes();
320
321 /**
322 * Returns an <code>Iterator</code> over the namespace prefix
323 * <code>String</code>s visible to this element. The prefixes returned by
324 * this iterator can be passed to the method
325 * <code>getNamespaceURI</code> to retrieve the URI of each namespace.
326 *
327 * @return an iterator over the namespace prefixes are within scope of this
328 * <code>SOAPElement</code> object
329 *
330 * @since SAAJ 1.2
331 */
332 public Iterator getVisibleNamespacePrefixes();
333
334 /**
335 * Creates a <code>QName</code> whose namespace URI is the one associated
336 * with the parameter, <code>prefix</code>, in the context of this
337 * <code>SOAPElement</code>. The remaining elements of the new
338 * <code>QName</code> are taken directly from the parameters,
339 * <code>localName</code> and <code>prefix</code>.
340 *
341 * @param localName
342 * a <code>String</code> containing the local part of the name.
343 * @param prefix
344 * a <code>String</code> containing the prefix for the name.
345 *
346 * @return a <code>QName</code> with the specified <code>localName</code>
347 * and <code>prefix</code>, and with a namespace that is associated
348 * with the <code>prefix</code> in the context of this
349 * <code>SOAPElement</code>. This namespace will be the same as
350 * the one that would be returned by
351 * <code>{@link #getNamespaceURI(String)}</code> if it were given
352 * <code>prefix</code> as it's parameter.
353 *
354 * @exception SOAPException if the <code>QName</code> cannot be created.
355 *
356 * @since SAAJ 1.3
357 */
358 public QName createQName(String localName, String prefix)
359 throws SOAPException;
360 /**
361 * Returns the name of this <code>SOAPElement</code> object.
362 *
363 * @return a <code>Name</code> object with the name of this
364 * <code>SOAPElement</code> object
365 */
366 public Name getElementName();
367
368 /**
369 * Returns the qname of this <code>SOAPElement</code> object.
370 *
371 * @return a <code>QName</code> object with the qname of this
372 * <code>SOAPElement</code> object
373 * @see SOAPElement#getElementName()
374 * @since SAAJ 1.3
375 */
376 public QName getElementQName();
377
378 /**
379 * Changes the name of this <code>Element</code> to <code>newName</code> if
380 * possible. SOAP Defined elements such as SOAPEnvelope, SOAPHeader, SOAPBody
381 * etc. cannot have their names changed using this method. Any attempt to do
382 * so will result in a SOAPException being thrown.
383 *<P>
384 * Callers should not rely on the element instance being renamed as is.
385 * Implementations could end up copying the content of the
386 * <code>SOAPElement</code> to a renamed instance.
387 *
388 * @param newName the new name for the <code>Element</code>.
389 *
390 * @exception SOAPException if changing the name of this <code>Element</code>
391 * is not allowed.
392 * @return The renamed Node
393 *
394 * @since SAAJ 1.3
395 */
396 public SOAPElement setElementQName(QName newName) throws SOAPException;
397
398 /**
399 * Removes the attribute with the specified name.
400 *
401 * @param name the <code>Name</code> object with the name of the
402 * attribute to be removed
403 * @return <code>true</code> if the attribute was
404 * removed successfully; <code>false</code> if it was not
405 * @see SOAPElement#removeAttribute(javax.xml.namespace.QName)
406 */
407 public boolean removeAttribute(Name name);
408
409 /**
410 * Removes the attribute with the specified qname.
411 *
412 * @param qname the <code>QName</code> object with the qname of the
413 * attribute to be removed
414 * @return <code>true</code> if the attribute was
415 * removed successfully; <code>false</code> if it was not
416 * @see SOAPElement#removeAttribute(Name)
417 * @since SAAJ 1.3
418 */
419 public boolean removeAttribute(QName qname);
420
421 /**
422 * Removes the namespace declaration corresponding to the given prefix.
423 *
424 * @param prefix a <code>String</code> giving the prefix for which
425 * to search
426 * @return <code>true</code> if the namespace declaration was
427 * removed successfully; <code>false</code> if it was not
428 */
429 public boolean removeNamespaceDeclaration(String prefix);
430
431 /**
432 * Returns an <code>Iterator</code> over all the immediate child
433 * {@link Node}s of this element. This includes <code>javax.xml.soap.Text</code>
434 * objects as well as <code>SOAPElement</code> objects.
435 * <p>
436 * Calling this method may cause child <code>Element</code>,
437 * <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be
438 * replaced by <code>SOAPElement</code>, <code>SOAPHeaderElement</code>,
439 * <code>SOAPBodyElement</code> or <code>javax.xml.soap.Text</code> nodes as
440 * appropriate for the type of this parent node. As a result the calling
441 * application must treat any existing references to these child nodes that
442 * have been obtained through DOM APIs as invalid and either discard them or
443 * refresh them with the values returned by this <code>Iterator</code>. This
444 * behavior can be avoided by calling the equivalent DOM APIs. See
445 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
446 * for more details.
447 *
448 * @return an iterator with the content of this <code>SOAPElement</code>
449 * object
450 */
451 public Iterator getChildElements();
452
453 /**
454 * Returns an <code>Iterator</code> over all the immediate child
455 * {@link Node}s of this element with the specified name. All of these
456 * children will be <code>SOAPElement</code> nodes.
457 * <p>
458 * Calling this method may cause child <code>Element</code>,
459 * <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be
460 * replaced by <code>SOAPElement</code>, <code>SOAPHeaderElement</code>,
461 * <code>SOAPBodyElement</code> or <code>javax.xml.soap.Text</code> nodes as
462 * appropriate for the type of this parent node. As a result the calling
463 * application must treat any existing references to these child nodes that
464 * have been obtained through DOM APIs as invalid and either discard them or
465 * refresh them with the values returned by this <code>Iterator</code>. This
466 * behavior can be avoided by calling the equivalent DOM APIs. See
467 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
468 * for more details.
469 *
470 * @param name a <code>Name</code> object with the name of the child
471 * elements to be returned
472 *
473 * @return an <code>Iterator</code> object over all the elements
474 * in this <code>SOAPElement</code> object with the
475 * specified name
476 * @see SOAPElement#getChildElements(javax.xml.namespace.QName)
477 */
478 public Iterator getChildElements(Name name);
479
480 /**
481 * Returns an <code>Iterator</code> over all the immediate child
482 * {@link Node}s of this element with the specified qname. All of these
483 * children will be <code>SOAPElement</code> nodes.
484 * <p>
485 * Calling this method may cause child <code>Element</code>,
486 * <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be
487 * replaced by <code>SOAPElement</code>, <code>SOAPHeaderElement</code>,
488 * <code>SOAPBodyElement</code> or <code>javax.xml.soap.Text</code> nodes as
489 * appropriate for the type of this parent node. As a result the calling
490 * application must treat any existing references to these child nodes that
491 * have been obtained through DOM APIs as invalid and either discard them or
492 * refresh them with the values returned by this <code>Iterator</code>. This
493 * behavior can be avoided by calling the equivalent DOM APIs. See
494 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
495 * for more details.
496 *
497 * @param qname a <code>QName</code> object with the qname of the child
498 * elements to be returned
499 *
500 * @return an <code>Iterator</code> object over all the elements
501 * in this <code>SOAPElement</code> object with the
502 * specified qname
503 * @see SOAPElement#getChildElements(Name)
504 * @since SAAJ 1.3
505 */
506 public Iterator getChildElements(QName qname);
507
508 /**
509 * Sets the encoding style for this <code>SOAPElement</code> object
510 * to one specified.
511 *
512 * @param encodingStyle a <code>String</code> giving the encoding style
513 *
514 * @exception IllegalArgumentException if there was a problem in the
515 * encoding style being set.
516 * @exception SOAPException if setting the encodingStyle is invalid for this SOAPElement.
517 * @see #getEncodingStyle
518 */
519 public void setEncodingStyle(String encodingStyle)
520 throws SOAPException;
521 /**
522 * Returns the encoding style for this <code>SOAPElement</code> object.
523 *
524 * @return a <code>String</code> giving the encoding style
525 *
526 * @see #setEncodingStyle
527 */
528 public String getEncodingStyle();
529 }
Save This Page