Sunday, January 30, 2011

Which Style of WSDL Does Your Web Service Use?

A WSDL document describes a Web service. A WSDL binding describes how the service is bound to a messaging protocol, particularly the SOAP messaging protocol. A WSDL SOAP binding can be either a Remote Procedure Call (RPC) style binding or a document style binding. A SOAP binding can also have an encoded use or a literal use. This gives you four style/use patterns:

1. RPC/encoded
2. RPC/literal
3. Document/encoded
4. Document/literal

Adding to this collection, there is another pattern which is known as the document/literal wrapped pattern and used by Microsoft's Web Services. Totally you can have five binding styles to choose from when creating a WSDL file. To learn about the strengths and weaknesses of each pattern, read "Which style of WSDL should I use?".

Which Style of WSDL Does Performance Notes Web Service Use?

Using operation "createXtmPerformanceNotesView1" as example, we can see our sample Performance Notes Web Service uses Document/literal style (see style and use attributes). Or rather, I should say, it uses document/literal wrapped pattern.

<wsdl:binding name="XtmPerfNotesAMServiceSoapHttp" type="tns:XtmPerfNotesAMService">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
<wsdl:operation name="createXtmPerformanceNotesView1">
<soap:operation soapAction="/model/common/createXtmPerformanceNotesView1" />
<wsdl:input>

<soap:body use="literal" />
</wsdl:input>
<wsdl:output>
<soap:body use="literal" />
</wsdl:output>

<wsdl:fault name="ServiceException">
<soap:fault name="ServiceException" use="literal" encodingStyle="" />
</wsdl:fault>
</wsdl:operation>
</wsdl:binding>

For a document/literal wrapped style WSDL, your portType definition should end up with something like this:

<schema elementFormDefault="qualified" xmlns:ns0="/model/common/"
targetNamespace="/model/common/types/">
<element name="createXtmPerformanceNotesView1">
<complexType>
<sequence>
<element name="xtmPerformanceNotesView1" type="ns0:XtmPerformanceNotesViewSDO" />
</sequence>

</complexType>
</element>

<complexType name="XtmPerformanceNotesViewSDO">
<sequence>
<element minOccurs="0" name="AuthorId" type="long" />
<element minOccurs="0" name="NoteCreationDate" type="ns0:dateTime-Timestamp" />

<element minOccurs="0" name="NoteId" type="long" />
<element minOccurs="0" name="NoteText" type="string" />
<element minOccurs="0" name="TargetId" type="long" />
</sequence>
</complexType>
<element name="xtmPerformanceNotesViewSDO" type="XtmPerformanceNotesViewSDO" />

</schema>

<wsdl:message name="XtmPerfNotesAMService_createXtmPerformanceNotesView1">
<wsdl:part name="parameters" element="types:createXtmPerformanceNotesView1" />
</wsdl:message>


<wsdl:portType name="XtmPerfNotesAMService">
<wsdl:operation name="createXtmPerformanceNotesView1">

<wsdl:input message="tns:XtmPerfNotesAMService_createXtmPerformanceNotesView1" />
<wsdl:output message="tns:XtmPerfNotesAMService_createXtmPerformanceNotesView1Response" />
<wsdl:fault name="ServiceException" message="errors:ServiceException" />
</wsdl:operation>
</wsdl:portType>

If you invoke createXtmPerformanceNotesView1 method with appropriate message parts, a SOAP message which looks something below should be sent:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:createXtmPerformanceNotesView1
xmlns:ns1="/model/common/types/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ns1:xtmPerformanceNotesView1 xmlns:ns2="/model/common/">
<ns2:AuthorId>40009 </ns2:AuthorId>

<ns2:NoteCreationDate>2009-04-14T11:22:00.000</ns2:NoteCreationDate>
<ns2:NoteId> 10001 </ns2:NoteId>
<ns2:NoteText>Tim has delivered the gadget on time!</ns2:NoteText>
<ns2:TargetId>45353</ns2:TargetId>

</ns1:xtmPerformanceNotesView1>
</ns1:createXtmPerformanceNotesView1>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In summary, the characteristics of document/literal wrapped style include:

  • There is no type encoding info in the parameters (i.e., not like this: <ns2:AuthorId type="xsd:long">40009 </ns2:AuthorId> ).
  • You can validate this message easily with any XML validator because everything within the soap:body is defined in a schema.
  • Document/literal is WS-I compliant, and the wrapped pattern meets the WS-I restriction that the SOAP message's soap:body has only one child.
  • The WSDL is more complicated than other styles.
  • The operation name appears in the message, so the receiver has an easy time dispatching this message to the implementation of the operation. This is also why not setting soapAction as below is ok.
var soapAction = document.getElementById("soapAction");
soapAction.value = "/model/common/createXtmPerformanceNotesView1";
...
xmlHttpReq.setRequestHeader("SOAPAction", "\"" + soapAction + "\"");

No comments: