he Web services programming model is breaking down the barriers of cross-platform and cross-language communications. Because it works through simple XML-formatted text messages, code written in any language should be able to interact with code written in any other language, on any platform, anywhere. That sounds good in theory, but practice is often quite different. In this article I’ll show you how to put the theory into practice.

SOAP Will Have a Profound Effect on Software Engineering
The Simple Object Access Protocol (SOAP) is a protocol specification for invoking methods on servers, services, components, and objects. The SOAP specification mandates a small number of HTTP headers that facilitate firewall/proxy filtering, as well as an XML vocabulary used to represent method parameters, return values, and exceptions. SOAP does not define language bindings; it’s simply a wire protocol.

SOAP is simple and non-intrusive enough that any tool vendor that supports HTTP can easily support SOAP. In short, SOAP is a wire protocol similar in intent to the Internet Inter-ORB protocol (IIOP) for Common Object Request Broker Architecture (CORBA), Object Remote Procedure Call (ORPC) for Distributed Component Object Model (DCOM), or Java Remote Method Protocol (JRMP) for Java Remote Method Invocation (RMI).

At this point you may be asking why, with so many wire protocols in existence, do we need another one. The answer is that while IIOP, ORPC, and JRMP are binary protocols, SOAP is a text-based protocol that uses XML. Using XML for data encoding gives SOAP some unique capabilities. For example, debugging applications based on SOAP is much easier because text-based XML messages are much easier to read than binary-formatted messages. Also, because all the information in SOAP is in text form, SOAP is much more firewall-friendly than IIOP, ORPC, or JRMP. SOAP requests can use the ubiquitous HTTP port 80. In contrast, the binary protocols typically force administrators to open other ports, which increases the likelihood of security breaches.

In this article, I’ll show you how to achieve cross-language interoperability with Web services and SOAP. You’ll see how to build a cross-language application featuring two-way communication between a Java service using a VB client, and the same Java service using a Visual C++ client. This simple example walks you through the procedures step-by-step.

Create and Deploy a Java Web Service
First you need to create a simple Java class that exposes a sayHello() method, which takes one String input parameter, appends “Hello” to the start of the parameter, and then returns the result, which looks like “Hello xyz” where “xyz” is the input parameter. Here’s the sayHello() code:

public String sayHello(String name)    throws Exception {   String hello = “Hello ” + name;   return hello;}

Put the method in a class named HelloService and in a package named helloservice. Next, you need to make this class act as a Web service by deploying it to a Web server or application server. I used Apache and Tomcat for the example, but any Java-compatible application server should work just as well.

Apache SOAP uses XML documents called deployment descriptors to provide information to the SOAP runtime about the Web services available to clients. Deployment descriptors provide information such as the Universal Resource Name (URN) for the service (which is used to route the request when it comes in), the method, and (for Web services implemented by Java classes) the class details.

The deployment descriptor for the service looks like this:

helloservice.HelloService”           static=”false”/>             org.apache.soap.server.DOMFaultListener                         

In the preceding deployment descriptor, hello-service is the URN that you want to give to a service; sayHello is a space-separated list of methods that you want to expose; and helloservice.HelloService is the fully qualified class name (the packagename.classname) that implements the methods being exposed.

The <java> element accepts an optional attribute called static, which you can set to “true” when the methods you want to expose are static. The <provider> element also accepts a scope attribute, which indicates the instantiation lifetime of the implementing class. The value “Request” indicates that the Web service destroys the object when the request is complete, and the value “Session” indicates that the object will persist for the lifetime of the current HTTP session. Finally, the value “Application” indicates that the object persists until the servlet that is servicing the requests terminates.

Why <isd:mappings> Are Important
Because XML is a text-based format, you need to convert values to and from text form to the proper types. To control the serialization and deserialization of specific Java types to and from XML in a particular encoding style, you may need to provide serialization and deserialization classes that know how to perform the correct conversions for those types.

The Apache-SOAP server already includes serialization classes for most basic types in a SOAP encoding style, as well as a Bean encoding class that provides generic bean serialization by serializing public properties. Apache-SOAP always includes xsi:type elements for all the request parameters, and it expects xsi:type elements in the response. However, the Microsoft SOAP implementation does not recognize xsi:type elements. Because the example Web service is a Java class and the client is Visual Basic, the server uses Apache SOAP and the client uses Microsoft SOAP. Therefore, you must handle this xsi:type incompatibility.

The Apache SOAP implementation expects requests to contain xsi:type elements. When they’re not present, the server rejects the request, so the service request fails. In the descriptor file, the element removes the xsi:type restriction for Apache SOAP, because it maps the XML element “name” to the StringDeserializer class. The StringDeserializer class transforms the contents of the XML element into an instance of java.lang.String. Using this kind of explicit mapping, Apache SOAP doesn’t have to look for xsi:type elements in the request to provide the mapping information; instead, it assumes that all XML “name” elements are of type String and deserializes them appropriately.

With the deployment descriptor now completed, execute the following command to deploy the Java Web service:

java org.apache.soap.server.ServiceManagerClient // NOTE: The URL below should be a single line of codehttp://localhost:8080/soap/servlet/rpcrouter deploy HelloServiceDeployment.xml 

After running this command, you’ve completed the server part of this example.

Describe Your Web Service with WSDL
For clients to be able to call a Web service they need to know the available method names, the parameter names and types, and the expected output type for each method. Therefore, you need to generate some kind of interface that can sit between the server and client so each can understand the other’s request or response. The Web Services Description Language (WSDL) fulfills these interface requirements.

