Provided by: libxml-compile-soap-perl_3.22-2_all bug

NAME

       XML::Compile::Transport - base class for XML transporters

INHERITANCE

        XML::Compile::Transport
          is a XML::Compile::SOAP::Extension

        XML::Compile::Transport is extended by
          XML::Compile::Transport::SOAPHTTP
          XML::Compile::Transport::SOAPHTTP_AnyEvent

SYNOPSIS

        use XML::Compile::Transport::SOAPHTTP;
        my $trans  = XML::Compile::Transport::SOAPHTTP->new(...);
        my $call   = $trans->compileClient(...);

        my ($xmlout, $trace) = $call->($xmlin);
        my $xmlout = $call->($xmlin);   # when no trace needed

DESCRIPTION

       This module defines the exchange of (XML) messages. The module does not known how to parse
       or compose XML, but only worries about the transport aspects.

       On the moment, there are three transporter implementations:

       XML::Compile::Transport::SOAPHTTP
           implements an synchronous message exchange; the library waits for an answer before it
           returns to the user application. The information is exchanged using HTTP with SOAP
           encapsulation (SOAP also defines a transport protocol over HTTP without encapsulation)

       XML::Compile::Transport::SOAPHTTP_AnyEvent
           Event-driven implementation, based on AnyEvent.  The user provides a callback to
           handle responses. Many queries can be spawned in parallel, in a single process.  Find
           this in a separate distribution.

       XML::Compile::Transport::SOAPHTTP_MojoUA
           Event-driven implementation,  which fits in the Mojolicious infrastructure.  Find this
           in a separate distribution.

       Extends "DESCRIPTION" in XML::Compile::SOAP::Extension.

METHODS

       Extends "METHODS" in XML::Compile::SOAP::Extension.

   Constructors
       Extends "Constructors" in XML::Compile::SOAP::Extension.

       XML::Compile::Transport->new(%options)
            -Option --Default
             address  'http://localhost'
             charset  'utf-8'

           address => URI|ARRAY-of-URI
             One or more URI which represents the servers.

           charset => STRING

   WSDL11
       Extends "WSDL11" in XML::Compile::SOAP::Extension.

       $obj->wsdl11Init($wsdl, $args)
       XML::Compile::Transport->wsdl11Init($wsdl, $args)
           Inherited, see "WSDL11" in XML::Compile::SOAP::Extension

   SOAP11
       Extends "SOAP11" in XML::Compile::SOAP::Extension.

       $obj->soap11ClientWrapper($operation, $call, $args)
           Inherited, see "SOAP11" in XML::Compile::SOAP::Extension

       $obj->soap11HandlerWrapper($operation, $callback, $args)
           Inherited, see "SOAP11" in XML::Compile::SOAP::Extension

       $obj->soap11OperationInit($operation, $args)
       XML::Compile::Transport->soap11OperationInit($operation, $args)
           Inherited, see "SOAP11" in XML::Compile::SOAP::Extension

   SOAP12
       Extends "SOAP12" in XML::Compile::SOAP::Extension.

       $obj->soap12ClientWrapper($operation, $call, $args)
           Inherited, see "SOAP12" in XML::Compile::SOAP::Extension

       $obj->soap12HandlerWrapper($operation, $callback, $args)
           Inherited, see "SOAP12" in XML::Compile::SOAP::Extension

       $obj->soap12OperationInit($operation, $args)
       XML::Compile::Transport->soap12OperationInit($operation, $args)
           Inherited, see "SOAP12" in XML::Compile::SOAP::Extension

   Accessors
       $obj->address()
           Get a server address to contact. If multiple addresses were specified, than one is
           chosen at random.

       $obj->addresses()
           Returns a list of all server contact addresses (URIs)

       $obj->charset()
           Returns the charset to be used when sending,

   Handlers
       $obj->compileClient(%options)
           Compile a client handler.  Returned is a subroutine which is called with a text
           represenation of the XML request, or an XML::LibXML tree.  In SCALAR context, an
           XML::LibXML parsed tree of the answer message is returned.  In LIST context, that
           answer is followed by a HASH which contains trace information.

            -Option    --Default
             hook        <undef>
             kind        'request-response'
             xml_format  0

           hook => CODE
             See section "Use of the transport hook".  When defined, the hook will be called, in
             stead of transmitting the message.  The hook will gets three parameters passed in:
             the textual representation of the XML message to be transmitted, the trace HASH with
             all values collected so far, and the transporter object.  The trace HASH will have a
             massive amount of additional information added as well.

             You may add information to the trace.  You have to return a textual representation
             of the XML answer, or "undef" to indicate that the message was totally unacceptable.

           kind => STRING
             Kind of communication, as defined by WSDL.

           xml_format => 0|1|2
             [2.26] See XML::LibXML::Document subroutine toString.  With '1', you will get
             beautified output.

