Client-Side Programming

Accessing a Web service from the client can be (almost) as easy. In the simplest case of wanting to access an RPC SOAP service, let's take a closer look at the example from Chapter 3, shown in Listing 4.3.

Listing 4.3 InventoryCheckClient.java

package ch3.ex2;

import org.apache.axis.client.ServiceClient;

/*
 * Inventory check web service client
 */
public class InventoryCheckClient {
    /**
     * Service URL
     */
    String url;

    /**
     * Point a client at a given service URL
     */
    public InventoryCheckClient(String url) {
        this.url = url;
    }

    /**
     * Invoke the inventory check web service
     */
    public boolean doCheck(String sku, int quantity) throws Exception {
        ServiceClient call = new ServiceClient(url);
        Object[] params = new Object[]{  sku, new Integer(quantity), } ;
        Boolean result = (Boolean)call.invoke("", "doCheck", params);
        return result.booleanValue();
    }

}

As shown here, a ServiceClient object is needed. This object is used as the portal through which the client application connects with the Web service. The constructor takes the URL of the target SOAP server. Once the ServiceClient object knows where to find the service, all that is left is to invoke the Web service itself. Notice that the client.invoke() method call takes three parameters: the value of the HTTP SOAPAction header, which in this call is just an empty string; the name of the Web service's method to invoke (doCheck); and an array containing the Java objects representing the parameters for the method. The return value of the invoke() method is a Java object of type Object, so it will need to be cast to the proper return type before it is used.

Sometimes each parameter passed to the method needs to have a specific name associated with it. For example, some SOAP servers will use the parameter names in the method-matching algorithm. In these cases, a slight change to the way invoke() is called is required:

Boolean result = (Boolean) call.invoke(
            "",
            "doCheck",
            new Object[] {  new RPCParam("skuName", sku),
                           new RPCParam("quantity", new Integer(quantity))} );

Notice that now instead of passing in an array of Java objects, an array of RPCParams is passed in, where each RPCParam consists of the name of the parameter (skuName and quantity in this example) and the value of the parameter (sku and quantity).

When talking with an Axis server or any other SOAP server that does explicit typing of the XML stream (this means the datatype of the parameters and return value of the RPC call is placed in the SOAP message), the Axis client can use that typing information to know how to deserialize the return value. However, some SOAP servers do not do this; in this instance, they are expecting the client to know the datatype through some other means (perhaps WSDL). When this occurs, it becomes the responsibility of the client application to tell the Axis client what type the return value is—which just requires a couple lines of code. The complete client application looks like Listing 4.4

Listing 4.4 InventoryCheckClient.java

package ch3.ex2;

import org.apache.axis.client.ServiceClient;

/*
 * Inventory check web service client
 */
public class InventoryCheckClient
{
    /**
     * Service URL
     */
    private String url;

    /**
     * Point a client at a given service URL
     */
    public InventoryCheckClient(String targetUrl)
    {
        url = targetUrl;
    }

    /**
     * Invoke the inventory check web service
     */
    public boolean doCheck(String sku, int quantity) throws Exception
    {
        ServiceClient call = new ServiceClient(url);
        ServiceDecription sd = new ServiceDescription("return", true);
        sd.setOutputType(new QName(Constants.URI_2001_SCHEMA_XSD, "boolean"));
        call.setServiceDescription(sd);
        Boolean result = (Boolean) call.invoke(
            "",
            "doCheck",
            new Object[] {  sku, new Integer(quantity) }  );
        return result.booleanValue();
    }
}

In this example we've added the definition of a ServiceDescription object. This object is used by the client to notify the Axis client of various pieces of metadata about the Web service being invoked. In this instance we're defining the OutputType (return type) of the method as a boolean using the 2001 W3C XML Schema definition. The ServiceDescription constructor takes two parameters: a name assigned to this object (return parameter names aren't used very much as they are basically ignored) and an indication of whether this service is an RPC service (true indicates that it is). The only other code change associates this ServiceDescription object with the ServiceClient, and this is done through the setServiceDescription() method call.