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