/ 
XML-Compile-SOAP-0.58
River stage two • 30 direct dependents • 35 total dependents
/ XML::Compile::SOAP::HTTPClient

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
action          <required>
address         <derived from action>
charset         'utf-8'
header          <created>
method          'POST'
mime_type       <depends on soap version>
mpost_id        42
soap_version    'SOAP11'
transport_hook  <undef>
user_agent      <singleton created>

    . action => URI

    . address => URI|ARRAY-of-URI

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

    . charset => STRING

    . header => HTTP::Headers object

    . 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_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.

      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 object

      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 $exchange = XML::Compile::SOAP::HTTPClient->new
  ( address => 'http://www.stockquoteserver.com/StockQuote'
  , action  => 'http://example.com/GetLastTradePrice'
  );

# $request and $answer are XML::LibXML trees!
# see XML::Compile::SOAP::Client::compileClient() for wrapper
my ($answer, $trace) = $exchange->($request);

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

Constructors

Single messages

$obj->compileClient(OPTIONS)

Debugging

$obj->fakeServer([FAKE|undef])

XML::Compile::SOAP::HTTPClient->fakeServer([FAKE|undef])

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;
}

SEE ALSO

This module is part of XML-Compile-SOAP distribution version 0.58, built on October 22, 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