9.2 WSDL Programming

Because of the relatively young age of WSDL as an accepted technology, the modules and tools available to develop Perl applications with it or based on it are still somewhat scarce . However, its acceptance in other arenas is growing in strength. Most noteworthy is Microsoft's .NET framework, which automatically creates WSDL for a published service and makes it available at a URL related to the address of the base service. Because of this, tools and applications need to be WSDL-aware.

9.2.1 WSDL Schema Support in SOAP::Lite

The SOAP::Lite package currently offers a certain degree of support for basic WSDL specifications. If a schema is provided as either a local file or an accessible resource (such as a HTTP URI), it can create stub routines for a class definition that provides transparent access to the service.

The basic intent of the SOAP::Schema class within SOAP::Lite is to provide transparent support for schemas in a fairly generic manner. At present, it supports only WSDL with limited support for complex types and objects. Unlike the .NET service from Microsoft, there is nothing within SOAP::Lite that provides on-demand generation of WSDL from a published service. A service developer must still produce the description by some other means.

On-Demand WSDL: The WSDL::Generator Module

A recent addition to the CPAN is the WSDL::Generator package from Pierre Denis at Fotango, Ltd. Although still in an alpha stage, the package offers great promise.

Using another alpha-level module by the same author called Class::Hook , the generator catches all calls to class methods in the running application. It works using Perl's auto-loading control to intercept calls to unknown routines in unknown packages. Class::Hook takes care of transparently locating the code for the requested class and loading it. At the beginning of a call to a method, the hooks record information on the name and class of the method being called, as well as on the nature of the input arguments. Upon return from the method, the returned value is noted and examined. After a thorough run of an application, WSDL::Generator should be able to fashion a reasonable WSDL description for the service.

Because of the way Class::Hook manipulates calls, using this package directly with SOAP::Lite is probably not recommended. However, assuming that the server has a reasonably comprehensive testing application (which of course was part of the project planning, right?) that exercises all the service's features, adding in WSDL generation can be as simple as loading the module and adding a few lines to the test script.

9.2.1.1 SOAP::Lite client support for WSDL

A SOAP::Lite client can load a service description using the service method on the object, usually at creation-time or during the compilation stage. The following code fragments show different approaches to using the method. The first loads the service description at compile time, when the SOAP::Lite package is being used:

 use SOAP::Lite service => 'http://localhost/wishlist.wsdl'; 

In this case, the service is specified as a HTTP URL, which is fetched by the SOAP::Schema class using classes from the LWP package. The service may also be a file on a local filesystem. An alternative to loading the service at the outset is to specify it when creating the client object. This is more flexible because there is less need for compile-time versus runtime issues to be taken into account. The schema source may be a command-line argument or a value computed from external sources:

 my $schema = shift  'file:./wishlist.wsdl'; my $soap = SOAP::Lite->service($schema); 

When a client object uses a service description, there is no need to specify the uri or proxy values, as most previous client examples did. Those values are contained within the WSDL, in the form of the targetNamespace attribute of the definitions element and the location attribute of the soap:address element.

When the service method is used, the object created by the SOAP::Lite constructor gets blessed into a different class than usual. The name for the class is taken from the name attribute of the service element itself, and all the methods are derived from the operation elements in the binding used by the port element that defines the SOAP binding. The service method can also accept optional service name and portType name parameters; they can be useful when the WSDL file has multiple portType or service names .

Calls to the methods made available by the service description return native Perl data types rather than SOAP::SOM objects. There's no need to call the result method, but the trade-off is that the additional information from a SOAP::SOM object isn't available directly. The self and call methods can access the SOAP::SOM object in this case:

 my $som = $soap->self->call; # AFTER the call 

9.2.1.2 Code-generation based on WSDL

Another way in which the SOAP::Lite package provides support for WSDL is through a tool that comes with the package called stubmaker.pl .

The stubmaker.pl tool is a handy utility that both demonstrates the WSDL support in SOAP::Lite and produces a useful result. When run against a WSDL file or URL that refers to a WSDL resource, it generates a loadable Perl module from the services defined by the WSDL. The resulting file's name is based on the class name that would be selected if the service were loaded directly by a SOAP::Lite client object. The WSDL for the WSDL describing the WishList service would yield a file called WishListCustomer.pm (which would be very different from the file by that name in the software project), while the WSDL for the use.perl.org journal system would yield UsePerlJournal.pm . Calling the tool is simple enough:

 perl stubmaker.pl file:./useperlorg.wsdl 

Once the stub file has been generated, it can then be used in a client in place of explicitly configuring the client settings:

 perl -MUsePerlJournal -e 'get_entries(shift, shift)' 1 15 

The WSDL samples in Appendix E can be fed to the utility to see examples of the code it generates.

9.2.1.3 SOAP::Schema shortcomings

The schema support code in SOAP::Lite as of version 0.55 is still under development. Support is limited to WSDL alone, and it doesn't support all the more detailed facets of WSDL. It doesn't handle complex types and XML Schema type declarations. Parameters that are declared as belonging in the SOAP header are treated in the parameter list as thought they are meant to be in the body. When applied to the wishlist.wsdl file, the user parameter is consistently passed in the SOAP body, making the resulting stubs unusable when authentication is required.

For simpler schemas, such as the use.perl.org journal in which authentication is handled separately through HTTP cookies, the SOAP::Lite support is very effective and useful. It can be presumed that the support will continue to undergo development and enhancement along with the rest of the package.