Part 5 - Integrating Java and Microsoft .NET

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 srcmsjsclient.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 srcBank.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.

Review

In this part of the Web services tutorial we learned how to write interoperable Web services. All examples were focused on the integration of MS .NET and Java. We demonstrated that Web services technology gives us the opportunity to pick the best technology for each particular piece of our system. Specifically, we can use the MS .NET framework on the client side to enable easy integration with common Office technologies, while still using the powerful and portable Java model for scalable server-side applications.

As we've seen today, a typical Web service application can easily support heterogeneous operations. One thing we haven't addressed yet, though, is heterogeneous Web service security. Next time we'll show how you to manage heterogeneous security using single sign-on. See you then.