Document, RPC, Literal, Encoded

Much of the confusion in understanding SOAP comes from the fact that several of the key terms are overloaded. For example, both SOAP RPC (meaning the convention for performing remote procedure calls via SOAP) and RPC style are both valid pieces of SOAP terminology. In this section we clarify the meaning of each of these terms so they do not cause further confusion as we begin discussing WSDL.

Document

Document-style SOAP refers to the way in which the application payload is hosted within the SOAP Body element. When we use document style, it means the document is placed directly as a child of the Body element, as shown on the left in Figure 3-22, where the application content is a direct child of the <soap:Body> element.

Figure 3-22. Document, RPC, Literal, and Encoded SOAP messages.

RPC

RPC-style SOAP wraps the application content inside an element whose name can be used to indicate the name of a method to dispatch the content to. This is shown on the right-hand side of Figure 3-22, where we see the application content wrapped <m:purchase> element.

Literal

Literal SOAP messages use arbitrary schemas to provide the meta-level description (and constraints) of the SOAP payload. Thus when using literal SOAP, we see that it is akin to taking an instance document of a particular schema and embedding it directly into the SOAP message, as shown at the top of Figure 3-22.

Encoded

SOAP-encoded messages are created by transforming application-level data structures via the SOAP Data Model into a XML format that conforms to the SOAP Schema. Thus, encoded messages tend to look machine-produced and may not generally resemble the same message expressed as a literal. Encoded messages are shown at the bottom of Figure 3-22.

SOAP RPC and SOAP Document-Literal

The SOAP specification provides four ways in which we could package SOAP messages, as shown in Figure 3-22. However, in Web services we tend to use only two of them: SOAP encoded-rpc (when combined with a request-response protocol becomes the SOAP RPC convention) and SOAP document-literal.

Document-literal is the preferred means of exchanging SOAP messages since it just packages application-level XML documents into the SOAP Body for transport without placing any semantics on the content.

As we have previously seen, with SOAP RPC the implied semantics are that the first child of the SOAP Body element names a method to which the content should be dispatched.

The remaining two options, document-encoded and rpc-literal, are seldom used since they mix styles to no great effect. Encoding documents is pointless if we already have schemas that describe them. Similarly, wrapping a document within a named element is futile unless we are going to use that convention as a remote procedure call mechanism. Since we already have SOAP RPC, this is simply a waste of effort.