Just the first of many fun tools for the enterprising Web developer

By now, you've read the hype. You know that Web Services is the "next big thing." You know it utilizes the hottest technologies such as SOAP and UDDI, but if you are like me, you are tired of reading white papers, high- level architecture papers, and magazine articles telling you what it is. You want to start writing your own Web service. Your wait is at an end.

Background
In case you have not read all the white papers and architecture documents, it is important to understand Web Services from a high level. Readers familiar with the high-level concepts may wish to skip this section.

Definition: A Web service is any program that is callable by another program across the Web in a platform/language/object model neutral fashion (using standardized Web Services protocols). In short, a Web service is to an application what a Web page is to a person.

The Web Services protocols mentioned above include Simple Object Access Protocol (SOAP); Universal Description, Discovery, and Integration (UDDI); and Web Services Description Language (WSDL).

The process for a typical Web service is described in Figure 1. In this example, the service provider publishes its service interface (a WSDL document) to a service registry (a UDDI provider). A service requester searches the service registry and finds a Web service that will suit its needs. It then binds to the service provider in order to execute the service (using SOAP).

The Web service itself is really nothing more than a Java servlet, bean, EJB, etc. The Web Services architecture is simply a wrapper for accessing this preexisting code in a platform and language-independent manner.

One of the main benefits that Web Services brings to the table is ease of integration. Consider a B2B scenario in which Company A, built upon Microsoft technology, wishes to connect to Company B, built on Java servlets. The process of integrating these two polar technologies requires significant developer time and resources. Things become even more interesting when Company A wishes to interface with a third company, Company C, built on CORBA/C++. Company A must now begin another long integration project. Enter Web Services. Now integration efforts that used to take 12 months may take as little as 12 days.

The key player for reducing integration time is SOAP. SOAP is an XML technology that describes remote procedure calls (RPC).

It is similar to Java Remote Method Invocation (RMI) but is platform-and language-indepen-dent. Thus, a C++ program can execute methods on a Java program, running on the other side of the planet. As you can see, the power of Web Services presents countless possibilities. Now let's write our own Web service.

