Anatomy of a SOAP Message

Using SOAP RPC Messages

One of the original design goals of SOAP was to provide an open and standard way to facilitate RPCs using Internet technologies such as XML and HTTP. In this section, I explain the method of encoding RPC-style messages described in version 1.1 of the SOAP specification.

As I stated earlier in the chapter, the SOAP specification does not dictate the way messages should be encoded, and encoding RPC-style messages is no exception. Section 7 of the SOAP 1.1 specification describes the recommended way to encode the request and response messages. The developer is free to create her own method of encoding RPC communication. In this section, however, I limit the discussion to the “standard” method of encoding RPC-style SOAP messages.

To facilitate the request/response behavior needed by RPC, you need two SOAP messages: one for the request and one for the response. Here is how the request message would be encoded for a simple C# function that adds two numbers:

public int Add(int x, int y) {     return x + y; }

The Add method accepts two integers as input parameters and passes the result back to the client as a return parameter. The input parameters must be packaged within the body of the request message so that they can be sent to the target application. This is accomplished by packaging the parameters in a struct-like format. Here is the resulting request message for Add(1, 2):

<?xml version="1.0"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">   <soap:Body>     <Add>       <x>1</x>       <y>2</y>     </Add>   </soap:Body> </soap:Envelope>

The Body element contains an Add element. Each of the input parameters is represented as a subelement within the Add element. The order of the x and y elements must match the order in which the parameters are specified in the method signature. In other words, placing y before x would be invalid. Furthermore, the names and the types of the Add, x, and y elements must be the same as the target method and its parameters. I will explain data typing in the next chapter. For now, suffice it to say that the body of the request message must be in a format expected by the remote application.

Now that I have created a properly formatted request message, take a look at the response generated by the remote application:

<?xml version="1.0"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">   <soap:Body>     <AddResult>       <result>1</result>     </AddResult>   </soap:Body> </soap:Envelope>

The response message returned by the remote application contains the result of the Add method. The return parameter is once again encoded in a struct-like format within the body of the SOAP message. The naming convention of the subelement within the body is the name of the method with Result appended to it. However, this naming convention is not dictated by the specification. The first (and in this case, only) parameter contains the return parameter of the method call. As with the AddResult element, the name of the element that contains the return parameter is not dictated by the specification.

What if more than one parameter is returned to the client? Let's take a look at a slight variation of the Add method. Add2 returns the sum of the two numbers via an output parameter.

public int Add2(int x, int y, out int sum) {     sum = x + y;     return sum; }

Calling Add2(1, 2)produces the following SOAP message:

<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">   <soap:Body>     <Add2>       <x>1</x>       <y>2</y>     </Add2>   </soap:Body> </soap:Envelope>

Notice that the third parameter, sum, does not get encoded. Because sum is declared as an output parameter, there is no reason to send its initial value to the remote application. Here is the response:

<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">   <soap:Body>     <Add2Response>       <Add2Result>3</Add2Result>       <sum>3</sum>     </Add2Response>   </soap:Body> </soap:Envelope>

The response message contains the value of two parameters. As I mentioned earlier, the return parameter must always be listed first. I called the element containing the return parameter Add2Result to demonstrate that the name is not relevant. The value of the sum parameter is listed next.