Creating a Web Service Client

Unlike developing a web service provider, creating a web service client application always starts with an existing WSDL file. This process is similar to the process you use to build a service from an existing WSDL file. The WSDL file that the client consumes already contains the WS-* policy assertions (and, in some cases, any value-added WSIT policy assertions that augment Sun's implementation, but can safely be ignored by other implementations). Most of the policy assertions are defined in the WS-* specifications. Sun's implementation processes these standard policy assertions.

The policy assertions describe any requirements from the server as well as any optional features the client may use. The WSIT build tools and run-time environment detect the WSDL's policy assertions and configure themselves appropriately, if possible. If an unsupported assertion is found, an error message describing the problem will be displayed.

Typically, you retrieve the WSDL directly from a web service provider using the wsimport tool. The wsimport tool then generates the corresponding Java source code for the interface described by the WSDL. The Java compiler, javac, is then called to compile the source into class files. The programming code uses the generated classes to access the web service.

The following sections describe how to create a web service client:

Creating a Client from Java

To create a client from Java, you must create the following files:

The build.xml and build.properties files are standard in any Ant build environment. Examples of these files are provided in the wsit-enabled-fromjava sample directory.

Client Java File (fromjava)

The client Java file defines the functionality of the web service client. The following code shows the AddNumbersClient.java file that is provided in the sample.

package fromjava.client;

import com.sun.xml.ws.Closeable;
import java.rmi.RemoteException;

public class AddNumbersClient {
  public static void main (String[] args) {
    AddNumbersImpl port = null;
    try {
      port = new 
AddNumbersImplService().getAddNumbersImplPort();
      int number1 = 10;
      int number2 = 20;
      System.out.printf ("Invoking addNumbers(%d, %d)\n",
          number1, number2);
      int result = port.addNumbers (number1, number2);
      System.out.printf (
          "The result of adding %d and %d is %d.\n\n", 
          number1, number2, result);

      number1 = -10;
      System.out.printf ("Invoking addNumbers(%d, %d)\n",
          number1, number2);
      result = port.addNumbers (number1, number2);
      System.out.printf (
          "The result of adding %d and %d is %d.\n", 
          number1, number2, result);
    } catch (AddNumbersException_Exception ex) {
      System.out.printf (
          "Caught AddNumbersException_Exception: %s\n", 
          ex.getFaultInfo ().getDetail ());
    } finally {
      ((Closeable)port).close();
    }
  }
} 

This file specifies two positive integers that are to be added by the web service, passes the integers to the web service and gets the results from the web service via the port.addNumbers method, and prints the results to the screen. It then specifies a negative number to be added, gets the results (which should be an exception), and prints the results (the exception) to the screen.

Client Configuration File (fromjava)

The client configuration file defines the URL of the web service WSDL file. It is used by the web container wsimport tool to access and consume the WSDL and to build the stubs that are used to communicate with the web service.

The custom-client.xml file provided in the wsit-enabled-fromjava sample is shown below. The wsdlLocation and the package name xml tags are unique to each client and are highlighted in bold text

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bindings 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  wsdlLocation="http://localhost:8080/wsit-enabled-fromjava/
      addnumbers?wsdl"
  xmlns="http://java.sun.com/xml/ns/jaxws">
  <bindings node="wsdl:definitions">
    <package name="fromjava.client"/>
  </bindings>
</bindings> 

Creating a Client from WSDL

To create a client from WSDL, you must create the following files:

The build.xml and build.properties files are standard in any Ant build environment. Examples of these files are provided in the fromwsdl sample directory.

Client Java File (fromwsdl)

The client Java file defines the functionality of the web service client. The same client java file is used with both samples, wsit-enabled-fromjava and wsit-enabled-fromwsdl. For more information on this file, see Client Java File (fromjava).

Client Configuration File (fromwsdl)

This is a sample custom-client.xml file. The wsdlLocation, package name, and jaxb:package name xml tags are unique to each client and are highlighted in bold text

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bindings 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  wsdlLocation="http://localhost:8080/wsit-enabled-fromwsdl/
      addnumbers?wsdl"
  xmlns="http://java.sun.com/xml/ns/jaxws">
  <bindings node="ns1:definitions" 
      xmlns:ns1="http://schemas.xmlsoap.org/wsdl/">
    <package name="fromwsdl.client"/>
  </bindings>
  <bindings node="ns1:definitions/ns1:types/xsd:schema
      [@targetNamespace='http://duke.org']" 
      xmlns:xs="http://www.w3.org/2001/XMLSchema" 
      xmlns:ns1="http://schemas.xmlsoap.org/wsdl/">
    <jaxb:schemaBindings>
      <jaxb:package name="fromwsdl.client"/>
    </jaxb:schemaBindings>
  </bindings>
</bindings>