/* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. */ 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(); /** * Detaches all children of this SOAPElement. *

* This method is useful for rolling back the construction of partially * completed SOAPHeaders and SOAPBodys in * reparation for sending a fault when an error condition is detected. It is * also useful for recycling portions of a document within a SOAP message. */ public abstract void removeContents(); /** * Returns an Iterator over the namespace prefix * Strings visible to this element. The prefixes returned by * this iterator can be passed to the method getNamespaceURI() * to retrieve the URI of each namespace. * * @return an iterator over the namespace prefixes are within scope of this * SOAPElement object */ public abstract Iterator getVisibleNamespacePrefixes(); }