WSDL, officially, is an XML grammar that contains information about the interface and semantics of a call to a Web service. But you can think of a WSDL file as an XML document that describes a set of SOAP messages, and how those messages are exchanged. In other words, WSDL is to SOAP as Interface Definition Language (IDL) is to CORBA or COM. Because WSDL is also XML, it is humanly readable and editable.

After developing a Web service, you publish its description and a link to it in a UDDI (Universal Description, Discovery and Integration) repository so that potential users can find it. When someone thinks they want to use your service, they request your WSDL file to find out the details for using the service. They then use the information in your WSDL file to form a SOAP request message.

The WSDL file is the heart of the Web service transaction, because without it the clients can’t communicate with your Web service. To understand the value of WSDL, imagine you want to start calling a SOAP method provided by one of your business partners. You could ask him for some sample SOAP messages and write your application to produce and consume messages that look like the samples, but that can be error-prone. For example, you might see a customer ID of 8907 and assume it’s an integer when in fact it’s a string. The WSDL file specifies the contents of request and response messages unambiguously.

You can view the WSDL file for the example Web service here. See the sidebar “The WSDL Specification” for more information about the WSDL grammar.

Create VB and C++ Web Service Clients
After deploying the Java Web service, you can test SOAP’s cross-language capabilities by creating clients in other languages that call the sayHello() method exposed by the Java service. Each client passes a SOAP message containing a string parameter and receives a “Hello xyz” string in response (where “xyz” is the value of the string parameter passed by the client).

The first step is to create a VB client class capable of constructing the appropriate SOAP messages using the WSDL file as a model. I used the Cape Clear CapeStudio WSDL Assistant. The CapeStudio WSDL Assistant tool takes a WSDL file as input and creates a VB class (cls) file that acts as a proxy and lets you treat the Web service just as you would any other COM object. The generated class transparently creates and parses the SOAP message call and response. The Microsoft SOAP Toolkit generates WSDL files only for Microsoft COM components, and it doesn’t allow you to generate VB cls files by specifying a WSDL file-but no SOAP toolkit possesses this feature.

Figure 1: The VB 6 IDE. The VB 6 IDE with the References dialog open.

Next, create an ActiveX DLL containing the generated cls file. I used Visual Basic 6.0 to create the DLL file because putting it in a separate file makes the class reusable, as you’ll see later in this article.

In the VB IDE, click the File menu, select New Project, and choose the ActiveX DLL project type. Name the project HelloVB. Create a new class module named Hello_PortTypeClient and copy the generated cls file code into the new class. Now select References from the Project Menu. Figure 1 shows the References dialog.

Select the Microsoft SOAP Type library and Microsoft XML, v3.0 from the references.

After including the two required references, select “Make HelloVB.DLL” to create the DLL file.

Now you can create a very simple Standard EXE application that uses the DLL to communicate with the Web service. Close your DLL project and select File, New Project, and choose the Standard EXE project type. To use the HelloVb.DLL, select References from Project Menu and then select HelloVb from the reference list. The form itself contains only the code to create a Hello_PortTypeClient object, make the call to the sayHello() method of the Java Web service, and display the results.

‘ in the Declarations sectionDim x As HelloVb.Hello_PortTypeClientPrivate Sub Form_Load()   Set x = New Hello_PortTypeClient   MsgBox x.sayHello(“VB”)End Sub

Figure 2: The Visual Studio IDE. The Visual Studio IDE with the open MFC ClassWizard dialog. Start with this dialog to add the HelloVB ActiveX Dynamic Link Library.

Before running this program, make sure to start the server on which you deployed the Java service. When you run the VB application, it displays a message box containing “Hello VB”, the return value of the Java service.

As you know, DLLs are portable and reusable, so you can use the same VB DLL to call the Web service from a VC++ program. Briefly, here’s how to instantiate objects and call a VB ActiveX DLL from VC++ (I used Visual C++ version 6.0):

1. The VC++ project is a simple Single Document Interface (SDI) executable, MFC-based application. After you create the VC++ project with the wizard, you need to add the VB Dynamic Link Library to it.
2. Open the ClassWizard dialog (Ctrl+W) and then add the class by selecting the type library (see Figure 2 and Figure 3).

This procedure adds a class wrapper for the VB DLL class module. Now include “HelloVb.h” in your project header file (in the sample code, the header file is HelloFromVC2.h). Also declare a VB DLL class module object pointer, for example:

Hello_PortTypeClient * mu_pMainClass 

Figure 3: Select the VB DLL file (HelloVb.dll). When the next dialog box appears, you can select the classes in the HelloVB.dll that you want to add to the project.

Next initialize OLE (see lines 53-57 in HelloFromVC2.cpp) and create the VB DLL class module object (see lines 79-109 in HelloVC2.cpp). Finally, you can call the Web service. To initiate the call with the sample application, click the Tools menu and select the “Call HelloVb” item. The menu fires a sayHello() method which calls the VB DLL sayHello() method with a string parameter, which then creates the SOAP message and calls the sayHello() method of the Java Web service.

So, now you’ve seen how to leverage the power of SOAP in a language-independent manner. You could just as easily develop your Web service in VB or a .NET language, and call it from a Java client. SOAP is simpler and easier to implement than any existing alternative, and it makes better use of the pervasive Web infrastructure. The overall result is that you can write code to pull a system together in weeks rather than annual quarters.