Contents


Consuming Web services

Use Rational Application Developer to create and consume Web services

Comments

Before you start

Learn what to expect from this tutorial, and how to get the most out of it.

About this tutorial

Web services provide a way for applications to easily communicate using common protocols, which allows for collaboration both across platforms and across time zones. To a developer who hasn't used Web services before, however, just understanding all the acronyms can be a challenge. Messages can be exchanged using text-based XML, so any system can read them; protocols such as the Simple Object Access Protocol (SOAP) can define their content so that systems recognize what they're looking at. You can describe entire messaging systems using a Web Services Definition Language (WSDL) file and publish information about the service in a Universal Description, Discovery, and Integration (UDDI) directory for companies to find.

Fortunately, using Web services doesn't require learning about all of the different technologies -- if you have the right tools. IBM® Rational® Application Developer Version 6.0 (or IBM Rational Web Developer Version 6.0) enables you to create and use Web services without knowing anything about XML, SOAP, or any of the other acronyms involved.

In this tutorial, you will:

  • Learn how different technologies interact to make Web services work
  • Wrap a simple inventory-control application as a Web service
  • Test the Web service
  • Browse the code for the Web services consumer
  • Build a Web services client for an external Web service
  • Test the external Web service
  • Build a WSDL file
  • Convert a WSDL file into a Web service

System requirements

To run the examples in this tutorial, you need the following software:

  • Rational Application Developer Version 6.0 (download the latest trial version) or Rational Web Developer Version 6.0 (download the latest trial version).
  • Apache Tomcat Version 5.0. You can use Apache Tomcat Version 5.0 or later.
  • Sample files. To start you off, this tutorial includes a simple Java™ class, which you can download.

See Related topics for related tutorials if you need to get a jump start. Familiarity with Java technology is also strongly recommended.

Basic Web services concepts

SOAP

The overarching idea of this tutorial is to allow you to make use of Web services from within your application. You can do so by making existing code available via a Web services interface or by using an existing Web services interface, or both.

Web services work by sending messages back and forth between applications. These messages can be as simple as Send me the current price of tea in China or as complex as Here are the details on the machinery I need fixed. Figure out where to put it on the schedule, create a work order, and make sure the parts gets ordered. The system receiving the message might create a response and send it back to the original requestor. These messages are typically sent in a form of XML called SOAP. SOAP messages consist of text that has a particular form -- with a header and body -- allowing both sides of the conversation to understand what's expected of them.

SOAP messages can do much more than simply provide information. Notice that both examples in the above paragraph involve requests that the receiver actually do something, such as looking up a price or arranging for a repair. SOAP messages can be used as a form of remote procedure call (RPC), allowing a system on one side of the world to execute, say, a Java method on the other side of the world (see Figure 1).

Figure 1. SOAP messages
SOAP messages

SOAP messages

These exposed methods make up the Web services interface. This tutorial explains how to take the methods in your own application and expose them in this way. In some systems, potential methods and their responses are detailed in a set of WSDL documents, as discussed in the next panel.

WSDL

WSDL provides a way for a system to explain what it does and how to get the system to do it. A WSDL file is XML that explains where the service can be accessed, the methods that are available, and the required parameters and their types (see Figure 2). It also details the form and type of any expected response.

Figure 2. WSDL messages
WSDL messages

WSDL messages

When you create a Web service in Rational Application Developer, the tool creates a set of WSDL files describing that service. WSDL describes the service so thoroughly, in fact, that by using Rational Application Developer you can also consume a Web service from a WSDL file. This tutorial shows you how to create a Web services client based on a WSDL file. That client contains all the methods necessary for accessing the Web services without ever specifically writing a single SOAP message.

Routers and proxies

Network administrators know routers and proxies as hardware and software that control the flow of messages over a network such as the Internet. Rational Application Developer acts as a proxy in a similar way when it comes to SOAP messages.

In this tutorial, you learn how to build a simple application this is exposed via a Web service. You also build a test client that can access this application by consuming this Web service. Although the data being passed between the Web service and the client is in the form of SOAP messages, neither the original application nor the client is using SOAP messages directly. The translation to and from SOAP messages happens behind the scenes via proxies and routers, as shown in Figure 3.

Figure 3. Web services interactions
Web services interactions

Web services interactions

When the application makes a client method call, that method is relayed through the proxy. The proxy then converts the method into a SOAP message, which is received intact. If a system is built directly on SOAP messages, it processes the message immediately. In the case where Rational Application Developer has exposed a traditional application, however, the request will be sent to an RPC router, which then makes the actual method call and translates the returned information back into a SOAP message. The response message is received by the proxy (in this case) and forwarded to the client application.

