Web Service - Best Practices

Summary

Web Services technology is well established as a communication technology for the Internet offering greatest interoperability. Their standardization process is going on at great speed, which will lead to even broader acceptance. Nonetheless judging from mailing lists and user groups, discussions there is still quite some confusion about the different Web Services Design approaches. What does “Document/Literal” mean compared “RPC-style”, how does SOAP “message-style” fit into this?

This article will clarify and explain in detail the different Web Service Design Methodologies as defined by the Web Services Standardization Groups, clarify the terms, highlight their differences. Here we will focus on the following Web Services Design Approaches, evaluate their strength and weaknesses and explore how far each style supports in designing an Interoperable Web Service.

1. RPC/Encoded Style
   
2. RPC/Literal Style
   
3. Document/Literal Style
   
4. Document /Literal Wrapped Style

Introduction

In their relatively short time of existence Web Services have gained an enormous acceptance and a broad usage on the market. One reason for this surely is, their very early open standardization which has been driven by all major players on the market. On the other side, all these players also have their preferences on how Web Services should look like and how they should communicate. This, and the fact, that different communication styles are required, has lead to standards that today support different ways of how web services messages can be formatted and how they can communicate.

The relevant standards for describing and using Web Services are the Web Services Description Language (WSDL), a standardized XML Schema-like language used for specifying Web Service and the Simple Object Access Protocol (SOAP), the actual communication protocol for Web Services.. Before Moving to the Real Design Approaches let's clarify some of the terms that is frequently used in the world of web services.

Communication Patterns

Let’s start with the communication patterns. With Web Services we can essentially distinguish three different ways of communication:

• Remote procedure call: Client sends a SOAP request to the service provider and waits for a SOAP response (synchronous communication).
  
• Messaging: Client sends a SOAP request and expects no SOAP response back (one-way communication).
  
• Asynchronous callback: A client calls service with one of the above methods. Later, the two parties switch roles for a callback call. This pattern can be build from either of the first two.

SOAP Formatting Rules

Now let’s turn to how the SOAP Message of a Web Services can be formatted (essentially the message’s <soap:body> Element) WSDL 1.1 distinguishes two different binding styles (referred to as soap:binding styles): RPC and Document.

• RPC Style
  

  The RPC style specifies that the <soap:body> contains an element with the name of the web method being invoked (wrapper element). This element in turn contains an entry for each parameter and the return value of this method.

  
  
• Document Style
  

  If the style is of type document, there is no wrapper element as with the RPC style. Instead, the message parts appear directly under the <soap:body> element. There are no SOAP formatting rules for what the <soap:body> contains; it contains what the sender and receiver agreed upon as an XML document.

The second formatting rule is the ‘Use’ attribute. This concerns how types are represented in XML. It indicates whether the message parts are encoded using some encoding rules, or whether the parts define the concrete schema of the message. The two offered choices are:

• Encoding
  

  If use is encoded, then each message part references an abstract type using the type attribute. The message is produced using an encoding specified by the encodingStyle attribute. The mostly used SOAP Encoding is a set of serialization rules defined in SOAP 1.1. The rules specify how objects, structures, arrays and object graphs should be serialized. In general, the applications using SOAP encoding is focused on remote procedure calls and will likely use RPC message style.

  
  
• Literal
  

  If use is Literal, then each part references a concrete schema definition using either the element or type attribute, i.e., data is serialized according to a given schema. In practice, this schema is usually expressed using W3C XML Schema.

Table 1 summarizes the options for different web services parameters. An important realization is that, three independent decisions are to be made by a web services developer. What is the “Communication Pattern” to be used? What is the SOAP formatting “Style” to be used ? and finally what is the SOAP message encoding Type to be used ?

WSDL Parameters	Available Options
Communication Patterns	Remote Procedure Call or One-way messaging
Style	Document or RPC
Use	Encoded or Literal

Table 1. Web Services Parameters.

