The SOAP Section 5 Encoding Rules

Ivan Marsic • Rutgers University 274 xmlns:xsi=http:www.w3.org2001XMLSchema-instance xmlns:soap-enc=http:www.w3.org200305soap-encoding xmlns:ns0=http:www.auctions.orgns soap-env:encodingStyle=http:www.w3.org200305soap-encoding soap-env:Body ns0:item ns0:name xsi:type=xsd:string old watch ns0:name ns0:startPrice xsi:type=xsd:float 34.99 ns0:startPrice ns0:reserved xsi:type=xsd:boolean false ns0:reserved ns0:seller ns0:name xsi:type=xsd:string John Doe ns0:name ns0:address xsi:type=xsd:string 13 Takeoff Lane, Talkeetna, AK 99676 ns0:address ns0:bids xsi:type=soap-enc:array soap-enc:arraySize= ns0:entry ns0:amount xsi:type=xsd:float 35.01 ns0:amount ns0:bidder . . . ns0:bidder ns0:entry ns0:entry ns0:amount xsi:type=xsd:float 34.50 ns0:amount ns0:bidder . . . ns0:bidder ns0:entry . . . ns0:bids ns0:seller ns0:item soap-env:Body soap-env:Envelope ItemInfo name : String startPrice : float reserved : boolean SellerInfo name : String address : String 1 1 bids seller Bid amount : float BidsList 1 bidder BuyerInfo name : String address : String entry item ItemInfo name : String startPrice : float reserved : boolean ItemInfo name : String startPrice : float reserved : boolean SellerInfo name : String address : String SellerInfo name : String address : String 1 1 bids seller Bid amount : float Bid amount : float BidsList BidsList 1 bidder BuyerInfo name : String address : String BuyerInfo name : String address : String entry item Sender Receiver Web service SOAP message item Sender Receiver Web service SOAP message item Figure 8-5: Example class diagram, extracted from Figure 2-21 above. Chapter 8 • Web Services 275 Array attributes. Needed to give the type and dimensions of an array’s contents, and the offset for partially-transmitted arrays. Used as the type of the arraySize attribute. Restricts asterisk to first list item only. Instances must contain at least an asterisk or a nonNegativeInteger. May contain other nonNegativeIntegers as subsequent list items. Valid instances include: , 1, 2, 2 2, 2 0.

8.2.3 SOAP Communication

Styles Generally, SOAP applications can communicate in two styles: document style and RPC style Remote Procedure Call style. In document-style communication, the two applications agree upon the structure of documents exchanged between them. SOAP messages are used to transport these documents from one application to the other. The structure of both request and response messages is the same, as illustrated in Figure 8-6, and there are absolutely no restrictions as to the information that can be stored in their bodies. In short, any XML document can be included in the SOAP message. The document style is often referred to also as message-oriented style. In RPC-style communication, one SOAP message encapsulates the request while another message encapsulates the response, just as in document-style communication. However, the difference is in the way these messages are constructed. As shown in Figure 8-7, the body of the request message contains the actual operation call. This includes the name of the operation being invoked and its input parameters. Thus, the two communicating applications have to agree upon the RPC operation signature as opposed to the document structure in the case of document-style communication. The task of translating the operation signature in SOAP is typically hidden by the SOAP middleware. Selecting the communication style is independent from selecting whether or not the message should be encoded Section 8.2.2 above. The term literal is commonly used to refer to non- encoded messages. Therefore, four different combinations are possible: • documentliteral: A document-style message which is not encoded. • documentencoded: A document-style message which is encoded. • rpcliteral: An RPC-style message which is not encoded. • rpcencoded: An RPC-style message which is encoded. Envelope Body Envelope Body Header Header header blocks arbitrary XML document Envelope Body Envelope Body Header Header header blocks arbitrary XML document SOAP Message same for Request or Response Figure 8-6: Structure of a document-style SOAP message. Ivan Marsic • Rutgers University 276 The documentencoded combination is rarely encountered in practice, but the other three are commonly in use. Document-style messages are particularly useful to support cases in which RPCs result in interfaces that are too fine grained and, therefore, brittle. The RPC-style SOAP Communication In the language of the SOAP encoding, the actual RPC invocation is modeled as a struct type Section 8.2.2 above. The name of the struct that is, the name of the first element inside the SOAP body is identical to the name of the methodoperation. Every in or in-out parameter of the RPC is modeled as an accessor with a name identical to the name of the RPC parameter and the type identical to the type of the RPC parameter mapped to XML according to the rules of the active encoding style. The accessors appear in the same order as do the parameters in the operation signature. All parameters are passed by value. SOAP has no notion of passing values by reference, which is unlike most of the programming languages. For Web services, the notion of in-out and out parameters does not involve passing objects by reference and letting the target application modify their state. Instead, copies of the data are exchanged. It is the up to the service client code to create the perception that the actual state of the object that has been passed in to the client method has been modified. Listing 8-3: An example of a SOAP 1.2 RPC-style requestresponse via HTTP: ?xml version=1.0? Envelope Envelope Body Body Header Header header blocks operationName operationName inputParameter_1 inputParameter_1 value 1 inputParameter_2 inputParameter_2 value 2 inputParameter_n inputParameter_n value n Envelope Envelope Body Body Header Header header blocks operationName operationName inputParameter_1 inputParameter_1 value 1 inputParameter_1 inputParameter_1 value 1 inputParameter_2 inputParameter_2 value 2 inputParameter_2 inputParameter_2 value 2 inputParameter_n inputParameter_n value n inputParameter_n inputParameter_n value n Remote Procedure Call Envelope Body Header Header header blocks operationNameReturn return return return value Envelope Body operationNameReturn outputParameter_2 outputParameter_2 value 2 outputParameter_n outputParameter_n value n outputParameter_1 outputParameter_1 value 1 Envelope Body Header Header header blocks operationNameReturn return return return value return return return value Envelope Body operationNameReturn outputParameter_2 outputParameter_2 value 2 outputParameter_2 outputParameter_2 value 2 outputParameter_n outputParameter_n value n outputParameter_n outputParameter_n value n outputParameter_1 outputParameter_1 value 1 outputParameter_1 outputParameter_1 value 1 Remote Procedure Call Response Request message Response message Figure 8-7: Structure of a SOAP RPC-style request and its associated response message. Chapter 8 • Web Services 277 description name=StockQuote targetNamespace=http:example.comstockquote.wsdl xmlns:tns=http:example.comstockquote.wsdl xmlns:xsd1=http:example.comstockquote.xsd xmlns:soap=http:www.w3.org200305soap-envelope xmlns=http:www.w3.orgnswsdl types schema targetNamespace=http:example.comstockquote.xsd xmlns=http:www.w3.org2001XMLSchema element name=TradePriceRequest complexType all element name=tickerSymbol type=string all complexType element element name=TradePrice complexType all element name=price type=float all complexType element schema types message name=GetLastTradePriceInput part name=body element=xsd1:TradePriceRequest message message name=GetLastTradePriceOutput part name=body element=xsd1:TradePrice message portType name=StockQuotePortType operation name=GetLastTradePrice input message=tns:GetLastTradePriceInput output message=tns:GetLastTradePriceOutput operation portType binding name=StockQuoteSoapBinding type=tns:StockQuotePortType soap:binding style=document transport=http:schemas.xmlsoap.orgsoaphttp operation name=GetLastTradePrice soap:operation soapAction=http:example.comGetLastTradePrice input soap:body use=literal input output soap:body use=literal output operation binding