services|web
Developing Interoperable Web Services - Integrating Java and Microsoft .NET
Interoperability is one of the main promises of Web services. Web services are designed to be independent of the underlying operating system and programming language. In this article we will introduce basic web services interoperability issues. We will focus on the two most popular platforms - Java and Microsoft .NET.
Introduction
Web services interoperability can be divided into two base categories: SOAP interoperability and WSDL interoperability.
In our previous articles we learned that SOAP is a very high-level protocol that mandates the structure of XML documents exchanged over some transport protocol. That's quite a vague definition. The vagueness of this definition makes SOAP extremely extensible and versatile, but it also makes interoperability a bit challenging. At a basic level, we start our quest to achieve interoperability at the transport protocol level. Both parties involved in a message exchange must agree to use the same transport protocol, such as HTTP, SMTP, or JMS. But transport protocol compatibility doesn't necessarily ensure interoperability. There are other issues that affect interoperability. One example is data type encoding. An encoding style defines how programmatic data types are encoded in XML. The SOAP specification does not mandate any particular encoding style, and developers are free to use any encoding style they want. In theory there are virtually unlimited choices of encoding styles that are mutually incompatible. Fortunately there is a standard convention. Section 5 of the SOAP specification defines an encoding style, and it has became the de facto standard for SOAP encoding. This encoding provides the basis for the automated SOAP interoperability tests that are periodically carried out by the major SOAP solutions vendors. You can see these test results online at http://soap.systinet.net/interop/soap/index.html
More and more we're finding that WSDL lies at the heart of Web services interoperability. WSDL is the description language for Web services. Usually a WSDL document is automatically generated by Web services framework tools (e.g., WASP WSDLCompiler) from the code written in a particular programming language. Developers can use the WSDL document to generate client-side stubs or proxies, which provide convenient access to Web services. Thus the key to enabling seamless Web services interoperability is the ability of one Web services framework to consume the WSDL documents generated by other frameworks. The WSDL interoperability effort is just taking off. You can see further details at http://soap.systinet.net/interop/wsdl/index.html.
Although there are still some interoperability issues to be resolved, the vendors are progressing very quickly, and we can expect delivery on the promise of Web services interoperability very soon.
How to not get trapped
The following subchapters give you some basic tips on how to write interoperable Web services using today's Web services frameworks. These tips may significantly ease your life as well as the lives of other developers who will use your Web services. Hopefully some of those tips will be outdated soon.
Keep your types simple - avoid advanced XML Schema constructs
The XML Schema standard is very complex and difficult to implement. Moreover, XML Schema processing is quite time consuming, so many frameworks sacrifice full XML Schema support for performance. Some advanced XML Schema constructs (e.g., choice) are quite hard to express in a programming language, and few Web services frameworks support them. So the key success factor in Web services interoperability is to use basic datatypes, such as primitive datatypes, arrays, and structures. As a best practice, decompose the complex types in your interfaces into simple and clean interfaces with basic datatypes. Also avoid using specific techniques (e.g. INOUT parameter passing) that aren't widely supported.
Provide XML Schema definitions for all your types
One common problem in today's frameworks is their limitied ability to import multiple XML Schema and WSDL documents. It's always a good idea to provide complete XML Schema and WSDL definitions in one WSDL file rather than importing them from various locations. Specifically, the Microsoft .NET framework is sensitive to XML Schema import functions.
Example: When you find that you need to include multiple WSDL and XML Schema files in a .NET service, you'll find it easier to pass the XML Schema definitions together with the WSDL definition to the commandline MS .NET WSDL compiler rather than trying to import the schemas into the WSDL file:
wsdl.exe /language:CS /protocol:SOAP MyService.wsdl MySchema.xsd JavaCollections.xsd
Multiple WSDL bindings
Some frameworks (e.g., MS .NET) generate multiple WSDL bindings that allow you to access a Web service through multiple protocols (e.g., HTTP GET, HTTP POST, and SOAP). The client-side framework needs to know which binding to use, so we need to specify further parameters (usually the fully qualified name of the service and the name of the WSDL port) when generating the programming language bindings from the WSDL document.
Example: We will later run the com.systinet.demos.weather.WeatherClient Java client to access the MS .NET weather service that is available on the XMethods site. Notice that the client must use a slightly different lookup method to specify a fully qualified service name (as a javax.wsdl.QName) and WSDL port name:
lookup("http://www.vbws.com/services/weatherretriever.asmx?WSDL",
new javax.wsdl.QName("http://tempuri.org/",
"WeatherRetriever"), "WeatherRetrieverSoap", WeatherRetrieverSoap.class)
Default document style with literal encoding
Some Web services frameworks, including MS .NET, generate, by default, a document style Web service, using literal encoding. Although the Web service uses document/literal, the .NET framework makes the service appear to be RPC style to .NET clients. This isn't necessarily so for other Web service frameworks, and many users may find it difficult to access the Web service using an RPC style client. So if you're writing an RPC Web service, force your framework to generate the RPC style WSDL.
Example: Use the [SoapRpcService] directive in your MS .NET RPC Web service implementations:
<%@ WebService Language="C#" Class="MSNetStockService" %>
using System.Web.Services;
using System.Web.Services.Protocols;
using System.Web.Services.Description;
[SoapRpcService]
public class MSNetStockService {
[WebMethod]
public double getQuote(string symbol) {
if(symbol == "SUNW") {
return 10;
}
if(symbol == "BEAS") {
return 11;
}
if(symbol == "MSFT") {
return 50;
}
return 0;
}
}
Use unique SOAPActions for your methods
If you start your Web service development with a WSDL document definition, consider using unique SOAPAction attributes for all your methods in the WSDL binding. Some frameworks rely on SOAPAction when routing SOAP messages to the Web service implementation's methods.
Example: Consider the following WSDL binding fragment for the previously mentioned MS .NET Web service:
<binding name="MSNetStockServiceSoap" type="tns:MSNetStockServiceSoap">
<soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc" />
<operation name="getQuote">
<soap:operation soapAction="http://tempuri.org/getQuote" style="rpc" />
<input>
<soap:body use="encoded" namespace="http://tempuri.org/"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</input>
<output>
<soap:body use="encoded" namespace="http://tempuri.org/"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</output>
</operation>
</binding>
Code Examples
Now we'll show a few Web services interoperability examples. We will use a simple banking application that is capable of keeping track of customers, accounts, and account balances. We will also use the MS .NET weather service that is listed on the XMethods site as a real-life example of Internet Web service access, so you'll need to be connected to the Internet while running this demo.
NOTE: If you haven't already downloaded the software used to create the tutorial examples, please refer to the installation chapter in Part One. You'll also need to download the demo sources. We assume that you've unpacked this archive into the c:\wasp_demo directory. All Java sources mentioned in the tutorial examples can be found in the src subdirectory of the unpacked demo sources archive. They all reside in the com.systinet.demos package. Similarly all scripts used in the demo are located in the bin subdirectory. You don't need to download and use the software to understand these articles, but we strongly recommend it.
Accessing a Microsoft .NET service from Java
We'll start with the Java client/.NET service example. As we mentioned earlier, we will access the weather service listed on the XMethods site. Click on the link and try the service online using the MS .NET invocation framework. Next look at the WSDL document for this service. You'll notice that it defines three bindings (WeatherRetrieverSoap, WeatherRetrieverHttpGet, and WeatherRetrieverHttpPost).
Now let's create a Java client for this service. Run the run_weather_client.bat script that's located in the bin directory of the demo sources archive. Please note that we're using a lookup method that specifices the fully qualified service name and the WSDL port. This lookup method allows us to specify that we want to use the SOAP binding.
lookup("http://www.vbws.com/services/weatherretriever.asmx?WSDL",
new javax.wsdl.QName("http://tempuri.org/",
"WeatherRetriever"), "WeatherRetrieverSoap", WeatherRetrieverSoap.class)
Calling a Java service from a Microsoft .NET client
The opposite scenario is pretty straightforward. First start the Web service runtime with the startserver.bat command, and then compile and deploy our simple Bank Web service by invoking the deploy.bat command. Now we're ready to show three different MS SOAP clients accessing our service.
NOTE: You need to use MS IE 6.0 or higher to run this demo.
First we will run a
MS JavaScript SOAP Client. Invoke the run_web_client.bat script. Specify an SSN number (you can use 001-0001-01, 002-0002-02 or 003-0003-03), and click the Get Accounts button, which populates the accounts combobox. Choose an account in the combobox and retrieve the account balance by clicking the Get Balance button. Look at the JavaScript code in src\msjsclient.html for further details. The code is very self-explanatory.
NOTE: You'll need to download and install the MS SOAP Toolkit 2.0 in order to successfully complete the next example. You'll also need MS Excel on your machine.
Now let's see the same functionality accessed from
Microsoft Excel (using Visual Basic). Open the src\Bank.xls spreadsheet and use the same steps described in the previous example to navigate the application. You can find the SOAP client code in the Visual Basic Editor (Tools->Macro->Visual Basic Editor) in the Sheet1 module.
NOTE: You'll need to download and install the MS .NET Framework SDK to run the C# part of this example
The last example demonstrates how to access our Java Web service from a C# client. Run the run_csharp.bat script to generate a C# static proxy from the service WSDL and to compile and run the client application. This example is going one step further than our previous examples in that it passes a Transfer structure from C# to Java. The previous examples pass only simple data types. Notice the simple XML Schema definition of the Transfer type (it includes the Balance element):
<xsd:schema targetNamespace="http://idoox.com/wasp/tools/java2wsdl/output/com/systinet/demos/bank/">
<xsd:complexType name="Transfer">
<xsd:sequence>
<xsd:element name="type" type="xsd:string"/>
<xsd:element name="accountNumberBeneficiary" type="xsd:string"/>
<xsd:element name="comment" type="xsd:string"/>
<xsd:element name="balance" type="ns0:Balance"/>
<xsd:element name="amount" type="xsd:double"/>
<xsd:element name="timestamp" type="xsd:dateTime"/>
<xsd:element name="accountNumber" type="xsd:string"/>
<xsd:element name="transferID" type="xsd:long"/>
<xsd:element name="commentBeneficiary" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="Balance">
<xsd:sequence>
<xsd:element name="changed" type="xsd:dateTime"/>
<xsd:element name="transfer" type="ns0:Transfer"/>
<xsd:element name="comment" type="xsd:string"/>
<xsd:element name="balance" type="xsd:double"/>
<xsd:element name="accountNumber" type="xsd:string"/>
<xsd:element name="transferID" type="xsd:long"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
The .NET WSDL compiler will generate the appropriate structures in C#. See the stub in the src/ms/JavaService.cs for more details. Run the Java client by invoking the run_java_client.bat script, and you'll notice that it does the same thing.
NOTE: Both clients share the same Web service, and both clients make withdrawals from the same account. So if you run the demo multiple times, you can easily get out of funds. Then you'll get the TransferProcessingException that says something like 'Insufficient funds'. One nice thing you'll notice is that C# is able to transparently rethrow the exception with the same message on the client side. Restart the Web services runtime using the startserver.bat to renew your funds.
