WAS502 Web Services Part 1

WebSphere 5.02 Web Services

Part 1: Consuming an existing Web Services using Eclipse and WAS 5.02 Engine

Introduction

WAS 5.02 fixpack includes a brand new Web Services engine that supports JSR101 (JAX-RPC) programming model and JSR109 (J2EE Web Services) deployment model. The development process is quite different from that of using the original Apache SOAP based engine that is shipped with WAS 5.0. This is Part 1 of a series of articles that walks you through the new programming model, discusses some key FAQs and do's and don'ts. They focus on WAS 5.02 specifics from a developer's perspective. In the end, I hope that you'd find accessing and developing Web Services on WAS502 isn't exactly rocket-science and the process requires little knowledge on XML and SOAP itself.

Part 1 goes through how to use WAS502 engine to consume an existing Web Service, using Amazon web service as an example
Part 2 discusses how to expose your Java methods as web services and develops different clients for the exposed Web Services (.Net, PHP, Perl, ASP.Net)
Part 3 reverses the scenario and start from developing a .Net-based web service and develop a WAS 5.02 client that accesses it
Part 4 illustrates how to take advantage of WSAD 5.1 specific web services features

Pre-requisites

Basic Java / J2EE web application development experience
Basic understanding of Web Services concepts (SOAP, WSDL)
Eclipse 2.x installed (e.g. c:\eclipse)
WebSphere AppServer 5.02 installed (e.g. c:\WebSphere\AppServer)

Overiew of Steps

Create standalone Java Project in Eclipse
Use WSDL2Java to generate Java artifacts from WSDL file (from Amazon)
Setup JRE and build path
Create and code MyAmazonClient.java
Test with live external server http://soap.amazon.com

Step 1 - Create standalone Java Project

File, New Project, Java Project, Project Name: MyAmazonClient and accept all defaults

Step 2 - Use WSDL2Java to generate Java artifacts from WSDL file (from Amazon)

open a command prompt and change directory to your Eclipse workspace location (e.g. c:\eclipse\MyAmazonWorkspace)
C:\WebSphere\AppServer\bin\wsdl2java -role client -container none -v http://soap.amazon.com/schemas3/AmazonWebServices.wsdl

this command performs the following:

downloads the web service definition file from the Amazon production site from the Internet (if you don't have direct internet connection, you can get the WSDL file using your browser and place it into the file system first and replace the "-t http://..." with the filename)
parses the WSDL file to generate Java classes that maps to the WSDL's complexTypes (for development)
generates the WAS502 specific serializers/deserializers/helper classes (for runtime)
produces a verbose report on what has been generated (-v)

Step 3 - Setup JRE and Java Build Path in Eclipse

WAS502 runs on the IBM JDK 1.3.1. To simplify things, we use the same WebSphere JDK instead of the default JDK 1.4 that comes with Eclipse. To switch the default JDK in Eclipse, go to Windows, Preferences and add the WAS502 JDK as shown:

jdk

You will need to include a few WAS502 jar files in your classpath to compile the generated code and execute your main class

Right-click on your Java Project, select Properties...
Under Java Build Path, select "Add External Jars..." to include the following WebSphere jar files in your build path (j2ee.jar, qname.jar, webservices.jar and wsdl4j.jar)

Java Build Path

Click OK

Right-click on the Java Project again and select Refresh. Eclipse will recognize the new Java classes generated by WSDL2Java and compile them. If you have no compile errors, you are half-way there now. 2 more steps to go.

Step 4 - Develop your main class (MyAmazonClient)

Writing the code to access the Web Service is actually very simple. You don't need to understand any underlying generated code at all. Just invoke it as if it is a regular Java method call and the WAS502 runtime will perform all the magic for you. It follows the pattern below:

Create an instance of a generated "XXXServiceLocator" class (in our example, it is the AmazonSearchServiceLocator class)
Create an instance of the generated "XXXPort" class (in our example, it is the AmazonSearchPort class)
Construct your Request object using regular java methods
Invoke the web service method (just like a regular java method call) on the AmazonSearchPort object. It returns a Response object that you get query.

To create the tester class in Eclipse,

Create a new Java package (e.g. com.ibm.test)
Create a new Java class (e.g. MyAmazonClient)

The example code is shown below:

package com.ibm.test;

import com.amazon.soap.*;

public class MyAmazonClient {

    public static void main(String[] args) {

        try {

            AmazonSearchServiceLocator locator = new AmazonSearchServiceLocator();    // ServiceLocator
            AmazonSearchPort service = locator.getAmazonSearchPort();                   // Port class
            KeywordRequest aKeywordRequest = new KeywordRequest();                      // construct request
            aKeywordRequest.setMode("books");
            aKeywordRequest.setType("lite");
            aKeywordRequest.setKeyword("Finding Nemo");
            ProductInfo aProductInfo = service.keywordSearchRequest(aKeywordRequest);   // invoke the service

            System.out.println("Total number of matches = " + aProductInfo.getTotalResults() + "\n");

            Details details[] = aProductInfo.getDetails();

            for (int i = 0; i < details.length; i++) {
                Details aDetail = details[i];
                System.out.println(i + ": " + aDetail.getProductName() + " " + aDetail.getOurPrice());
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Step 5: Execute your code!

Select on your Tester class (e.g. MyAmazonClient). On the menu bar, select "Run", "Run As...", Java Application
If everything goes well and you have internet connections, the output would look like:

output

Additional discussion points:

The AmazonSearchServiceLocatorclass and AmazonSearchPort class (generated by WSDL2Java) provide a simple interface to invoke the web service. The code in their constructors prepares the runtime for the subsequent method calls and they are quite resource intensive. So, as a best practice, you should consider caching and re-using these objects, instead of creating a new instance every time. They are thread-safe.

As you can see, there is no XML coding at all. Java programmers does not have to learn XML APIs or SOAP interface. Just import the generated classes and trigger the functions as if they are local to the JVM. Everything else is transparent to you.

If things don't work as expected, one very common debugging technique is to use a TCP Monitor to inspect the SOAP message going back and forth. WAS 502 comes with the tcpmon tool. To set it up inside Eclipse... select "Run", "External Tools", "External Tools..."

tcpmon

Click on "Run" to start the TCP Monitor. It will accept TCP requests on localhost:81 and forward it to the target server (soap.amazon.com:80) and displays the actual content of the SOAP request/response. You will need to go into the AmazonSearchServiceLocator class and change the URL from soap.amazon.com to localhost:81

The output should look like this:

tcpmon

tcpmon

I hope that you'd find this tutorial useful. Invoking a Web Service using WAS502 is fairly simple and requires very little knowledge on XML and SOAP itself. You can use WSAD 4.x or WSAD 5.0 instead of Eclipse. If you are using WSAD 5.1, there are some wizards which make thing even easier (without invoking WSDL2Java outside of the IDE).

Courtesy of www.websphere-world.com
Billy Lo