/* * The Apache Software License, Version 1.1 * * * Copyright (c) 2001-2003 The Apache Software Foundation. All rights * reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in * the documentation and/or other materials provided with the * distribution. * * 3. The end-user documentation included with the redistribution, * if any, must include the following acknowledgment: * "This product includes software developed by the * Apache Software Foundation (http://www.apache.org/)." * Alternately, this acknowledgment may appear in the software itself, * if and wherever such third-party acknowledgments normally appear. * * 4. The names "Axis" and "Apache Software Foundation" must * not be used to endorse or promote products derived from this * software without prior written permission. For written * permission, please contact apache@apache.org. * * 5. Products derived from this software may not be called "Apache", * nor may "Apache" appear in their name, without prior written * permission of the Apache Software Foundation. * * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * ==================================================================== * * This software consists of voluntary contributions made by many * individuals on behalf of the Apache Software Foundation. For more * information on the Apache Software Foundation, please see * . */ package javax.xml.soap; import java.util.Iterator; /** * An object representing the contents in a * SOAPBody object, the contents in a SOAPHeader * object, the content that can follow the SOAPBody object in a * SOAPEnvelope object, or what can follow the detail element * in a SOAPFault object. It is * the base class for all of the classes that represent the SOAP objects as * defined in the SOAP specification. */ public interface SOAPElement extends Node, org.w3c.dom.Element { /** * Creates a new SOAPElement object initialized with the * given Name object and adds the new element to this * SOAPElement object. * @param name a Name object with the XML name for the * new element * @return the new SOAPElement object that was created * @throws SOAPException if there is an error in creating the * SOAPElement object */ public abstract SOAPElement addChildElement(Name name) throws SOAPException; /** * Creates a new SOAPElement object initialized with the * given String object and adds the new element to this * SOAPElement object. * @param localName a String giving the local name for * the element * @return the new SOAPElement object that was created * @throws SOAPException if there is an error in creating the * SOAPElement object */ public abstract SOAPElement addChildElement(String localName) throws SOAPException; /** * Creates a new SOAPElement object initialized with the * specified local name and prefix and adds the new element to this * SOAPElement object. * @param localName a String giving the local name for * the new element * @param prefix a String giving the namespace prefix for * the new element * @return the new SOAPElement object that was created * @throws SOAPException if there is an error in creating the * SOAPElement object */ public abstract SOAPElement addChildElement(String localName, String prefix) throws SOAPException; /** * Creates a new SOAPElement object initialized with the * specified local name, prefix, and URI and adds the new element to this * SOAPElement object. * @param localName a String giving the local name for * the new element * @param prefix a String giving the namespace prefix for * the new element * @param uri a String giving the URI of the namespace * to which the new element belongs * @return the new SOAPElement object that was created * @throws SOAPException if there is an error in creating the * SOAPElement object */ public abstract SOAPElement addChildElement( String localName, String prefix, String uri) throws SOAPException; /** * Add a SOAPElement as a child of this * SOAPElement instance. The SOAPElement * is expected to be created by a * SOAPElementFactory. Callers should not rely on the * element instance being added as is into the XML * tree. Implementations could end up copying the content * of the SOAPElement passed into an instance of * a different SOAPElement implementation. For * instance if addChildElement() is called on a * SOAPHeader, element will be copied * into an instance of a SOAPHeaderElement. * *

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

The fragment rooted in element cannot contain * elements named "Envelope", "Header" or "Body" and in the SOAP * namespace. Any namespace prefixes present in the fragment * should be fully resolved using appropriate namespace * declarations within the fragment itself. * @param element the SOAPElement to be added as a * new child * @return an instance representing the new SOAP element that was * actually added to the tree. * @throws SOAPException if there was an error in adding this * element as a child */ public abstract SOAPElement addChildElement(SOAPElement element) throws SOAPException; /** * Creates a new Text object initialized with the given * String and adds it to this SOAPElement object. * @param text a String object with the textual content to be added * @return the SOAPElement object into which * the new Text object was inserted * @throws SOAPException if there is an error in creating the * new Text object */ public abstract SOAPElement addTextNode(String text) throws SOAPException; /** * Adds an attribute with the specified name and value to this * SOAPElement object. *

* @param name a Name object with the name of the attribute * @param value a String giving the value of the attribute * @return the SOAPElement object into which the attribute was * inserted * @throws SOAPException if there is an error in creating the * Attribute */ public abstract SOAPElement addAttribute(Name name, String value) throws SOAPException; /** * Adds a namespace declaration with the specified prefix and URI to this * SOAPElement object. *

* @param prefix a String giving the prefix of the namespace * @param uri a String giving * the prefix of the namespace * @return the SOAPElement object into which this * namespace declaration was inserted. * @throws SOAPException if there is an error in creating the * namespace */ public abstract SOAPElement addNamespaceDeclaration( String prefix, String uri) throws SOAPException; /** * Returns the value of the attribute with the specified * name. * @param name a Name object with * the name of the attribute * @return a String giving the value of the * specified attribute */ public abstract String getAttributeValue(Name name); /** * Returns an iterator over all of the attribute names in * this SOAPElement object. The iterator can be * used to get the attribute names, which can then be passed to * the method getAttributeValue to retrieve the * value of each attribute. * @return an iterator over the names of the attributes */ public abstract Iterator getAllAttributes(); /** * Returns the URI of the namespace that has the given * prefix. * * @param prefix a String giving * the prefix of the namespace for which to search * @return a String with the uri of the namespace * that has the given prefix */ public abstract String getNamespaceURI(String prefix); /** * Returns an iterator of namespace prefixes. The iterator * can be used to get the namespace prefixes, which can then be * passed to the method getNamespaceURI to retrieve * the URI of each namespace. * @return an iterator over the namespace prefixes in this * SOAPElement object */ public abstract Iterator getNamespacePrefixes(); /** * Returns the name of this SOAPElement * object. * @return a Name object with the name of this * SOAPElement object */ public abstract Name getElementName(); /** * Removes the attribute with the specified name. * @param name the Name object with * the name of the attribute to be removed * @return true if the attribute was removed * successfully; false if it was not */ public abstract boolean removeAttribute(Name name); /** * Removes the namespace declaration corresponding to the * given prefix. * @param prefix a String giving * the prefix for which to search * @return true if the namespace declaration was * removed successfully; false if it was * not */ public abstract boolean removeNamespaceDeclaration(String prefix); /** * Returns an iterator over all the immediate content of * this element. This includes Text objects as well * as SOAPElement objects. * @return an iterator with the content of this * SOAPElement object */ public abstract Iterator getChildElements(); /** * Returns an iterator over all the child elements with the * specified name. * @param name a Name object with * the name of the child elements to be returned * @return an Iterator object over all the elements * in this SOAPElement object with the * specified name */ public abstract Iterator getChildElements(Name name); /** * Sets the encoding style for this SOAPElement * object to one specified. * @param encodingStyle a String * giving the encoding style * @throws java.lang.IllegalArgumentException if * there was a problem in the encoding style being set. * @see #getEncodingStyle() getEncodingStyle() */ public abstract void setEncodingStyle(String encodingStyle) throws SOAPException; /** * Returns the encoding style for this * SOAPElement object. * @return a String giving the encoding style * @see #setEncodingStyle(java.lang.String) setEncodingStyle(java.lang.String) */ public abstract String getEncodingStyle(); public abstract void removeContents(); public abstract Iterator getVisibleNamespacePrefixes(); }