Although in theory any combination of these options is possible, in practice there is a clear preference of one combination over the other, and also the standards and the Web Services Interoperability organization (WS-I) has a clear preference.

Thus in practice, only Document/Literal and RPC/Encoded have gained wide spread usage and are directly supported by most platforms as indicated in Table 2. The table also shows the results of the WS-I conformance tests for the different style/use combinations.

Style/Use combination	Supported Soap tool kit	WS-I Conformance
RPC/Encoded	Microsoft, Axis 1.1	Failed
RPC/Literal	Axis 1.1	Failed
Document/Literal	Microsoft , Axis1.1	Passed

Table 2. Web Services Format Support.

The Document/Encoded has not been tested, since it is not supported by the used platforms. In fact there is no real world usage of Document/Encoded combination.

A Simple Web Service Example

Now let’s look in more detail into the mostly used and supported style/use formats RPC/Encoded and Document/Literal. We will illustrate each of this style use combinations by means of a web method called “SendTemperature” which takes a user defined complex object as its parameter and returns void type as described in listing 1.

We choose an example with a complex data type to make the differences between the various styles more obvious.

public void SendTemperature (Temperature[] TempCollection){}

public class Temperature
{
   /// <remarks/>
   public int Id;

  /// <remarks/>
  public string Name;

  /// <remarks/>
  public System.Double Temperature;
}

Listing 1. SendTemperature Web Method implemented in C#.

We will show how the various Web Services formats are implemented in the WSDL file for this web method with their respective SOAP request formats and highlight their differences. The implementations were done using Microsoft VS.NET and the Axis SOAP toolkit.

Note that the namespaces, prefixes and the service part of the WSDL files have been ignored in this article for simplicity. The Listing 2 shows the common namespaces and prefixes that were used.

xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:s="http://www.w3.org/2001/XMLSchema"
xmlns:s0="http://interop.webservices.fhso.ch/{service name}"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"
xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
xmlns="http://schemas.xmlsoap.org/wsdl/"
targetNamespace="http://interop.webservices.fhso.ch/{service name}/ ”

Listing 2. Namespaces and used prefixes.