Rational Application Developer automates the creation of these proxies and routers, as the next panel shows.

UDDI

The last piece of the puzzle involves UDDI. UDDI is a specification that creates universal registries in which you can place pointers to WSDL files for other companies to find, or discover.

A UDDI Registry contains information about companies and the services that they make available. In essence, UDDI is a globally distributed business registry. Registering with one operator ensures that your company's information is replicated to other UDDI nodes, making that information available to companies searching anywhere within the system.

Conceptually, UDDI is similar to a huge phone book. The white pages enable you to find a company by name. Once there, you can see the services they provide. You can also look up a company by using the yellow pages, in which companies are listed by classification. This means you can look up companies that carry sporting goods or that provide navigational equipment. You can also use the green pages, which allow you to look up companies that provide a specific service. UDDI provides a way for companies to describe their services but doesn't require the use of WSDL. Instead, it provides a means for pointing to a WSDL file.

As mentioned before, Rational Application Developer enables you to directly import WSDL files using information discovered in UDDI and to publish similar information regarding your own WSDL files via the Web Services Explorer.

Create a Web services project

Create a project

To build Web services in Rational Application Developer, you need to work within a Web Project. To create a Dynamic Web Project:

  1. Click File > New > Dynamic Web Project.
  2. Click Next.
  3. Use the settings shown below.

    Figure 4. Settings for the new Dynamic Web Project
    Settings for the new Dynamic Web Project

    Settings for the new Dynamic Web Project

  4. Click Finish.

Note: For this tutorial, you'll use Apache Tomcat as the deployment container. Install Apache Jakarta Tomcat from the URL http://jakarta.apache.org/tomcat. After you have installed the server, create a Tomcat server in the workbench by performing the following steps:

  1. From the File menu, select New > Other > Server > Server > Next.
  2. Select Tomcat v5.0 as the server type (or the correct version of Tomcat for your installation), then click Next.
  3. On the Tomcat server page, enter a server name and specify where Tomcat is installed.
  4. Click Installed JREs, click Add, and then enter the appropriate information for the JDK you plan to use for Tomcat. For example, for Tomcat version 5.0, the JRE name would be jdk1.5 and the JRE home would be the home directory for JDK 1.5.0. When you've entered the information, click OK twice.
  5. Ensure that the newly added JDK is now selected in the JRE field of the Tomcat server window. Note that if you point the server at a JRE rather than a JDK, the JavaServer Page (JSP) files will not properly compile and will not be able to run on the Tomcat server.
  6. Click Finish.
  7. To see the server you have created in the workspace, from the Window menu, select Show view > Other > Server > Servers > OK.

Create the Java bean

This tutorial takes a straightforward inventory-control application and exposes it via a Web services interface. The application itself contains methods to retrieve information, such as name, price, and quantity on hand, as well as methods to buy an item, decrementing the quantity on hand. The skeleton of the application is shown in Listing 1.

Listing 1. The inventory-control application

public class InventoryItem {
               
public String getProductName (String productId) {
...
}
               
public String getProductId (String productName) {
...
}
               
public double getPrice (String productId){
...
}       
               
public boolean getInstock (String productId) {
... 
}     
               
public int getInstockAmt (String productId) {
... 
}  
               
public int buyItem (String productId) {
...   
}  
}

The implementations have been omitted because the process of turning this application into a Web service is unaffected by the means by which it accomplishes its goals. This application might be accessing a database, an XML file, or some other form of storage. This could be any application that you write.

If you want to follow along exactly, however, this tutorial includes a simple version, InventoryItem.java, that you can import into your own project. (See Prerequisites for a link to download this file.) The application doesn't require a database or any particular data files.

Import the class

To build the Web service, you first need to import the class into the project:

  1. Select Window > Open Perspective > Other > Resource.
  2. Click OK.
  3. From the File menu, select Import. A window appears with a list of places from where you can import a resource.
  4. Select File system.
  5. Browse and import the InventoryItem.java class from this tutorial sample code (see Figure 5).

    Figure 5. Import the Java class
    Import the Java class

    Import the Java class

  6. Click Finish.

You should be able to navigate to the WEB-INF/classes folder from the Navigator and see a compiled version of the class. This indicates that your import was successful. If you see any errors, correct them before moving ahead.

Create the Web service

Now you can actually create the Web service:

  1. From the File menu, select New > Other.
  2. Select Web Service, as shown in Figure 6.

    Figure 6. Create the Web service
    Create the Web service

    Create the Web service

  3. Click Next.

