Beginning XML 4th Edition

Chapter 15: SOAP and WSDL

Chapter 15 Objectives Why SOAP can provide more flexibility than previous RPC protocols How to format SOAP messages When to use GET versus POST in an HTTP request What SOAP intermediaries are How to describe a service using WSDL The difference between SOAP styles

Laying the Groundwork Running Examples in Windows 2003, XP, and 2000 The New RPC Protocol: SOAP SOAP is ″a lightweight protocol for exchange of information in a decentralized, distributed environment.”

Creating an RPC Server in ASP.NET Try It Out Creating an RPC Server in ASP.NET

Just RESTing REpresentational State Transfer (REST) <GetTotalResponse> <Discount>0.95</Discount> <TotalPrice>44.46</TotalPrice> </GetTotalResponse>

Basic SOAP Messages Rules Structure <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Header> <head-ns:someHeaderElem xmlns:head-ns="some URI" env:mustUnderstand="true{{vert}false" env:relay="true{{vert}false" env:role="some URI"/> </soap:Header> <soap:Body encodingStyle="http://www.w3.org/2003/05/soap-encoding"> <some-ns:someElem xmlns:some-ns="some URI"/> <!-- OR --> <soap:Fault> <soap:Code> <soap:Value>Specified values</soap:Value> <soap:Subcode> </soap:Subcode> </soap:Code> <soap:Reason> <soap:Text xml:lang="en-US">English text</soap:Text> <v:Text xml:lang="fr">Texte francais</soap:Text> </soap:Reason> <soap:Detail> <!-- Application specific information --> </soap:Detail> </soap:Fault> </soap:Body> </soap:Envelope> Rules Structure

<Envelope> Body <soap:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <soap:Body> <o:AddToCart xmlns:o="http://www.wiley.com/soap/ordersystem"> <o:CartId>THX1138</o:CartId> o:Item>ZIBKA</o:Item> <o:Quantity>3</o:Quantity> <o:TotalPrice>34.97</o:TotalPrice> </o:AddToCart> </soap:Body> </soap:Envelope>

Encoding Style <soap:Envelope xmlns:soap=‘http://www.w3.org/2003/05/soap-envelope’> <soap:Body soap:encodingStyle="http://www.w3.org/2003/05/soap-encoding"> <o:AddToCartResponse xmlns:o=‘http://www.wiley.com/soap/ordersystem’> <o:CartId>THX1138</o:CartId> <o:Status>OK</o:Status> <o:Quantity>3</o:Quantity> <o:ItemId>ZIBKA</o:ItemId> </o:AddToCartResponse> </soap:Body> </soap:Envelope>

Try It Out GETting a SOAP Message

More Complex SOAP Interactions <Header> The mustUnderstand Attribute The role Attribute The relay Attribute <Fault>

The mustUnderstand Attribute <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Header xmlns:some-ns="http://www.wiley.com/soap/headers/"> <some-ns:authentication mustUnderstand="true"> <UserID>User ID goes here...</UserID> <Password>Password goes here...</Password> </some-ns:authentication> <some-ns:log mustUnderstand="false"> <additional-info>Info goes here...</additional-info> </some-ns:log> <some-ns:log> </soap:Header> <soap:Body xmlns:body-ns="http://www.wiley.com/soap/rpc"> <body-ns:mainRPC> <additional-info/> </body-ns:mainRPC> </soap:Body> </soap:Envelope>

The role Attribute Intermediary processing http://www.w3.org/2003/05/soap-envelope/role/next applies to the next intermediary in line, wherever it is. http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver only applies to the very last stop. http://www.w3.org/2003/05/soap-envelope/role/none effectively ″turns off” the header block so that it is ignored at this stage of the process.

The relay Attribute False by default.

<Fault> <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:rpc="http://www.w3.org/2003/05/soap-rpc"> <soap:Body> <soap:Fault> <soap:Code> <soap:Value>soap:Sender</soap:Value> <soap:Subcode> <soap:Value>rpc:BadArguments</soap:Value> </soap:Subcode> </soap:Code> <soap:Reason> <soap:Text xml:lang="en-US">Processing error</soap:Text> <soap:Text xml:lang="fr">Erreur de traitement </soap:Text> </soap:Reason> <soap:Detail> <o:orderFaultInfo xmlns:o="http://www.wiley.com/soap/ordersystem"> <o:errorCode>WA872</o:errorCode> <o:message>Cart doesn’t exist</o:message> </o:OrderFaultInfo> </soap:Detail> </soap:Fault> </soap:Body> </soap:Envelope>