1. 
   

   RPC/Encoded Style

   
   

   RPC/Encoded is essentially a format following the classical “remote procedure call” style in which a client sends a synchronous request to a server to execute an operation. The SOAP request contains the name of method to be executed and the parameter it takes. The server running the Web Service converts this request to appropriate objects, executes the operation and sends the response back to the client as SOAP message. At the client side, this response is used to form appropriate objects and return the required information to the client. In RPC-style Web Services, the complete method is specified in the WSDL file and in the SOAP body, including the sent parameters and the return values. So we have a rather tight coupling with this style.

   
   

   Listing 3 shows the WSDL defined for the SendTemperature Method in the RPC/Encoded style.

   <types>
   <s:schema targetNamespace="http://interop.webservices.fhso.ch/rpcencoded">
   <s:complexType name="ArrayOfTemperature">
   <s:complexContent mixed="false">
   <s:restriction base="soapenc:Array">
   <s:attribute d7p1:arrayType="s0:Temperature[]" ref="soapenc:arrayType"
   xmlns:d7p1="http://schemas.xmlsoap.org/wsdl/"/>
   </s:restriction>
   </s:complexContent>
   </s:complexType>
   <s:complexType name="Temperature">
   <s:sequence>
   <s:element minOccurs="1" maxOccurs="1" name="Id" type="s:int"/>
   <s:element minOccurs="1" maxOccurs="1" name="Name" type="s:string"/>
   <s:element minOccurs="1" maxOccurs="1" name="value" type="s:double"/>
   </s:sequence>
   </s:complexType>
   </s:schema>
   </types>
   <message name="SendTemperatureSoapIn">
   <part name="Collection" type="s0:ArrayOfTemperature"/>
   </message>
   <message name="SendTemperatureSoapOut"/>
   <portType name="TemperatureRpcEncodedSoap">
   <operation name="SendTemperature">
   <input message="s0:SendTemperatureSoapIn"/>
   <output message="s0:SendTemperatureSoapOut"/>
   </operation>
   </portType>
   <binding name="TemperatureRpcEncodedSoap" type="s0:TemperatureRpcEncodedSoap">
   <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
   <operation name="SendTemperature">
   <soap:operation soapAction="http://interop.fhso.ch/soapformat/SendTemperature"/>
   <input>
   <soap:body use="encoded"
         encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
   </input>
   <output>
   <soap:body use="encoded"
         encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
   </output>
   </operation>
   </binding>

   
   

   Listing 3. RPC/Encoded WSDL for SendTemperature.

   
   

   Notice the binding style, which is set to ‘rpc’ and use, which is set to ‘encoded’. Under the <message> section there can be any number of <part> elements each containing a type attribute which is unique to ‘rpc’ style. Now let’s look what happens when we invoke the SendTemperature web method, sending an array with two entries. Listing 4 shows the resulting SOAP message.

   <soap:Envelopexmlns:
        soap="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
        xmlns:tns="http://interop.webservices.fhso.ch/rpcencoded"
        xmlns:types="http://interop.webservices.fhso.ch/rpcencoded/encodedTypes"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SendTemperature>
   <Collection href="#id1"/>
   </SendTemperature>
   <soapenc:Array id="id1" soapenc:arrayType="tns:Temperature[2]">
   <Item href="#id2"/>
   <Item href="#id3"/>
   </soapenc:Array>
   <tns:Temperature id="id2" xsi:type="tns:Temperature">
   <Id xsi:type="xsd:int">3</Id>
   <Name xsi:type="xsd:string">Station1</Name>
   <value xsi:type="xsd:double">34.3</value>
   </tns:Temperature>
   <tns:Temperature id="id3" xsi:type="tns:Temperature">
   <Id xsi:type="xsd:int">56</Id>
   <Name xsi:type="xsd:string">Station3</Name>
   <value xsi:type="xsd:double">23.6</value>
   </tns:Temperature>
   </soap:Body>
   </soap:Envelope>

   
   

   Listing 4. RPC/Encoded SOAP Message for SendTemperature.

   
   

   Each parameter is type encoded in the SOAP message. Notice also the ‘href’ tags in the SOAP message, which is an essential part of the RPC/Encoded style and which is used to refer the items in the array. Under any literal style, the ‘href’ tag is not available. Let’s analyze the WSDL and its SOAP message format.

   
   

   Strengths:

   
   

   
   

   • The definition of the WSDL file follows the intuitive and well-known remote-procedure-call style.
     
   • The operation name appears in the message, so that the receiver has an easy time dispatching the message to its implementation.
     
   • If you are using data graphs or polymorphism in your service, this is the only possible style that can be used for the types described in this article.
   
   

   Weaknesses:

   
   

   
   

   • The SOAP message includes the type encoding information such as xsi:type="xsd:int", xsi:type="xsd:string", xsi:type="xsd:double" which is an overhead.
     
   • In general it is harder to validate the SOAP message.
     
   • RPC style causes a rather tight coupling between service provider and client, any changes to the interface would break the contract between the service and the client.
     
   • Depending on the information that may need to handle simultaneously, memory constraints may make RPC messaging unfeasible as marshalling takes place in-memory.
     
   • Is not supported by the WSI conformance standard.
   
   

   Now let’s look at the implementation of the same Web Method in RPC/Literal format and see if it can eliminate some of the drawbacks of RPC/Encoded style.

   
   
