OReilly Java Web Services In A Nutshell Jun 2003 ISBN 0596003994

SAAJ 1.1; JWSDP 1.0, J2EE 1.4 public interface SOAPElement extends Node { // Property Accessor Methods by property name public abstract Iterator getAllAttributes ; public abstract Ite

SAAJ 1.1; JWSDP 1.0, J2EE 1.4

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

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

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

Implementations

DetailEntry, SOAPBody, SOAPBodyElement, SOAPEnvelope, SOAPFaultElement, SOAPHeader, SOAPHeaderElement

Passed To

Node.setParentElement( ), SOAPElement.addChildElement( )

Returned By

Node.getParentElement( ), SOAPElement.{addAttribute( ),

addChildElement( ), addNamespaceDeclaration( ), addTextNode( )}, SOAPElementFactory.create( ), SOAPFactory.createElement( )