aoqi@0: /* aoqi@0: * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved. aoqi@0: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. aoqi@0: * aoqi@0: * This code is free software; you can redistribute it and/or modify it aoqi@0: * under the terms of the GNU General Public License version 2 only, as aoqi@0: * published by the Free Software Foundation. Oracle designates this aoqi@0: * particular file as subject to the "Classpath" exception as provided aoqi@0: * by Oracle in the LICENSE file that accompanied this code. aoqi@0: * aoqi@0: * This code is distributed in the hope that it will be useful, but WITHOUT aoqi@0: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or aoqi@0: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License aoqi@0: * version 2 for more details (a copy is included in the LICENSE file that aoqi@0: * accompanied this code). aoqi@0: * aoqi@0: * You should have received a copy of the GNU General Public License version aoqi@0: * 2 along with this work; if not, write to the Free Software Foundation, aoqi@0: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. aoqi@0: * aoqi@0: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA aoqi@0: * or visit www.oracle.com if you need additional information or have any aoqi@0: * questions. aoqi@0: */ aoqi@0: aoqi@0: package javax.xml.soap; aoqi@0: aoqi@0: import java.util.Iterator; aoqi@0: aoqi@0: import javax.xml.namespace.QName; aoqi@0: aoqi@0: /** aoqi@0: * An object representing an element of a SOAP message that is allowed but not aoqi@0: * specifically prescribed by a SOAP specification. This interface serves as the aoqi@0: * base interface for those objects that are specifically prescribed by a SOAP aoqi@0: * specification. aoqi@0: *
aoqi@0: * Methods in this interface that are required to return SAAJ specific objects
aoqi@0: * may "silently" replace nodes in the tree as required to successfully return
aoqi@0: * objects of the correct type. See {@link #getChildElements()} and
aoqi@0: * {@link javax.xml.soap}
aoqi@0: * for details.
aoqi@0: */
aoqi@0: public interface SOAPElement extends Node, org.w3c.dom.Element {
aoqi@0:
aoqi@0: /**
aoqi@0: * Creates a new
aoqi@0: * This method may be deprecated in a future release of SAAJ in favor of
aoqi@0: * addChildElement(javax.xml.namespace.QName)
aoqi@0: *
aoqi@0: * @param name a The fragment rooted in The fragment rooted in
aoqi@0: * This method is useful for rolling back the construction of partially
aoqi@0: * completed
aoqi@0: * Callers should not rely on the element instance being renamed as is.
aoqi@0: * Implementations could end up copying the content of the
aoqi@0: *
aoqi@0: * Calling this method may cause child
aoqi@0: * Calling this method may cause child
aoqi@0: * Calling this method may cause child SOAPElement
object initialized with the
aoqi@0: * given Name
object and adds the new element to this
aoqi@0: * SOAPElement
object.
aoqi@0: * Name
object with the XML name for the
aoqi@0: * new element
aoqi@0: *
aoqi@0: * @return the new SOAPElement
object that was created
aoqi@0: * @exception SOAPException if there is an error in creating the
aoqi@0: * SOAPElement
object
aoqi@0: * @see SOAPElement#addChildElement(javax.xml.namespace.QName)
aoqi@0: */
aoqi@0: public SOAPElement addChildElement(Name name) throws SOAPException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Creates a new SOAPElement
object initialized with the given
aoqi@0: * QName
object and adds the new element to this SOAPElement
aoqi@0: * object. The namespace, localname and prefix of the new
aoqi@0: * SOAPElement
are all taken from the qname
argument.
aoqi@0: *
aoqi@0: * @param qname a QName
object with the XML name for the
aoqi@0: * new element
aoqi@0: *
aoqi@0: * @return the new SOAPElement
object that was created
aoqi@0: * @exception SOAPException if there is an error in creating the
aoqi@0: * SOAPElement
object
aoqi@0: * @see SOAPElement#addChildElement(Name)
aoqi@0: * @since SAAJ 1.3
aoqi@0: */
aoqi@0: public SOAPElement addChildElement(QName qname) throws SOAPException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Creates a new SOAPElement
object initialized with the
aoqi@0: * specified local name and adds the new element to this
aoqi@0: * SOAPElement
object.
aoqi@0: * The new SOAPElement
inherits any in-scope default namespace.
aoqi@0: *
aoqi@0: * @param localName a String
giving the local name for
aoqi@0: * the element
aoqi@0: * @return the new SOAPElement
object that was created
aoqi@0: * @exception SOAPException if there is an error in creating the
aoqi@0: * SOAPElement
object
aoqi@0: */
aoqi@0: public SOAPElement addChildElement(String localName) throws SOAPException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Creates a new SOAPElement
object initialized with the
aoqi@0: * specified local name and prefix and adds the new element to this
aoqi@0: * SOAPElement
object.
aoqi@0: *
aoqi@0: * @param localName a String
giving the local name for
aoqi@0: * the new element
aoqi@0: * @param prefix a String
giving the namespace prefix for
aoqi@0: * the new element
aoqi@0: *
aoqi@0: * @return the new SOAPElement
object that was created
aoqi@0: * @exception SOAPException if the prefix
is not valid in the
aoqi@0: * context of this SOAPElement
or if there is an error in creating the
aoqi@0: * SOAPElement
object
aoqi@0: */
aoqi@0: public SOAPElement addChildElement(String localName, String prefix)
aoqi@0: throws SOAPException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Creates a new SOAPElement
object initialized with the
aoqi@0: * specified local name, prefix, and URI and adds the new element to this
aoqi@0: * SOAPElement
object.
aoqi@0: *
aoqi@0: * @param localName a String
giving the local name for
aoqi@0: * the new element
aoqi@0: * @param prefix a String
giving the namespace prefix for
aoqi@0: * the new element
aoqi@0: * @param uri a String
giving the URI of the namespace
aoqi@0: * to which the new element belongs
aoqi@0: *
aoqi@0: * @return the new SOAPElement
object that was created
aoqi@0: * @exception SOAPException if there is an error in creating the
aoqi@0: * SOAPElement
object
aoqi@0: */
aoqi@0: public SOAPElement addChildElement(String localName, String prefix,
aoqi@0: String uri)
aoqi@0: throws SOAPException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Add a SOAPElement
as a child of this
aoqi@0: * SOAPElement
instance. The SOAPElement
aoqi@0: * is expected to be created by a
aoqi@0: * SOAPFactory
. Callers should not rely on the
aoqi@0: * element instance being added as is into the XML
aoqi@0: * tree. Implementations could end up copying the content
aoqi@0: * of the SOAPElement
passed into an instance of
aoqi@0: * a different SOAPElement
implementation. For
aoqi@0: * instance if addChildElement()
is called on a
aoqi@0: * SOAPHeader
, element
will be copied
aoqi@0: * into an instance of a SOAPHeaderElement
.
aoqi@0: *
aoqi@0: * element
is either added
aoqi@0: * as a whole or not at all, if there was an error.
aoqi@0: *
aoqi@0: * element
cannot contain
aoqi@0: * elements named "Envelope", "Header" or "Body" and in the SOAP
aoqi@0: * namespace. Any namespace prefixes present in the fragment
aoqi@0: * should be fully resolved using appropriate namespace
aoqi@0: * declarations within the fragment itself.
aoqi@0: *
aoqi@0: * @param element the SOAPElement
to be added as a
aoqi@0: * new child
aoqi@0: *
aoqi@0: * @exception SOAPException if there was an error in adding this
aoqi@0: * element as a child
aoqi@0: *
aoqi@0: * @return an instance representing the new SOAP element that was
aoqi@0: * actually added to the tree.
aoqi@0: */
aoqi@0: public SOAPElement addChildElement(SOAPElement element)
aoqi@0: throws SOAPException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Detaches all children of this SOAPElement
.
aoqi@0: * SOAPHeaders
and SOAPBodys
in
aoqi@0: * preparation for sending a fault when an error condition is detected. It
aoqi@0: * is also useful for recycling portions of a document within a SOAP
aoqi@0: * message.
aoqi@0: *
aoqi@0: * @since SAAJ 1.2
aoqi@0: */
aoqi@0: public abstract void removeContents();
aoqi@0:
aoqi@0: /**
aoqi@0: * Creates a new Text
object initialized with the given
aoqi@0: * String
and adds it to this SOAPElement
object.
aoqi@0: *
aoqi@0: * @param text a String
object with the textual content to be added
aoqi@0: *
aoqi@0: * @return the SOAPElement
object into which
aoqi@0: * the new Text
object was inserted
aoqi@0: * @exception SOAPException if there is an error in creating the
aoqi@0: * new Text
object or if it is not legal to
aoqi@0: * attach it as a child to this
aoqi@0: * SOAPElement
aoqi@0: */
aoqi@0: public SOAPElement addTextNode(String text) throws SOAPException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Adds an attribute with the specified name and value to this
aoqi@0: * SOAPElement
object.
aoqi@0: *
aoqi@0: * @param name a Name
object with the name of the attribute
aoqi@0: * @param value a String
giving the value of the attribute
aoqi@0: * @return the SOAPElement
object into which the attribute was
aoqi@0: * inserted
aoqi@0: *
aoqi@0: * @exception SOAPException if there is an error in creating the
aoqi@0: * Attribute, or it is invalid to set
aoqi@0: an attribute with Name
aoqi@0: name
on this SOAPElement.
aoqi@0: * @see SOAPElement#addAttribute(javax.xml.namespace.QName, String)
aoqi@0: */
aoqi@0: public SOAPElement addAttribute(Name name, String value)
aoqi@0: throws SOAPException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Adds an attribute with the specified name and value to this
aoqi@0: * SOAPElement
object.
aoqi@0: *
aoqi@0: * @param qname a QName
object with the name of the attribute
aoqi@0: * @param value a String
giving the value of the attribute
aoqi@0: * @return the SOAPElement
object into which the attribute was
aoqi@0: * inserted
aoqi@0: *
aoqi@0: * @exception SOAPException if there is an error in creating the
aoqi@0: * Attribute, or it is invalid to set
aoqi@0: an attribute with QName
aoqi@0: qname
on this SOAPElement.
aoqi@0: * @see SOAPElement#addAttribute(Name, String)
aoqi@0: * @since SAAJ 1.3
aoqi@0: */
aoqi@0: public SOAPElement addAttribute(QName qname, String value)
aoqi@0: throws SOAPException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Adds a namespace declaration with the specified prefix and URI to this
aoqi@0: * SOAPElement
object.
aoqi@0: *
aoqi@0: * @param prefix a String
giving the prefix of the namespace
aoqi@0: * @param uri a String
giving the uri of the namespace
aoqi@0: * @return the SOAPElement
object into which this
aoqi@0: * namespace declaration was inserted.
aoqi@0: *
aoqi@0: * @exception SOAPException if there is an error in creating the
aoqi@0: * namespace
aoqi@0: */
aoqi@0: public SOAPElement addNamespaceDeclaration(String prefix, String uri)
aoqi@0: throws SOAPException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns the value of the attribute with the specified name.
aoqi@0: *
aoqi@0: * @param name a Name
object with the name of the attribute
aoqi@0: * @return a String
giving the value of the specified
aoqi@0: * attribute, Null if there is no such attribute
aoqi@0: * @see SOAPElement#getAttributeValue(javax.xml.namespace.QName)
aoqi@0: */
aoqi@0: public String getAttributeValue(Name name);
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns the value of the attribute with the specified qname.
aoqi@0: *
aoqi@0: * @param qname a QName
object with the qname of the attribute
aoqi@0: * @return a String
giving the value of the specified
aoqi@0: * attribute, Null if there is no such attribute
aoqi@0: * @see SOAPElement#getAttributeValue(Name)
aoqi@0: * @since SAAJ 1.3
aoqi@0: */
aoqi@0: public String getAttributeValue(QName qname);
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns an Iterator
over all of the attribute
aoqi@0: * Name
objects in this
aoqi@0: * SOAPElement
object. The iterator can be used to get
aoqi@0: * the attribute names, which can then be passed to the method
aoqi@0: * getAttributeValue
to retrieve the value of each
aoqi@0: * attribute.
aoqi@0: *
aoqi@0: * @see SOAPElement#getAllAttributesAsQNames()
aoqi@0: * @return an iterator over the names of the attributes
aoqi@0: */
aoqi@0: public Iterator getAllAttributes();
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns an Iterator
over all of the attributes
aoqi@0: * in this SOAPElement
as QName
objects.
aoqi@0: * The iterator can be used to get the attribute QName, which can then
aoqi@0: * be passed to the method getAttributeValue
to retrieve
aoqi@0: * the value of each attribute.
aoqi@0: *
aoqi@0: * @return an iterator over the QNames of the attributes
aoqi@0: * @see SOAPElement#getAllAttributes()
aoqi@0: * @since SAAJ 1.3
aoqi@0: */
aoqi@0: public Iterator getAllAttributesAsQNames();
aoqi@0:
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns the URI of the namespace that has the given prefix.
aoqi@0: *
aoqi@0: * @param prefix a String
giving the prefix of the namespace
aoqi@0: * for which to search
aoqi@0: * @return a String
with the uri of the namespace that has
aoqi@0: * the given prefix
aoqi@0: */
aoqi@0: public String getNamespaceURI(String prefix);
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns an Iterator
over the namespace prefix
aoqi@0: * String
s declared by this element. The prefixes returned by
aoqi@0: * this iterator can be passed to the method
aoqi@0: * getNamespaceURI
to retrieve the URI of each namespace.
aoqi@0: *
aoqi@0: * @return an iterator over the namespace prefixes in this
aoqi@0: * SOAPElement
object
aoqi@0: */
aoqi@0: public Iterator getNamespacePrefixes();
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns an Iterator
over the namespace prefix
aoqi@0: * String
s visible to this element. The prefixes returned by
aoqi@0: * this iterator can be passed to the method
aoqi@0: * getNamespaceURI
to retrieve the URI of each namespace.
aoqi@0: *
aoqi@0: * @return an iterator over the namespace prefixes are within scope of this
aoqi@0: * SOAPElement
object
aoqi@0: *
aoqi@0: * @since SAAJ 1.2
aoqi@0: */
aoqi@0: public Iterator getVisibleNamespacePrefixes();
aoqi@0:
aoqi@0: /**
aoqi@0: * Creates a QName
whose namespace URI is the one associated
aoqi@0: * with the parameter, prefix
, in the context of this
aoqi@0: * SOAPElement
. The remaining elements of the new
aoqi@0: * QName
are taken directly from the parameters,
aoqi@0: * localName
and prefix
.
aoqi@0: *
aoqi@0: * @param localName
aoqi@0: * a String
containing the local part of the name.
aoqi@0: * @param prefix
aoqi@0: * a String
containing the prefix for the name.
aoqi@0: *
aoqi@0: * @return a QName
with the specified localName
aoqi@0: * and prefix
, and with a namespace that is associated
aoqi@0: * with the prefix
in the context of this
aoqi@0: * SOAPElement
. This namespace will be the same as
aoqi@0: * the one that would be returned by
aoqi@0: * {@link #getNamespaceURI(String)}
if it were given
aoqi@0: * prefix
as it's parameter.
aoqi@0: *
aoqi@0: * @exception SOAPException if the QName
cannot be created.
aoqi@0: *
aoqi@0: * @since SAAJ 1.3
aoqi@0: */
aoqi@0: public QName createQName(String localName, String prefix)
aoqi@0: throws SOAPException;
aoqi@0: /**
aoqi@0: * Returns the name of this SOAPElement
object.
aoqi@0: *
aoqi@0: * @return a Name
object with the name of this
aoqi@0: * SOAPElement
object
aoqi@0: */
aoqi@0: public Name getElementName();
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns the qname of this SOAPElement
object.
aoqi@0: *
aoqi@0: * @return a QName
object with the qname of this
aoqi@0: * SOAPElement
object
aoqi@0: * @see SOAPElement#getElementName()
aoqi@0: * @since SAAJ 1.3
aoqi@0: */
aoqi@0: public QName getElementQName();
aoqi@0:
aoqi@0: /**
aoqi@0: * Changes the name of this Element
to newName
if
aoqi@0: * possible. SOAP Defined elements such as SOAPEnvelope, SOAPHeader, SOAPBody
aoqi@0: * etc. cannot have their names changed using this method. Any attempt to do
aoqi@0: * so will result in a SOAPException being thrown.
aoqi@0: *SOAPElement
to a renamed instance.
aoqi@0: *
aoqi@0: * @param newName the new name for the Element
.
aoqi@0: *
aoqi@0: * @exception SOAPException if changing the name of this Element
aoqi@0: * is not allowed.
aoqi@0: * @return The renamed Node
aoqi@0: *
aoqi@0: * @since SAAJ 1.3
aoqi@0: */
aoqi@0: public SOAPElement setElementQName(QName newName) throws SOAPException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Removes the attribute with the specified name.
aoqi@0: *
aoqi@0: * @param name the Name
object with the name of the
aoqi@0: * attribute to be removed
aoqi@0: * @return true
if the attribute was
aoqi@0: * removed successfully; false
if it was not
aoqi@0: * @see SOAPElement#removeAttribute(javax.xml.namespace.QName)
aoqi@0: */
aoqi@0: public boolean removeAttribute(Name name);
aoqi@0:
aoqi@0: /**
aoqi@0: * Removes the attribute with the specified qname.
aoqi@0: *
aoqi@0: * @param qname the QName
object with the qname of the
aoqi@0: * attribute to be removed
aoqi@0: * @return true
if the attribute was
aoqi@0: * removed successfully; false
if it was not
aoqi@0: * @see SOAPElement#removeAttribute(Name)
aoqi@0: * @since SAAJ 1.3
aoqi@0: */
aoqi@0: public boolean removeAttribute(QName qname);
aoqi@0:
aoqi@0: /**
aoqi@0: * Removes the namespace declaration corresponding to the given prefix.
aoqi@0: *
aoqi@0: * @param prefix a String
giving the prefix for which
aoqi@0: * to search
aoqi@0: * @return true
if the namespace declaration was
aoqi@0: * removed successfully; false
if it was not
aoqi@0: */
aoqi@0: public boolean removeNamespaceDeclaration(String prefix);
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns an Iterator
over all the immediate child
aoqi@0: * {@link Node}s of this element. This includes javax.xml.soap.Text
aoqi@0: * objects as well as SOAPElement
objects.
aoqi@0: * Element
,
aoqi@0: * SOAPElement
and org.w3c.dom.Text
nodes to be
aoqi@0: * replaced by SOAPElement
, SOAPHeaderElement
,
aoqi@0: * SOAPBodyElement
or javax.xml.soap.Text
nodes as
aoqi@0: * appropriate for the type of this parent node. As a result the calling
aoqi@0: * application must treat any existing references to these child nodes that
aoqi@0: * have been obtained through DOM APIs as invalid and either discard them or
aoqi@0: * refresh them with the values returned by this Iterator
. This
aoqi@0: * behavior can be avoided by calling the equivalent DOM APIs. See
aoqi@0: * {@link javax.xml.soap}
aoqi@0: * for more details.
aoqi@0: *
aoqi@0: * @return an iterator with the content of this SOAPElement
aoqi@0: * object
aoqi@0: */
aoqi@0: public Iterator getChildElements();
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns an Iterator
over all the immediate child
aoqi@0: * {@link Node}s of this element with the specified name. All of these
aoqi@0: * children will be SOAPElement
nodes.
aoqi@0: * Element
,
aoqi@0: * SOAPElement
and org.w3c.dom.Text
nodes to be
aoqi@0: * replaced by SOAPElement
, SOAPHeaderElement
,
aoqi@0: * SOAPBodyElement
or javax.xml.soap.Text
nodes as
aoqi@0: * appropriate for the type of this parent node. As a result the calling
aoqi@0: * application must treat any existing references to these child nodes that
aoqi@0: * have been obtained through DOM APIs as invalid and either discard them or
aoqi@0: * refresh them with the values returned by this Iterator
. This
aoqi@0: * behavior can be avoided by calling the equivalent DOM APIs. See
aoqi@0: * {@link javax.xml.soap}
aoqi@0: * for more details.
aoqi@0: *
aoqi@0: * @param name a Name
object with the name of the child
aoqi@0: * elements to be returned
aoqi@0: *
aoqi@0: * @return an Iterator
object over all the elements
aoqi@0: * in this SOAPElement
object with the
aoqi@0: * specified name
aoqi@0: * @see SOAPElement#getChildElements(javax.xml.namespace.QName)
aoqi@0: */
aoqi@0: public Iterator getChildElements(Name name);
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns an Iterator
over all the immediate child
aoqi@0: * {@link Node}s of this element with the specified qname. All of these
aoqi@0: * children will be SOAPElement
nodes.
aoqi@0: * Element
,
aoqi@0: * SOAPElement
and org.w3c.dom.Text
nodes to be
aoqi@0: * replaced by SOAPElement
, SOAPHeaderElement
,
aoqi@0: * SOAPBodyElement
or javax.xml.soap.Text
nodes as
aoqi@0: * appropriate for the type of this parent node. As a result the calling
aoqi@0: * application must treat any existing references to these child nodes that
aoqi@0: * have been obtained through DOM APIs as invalid and either discard them or
aoqi@0: * refresh them with the values returned by this Iterator
. This
aoqi@0: * behavior can be avoided by calling the equivalent DOM APIs. See
aoqi@0: * {@link javax.xml.soap}
aoqi@0: * for more details.
aoqi@0: *
aoqi@0: * @param qname a QName
object with the qname of the child
aoqi@0: * elements to be returned
aoqi@0: *
aoqi@0: * @return an Iterator
object over all the elements
aoqi@0: * in this SOAPElement
object with the
aoqi@0: * specified qname
aoqi@0: * @see SOAPElement#getChildElements(Name)
aoqi@0: * @since SAAJ 1.3
aoqi@0: */
aoqi@0: public Iterator getChildElements(QName qname);
aoqi@0:
aoqi@0: /**
aoqi@0: * Sets the encoding style for this SOAPElement
object
aoqi@0: * to one specified.
aoqi@0: *
aoqi@0: * @param encodingStyle a String
giving the encoding style
aoqi@0: *
aoqi@0: * @exception IllegalArgumentException if there was a problem in the
aoqi@0: * encoding style being set.
aoqi@0: * @exception SOAPException if setting the encodingStyle is invalid for this SOAPElement.
aoqi@0: * @see #getEncodingStyle
aoqi@0: */
aoqi@0: public void setEncodingStyle(String encodingStyle)
aoqi@0: throws SOAPException;
aoqi@0: /**
aoqi@0: * Returns the encoding style for this SOAPElement
object.
aoqi@0: *
aoqi@0: * @return a String
giving the encoding style
aoqi@0: *
aoqi@0: * @see #setEncodingStyle
aoqi@0: */
aoqi@0: public String getEncodingStyle();
aoqi@0: }