Fault Codes Fault Code Description VersionMismatch A SOAP message was received that specified a version of the SOAP protocol that this server doesn’t understand. (This would happen, for example, if you sent a SOAP 1.2 message to a SOAP 1.1 server.) MustUnderstand The SOAP message contained a mandatory header that the SOAP server didn’t understand. Sender Indicates that the message was not properly formatted. That is, the client made a mistake when creating the SOAP message. This identifier also applies if the message itself is well formed, but doesn’t contain the correct information. For example, if authentication information were missing, this identifier would apply. Receiver Indicates that the server had problems processing the message, even though the contents of the message were formatted properly. For example, perhaps a database was down. DataEncodingUnknown Indicates that the data in the SOAP message is organized, or encoded, in a way the server doesn’t understand.

Try It Out POSTing a SOAP Message

Defining Web Services: WSDL http://www.w3.org/TR/wsdl How to call the service What to expect as a response from the service

<definitions> <?xml version="1.0"?> <definitions name="temperature" targetNamespace="http://www.example.com/temperature" xmlns:typens="http://www.example.com/temperature" xmlns:xsd="http://www.w3.org/2000/10/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns="http://schemas.xmlsoap.org/wsdl/"> </definitions>

<types> <types> <xsd:schema xmlns="" xmlns:xsd="http://www.w3.org/2000/10/XMLSchema" targetNamespace="http://www.example.com/temperature"> <xsd:complexType name="temperatureRequestType"> <xsd:sequence> <xsd:element name="where" type="xsd:string" /> <xsd:element name="when" type="xsd:date"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="temperatureResponseType"> <xsd:element name="temperature" type="xsd:integer"/> </xsd:schema> </types>

<messages> <message name="TemperatureRequestMsg"> <part name="getTemperature" type="typens:temperatureRequestType"/> </message> <message name="TemperatureResponseMsg"> <part name="temperatureResponse" type="typens:temperatureResponseType"/> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <env:Body> <getTemperature> <where>{{it{POSTAL} CODE}</where> <when>{{it{DATE}}</when> </getTemperature> </env:Body> </env:Envelope>

<portTypes> <portType name="TemperatureServicePortType"> <operation name="GetTemperature"> <input message="typens:TemperatureRequestMsg"/> <output message="typens:TemperatureResponseMsg"/> </operation> </portType>

<binding> <binding name="TemperatureBinding" type="typens:TemperatureServicePortType"> <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="GetTemperature"> <soap:operation /> <input> <soap:body use="encoded" encodingStyle="http://www.w3.org/2003/05/soap-encoding" namespace="http://www.example.com/temperature" /> </input> <output> </output> </operation> </binding>

<soap:binding> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <env:Body> <getTemperature> <where>34652</where> <when>2004-05-23</when> </getTemperature> </env:Body> </env:Envelope> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <env:Body> <where>34652</where> <when>2004-05-23</when> </env:Body> </env:Envelope>

<soap:operation> POST /soap.asp HTTP/1.1 Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */* Accept-Language: en-us Content-Type: application/x-www-form-urlencoded Accept-Encoding: gzip, deflate User-Agent: Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 5.0) Host: www.example.com Content-Length: 242 SOAPAction: "http://www.example.org/soap/TemperatureService.asp" <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <env:Body> <getTemperature> <where>34652</where> <when>2004-05-23</when> </getTemperature> </env:Body> </env:Envelope>

<soap:body> <soap:body use="encoded" encodingStyle="http://www.w3.org/2003/05/soap-encoding" namespace="http://www.example.com/temperature" /> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <env:Body> <t:getTemperature xmlns:t="http://www.example.com/temperature"> <t:where>34652</t:where> <t:when>2004-05-23</t:when> </t:getTemperature> </env:Body> </env:Envelope>

<service> <service name="TemperatureService"> <port name="TemperaturePort" binding="typens:TemperatureBinding"> <soap:address location="http://www.example.com/temp/getTemp.asp"/> </port> </service>

Specifying the Order Service via WSDL Try It Out Specifying the Order Service via WSDL

Other Bindings For example: More in the book. xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" <xsd:complexType name="GetTotalResponseType"> <xsd:sequence> <xsd:element name="Discount" type="xsd:string" /> <xsd:element name="TotalPrice" type="xsd:string"/> More in the book.