Basic properties

Rational Application Developer provides you with the ability to create a Web service from several different resources:

  • Java bean. You can expose any Java bean or simple Java class as a Web service.
  • EJB. You can expose the methods of a Stateless Session Enterprise Java Bean (EJB) as a Web service.
  • DADX. You can expose this file as a Web service. This XML file contains the operations and SQL statements that need to run.
  • URL. You can expose a servlet as a Web service via a URL mapping.

Figure 7 shows the basic settings that you need to enter for the Web service.

Figure 7. Specify the configuration for the Web service
Specify the configuration for the Web service

Specify the configuration for the Web service

For this example, create a Java bean Web service and generate a Java proxy. This is a simple Web service that will allow you to demonstrate the Web service generation features in Rational Application Developer.

Note: You can choose from two different methodologies to Web services implementation: top-down design and bottom-up design.

Select the Test the Web Service option so that a test client will be generated for you so that you can test your Web service. This client demonstrates the code that goes into consuming a Web service and how much of it can be automatically generated with Rational Application Developer. The Monitor the Web Service option is a nice but more advanced feature that allows you to monitor the SOAP messages that your Web service is sending and receiving.

Click Next.

Deployment configuration

Figure 8 shows how to set up the deployment configuration.

Figure 8. Specify the deployment configuration for the Web service
Specify the deployment configuration for the Web service

Specify the deployment configuration for the Web service

For this example, deploy your service using the Apache Axis Web service runtime with Apache Tomcat as your server. I'm using Apache Axis because it's one of the most popular Web service runtimes today and it's open source. Apache Axis is already bundled into your original Rational Application Developer download.

As mentioned in the beginning of this tutorial, you're going to use Apache Tomcat as the deployment container. As an exercise, try deploying the Web service to the container of your choice, such as an IBM WebSphere® or WebLogic server.

Click Next.

WSDL and methods

Figure 9 shows the different options for the Web service, including the name of the WSDL file as well as which methods from the Java file you want to expose through the Web service. You can also define whether this Web service is a document-style Web service or an RPC Web service. See Related topics for a link to more information about these two styles.

Although document-style Web services are in some ways more powerful, they are also more challenging to implement. Therefore, to help you become more comfortable working with Web services, choose RPC style. This style is easier to work with and still covers all the basic concepts of Web services.

Figure 9. Specify the type of Web service and methods to expose
Specify the type of Web service and methods to expose

Specify the type of Web service and methods to expose

For this example, select all the methods. This service is an RPC/Encoded Web service. In the WSDL File field, enter the name InventoryItem.wsdl and click Next.

You'll see the Web service being built, then you're presented with a choice of how you want to test the Web service. Click Next.

In the next window, define the Web service proxy. For now, leave the defaults, then click Next.

Specify the testing environment

Define basic options for how you want to test the Web service and the proxy (see Figure 10) in the Web Service Client Test window. For now, leave the defaults.

Figure 10. Specify the testing configuration for the Web service
Specify the testing configuration for the Web service

Specify the testing configuration for the Web service

In this example, generate a JSP-based test client for the Web service. The JSP-based test suite is simple and intuitive to use. It also demonstrates the value of having a Web service consumer generated as a starting point. Notice that the code underneath is complex and would have been very time-consuming to write by hand. Select all the methods so that the JSP files generated enable testing of all the methods and then click Next.

Publish the Web service

In the Web Service Publication window, you can choose whether you want to publish your Web service to a UDDI directory. You can publish your Web service to an external repository or to an internal UDDI registry that you might be running. However, because Apache Tomcat is the server used in this example and this server does not ship with a UDDI registry, choose not to publish this Web service by clearing the two options in the window and clicking Finish (see Figure 11).

Figure 11. Options for publishing the Web service
Options for publishing the Web service

Options for publishing the Web service

IBM WebSphere Application Server comes with an internal UDDI registry. If you choose to use WebSphere Application Server for this tutorial, you can explore this option. The Related topics section provides a link where you can learn more about the UDDI registry that comes with WebSphere Application Server.

Test your Web service

When Tomcat starts up, it should load the JSP page shown in Figure 12. From this page, you can test your Web service and the various methods within it.

Figure 12. JSP page for testing your Web service
JSP page for testing your Web service

JSP page for testing your Web service

For each method, try entering some values and clicking Invoke. For example, in the productId text file, if you enter SA15 and click Invoke, you should get back Silver Show Saddle, 16 inch. Now, enter this return value in the productName text field, then click Invoke. You should get back SA15.

