Sending SOAP messages

Sending SOAP messages

The primary motivation for developing the SOAP specification has been to find a way to make RPC architectures simpler and less problematic. The problems with DCOM and CORBA—vendor dependence, firewall unfriendliness, and unnecessary complexity—led to the development of early XML-based RPC architectures, such as XML-RPC.

XML-RPC paved the way for SOAP. Although XML-RPC was a straightforward applica-tion of XML, it did not take advantage of XML namespaces and was therefore not fully extensible. For this reason, SOAP was originally thought of as a namespace-capable aug-mentation to XML-RPC.

Even though SOAP is primarily intended to be used as part of an RPC architecture and its heritage is firmly in the RPC camp, it nevertheless does not require a synchronous request/response mechanism. In fact, SOAP supports four types of operations:

   A request-response operation, which is bidirectional. In this type of operation, the server receives a message from the client and replies with a response message.

   A solicit-response operation, which is also bidirectional, except that the server solicits a request from the client, who then responds, essentially putting the response before the request.

   A one-way message sent from the client to the server with no response message returned.

   A notification message sent from the server to the client.

In essence, the bidirectional messages are inverses of each other, as are the unidirectional ones. In addition to these four basic operations, SOAP also supports the forwarding by intermediaries, which can also be either unidirectional or bidirectional. Furthermore, SOAP faults are only supported by bidirectional messages.

Because of SOAP’s flexibility regarding message type, in combination with the fact that it is a text-based protocol, SOAP messages can go over any number of different proto-cols: HTTP, SMTP, FTP, and so on. However, HTTP has become the predominant trans-fer protocol for SOAP because of its request-response mechanism, its ubiquity, and its familiarity. Nevertheless, it is still important to point out some asynchronous applications of SOAP as well.

SOAP and HTTP

HTTP supports two request methods: GET and POST. The GET method sends its parame-ters in the URL and is typically used to request Web pages from a Web server. The POST method sends data to the server in a payload that comes after the HTTP header. Because POST payloads can be of indefinite length, SOAP requests transmitted via HTTP are sent as HTTP POST requests.

Here’s the format of a simple HTTP POST request that you might send when submitting a form on a Web page:

POST  /mypath  HTTP/1.1

Host:  123.45.67.89

Content-Type:  text/plain;  charset=”utf-8”

Content-Length:  20

This  is  the  payload.

The first line of the HTTP request contains the method, the URI of the recipient, and the HTTP version. The second line contains the IP address of the sender. The third line spec-ifies the MIME type and the character encoding of the request, and the fourth line tells the server how many characters to expect in the payload. Following the fourth line is an extra carriage return/linefeed (required by the HTTP protocol) and then the payload itself, which is arbitrary text.

Now, let’s take a look at an HTTP POST request that contains a simple SOAP message:

POST  /mypath  HTTP/1.1

Host:  123.45.67.89

Content-Type:  text/xml

Content-Length:  300

SOAPMethodName:  urn:mysite-com:PhoneNumber#getPhoneNumber

<SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/” SOAP-ENV:encodingStyle=”http://schemas.xmlsoap.org/soap/encoding/”> <SOAP-ENV:Body>

<ns:getPhoneNumber xmlns:ns=”PhoneNumber”> <name>John Doe</name>

</ns:getPhoneNumber> </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

In this request, the URI /mypath indicates the SOAP endpoint: It is up to the server to translate this URI into the location of the application charged with accepting this request. The Content-Type for all SOAP messages must be text/xml (as opposed to text/plain for Web pages).

SOAP requests must also contain the additional SOAPMethodName HTTP header. This header indicates the method that is to be called (in this case, the getPhoneNumber method of the PhoneNumber class). This header is scoped by a URI using a # character as a delimiter. The payload for this request is simply the SOAP Envelope element.

Now, let’s look at HTTP responses. In the case of a simple Web page, an HTTP response looks like this:

