SOAP (Simple Object Access Protocol)
If you haven't heard of it by now, you've
probably been living under a rock somewhere. It's become the newest craze in web programming,
and is integral to the web services fanaticism that has taken hold of the latest generation
of web development. If you've heard of .NET from Microsoft or the peer-to-peer "revolution,"
then you've heard about technologies that rely on SOAP (even if you don't know it).
There's not one but two SOAP implementations going on, one over at Apache, and the other at Microsoft.
SOAP is a lightweight protocol for exchange of information in a decentralized,
distributed environment. It is an XML based protocol that consists of three parts:
an envelope that defines a framework for describing what is in a message and how
to process it, a set of encoding rules for expressing instances of application-defined
datatypes, and a convention for representing remote procedure calls and responses.
SOAP can potentially be used in combination with a variety of other protocols;
however, the only bindings defined in this document describe how to use SOAP in
combination with HTTP and HTTP Extension Framework.
Introduction
SOAP provides a simple and lightweight mechanism for exchanging structured and typed
information between peers in a decentralized, distributed environment using XML.
SOAP does not itself define any application semantics such as a programming model or
implementation specific semantics; rather it defines a simple mechanism for expressing
application semantics by providing a modular packaging model and encoding mechanisms
for encoding data within modules. This allows SOAP to be used in a large variety of
systems ranging from messaging systems to RPC.
SOAP consists of three parts:
- The SOAP envelope (see section 4) construct defines an overall framework for expressing what is in a message; who should deal with it, and whether it is optional or mandatory.
- The SOAP encoding rules (see section 5) defines a serialization mechanism that can be used to exchange instances of application-defined datatypes.
- The SOAP RPC representation (see section 7) defines a convention that can be used to represent remote procedure calls and responses.
Although these parts are described together as part of SOAP, they are functionally orthogonal. In particular, the envelope and the encoding rules are defined in different namespaces in order to promote simplicity through modularity.
In addition to the SOAP envelope, the SOAP encoding rules and the SOAP RPC conventions, this specification defines two protocol bindings that describe how a SOAP message can be carried in HTTP [5] messages either with or without the HTTP Extension Framework [6].
Design Goals
A major design goal for SOAP is simplicity and extensibility. This means that there are several
features from traditional messaging systems and distributed object systems that are not part of
the core SOAP specification.
Such features include
Distributed garbage collection
Boxcarring or batching of messages
Objects-by-reference (which requires distributed garbage collection)
Activation (which requires objects-by-reference)
Relation to XML
All SOAP messages are encoded using XML.
A SOAP application SHOULD include the proper SOAP namespace on all elements and attributes defined by SOAP in messages that it generates. A SOAP application MUST be able to process SOAP namespaces in messages that it receives. It MUST discard messages that have incorrect namespaces and it MAY process SOAP messages without SOAP namespaces as though they had the correct SOAP namespaces.
SOAP defines two namespaces:
The SOAP envelope has the namespace identifier.
The SOAP serialization has the namespace identifier.
A SOAP message MUST NOT contain a Document Type Declaration. A SOAP message MUST NOT contain Processing Instructions.
SOAP uses the local, unqualified "id" attribute of type "ID" to specify the unique identifier of an encoded element. SOAP uses the local, unqualified attribute "href" of type "uri-reference" to specify a reference to that value, in a manner conforming to the XML Specification, XML Schema Specification, and XML Linking Language Specification.
With the exception of the SOAP mustUnderstand attribute and the SOAP actor attribute, it is generally permissible to have attributes and their values appear in XML instances or alternatively in schemas, with equal effect. That is, declaration in a DTD or schema with a default or fixed value is semantically equivalent to appearance in an instance.
SOAP Envelope
A SOAP message is an XML document that consists of a mandatory SOAP envelope, an optional SOAP header, and a mandatory SOAP body. This XML document is referred to as a SOAP message for the rest of this specification. The namespace identifier for the elements and attributes defined in this section is.
A SOAP message contains the following:
The Envelope is the top element of the XML document representing the message.
The Header is a generic mechanism for adding features to a SOAP message in a decentralized manner without prior agreement between the communicating parties. SOAP defines a few attributes that can be used to indicate who should deal with a feature and whether it is optional or mandatory.
The Body is a container for mandatory information intended for the ultimate recipient of the message. SOAP defines one element for the body, which is the Fault element used for reporting errors.
The grammar rules are as follows:
- Envelope
- The element name is "Envelope".
- The element MUST be present in a SOAP message
- The element MAY contain namespace declarations as well as additional attributes. If present, such additional attributes MUST be namespace-qualified. Similarly, the element MAY contain additional sub elements. If present these elements MUST be namespace-qualified and MUST follow the SOAP Body element.
- Header
- The element name is "Header".
- The element MAY be present in a SOAP message. If present, the element MUST be the first immediate child element of a SOAP Envelope element.
- The element MAY contain a set of header entries each being an immediate child element of the SOAP Header element. All immediate child elements of the SOAP Header element MUST be namespace-qualified.
- Body
- The element name is "Body".
- The element MUST be present in a SOAP message and MUST be an immediate child element of a SOAP Envelope element. It MUST directly follow the SOAP Header element if present. Otherwise it MUST be the first immediate child element of the SOAP Envelope element.
- The element MAY contain a set of body entries each being an immediate child element of the SOAP Body element. Immediate child elements of the SOAP Body element MAY be namespace-qualified. SOAP defines the SOAP Fault element, which is used to indicate error messages
SOAP provides a flexible mechanism for extending a message in a decentralized and modular way without prior knowledge between the communicating parties. Typical examples of extensions that can be implemented as header entries are authentication, transaction management, payment etc.
The Header element is encoded as the first immediate child element of the SOAP Envelope XML element. All immediate child elements of the Header element are called header entries.
The encoding rules for header entries are as follows:
- A header entry is identified by its fully qualified element name, which consists of the namespace URI and the local name. All immediate child elements of the SOAP Header element MUST be namespace-qualified.
- The SOAP encodingStyle attribute MAY be used to indicate the encoding style used for the header entries (see section.
- The SOAP mustUnderstand attribute and SOAP actor attribute MAY be used to indicate how to process the entry and by whom.
The SOAP Body element provides a simple mechanism for exchanging mandatory information intended for the ultimate recipient of the message. Typical uses of the Body element include marshalling RPC calls and error reporting.
The Body element is encoded as an immediate child element of the SOAP Envelope XML element. If a Header element is present then the Body element MUST immediately follow the Header element, otherwise it MUST be the first immediate child element of the Envelope element.
All immediate child elements of the Body element are called body entries and each body entry is encoded as an independent element within the SOAP Body element.
The encoding rules for body entries are as follows:
- A body entry is identified by its fully qualified element name, which consists of the namespace URI and the local name. Immediate child elements of the SOAP Body element MAY be namespace-qualified.
- The SOAP encodingStyle attribute MAY be used to indicate the encoding style used for the body entries.
SOAP defines one body entry, which is the Fault entry used for reporting errors
Relationship between SOAP Header and Body
While the Header and Body are defined as independent elements, they are in fact related. The relationship between a body entry and a header entry is as follows: A body entry is semantically equivalent to a header entry intended for the default actor and with a SOAP mustUnderstand attribute with a value of "1". The default actor is indicated by not using the actor attribute
A Quick Introduction to WSDL
The Web Services Description Language (WSDL) is an XML-based language for describing the network services offered by the server. You use WSDL to create a file that identifies the services provided by the server and the set of operations within each service that the server supports. For each of the operations, the WSDL file also describes the message format that the client must follow in requesting an operation.
The WSDL document is like a contract between the client and server. The server agrees to provide certain services only if the client sends a properly formatted SOAP request message.
To illustrate, suppose a WSDL file defines a service called StockQuoteService, which describes operations such as GetLastTradePrice, GetLowestPriceOfTheDay, and GetHighestPriceOfTheDay. You place this WSDL file on the server. A client who wishes to send a SOAP request to this service obtains a copy of this WSDL file from the server. The client then uses the information in this file to format a SOAP request message. The client sends this request to the server. The server executes the requested operation and sends the resulting stock price back to the client as a SOAP response message.
In addition to creating a Web Services Description Language (WSDL) file describing the services and operations on the server, you need to create a Web Services Meta Language (WSML) file on the server.
Note The use of a WSML file is specific to the SOAP Toolkit.
A WSML file provides information that maps the operations of a service (as described in the WSDL file) to specific methods in the COM object. The WSML file determines which COM object to load in order to service the request for each operation.
Consider this WSML fragment:
In this WSML fragment, there is one <service> element, which has <using> and <port> child elements.
The <using> element specifies the COM object used by the service.
The <port> element lists all the operations. For each operation, the <execute> element maps the operation to a method on the specified COM object.
Using SOAP in HTTP
This section describes how to use SOAP within HTTP with or without using the HTTP Extension Framework. Binding SOAP to HTTP provides the advantage of being able to use the formalism and decentralized flexibility of SOAP with the rich feature set of HTTP. Carrying SOAP in HTTP does not mean that SOAP overrides existing semantics of HTTP but rather that the semantics of SOAP over HTTP maps naturally to HTTP semantics.
SOAP naturally follows the HTTP request/response message model providing SOAP request parameters in a HTTP request and SOAP response parameters in a HTTP response. Note, however, that SOAP intermediaries are NOT the same as HTTP intermediaries. That is, an HTTP intermediary addressed with the HTTP Connection header field cannot be expected to inspect or process the SOAP entity body carried in the HTTP request.
HTTP applications MUST use the media type "text/xml" according to RFC 2376 when including SOAP entity bodies in HTTP messages.
SOAP HTTP Request
Although SOAP might be used in combination with a variety of HTTP request methods, this binding only defines SOAP within HTTP POST requests.
DIME (Direct Internet Message Encapsulation)
The SOAP Toolkit uses the DIME binary message format for SOAP messages with one or more attachments. DIME is a binary message format that defines how to construct a single message with multiple payloads of arbitrary types and sizes.
As per the DIME format, each message consists of one or more DIME records. Each DIME record carries a payload of arbitrary type and size. Each DIME record describes its payload using three parameters.
Payload length -
Describes length of the payload in the record (in bytes).
Payload type -
Describe the kind of data being carried in the payload of that record.
Payload identifier -
Provides a unique identifier for the payload.
Quick Start Instructions:
- Download the ZIP file.
- Unzip to a separate directory.
- Look for the readme.txt file that describes how to build and test.
