Styles of Web services

The whole promise of web services was that it would allow for seamless communication between disparate systems. This was supposed to be true even between systems that make use of different environments like .Net or J2EE or different flavors of J2EE (say Weblogic or Websphere). However, web service developers and users are finding out that this is not true always. This episode of our continuing saga on web services will try to throw light on why this problem has arisen and how to solve it.

It has been found that different platforms and even different services in the same platform construct SOAP messages differently. Consequently, different structures and types of SOAP messages are expected by either the web services themselves or clients on the other side of the architecture. The first part of this article will concentrate on the two major paradigms – style and use, and how they affect communication methods supported by web services and other things, including the basic design decisions behind using web services. The subsequent part of the article will talk about how to control style and use.

Nowadays the buzzword machine is on overdrive in the world of web services, generating words like “RPC-Encoded” and “Doc-Lit” that many developers no longer know the correct meanings of these words anymore and there is lot of uncertainty and doubt about these and similar words. This is understandable given the fact that the standards and meanings of terms in this field are being defined only now.

Let us first define some elements found in the WSDL standard:

  • <portType>: Defines an abstract Web service interface in terms of its operations, where each operation is defined in terms of the SOAP messages;
  • <binding>: Defines a concrete Web service implementation (except for the URL) in terms of the above port type, the use of SOAP, as well as the two XML formatting decisions – style for the entire service (or less commonly, per operation) and use per operation; and
  • <service>: Defines a port, or Web service destination, in terms of the above binding plus a URL. The <service> element is intended to locate a Web service.

Armed with this knowledge, let us now attack the meat of the issue.

In web services, the three major types of communication pattern are:

  • RPC (remote procedure call): Client communicates with the service using OAP requests and responses;
  • One-way messaging: Client just sends a SOAP requests and does not expect a response; and
  • Asynchronous callback: Client calls service; later, the two parties switch roles for a callback call. This pattern can be built from either of the first two.

The style, or binding style, decides how the elements in the SOAP body are constructed:

  • RPC: Elements are added to simulate a method call; and
  • Document: Just send the XML as if it is just a document. There is also a variation called wrapped that is also specified as document.

The second control, use or encoding, concerns how types are represented in XML. The two ways are:

  • Literal: Literally follow an XML Schema definition; and
  • SOAP encoded: Follow special encoding rules detailed in the SOAP 1.1 specification to produce XML that can contain references pointing within the message.

Now let us understand the different combinations of things possible. Refer table 1.

Communication Pattern

Style

Use

RPC

RPC

Encoded

One-Way Messaging

Document

Literal

Table 1: Combinations of Communication Pattern, Style and Use

Theoretically, one should be able to mix and match any of the patterns, styles and uses. Practically, the style/use combinations have limitations. Many Web service platforms do not directly support RPC/literal. And document/encoded doesn’t make sense. So, one is typically left with document/literal, RPC/Literal and RPC/encoded.

Let us now look at some examples of different types of SOAP messages and also some platform specific intricacies.

Table 2 depicts an RPC Encoded SOAP message.


<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="http://CreditManagement.demobank.xx.com" xmlns:types="http://CreditManagement.demobank.xx.com/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/">    <tns:isCreditBalAvailableForUser>
<in0 xsi:type="xsd:string">john</in0>
</tns:isCreditBalAvailableForUser>  </soap:Body></soap:Envelope>

Table 2: RPC encoded SOAP message

RPC Encoded SOAP

RPC Literal SOAP

<?xml version="1.0" encoding="UTF-8"?>
<soap:envelope>
    <soap:body>
        <myMethod>
            <x xsi:type="xsd:int">5</x>
            <y xsi:type="xsd:float">5.0</y>
        </myMethod>
    </soap:body>
</soap:envelope>

<?xml version="1.0" encoding="UTF-8"?>
<soap:envelope>
    <soap:body>
        <myMethod>
            <x>5</x>
            <y>5.0</y>
        </myMethod>
    </soap:body>
</soap:envelope>

Table 3: RPC encoded and RPC Literal SOAP

In table 3, note the differences between RPC Encoded and RPC Literal SOAP messages.

Dot Net DocLit SOAP Message

Axis DocLit SOAP Message

<?xml version="1.0" encoding="utf-16"?>
<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>
    < add xmlns="http://wsdm.ca.com/experimental/Calculator">
      <op1>1</op1>
      <op2>2</op2>
    </add>
  </soap:Body>
</soap:Envelope>

<?xml version="1.0" encoding="utf-16"?>
<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>
    <in0 xmlns="http://echo.ca.com">Hi</in0>
  </soap:Body>
</soap:Envelope>

Table 4: Doc Lit SOAP Messages

From Dot Net DocLit SOAP Message (table 4) we can get operationName and operationNameSpace. However, an Axis DocLit SOAP message does not contain the operation name and namespace (as it is not required to do so according to standards).

General DocLit SOAP Message

Wrapped DocLit SOAP Message

<soap:envelope>
          <soap:body>
        <xElement>5</xElement>
        <yElement>5.0</yElement>
    </soap:body>
</soap:envelope>

 

<soap:envelope>
    <soap:body>
        <myMethod>
            <x>5</x>
            <y>5.0</y>
        </myMethod>
    </soap:body>
</soap:envelope>

Table 5: Difference between wrapped and non-wrapped SOAP Messages

Notice that this SOAP message looks remarkably like the RPC/literal SOAP message. However, but there is a subtle difference. In the RPC/literal SOAP message, the <myMethod> child of <soap:body> was the name of the operation. In the document/literal wrapped SOAP message, the <myMethod> clause is the name of the wrapper element that the single input message's part refers to. It just so happens that one of the characteristics of the wrapped pattern is that the name of the input element is the same as the name of the operation. This pattern is a sly way of putting the operation name back into the SOAP message. This wrapped style originates from Microsoft. See table 5.

One cannot have overloaded operations if one uses the document/literal wrapped style.

public void myMethod(int x, float y);
public void myMethod(int x);                  

Table 6: Overloading Methods
WSDL allows overloaded operations. However, when one adds the wrapped pattern to WSDL, one requires an element to have the same name as the operation and one cannot have two elements with the same name in XML. So one cannot use this with DocLit wrapped style. This is not possible even with WSDL 2.0. Refer table 6.

In Websphere, when DocLit service is created by default it is a wrapped service. So, a DocLit service hosted in websphere sends the SOAP Message as in table 7.

<?xml version="1.0" encoding="utf-16"?>
<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>
    <echo xmlns="      http://echo">
      <param>Sundar</param>
    </echo>
  </soap:Body>
</soap:Envelope>

Table 7: Webshpere DocLit service (wrapped style)

I guess by this time more than necessary information regarding the different types of web services and SOAP messages have been discussed. The general takeaway from this discussion would be to be aware of all the different types of web services are possible and to keep this in mind while designing them. Some excellent articles on this topic are present in www.javaworld.com (one by Mitch Gitman) and in IBM DeveloperWorks.








}