What do I need?
The examples in this article were written in the IBM XML and Web Services Development Environment (WSDE) and executed in the IBM WebSphere Application Server Advanced Edition 3.5.3 run-time environment. WSDE is available for free download from www.alphaWorks.ibm.com/tech/wsde. The WebSphere Application Server 60- day evaluation version is available at www.ibm.com/software/Webservers/appserv/download.html. At the time of this writing, the WSDE was only supported on Windows NT/2000. The evaluation version of WebSphere Application Server will run on the Red Hat Linux and NT/2000 platforms. The WSDE also supports the Apache Tomcat as a runtime environment (http://jakarta.apache.org/tomcat/index.html). After downloading and installing WSDE and WebSphere, you are ready to begin development.

From the bottom up
Our example will focus on bottom-up design strategy. This means that we will develop the application first, and then fit a Web service wrapper on top of it. At least initially, most Web Services development will follow this strategy.

The Web service we will create is a stock quote generator. When given a stock symbol, this service will return the current price for one share. Users of this Web service will probably be portal companies that provide stock advice to their customers.

Open the WSDE environment (see Figure 2). Select "Create a new Web project," and then click OK. Enter solution and project names (see Figure 3). Continue through the wizard with the default values. When you have finished you will have created the Web project in which you will develop your Web service.

Next, change the perspective to Java (from the menu bar select Perspective/Switch To/ Java Perspective). This provides a more suitable development environment for coding. In the left pane, switch to the "Packages" tab, and then expand to the "servlets" directory. Right click on servlets and select "New/ Class..." to create a Java bean that will return the stock price. Name the class Stock QuoteService.

Enter the code for StockQuoteService (see Listing 1; all code listings can be found at www.wsj2.com). This class will read in a properties file containing a number of stock symbols and their corresponding prices. Save the file when finished. You may have compiler errors because you are missing a required class, StockNotFoundException. The code for this exception is found in Listing 2. Once you have entered the code for both of these classes, you are ready to test it.

In order to test the new application, you need to create a file called stock_ quote.properties that contains the stock symbols and prices you wish to display. An example of this file is in Listing 3. This file must be located in the directory specified by QUOTE_FILENAME in Stock QuoteService.java found on line 10.

Now, from a command prompt, you can test the code within the /workbench/Sample/SampleProject/servlets by executing "java StockQuote Service ", where is a symbol in your stock_ quote .properties file. You should see the corres-ponding price for that stock.

Next Stop: The Web
At this point we are ready to add some spice. Now that we have a working application, it is time to turn this ordinary command-line program into a Web service that is accessible to the world. The first step is to start the WebSphere admin server. You start the admin server from the Windows Services (on NT, Start/ Settings/Control Panel/ Services; on 2000, Start/Settings/Control Panel/Administrative Tools/Component Services/Services). Find and start the service labeled, "IBM WS AdminServer."

The next step is to create a new WSDL Web service in WSDE (File/New/WSDL Web Service). This will bring up a wizard that looks like Figure 4. You can accept the defaults here, but make sure that you select "Create a Web service (WSDL) from an existing Java bean." You may also need to select a folder; select /Sample/SampleProjects/servlets. Click Next.

On the next screen, select the StockQuote Service.class file and proceed. The third screen allows you to select which method to publish. Select getQuote(String).

The fourth screen has many fields, as shown in Figure 5. First of all, you will need to select IBM WebSphere Standard Edition v3.5.2 (even if you are using 3.5.3). You can leave the defaults for the rest. This information will be stored in the SOAP deployment descriptor.

The next screen is where you will actually deploy the SOAP Server and SOAP deployment descriptor from the previous screen. Change the directory of the WebSphere Install Path if necessary. Then press Deploy. Once you have successfully deployed the app to the SOAP Server, press next.

This is where you will generate a client proxy. A client proxy is a Java class that allows a client application to use your Web service remotely. It contains the methods you declared in the third screen plus getEndPoint() and setEndPoint(java.net.URL). These two meth-ods allow the client application to set the location of the SOAP Server. The methods you declared create a SOAP request to the specified SOAP Server with the parameters that the client specified, all behind the scenes! We will discuss this more later.

The next screen generates the test client for the Web service. It is a JavaServer Page (JSP) that runs on the specified port (default 9090) and will invoke the methods on the StockQuoteServiceProxy class. When you click the Launch button, it starts a test servlet engine from which the test client is executed. It also launches your Web browser to the testclient.jsp page. The servlet engine is shown in Figure 6; the test client page in Figure 7.

Click on the Web service creation wizard. This screen simply displays what has happened (see Figure 8). Click Finish and return to the Web browser.

In the top left frame is a list of methods from the services StockQuoteServiceProxy class. Clicking on a method here changes the top right frame to allow you to enter any parameters, and invoke the service's method. Experiment with this to work out any bugs in your service's implementation. For example, rename the properties file and try to invoke getQuote(String). You should see a SOAPException in the bottom frame. You can also use stock symbols that you have not defined.

If everything has gone correctly, you have just created your first Web service! Of course, the test client application is the only client so far, and it is not terribly useful. If all you wanted to do was display stock prices in a Web page, you have many less complex alternatives (servlet/JSP, CGI, etc.). So, to take better advantage of your new Web service, let's write a client application with logic that depends on this Web service.

The Service Requester
If you are a stock day trader, you know the importance of selling and buying at just the right moment (hopefully buying low and selling high). If you are like me, you cannot afford to hire a stockbroker to constantly monitor the market. But if you could write an application that monitored a stock (or list of stocks), you could build in logic to buy or sell once the stock reaches a set price. This idea is the basis for our client application.

Listing 4 shows the code for the Stock Broker (service requester) client. To run the StockBroker, you will need to create a broker.properties file such as that in Listing 5. This will allow you to set up the stock you wish to purchase (or sell), the range the stock price must be within in order to buy or sell it, and the quantity of shares to buy or sell. The operation attribute must be either "BUY" or "SELL". Also, when executing the StockBroker you will need to ensure that the client proxy and soap.jar and the <WSDE DIRECTORY>/workbench/ Sample/Sample Project/servlets directory is in the classpath (e.g., java-classpath .;c: \itp\plugins\org.apache.soap\soap.jar StockBroker).

Once you have started the StockBroker, it will sit and wait until the stock price falls (or rises) into the specified range. Open the stock_quote.properties file in a text editor such as Notepad, and change the specified stock price so that it fits within your range. Within a few seconds, StockBroker will alert you that it has purchased (or sold) a number of shares. The key to writing Web service requester applications is in using the generated proxy class methods (see Listing 6). If you have access to a networked environment, you can write a more advanced client application that will make a SOAP request to another server [using the setEndPoint(URL) method in the proxy class)], possibly on another platform.

Summary
If you have made it this far, you have successfully created and tested your own Web service and client. If this were a real enterprise quality client, you could distribute it via CDROMs, FTP, etc., to your paying customers. Furthermore, you could publish your service in a UDDI registry, on the Internet. While this article has shown you how to write a very simple Web service, I hope that it will also encourage you to explore the various Web Services tools and offerings available.

• Figure 1
• Figure 2
• Figure 3
• Figure 4
• Figure 5
• Figure 6
• Figure 7
• Figure 8
• Source Code