Feature

Our latest book, Developing Web Services for Web Applications, takes you on a guided tour of developing and using Web Services with Rational Developer and WebSphere. This article, an extract from the book, gives you an introduction to the basic steps to create and use a simple Web Service in Rational Developer, and describes what you’ll learn when you follow the guided tour.

To follow along with the steps in the book, you need IBM WebSphere Application Server 6.0. You also need either IBM Rational Web Developer 6.0 or IBM Rational Application Developer 6.0. Application Developer contains all the same functions you’ll find in Web Developer (and much more), so you can follow the instructions with either product. For simplicity, we refer to the tools as Rational Developer, but you can use the one you prefer. You can install WebSphere Application Server and Rational Developer separately on your machine, or if you prefer, you can install WebSphere Express 6.0, which includes both WebSphere Application Server and Rational Web Developer. If you don’t already have a copy of WebSphere Express 6.0, you can download a trial version at www-106.ibm.com/developerworks/websphere/
downloads/EXPRESSsupport.html.

Introduction
Web Services are network-accessible programs that use a standardized messaging protocol to communicate with other programs that want to use their functions. Web Services reside on application servers, such as WebSphere Application Server, which can be on the Internet, on your company’s private intranet, or on your own computer. The functions that Web Services provide can be general-purpose, such as looking up the weather forecast for a particular city, or application-specific, such as creating an order for an e-commerce application. Web Services are also self-describing; that is, they include special descriptions of the functions that they provide and how to access those functions. Application programmers use these descriptions to find (discover) and use the services.

Web applications also reside on application servers. These applications consist of one or more Web pages that users access through a Web browser. They typically contain a combination of static and dynamic content, such as text, images, and programs that run on the server or in the user’s Web browser. Web applications can use Web Services that reside on the same server, or on any server in the network that the Web application has access to. Unless you tell them, users at a Web browser aren’t aware that the work might be distributed across multiple servers.

Notice that we haven’t said anything about what programming language a Web Service is written in, or what operating system it’s running on. That’s because it doesn’t matter. The Web Service just needs to be available on the network that the application is using, and the service and the application need to use the correct protocol to communicate with one another. The application can be written in a different programming language than the service, and run on a different operating system.

Web Services and applications communicate with each other using messages in a specific, standardized format. An application builds a message request such as “give me the weather forecast for Atlantic, NC,” and sends it to the server where the Web Service resides. That server calls the Web Service to process the request. When the Web Service returns the result (such as “warm and sunny”), the server builds a message response and sends it back to the application. At first glance, this probably sounds very complicated — building messages and sending them where they need to go. As you’ll see in this article, however, Rational Developer and WebSphere handle most of the work for you, so you can just concentrate on developing your Web Service functions and application logic.

With Rational Developer’s Web Service wizard, you can create Web Services from existing artifacts, such as JavaBeans, stored procedures, EJB components, or SQL queries. For the examples in the book, we have you create your Web Services from JavaBeans, since that’s a common practice. We also explain all the Web Services terminology (an alphabet soup of acronyms), as you encounter each topic on the guided tour, such as WSDL, one of the main building blocks of Web Services.

WSDL
Web Services Description Language (WSDL) is the XML vocabulary that describes Web Services. WSDL is stored in standard text files with a .wsdl extension, typically on the same application server where the Web Service itself is deployed.

As a Web Service developer, you use WSDL to describe the functions that your Web Service provides and how other programs can access those functions. For other programmers to use your Web Service, you have to give them access to two things:

• Your Web Service program
• The WSDL file that describes your Web Service

From the WSDL, other programmers know the URL to use to invoke your Web Service, the specific format of requests that your Web Service handles, parameters that need to be supplied to each request, the format of responses, and so on. Basically, the WSDL provides all the rules that a program needs to follow to use your Web Service.

As a Web application developer, you use the WSDL for a particular Web Service to create the code that locates, builds messages for, and invokes the Web Service. Typically, all this logic is placed in a client proxy that represents the Web Service in your client application. You just call the proxy, and it handles all the details of finding and invoking the Web Service. 

Luckily, you don’t have to be fluent in WSDL to create or work with Web Services, because Rational Developer handles it all for you. When you use the Web Service wizard to create a new Web Service, the wizard creates the corresponding WSDL file. And when you want to use a Web Service in a Web application, you just point the Web Service wizard to the WSDL file, and the wizard creates the client proxy to locate and invoke the service.