Verify that the results retrieved are consistent with the InventoryItem.java file implementation of each method. All the possible inputs and outputs are defined in the implementation of each of these methods in the Java source file.

Now that you've created and tested the Web service, let's look at the various parts of the service you've created.

Web service dissected

A look at the WSDL

In the Navigator, expand the Web Content folder, then the WSDL folder. Double-click the InventoryItem.wsdl file. This WSDL file was generated automatically as part of the Web service creation process.

In Rational Application Developer, you can see both the WSDL source and a graphical representation of the WSDL. Notice that the Source view is rather complicated to read. WSDL is just another XML file, but trying to decipher the XML manually can be tedious. To make things easier, switch to the Graph view by clicking the Graph tab.

This WSDL represents one service and exposes several methods for that service. Expand the different sections in the graph view to see how the Web service is connected (see Figure 13).

Figure 13. Graph view of the WSDL file
Graph view of the WSDL file

Graph view of the WSDL file

As you can see, the WSDL file is fairly complex, and it's probably a good thing that the file is generated automatically. But you learn how to use Rational Application Developer to create a WSDL file later in the tutorial.

Browse through the other folders in this project, and pay particular attention to the deployment descriptors for this Web service. This service is very basic, and the simple InventoryItem.java class (which is nothing more then a Plain Old Java Object, or POJO) is exposed as a Web service with just a few clicks. The next section, Consume an external Web service, provides an example of consuming an external Web service, which is a bit more complex.

Now, let's look at the client or consumer for the Web service.

The Web services consumer

In the Navigator, expand MyFirstWebServicesProjectClient. Expand the JavaSource folder. To consume a simple POJO, the system has created five Java classes, as shown in Figure 14.

Figure 14. Java files for the Web services consumer
Java files for the Web services consumer

Java files for the Web services consumer

You see code that helps locate the Web service, that serves as the proxy to the Web service, and that provides the binding between the locator and the proxy. You also see a simple bean that you can use to work with the Web service.

The Web services test client

In addition to the consumer code, you've also created a set of JSP files that allow you to test the Web service. You saw the basic JSP files in Figure 12. These files allow you to invoke each method exposed in the WSDL. You can send basic inputs and see the results from the Web service invocation.

Consider exploring the code in the Result.jsp file. This is the file that actually makes the calls to the Web services consumer code, which in turn invokes the Web service.

How does this work in the real world?

So, how does this all work? In this example, you've seen how you can easily consume a Web service. You end up with the consumer code and some sort of test client. For your real-world application, all you need to do is cut and paste the code from the Result.jsp file into a Java class. Call this class <<WebServiceName>>ConsumerDelegate.java. The class can be a POJO, in most cases. Let your code call this delegate class to interface with the Web service.

You're done. You can now use the Web service that you've consumed in your application.

Consume an external Web service

Create a Web services client

As a more concrete, real-world example, let's consume a Web service from the xmethods.net site. You can use any other Web service: Just follow the steps identified here.

For this example, choose the E-mail Address Verifier Web service listed on the site. The URL to the WSDL -- http://ws.cdyne.com/emailverify/Emailvernotestemail.asmx?wsdl -- is all you need.

  1. Open Rational Application Developer.
  2. Select File > New > Other.
  3. Click Web Service Client, as shown in Figure 15.

    Figure 15. Launch the Web Service Client Wizard
    Launch the Web Service Client Wizard

    Launch the Web Service Client Wizard

  4. Click Next.

Import a WSDL

Cut and paste the URL to the WSDL for the xmethods.net E-mail Address Verifier Web service, as shown in Figure 16, into the text box.

Figure 16. Import the WSDL for the Web service
Import the WSDL for the Web service

Import the WSDL for the Web service

Follow the steps outlined in Create a Web services project for choosing a server until you come to the Web Service Client Test window.

Web service client test

In the previous example, you chose to generate JSP files to test your Web service. In this example, select Web Services Explorer from the Test facility drop-down list, as shown in Figure 17. Doing so allows you to see a different type of Web service test client. The underlying proxies and router code will be similar to what you've been working with, but the client code will be different.

Figure 17. Select Web Services Explorer as the test facility
Select Web Services Explorer as the test facility

Select Web Services Explorer as the test facility

For this example, you're choosing only the last three methods, which are the only methods available when the test client is generated. The main reason for excluding the getEndPoint and setEndPoint methods is that those methods are more generic Web service-related methods rather than business logic methods specific to the E-mail Address Verifier Web Service.

Click Finish.