DETAILS

   Use of the transport hook
       A transport hook can be used to follow the process of creating a message to its furthest
       extend: it will be called with the data as used by the actual protocol, but will not
       connect to the internet.  Within the transport hook routine, you have to simulate the
       remote server's activities.

       There are two reasons to use a hook:

       .   You want to fake a server, to produce a test environment.

       .   You may need to modify the request or answer messages outside the reach of
           XML::Compile::SOAP, because something is wrong in either your WSDL of XML::Compile
           message processing.

       XML and Header Modifications

       Some servers require special extensions, which do not follow any standard (or logic). But
       even those features can be tricked, although it requires quite some programming skills.

       The "transport_hook" routine is called with a $trace hash, one of whose entries is the
       UserAgent which was set up for the data transfer. You can modify the outgoing message XML
       body and headers, carry out the data exchange using the UserAgent, and then examine the
       returned Response for content and headers using methods similar to the following:

        sub transport_hook($$$)
        {   my ($request, $trace, $transporter) = @_;
            my $content = $request->content;

            # ... modify content if you need
            my $new_content = encode "utf-8", $anything;
            $request->content($new_content);
            $request->header(Content_Length => length $new_content);
            $request->header(Content_Type => 'text/plain; charset=utf-8');

            # ... update the headers
            $request->header(Name => "value");

            # sent the request myself
            my $ua = $trace->{user_agent};
            my $response = $ua->request($request);

            # ... check the response headers
            my $name = $response->header('Name');

            # ... use the response content
            my $received = $response->decoded_content || $response->content;

            $response;
        }

       You should be aware that if you change the size or length of the content you MUST update
       the "Content-Length" header value, as demonstrated above.

       Transport hook for debugging

       The transport hook is a perfect means for producing automated tests.  Also, the
       XML::Compile::SOAP module tests use it extensively.  It works like this (for the SOAPHTTP
       simluation):

        use Test::More;

        sub fake_server($$)
        {  my ($request, $trace) = @_;
           my $content = $request->decoded_content;
           is($content, <<__EXPECTED_CONTENT);
       <SOAP-ENV:Envelope>...</SOAP-ENV:Envelope>
       __EXPECTED_CONTENT

           HTTP::Response->new(200, 'Constant'
             , [ 'Content-Type' => 'text/xml' ]
             , <<__ANSWER
       <SOAP-ENV:Envelope>...</SOAP-ENV:Envelope>
       __ANSWER
        }

       Then, the fake server is initiated in one of the follow ways:

         my $transport = XML::Compile::Transport::SOAPHTTP->new(...);
         my $http = $transport->compileClient(hook => \&fake_server, ...);
         $wsdl->compileClient('GetLastTracePrice', transporter => $http);

       or

         my $soap = XML::Compile::SOAP11::Client->new(...);
         my $call = $soap->compileClient(encode => ..., decode => ...,
             transport_hook => \&fake_server);

       or

         my $wsdl = XML::Compile::WSDL11->new(...);
         $wsdl->compileClient('GetLastTracePrice',
             transport_hook => \&fake_server);

       Transport hook for basic authentication

       [Adapted from an example contributed by Kieron Johnson] This example shows a
       transport_hook for compileClient() to add to http headers for the basic http
       authentication.  The parameter can also be used for compileAll() and many other related
       functions.

         my $call = $wsdl->compileClient($operation
            , transport_hook => \&basic_auth );

         # HTTP basic authentication encodes the username and password with
         # Base64. The encoded source string has format: "username:password"
         # With the below HTTP header being required:
         #        "Authorization: Basic [encoded password]"

         use MIME::Base64 'encode_base64';

         my $user     = 'myuserid' ;
         my $password = 'mypassword';

         sub basic_auth($$)
         {   my ($request, $trace) = @_;

             # Encode userid and password
             my $authorization = 'Basic '. encode_base64 "$user:$password";

             # Modify http header to include basic authorisation
             $request->header(Authorization => $authorization );

             my $ua = $trace->{user_agent};
             $ua->request($request);
         }

Helpers

       XML::Compile::Transport->register($uri)
           Declare an transporter type.

SEE ALSO

       This module is part of XML-Compile-SOAP distribution version 3.22, built on June 30, 2017.
       Website: http://perl.overmeer.net/xml-compile/

       Please post questions or ideas to the mailinglist at
       http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile .  For live contact with
       other developers, visit the "#xml-compile" channel on "irc.perl.org".

LICENSE

       Copyrights 2007-2017 by [Mark Overmeer]. For other contributors see ChangeLog.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.  See http://dev.perl.org/licenses/