/ 
SOAP-WSDL-2.00.07
River stage one • 7 direct dependents • 7 total dependents
/ SOAP::WSDL::Manual::Cookbook

NAME

SOAP::WSDL::Manual::Cookbook - SOAP::WSDL recipes

Accessing HTTPS webservices

You need Crypt::SSLeay installed to access HTTPS webservices.

Accessing protected web services

Passing a username and password, or a client certificate and key, to the transport layer is highly dependent on the transport backend. The descriptions below are for HTTP(S) transport using LWP::UserAgent

Accessing HTTP(S) webservices with basic/digest authentication

When using SOAP::WSDL::Transport::HTTP (SOAP::Lite not installed), add a method called "get_basic_credentials" to SOAP::WSDL::Transport::HTTP:

*SOAP::WSDL::Transport::HTTP::get_basic_credentials = sub {
   return ($user, $password);
};

When using SOAP::Transport::HTTP (SOAP::Lite is installed), do the same to this backend:

*SOAP::Transport::HTTP::Client::get_basic_credentials = sub {
    return ($user, $password);
};

Accessing HTTP(S) webservices protected by NTLM authentication

You need the NTLM distribution installed to access webservices protected by NTLM authentication. More specifically, you need the Authen::NTLM module from this distribution. Note that this is different from the Authen::NTML distribution by Yee Man Chan also available from CPAN.

Your user credentials usually need to include the windows domain like this:

testdomain\testuser

Besides passing user credentials as when accessing a web service protected by basic or digest authentication, you also need to enforce connection keep_alive on the transport backens.

To do so, pass a proxy argument to the new() method of the generated class. This unfortunately means that you have to set the endpoint URL, too:

my $interface = MyInterfaces::SERVICE_NAME::PORT_NAME->new({
    proxy => [ $url, keep_alive => 1 ]
});

You may, of course, decide to just hack the generated class. Be advised that subclassing might be a more appropriate solution - re-generating overwrites changes in interface classes.

Accessing HTTPS webservices protected by certificate authentication

You need Crypt::SSLeay installed to access HTTPS webservices.

See Crypt::SSLeay on how to configure client certificate authentication.

XML OUTPUT

Outputting namespaces as prefixes

Q: I need to interface with a SOAP server which doesn't accept the following format:

<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Body>
        <getElement xmlns="http://services.company.com/">
            <elementId>12345</elementId>
        </getElement>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Instead, it requires this:

<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:ns2="http://services.company.com/"
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Body>
        <ns2:getElement>
            <ns2:elementId>12345</ns2:elementId>
        </ns2:getElement>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

How do I do this using SOAP::WSDL?

A: The following steps are neccessary to achieve this result:

First, you would need to write a new serializer, which is quite easy, as it just creates the envelope and calls ->serialize_qualified() on $header and $body to fill them in. The new serializer has to declare all namespace prefixes used, the rest is just the same as the original XSD serializer.

Second, you'd need to overwrite the start_tag method in SOAP::WSDL::XSD::Typelib::Element to use the appropriate prefixes for the body elements.

In contrast to the original method, it would probably look up the appropriate prefix from some data set in the serializer class, so this could be the appropriate place to load SOAP::WSDL::XSD::Typelib::Element and override the method.

Something like this should do (without the handling of specialties like empty or nil elements):

%PREFIX_OF = { 'http://services.company.com/' => 'ns2' };

*SOAP::WSDL::XSD::Typelib::Element::start_tag = sub {
    # use prefix instead of xmlns attribute and copy the rest from
    # SOAP::WSDL::XSD::Typelib::Element::start_tag
    my $prefix = $PREFIX_OF{ $_[0]->get_xmlns() };
    my $name = $_[1]->{ name } || $self->__get_name();
    return "<$prefix:$name>";
}

Skipping unknown XML elements - "lax" XML processing

SOAP::WSDL's default serializer SOAP::WSDL::Deserializer::XSD is a "strict" XML processor in the sense that it throws an exception on encountering unknown XML elements.

SOAP::WSDL::Deserializer::XSD allows switching off the stric XML processing by passing the strict => 0 option.

Disabling strict XML processing in a Client

Pass the following as deserializer_args:

{ strict => 0 }

Example: The generated SOAP client is assumed to be "MyInterface::Test".

use MyInterface::Test;

my $soap = MyInterface::Test->new({
    deserializer_args => { strict => 0 }
});

my $result = $soap->SomeMethod();

Disabling strict XML processing in a CGI based server

You have to set the deserializer in the transport class explicitely to a SOAP::WSDL::Deserializer object with the strict option set to 0.

Example: The generated SOAP server is assumed to be "MyServer::Test".

use strict;
use MyServer::Test;
use SOAP::WSDL::Deserializer::XSD;

my $soap = MyServer::Test->new({
    transport_class => 'SOAP::WSDL::Server::CGI',
    dispatch_to => 'main',
});
$soap->get_transport()->set_deserializer(
   SOAP::WSDL::Deserializer::XSD->new({ strict => 0 })
);

$soap->handle();

Disabling strict XML processing in a mod_perl based server

Sorry, this is not implemented yet - you'll have to write your own handler class based on SOAP::WSDL::Server::Mod_Perl2.

Changing the encoding of a SOAP request

SOAP::WSDL uses utf-8 per default: utf-8 is the de-facto standard for webservice ommunication.

However, you can change the encoding the transport layer announces by calling set_encoding($encoding) on a client object.

You probably have to write your own serializer class too, because the default serializer has the utf-8 encoding hardcoded in the envelope.

Just look into SOAP::WSDL::Serializer on how to do that.

Don't forget to register your serializer at the serializer factory SOAP::WSDL::Factory::Serializer.

LICENSE AND COPYRIGHT

Copyright 2008, 2009 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>

REPOSITORY INFORMATION

$Rev: 583 $
$LastChangedBy: kutterma $
$Id: $
$HeadURL: $