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 SOAPElement object initialized with the ohair@286: * given Name object and adds the new element to this ohair@286: * SOAPElement object. ohair@286: *

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 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: *

The fragment rooted in element is either added ohair@286: * as a whole or not at all, if there was an error. ohair@286: * ohair@286: *

The fragment rooted in 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: *

ohair@286: * This method is useful for rolling back the construction of partially ohair@286: * completed 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: * Strings 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: * Strings 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: *

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: * 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: *

ohair@286: * Calling this method may cause child 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: *

ohair@286: * Calling this method may cause child 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: *

ohair@286: * Calling this method may cause child 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: }