public interface SOAPElement extends Node {
// Property Accessor Methods (by property name)
public abstract Iterator getAllAttributes( );
public abstract Iterator getChildElements( );
public abstract Iterator getChildElements( Name name);
public abstract Name getElementName( );
public abstract String getEncodingStyle( );
public abstract void setEncodingStyle(
String encodingStyle) throws SOAPException;
public abstract Iterator getNamespacePrefixes( );
// Public Instance Methods
public abstract SOAPElement addAttribute(Name name, String value)
throws SOAPException;
public abstract SOAPElement addChildElement(SOAPElement element) throws SOAPException;
public abstract SOAPElement addChildElement(String localName)
throws SOAPException;
public abstract SOAPElement addChildElement(Name name)
throws SOAPException;
public abstract SOAPElement addChildElement(String localName,
String prefix) throws SOAPException;
public abstract SOAPElement addChildElement(String localName, String prefix,
String uri) throws SOAPException;
public abstract SOAPElement addNamespaceDeclaration(String prefix,
String uri) throws SOAPException
public abstract SOAPElement addTextNode(String text) throws SOAPException;
public abstract String getAttributeValue( Name name);
public abstract String getNamespaceURI( String prefix);
public abstract boolean removeAttribute( Name name);
public abstract boolean removeNamespaceDeclaration(String prefix);
}
A SOAPElement represents an element within a
SOAPMessage. SOAPElement is
derived from Node and inherits its ability to be
associated with a parent node, thus allowing the construction of a
message as a tree of objects representing the elements and attributes
that will eventually be serialized into XML tags. With the exception
of Text, SOAPPart, and
AttachmentPart, all of the nodes within a
SOAPMessage are SOAPElements.
SOAPElement has a number of derived interfaces
that are used to form particular parts of a SOAP message. For
example, SOAPHeaderElement is a
SOAPElement that appears only as a direct child of
a SOAPHeader. Where these special interfaces
exist, they are the only type of element that can be added to their
particular parent. An attempt to add a SOAPElement
where a more specialized type is required does not, however, result
in an exception. Instead, the element and any child elements it might
have are copied, and the root element is converted to the correct
specialized type before being added to the parent. An attempt to add
a SOAPElement to a SOAPHeader,
for example, would result in an equivalent
SOAPHeaderElement being added instead.
There are several ways to create a SOAPElement.
The simplest way is to use one of the addChildElement(
) methods of an existing SOAPElement,
such as SOAPBody, which both creates a new element
and makes it a child of the original element. There are five variants
of this method.
The addChildElement(Name name) method creates a
new element whose name and namespace prefix are taken from the
supplied Name object. A namespace declaration
linking the namespace prefix to the namespace URI from the
Name object is also added to the element. If the
Name object does not have an explicit namespace,
then neither the namespace prefix nor the namespace declaration
appears on the element.
The addChildElement(String localName) method
creates an element whose name is supplied by the
localName argument and has no explicit namespace.
The element is therefore in the default namespace declared by the
nearest ancestor that has an xlmns: namespace
declaration, or it is declared by itself if such a declaration is
added using the addNamespaceDeclaration( ) method.
The addChildElement(String localName, String prefix, String
uri) method creates an element in which the name, namespace
prefix, and namespace URI are obtained from the method arguments. A
namespace declaration linking the prefix and URI are included. For
example, the method call addChildElement("BookQuery",
"book", "urn:BookService") would create an element that
would be serialized as book:BookQuery
xmlns:book="urn:BookService".
The addChildElement(String localName, String
prefix) method creates an element with the given local name
and namespace prefix. A mapping from the given prefix to a URI must
have been provided by an ancestor of the newly created element, or a
SOAPException is thrown.
The addChildElement(SOAPElement element) method
adds either an existing element or a copy of that element (and any
child elements it might have) as a child of the element on which it
is invoked. The specification of this method warns that application
code should not assume that the element itself is added, and a copy
is actually added in the reference implementation.
All of the addChildElement( ) methods return a
reference to the SOAPElement that was created
and/or added. This can be useful if you want to create several nested
elements in a single line of code:
body.addChildElement("Level1").addChildElement("Level2").
addChildElement("Level3").addTextNode("Text");
This code adds three levels of nested elements. The
addTextNode( ) adds the text passed to it below
the SOAPElement on which it is called and returns
a reference to that SOAPElement. The result of
executing this code is the following:
<Level1>
<Level2>
<Level3>Text</Level3>
</Level2>
</Level1>
SOAPElement provides a group of methods that allow
you to add and manipulate attributes. The addAttribute(
) method adds an attribute whose name and namespace prefix
are given by the Name argument and equates it to
the supplied attribute value. If the Name object
does not have an associated namespace, then no namespace prefix
appears in the serialized XML. The setEncodingStyle(
) method is a convenience method that allows you to set the
attribute that represents the SOAP encoding style that applies to an
element and its descendents without having to explicitly name the
attribute. The following code extract sets the default SOAP encoding
rules:
element.setEncodingStyle(SOAPConstants.URI_NS_SOAP_ENCODING);
The getEncodingStyle( ) method returns the
encoding style set for the element on which it is invoked. Note that
this method does not search the ancestors of the element for an
inherited encoding style if the element itself does not specify
one�it simply returns null. The
getAttributeValue( ) method can be used to obtain
the value of an attribute given its Name. If the
given attribute is not present, then null is
returned. You can get an Iterator containing a
Name object for each attribute attached to an
element by calling the getAllAttributes( ) method,
and you can remove an attribute with removeAttribute(
).
The final group of SOAPElement methods handles
namespaces. addNamespaceDeclaration( ) adds a
namespace declaration to the element that links the given namespace
prefix to its URI. For example, the following code links the
namespace prefix book to the URI
urn:BookService for the scope of the element
referred to by the element variable and its child
elements:
element.addNamespaceDeclaration("book", "urn:BookService");
The serialized XML for this element looks like this, assuming the
element is called BookName:
<BookName xmlns:book="urn:BookService"/>
If the prefix is supplied as the empty string, then a declaration of
the default namespace is being made (i.e.,
xmlns="urn:BookService"). The
removeNamespaceDeclaration( ) method removes a
namespace declaration from an element given its namespace prefix. The
getNamespacePrefixes( ) method returns an
Iterator in which each element is a string that
represents the prefix of a namespace declaration attached to the
element on which it is invoked. To get the namespace URI for a given
prefix, use the getNamespaceURI( ) method.
