Introduction

Web services technology offers the promise and hope of integrating disparate applications in a seamless fashion. But enterprise applications are built around different technologies and platforms, and integration across businesses is never a trivial task. The relatively recent emergence of Business Process Execution Language (BPEL) for Web services provides a higher-level description language to specify the behavior of Web services. It provides a standard and portable language for orchestrating Web services into business processes. As BPEL was embraced by major vendors, IDE tools designed to automate business process design, such as the IBM® WebSphere® Studio Application Developer Integration Edition (Application Developer), entered the marketplace. The tools eliminate a large amount of required coding in the Web services integration, and allow you to construct business processes by dragging and dropping the WSDL files into the tools. It is expected that the tools automatically generate the client stubs for the participating Web services. As a result, the success of the integration is now largely dependent upon the underlying sophisticated tooling support. This puts an even greater demand on developers to adopt best practices that ensure the inherent interoperability of participating Web services.

As I illustrate in this article and the following articles, several issues require attention:

• Using vendor tools to derive the Web services semantics in WSDL from implementation code is convenient, but this approach ignores the design of the message schemas which is central to Web services interoperability in heterogeneous environments (J2EE technology versus .NET, for example).
• The ease, flexibility, and familiarity of the popular RPC/encoded style makes it an attractive choice for developers; however, the difficulty in synchronizing the implementations of the abstract SOAP encoding data model among vendors presents a difficult challenge for Web services interoperability.
• Weakly-typed collection objects, arrays containing null elements, and certain native data types all pose special problems for interoperability. Specifically:
  • It is impossible for vendor tools to accurately interpret XML Schemas representing weakly-typed collection objects and map them to the correct native data types.
  • The XML representations of an array with null elements differ between .NET and WebSphere.
  • Because native data types and XSD data types do not share a one-to-one mapping, information or precision can be lost during the translation.
• Different naming conventions in .NET and Java technology can result in namespace conflicts, as can the use of relative URI references.

Back to top

Start from WSDL

Ultimately all Web services interoperability issues center on the WSDL file. WSDL is the interface definition language (IDL) of Web services and the contract between the client and the server. The services semantics, namely the message types, data types, and interaction styles in the WSDL file, are the key to building loosely-coupled systems. Even though WSDL does not mandate the use of a particular type system, the XML Schema data types (XSD) is widely embraced by the Web services community.

XSD offers a wide range of built-in primitive types and further allows service providers to define custom complex types. The XSD-type system is more sophisticated and powerful than the type system of any programming language, and more importantly it is language-neutral. That makes WSDL the logical starting point to define the Web services semantics.

Ideally, just like the IDLs for COM and CORBA, you should create and edit the WSDL first -- define the interfaces, messages, and data types before you build the Web services and clients in specific implementation languages based on the service semantics in the WSDL.

However, in practice, even seasoned programmers like to do the opposite: they start with their implementation-language-specific interfaces, such as Java interfaces, and rely on vendors' tools to derive the service semantics in WSDL from their implementation code; they then leave it to the Web services client to figure out from the WSDL how to make the calls to the Web service. In the end, they often don't even need to know about the WSDL before they can build and run a sophisticated Web service. They might only have run their client and server in a homogeneous environment; that is, either on a J2EE platform or on a .NET platform, but not on both.

Vendors' IDE tools today are pushing toward the direction that everything can be auto-generated and no code writing is required (or, at least it is claimed and hoped by many), including the WSDL. This trend is attractive because it is productive, and it is less error-prone (only if the tool is righteous and robust) than human coding. Interoperability is usually not an issue on a single platform where both the Web services and clients use the same toolkits.

The danger becomes evident when there is a demand for interoperability across heterogeneous environments. Now you are creating the key artifacts for Web services interaction from implementation languages and then using the platform-dependent tools to map them to the language-neutral ones in WSDL. When the tool on the client platform generates the service proxy from this tool-generated WSDL, another level of mapping occurs. This process deviates from the hard fact that WSDL is the IDL for Web services. The language-neutral WSDL should be the common ground for both client and server and using the tools in this way doubles the likelihood that information is lost during the mappings.