Creating a Web Service
To keep things simple for the first example, we use what’s become a standard Web Service, the StockQuote service, shown in Listing 1 at the end of this article. This Web Service has one operation called getQuote. The caller supplies a stock symbol, and the Web Service returns the last trading price for that stock symbol. We supply source code for the JavaBean on a CD that’s included with the book, so you just need to create a Web project to contain your Web Service, and import the source code into it.

To create the Web Service, right-click StockQuote.java in the Workbench, and select Web Services > Create Web Service from the pop-up menu. The Web Service wizard’s Options window appears as shown in Figure 1.

Notice that the wizard has many options to control how a Web Service is created, to test and publish the Web Service, and to generate and test the client proxy that applications call when they want to use the service. For the first example, you’re just creating the Web Service using Rational Developer’s defaults. That means your Web Service will be set up to run in the WebSphere Application Server v6.0 runtime environment, which is the default runtime environment for Rational Developer, so just click Finish.

When the wizard completes, you’ll see that it added several new folders and files to your Web project. What you see are the control files that WebSphere Application Server needs to process your StockQuote class as a Web Service, so that, when an application sends a message to invoke the Web Service, the server knows what to do. The control files include the information that applications need to discover and use the Web Service — namely, the StockQuote.wsdl file in the WebContent/WEB-INF/wsdl folder. The WSDL file describes the operations that the Web Service provides and the URL that applications use to access the Web Service. You’ll use this file in the next section to create a client proxy (that is, the code that your application calls to use the Web Service).

In addition to creating all the necessary control files, the wizard also deployed your Web Service to the WebSphere Test Environment, which means your Web Service is now ready to use. In the next section, you’ll change roles from being a Web Service developer to being a Web application developer. In that role, you’ll create a Web application to test your Web Service.

Creating a Web Application
The Web application you’ll create to test your Web Service is a JavaServer Page (JSP). It contains an HTML table with your favorite stock symbols and their last trading prices. You’ll create the application in a new Web project using Rational Developer’s Page Designer and the Web Service wizard. Then, you’ll run the JSP in the WebSphere Test Environment (the same server where your Web Service is currently deployed).

For the Web application, you’ll create a StockQuoteClient Web project to contain the Web application, and a new JSP file called MyStocks.jsp. When you create the JSP file for your Web page, it opens in the Page Designer. You use the Page Designer much like any other graphical editor. To add or change text in the Web page, just type on the design surface. To change the attributes for a particular text string, select the text on the design surface, and then set the value you want in the Properties view. The Properties view appears at the bottom of the Workbench, and its layout changes based on the element that’s currently selected on the design surface.

To add more complex elements to the Web page, such as tables, images, forms, or JSP logic, select the element you want in the Palette (see Figure 2), drop it on the design surface, and set its attributes in the Properties view. The Palette contains all the commonly used elements for Web pages, organized into related groups called drawers. You click the name of a drawer to open it.

To add the table of stock symbols to your Web page, select a Table in the Palette’s HTML drawer, and drop it on the design surface. When prompted to enter the number of table rows and columns, leave the columns set to 2, set the rows to the number of stocks you want to display plus one for the table header, and click OK. Then just type in the text you want for headings and stock symbols so the design surface looks like Figure 3.

To add the dynamic content to the Web page, you’ll use the Web Service wizard to create a client proxy for your StockQuote Web Service, that is, the code that a Web application uses to call the Web Service. All the Web Services in your Workbench are conveniently grouped in a Web Services folder, so to create the client proxy, you just right-click StockQuoteService in that folder, and select Generate Client from the pop-up menu. This time, the Web Service wizard just shows the options relevant to creating a Web Service client (a subset of the options you already saw in Figure 1). The first two pages of the wizard are preset with the values you want, but you need to verify on the third page that the correct Web project is selected as the Client project (the project where the wizard will place the client proxy), as shown in Figure 4.

Click Finish, and when the wizard completes, you’ll see that it added several new folders and files to your StockQuoteClient Web project. In particular, the JavaResources folder now contains a “samples” package with six Java source files. These files are the client proxy code that the wizard generated for you from the WSDL file using the default client runtime, that is, the WebSphere Application Server v6.0 runtime environment. If you had chosen a different client runtime, the generated code would look somewhat different, but the concept would still be the same — these are the classes that your application uses to access the Web Service.

The client proxy code is very simple to use. First, you create an instance of the proxy class that represents your Web Service — that’s StockQuoteProxy for your StockQuote Web Service. Then, you call the proxy’s getQuote(String) method, passing the stock symbol whose trading price you want. That’s it. The proxy classes do all the work to locate your Web Service, send the request message, and return the response (the stock price) to you.