Creating a Client and Invoking the Web Service

Following web service registration and stub generation, developers can access the web service by utilizing the classes produced by the WSDL-to-Java tool. These include the following:

For each service element in the WSDL file, an interface class (suffixed with Service) and an implementing service locator class (suffixed with ServiceLocator) are generated. The ServiceLocator class creates an instance of the stub class described next.
For each portType element in the WSDL file, an interface class (suffixed with _PortType) and an implementing web service stub class (suffixed with SoapBindingStub) are generated. The SoapBindingStub (instantiated by the ServiceLocator) provides access to the external web service via invocation of its appropriate methods.
A Java class is also generated for each schema element type in the WSDL file, that represents a parameter or a return type, for each web service.

The following example describes how a very simple web service can be invoked from Java code.

The following listing is a WSDL extract of a web service which allows the client to query the price of a shoe by providing its size.

Figure 1. WSDL for a sample web service

<wsdl:types>
    <schema targetNamespace="http://DefaultNamespace"
      xmlns="http://www.w3.org/2001/XMLSchema"
      xmlns:impl="http://DefaultNamespace"
      xmlns:intf="http://DefaultNamespace"
      xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema">

     <element name="askShoePriceResponse">
      <complexType>
       <sequence/>
      </complexType>
     </element>

     <element name="askShoePrice">
      <complexType>
       <sequence>
        <element name="myShoeSize" type="xsd:int"/>
        <element name="shoePrice" nillable="true"
          type="impl:ShoePrice"/>
       </sequence>
      </complexType>
     </element>

     <complexType name="ShoePrice">
      <sequence>
       <element name="priceInCents" type="xsd:int"/>
      </sequence>
     </complexType>
    </schema>
   </wsdl:types>


     <wsdl:message name="askShoePriceResponse">
        <wsdl:part element="impl:askShoePriceResponse"
          name="parameters"/>
     </wsdl:message>

     <wsdl:message name="askShoePriceRequest">
        <wsdl:part element="impl:askShoePrice"
          name="parameters"/>
     </wsdl:message>

     <wsdl:portType name="ShoeShop">
        <wsdl:operation name="askShoePrice">
           <wsdl:input message="impl:askShoePriceRequest"
             name="askShoePriceRequest"/>
           <wsdl:output message="impl:askShoePriceResponse"
             name="askShoePriceResponse"/>
        </wsdl:operation>
     </wsdl:portType>

     <wsdl:binding name="yourhost9082SoapBinding"
       type="impl:ShoeShop">
        <wsdlsoap:binding style="document"
          transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="askShoePrice">
           <wsdlsoap:operation soapAction=""/>
           <wsdl:input name="askShoePriceRequest">
              <wsdlsoap:body use="literal"/>
           </wsdl:input>
           <wsdl:output name="askShoePriceResponse">
              <wsdlsoap:body use="literal"/>
           </wsdl:output>
        </wsdl:operation>
     </wsdl:binding>

     <wsdl:service name="ShoeShopService">
        <wsdl:port binding="impl:yourhost9082SoapBinding"
          name="yourhost9082">
           <wsdlsoap:address location="http://yourhost:9082"/>
        </wsdl:port>
     </wsdl:service>

This WSDL will result in a number of Java classes being generated.

The following generated Java interface represents the client side of the web service. This interface is implemented by the generated ShoeShopSoapBindingStub, which the developer will use to invoke the web service.

Figure 2. Java client stub interface for the web service

public interface ShoeShop_PortType extends java.rmi.Remote {
      public ShoePrice askShoePrice(int myShoeSize)
        throws java.rmi.RemoteException;
  }

Instances of the ShoeShopSoapBindingStub class are created by the generated ShoeShopServiceLocator class.

The following code shows how this web service can be invoked from Java code:

Figure 3. Invoking the web service from Java code

// The service locator gets instances of the web service.
    final ShoeShopServiceLocator serviceLocator =
      new ShoeShopServiceLocator();

    // get an instance of client stub by casting from interface:
    final ShoeShopSoapBindingStub shoeShop =
      (ShoeShopSoapBindingStub) serviceLocator.getShoeshop();

    // this is our in parameter:
    int myShoeSize = 8;

    // ShoePrice is a generated type wrapper:
    final ShoePrice shoePrice = new ShoePrice();

    // invoke the web service:
    shoePrice =
      shoeShop.askShoePrice( myShoeSize );

    // examine the value we got back:
    final int priceInCents = shoePrice.getPriceInCents();

This is a very simple example to illustrate how web services can be accessed by IBM Cúram Social Program Management applications. For working with more complex web services the developer should consult the web service WSDL, and refer to the documentation on the Apache Axis website.