=head1 NAME

XML::Compile::Transport::SOAPHTTP - exchange XML via HTTP

=head1 INHERITANCE

 XML::Compile::Transport::SOAPHTTP
   is a XML::Compile::Transport

=head1 SYNOPSIS

 use XML::Compile::Transport::SOAPHTTP;

 my $http = XML::Compile::Transport::SOAPHTTP->new(@options);
 my $send = $transporter->compileClient(@options2);

 my $call = $wsdl->compileClient
  ( operation => 'some-port-name'
  , transport => $send
  );

 my ($xmlout, $trace) = $call->($xmlin);

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

=head1 METHODS

=head2 Constructors

XML::Compile::Transport::SOAPHTTP-E<gt>B<new>(OPTIONS)

=over 4

The C<keep_alive> and C<timeout> options are used when an LWP::UserAgent
is created, and ignored when you provide such an object.  In the latter
case, the values for those are inquired such that you can see the setting
directly from the passed object.

If you need to change UserAgent settings later, you can always directly
access the LWP::UserAgent object via L<userAgent()|XML::Compile::Transport::SOAPHTTP/"Accessors">.

 Option    --Defined in     --Default
 address     XML::Compile::Transport  'localhost'
 charset     XML::Compile::Transport  'utf-8'
 keep_alive                   <true>
 timeout                      180
 user_agent                   <created when needed>

. address => URI|ARRAY-of-URI

. charset => STRING

. keep_alive => BOOLEAN

=over 4

When connection can be re-used.

=back

. timeout => SECONDS

=over 4

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.

=back

. user_agent => LWP::UserAgent object

=over 4

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

=back

=back

=head2 Accessors

$obj-E<gt>B<address>

=over 4

See L<XML::Compile::Transport/"Accessors">

=back

$obj-E<gt>B<addresses>

=over 4

See L<XML::Compile::Transport/"Accessors">

=back

$obj-E<gt>B<charset>

=over 4

See L<XML::Compile::Transport/"Accessors">

=back

$obj-E<gt>B<userAgent>([AGENT|(undef, OPTIONS)])

=over 4

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

$obj-E<gt>B<compileClient>(OPTIONS)

=over 4

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       XML::Compile::Transport  'request-response'
 method                      'POST'
 mime_type                   <depends on soap version>
 mpost_id                    42
 soap                        'SOAP11'

. action => URI

. header => HTTP::Headers object

=over 4

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

=back

. hook => CODE

. kind => STRING

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

=over 4

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.

=back

. mime_type => STRING

. mpost_id => INTEGER

=over 4

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

=back

. soap => 'SOAP11'|'SOAP12'|OBJECT

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

=back

$obj-E<gt>B<headerAddVersions>(HEADER)

XML::Compile::Transport::SOAPHTTP-E<gt>B<headerAddVersions>(HEADER)

=over 4

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

=head1 SEE ALSO

This module is part of XML-Compile-SOAP distribution version 0.77,
built on August 15, 2008. Website: F<http://perl.overmeer.net/xml-compile/>

All modules in this suite:
L<XML::Compile>,
L<XML::Compile::SOAP>,
L<XML::Compile::SOAP::Daemon>,
L<XML::Compile::Tester>,
L<XML::Compile::Cache>,
L<XML::Rewrite>,
L<XML::Compile::Dumper>.

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

=head1 LICENSE

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