2. 
   

   RPC/Literal Style

   
   

   The WSDL looks almost similar to the previous one except the change in the ‘use’ setting from ‘encoded’ to ‘literal’ in the soap:body as shown in Listing 5. As described above, this means that the data type definition is not provided by the referenced XML Schema instead of RPC encoding.
   

   <types>
   <s:schema elementFormDefault="qualified"
   targetNamespace="http://interop.webservices.fhso.ch/rpcliteral">
   <!-- there are no global element declarations. There's nothing in the
   schema that completely describes the content of soap:Body -->
   <s:complexType name="ArrayOfTemperature">
   <s:sequence>
   <s:element minOccurs="0" maxOccurs="unbounded" name="Temperature"
        nillable="true"
        type="s0:Temperature"/>
   </s:sequence>
   </s:complexType>
   <s:complexType name="Temperature">
   <s:sequence>
   <s:element minOccurs="0" maxOccurs="1" name="Id" type="s:int"/>
   <s:element minOccurs="0" maxOccurs="1" name="Name" type="s:string"/>
   <s:element minOccurs="0" maxOccurs="1" name="value" type="s:double"/>
   </s:sequence>
   </s:complexType>
   </s:schema>
   </types>
   <message name="SendTemperatureSoapIn">
   <part name="Collection" type="s0:ArrayOfTemperature"/>
   </message>
   <message name="SendTemperatureSoapOut"/>
   <portType name="TemperatureRpcLiteralSoap">
   <operation name="SendTemperature">
   <input message="s0:SendTemperatureSoapIn"/>
   <output message="s0:SendTemperatureSoapOut"/>
   </operation>
   </portType>
   <binding name="TemperatureRpcLiteralSoap"
               type="s0:TemperatureRpcLiteralSoap">
   <soap:binding style="rpc"
               transport="http://schemas.xmlsoap.org/soap/http"/>
   <operation name="SendTemperature">
   <soap:operation
               soapAction="http://interop.fhso.ch/soapformat/SendTemperature"/>
   <input>
   <soap:body use="literal"
               namespace="http://interop.fhso.ch/soapformat/SendTemperature"/>
   </input>
   <output>
   <soap:body use="literal" />
   </output>
   </operation>
   </binding>

   
   

   Listing 5. RPC/Literal WSDL for SendTemperature.

   
   

   However, there is still a major drawback with this style. The XML Schema alone does not tell you what the message body Infoset contains, you must also know the RPC rules. Therefore, the schema describing an RPC/Literal message is not sufficient to validate that message.

   
   

   Now let’s look at the SOAP message format for RPC/Literal shown in Listing 6. Note that the type encoding is completely removed.

   <soapenv:Envelope
   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
   < ! – SendTemperature is the name of the procedure being invoked.
   Collection is a parameter of that procedure.
   Note that Collection is not namespace qualified. The two Temperature
   elements are contents of the Collection parameter. This Collection can
   be thought of as an array of Temperature items. Note that the Temperature
   is namespace qualified but is in a different namespace than SendTemperature.
   These namespace rules are unique to RPC-style messages -- >
   <SendTemperature xmlns="http://interop.fhso.ch/soapformat/SendTemperature">
   <Collection xmlns="">
   <ns1:Temperature xmlns:ns1="http://interop.webservices.fhso.ch/rpcliteral">
   <ns1:Id>2</ns1:Id>
   <ns1:Name> Station1</ns1:Name>
   <ns1:value>34.2</ns1:value>
   </ns1:Temperature>
   <ns2:Temperature xmlns:ns2="http://interop.webservices.fhso.ch/rpcliteral">
   <ns2:Id>56</ns2:Id>
   <ns2:Name> Station 3</ns2:Name>
   <ns2:value>23.6</ns2:value>
   </ns2:Temperature>
   </Collection>
   </SendTemperature>
   </soapenv:Body>
   </soapenv:Envelope>

   
   

   Listing 6. RPC/Literal SOAP message for SendTemperature.

   
   

   Strengths:

   
   

   
   

   • The WSDL is still about as straightforward as with the RPC/Encoded style.
     
   • The operation name still appears in the SOAP message.
     
   • The type encoding is eliminated from the message and hence increase the throughput performance
   
   

   Weaknesses:

   
   

   
   

   • Still the contract between the service and the clients are tightly coupled.
     
   • It is still hard to validate the transferred data by the SOAP message.
     
   • Is not supported by the WSI conformance standard either
   
   

   Now let’s move to the Document/Literal type and see if this style can reduce the existing drawbacks.

   
   
