"She had a pretty gift for quotation, which is a serviceable substitute for wit."
--W. Somerset Maugham
Later in this article, I'll explain the relevance of the quote above. I don't want to lead with the explanation, because it's not entirely flattering, and the great majority of the Web Services support in WDSc deserves nothing but praise. So let's start with the good stuff, shall we?
The Good News
Before I start on the Web Services support, I'd like to give you an update on something I mentioned a couple of columns back: the Virtual Innovation Center, or VIC. The VIC is an adjunct to IBM support and is a place where we can get answers to our questions about new IBM technologies. And while the VIC's focus started out as primarily WebSphere, it continues to add new areas. The latest is an entire section devoted to iSeries/i5--something you, my faithful reader, should be happy to see.
In that previous column, I noted that I was going to actually use the VIC to address some problems I had. And while my problems with Portal have not been resolved yet, I did task the VIC with another real mystery. For some reason, my WDSc installation had gotten confused, and whenever I went into Update Manager, the system thought it needed to update to 5.0.1. That wouldn't be such a bad thing, except I was already at 5.1.0.2, the latest and greatest version. This bothered me, and nobody at IBM could tell me what was happening.
I had talked informally to some IBM folks, and the response was "uninstall and reinstall." Those of you who have installed WDSc (especially the Advanced Edition, which I was trying to use) understand why that is not an option. To go through the entire download, uninstall, reinstall, and re-upgrade process can literally take days. So, I went to the VIC, and they started in on the problem.
My biggest relief from the time I started to talk to the folks at the VIC was that they understood that uninstall and reinstall is not an option. Even though there seems to be a (growing?) minority within IBM that considers the Microsoft three R's (reboot, restore, reinstall) a valid answer to software problems, the VIC team stood firm with me and explained to the IBM support group that this was not acceptable. It's kind of like another Maugham quote: "It's a funny thing about life; if you refuse to accept anything but the best, you very often get it."
Eventually, I answered enough questions and gave the IBM support group enough information that they were able to diagnose my problem and fix it without my having to reinstall WDSc--despite my primary VIC contact leaving to get married in the middle of the process! That didn't stop the VIC; they picked up the ball and really did the job of acting as my advocate. I didn't have to constantly explain that the recommended solution was no solution at all; the VIC did that dirty work and got me a real resolution.
I recommend that everyone give the VIC a try. It's a great organization, and I think their heart is in the right place. Time will tell whether their advocacy is a short-lived phenomenon or a trend toward a new level of service, but I think they'll have a better shot at it if the general population starts taking advantage of their services.
A Quick Introduction to Web Services
The topic of Web Services is broad and complex. Nearly every little bit about it is not only fairly new, but also subject to rancorous debate. Well, "new" is a relative term. XML-based Remote Procedure Call (XML-RPC) has been around since 1998, and Simple Object Access Protocol (SOAP) was released from Microsoft to the World Wide Web Consortium (W3C) in 2001. But the specifications continue to evolve, and the latest SOAP specification was just released in June 2003.
The arguments are real, however, and they range from the smallest detail to the very core of the technology. For example, debate continues about the basic protocol of messages in Web Services. There a schism between the SOAP and the XML-RPC camps. And even in the SOAP camp, there are at least four subprotocols that define how the message is defined. All of this leads to some interesting issues when implementing Web Services, and I'll address some of those in my next feature article. For now, I'll just review the basics of Web Services.
The 20,000 Foot View
At the highest level, Web Services are simply a way for one program to call another program over the Internet. While this seems like a relatively simple goal, there are enough issues to make the process difficult.
What type of parameters do you support? Can you return binary data, such as images? How do you handle complex structures, like orders, which may have multiple different data structures? The various specifications exist to help answer these questions, but unfortunately they're not entirely compatible. Attempts have been made, especially in recent years, to allow more interoperability, but this comes at the price of complexity. I invite you to compare the original XML-RCP specification to the current SOAP specification, which requires four parts: the primer, the messaging framework, adjuncts, and a testing document.
Regardless of the specification used, the concept of a Web Service comes down to this: One program sends an HTTP request to another program. The HTTP request (usually) contains a short XML document identifying the program to be called and the parameters to be passed to that program. The program processes the request and makes an HTTP response. This response is also an XML document containing the results of the request. The response document should contain either valid data or an error code of some kind.
That's the idea, but as the standards get more "standardized," it becomes more difficult for a human being to actually format the request. Take a look at a typical Web Service request using the SOAP protocol:
POST /myservice/servlet/rpcrouter HTTP/1.0
Host: localhost:7080
Content-Type: text/xml; charset=utf-8
Content-Length: 524
SOAPAction: ""
xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
This is just the request. In fact, this is just one variation of the request, the RPC/encoded variation. There are at least three others. With enough time, you could probably decipher this message. With even more time, you could probably write a program that would generate such a request. But the truth is that the conversation is so complex that just about any programmer will need some sort of help to get this programming feat accomplished. And that would be just one small part of the entire Web Service deployment.
WDSc to the Rescue
And that is where WDSc comes in. The WDSc wizards make it painless to create a Web Service. Not only that, but because there are so many different tasks involved in deploying a Web Service, WDSc came up with a new concept, the cheat sheet. Sort of a "meta-wizard," the cheat sheet is a walkthrough of the various steps required to create and deploy a Web Service. The cheat sheet for creating a Web Service from a JavaBean is depicted in Figure 1.
Figure 1: This is the cheat sheet for creating a Web Service from a JavaBean. (Click images to enlarge.)
I actually used this cheat sheet to create a Bean from a Web Service. My "JavaBean" is a simple class that takes a string (this is meant to be a customer number) and returns the associated email address. I put the term "JavaBean" in quotes because you don't really need to adhere to the conventions of a traditional JavaBean. There is a step in which a wizard looks through your class and lists all of the methods, and you can select the ones you want to make visible.
My Web Service
Currently, my class is really simple, as shown in the code below:
import java.util.*;
public class GetCustomerEmail {
private TreeMap map;
public String getEmail(String customer)
{
if (map == null) init();
return (String) map.get(customer);
}
private void init()
{
map = new TreeMap();
map.put("001987", "
map.put("123456", "
map.put("777777", "
}
}
I'm not trying to be facetious here; I simply wanted to quickly create something that was a little more business-like than adding two numbers. This class will use the input parameter as a key to retrieve an email address. In a real business application, this would involve a connection to a database, but in this case, I use a simple TreeMap, which is basically a keyed list. I told you the class was simple; there is more code in the initialization than in the rest of the class.
What I Had to Do
Once the class was written, turning it into a Web Service required very little work. All I had to do was follow the steps in the cheat sheet. I read the introduction shown in Figure 1 and then clicked on the arrow at the bottom. This marked the first section of the cheat sheet complete and moved me on to the next section, as shown in Figure 2.
Figure 2: This is the second task in the cheat sheet, creating a Dynamic Web Project.
After reading what was going to happen, I clicked on the black arrow, which then brought up the appropriate wizard for the step. In this case, the wizard was the New Web Project wizard (Figure 3). I entered a name for my project (WSServer) and continued on.
Figure 3: This is the New Web Project wizard, which was invoked by the cheat sheet.
I continued working my way through each step of the cheat sheet until I had a working Web Service that I could test through the Web Services Explorer (Figure 4).
Figure 4: The Web Services Explorer is used to test a Web Service.
I continued on with the cheat sheet and created a Web Services client and then ran that within the workbench. That gave me a lightly different view of the same Web Service (Figure 5).
Figure 5: This is the Web Service after being called by the generated Web client proxy.
As you can see, the results are the same, which is a good thing. In the meantime, though, the workbench created an entire new project for me, as well as four client classes (in addition to the hefty WSDL file it created during the previous step).
What It Does, It Does Great
The Web Services cheat sheet works probably as well as anything like it I've ever seen. The integration between it and the various WDSc wizards is smooth, and the step-by-step nature of the approach appeals to me. And the cheat sheet I used is only one of three Web Service scenarios and only one of six cheat sheets. Given how well they work, I'm going to try some of the others when I get a chance.
The trick to the cheat sheet is how it encapsulates everything in simple, easy-to-follow steps that invoke the powerful WDSc wizards. With this technique, almost all of the actual work is hidden from you.
The Devil Is in the Details
Now, I must sound a warning, if only a mild one. Up until this point, everything has worked flawlessly, but that's because I've stayed strictly within the boundaries of the cheat sheet. Let's say I want to do something a little out of the ordinary; for example, suppose I want to write my own test client.
It would seem reasonable that I could simply go into the generated client code and start to play with it. The problem is that the code isn't that simple. There are over 300 lines of JSP code alone required to display the simple screen shown in Figure 5. Add to that over 200 lines of Java in the four generated classes, and it starts to get awfully top-heavy.
I managed to cut the client-side code in half, creating a simple client class that invokes a Web Service without all the extra baggage of the JSP. However, because everything is wrapped in a SOAP document, I was unable to remove the bulk of the code that formats the document. The code below shows one method generated by the Web Service wizard.
if (_getEmailOperation0 == null) {
ParameterDesc[] _params = new ParameterDesc[] {
new ParameterDesc(
QNameTable.createQName(
"http://server.ws.pbd.com",
"customer"),
ParameterDesc.IN,
QNameTable.createQName(
"http://www.w3.org/2001/XMLSchema",
"string"),
java.lang.String.class, false, false),
};
_getEmailOperation0 = new OperationDesc(
"getEmail", _params,
QNameTable.createQName(
"http://server.ws.pbd.com",
"getEmailReturn"));
_getEmailOperation0.setReturnType(
QNameTable.createQName(
"http://www.w3.org/2001/XMLSchema",
"string"));
_getEmailOperation0.setElementQName(
QNameTable.createQName(
"http://server.ws.pbd.com",
"getEmail"));
_getEmailOperation0.setSoapAction("");
FaultDesc _fault = null;
}
return _getEmailOperation0;
}
Although I tried, I was unable to remove the dense, nearly unreadable code generated in the bowels of the Web Service. And remember, this is for an almost trivial example. And even the code shown above is simplified; in the original code, every class was fully qualified, like so:
So if I wanted to write my own version of this code, I'd have to figure out how the IBM classes work, and I don't believe IBM is releasing the source to the com.ibm.ws.webservices packages. That means a lot of guesswork on my part to make use of those classes, as well as the chance that my custom code could break with the next release of IBM's jar files.
So what does this all mean? Among other things, it means I'm stuck using whatever code WDSc generates. I can't go in and customize and streamline the code to my own liking, and since this code must be all things to all Web Services, I end up with some pretty fat code.
Also, I don't really know what this code does. Through careful examination, I think I can puzzle out some of what is intended, but given the high use of specialized IBM classes, I'm not sure I would be able to debug this in the event of a failure.
And that brings me back to my opening quotation: To me, the Web Services wizards generate code that, while good enough for testing, is really only a substitute for production code, not the real thing. Like someone who can quote witticisms to seem witty, I can use the wizards to generate Web Services and seem Web-enabled, but unless I can get in and debug those generated classes, I hesitate to put them into production.
Lots of Compliments and a Caveat
By far, the news is good. The VIC is doing great things, and the Web Services cheat sheets functioned flawlessly and indeed managed to automate a process of substantial complexity. I am still raising a red flag, albeit a small one, regarding the proliferation of wizard-generated code that may or may not be debuggable in production, but the fact that I turned a class into a Web Service in about 10 minutes is an awfully strong argument in favor of the process.
Joe Pluta is the founder and chief architect of Pluta Brothers Design, Inc. He has been working in the field since the late 1970s and has made a career of extending the IBM midrange, starting back in the days of the IBM System/3. Joe has used WebSphere extensively, especially as the base for PSC/400, the only product that can move your legacy systems to the Web using simple green-screen commands. Joe is also the author of E-Deployment: The Fastest Path to the Web and Eclipse: Step by Step, with WDSc: Step by Step coming out this September. You can reach him at
LATEST COMMENTS
MC Press Online