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