Working with JAX-WS Web Services: Building a Web Service Client

In the previous article, we have learned how to create a simple web service. In this article, we discuss how to access this web service and use it.

To access the web service, we need to know the service artifacts and it’s location.

The service artifacts are described in a document called WSDL(Web Service Description Language) file. The WSDL file contains information pertaining to the service, such as the types, operations of the service, binding and port type information. More details on this and other technologies involved will be discussed in next article. But, some details on WSDL are discussed below.

Why do we need a WSDL?

Because, it is with this the web service provider and the consumer will come to an understanding and agreement on what information should be exchanged and what are the data types, protocols and semantics of the web service. This is the reason we call the WSDL as an interface between the service provider and service consumer.

How does it look like?

A WSDL file is nothing but an XML document describing the web service operations, data types and it’s location. A sample WSDL file generated for our Simple Web Service is given  below.

<?xml version="1.0" encoding="UTF-8"?>
<!--Published by JAX-WS RI at http://jax-ws.dev.java.net. RI's version is JAX-WS RI 2.2.5-b01 . -->
<!-- Generated by JAX-WS RI at http://jax-ws.dev.java.net. RI's version is JAX-WS RI 2.2.5-b01 . -->
<definitions targetNamespace="http://sample.jaxws.ws.blog.accrd.com/"
    name="SimpleWebServiceService">
    <types>
        <xs:element name="sayHello" type="tns:sayHello" />
        <xs:element name="sayHelloResponse" type="tns:sayHelloResponse" />
        <xs:complexType name="sayHello">
            <xs:sequence>
                <xs:element name="arg0" type="xs:string" minOccurs="0" />
            </xs:sequence>
        </xs:complexType>
        <xs:complexType name="sayHelloResponse">
            <xs:sequence>
                <xs:element name="return" type="xs:string" minOccurs="0" />
            </xs:sequence>
        </xs:complexType>
    </types>
    <message name="sayHello">
        <part name="parameters" element="tns:sayHello" />
    </message>
    <message name="sayHelloResponse">
        <part name="parameters" element="tns:sayHelloResponse" />
    </message>
    <portType name="SimpleWebService">
        <operation name="sayHello">
            <input
                wsam:Action="http://sample.jaxws.ws.blog.accrd.com/SimpleWebService/sayHelloRequest"
                message="tns:sayHello" />
            <output
                wsam:Action="http://sample.jaxws.ws.blog.accrd.com/SimpleWebService/sayHelloResponse"
                message="tns:sayHelloResponse" />
        </operation>
    </portType>
    <binding name="SimpleWebServicePortBinding" type="tns:SimpleWebService">
        <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
            style="document" />
        <operation name="sayHello">
            <soap:operation soapAction="" />
            <input>
                <soap:body use="literal" />
            </input>
            <output>
                <soap:body use="literal" />
            </output>
        </operation>
    </binding>
    <service name="SimpleWebServiceService">
        <port name="SimpleWebServicePort" binding="tns:SimpleWebServicePortBinding">
            <soap:address
                location="http://localhost:8080/SimpleWebService/SimpleWebService" />
        </port>
    </service>
</definitions>

Who creates the WSDL?

The service provider creates the WSDL and publishes it. In the service that we developed in previous article, we don’t manually create or publish the WSDL, instead that is created and published by the JAX-WS run time environment.

What does the client(or web service consumer) do with WSDL?

By reading the WSDL, the client will know what are the operations of the web service, what are the data types, what are the protocols and etc. Not just knowing these details, the client can now create a client which is compatible with published WSDL and start accessing it.

How do we build the client?

There are different ways in which we can access a web service.

If you want to quickly test the web service, there is a famous tool called SoapUI. SoapUI is an open source web service testing tool. It’s easy to use. You can download it from here and try.

If you want to develop one on your own, then let’s start building a Java web service client, that can access the simple service that we created in previous article.

we need to follow the below steps to build the web service client.

Step 1: Generate the required web service artifacts, such as data types, port types and web service stub classes on client side using the WSDL url.

To generate these artifacts in Java, we need to invoke a tool called wsimport which comes with the JDK 6 and later.

Note: If you are planning to create web service client in other programming languages(.NET, C++, PHP and etc) the process is different and you need to browse the appropriate language documentation.

The syntax for executing wsimport tool is given below

wsimport [options] <WSDL_URI>

The mostly used options are listed below:

-s : indicate the directory where the generated java source files from the WSDL need to be stored.

-p : the package name with which the source files need  to be gneerated

-d : the directory, where  the compiled class files need to be stored.

-b <path> : used, when we need to specify any additional XSD files along with the WSDL_URI.

For our exmaple, we need to execute the following command, assuming that the web service is deployed onto a local tomcat. If required, please change or create the URI part and the directory paths according to your environment.

wsimport -s src -d bin -p com.accrd.blog.ws.jaxws.sample.client http://localhost:8080/SimpleWebService/SimpleWebService?wsdl

The above command would generate the required java artifacts under specified package in folder ‘src’ depending on the elements in the WSDL. The compiled  version of the generated artifacts are stored into folder ‘bin’.

Step 2: Now create a java class, which would use the artifacts generated and invoke the web service. The code for this is given below. All the important lines are documented for better understanding.

package com.accrd.blog.ws.jaxws.sample.client;
 
public class SimpleWSClient {
    /**
     * This is a Service object providing the client view or the factory for proxies of the Web service from which we generated this.
     * This is used to get the proxy(stub) or port of the web service created.
     */
    SimpleWebServiceService service = null ;
 
    public SimpleWSClient(){
        /**
         * Instantiate the web service client object.
         */
        service = new SimpleWebServiceService() ;
    }
 
    public void testService (String name){
        /*
         * Get the web service proxy or port from the web service client factory. This port is nothing but the stub for the web service created.
         * It facilitates us to invoke the web service methods remotely.
         */
        SimpleWebService servicePort = service.getSimpleWebServicePort() ;
 
        /*
         * Invoke the web service operation using the port or stub or proxy
         */
        String helloMessage = servicePort.sayHello(name) ;
 
        System.out.println("Response from web service call : "+helloMessage) ;
    }
 
    public static void main (String arags[]){
        SimpleWSClient client = new SimpleWSClient() ;
        client.testService("Accordess") ;
    }
 
}

Step 3: Now compile and run this class as a stand-alone Java application from a console prompt or from your favorite IDE. The response from the web service call is printed.

>java com.accrd.blog.ws.jaxws.sample.client.SimpleWSClient
Response from web service call : Hello, Accordess!

The Eclipse Indigo project for this sample web service client can be downloaded from here

This one and the previous article has covered how to build a simple web service and access it using a web service client. This has helped us to understand how a web service works with a quick example in hand.

Our next article in this series, will discuss on web services history, evolution and the technologies involved.

From http://www.accordess.com/wpblog/2012/01/02/working-with-jax-ws-web-services-building-a-web-service-client/