Creating a Client and Invoking the Web Service

Invoking the web service and utilizing the generated code depends on your development environment; but, for example, it might include the following steps, assuming the web service has already been deployed and tested:

Copy or reference the generated source and class files; e.g. reference in Eclipse;
Code your client; e.g. Java main program. Typically your steps here will include:
- Instantiate the generated stub class;
- Optionally, increase the client timeout threshold (especially for a client that might run first after the application server starts);
- Setup the credentials in the custom SOAP header (see Custom SOAP Headers for more details);
- Call the stub methods to instantiate objects and set their values for passing to the service;
- Invoke the service operation;
- Check the response;
Build and test.

Typically the generated stub code provides a number of options to invoke the web service. Following are some sample code fragments to help illustrate that.

The following fragment calls a service named simpleAdd in class WebServiceTest for which the external tooling generates WebServiceTestStub and related classes:

Figure 1. Sample Web Service Client

final WebServiceTestStub stub =
      new WebServiceTestStub();

    // Set client timeout for slow machines.
    ServiceClient client = stub._getServiceClient();
    client.getOptions().setProperty(
      HTTPConstants.SO_TIMEOUT, new Integer(180000));
    client.getOptions().setProperty(
      HTTPConstants.CONNECTION_TIMEOUT, new Integer(180000));

    // test string and primitive data types
    final WebServiceTestStub.SimpleAdd service =
      new WebServiceTestStub.SimpleAdd();
    final int i = 20;
    final int j = 30;
    service.setArgs0(i);
    service.setArgs1(j);

    final WebServiceTestStub.SimpleAddResponse
      simpleAddResponse = stub.simpleAdd(service);
    final long sum = simpleAddResponse.get_return();
    
    client.cleanupTransport(); // Call when done with the service
                               // to avoid exhausting connection pool.
    client.cleanup();          // Call when done with the client.

Sometimes, while the generated code is convenient, you need a little more control over your client environment. The following example illustrates how you might call an in-only service using a "hand-built" SOAP message, which in this case takes a simple String argument as input:

Figure 2. Sample Web Service Client Using Generated Stub and Custom Code

final TestWSStub stub =
     new TestWSStub();

   // Get client from stub
   ServiceClient client;
   client = stub._getServiceClient();

   /*
    * Define SOAP using string
    */
   final String xml = "  <rem:testString "
     + "xmlns:rem=\"http://remote.testmodel.util.curam\"> "
     + "    <rem:testString>"
     + My test string!
     + "</rem:testString>"
     + "  </rem:testString>";

   final ByteArrayInputStream xmlStream =
     new ByteArrayInputStream(xml.getBytes());
   final StAXBuilder builder = new StAXOMBuilder(xmlStream);
   final OMElement oe = builder.getDocumentElement();

   // Send the message
   client.fireAndForget(oe);  // API for In-Only processing
   Thread.sleep(10000);       // Required for fireAndForget()
   client.cleanupTransport(); // Call when done with the service
                              // to avoid exhausting connection pool.
   client.cleanup();          // Call when done with the client.

Note: Later versions of Axis2 JavaDoc indicate that unless your client sets the callTransportCleanup property to true (not recommended for performance reasons) on the org.apache.axis2.client.Options object that you must call the org.apache.axis2.client.ServiceClient.cleanupTransport() API after processing the response.