Test the new Web service client

Figure 18 shows the new Web service client that was generated. In this example, an e-mail address was entered in the Input field and Go was clicked. Information regarding the mail server is displayed in the status sections toward the bottom of the window.

Test the generated Web service and browse through the source tree for this client, as well.

Figure 18. The Web service test client
The Web service test client

The Web service test client

Create a WSDL file and a Web service

Create a WSDL file

In most cases, it is easier to build a Web service from Java code -- whether it is an EJB or a simple Java class. Build your Web service in the order outlined in this section because:

  • The code that implements this Web service does not exist
  • You need to publish your interface to the Web service so that others can start writing the consumer
  • You need to be more XML complaint

In this section, you learn how to build your WSDL file using Rational Application Developer. When you have a WSDL, you can convert it to a Web service using the methods demonstrated earlier in this tutorial.

To create a WSDL file in Rational Application Developer, click File > New > Other. In the Select a wizard window, select WSDL as shown in Figure 19. You're going to build a simple WSDL file called CurrencyConvertor.wsdl that allows you to convert one currency to another.

Figure 19. Choose the wizard to create a WSDL file
Choose the wizard to create a WSDL file

Choose the wizard to create a WSDL file

Open the WSDL file

From the Navigator, expand the WebContent folder, then open the WSDL file as shown in Figure 20.

Figure 20. Open CurrencyConvertor.wsdl
Open CurrencyConvertor.wsdl

Open CurrencyConvertor.wsdl

Build the WSDL file

This is probably the most complex step. You need to define the methods, along with the inputs and outputs for this WSDL file. For this example, define a simple Web service operation called convertCurrency. This operation takes in three parameters: fromCountry, toCountry, and convertAmount. The first two parameters are strings; the last parameter is a float.

Build a port

First, build a port using the Port Types Panel of the WSDL file. A port defines the end-point for a service -- that is, the end-point at which the service will be available.

  1. Right-click in the panel to create a new port.
  2. Name the port currencyConvertorPort.
  3. Right-click currencyConvertorPort and select Add Operation to add an operation called currencyConvert.

Figure 21 shows how your WSDL file looks after these operations. Note that samples messages were created automatically.

Figure 21. Build a port in the WSDL file
Build a port in the WSDL file

Build a port in the WSDL file

Customize the message

  1. Right-click the currencyConvertRequest message and select Add Part. Name the part fromCountry.
  2. Repeat this step for toCountry and convertAmount. Note that by default, all parts are given a string type.
  3. Right-click the convertAmount type and select Set Type.
  4. In the Specify Type window (see Figure 22), select Select an existing type, then select xsd:float.

    Figure 22. Converting a type
    Converting a type

    Converting a type

  5. Click Finish.
  6. Add a part to the currencyConvertResponse message. Call this type convertedAmount and convert it to a float. Figure 23 shows the final messages section that you just created.

    Figure 23. Messages section of the WSDL file
    Messages section of the WSDL file

    Messages section of the WSDL file

Now you have to build the rest of the WSDL file.

Set the bindings

To bind to the port type that you just created:

  1. Right-click anywhere in the Bindings panel of the WSDL file and select Set Port Type.
  2. In the Specify Port Type window (see Figure 24), select Select an existing port type, select the currencyConvertor port you created, then click Finish.

    Figure 24. Binding the port
    Binding the port type

    Binding the port type

  3. You're almost done. In the Navigator, right-click anywhere in the WSDL file and select Validate. The WSDL file should validate correctly. If the validation fails, an error message appears indicating what failed.

Generate the Web service

To generate the Web service from the WSDL file you created, right-click anywhere in the WSDL file (see Figure 13) and select Web Services > Generate Java bean skeleton. Generate a Web service of the type Skeleton Java Bean Web Service. This step generates a skeleton class in which you can implement the actual Currency Conversion option. You can also create a client to consume your new Web service.

Summary

Summary

This tutorial described the basic technologies that make up a Web service. It also showed how you can easily expose and consume Web services using Rational Application Developer. Simple wizards guide you through exposing any Java class as a Web service. Using the Web Services Client Wizard, you can quickly consume the Web service you just exposed or another Web service from the Internet. Not only will you get all the Web service consumer code, but you will also get a rich test client that you can use to test the Web service. The tutorial ended by showing you how to use Rational Application Developer to build a WSDL file that can be converted into a Web service. This operation gives you the skeleton classes that you need to implement for the Web service as well as a test client to test the Web service after you have implemented it.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=151091
ArticleTitle=Consuming Web services
publish-date=04132005