import SOAP-WSDL 2.00.02 from CPAN

git-cpan-module:   SOAP-WSDL
git-cpan-version:  2.00.02
git-cpan-authorid: MKUTTER
git-cpan-file:     authors/id/M/MK/MKUTTER/SOAP-WSDL-2.00.02.tar.gz

lib/SOAP/WSDL/Manual/Cookbook.pod

@@ -0,0 +1,133 @@
+=pod
+
+=head1 NAME
+
+SOAP::WSDL::Manual::Cookbook - SOAP::WSDL recipes
+
+=head2 Accessing HTTPS webservices
+
+You need Crypt::SSLeay installed to access HTTPS webservices.
+
+=head2 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 usingLWP::UserAgent
+
+=head3 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);
+ };
+
+=head3 Accessing HTTP(S) webservices protected by NTLM authentication
+
+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 I<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.
+
+=head3 Accessing HTTPS webservices protected by certificate authentication
+
+You need Crypt::SSLeay installed to access HTTPS webservices.
+
+See L<Crypt::SSLeay> on how to configure client certificate authentication.
+
+=head1 XML OUTPUT
+
+=head2 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
+L<SOAP::WSDL::XSD::Typelib::Element|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>";
+ }
+
+=head1 LICENSE AND COPYRIGHT
+
+Copyright 2008 Martin Kutter.
+
+This library is free software. You may distribute/modify it under
+the same terms as perl itself
+
+=head1 AUTHOR
+
+Martin Kutter E<lt>martin.kutter fen-net.deE<gt>
+
+=head1 REPOSITORY INFORMATION
+
+ $Rev: 583 $
+ $LastChangedBy: kutterma $
+ $Id: $
+ $HeadURL: $
+
+=cut