Architecture

   

The SOAP Protocol

If you know HTTP and XML, you'll learn SOAP in minutes. Essentially, SOAP defines how a client should format its request and how the server should format its answer.

Warning

This discussion is based on SOAP 1.1, the latest version at the time of writing. At the time of writing, SOAP is not formally an Internet standard, but it appears that W3C might define its own XML-based RPC protocol. This new protocol would be based on the same principle as SOAP but might differ in the details.

I will post articles and news as the status of SOAP clarifies at http://www.marchal.com.


SOAP Request

Listing 9.1 is a SOAP request. As you can see, it's an HTTP 1.1 POST request with an XML payload. The SOAP specification mandates the use of HTTP 1.1, POST , and XML. It also mandates the presence of the Content-Length and SOAPAction headers in the request.

SOAPAction is specific to SOAP. It is loosely defined in the specification as a URI identifying the intent of the request. However, it need not be the URL of the Web server (indeed, if you read the header, the request is for localhost/ stockq , not http://www.psol.com/xmlns/stockq).

You should not worry too much about SOAPAction . It was introduced primarily to help firewalls separate SOAP traffic from regular Web requests .

Listing 9.1 A SOAP Request
 POST /stockq HTTP/1.1 Host: localhost Content-Type: text/xml Content-Length: 422 SOAPAction: "http://www.psol.com/xmlns/stockq" <?xml version='1.0'?> <SOAP-ENV:Envelope    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">    <SOAP-ENV:Body>     <psol:getStock          xmlns:psol='http://www.psol.com/xmlns/stockq'          SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>          <manufacturer>Playfield</manufacturer>          <sku>101</sku>       </psol:getStock>    </SOAP-ENV:Body> </SOAP-ENV:Envelope> 

The RPC is encoded as an XML document. SOAP defines the SOAP-ENV:Envelope , SOAP-ENV:Body , and SOAP-ENV:Header elements (in the http://schemas.xmlsoap.org/soap/envelope/ namespace).

SOAP-ENV:Envelope must be the root of SOAP requests. SOAP-ENV:Envelope can contain a SOAP-ENV:Header and must contain a SOAP-ENV:Body . In Listing 9.1, the optional SOAP-ENV:Header is not present.

The SOAP-ENV:Header carries extensions to SOAP. Headers were introduced to manage transactions, payments, or authentication. So far, though, they are not used frequently.

The SOAP-ENV:Body contains the RPC data. The name of the RPC is encoded as an XML element: psol:getStock for the getStock RPC in Listing 9.1.

The parameters of the call are also encoded as elements. SOAP offers a default encoding for parameters, which Listing 9.1 uses. However, your application can use any encoding, provided it is declared in the SOAP-ENV:encodingStyle attribute. For example, SOAP for Java from IBM can encode parameters following the SOAP rules or XMI.

The SOAP encoding lists the parameters as XML elements whose names match the parameter names . In Listing 9.1, the two parameters are manufacturer and sku . Their values are Playfield and 101 .

Note

SOAP provides a mechanism to signal the type of the parameters. The specification states that values are always encoded as strings. For example, the integer fifty-three is represented by the string 53 .

SOAP defines an optional attribute ( xsi:type ) that you would use as follows :

 <manufacturer xsi:type="xsd:string">101</manufacturer> 

However, xsi:type is not required if the parameter supports only one type. In practice, you mainly use xsi:type for object parameters because, through inheritance and polymorphism, recognizing the actual parameter's type is not always easy.


SOAP Response

When the server recognizes a SOAP request, it parses the payload and extracts the RPC name and its parameters. It executes the call and prepares a response, again as an XML document sent over HTTP.

Listing 9.2 is the response for the query in Listing 9.1. As you can see, it's a regular HTTP response with an XML payload.

Listing 9.2 The SOAP Response
 HTTP/1.1 200 OK Content-Type: text/xml Content-Length: 555 <?xml version='1.0'?> <SOAP-ENV:Envelope    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">    <SOAP-ENV:Body>       <psol:getStockResponse          xmlns:psol='http://www.psol.com/xmlns/stockq'          SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>          <stockq>             <manufacturer>Playfield</manufacturer>             <sku>101</sku>             <available>true</available>             <level>10</level>          </stockq>       </psol:getStockResponse>    </SOAP-ENV:Body> </SOAP-ENV:Envelope> 

You are now familiar with SOAP-ENV:Envelope and SOAP-ENV:Body . The body of the response is again an XML element, but the specification does not specify its name. It could be anything, even though the specification suggests you'd use the RPC name suffixed with Response ( psol:getStockResponse ).

The first element within the response is the return value (again, the specification does not enforce its name). In this example, the return value is a structure with four fields.

SOAP's rule to encode structures is that the names of the elements must match the names of the fields. So, in Listing 9.2, the four fields are manufacturer , sku , available , and level .

Although Listing 9.2 does not illustrate it, a response can include out parameters. They simply appear after the response element.

SOAP Fault

As you have seen, in most cases, the content of SOAP-ENV:Body is defined by the application. However, SOAP defines one special element to report errors: SOAP-ENV:Fault . SOAP-ENV:Fault is a structure with four fields, the first two of which are mandatory:

  • faultcode ”Indicates the type of error (acceptable values are SOAP-ENV:VersionMismatch , SOAP-ENV:MustUnderstand , SOAP-ENV:Client , and SOAP-ENV:Server ).

  • faultstring ”A human-readable description of the error.

  • faultfactor ”Used primarily when relaying SOAP messages (for example, when using a proxy). It is a URI that indicates on which relay the request failed.

  • detail ”Intended for application-specific errors.

Listing 9.3 is a response with an error. Note that SOAP mandates the use of the HTTP 500 return code.

Listing 9.3 A SOAP Fault
 HTTP/1.1 500 Internal Server Error Content-Type: text/xml Content-Length: 333 <?xml version='1.0'?> <SOAP-ENV:Envelope    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">    <SOAP-ENV:Body>       <SOAP-ENV:Fault>          <faultcode>SOAP-ENV:VersionMismatch</faultcode>          <faultstring>Unknown SOAP version</faultstring>       </SOAP-ENV:Fault>    </SOAP-ENV:Body> </SOAP-ENV:Envelope> 
   


Applied XML Solutions
Applied XML Solutions
ISBN: 0672320541
EAN: 2147483647
Year: 1999
Pages: 142

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net