The concept of Web services is finally starting to take hold. But as you experiment with implementation, it's important not to forget that seamless cross-platform interoperability, regardless of development platform or programming language, is the driving force behind this technology. If you don't get interoperability issues nailed down, the various SOAP and Web services implementations will experience breakdowns in communication. And Web services will become just another failed experiment.
Last spring, as many of you may know, IBM and Microsoft both released the first versions of their SOAP implementations. (IBM later donated its code to Apache to kick off what is now the Apache SOAP Project.) But while all of the marketing literature for SOAP promised cross-platform interoperability, the tools didn't provide it. There were too many various bugs and nuances in the way SOAP had been implemented, and they made communication between the two tools nearly impossible. But things are beginning to change. Thanks to a concerted effort on the part of the members of the Apache SOAP Project and Microsoft, interoperability has become a center-stage issue. Many of the initial problems have disappeared, and the few remaining incompatibilities are dying a quick and painless death.
Please note that in order to experiment with the two samples presented here you will need to download the latest release version of Apache SOAP (version 2.1) and the most current version of the Microsoft SOAP Toolkit (Beta 2 or higher). See Resources.
Interoperability -- the problem of the xsi:type attribute
If you've read through the other articles on developerWorks that discuss the Web services architecture, you're no doubt familiar with the following diagram and what it represents. (If you haven't read these articles, I strongly recommend that you visit the library and take a look around.)
Figure 1: The fundamental components of the Web services architecture
Figure 1 represents the three fundamental operations performed by the three fundamental components of the Web services architecture:
- Service providers deploy and publish services by registering them with the Service broker;
- Service requesters find services by searching the Service broker's registry of published services;
- Service requesters bind to the Service provider and consume the available services.
In the world of Web services, each of these three operations involves three complimentary yet distinct technologies:
- Publishing services uses the Universal Description, Discovery and Integration (UDDI) API;
- Locating services uses a combination of UDDI and the Web Services Description Language (WSDL);
- Binding to services leverages WSDL and the Simple Object Access Protocol (SOAP).
At the most basic level, the Binding operation stands out as the most important of the three. It involves the actual consumption of services, where the vast majority of interoperability problems occur. Simply put, full support of the SOAP specification by both the Service provider and the Service requester solves these problems and enables seamless interoperability.
Unfortunately, this simple solution sounds easier to implement than it actually is. The flexibility built into SOAP via its many optional components, and its inherent complex simplicity, can frustrate us when we're trying to implement it. Take the conflict of the xsi:type attribute that arose between the Microsoft and Apache SOAP toolkits, an annoying little problem that caused, for a while, a halt in interoperability between the tools completely.
Remember that according to SOAP specification, the various elements contained in an envelope may optionally use the xsi:type attribute to identify the type of data that the element contains. If the provider and requester have some other means of communicating this information, then it needn't be included in the envelope. The xsi:type attribute should only be used if these data types can not be communicated by any other means.
To solve this problem, Microsoft built a dependency on an external service description document, that described the data types and could be accessed by both the requester and provider. Apache required that the xsi:type attribute be included at all times.
Both approaches were "legal SOAP" (although the approach taken by Apache's implementation was admittedly a bit legalistic and inflexible), but they were incompatible with each other. Apache SOAP did not and still doesn't, I might add, understand the Service Description Language used by Microsoft, that has gone through three iterations. First it was the "Service Description Language" or SDL, then as the "Service Contract Language" or SCL, and now as the Web Services Description Language or WSDL.
Microsoft also did not include any mechanism to easily add the xsi:type attribute to the SOAP envelopes generated by the tools. Luckily, things have changed. Microsoft now has a new and very flexible SOAP implementation which includes better support and lower-level control over the composition of the SOAP Envelope. And Apache has removed the restriction that requires the xsi:type attribute to be present. The result has been two tools that can communicate freely with one another.
An extended stock quote service, version one
Our example here will create a SOAP-based interface to the free NASDAQ InfoQuotes Service, available at http://quotes.nasdaq.com. This simple service provides extended stock quotes in HTML or XML format via an HTTP-GET request. All the Java and XML source files for this project are included in the Resources section. The screen shot in Figure 2 shows the XML-data returned by the Quote Service.
Figure 2: A Screenshot of the XML data from NasdaqQuotes
For version one of the NasdaqQuotes Web service, we will use a simple
Java class that exposes a single getQuotes method; this returns
the XML output of the HTTP-GET request as a string, as illustrated in the
code snippet in Listing 1 in the sidefile.
To deploy this Java class as a Web service, compile it and make sure it's in your Java Web server's class path (assuming you already have Apache SOAP 2.1 installed and configured). The following steps explain how to deploy the service and invoke it from Microsoft SOAP.
Step 1. Create an Apache deployment descriptor. The Apache SOAP Service Manager uses the deployment descriptor (a simple XML document) to collect information about deployed services. Take a look at the deployment descriptor for the NasdaqQuotes Version 1.0 Service in Listing 2.
<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment"
id="urn:NasdaqQuotes">
<isd:provider type="java"
scope="Application"
methods="getQuote">
<isd:java class="NasdaqQuotes" static="false"/>
</isd:provider>
<isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener>
<isd:mappings>
<isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:x="" qname="x:symbol"
xml2JavaClassName="org.apache.soap.encoding.soapenc.StringDeserializer"/>
</isd:mappings>
</isd:service>
|
For a detailed structural explanation of deployment descriptor
XML, go to the Apache SOAP documentation. But take note of the <isd:mappings>
section in our example, which removes the xsi:type restriction
from Apache SOAP. Here we've declared the XML element symbol to
map to the StringDeserializer class. This class transforms the
contents of the XML element into an instance of java.lang.String.
By using this kind of explicit mapping, Apache SOAP doesn't have to look
for xsi:type in order to provide the mapping information. Rather,
it can assume that all instances of the XML symbol element are Strings
and thus, deserialize them as such.
Step 2. Once you've created the Deployment Descriptor, you need to use it to deploy the NasdaqQuotes service into the services registry. Do so by executing this command line instruction.
Here http://acme.com/soap/servlet/rpcrouter corresponds
to your installation of the SOAP RPC Router Servlet.The NasdaqQuotes Service
should now be deployed and ready to use. You can test the service by invoking
the Java-based client I have provided in the zip package that accompanies
this article. Look in the readme.txt for instructions.
Step 3. The Microsoft tools require the use of a WSDL Document that describes the interface and location of the service. Since Apache SOAP does not include any support for WSDL, you have two options: you can use the WSDL-Toolkit from IBM's alphaWorks to generate WSDL for a specified Java Class, or you can write the WSDL file ourselves. I recommend you write the WSDL out by hand (see Listing 3 in the sidefile) -- writing things out by hand also gives you a better feel for WSDL structure and function. If you need a good XML editor, I highly recommend the commercial XML-Spy product, but any editor will do.
After the NasdaqQuotes.wsdl file has been edited,
it's time to use Microsoft tools. In the Zip that accompanies this article,
you will find two files in the samp1e directory called nq.vbs
and vq.bat. The file nq.vbs (see Listing
4) contains the code for invoking the NasdaqQuotes Service using the
Microsoft SOAP Toolkit. The script contains forty-three lines of code,
but the actual SOAP invocation occurs within the first six lines (with
four of those lines consisting of basic variable initialization code).
As you can see, Microsoft has done a great job making it easy to use their
tools.
Set SC = CreateObject("MSSOAP.SoapClient")
SC.mssoapinit "D:\Services\NasdaqQuotesClient.wsdl", "", "", ""
Res = SC.getQuote(WScript.Arguments(0))
|
You can invoke the NasdaqQuotes Service by executing the nq.bat
file, passing in the symbol you would like to query as a command line parameter
(see Figure 3).
Figure 3: Running the NasdaqQuotes from the command line
Homework: NasdaqQuotes version two
The NasdaqQuotes Service Version 1.0 demonstrates very simply that Microsoft and Apache are now capable of easily communicating with one another. But the fact that information returned by the Quote service is returned in the form of a string means that more work could be done to improve the service. For example, we may want the body of the SOAP envelope to return the results of the Query in XML form rather than returning a string. The NasdaqQuotes2 Service sample included in the Zip download takes you one step in the right direction. Your homework is to dissect that example and see what's going on. As usual, if you have any problems, let me know and I'll see if I can't help you out.
-
The source Java and XML code for the project in this article is available
in this zip file.
-
Download the latest version of the Apache SOAP.
-
Download the latest version of the Microsoft SOAP toolkit.
-
Check out cetus-links' index of SOAP resources.
- SoapWare.org and
SOAPClient.com are resources devoted exclusively to SOAP information.
James Snell is both an author and a developer and is one of the newest members of the IBM Web Services development team. He comes to IBM with an extensive background in custom enterprise application development and business-to-business integration, and a passion for the cutting edge of Web technology. You can reach him at jasnell@us.ibm.com.
Comments (Undergoing maintenance)
Table of contents
Next steps from IBM
Rational Tester for SOA Quality is an automated web services testing and SOA testing tool that supports Web services SOAP, HTTP(S), JMS, WS-Security, UDDI, and RESTful standards.
- Try: The no-charge Rational Service Tester for SOA Quality helps quality assurance professionals validate web service based SOA application..
- Article: See the whats new with Rational Service Tester for SOA Quality, and its Generic Service Client, which provides a single client to interact with any SOA service type.
- Tutorial: Get hands-on experience with this Transport for SOAP feature tutorial using Rational Tester for SOA Quality.
- Buy: Rational Service Tester for SOA Quality
My developerWorks community
Tags
Use the slider bar to see more or fewer tags.
Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).
My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
