When invoking a Web service which has complex requirements, you to make sure your Web service client can handle it. Saminda helps you to do this in just 3 simple steps. Saminda is a Senior Software Engineer at WSO2. Date: Fri, 2nd Oct, 2009 Level: Introductory Reads: 69094 Discuss this article on Stack Overflow

Saminda Wijeratne Senior Software Engineer WSO2 Inc

How to Create a Web Service Client in 3 Steps

With the increasing complexity of using Web services, the method of invoking them has also become increasingly complex. Users are required to learn a lot more than how to pass parameters to a specific url to get results. Learning the required domain is a waste of time if it is only a one time scenario or you don't want to know about Web service specifications at all.

Introduction

Writing a client manually is a time consuming process when having a very complex invocation procedure. From passing parameters to transportation methods and to applying security, the client has to be prepared before making the house call. Although these necessities are described in the WSDL file, understanding a long and complex WSDL file and converting the requirements into code can take hours specially if you lack the relevant knowledge. This procedure can be automated using the Apache Axis2 code generation libraries. This functionality now has been included as an Eclipse tool (one of the most popular open source IDEs in the world) so that within few seconds you can generate the client stubs according to the WSDL.

 The following are the 3 steps,

1. Setting up the environment
2. Creating Client Stubs
3. Use the Generated Stubs to Invoke the Web service

Prerequisites

Note: Visit the resources section of this tutorial to find out from where to download the prerequisites or click the above links.

Step 1 - Setting up the environment - Adding a WSAS Server to eclipse

Open the Servers View in Eclipse by Window -> Show View -> Other... and select "Servers"

or just switch to "Java EE" perspective which will have "Server" view by default.

After opening the "Servers" view, if it does not contain a WSAS Server, right click on the view item content area and select New -> Server

Select "WSO2 WSAS 3.1" and click "Next"

Specify the WSAS binary distribution location and click "Finish".

You will see a WSAS server being added. You don't need to start the server to do this tutorial. If you want to start the server click on the WSAS server in the list in Servers view and click the Start button of the view in upper right hand side.

Step 2 - Create Client Stubs

As a first step, you need to get your hands on to the WSDL of the Web service. If it not hosted online, import the wsdl file into the eclipse workspace. In this tutorial, we will be using the WSDL at http://www50.brinkster.com/vbfacileinpt/np.asmx?WSDL. You may use any other valid WSDL.

(At this point if you have imported the WSDL file to the workspace, select the WSDL file from the Project Explorer)

Go to  File -> New -> Other... (or Ctrl + N)

Select "Web Service Client" and click "Next"

Specify the WSDL file in the "Service Definition" text box if it is not already there.

Click the "Server" link and select "WSO2 WSAS Server 3.1" among existing servers or server types.

Select "WSO2 Web Services Application Server".

Click "OK"

Click "Next"

In this page, you can customize how the Client Stubs are generated. For now, lets leave the settings as it is. Click "Finish"

The related stubs will be generated in the given Eclipse project.

Step 3 - Use the Generate Stubs to Invoke the Web Service

Inside an existing class or in a new class we'll add the java code to invoke the Web service now. As long as the stub classes are accessible you can use any class in any project in the workspace. I'm creating a new class "PrimeNumberViewer" inside the stub generated project itself ("WebServiceProject") adding the following method.

    public static void main(String[] args) throws AxisFault {
        Scanner in = new Scanner(System.in);
        String input;
        String prompt = "\nEnter Number (q - quit):";

        PrimeNumbersStub primeNumbersStub = new PrimeNumbersStub();
        GetPrimeNumbers primeNumbersParameter=new GetPrimeNumbers();
         System.out.print(prompt);
        while (!(input=in.nextLine()).equalsIgnoreCase("q")){
            try{
                int maxNumber = Integer.parseInt(input);
                primeNumbersParameter.setMax(maxNumber);
                GetPrimeNumbersResponse primeNumbers = primeNumbersStub.getPrimeNumbers(primeNumbersParameter);
                System.out.println("   Prime Numbers: "+primeNumbers.getGetPrimeNumbersResult());
            }catch (Exception e){
                System.out.println("ERROR: "+e.getMessage());
            }
            System.out.print(prompt);
        }
     }

 Only the bolded text/commands in the above script are related to the web service invocation. Rest are just there to create a fancy program.

Now just execute the above method. In my case I'll just execute it as a java class.

Explaining the use of client stubs

• To invoke the client service, first you need to create an object from "<ServiceName>Stub" class. In my case, this class is "PrimeNumbersStub" and the object created is primeNumbersStub.
   

• It is from invoking methods in this object (primeNumbersStub) you will invoke the Web service. (The Web service port names become the names methods in this object)

  eg: primeNumbersStub.getPrimeNumbers(....)

• If the Web service requires some parameters to be passed to it, then you will need to pass a parameter to this method depicting the Web service port type.

  eg: primeNumbersStub.getPrimeNumbers(primeNumbersParameter);
      here the primeNumbersParameter is an object which keeps the required parameters. Normally it would contain getter/setter methods for the parameters (primeNumbersParameter.setMax(maxNumber);)

• The return object of the service invocation method would contain the response received from the server.  In this example, the response object is primeNumbers of the type GetPrimeNumbersResponse. There will be a getter to retrieve the expected result/value of the Web service.

  eg: primeNumbers.getGetPrimeNumbersResult()

Resources

1. The Java class which uses the generated client stubs to invoke the service can be found here.
2. To download WSO2 WSAS please visit https://wso2.org/projects/wsas/java
3. To download WSO2 WSAS Tools please visit http://wso2.org/projects/tools or use the update site URL http://tools.wso2.org/eclipse

Summary

It is easier to create a Web service rather than finding issues related to it. But these tools help you in debugging your Web service just like debugging your Java application in Eclipse.

Click here to find out how to create a web service 

Author

Saminda Wijeratne, Senior Software Engineer, WSO2, samindaw@wso2.com