3. 
   

   Document/Literal

   
   

   The major difference of the Document style to the above RPC style is that, the client sends the service parameters in a normal XML document to the server instead of a discrete set of parameter values of methods. This makes the Document style to a more loosely coupled style of interaction than the RPC format.

   
   

   The Web Service provider processes the normal XML document, executes the operation and sends the response to the client again as a normal XML document. There is no direct mapping between the server objects (parameters, method calls etc) and the values in XML documents. The application is responsible for mapping the XML data values. The SOAP message of a Document style carries one or more XML documents within its SOAP body. The protocol places no constraint on how the document needs to be structured; this is completely handled at the application level. Additionally, Document style Web Services follows the asynchronous processing paradigm.

   
   

   The WSDL for this style has more changes compared to RPC style as shown in Listing 7.

   <types>
   <s:schema elementFormDefault="qualified"
        targetNamespace="http://interop.webservices.fhso.ch/docLit">
   < ! - - this element declaration describes the entire contents
   of the soap:Body in the request message.
   This is a feature of document/Literal that RPC/Literal lacks - ->
   <s:element name="Collection">
   <s:complexType>
   <s:sequence>
   <s:element minOccurs="0" maxOccurs="unbounded" name="Temperature"
      nillable="true"
      type="s0:Temperature"/>
   </s:sequence>
   </s:complexType>
   </s:element>
   <s:complexType name="Temperature">
   <s:sequence>
   <s:element minOccurs="0" maxOccurs="1" name="Id" type="s:int"/>
   <s:element minOccurs="0" maxOccurs="1" name="Name" type="s:string"/>
   <s:element minOccurs="0" maxOccurs="1" name="value" type="s:double"/>
   </s:sequence>
   </s:complexType>
   < ! – Similarly this element declaration describes
   the contents of the soap body in the response
   message. In this case the response is empty -- >
   <s:element name="SendTemperatureResponse">
   <s:complexType/>
   </s:element>
   </s:schema>
   </types>
   <message name="SendTemperatureSoapIn">
   <part name="parameters" element="s0:Collection"/>
   </message>
   <message name="SendTemperatureSoapOut">
   <part name="parameters" element="s0:SendTemperatureResponse"/>
   </message>
   <portType name="TemperatureDocLitSoap">
   <operation name="SendTemperature">
   <input message="s0:SendTemperatureSoapIn"/>
   <output message="s0:SendTemperatureSoapOut"/>
   </operation>
   </portType>
   <binding name="TemperatureDocLitSoap" type="s0:TemperatureDocLitSoap">
   <soap:binding style="document"
     transport="http://schemas.xmlsoap.org/soap/http"/>
   <operation name="SendTemperature">
   <soap:operation soapAction=
      "http://interop.webservices.fhso.ch/documentliteral/SendTemperature"
   style="document"/>
   <input>
   <soap:body use="literal" />
   </input>
   <output>
   <soap:body use="literal" />
   </output>
   </operation>
   </binding>

   
   

   Listing 7. Document/Literal WSDL for SendTemperature.

   
   

   Note that, the binding style is set to ‘document’ and use to ‘literal’. Under the ‘message’ section only a single <part> element is possible, which contains an element attribute.

   
   

   This part points to a schema element declaration that describes the entire contents of the soap body. Note that, the collection is now defined as an element rather that a type. The primary feature of Document/Literal, and its key benefit compared to RPC/Literal is the use of schema element declaration to completely describe the contents of the <soap:body>. This means that you can tell what the message body Infoset contains just by looking at the schema with no need for additional rules. Consequently you could take the schema describing a Document/Literal message and use it to validate the message - you can’t do this with RPC/Literal.

   
   

   Now let’s have a look at the corresponding SOAP message format shown in Listing 8. Note that there is no type encoding data specified and that the operation name is missing.

   <soap:Envelope
   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
   < -- note that the Operation name is missing in the message -- >
   <Collection xmlns="http://interop.webservices.fhso.ch/docLit">
   <Temperature>
   <Id>2</Id>
   <Name>Station 1</Name>
   <value>34.2</value>
   </Temperature>
   <Temperature>
   <Id>56</Id>
   <Name>Station 3</Name>
   <value>23.5</value>
   </Temperature>
   </Collection>
   </soap:Body>
   </soap:Envelope>

   
   

   Listing 8. Document/Literal SOAP message for SendTemperature.

   
   

   The summarized strengths and weaknesses of this approach are as follows.

   
   

   Strengths:

   
   

   
   

   • No type encoding information in the SOAP Message.
     
   • You can always validate the message with any XML validator. Everything within the soap body is defined in the schema.
     
   • With document style the rules are less rigid and many enhancements and changes can be made to the XML schema without breaking the interface.
     
   • Document style services can maintain application state if multiple procedures are called in a particular sequence.
     
   • Document style is better suited for asynchronous processing.
     
   • Many document-messaging services are able to choose between DOM and SAX handlings of the document and as a result are able to minimize in-memory processing
   
   

   Weaknesses:

   
   

   
   

   • The WSDL is getting bit more complicated.
     
   • The operation name in the in the SOAP message is lost. Without the name, the dispatching can be difficult or impossible.
   
   

   We have seen that the Document/Literal style eliminates most of the drawbacks of the RPC/Literal style – on the other side it introduces a new one: it looses the operation name in the SOAP message.

   
   

   Since the fourth format option, Document/Encoding, has no practical usage, it will not be described. Instead we will look at an extension to the Document/Literal style, the Document/Literal wrapped format.

   
   