HTTP/1.0  200  OK

Content-Type:  text/plain;  charset=”utf-8”

Content-Length:  38

<html><body> 617-555-6789 </body></html>

The first line of this response always contains the HTTP status code, which in this case is 200 (indicating success). Other failure codes include 400 Bad Request and the all-too-familiar 404 Not Found. The second and third lines are analogous to the request, as is the carriage return/linefeed. Finally, the server sends the payload, which in this case is the HTML for a Web page that displays John Doe’s phone number.

A SOAP response looks pretty much the way you would expect:

HTTP/1.0  200  OK

Content-Type:  text/xml

Content-Length:  374

<SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/” SOAP-ENV:encodingStyle=”http://schemas.xmlsoap.org/soap/encoding/”>

<SOAP-ENV:Body>

<m:getPhoneNumberResponse xmlns:m=”urn:mysite-com:PhoneNumber”> <areacode>617</areacode>

<numberbody>555-1234</numberbody> </m:getPhoneNumberResponse>

</SOAP-ENV:Body> </SOAP-ENV:Envelope>

Note that the URN for the receiving class appears in the getPhoneNumberResponse ele-ment, but there is no SOAPMethodName HTTP header. Such headers are only required for HTTP requests and are not allowed in responses. In addition, if the server encounters an error and returns a SOAP fault, the first line of the HTTP header would be this:

500  Internal  Server  Error

Header Extensions

HTTP is a mature protocol that was developed to support the connectionless, stateless world of Web pages. However, HTTP’s inability to guarantee message delivery threat-ened to constrain its usefulness in the world of Web Services. As a result, the HTTP extension framework was developed to allow for additional functionality within the con-fines of the HTTP specification.

Here is an example of an HTTP POST request that takes advantage of the HTTP exten-sion framework:

M-POST  /mypath  HTTP/1.1

Host:  123.45.67.89

Content-Type:  text/xml;  charset=”utf-8”

Content-Length:  300

Man: “http://schemas.xmlsoap.org/soap/envelope/”; ns=01 01-SOAPAction: urn:mysite-com:PhoneNumber#getPhoneNumber

<SOAP-ENV:Envelope

...

The first line of the preceding request contains the M-POST method, where M indicates mandatory. A mandatory HTTP request must include at least one mandatory extension declaration, which uses either the Man or C-Man header field. (The C-Man header field is used for “hop-by-hop” requests that can traverse one or more intermediaries.)

In this example, the Man header request indicates the default Envelope namespace and maps the header prefix 01 to the namespace. The next line then attaches this prefix to the SOAPAction field.

The server’s response to this request (assuming there are no errors) appears as such:

HTTP/1.0  200  OK

Ext:

Content-Type:  text/xml;  charset=”utf-8”

Content-Length:  374

<SOAP-ENV:Envelope

...

The Ext: header (or C-Ext: header, in the case of a hop-by-hop response) simply indi-cates that the mandatory extension declarations were fulfilled by the server.

SOAP and SMTP

The Simple Mail Transport Protocol (SMTP) is the established standard protocol for sending e-mail messages. Because SOAP envelopes are nothing more than text mes-sages, e-mailing them is elementary on the surface. However, there are several issues that must be dealt with when using SMTP to send a message to an application.

A SOAP message sent via SMTP goes to a mailbox and waits for the server to act upon it. The mailbox will be typically provided by a Post Office Protocol (POP3) server. Therefore, in order for the server to access the SOAP message in a mailbox, the server will typically use a POP3-to-HTTP bridge to post the incoming message to the process-ing application, and then take the response and use an HTTP-to-SMTP bridge to send it back to the client. The client must then poll its own POP3 mailbox in order to accept the message.

Alternately, it is possible to custom-code a POP3-compliant application that can parse SOAP messages directly as well as create the responses. Furthermore, because SMTP is an asynchronous protocol, its best application may be for those SOAP messages that are unidirectional.