Mercurial > jdk8-mips64-public > jaxws / file comparison

comparison: src/share/jaxws_classes/javax/xml/soap/SOAPElement.java

src/share/jaxws_classes/javax/xml/soap/SOAPElement.java

changeset 286
f50545b5e2f1
child 368
0989ad8c0860
equal deleted inserted replaced
284:88b85470e72c 286:f50545b5e2f1
1 /*
2 * Copyright (c) 2004, 2011, 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 <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
98 * <code>SOAPElement</code> object.
99 *
100 * @param localName a <code>String</code> giving the local name for
101 * the new element
102 * @param prefix a <code>String</code> giving the namespace prefix for
103 * the new element
104 *
105 * @return the new <code>SOAPElement</code> object that was created
106 * @exception SOAPException if the <code>prefix</code> is not valid in the
107 * context of this <code>SOAPElement</code> or if there is an error in creating the
108 * <code>SOAPElement</code> object
109 */
110 public SOAPElement addChildElement(String localName, String prefix)
111 throws SOAPException;
112
113 /**
114 * Creates a new <code>SOAPElement</code> object initialized with the
115 * specified local name, prefix, and URI and adds the new element to this
116 * <code>SOAPElement</code> object.
117 *
118 * @param localName a <code>String</code> giving the local name for
119 * the new element
120 * @param prefix a <code>String</code> giving the namespace prefix for
121 * the new element
122 * @param uri a <code>String</code> giving the URI of the namespace
123 * to which the new element belongs
124 *
125 * @return the new <code>SOAPElement</code> object that was created
126 * @exception SOAPException if there is an error in creating the
127 * <code>SOAPElement</code> object
128 */
129 public SOAPElement addChildElement(String localName, String prefix,
130 String uri)
131 throws SOAPException;
132
133 /**
134 * Add a <code>SOAPElement</code> as a child of this
135 * <code>SOAPElement</code> instance. The <code>SOAPElement</code>
136 * is expected to be created by a
137 * <code>SOAPFactory</code>. Callers should not rely on the
138 * element instance being added as is into the XML
139 * tree. Implementations could end up copying the content
140 * of the <code>SOAPElement</code> passed into an instance of
141 * a different <code>SOAPElement</code> implementation. For
142 * instance if <code>addChildElement()</code> is called on a
143 * <code>SOAPHeader</code>, <code>element</code> will be copied
144 * into an instance of a <code>SOAPHeaderElement</code>.
145 *
146 * <P>The fragment rooted in <code>element</code> is either added
147 * as a whole or not at all, if there was an error.
148 *
149 * <P>The fragment rooted in <code>element</code> cannot contain
150 * elements named "Envelope", "Header" or "Body" and in the SOAP
151 * namespace. Any namespace prefixes present in the fragment
152 * should be fully resolved using appropriate namespace
153 * declarations within the fragment itself.
154 *
155 * @param element the <code>SOAPElement</code> to be added as a
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
197 * <code>SOAPElement</code> object.
198 *
199 * @param name a <code>Name</code> object with the name of the attribute
200 * @param value a <code>String</code> giving the value of the attribute
201 * @return the <code>SOAPElement</code> object into which the attribute was
202 * inserted
203 *
204 * @exception SOAPException if there is an error in creating the
205 * Attribute, or it is invalid to set
206 an attribute with <code>Name</code>
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
433 * replaced by <code>SOAPElement</code>, <code>SOAPHeaderElement</code>,
434 * <code>SOAPBodyElement</code> or <code>javax.xml.soap.Text</code> nodes as
435 * appropriate for the type of this parent node. As a result the calling
436 * application must treat any existing references to these child nodes that
437 * have been obtained through DOM APIs as invalid and either discard them or
438 * refresh them with the values returned by this <code>Iterator</code>. This
439 * behavior can be avoided by calling the equivalent DOM APIs. See
440 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
441 * for more details.
442 *
443 * @return an iterator with the content of this <code>SOAPElement</code>
444 * object
445 */
446 public Iterator getChildElements();
447
448 /**
449 * Returns an <code>Iterator</code> over all the immediate child
450 * {@link Node}s of this element with the specified name. All of these
451 * children will be <code>SOAPElement</code> nodes.
452 * <p>
453 * Calling this method may cause child <code>Element</code>,
454 * <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be
455 * replaced by <code>SOAPElement</code>, <code>SOAPHeaderElement</code>,
456 * <code>SOAPBodyElement</code> or <code>javax.xml.soap.Text</code> nodes as
457 * appropriate for the type of this parent node. As a result the calling
458 * application must treat any existing references to these child nodes that
459 * have been obtained through DOM APIs as invalid and either discard them or
460 * refresh them with the values returned by this <code>Iterator</code>. This
461 * behavior can be avoided by calling the equivalent DOM APIs. See
462 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
463 * for more details.
464 *
465 * @param name a <code>Name</code> object with the name of the child
466 * elements to be returned
467 *
468 * @return an <code>Iterator</code> object over all the elements
469 * in this <code>SOAPElement</code> object with the
470 * specified name
471 * @see SOAPElement#getChildElements(javax.xml.namespace.QName)
472 */
473 public Iterator getChildElements(Name name);
474
475 /**
476 * Returns an <code>Iterator</code> over all the immediate child
477 * {@link Node}s of this element with the specified qname. All of these
478 * children will be <code>SOAPElement</code> nodes.
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
520 *
521 * @see #setEncodingStyle
522 */
523 public String getEncodingStyle();
524 }

Mercurial Repository: jdk8-mips64-public/jaxws

mercurial