=encoding utf8
=head1 NAME
XML::Compile::Transport::SOAPHTTP - exchange XML-SOAP via HTTP
=head1 INHERITANCE
XML::Compile::Transport::SOAPHTTP
is a XML::Compile::Transport
is a XML::Compile::SOAP::Extension
=head1 SYNOPSIS
use XML::Compile::Transport::SOAPHTTP;
my $http = XML::Compile::Transport::SOAPHTTP->new(@options);
my $send = $http->compileClient(@options2);
my $call = $wsdl->compileClient
( operation => 'some-port-name'
, transport => $send
);
my ($xmlout, $trace) = $call->($xmlin);
$wsdl->compileCalls(transport => $send);
=head1 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.
Extends L<"DESCRIPTION" in XML::Compile::Transport|XML::Compile::Transport/"DESCRIPTION">.
=head1 METHODS
Extends L<"METHODS" in XML::Compile::Transport|XML::Compile::Transport/"METHODS">.
=head2 Constructors
Extends L<"Constructors" in XML::Compile::Transport|XML::Compile::Transport/"Constructors">.
=over 4
=item XML::Compile::Transport::SOAPHTTP-E<gt>B<new>(%options)
Create a SOAP-over-HTTP handler, implemented as a wrapper around
LWP::UserAgent.
If you need to change UserAgent settings (for instance at runtime),
you can always directly access the internal C<LWP::UserAgent> object
via L<userAgent()|XML::Compile::Transport::SOAPHTTP/"Accessors">.
B<Warning:> The C<keep_alive> and C<timeout> options are only used when
an default internal C<LWP::UserAgent> is created; this is only once in a
program. Later instantiations of this ::SOAPHTTP will share that default
agent, even though these passed parameters have different parameters.
If that is not what you want, then pass your own C<user_agent> object to
the constructor to avoid the use of the default.
-Option --Defined in --Default
address XML::Compile::Transport 'http://localhost'
charset XML::Compile::Transport 'utf-8'
keep_alive <true>
timeout 180
user_agent <created when needed>
=over 2
=item address => URI|ARRAY-of-URI
=item charset => STRING
=item keep_alive => BOOLEAN
When connection can be re-used.
=item timeout => SECONDS
The maximum time for a single connection before the client will close it.
The server may close it earlier. Do not set the timeout too long, because
you want objects to be cleaned-up.
=item user_agent => LWP::UserAgent object
If you do not pass your own user agent, a default will be created for you.
=back
=back
=head2 WSDL11
Extends L<"WSDL11" in XML::Compile::Transport|XML::Compile::Transport/"WSDL11">.
=over 4
=item $obj-E<gt>B<wsdl11Init>($wsdl, $args)
=item XML::Compile::Transport::SOAPHTTP-E<gt>B<wsdl11Init>($wsdl, $args)
Inherited, see L<XML::Compile::SOAP::Extension/"WSDL11">
=back
=head2 SOAP11
Extends L<"SOAP11" in XML::Compile::Transport|XML::Compile::Transport/"SOAP11">.
=over 4
=item $obj-E<gt>B<soap11ClientWrapper>($operation, $call, $args)
Inherited, see L<XML::Compile::SOAP::Extension/"SOAP11">
=item $obj-E<gt>B<soap11HandlerWrapper>($operation, $callback, $args)
Inherited, see L<XML::Compile::SOAP::Extension/"SOAP11">
=item $obj-E<gt>B<soap11OperationInit>($operation, $args)
=item XML::Compile::Transport::SOAPHTTP-E<gt>B<soap11OperationInit>($operation, $args)
Inherited, see L<XML::Compile::SOAP::Extension/"SOAP11">
=back
=head2 SOAP12
Extends L<"SOAP12" in XML::Compile::Transport|XML::Compile::Transport/"SOAP12">.
=over 4
=item $obj-E<gt>B<soap12ClientWrapper>($operation, $call, $args)
Inherited, see L<XML::Compile::SOAP::Extension/"SOAP12">
=item $obj-E<gt>B<soap12HandlerWrapper>($operation, $callback, $args)
Inherited, see L<XML::Compile::SOAP::Extension/"SOAP12">
=item $obj-E<gt>B<soap12OperationInit>($operation, $args)
=item XML::Compile::Transport::SOAPHTTP-E<gt>B<soap12OperationInit>($operation, $args)
Inherited, see L<XML::Compile::SOAP::Extension/"SOAP12">
=back
=head2 Accessors
Extends L<"Accessors" in XML::Compile::Transport|XML::Compile::Transport/"Accessors">.
=over 4
=item $obj-E<gt>B<address>()
Inherited, see L<XML::Compile::Transport/"Accessors">
=item $obj-E<gt>B<addresses>()
Inherited, see L<XML::Compile::Transport/"Accessors">
=item $obj-E<gt>B<charset>()
Inherited, see L<XML::Compile::Transport/"Accessors">
=item $obj-E<gt>B<defaultUserAgent>()
=item XML::Compile::Transport::SOAPHTTP-E<gt>B<defaultUserAgent>()
[3.07] Returns the used LWP::UserAgent, available after the compilation
of the SOAP call(s).
=item $obj-E<gt>B<userAgent>( [$agent|<undef, %options>] )
Returns the User Agent which will be used. You may change the
configuration of the $agent (the returned LWP::UserAgent object)
or provide one yourself. See also L<new(user_agent)|XML::Compile::Transport::SOAPHTTP/"METHODS">.
Changes to the agent configuration can be made before or after the
compilation, or even inbetween SOAP calls.
=back
=head2 Handlers
Extends L<"Handlers" in XML::Compile::Transport|XML::Compile::Transport/"Handlers">.
=over 4
=item $obj-E<gt>B<compileClient>(%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 --Defined in --Default
action ''
header <created>
hook XML::Compile::Transport <undef>
kind 'request-response'
method 'POST'
mime_type <depends on soap version>
mpost_id 42
soap 'SOAP11'
xml_format XML::Compile::Transport 0
=over 2
=item action => URI
=item header => HTTP::Headers object
Versions of L<XML::Compile|XML::Compile>, L<XML::Compile::SOAP|XML::Compile::SOAP>, and LWP will be
added to simplify bug reports.
=item hook => CODE
=item kind => DIRECTION
What kind of interactie, based on the four types defined by WSDL(1):
C<notification-operation> (server initiated, no answer required),
C<one-way> (client initiated, no answer required), C<request-response>
(client initiated, the usual in both directions), C<solicit-response> (server
initiated "challenge").
=item method => 'POST'|'M-POST'
With C<POST>, you get the standard HTTP exchange. The C<M-POST> is
implements the (Microsoft) HTTP Extension Framework. Some servers
accept both, other require a specific request.
=item mime_type => STRING
=item mpost_id => INTEGER
With method C<M-POST>, the header extension fields require (any) number
to be grouped.
=item soap => 'SOAP11'|'SOAP12'|OBJECT
=item xml_format => 0|1|2
=back
example: create a client
my $trans = XML::Compile::Transport::SOAPHTTP->new
( address => 'http://www.stockquoteserver.com/StockQuote'
);
my $call = $trans->compileClient
( action => 'http://example.com/GetLastTradePrice'
);
# $request and $answer are XML::LibXML trees!
# see XML::Compile::SOAP::Client::compileClient() for wrapper which
# converts from and to Perl data structures.
my ($answer, $trace) = $call->($request);
my $answer = $call->($request); # drop $trace info immediately
=item $obj-E<gt>B<headerAddVersions>($header)
=item XML::Compile::Transport::SOAPHTTP-E<gt>B<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.
=back
=head1 DETAILS
Extends L<"DETAILS" in XML::Compile::Transport|XML::Compile::Transport/"DETAILS">.
=head1 Helpers
Extends L<"Helpers" in XML::Compile::Transport|XML::Compile::Transport/"Helpers">.
=over 4
=item XML::Compile::Transport::SOAPHTTP-E<gt>B<register>($uri)
Inherited, see L<XML::Compile::Transport/"Helpers">
=back
=head1 SEE ALSO
This module is part of XML-Compile-SOAP distribution version 3.20,
built on October 19, 2016. Website: F<http://perl.overmeer.net/xml-compile/>
Please post questions or ideas to the mailinglist at
F<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile> .
For live contact with other developers, visit the C<#xml-compile> channel
on C<irc.perl.org>.
=head1 LICENSE
Copyrights 2007-2016 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 F<http://www.perl.com/perl/misc/Artistic.html>