Automatically Generating WSDL Files - Page 7

One of the best aspects of WSDL is that you rarely have to create WSDL files from scratch. A whole host of tools currently exists for transforming existing services into WSDL descriptions. You can then choose to use these WSDL files as is or manually tweak them with your favorite text editor. In the discussion that follows, we explore the WSDL generation tool provided by GLUE.

TIP:  If you create WSDL files from scratch or tweak WSDL files generated by a tool, it is a good idea to validate your final WSDL documents. You can download a WSDL validator from http://pocketsoap.com/wsdl/. This package requires that you have an XSLT engine and the zvonSchematron (http://www.zvon.org/), but installation only takes a few minutes. Once installed, the validator is well worth the effort and creates nicely formatted HTML reports indicating WSDL errors and warnings.

GLUE java2wsdl Tool

The GLUE platform includes a java2wsdl command-line tool for transforming Java services into WSDL descriptions. The command-line usage is as follows:

usage: java2wsdl <arguments>
 
where valid arguments are:
  classname                     name of java class
  -d directory                  output directory
  -e url                        endpoint of service
  -g                            include GET/POST binding
  -m map-file                   read mapping instructions
  -n namespace                  namespace for service
  -r description                description of service
  -s                            include SOAP binding
  -x command-file               command file to execute

Complete information on each argument is available online within the GLUE User Guide at http://themindelectric.com/docs/glue/guide/index.html. For now, we will focus on the most basic arguments.

For example, consider the PriceService class in Example 6-4. The service provides a single getPrice( ) method.

Example 6-4: PriceService.java

package com.ecerami.soap.examples;
 
import java.util.Hashtable;
/**
 * A Sample SOAP Service
 * Provides Current Price for requested Stockkeeping Unit (SKU)
 */
public class PriceService {
  protected Hashtable products;
 
  /**
   * Zero Argument Constructor
   * Load product database with two sample products
   */
  public PriceService (  ) {
    products = new Hashtable(  );
    //  Red Hat Linux
    products.put("A358185", new Double (54.99));
    //  McAfee PGP Personal Privacy
    products.put("A358565", new Double (19.99));
  }
 
  /**
  *  Provides Current Price for requested SKU
  *  In a real-setup, this method would connect to
  *  a price database.  If SKU is not found, method
  *  will throw a PriceException.
  */
  public double getPrice (String sku)
    throws ProductNotFoundException {
    Double price = (Double) products.get(sku);
    if (price == null) {
      throw new ProductNotFoundException ("SKU: "+sku+" not found");
    }
    return price.doubleValue(  );
  }
}

To generate a WSDL file for this class, run the following command:

java2wsdl com.ecerami.soap.examples.PriceService -s -e http://localhost:
 8080/soap/servlet/rpcrouter -n urn:examples:priceservice

The -s option directs GLUE to create a SOAP binding; the -e option specifies the address of our service; and the -n option specifies the namespace URN for the service. GLUE will generate a PriceService.wsdl file. (See Example 6-5.)

TIP:   If your service is defined via a Java interface and you include your source files within your CLASSPATH, GLUE will extract your Javadoc comments, and turn these into WSDL documentation elements.

Example 6-5: PriceService.wsdl (automatically generated by GLUE)

<?xml version='1.0' encoding='UTF-8'?>
<!--generated by GLUE-->
<definitions name='com.ecerami.soap.examples.PriceService'
   targetNamespace='http://www.themindelectric.com/wsdl/com.ecerami.soap.
       examples.PriceService/'
 
   xmlns:tns='http://www.themindelectric.com/wsdl/com.ecerami.soap.
       examples.PriceService/'
   xmlns:electric='http://www.themindelectric.com/'
   xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/'
   xmlns:http='http://schemas.xmlsoap.org/wsdl/http/'
   xmlns:mime='http://schemas.xmlsoap.org/wsdl/mime/'
   xmlns:xsd='http://www.w3.org/2001/XMLSchema'
   xmlns:soapenc='http://schemas.xmlsoap.org/soap/encoding/'
   xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/'
   xmlns='http://schemas.xmlsoap.org/wsdl/'>
  <message name='getPrice0SoapIn'>
    <part name='sku' type='xsd:string'/>
  </message>
  <message name='getPrice0SoapOut'>
    <part name='Result' type='xsd:double'/>
  </message>
  <portType name='com.ecerami.soap.examples.PriceServiceSoap'>
    <operation name='getPrice' parameterOrder='sku'>
      <input name='getPrice0SoapIn' message='tns:getPrice0SoapIn'/>
      <output name='getPrice0SoapOut' message='tns:getPrice0SoapOut'/>
    </operation>
  </portType>
  <binding name='com.ecerami.soap.examples.PriceServiceSoap'
      type='tns:com.ecerami.soap.examples.PriceServiceSoap'>
    <soap:binding style='rpc' 
      transport='http://schemas.xmlsoap.org/soap/http'/>
    <operation name='getPrice'>
      <soap:operation soapAction='getPrice' style='rpc'/>
      <input name='getPrice0SoapIn'>
        <soap:body use='encoded'
         namespace='urn:examples:priceservice'
         encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'/>
      </input>
      <output name='getPrice0SoapOut'>
        <soap:body use='encoded'
        namespace='urn:examples:priceservice'
        encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'/>
      </output>
    </operation>
  </binding>
  <service name='com.ecerami.soap.examples.PriceService'>
    <port name='com.ecerami.soap.examples.PriceServiceSoap'
      binding='tns:com.ecerami.soap.examples.PriceServiceSoap'>
      <soap:address location='http://207.237.201.187:8080
          /soap/servlet/ rpcrouter'/>
    </port>
  </service>
</definitions>

You can then invoke the service via SOAP::Lite:

use SOAP::Lite;
 
print "Connecting to Price Service...\n";
print SOAP::Lite
   -> service('http://localhost:8080/wsdl/PriceService.wsdl')
   -> getPrice ('A358185');

Hopefully, this example illustrates the great promise of web service interoperability. We have a WSDL file generated by GLUE, a server running Java, and a client running Perl, and they all work seamlessly together.

Connecting to Price Service...
54.99

WARNING:   The IBM Web Services Toolkit (available at http://www.alphaworks.ibm.com/tech/webservicestoolkit) provides a WSDL generation tool called wsdlgen. This tool can take existing Java classes, Enterprise JavaBeans, and Microsoft COM objects and automatically generate corresponding WSDL files. However, as this book goes to press, the wsdlgen tool creates files based on the 1999 version of the W3C XML Schema. The WSDL files are therefore incompatible with other WSDL invocation tools, such as SOAP::Lite and GLUE. If you choose to use the IBM tool, make sure to manually update your WSDL files to reflect the latest version of XML Schema (http://www.w3.org/2001/XMLSchema).

WSDL Invocation Tools, Part II - Page 6
Web Services Essentials
XML Schema Data Typing - Page 8