4. 
   

   Document/Literal wrapped

   
   

   This style has been suggested by Microsoft to fix the drawback from the standard Document/Literal style. Although there is no specification in WSDL 1.1 standard for this style, many current SOAP toolkits support it.

   
   

   Let’s first look at the WSDL in Listing 9 and its corresponding SOAP message in Listing 10.

   <types>
   <s:schema elementFormDefault="qualified"
   targetNamespace="http://interop.webservices.fhso.ch/docLitWrapped">
   <s:element name="SendTemperature">
   <s:complexType>
   <s:sequence>
   <s:element minOccurs="0" maxOccurs="1" name="Collection"
   type="s0:ArrayOfTemperature"/>
   </s:sequence>
   </s:complexType>
   </s:element>
   <s:complexType name="ArrayOfTemperature">
   <s:sequence>
   <s:element minOccurs="0" maxOccurs="unbounded" name="Temperature"
     nillable="true"
     type="s0:Temperature"/>
   </s:sequence>
   </s:complexType>
   <s:complexType name="Temperature">
   <s:sequence>
   <s:element minOccurs="0" maxOccurs="1" name="Id" type="s:int"/>
   <s:element minOccurs="0" maxOccurs="1" name="Name" type="s:string"/>
   <s:element minOccurs="0" maxOccurs="1" name="value" type="s:double"/>
   </s:sequence>
   </s:complexType>
   <s:element name="SendTemperatureResponse">
   <s:complexType/>
   </s:element>
   </s:schema>
   </types>
   <message name="SendTemperatureSoapIn">
   <part name="parameters" element="s0:SendTemperature"/>
   </message>
   <message name="SendTemperatureSoapOut">
   <part name="parameters" element="s0:SendTemperatureResponse"/>
   </message>
   <portType name="TemperatureDocLitWrappedSoap">
   <operation name="SendTemperature">
   <input message="s0:SendTemperatureSoapIn"/>
   <output message="s0:SendTemperatureSoapOut"/>
   </operation>
   </portType>
   <binding name="TemperatureDocLitWrappedSoap"
      type="s0:TemperatureDocLitWrappedSoap">
   <soap:binding style="document"
      transport="http://schemas.xmlsoap.org/soap/http"/>
   <operation name="SendTemperature">
   <soap:operation soapAction=
     "http://interop.webservices.fhso.ch/docLitWrapped/SendTemperature"
     style="document"/>
   <input>
   <soap:body use="literal"/>
   </input>
   <output>
   <soap:body use="literal"/>
   </output>
   </operation>
   </binding>

   
   

   Listing 9. Document/Literal wrapped WSDL for SendTemperature.

   
   

   First, notice in Listing 9 that the operation name is now reintroduced into the WSDL file in the first ‘element’ tag. Also notice that this SOAP message in Listing 10 looks similar to the RPC/Literal SOAP Message. But there is a subtle difference. In the RPC Literal SOAP message the <SendTemperature> child of <soap:body> was the name of the operation. In the Document/literal wrapped soap message, the <SendTemperature> is the name of the element to which the single input message’s part refers. This pattern is a sly way of putting the operation name back into the SOAP message.

   
   

   These are the characteristics of the document/Literal wrapped pattern:

   
   

   
   

   • The input message has a single part
     
   • The part is an element
     
   • The element has the same name as the operation.
     
   • The element’s complex type has no attributes.

   <soap:Envelope
   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
   <! – the following is an xml document described in the service’s
   contract using XML schema. In this case SendTemperature may or may not
   be the name of the remote procedure being invoked by this message.
   Also, Collection may or may not be the name of the parameter. We know the
   structure of the xml document but We don’t know how the service
   is going to process it -- >
   <SendTemperature xmlns="http://interop.webservices.fhso.ch/docLitWrapped">
   <Collection>
   <Temperature>
   <Id>2</Id>
   <Name>Station 1</Name>
   <value>34.2</value>
   </Temperature>
   <Temperature>
   <Id>56</Id>
   <Name>Station 3</Name>
   <value>23.6</value>
   </Temperature>
   </Collection>
   </SendTemperature>
   </soap:Body>
   </soap:Envelope>

   
   

   Listing 10. Document/Literal wrapped message for SendTemperature.

   
   

   The summarized strengths and weaknesses of this approach are:

   
   

   Strengths:

   
   

   
   

   • Contains all the strengths of Document/Literal style.
     
   • The method name appears in the SOAP message.
   
   

   Weaknesses:

   
   

   
   

   • The WSDL is even more complicated, but this is still a very minor weakness.
     
   • If you have overloaded operations in your web service, you cannot use this style.

