The SOAP Message

Having surveyed the SOAP messaging layers, let’s examine the SOAP
message itself. Although the work of rendering a SOAP message in XML is taken
care of by the SAAJ implementation, you must still understand its structure
in order to make the SAAJ calls in the right order.

A SOAP message is an XML document that consists
of a SOAP envelope, an optional SOAP header, and a SOAP body. The SOAP message
header contains information that allows the message to be routed through one
or more intermediate nodes before it reaches its final destination.

The envelope is the root element of the
XML document representing the message. It defines the framework for how the
message should be handled and by whom. Once it encounters the Envelope element,
the SOAP processor knows that the XML is a SOAP message and can then look
for the individual parts of the message.

The header is a generic mechanism for
adding features to a SOAP message. It can contain any number of child elements
that define extensions to the base protocol. For example, header child elements
might define authentication information, transaction information, locale information,
and so on. The actors, the software that handle the message
may, without prior agreement, use this mechanism to define who should deal
with a feature and whether the feature is mandatory or optional.

The body is a container for mandatory
information intended for the ultimate recipient of the message.

A SOAP message may also contain an attachment, which does not have to
be in XML. For more information, see SOAP Packaging Models next.

A SOAP message is constructed like a nested matrioshka doll. When you
use SAAJ to assemble or disassemble a message, you need to make the API calls
in the appropriate order to get to the message part that interests you. For
example, in order to add content to the message, you need to get to the body
part of the message. To do this you need to work through the nested layers:
SOAP part, SOAP envelope, SOAP body, until you get to the SOAP body element
that you will use to specify your data. For more information, see The SOAP Message Object.