NAME

XML::Compile::SOAP::HTTPClient - exchange SOAP via HTTP

INHERITANCE

XML::Compile::SOAP::HTTPClient
  is a XML::Compile::SOAP::Client

SYNOPSIS

my $call = XML::Compile::SOAP::HTTPClient->new(@options);
my ($answer, $trace) = $call->($request);
my $answer = $call->($request);

DESCRIPTION

This module handles the exchange of (XML) messages, according to the rules of SOAP (any version). The module does not known how to parse or compose XML, but only worries about the HTTP aspects.

METHODS

XML::Compile::SOAP::HTTPClient->defaultUserAgent([AGENT])

Returns the User Agent which will be used when none is specified. You may change the configuration of the AGENT (the returned LWP::UserAgent object) or provide one yourself. See also new(user_agent).

Changes to the agent configuration can be made before or after the compilation, or even inbetween SOAP calls.

$obj->headerAddVersions(HEADER)

XML::Compile::SOAP::HTTPClient->headerAddVersions(HEADER)

Adds some lines about module versions, which may help debugging or error reports. This is called when a new client or server is being created.

XML::Compile::SOAP::HTTPClient->new(OPTIONS)

Compile an HTTP 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
address         <derived from soap_action>
charset         'utf-8'
header          <created>
method          'POST'
mime_type       <depends on protocol>
mpost_id        42
soap_action     undef
soap_version    'SOAP11'
transport_hook  <undef>
user_agent      <singleton created>

. address => URI|ARRAY-of-URI

One or more URI which represents the servers. One is chosen at random.

. charset => STRING

. header => HTTP::Headers object

Versions of XML::Compile, XML::Compile::SOAP, and LWP will be added to simplify bug reports.

. method => 'POST'|'M-POST'

With POST, you get the standard HTTP exchange. The M-POST is implements the (Microsoft) HTTP Extension Framework. Some servers accept both, other require a specific request.

. mime_type => STRING

. mpost_id => INTEGER

With method M-POST, the header extension fields require (any) number to be grouped.

. soap_action => URI

. soap_version => 'SOAP11'|'SOAP12'

. transport_hook => CODE

Transport is handled by LWP::UserAgent subroutine request, however... you may need to modify the request or answer messages outside the reach of XML::Compile::SOAP. This may also be used for debugging. The CODE reference provided will be called with the request message (HTTP::Request) as first parameter, and the user agent (LWP::UserAgent) as second. You must return an answer (HTTP::Response) or undef.

See section "Use of transport_hook" in DETAILS.

. user_agent => LWP::UserAgent

If you pass your own user agent, you will be able to configure it. Otherwise, one will be created with all the defaults by defaultUserAgent(). Providing your own user agents -or at least have a look at the configuration- seems like a good idea.

example: create a client

my $call = XML::Compile::SOAP::HTTP->client
 ( address => 'http://www.stockquoteserver.com/StockQuote' );

# $request and $answer are XML::LibXML trees
my ($answer, $trace) = $call->($request);

# drop $trace info immediately
my $answer = $call->($request);

DETAILS

Use of transport_hook

The new(transport_hook) options can be used for various purposes. These CODE references are called in stead of the actual HTTP transport, but may still make that happen.

The dummy hook

A dummy client transport_hook is this:

sub hook($$)
{  my ($request, $user_agent) = @_;
   my $answer = $user_agent->request($request);
   return $answer;
}
# sub hook($$) { $_[1]->request($_[0]) }

my $http = XML::Compile::SOAP::HTTP->client
  ( ...
  , transport_hook => \&hook
  )

or

my $call = $wsdl->prepareClient
  ( 'some port'
  , transport_hook => \&hook
  );

Example use of transport_hook

Add a print statement before and after the actual transmission. Of course, you can get a trace hash with timing info back from the call (in LIST context as second returned element).

sub hook
{  my ($request, $user_agent) = @_;
   print "sending request\n";
   my $answer = $user_agent->request($request);
   print "received answer\n";
   $answer;
}

Regression tests with transport_hook

In test-scripts, we may not have access to internet, and we may not know how to create a daemon on all kinds of platforms. Therefore, the new(transport_hook) can be used to connect the request directly to an answer.

my $operation = $wsdl->operation('my-port');
my ($soapAction, $decode_request, $encode_answer)
   = $operation->prepareServer(...);

# Simulate server daemon
my $hook = sub               # closure!
{   my ($request, $user_agent) = @_;
    my $received = $decode_request->($request);
    # .... server-side tests on $received data...
    my $send     = { ... };  # fake an answer
    $encode_answer->($send);
}

my $client = $operation->prepareClient
  ( ....
  , transport_hook => \&hook
  );

In this case, there is no actual message transmission, because the user_agent is not used.

SEE ALSO

This module is part of XML-Compile-SOAP distribution version 0.55, built on October 03, 2007. Website: http://perl.overmeer.net/xml-compile/

LICENSE

Copyrights 2007 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

cpanm XML::Compile::SOAP

perl -MCPAN -e shell
install XML::Compile::SOAP