This doesn't mean that you should abandon the tools, and that all the vendors should stop producing and marketing those tools. Automation has become an important aspect of today's enterprise application development landscape. The tools are powerful; it's a matter of how you leverage their power. You can use these tools to generate a skeleton WSDL to serve as a starting point or as a template. Schemas, message parts, and data bindings must be carefully designed in accordance with the WS-I recommendations. Just as you probably would not let a database schema be generated by a tool for the sake of the database efficiency, you should not ignore the design of efficient Web services messages and data types by hand. Sometimes, even the name of an element must be carefully chosen to conform to the naming conventions among potential interoperating platforms. WSDL is the single most important artifact for Web services interoperability. Programmers must learn to program against raw XML messages, and at least learn to read XSD, WSDL, and SOAP messages.

Back to top

Still RPC/encoded?

WS-I Basic Profile 1.0 promotes the use of literal XML for interoperability. It prohibits the use of soap:encodingStyle attributes to soap:Envelope or descendents of the soap:Body elements. Therefore, RPC/literal and Document/literal are the only two formats supported by the WS-I standards. But not many Web services toolkits support RPC/literal, so it leaves the Document/literal as the only actual interoperability standard.

However, the RPC/encoded way of doing things existed long before XML Schema or WSDL came into existence; even then, some encoding rules still can not be expressed in XSD. Even though SOAP encoding is recognized as one of the major sources of the Web services interoperability problems and, combined with the fact that the ASP.NET WebMethod infrastructure defaults to Document/literal, most of the J2EE Web services tools defaulted to RPC/encoded, until recently.

The RPC/encoded style is popular mainly because of its simple programming model for developers who are accustomed to the remote procedure calling convention. The RPC binding style uses the names of the method and its parameters to generate structures that represent a method's call stack, so it makes the Web services look like a single logical component with encapsulated objects, all handled in the SOAP RPC stack. This is in contrast with the Document/literal style in which developers have to assume everything, including the serialization and de-serialization of the XML-based SOAP messages.

Moreover, the SOAP encoding rules define standards to conveniently map the programmatic types to XML. The encoding rules are very flexible and support the representation of data graphs and polymorphism. This is no doubt more capable than the Document/literal model, which relies on the natural tree structures to represent data objects.

To get an idea of what the RPC/encoded model can and can't do, let's start with an example. Consider a Serializable Person class that defines a friend of its own, as shown in Listing 1.

public class Person implements java.io.Serializable {
	private Person friend;
	private String name;
	
	public Person getFriend() {
		return this.friend;
	}
	public void setFriend(Person friend) {
		this.friend = friend;
	}
<!-- Other setter and getter methods -->
}

If you instantiate two Persons: A and B, and make Person A a friend of Person B and Person B a friend of Person A, you are creating a cyclical object graph:

public Person makeFriend(Person A, Person B) {
	A.setFriend(B);
	B.setFriend(A);
	return A;
}

If you were to expose the public method in Listing 2 as a Document/literal Web service, how would the cyclic graph be represented in XML?

It turns out there is no easy way to do this with the Document/literal approach. The reason: the Document/literal approach defines the message types as concrete types based on the XML Schema; the XML Schema represents natural tree structures with the XSD primitive types as leaf nodes. A cyclic object graph cannot be transformed into a tree structure. In this case, because of the circular references between the object instances A and B of the Person class, the serialization of object A and B falls into a recursive loop. With WebSphere Studio, for example, you see a stack overflow exception in the end. That doesn't mean that the Document/literal approach offers no way of doing this, but it would require considerable effort on the developers' side.

If you use the SOAP encoding as the message bindings, the circular reference can be easily represented by applying SOAP encoding rules on the cyclic graph by using the multireference accessors. Take a look at the serialized XML payload by the Web service running on a WebSphere platform in response to a SOAP request to make John and Jason friends of each other. Listing 3 shows how easy the cyclic graph is represented.

