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

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

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

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

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

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

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

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

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