javax.xml.soap.SOAPElement Maven / Gradle / Ivy
/*
* 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 javax.xml.namespace.QName;
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 javax.xml.soap.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 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(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();
public abstract SOAPElement addAttribute(javax.xml.namespace.QName qname,
java.lang.String value)
throws SOAPException;
public abstract SOAPElement addChildElement(javax.xml.namespace.QName qname)
throws SOAPException;
public abstract javax.xml.namespace.QName createQName(String localName, String prefix)
throws SOAPException;
public abstract java.util.Iterator getAllAttributesAsQNames();
public abstract java.lang.String getAttributeValue(javax.xml.namespace.QName qname);
public abstract java.util.Iterator getChildElements(QName name);
public abstract javax.xml.namespace.QName getElementQName();
boolean removeAttribute(javax.xml.namespace.QName qname);
public abstract SOAPElement setElementQName(javax.xml.namespace.QName newName)
throws SOAPException;
}