<soapenv:Body soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<makeFriendResponse xmlns="http://cyclic.test">
<makeFriendReturn href="#id0" xmlns=""/>
</makeFriendResponse>
<multiRef  id="id0" soapenc:root="0" 
soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="ns-
520570027:Person" xmlns:ns-520570027="http://cyclic.test" xmlns="">
<name xsi:type="xsd:string">John</name>
<friend href="#id1"/>
</multiRef>
<multiRef  id="id1" soapenc:root="0" 
soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="ns-
520570027:Person" xmlns:ns-520570027="http://cyclic.test" xmlns="">
<name xsi:type="xsd:string">Jason</name>
<friend href="#id0"/>
</multiRef>
</soapenv:Body >

Notice how SOAP uses the local unqualified attributes id0 and id1 of type ID to specify the unique identifiers for the encoded elements Person A (John) and Person B (Jason) and another local unqualified attribute href is used to specify references to those two ID values. The circular references between Object A and Object B are handily represented by the flexible SOAP encoding rules.

The power of the RPC/encoded model has enormous appeal to traditional object-oriented programmers who are accustomed to programming within a single organizational domain, such as J2EE technology or .NET. While it provides great ease for the Web services designers and implementers when the scope is limited to a single platform where both the SOAP message writers and readers have a synchronized stub to understand the encoded SOAP messages, it comes at a big price as Web services go global. Its powerful strength turns out to be its weakness in the face of the demand for interoperability across platforms. To illustrate the interoperability problem, examine the WSDL file that Application Developer generated from the previous Web service (see Listing 4 in this sidefile).

In the WSDL document, the operation makeFriend's output message makeFriendResponse has a message part makeFriendReturn of Person type. According to the schema, the Person complex type must have the direct child elements name of xsd:string type and friend of Person type, and should not have any other types and attributes. However, the serialized SOAP response message (Listing 3) certainly does not match this rule. The href attribute in the response message is not present in the definitions. Given this discrepancy, how do you tell the message receiver that the elements A and B are instances of the Person class?

In fact, if you code a .NET client to talk to this Web service, the .NET client fails to de-serialize the WebSphere response, as in Listing 3. What the .NET client expects is the following response message to describe that John and Jason are friends:

<soap:Body 
soap:encodingStyle=
"http://schemas.xmlsoap.org/soap/encoding/"><tns:makeFriendsResponse>
	<makeFriendsResult href="#id1" />
</tns:makeFriendsResponse>
<types:Person id="id1" xsi:type="types:Person">
	<name xsi:type="xsd:string">John</name>
	<friend href="#id2" />
</types:Person>
<types:Person id="id2" xsi:type="types:Person">
	<name xsi:type="xsd:string">Jason</name>
	<friend href="#id1" />
</types:Person></soap:Body>

As you see, the multireference accessor encoding is powerful, but it is difficult to express in XSD. As a result, the implementations can have some subtle differences between different platforms, as in Listing 3 and Listing 5. This example illustrates the gap between SOAP encoding and XML Schema validation. Unlike the Document/literal approach, which passes through the literal documents and relies on the XML Schema to validate and de-serialize the XML representation of objects, the RPC/encoded model uses the SOAP encoding rules to represent the abstract SOAP data model and relies on the vendors' SOAP library to provide the concrete implementation of the abstract SOAP data model. It is thus highly platform-dependent. There is no intermediary specification to fill the gap and, as a result, this approach is open to different implementations by vendors. Although SOAP is a standard, the SOAP implementations (such as the DOM-based Apache SOAP library and the SAX-based Apache AXIS library for Application Developer V4 and V5, MS SOAP toolkit for MS .NET Framework 1.1) have subtle differences because of the lack of XML Schema support.

Back to top

Test conformance with the WS-I Conformance Testing Tool

