The technology world is abuzz with talk of Web services. Code warriors and suits alike are touting it as the next big thing. The incorruptible Apache Software Foundation has spawned a whole top-level project dedicated to it. Yet, I'd venture a guess that relatively few of us completely understand the concept - and even fewer sense an immediate need to dive right in.

Perhaps this is because Web services is pitched in fuzzy marketing language (from which it's difficult to extract anything concrete), most of which focuses on applying Web service technology in the consumer market and in B2B transactions. These are real applications and will likely become ubiquitous in the years ahead, but the immediate utility of Web services lies elsewhere.

The most exciting concrete thing about Web services today is its potential to finally deliver when it comes to integrating internal systems. If you could be a fly on the cube wall at most big corporations, you'd hear daily grousing about different systems not talking to each other and the need to enter the same data into several different applications, which costs us both in time and in the increased potential for data entry error.

It's an old problem, and most of us can recite a long list of acronyms we once thought would help us solve it: CORBA, RMI, COM, IOP, IIOP, RPC, and lately, EJBs. The problem with these methods of "distributing" applications is that they're proprietary to a specific programming language or a narrow subset of languages. EJBs work well if you're trying to interconnect a far-flung set of Java applications, but like it or not, much of the world's economy is transacted on big iron via COBOL and RPG (Report Program Generator) - and they don't speak bytecode.

All of them, however, speak text. For all the fanfare, Web services consists of little more than the exchange of text messages between peers. The text happens to be XML - and specially formatted XML at that - but text is still text. This inherent language independence - coupled with the fact that Sun, Microsoft, and IBM have actually agreed upon and contributed to the standards that constitute Web services - is highly encouraging. All this has given rise to the latest acronym being bandied about among the IT brass: EAI, or Enterprise Application Integration.

How Web Services Actually Work
Web services, much like J2EE, is an umbrella term under which a number of related standards reside. Web services is often thought of as a layered stack of protocols consisting primarily of HTTP, XML, SOAP, WSDL, and UDDI. Other standards for things like authentication and two-phase commit transactions are in the hopper, but have yet to gain enough momentum for us to know if they will stick.

As I alluded to earlier, a Web service is basically a formatted exchange of XML messages, theoretically over any transport protocol, but HTTP is used often enough to make it the de facto standard. A typical Web service request consists of an XML-formatted message being posted to an HTTP server that responds with an XMLformatted reply. If we consider a simple state capital Web service, the raw HTTP exchange would look like Listings 1 and 2.

The flurry of tags and namespace declarations that surround the actual data in our state capital example is called SOAP. Although the acronym stands for Simple Object Access Protocol, SOAP is really a messaging protocol. It uses the concept of envelopes to wrap the XML data with the headers necessary to route, secure, and control the messages. In addition to pure message-based SOAP, a Remote Procedure Call model is specified by the SOAP 1.2 Adjuncts document as a standard extension to SOAP and is included in most SOAP implementations. While this is little more than a standardized way of encoding method calls as SOAP messages, it makes it possible to easily convert existing function or method libraries into Web services.

The whole idea behind Web services is to create or wrap some useful functionality using language-independent SOAP messages. Doing this does little good unless there is a standardized way of describing the interface thus exposed by a Web service. WSDL, or Web Services Description Language, is that standard. WSDL provides information about the location of a Web service, its URI or identifier, along with what methods or "operations" are supported and the format of their associated parameters. It isn't absolutely necessary that you understand the details of WSDL to build Web services, as those flavors of WebSphere Studio that include Web service tools will generate the WSDL for you.

The last Web services standard we'll consider is UDDI or Universal Description, Discovery, and Integration. UDDI is a standard for Web service directories and at its most basic level provides a mechanism to store, find, and retrieve WSDL documents (and others) for public services. It allows Web services to be located by company name, service type, category, etc.

Viewed in the context of internal integration projects, a private UDDI server on your intranet can provide a central place for various project teams to publish the fact that they exist, along with their associated APIs. Project teams that must integrate their work with the work of other teams don't have to hunt for API documentation that may or may not exist. They just look up the other project's WSDL with UDDI and use a tool like WSAD to generate a Java client for it. It provides a way around the phone tag and meetings usually required to extract documentation from other project teams. The format of API documentation is consistent across all projects and can even be fed directly into code generators.

With the preliminaries out of the way, let's consider a simple example that makes use of all these acronyms and WSAD to generate a complete Web service. We'll stick to pure Java for now and delve into how legacy systems fit in later.

A Quick Tutorial
WebSphere Studio generates all of the plumbing required to publish a Web service for us. All we really need to do is create a simple JavaBean that performs a given function and let WSAD do the rest. Start by creating a new Web project called wsdj-example-web and a source package called com.wsdj.ws.example.

Next, create a new class called StateCapitalService and paste in the code in Listing 3. Note that there's nothing in this code that references SOAP or anything Web service-specific for that matter. This means that the code used to implement a service doesn't have to know it's a Web service. It's a JavaBean just like any other. This makes it extremely easy to convert old Java libraries (or Java wrappers for RPG and COBOL) into Web services without doing much extra legwork.

Before we actually create the service we need to create a local UDDI Registry in which to publish it. Do this by selecting "New" from the File menu. When the dialog comes up, select Web Services and Unit Test UDDI. Accept the default Registry Type (Cloudscape) and click "Next". Select the server you would like the local registry to run in and click "Finish". WSAD will then create the necessary resources, start the server, and load the Web Services Explorer.

 

Finally, we come to the point of turning a mere JavaBean into a full-fledged Web service. Select the wsdj-exampleweb project, open the context menu, and click "New". Select the Web Services category and Web Service as the wizard type. Click "Next" and use Table 1 to navigate through the subsequent wizard.

 

Provided you encountered no errors in the wizard, you have officially created a Web service. The next step is to publish it in the local UDDI registry. The wizard seems to suggest that it did this for you, but it didn't. It merely fires up the Web Services Explorer for you. Luckily, publishing is pretty easy. Select your local UDDI node from the Navigator pane (see Figure 2) and click the "Publish" button to the right of the "Actions" heading. Select Service Interface as the type of information to publish. Scrolling down, enter "admin" for the User ID and click the browse link next to the WSDL URL. In the pop-up window, select the wsdj-example-web project. The only WSDL file that should appear in the list will be the one for the StateCapitalService we just created. Click "GO" and finish up by entering a name and description for the service. Click "GO" on the publish page.

 

The WSDL document describing the state capital service has now been entered into the UDDI directory. At this point we can use yet another WebSphere Studio wizard to create a client for the service. Start by creating an empty Web project for the client called wsdj-exampleclient. Next, get the WSDL URL ready by copying it onto the clipboard before returning to the File menu and clicking "New". Select the Web Services category and Web Service Client. Accept the default values for the first wizard panel and click "Next". Paste the WSDL URL into the URL field and click "Next". Make sure the client project you just created is selected, step through, and finish the wizard.

If you take a look at the client project, you'll notice that a class called StateCapitalServiceProxy has been created with a getCapital() method signature identical to the one in the original service plus the getEndPoint() and setEndPoint() methods. To use the proxies, you must first set the endpoint value equal to the URL of the SOAP RPC router, which is the servlet through which all RPC services are executed. This URL typically takes the form:

http://<hostname>:<port>/<applicationcontext>/servlet/rpcrouter

Admittedly, working our way through wizards panel by panel is a bit tedious, and the pathway described above should by no means be considered the only way to do it. The important thing to note about the preceding process is how little code was actually written. We essentially pointed the Web Service wizard at a JavaBean and let it work its magic. It generated the WSDL and deployed the service for us. We published the WSDL for our service in a UDDI registry, making it available for potential users to find. We then assumed the role of a client and used the published WSDL to generate a Java proxy for the service. We may have examined the two processes at a low level of detail, but with a little practice, building Web services and their clients becomes a quick, intuitive process.

SOAP for Big Iron
COBOL and RPG may be losing favor, but they're far from dead languages. If making these apps accessible as Web services means rewriting them in Java or (shudder) C#, few prudent IT execs would blithely take such a risk. The good news is that several techniques exist for adding SOAP functionality to legacy systems without throwing the proverbial baby out with the bath water. For mainframes, IBM has a SupportPac module specifically for this purpose called SOAP for CICS. iSeries programmers have to go through WebSphere, which means wrapping everything in Java, but this isn't the Herculean labor it portends to be either. If you have WebSphere Development Studio for iSeries, you can generate Java wrappers for all of your RPG programs using fairly intuitive GUI tools.

The particulars of wrapping COBOL and RPG code with Java are arguably out of scope here, but knowing how you actually go about turning your legacy apps into Web services isn't nearly as important as knowing that you can. Building SOAP interfaces around legacy apps allows you to do a number of neat things.

First, taking an API approach and putting everything needed to interact with the app into the SOAP interface allows new user interfaces to be written in whatever language makes sense for that user interface. You could write a new Windows client using Visual Studio .NET or a new Web interface with WebSphere Studio. The demise of green screens means more intuitive user interfaces that dramatically lower training and help desk-related costs. Going the Web route even eliminates the need to support the software on user desktops. Client deployment consists of dropping a new EAR file into your friendly neighborhood app server and adding a new link to your intranet portal.

Second, apps that are merely walled in with SOAP interfaces don't have to be scrapped and rewritten. This obviously saves a lot of money by extending the life of applications, as well as mitigating the untold risks associated with tossing out perfectly good code whose only crime is not being Java.

In addition, multiple applications with published SOAP APIs lend themselves to the development of single integrated clients that combine the features of each without forcing users to bounce around between systems.

SOAP APIs can deliver the holy grail of code reuse and component-based software development that actually works off the white board. Ostensibly, the main reason SOAP can actually make component-based software development possible is its indifference to programming language. And while that is a huge plus, I would argue that the UDDI and WSDL standards for publishing APIs are an even bigger plus when it comes to reuse. The reason is political. The more people that have to actively collaborate in order to share code, the less likely it is to actually happen. For a variety of reasons, be they inconsistent documentation formats, competitiveness between departments, or merger and acquisition-related political struggles, a centralized UDDI server isn't open to human interference. If the team developing an integrated client needs API docs, they know where to get them. No phone calls. No rooting around in shared folders for Word documents. No stonewalling. (A free open source UDDI server called Roundhouse that displays WSDL in a Javadoc-like format is available from www.mediafortress.com.)

Finally, a SOAP API makes it possible to convert the inner workings of legacy apps gradually. Once a SOAP API is deployed and users are weaned off proprietary clients, the internals of such applications can be slowly converted to a language such as Java without disrupting use or functionality of the system. An RPG application gets bits of Java introduced into it in the process of ongoing maintenance, and before long the hybrid app is more Java than RPG. Eventually the last line of RPG is replaced, and now you have a portable application that comes with no vendor lock-in strings attached.

The Catch
If you're salivating over the prospect of instantly modernizing the interfaces to your legacy apps by having your people spend a few weeks stepping through wizards, don't start popping corks just yet. Unless you take extra care to preserve the language neutrality and interoperability that makes us love SOAP so much, you could end up working yourself into a tight corner. The main gotcha involved with SOAP-enabling older applications revolves around complex data types such as objects and structures. Since such data structures are anything but language independent, any method or function being exposed via SOAP that makes use of such objects needs to be wrapped by another method that converts these objects into a languageneutral expression of structured data, which just happens to be something XML is awfully good at.

The SOAP specification itself does allow for the declaration of custom data types, but it's usually better to convert complex parameters into XML elements yourself than to let SOAP do it for you. Otherwise you get into the realm of creating custom object serializers and deserializers whose operation is closely tied to a specific SOAP implementation, which affects the portability of your own code. Clients that eventually make use of the interface will face a similar dilemma. Yet detaching the XML conversion of complex data types from the underlying SOAP provider doesn't alleviate the need to do it.

Assuming the bridge between old and new is made with Java, what emerges is a layer of JavaBeans specifically designed to have SOAP-friendly method signatures (see Figure 3), which can then be fed into Web service wizards. The most labor-intensive portion of any RPC SOAP interface, the XML/object converter, powers this layer. The form this converter will take is largely a function of the type of data being converted and the preferences of the developers who design it. It may be implemented by extending the XML transformer facilities of Xalan or some customized solution. Either way, every SOAP interface layer needs a black box into which Java objects go in and XML elements come out.

 

Building this black box is the trickiest part of building any SOAP API and requires the development of a standard XML representation for every object used by the application. Typically, this representation will ultimately manifest itself as an XML Schema file that can be used to validate the data coming into and out of the interface.

Another trouble spot with SOAP is security. Web services can be secure, but as of right now authentication and access control aren't part of the standards generally accepted to make up Web services. SOAP as implemented by Apache - and thus IBM - does support the idea of sessions, so session-based authentication can be used with SOAP just the way we use it with traditional Web applications.

You could always roll the dice with one of the competing security standards and hope you pick the one that eventually catches on. Or you could invent your own mechanism for authenticating users. At this point, there is no one perfect solution and certainly none that are part of implementations that aren't vendor specific. Your best bet would be finding a way to play nicely with whatever single sign-on solution your company is moving toward. Just be aware going in that dealing with security will be up to you.

The Road Ahead
Most of us have heard it said that one day in the not-toodistant future just about every business application will be J2EE or .NET. Recent studies by Gartner and others bear this out. For our sake, let's hope things are slanted a little more toward J2EE. However the pie chart eventually gets sliced, Web services and specifically SOAP promise to be a bridge between the two - and a viable way to build new applications from pieces of old ones. Web service applications will also emerge for consumer and for inter-business transactions, but more standards work is needed before Web services truly replace the phone and fax machine.

An IT executive can't control what other IT executives do, or whether or not all the world's corporate transaction systems talk to each other. The Web service gurus aren't quite ready to tackle that one either. What Web services can do now is put language- and vendor-neutral APIs on top of any application, as long as you're willing to invest the time it takes to convert the object vocabulary of these applications into XML and back again. Once deployed, these APIs can be used to replace older clients, create integrated clients, accelerate the development of new applications by reusing pieces of the old ones, and shroud the innards of legacy apps under renovation.

Like all things in technology, these benefits don't come without trade-offs. Building XML Schemas for big applications with lots of complex data structures is no small task, and you'll have to find your own way when it comes to security. Yet all things considered, these annoyances are a small price to pay for the flexibility and long-term cost savings a Web service- based and fully integrated application infrastructure provides. And while portals as they typically exist today give companies the illusion of an integrated universe of applications, Web services can actually integrate them.