javax.xml.soap.SOAPElement Maven / Gradle / Ivy
/*
* Copyright 2001-2004 The Apache Software Foundation.
*
* Licensed 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();
}