NAME

SOAP::WSDL - SOAP with WSDL support

SYNOPSIS

 my $soap = SOAP::WSDL->new(
    wsdl => 'file://bla.wsdl',
    readable => 1,
 )->wsdlinit();
 
 my $result = $soap->call('MyMethod', %data);
 

DESCRIPTION

SOAP::WSDL provides easy access to Web Services with WSDL descriptions.

The WSDL is parsed and stored in memory.

Your data is serialized according to the rules in the WSDL and sent via SOAP::Lite's transport mechanism.

METHODS

wsdlinit

Reads the WSDL file and initializes SOAP::WSDL for working with it.

Must be called after the wsdl URL has been set, and before calling one of

 servicename
 portname
 call

You may set servicename and portname by passing them as attributes to wsdlinit:

 $soap->wsdlinit(
    servicename => 'MyService',
    portname => 'MyPort' 
 );

call

Performs a SOAP call. The result is either an object tree (with outputtree), a hash reference (with outputhash), plain XML (with outputxml) or a SOAP::SOM object (with neither of the above set).

 my $result = $soap->call('method', %data);

CONFIGURATION METHODS

outputtree

When outputtree is set, SOAP::WSDL will return an object tree instead of a SOAP::SOM object.

You have to specify a class_resolver for this to work. See <class_resolver|class_resolver>

class_resolver

Set the class resolver class (or object).

Class resolvers must implement the method get_class which has to return the name of the class name for deserializing a XML node at the current XPath location.

Class resolvers are typically generated by using the to_typemap method on a SOAP::WSDL::Definitions objects.

Example:

XML structure (SOAP body content):

 <Person>
    <Name>Smith</Name>
    <FirstName>John</FirstName>
 </Person>

Class resolver

 package MyResolver;
 my %typemap = (
    'Person' => 'MyPersonClass',
    'Person/Name' => 'SOAP::WSDL::XSD::Typelib::Builtin::string',
    'Person/FirstName' => 'SOAP::WSDL::XSD::Typelib::Builtin::string',
 );

 sub get_class { return $typemap{ $_[1] } };
 1;

You'll need a MyPersonClass module in your search path for this to work - see SOAP::WSDL::XSD::ComplexType on how to build / generate one.

servicename

 $soap->servicename('Name');

Sets the service to operate on. If no service is set via servicename, the first service found is used.

Must be called after calling wsdlinit().

Returns the soap object, so you can chain calls like

 $soap->servicename->('Name')->portname('Port');

portname

 $soap->portname('Name');

Sets the port to operate on. If no port is set via portname, the first port found is used.

Must be called after calling wsdlinit().

Returns the soap object, so you can chain calls like

 $soap->portname('Port')->call('MyMethod', %data);

no_dispatch

When set, call() returns the plain request XML instead of dispatching the SOAP call to the SOAP service. Handy for testing/debugging.

_wsdl_init_methods

Creates a lookup table containing the information required for all methods specified for the service/port selected.

The lookup table is used by call.

Differences to previous versions

• WSDL handling

  SOAP::WSDL 2 is a complete rewrite. While SOAP::WSDL 1.x attempted to process the WSDL file on the fly by using XPath queries, SOAP:WSDL 2 uses a SAX filter for parsing the WSDL and building up a object tree representing it's content.

  The object tree has two main functions: It knows how to serialize data passed as hash ref, and how to render the WSDL elements found into perl classes.

  Yup your're right, there's a builting code generation facility.

• no_dispatch

  call() with outputtxml set to true now returns the complete SOAP envelope, not only the body's content.

• outputxml

  call() with outputxml set to true now returns the complete SOAP envelope, not only the body's content.

• servicename/portname

  Both servicename and portname can only be called after calling wsdlinit().

  You may pass the servicename and portname as attributes to wsdlinit, though.

Differences to SOAP::Lite

Auto-Dispatching

SOAP::WSDL does does not support auto-dispatching.

This is on purpose: You may easily create interface classes by using SOAP::WSDL and implementing something like

 sub mySoapMethod {
     my $self = shift;
     $soap_wsdl_client->call( mySoapMethod, @_);
 }

You may even do this in a class factory - SOAP::WSDL provides the methods for generating such interfaces.

SOAP::Lite's autodispatching mechanism is - though convenient - a constant source of errors: Every typo in a method name gets caught by AUTOLOAD and may lead to unpredictable results.

Bugs and Limitations

• readable

  readable() must be called before calling wsdlinit. This is a bug.

• Unsupported XML Schema definitions

  The following XML Schema definitions are not supported:

   choice
   group
   union
   simpleContent
   complexContent

• Serialization of hash refs dos not work for ambiguous values

  If you have list elements with multiple occurences allowed, SOAP::WSDL has no means of finding out which variant you meant.

  Passing in item => [1,2,3] could serialize to

   <item>1 2</item><item>3</item>
   <item>1</item><item>2 3</item>

  Ambiguos data can be avoided by passing an object tree as data.

• XML Schema facets

  Almost all XML schema facets are not yet implemented. The only facets currently implemented are:

   fixed
   default

  The following facets have no influence yet:

   minLength
   maxLength
   minInclusive
   maxInclusive
   minExclusive
   maxExclusive
   pattern
   enumeration

LICENSE

Copyright 2004-2007 Martin Kutter.

This file is part of SOAP-WSDL. You may distribute/modify it under the same terms as perl itself

AUTHOR

Martin Kutter <martin.kutter fen-net.de>

cpanm SOAP::WSDL

perl -MCPAN -e shell
install SOAP::WSDL