The WS-I Basic Profile provides guidelines for conformance to Web Services specifications in order to build interoperable Web services. The WS-I Working Groups developed the WS-I Conformance Testing Tool to help developers determine whether their Web services are conformant with the Profile guidelines. A Profile Conformance Report can also be created from the WS-I Testing Tool Analyzer to document a conformance claim in your WSDL documents. Currently the C# and Java versions of the testing tool are available for download. By running the testing tool, much of the obvious violations of the WS-I Basic Profile 1.0 are reported. A conformance check on the WSDL document in Listing 4 results in the violation claim shown in Listing 6.

Result: failed
Failure Message: The use attribute of a soapbind:body, soapbind:fault, 
soapbind:header and soapbind:headerfault does not have value 
of "literal".
Failure Detail Message:

SOAPBody ({http://schemas.xmlsoap.org/wsdl/soap/}body):
required=null
use=encoded
encodingStyles=[http://schemas.xmlsoap.org/soap/encoding/]
namespaceURI=http://cyclic.test
 
Element Location:
  lineNumber=87

The failure message is self explanatory: "use=encoded" in the soapbind:body, soapbind:fault, soapbind:header or soapbind:headerfault is not considered conformant to the WS-I Profile. You should use "use=literal" instead. Since Document/encoded has no meaning, that is equivalent to saying that you should not use RPC/encoded.

Although the WS-I Conformance Testing Tool does not capture everything that might cause the Web services interoperability issues in the field, it is nonetheless a powerful tool. In parallel with the Web services development, incrementally developing a comprehensive test suite to capture potential interoperability issues is a best practice. For more details about the tool, refer to the articles in the Resources section.

Back to top

Conclusion

The author stressed that the Web services semantics in WSDL must be carefully designed before the actual implementation, explained why RPC SOAP encoding is one of major roadblocks for Web services interoperability, and showed the importance of building comprehensive test suite to test for WS-I Profile conformance. Coming up in this series, the author will discuss interoperability issues resulting from inbound and outbound data types and namespace conventions.

Resources

• Check out the other tips in this series:
  • "Part 2: Managing collections, arrays, or even primitive data types" (developerWorks, January 2005)
  • "Part 3: Handling namespaces" (developerWorks, February 2005)
  
  
  
• Read pertinent specifications on WSDL, SOAP, and other standards:
  • W3C WSDL 1.1 specification
  • W3C SOAP 1.1 specification
  • WS-I Basic Profile 1.1
  
  
  
• Gain guidance on determining which WSDL binding style/use is appropriate in the article "Which style of WSDL should I use?," by Russell Butek (developerWorks, October 2003).
  
  
• Study an overview of the architecture and functions of WS-I Test Tools in the article "Understanding the WS-I Test Tools," by Peter Brittenham (developerWorks, November 2003).
  
  
• See the tutorial "Using the WS-I Test Tools with Java technology," by Peter Brittenham for step-by-step instructions in using the Java versions of the WS-I test tools (developerWorks, November 2003).
  
  
• Learn more about the Web Services Interoperability Organization and IBM's commitment to interoperability.
  
  
• Browse for books on these and other technical topics.
  
  
• Want more? The developerWorks SOA and Web services zone hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop Web services applications.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Start from WSDL
• Still RPC/encoded?
• Test conformance with the WS-I Conformance Testing Tool
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

Rational Application Developer features provide the comprehensive Integrated Development Environment (IDE) used to develop J2EE applications requiring Servlets and JavaServer Pages (JSPs).

---

• Try: Try the free Rational Application Developer, which helps developers quickly design, develop, test, analyze, and deploy high-quality Java, Javaserver pages, and J2EE applications.
• Article: Learn how you can deliver accurate, higher-quality J2EE apps with Rational Application Developer, open source JUnit and JUnitEE test frameworks.
• Tutorial: Build a Facebook application using PHP, the Spring framework, and J2EE.
• Buy: Rational Application Developer

My developerWorks community

Dig deeper into SOA and Web services on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers