view release on metacpan or  search on metacpan

lib/SOAP/Transport.pod  view on Meta::CPAN

=item new

    $trans = SOAP::Transport->new;

This is the constructor, which isn't usually called by an application directly. An application can use this to create a fresh new SOAP::Transport object, which may be installed using the SOAP::Lite->transport method defined earlier. No arguments are ...

=item proxy(optional URL string)

    $trans->proxy('http://www.blackperl.com/SOAP');

Gets or sets the proxy (endpoint). This method must be called before any other methods are called. The proper transport code is loaded based on the scheme specified by the URL itself (http, jabber, etc.). Until this method is called the first time wi...

=back

=head1 SOAP Transport Sub-Classes

Because the bulk of the work is done within the C<SOAP::Lite> module itself, many of the transport-level modules are very simple in their implementations. Transport modules are expected to define both client and server classes within their files. If ...

L</"SOAP::Transport::FTP"> - Client class only

L</"SOAP::Transport::HTTP"> - Client, and server classes for CGI, FCGI, Daemon and mod_perl

L</"SOAP::Transport::IO"> - Server class only

L</"SOAP::Transport::JABBER"> - Server and Client classes

L</"SOAP::Transport::LOCAL"> - Client class only

L</"SOAP::Transport::MAILTO"> - Client class only

L</"SOAP::Transport::MQ"> - Server and Client classes

L</"SOAP::Transport::POP3"> - Server class only

L</"SOAP::Transport::TCP"> - Server and Client classes

=head2 METHODS

Each SOAP::Transport sub-class is expected to define (or inherit, if it is subclassing another transport class) at least two methods. Any newly developed transport classes are also expected to adhere to this interface. Clients are expected to impleme...

=over

=item new(optional key/value pairs)

    $object = $class->new(%params);

Creates a new object instance and returns it. Like the constructors for both C<SOAP::Lite> and L<SOAP::Server> classes, all arguments passed in are treated as key/value pairs, where the key is expected to be one of the methods the class supports, and...

=item send_receive(key/value pairs)

    $client->send_recieve(%hash_table);

(Required for client classes only) When the SOAP::Lite objects attempt to send out requests, the means for doing so is to attempt to call this method on the object held within the SOAP::Transport object contained within the client itself. All clients...

=over

=item action

The URI specifying the action being performed, usually the result from the on_action hook on the client object.

=item encoding

The URI of the encoding scheme that governs the message being sent.

=item endpoint

The URI specifying the endpoint to which the message is being sent.

=item envelope

The XML content of the message to be sent. It is generally the return value of the envelope method from the L<SOAP::Serializer> object instance that the client object maintains.

=item parts

Attachments to add to the request. Currently this only supports an array of MIME::Entity objects, but in theory could support attachments of any format.

=back

=item handle

    $server->handle;

(Required for server classes only.) This method is the central point for the various server classes to provide an interface to handling requests. The exact set and nature of parameters generally varies based on the classes themselves.

=back

=head2 SOAP::Transport::HTTP

The most commonly used transport module is the HTTP implementation. This is loaded whenever an endpoint is given that starts with the characters, http:// or https://. This is also the most involved of the transport modules, defining not only a client...

=head3 HTTP PROXY SETTINGS

Because C<SOAP::Client> inherits from C<LWP::UserAgent>, you can use any of C<LWP::UserAgent>'s proxy settings. For example:

   SOAP::Lite->proxy("http://endpoint.server/",
                     proxy => ["http" => "http://my.proxy.server"]);

or

   $soap->transport->proxy("http" => "http://my.proxy.server");

The above code samples should specify a proxy server for you. And should you use C<HTTP_proxy_user>
and C<HTTP_proxy_pass> for proxy authorization, C<SOAP::Lite> will handle it properly.

=head3 HTTP BASIC AUTHENTICATION

HTTP Basic authentication is accomplished by overriding the get_basic_credentials subroutine in C<LWP::UserAgent> (which C<SOAP::Transport::HTTP::Client> is a subclass):

  BEGIN {
    sub SOAP::Transport::HTTP::Client::get_basic_credentials {
      return 'username' => 'password';
    }
  }

=head3 COOKIE-BASED AUTHENTICATION

    use HTTP::Cookies;
    my $cookies = HTTP::Cookies->new(ignore_discard => 1);
    # you may also add 'file' if you want to keep them between sessions
    my $soap = SOAP::Lite->proxy('http://localhost/');
    $soap->transport->cookie_jar($cookies);

Or, alternatively, you can do the above on a single line:

  $soap->proxy('http://localhost/',
               cookie_jar => HTTP::Cookies->new(ignore_discard => 1));

Cookies will be taken from the response and provided to the request. You may access and manipulate cookies received, as well as add cookies of your own by using the C<HTTP::Cookies> interfaces.

=head3 SSL CERTIFICATE AUTHENTICATION

The default SSL implementation for the HTTP client library L<LWP::UserAgent> used by SOAP::Lite is L<IO::Socket::SSL>.

To enable certificate based authentication, you'll have to pass your certificate and key as additional options to the
proxy() method like this:

    $soap->proxy( $url, ssl_opts => {
        SSL_cert_file => 'client-cert.pem',
        SSL_key_file  => 'client-key.pem'
    });

Or you can set them later like this:

    $soap->transport->ssl_opts(
        SSL_cert_file => 'client-cert.pem',
        SSL_key_file  => 'client-key.pem'
    );


If you're using L<Crypt::SSLeay>, the following applies:

To get certificate authentication working you need to set three environment variables: C<HTTPS_CERT_FILE>, C<HTTPS_KEY_FILE>, and optionally C<HTTPS_CERT_PASS>. This can be done either through the command line, or directly within your Perl script usi...

  $ENV{HTTPS_CERT_FILE} = 'client-cert.pem';
  $ENV{HTTPS_KEY_FILE}  = 'client-key.pem';

These settings are referenced by C<Crypt::SSLeay>. Other options (e.g. CA peer verification) can be specified in a similar way. See L<Crypt::SSLeay> documentation for more information.

Please note that you probably should not be using L<Crypt::SSLeay> because it does not perform hostname verification; LWP::UserAgent uses IO::Socket::SSL by default. See also L<https://metacpan.org/pod/Crypt::SSLeay#DO-YOU-NEED-Crypt::SSLeay>.

Those who would like to use encrypted keys may find the following thread in the SOAP::Lite newsgroup helpful:

http://groups.yahoo.com/group/soaplite/message/729

=head3 COMPRESSION

SOAP::Lite provides you with the option for enabling compression over the wire using HTTP I<only> in both the server and client contexts, provided that you have L<Compress::Zlib> installed. Compression and decompression is done transparently to your ...

A server will respond with an encoded/compressed message only if the client has asserted that it can accept it (indicated by client sending an C<Accept-Encoding> HTTP header with a 'deflate' or '*' value).

C<SOAP::Lite> clients all have fallback logic implemented so that if a server doesn't understand the specified encoding (i.e. "Content-Encoding: deflate") and returns the proper HTTP status code (415 NOT ACCEPTABLE), the client will repeat the reques...

Compression is enabled on the client side by specifying the C<compress_threshold> option, and if the size of the current request exceeds that threshold.

B<Client Code Sample>

  print SOAP::Lite
    ->uri('http://localhost/My/Parameters')
    ->proxy('http://localhost/', options => {compress_threshold => 10000})
    ->echo(1 x 10000)
    ->result;

Servers will respond with a compressed message if the C<compress_threshold> option has been specified, if the size of the current response exceeds that threshold, and if the calling client transmitted the proper C<Accept-Encoding> HTTP Header.

B<Server Code Sample>

  my $server = SOAP::Transport::HTTP::CGI
    ->dispatch_to('My::Parameters')
    ->options({compress_threshold => 10000})
    ->handle;

See also: L<Compress::Zlib>

=head3 SOAP::Transport::HTTP::Client

Inherits from: L<SOAP::Client>, L<LWP::UserAgent> (from the LWP package).

With this class, clients are able to use HTTP for sending messages. This class provides just the basic new and send_receive methods. Objects of this class understand the compress_threshold option and use it if the server being communicated to also un...

=head4 CHANGING THE DEFAULT USERAGENT CLASS

By default, C<SOAP::Transport::HTTP::Client> extends C<LWP::UserAgent>.
But under some circumstances, a user may wish to change the default
UserAgent class with their in order to better handle persist connections, or
to C<LWP::UserAgent::ProxyAny>, for example, which has better Win32/Internet
Explorer interoperability.

One can use the code below as an example of how to change the default UserAgent class.

  use SOAP::Lite;
  use SOAP::Transport::HTTP;
  $SOAP::Transport::HTTP::Client::USERAGENT_CLASS = "My::UserAgent";
  my $client = SOAP::Lite->proxy(..)->uri(..);
  my $som = $client->myMethod();

There is one caveat, however. The UserAgent class you use, I<MUST> also be a subclass of C<LWP::UserAgent>. If it is not, then C<SOAP::Lite> will issue the following error: "Could not load UserAgent class <USERAGENT CLASS>."

=head4 HTTP-KEEP-ALIVE, TIMEOUTS, AND MORE

Because C<SOAP::Transport::HTTP::Client> extends C<LWP::UserAgent>, all methods available C<LWP::UserAgent> are also available to your SOAP Clients. For example, using C<LWP::UserAgent> HTTP keep alive's are accomplished using the following code:

  my $ua = LWP::UserAgent->new(
        keep_alive => 1,
        timeout    => 30
  );

Therefore, the same initialization parameters you would pass to C<LWP::UserAgent> can also be passed to your SOAP::Lite client's C<proxy> subroutine like so:

    my $soap = SOAP::Lite
       ->uri($uri)
       ->proxy($proxyUrl,