1 /*
2 * Copyright (c) 2004, 2013, 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 * @since 1.6
45 */
46 public interface SOAPElement extends Node, org.w3c.dom.Element {
47
48 /**
49 * Creates a new {@code SOAPElement} object initialized with the
50 * given {@code Name} object and adds the new element to this
51 * {@code SOAPElement} 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} object with the XML name for the
57 * new element
58 *
59 * @return the new {@code SOAPElement} object that was created
60 * @exception SOAPException if there is an error in creating the
61 * {@code SOAPElement} object
62 * @see SOAPElement#addChildElement(javax.xml.namespace.QName)
328 */
329 public Iterator getVisibleNamespacePrefixes();
330
331 /**
332 * Creates a {@code QName} whose namespace URI is the one associated
333 * with the parameter, {@code prefix}, in the context of this
334 * {@code SOAPElement}. The remaining elements of the new
335 * {@code QName} are taken directly from the parameters,
336 * {@code localName} and {@code prefix}.
337 *
338 * @param localName
339 * a {@code String} containing the local part of the name.
340 * @param prefix
341 * a {@code String} containing the prefix for the name.
342 *
343 * @return a {@code QName} with the specified {@code localName}
344 * and {@code prefix}, and with a namespace that is associated
345 * with the {@code prefix} in the context of this
346 * {@code SOAPElement}. 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} as it's parameter.
350 *
351 * @exception SOAPException if the {@code QName} 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} object.
359 *
360 * @return a {@code Name} object with the name of this
361 * {@code SOAPElement} object
362 */
363 public Name getElementName();
364
365 /**
366 * Returns the qname of this {@code SOAPElement} object.
367 *
368 * @return a {@code QName} object with the qname of this
422 * to search
423 * @return {@code true} if the namespace declaration was
424 * removed successfully; {@code false} if it was not
425 */
426 public boolean removeNamespaceDeclaration(String prefix);
427
428 /**
429 * Returns an {@code Iterator} over all the immediate child
430 * {@link Node}s of this element. This includes {@code javax.xml.soap.Text}
431 * objects as well as {@code SOAPElement} objects.
432 * <p>
433 * Calling this method may cause child {@code Element},
434 * {@code SOAPElement} and {@code org.w3c.dom.Text} nodes to be
435 * replaced by {@code SOAPElement}, {@code SOAPHeaderElement},
436 * {@code SOAPBodyElement} or {@code javax.xml.soap.Text} nodes as
437 * appropriate for the type of this parent node. As a result the calling
438 * application must treat any existing references to these child nodes that
439 * have been obtained through DOM APIs as invalid and either discard them or
440 * refresh them with the values returned by this {@code Iterator}. This
441 * behavior can be avoided by calling the equivalent DOM APIs. See
442 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap</a>}
443 * for more details.
444 *
445 * @return an iterator with the content of this {@code SOAPElement}
446 * object
447 */
448 public Iterator getChildElements();
449
450 /**
451 * Returns an {@code Iterator} over all the immediate child
452 * {@link Node}s of this element with the specified name. All of these
453 * children will be {@code SOAPElement} nodes.
454 * <p>
455 * Calling this method may cause child {@code Element},
456 * {@code SOAPElement} and {@code org.w3c.dom.Text} nodes to be
457 * replaced by {@code SOAPElement}, {@code SOAPHeaderElement},
458 * {@code SOAPBodyElement} or {@code javax.xml.soap.Text} nodes as
459 * appropriate for the type of this parent node. As a result the calling
460 * application must treat any existing references to these child nodes that
461 * have been obtained through DOM APIs as invalid and either discard them or
462 * refresh them with the values returned by this {@code Iterator}. This
463 * behavior can be avoided by calling the equivalent DOM APIs. See
464 * {@link <a HREF="package-summary.html#package_description">javax.xml.soap</a>}
465 * for more details.
466 *
467 * @param name a {@code Name} object with the name of the child
468 * elements to be returned
469 *
470 * @return an {@code Iterator} object over all the elements
471 * in this {@code SOAPElement} object with the
472 * specified name
473 * @see SOAPElement#getChildElements(javax.xml.namespace.QName)
474 */
475 public Iterator getChildElements(Name name);
476
477 /**
478 * Returns an {@code Iterator} over all the immediate child
479 * {@link Node}s of this element with the specified qname. All of these
480 * children will be {@code SOAPElement} nodes.
481 * <p>
482 * Calling this method may cause child {@code Element},
483 * {@code SOAPElement} and {@code org.w3c.dom.Text} nodes to be
484 * replaced by {@code SOAPElement}, {@code SOAPHeaderElement},
485 * {@code SOAPBodyElement} or {@code javax.xml.soap.Text} 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}. 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} object with the qname of the child
495 * elements to be returned
496 *
497 * @return an {@code Iterator} object over all the elements
498 * in this {@code SOAPElement} 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} object
507 * to one specified.
508 *
509 * @param encodingStyle a {@code String} giving the encoding style
510 *
511 * @exception IllegalArgumentException if there was a problem in the
|
1 /*
2 * Copyright (c) 2004, 2015, 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)
327 */
328 public Iterator 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
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 may 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 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 may 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 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 may 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 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
|