So far, we saw that Document/Literal and Document/Literal wrapped style brought us a lot of flexibility and strengths compared to any other design style. Yet there are some issues remaining to be addressed.

Limitations of Document/Literal and Document/Literal wrapped styles

Suppose, we have overloaded operations as shown in the following Listing 11.

public void SendTemperature (Temperature[] TempCollection){}
public void SendTemperature (Temperature[] TempCollection, int week){}

Listing 11. Overloaded SendTemperature Method.

In this situation, it is not possible to use Document/Literal wrapped style even though the WSDL specification allows to have overloaded operations. The reason for this is that, when you add a wrapped pattern to a WSDL document you require an element to have the same name as the operation. (see Listing 9). The issue comes when you want to have two elements with the same name in the XML Schema. So the alternative we have for overloaded operations is to go for Document/Literal non-wrapped or one of the RPC styles.

Let us see how we can realize this in Document/Literal. Here is the modification of the schema section of the WSDL for the above two web methods.

<types>
<s:schema elementFormDefault="qualified"
   targetNamespace="http://interop.webservices.fhso.ch/docLit">
<s:element name="Collection">
<s:complexType>
<s:sequence>
<s:element minOccurs="0" maxOccurs="unbounded" name="Temperature"
   nillable="true" type="s0:Temperature"/>
