XML::Compile::Transport - base class for XML transporters
XML::Compile::Transport is a XML::Compile::SOAP::Extension XML::Compile::Transport is extended by XML::Compile::Transport::SOAPHTTP XML::Compile::Transport::SOAPHTTP_AnyEvent
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
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 two transporter implementations:
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)
This requires the installation of an additional module. The user provides a callback to handle responses. Many queries can be spawned in parallel.
-Option --Default address 'http://localhost' charset 'utf-8'
One or more URI which represents the servers.
See "WSDL11" in XML::Compile::SOAP::Extension
See "SOAP11" in XML::Compile::SOAP::Extension
Get a server address to contact. If multiple addresses were specified, than one is chosen at random.
Returns a list of all server contact addresses (URIs)
Returns the charset to be used when sending,
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'
See section "Use of the transport hook" in DETAILS. When defined, the hook will be called, in stead of transmitting the message. The hook will get a two parameters passed in: the textual representation of the XML message to be transmitted, and the trace HASH with all values collected so far. 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.
undef
Kind of communication, as defined by WSDL.
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 transfer_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 Reponse for content and headers using methods similar to the following:
transfer_hook
$trace
sub transport_hook($$) { my ($request, $trace) = @_; 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 $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.
Content-Length
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);
my $wsdl = XML::Compile::WSDL11->new(...); $wsdl->compileClient('GetLastTracePrice', transport_hook => \&fake_server);
A transport hook can be used to follow the process of creating a message to its furthest extendt it will be called with the data as used by the actual protocol, but will not actually 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.
Declare an transporter type.
This module is part of XML-Compile-SOAP distribution version 2.25, built on September 22, 2011. Website: http://perl.overmeer.net/xml-compile/
Other distributions in this suite: XML::Compile, XML::Compile::SOAP, XML::Compile::SOAP12, XML::Compile::SOAP::Daemon, XML::Compile::SOAP::WSA, XML::Compile::C14N, XML::Compile::WSS, XML::Compile::Tester, XML::Compile::Cache, XML::Compile::Dumper, XML::Compile::RPC, XML::Rewrite, XML::eXistDB, and XML::LibXML::Simple.
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.
#xml-compile
irc.perl.org
Copyrights 2007-2011 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://www.perl.com/perl/misc/Artistic.html
To install XML::Compile::SOAP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XML::Compile::SOAP
CPAN shell
perl -MCPAN -e shell install XML::Compile::SOAP
For more information on module installation, please visit the detailed CPAN module installation guide.