What is SOAP?

SOAP, the Simple Object Access Protocol, is a protocol that allows the
exchange of structured data between peers in a decentralized, distributed
environment. The structure of the data being exchanged is specified by an
XML scheme.

The fact that SOAP messages are encoded in XML makes SOAP messages portable,
because XML is a portable, system-independent way of representing data. By
representing data using XML, you can access data from legacy systems as well
as share your data with other enterprises. The data integration offered by
XML also makes this technology a natural for Web-based computing such as Web services. Firewalls can recognize SOAP packets based on their
content type (text/xml-SOAP) and can filter messages based
on information exposed in the SOAP message header.

The SOAP specification describes a set of conventions for exchanging
XML messages. As such, it forms a natural foundation for Web services that
also need to exchange information encoded in XML. Although any two partners
could define their own protocol for carrying on this exchange, having a standard
such as SOAP allows developers to build the generic pieces that support this
exchange. These pieces might be software that adds functionality to the basic
SOAP exchange, or might be tools that administer SOAP messaging, or might
even comprise parts of an operating system that supports SOAP processing.
Once this support is put in place, other developers can focus on creating
the Web services themselves.

The SOAP protocol is fully described at http://www.w3.org/TR/SOAP. This
section restricts itself to discussing the reasons why you would use SOAP
and to describing basic concepts that will make it easier to work with SOAP
messages.

SOAP with Attachments API for Java

The Soap with Attachments API for Java (SAAJ) is a JAVA-based API that
enforces compliance to the SOAP standard. When you use this API to assemble
and disassemble SOAP messages, it ensures the construction of syntactically
correct SOAP messages. SAAJ also makes it possible to automate message processing
when several applications need to handle different parts of a message before
forwarding it to the next recipient.

Figure 5–1 shows the layers that
can come into play in the implementation of SOAP messaging. This chapter focuses
on the SOAP and language implementation layers.

Figure 5–1 SOAP Messaging Layers

The sections that follow describe each layer shown in the preceding
figure in greater detail. The rest of this chapter focuses on the SOAP and
language implementation layers.

The Transport Layer

Underlying any messaging system is the transport or wire protocol that
governs the serialization of the message as it is sent across a wire and the
interpretation of the message bits when it gets to the other side. Although
SOAP messages can be sent using any number of protocols, the SOAP specification
defines only the binding with HTTP. SOAP uses the HTTP request/response message
model. It provides SOAP request parameters in an HTTP request and SOAP response
parameters in an HTTP response. The HTTP binding has the advantage of allowing
SOAP messages to go through firewalls.

The SOAP Layer

Above the transport layer is the SOAP layer. This layer, which is defined
in the SOAP Specification, specifies the XML scheme used to identify the message
parts: envelope, header, body, and attachments. All SOAP message parts and
contents, except for the attachments, are written in XML. The following sample
SOAP message shows how XML tags are used to define a SOAP message:

The wire transport and SOAP layers are actually sufficient to do SOAP
messaging. You could create an XML document that defines the message you want
to send, and you could write HTTP commands to send the message from one side
and to receive it on the other. In this case, the client is limited to sending
synchronous messages to a specified URL. Unfortunately, the scope and reliability
of this kind of messaging is severely restricted. To overcome these limitations,
the provider and profile layers
are added to SOAP messaging.

The Language Implementation Layer

A language implementation allows you to create XML messages that conform
to SOAP, using API calls. For example, the SAAJ implementation of SOAP, allows
a Java client to construct a SOAP message and all its parts as Java objects.
The client would also use SAAJ to create a connection and use it to send the
message. Likewise, a Web service written in Java could use the same implementation
(SAAJ), or any other language implementation, to receive the message, to disassemble
it, and to acknowledge its receipt.

The Profiles Layer

In addition to a language implementation, a SOAP implementation can
offer services that relate to message delivery. These could include reliability,
persistence, security, and administrative control, and are typically delivered
by a SOAP messaging provider. These services will be provided for SOAP messaging
by Message Queue in future releases.

Interoperability

Because SOAP providers must all construct and deconstruct messages as
defined by the SOAP specification, clients and services using SOAP are interoperable.
That is, as shown in Figure 5–2, the
client and the service doing SOAP messaging do not need to be written in the
same language nor do they need to use the same SOAP provider. It is only the
packaging of the message that must be standard.

Figure 5–2 SOAP Interoperability

In order for a SAAJ client or service to interoperate with a service
or client using a different implementation, the parties must agree on two
things:

They must use the same transport bindings--that is, the same
wire protocol.

They must use the same profile in constructing the SOAP message
being sent.

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.

SOAP Packaging Models

The SOAP specification describes two models of SOAP messages: one that
is encoded entirely in XML and one that allows the sender to add an attachment
containing non-XML data. You should look over the following two figures and
note the parts of the SOAP message for each model. When you use SAAJ to define
SOAP messages and their parts, it will be helpful for you to be familiar with
this information.

Figure 5–3 shows the SOAP model
without attachments. This package includes a SOAP envelope, a header, and
a body. The header is optional.

Figure 5–3 SOAP Message Without Attachments

When you construct a SOAP message using SAAJ, you do not have to specify
which model you’re following. If you add an attachment, a message like
that shown in Figure 5–4 is constructed;
if you don’t, a message like that shown in Figure 5–3 is constructed.

Figure 5–3 shows a SOAP Message
with attachments. The attachment part can contain any kind of content: image
files, plain text, and so on. The sender of a message can choose whether to
create a SOAP message with attachments. The message receiver can also choose
whether to consume an attachment.

A message that contains one or more attachments is enclosed in a MIME
envelope that contains all the parts of the message. In SAAJ, the MIME envelope
is automatically produced whenever the client creates an attachment part.
If you add an attachment to a message, you are responsible for specifying
(in the MIME header) the type of data in the attachment.