The SOAP Message Object

A SOAP Message Object is a tree of objects as shown in Figure 5–5. The classes or interfaces from
which these objects are derived are all defined in the javax.xml.soap package.

Figure 5–5 SOAP Message Object

As shown in the figure, the SOAPMessage object is
a collection of objects divided in two parts: a SOAP part and an attachment
part. The main thing to remember is that the attachment part can contain non-xml
data.

The SOAP part of the message contains an envelope that contains a body
(which can contain data or fault information) and an optional header. When
you use SAAJ to create a SOAP message, the SOAP part, envelope, and body are
created for you: you need only create the body elements. To do that you need
to get to the parent of the body element, the SOAP body.

In order to reach any object in the SOAPMessage tree, you must traverse
the tree starting from the root, as shown in the following lines of code.
For example, assuming the SOAPMessage is MyMsg, here are
the calls you would have to make in order to get the SOAP body:

At this point, you can create a name for a body element (as described
in Namespaces) and add the body element to
the SOAPMessage.

For example, the following code line creates a name (a representation
of an XML tag) for a body element:

Name bodyName = envelope.createName("Temperature");

The next code line adds the body element to the body:

SOAPBodyElement myTemp = MyBody.addBodyElement(bodyName);

Finally, this code line defines some data for the body element bodyName :

myTemp.addTextNode("98.6");

Inherited Methods

The elements of a SOAP message form a tree. Each node in that tree implements
the Node interface and, starting at the envelope level,
each node implements the SOAPElement interface as well.
The resulting shared methods are described in Table 5–1.

Create a new SOAPElement object, initialized with
the given Name object, and add the new element

(Use the Envelope.createName method to create a Name object)

addNameSpaceDeclaration
(String, String)

Add a namespace declaration with the specified prefix and URI

addTextnode(String)

Create a new Text object initialized with the given String and add it to this SOAPElement object

getAllAttributes()

Return an iterator over all the attribute names in this object

getAttributeValue(Name)

Return the value of the specified attribute

getChildElements()

Return an iterator over all the immediate content of this element

getChildElements(Name)

Return an iterator over all the child elements with the specified name

getElementName()

Return the name of this object

getEncodingStyle()

Return the encoding style for this object

getNameSpacePrefixes()

Return an iterator of namespace prefixes

getNamespaceURI(String)

Return the URI of the namespace with the given prefix

removeAttribute(Name)

Remove the specified attribute

removeNamespaceDeclaration
(String)

Remove the namespace declaration that corresponds to the specified prefix

setEncodingStyle(String)

Set the encoding style for this object to that specified by String

Node

detachNode()

Remove this Node object from the tree

getParentElement()

Return the parent element of this Node object

getValue

Return the value of the immediate child of this Node object
if a child exists and its value is text

recycleNode()

Notify the implementation that his Node object is
no longer being used and is free for reuse

setParentElement(SOAPElement)

Set the parent of this object to that specified by the SOAPElement parameter

Namespaces

An XML namespace is a means of qualifying element
and attribute names to disambiguate them from other names in the same document.
This section provides a brief description of XML namespaces and how they are
used in SOAP. For complete information, see http://www.w3.org/TR/REC-xml-names/

An explicit XML namespace declaration takes the following form:

<prefix:myElement
xmlns:prefix ="URI">

The declaration defines prefix as an alias
for the specified URI. In the element myElement, you can
use prefix with any element or attribute to specify
that the element or attribute name belongs to the namespace specified by the
URI.

After defining the alias, you can use it as a prefix to any attribute
or element in the Envelope element. In Example 5–1, the elements <Envelope> and <Body> and the attribute encodingStyle all
belong to the SOAP namespace specified by the http://schemas.sxmlsoap.org/soap/envelope/URI .

Note that the URI that defines the namespace does not have to point
to an actual location; its purpose is to disambiguate attribute and element
names.

Pre-defined SOAP Namespaces

SOAP defines two namespaces:

The SOAP envelope, the root element of a SOAP message, has
the following namespace identifier:

"http://schemas.xmlsoap.org/soap/envelope"

The SOAP serialization, the URI defining SOAP’s serialization
rules, has the following namespace identifier:

"http://schemas.xmlsoap.org/soap/encoding"

When you use SAAJ to construct or consume messages, you are responsible
for setting or processing namespaces correctly and for discarding messages
that have incorrect namespaces.

Using Namespaces when Creating a SOAP Name

When you create the body elements or header elements of a SOAP message,
you must use the Name object to specify a well-formed name
for the element. You obtain a Name object by calling the
method SOAPEnvelope.createName.

When you call this method, you can pass a local name as a parameter
or you can specify a local name, prefix, and URI. For example, the following
line of code defines a name object bodyName.