<s:element minOccurs="0" maxOccurs="1" name="week" type="s:int"/>
</s:sequence>
</s:complexType>
</s:element>
<s:complexType name="Temperature">
<s:sequence>
<s:element minOccurs="0" maxOccurs="1" name="Id" type="s:int"/>
<s:element minOccurs="0" maxOccurs="1" name="Name" type="s:string"/>
<s:element minOccurs="0" maxOccurs="1" name="value" type="s:double"/>
</s:sequence>
</s:complexType>
<s:element name="SendTemperatureResponse">
<s:complexType/>
</s:element>
</s:schema>
</types>

Listing 12. Changed Schema Section of the Document/Literal WSDL for SendTemperature.

We just added another element to the collection. And everything else remains similar as in the Listing 7. It is interesting to look at the client proxy generated by the VS.NET wsdl.exe utility.

Public void SendTemperature([System.Xml.Serialization.XmlElementAttribute("Protocol",
                IsNullable=true)] Temperature[] Temperature, int week,
                [System.Xml.Serialization.XmlIgnoreAttribute()] bool weekSpecified) {
this.Invoke("SendTemperature", new object[] {
   Temperature,
   week,
   weekSpecified});
}

Listing 13. C# proxy code generated for the overloaded SendTemperature.

Notice that an additional Boolean variable called “weekSpecified” is automatically created and now the client can invoke this operator overloaded web method in two ways. If a client invokes this method with the week specified set to “false” we call the first overloaded method of Listing 11 - and the SOAP request is still identical to the one of Listing 10.

SendTemperature(Temperatue_Object,7,false);

On the other hand if a client call is made with the weekSpecified set to “true”, then it refers to the overloaded method of Listing 11 - and now the SOAP request looks like the following with the “week” parameter being passed as an XML tag.

SendTemperature(Temperature_Object,7,true);

<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<Collection xmlns="http://interop.webservices.fhso.ch/docLit">
<Temperatue>
<Id>2</Id>
<Name>Station 1</Name>
<value>34.2</value>
</Temperature>
<Temperature>
<Id>56</Id>
<Name>Station 3</Name>
<value>23.5</value>
</Temperature>
<week>7</week>
</Collection>
</soap:Body>
</soap:Envelope>

Listing 14. SOAP Message for the second overload format.

Now we have seen how the problem with Document/Literal wrapped is nicely solved by the standard Document/Literal.

Conclusion

Document-centric and RPC Web Services fill quite different niches. Document-style web services are more suitable for most enterprise-to-enterprise interaction over the Internet. Developing a Document-style web service may require a little more effort than RPC-style. We saw that Document/Literal Style and Document/Literal wrapped style brought us a lot of flexibility and strengths in Interoperability compared to any other design style. Anytime you are not interfacing to a preexisting RPC, the benefits of the document-style usually outweigh the fact to interface to the service. RPC/Encoded Approach is highly discouraged in Designing a web service if your main requirement is interoperability.

The WS-I Basic profile 1.0 discourages the use of RPC/Encoded approach and motivates Document/Literal and RPC/Literal as the only allowed style/use combinations. Many believe that RPC/Literal would go away with the future versions of WSI- profile.

References

• [WSI] WS-I Final Specification " BasicProfile Version 1.0a", 8 August 2003.
  
• [WSDL] WSDL Specification.
  
• [SOAP] SOAP Specification.
  
• [IBMWS] IBM Developer works Web Services article suit.
  
• [XMETH] Publicly available web services in both Doc/RPC styles at Xmethods.
  
• [MSDN] Microsoft’s MSDN Web Services article library.

About the Authors

Nalaka Withanage

Nalaka Withanage is an Electronics & Telecommunications Engineer and a Microsoft Certified Solutions Developer for .NET. He has being involved in Designing and Implementing Web Services based Distributed Systems as business solutions over the past 3+ years with J2EE, XML, ASP.NET, C#, VB.NET and .NET Compact Framework technologies.

Martin Kropp

Martin Kropp is a professor for Computer Science at the University of Applied Sciences Solothurn / Northwest Switzerland in Olten. He teaches software engineering with emphasis on object-oriented technology. He has defined and conducted several research projects for solving real world problems through Distributed systems technology including .NET and web services.