HOW TO: Integrate an Apache SOAP 2.2 Client with a SOAP Toolkit XML Web Service (307279)

SUMMARY

This article describes how to write an Apache SOAP 2.2 client for a Microsoft SOAP Toolkit-based Web service.

back to the top

Requirements

The following list outlines the recommended hardware, software, network infrastructure, and service packs that you need:

• Sun Microsystems Java Development Kit (JDK) version 1.3
• Apache SOAP version 2.2
• IBM Web Services Toolkit version 2 or 2.4

This article assumes that you are familiar with the following topics:

• Apache SOAP 2.2 libraries setup
• Java language and JavaBean technology
• XML Schema Documents (XSD)

For more information about how to set up the Apache SOAP 2.2 libraries, refer to the downloads for these products, as well as the REFERENCES at the end of this article.

When you use complex types in the SOAP interfaces, it is helpful to understand JavaBean technology as well. In addition, it is helpful to understand XSD if you must edit complex types or types whose names changed between the 1999 XSD proposal and the 2001 XSD World Wide Web Consortium (W3C) recommendation.

back to the top

Create the Java Proxy

Although this step is not required, it makes your Web service development significantly easier. Alternatively, you can write the code to call the Web service inline or write a proxy by hand.

NOTE: These steps require that the IBM Web Services Toolkit be installed on your computer.

1. Obtain a local copy of the Web Service Description Language (WSDL) file.
2. Within the .wsdl file, locate the <binding> element. This element contains an element named stk:binding.
3. Delete or comment out the stk:binding element, and then save the edited file.
4. Open a command prompt, and browse to the folder that contains the edited .wsdl file.
5. Type the following command:

   Path to Web Services Toolkit\Bin\Proxygen.bat edited WSDL file

   where edited WSDL file is the name of the .wsdl file that you edited in step 2.
6. Open the newly generated Java proxy class. This file usually appears in a subfolder of the directory that you are in. For example, if the targetNamespace for the definitions element is http://tempuri.org/wsdl, the new class appears in the subfolder named org/tempuri/wsdl.
   
   Add the function signatures and return statements if the code generator did not already add this information.
7. Tell the generated object how to deserialize the return value (if anything is returned). Apache contains many deserialization classes. The names of these classes appear in the "TypeDeserializer" format, where Type is the class that is being serialized (for example, StringDeserializer, IntDeserializer, and so on).
   
   If you are deserializing or serializing a complex type, you may need to write your own handler. For more information about how to write a custom handler, see the REFERENCES section. To add handlers, you associate the name of the return element with a particular class. The proxy has a member variable of type SOAPMappingRegistry named smr. This element is used to map elements to specific elements in the message.
   
   To map a string to a return element named Result, use the following code:

   org.apache.soap.util.xml.Deserializer stringDser = 
      new org.apache.soap.encoding.soapenc.StringDeserializer();
   smr.mapTypes ("http://schemas.xmlsoap.org/soap/encoding/", 
       new org.apache.soap.util.xml.QName("", "Result"), null, null, stringDser);
   						

   Add the preceding code before the generated proxy sets the method name, as in the following code:

   call.setMethodName("Logon");
   					

8. Type the following command to compile the proxy object:

   javac proxy object.java

9. Continue to fix the code until it builds.

back to the top

Use the Generated Proxy

You now have a proxy that you can use and test. To use the proxy, make sure that it is on the Java CLASSPATH, which includes the directory of the application that is using the proxy. Write code to instantiate the object, call any functions, and use the return value.

The following sample code calls a service that adds to numbers and returns the sum:

try {
    Service1SoapProxy proxy = new Service1SoapProxy();
    int result = proxy.Add( 5, 60 );
    System.out.println( "Result of add is " + result );
} catch( org.apache.soap.SOAPException e ) {
    System.out.println( e.toString() );
}
				

The catch clause is used to catch the SOAP faults that the proxy may return.

back to the top

Troubleshooting

It may take some time to set up the proxy correctly. This can be somewhat time consuming. If you must pass a complex type to the client, consider writing a client-side object as a JavaBean. This allows you to use the built-in JavaBeanSerializer and JavaBeanDeserializer classes.

back to the top