SOAP::Transport - phpMan

NAME
    SOAP::Transport - an abstract class extended by more specialized
    transport modules

DESCRIPTION
    Objects of the SOAP::Transport class manage two roles: they manage both
    the parameters related to transport as set through the containing
    SOAP::Lite object, and they abstract the selection and loading of an
    appropriate transport module. This is done with an AUTOLOAD function
    within the class that intercepts all methods beyond the two defined next
    and reroutes them to the underlying transport implementation code.

METHODS
    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
        recognized.

    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 with a URL string,
        the underlying code has yet to be loaded, and the methods aren't
        available. When getting the current proxy (calling with no
        parameters), the returned value is a reference to the client object
        created from the protocol class that matched the endpoint, not the
        endpoint itself.

SOAP Transport Sub-Classes
    Because the bulk of the work is done within the "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 a module defines only one of
    the types, it is assumed that the transport protocol itself supports
    only that side of the conversation. An example is SOAP::Transport::FTP,
    which provides only a "SOAP::Transport::FTP::Client" class.

    "SOAP::Transport::FTP" - Client class only

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

    "SOAP::Transport::IO" - Server class only

    "SOAP::Transport::JABBER" - Server and Client classes

    "SOAP::Transport::LOCAL" - Client class only

    "SOAP::Transport::MAILTO" - Client class only

    "SOAP::Transport::MQ" - Server and Client classes

    "SOAP::Transport::POP3" - Server class only

    "SOAP::Transport::TCP" - Server and Client classes

  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 implement the "new" and
    "send_receive" methods, and servers are expected to implement the "new"
    and "handle" methods. Here they are:

    new(optional key/value pairs)
            $object = $class->new(%params);

        Creates a new object instance and returns it. Like the constructors
        for both "SOAP::Lite" and 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 the value is the argument
        (or list reference of arguments) to the method.

    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 are expected
        to provide this, and the call to this method always passes four
        values for the hash keys:

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

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

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

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

        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.

    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.

  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 class but several different server
    classes as well.

   HTTP PROXY SETTINGS
    Because "SOAP::Client" inherits from "LWP::UserAgent", you can use any
    of "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 "HTTP_proxy_user" and "HTTP_proxy_pass" for proxy authorization,
    "SOAP::Lite" will handle it properly.

   HTTP BASIC AUTHENTICATION
    HTTP Basic authentication is accomplished by overriding the
    get_basic_credentials subroutine in "LWP::UserAgent" (which
    "SOAP::Transport::HTTP::Client" is a subclass):

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

   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 "HTTP::Cookies" interfaces.

   SSL CERTIFICATE AUTHENTICATION
    The default SSL implementation for the HTTP client library
    LWP::UserAgent used by SOAP::Lite is 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 Crypt::SSLeay, the following applies:

    To get certificate authentication working you need to set three
    environment variables: "HTTPS_CERT_FILE", "HTTPS_KEY_FILE", and
    optionally "HTTPS_CERT_PASS". This can be done either through the
    command line, or directly within your Perl script using the $ENV
    variable:

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

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

    Please note that you probably should not be using Crypt::SSLeay because
    it does not perform hostname verification; LWP::UserAgent uses
    IO::Socket::SSL by default. See also
    <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

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

    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 "Accept-Encoding" HTTP header with a 'deflate' or '*' value).

    "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 request without using
    encoding/compression. The client will then store this server in a
    per-session cache, so that all subsequent requests to that server will
    be transmitted without encoding.

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

    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
    "compress_threshold" option has been specified, if the size of the
    current response exceeds that threshold, and if the calling client
    transmitted the proper "Accept-Encoding" HTTP Header.

    Server Code Sample

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

    See also: Compress::Zlib

   SOAP::Transport::HTTP::Client
    Inherits from: SOAP::Client, 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 understands it.

   CHANGING THE DEFAULT USERAGENT CLASS
    By default, "SOAP::Transport::HTTP::Client" extends "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 "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, *MUST* also
    be a subclass of "LWP::UserAgent". If it is not, then "SOAP::Lite" will
    issue the following error: "Could not load UserAgent class <USERAGENT
    CLASS>."

   HTTP-KEEP-ALIVE, TIMEOUTS, AND MORE
    Because "SOAP::Transport::HTTP::Client" extends "LWP::UserAgent", all
    methods available "LWP::UserAgent" are also available to your SOAP
    Clients. For example, using "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
    "LWP::UserAgent" can also be passed to your SOAP::Lite client's "proxy"
    subroutine like so:

        my $soap = SOAP::Lite
           ->uri($uri)
           ->proxy($proxyUrl,
               timeout => 30,
               keep_alive => 1,
             );

    This is true for all initialization parameters and methods of
    "LWP::UserAgent".

   METHODS
    http_request
        This method gives you access to a prototype of the HTTP Request
        object that will be transmitted to a SOAP::Server. The actual
        request used is a copy of that object.

        Do not use this method for anything else than setting prototypic
        behaviour for the client object.

    http_response
        This method gives you access to the HTTP Response object that will
        be, or was transmitted to a SOAP Server. It returns a HTTP::Response
        object.

   SOAP::Transport::HTTP::Server
    Inherits from: SOAP::Server.

    This is the most basic of the HTTP server implementations. It provides
    the basic methods, new and handle. The handle method's behavior is
    defined here, along with other methods specific to this class. The role
    of this class is primarily to act as a superclass for the other
    HTTP-based server classes.

    handle
            $server->handle;

        Expects the request method to have been used to associate a
        HTTP::Request object with the server object prior to being called.
        This method retrieves that object reference to get at the request
        being handled.

    request(*optional value*)
            $server->request($req_object)

        Gets or sets the HTTP::Request object reference that the server will
        process within the handle method.

    response(*optional value*)
            $server->response(HTTP::Response->new(...));

        Gets or sets the HTTP::Response object reference that the server has
        prepared for sending back to the client.

    make_response(*code*, *body*)
            $server->make_response(200, $body_xml);

        Constructs and returns an object of the HTTP::Response class, using
        the response code and content provided.

    make_fault(*fault arguments*)
            $server->response($server->make_fault(@data));

        Creates a HTTP::Response object reference using a predefined HTTP
        response code to signify that a fault has occurred. The arguments
        are the same as those for the make_fault method of the SOAP::Server
        class.

    product_tokens
        This method takes no arguments and simply returns a string
        identifying the elements of the server class itself. It is similar
        to the product_tokens methods in the HTTP::Daemon and Apache
        classes.

   SOAP::Transport::HTTP::CGI
    Inherits from: SOAP::Transport::HTTP::Server.

    This class is a direct subclass of SOAP::Transport::HTTP::Server and
    defines no additional methods. It includes logic in its implementation
    of the handle method that deals with the request headers and parameters
    specific to a CGI environment.

   EXAMPLE CGI
    The following code sample is a CGI based Web Service that converts
    celsius to fahrenheit:

        #!/usr/bin/perl
        use SOAP::Transport::HTTP;
        SOAP::Transport::HTTP::CGI
          ->dispatch_to('C2FService')
          ->handle;
        BEGIN {
          package C2FService;
          use vars qw(@ISA);
          @ISA = qw(Exporter SOAP::Server::Parameters);
          use SOAP::Lite;
          sub c2f {
            my $self = shift;
            my $envelope = pop;
            my $temp = $envelope->dataof("//c2f/temperature");
            return SOAP::Data->name('convertedTemp' => (((9/5)*($temp->value)) + 32));
          }
        }

   EXAMPLE APACHE::REGISTRY USAGE
    Using a strictly CGI based Web Service has certain performance
    drawbacks. Running the same CGI under the Apache::Registery system has
    certain performance gains.

    httpd.conf

      Alias /mod_perl/ "/Your/Path/To/Deployed/Modules"
      <Location /mod_perl>
        SetHandler perl-script
        PerlHandler Apache::Registry
        PerlSendHeader On
        Options +ExecCGI
      </Location>

    soap.cgi

      use SOAP::Transport::HTTP;

      SOAP::Transport::HTTP::CGI
        ->dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
        ->handle;

    *WARNING: Dynamic deployments with "Apache::Registry" will fail because
    the module will be only loaded dynamically the first time. Subsequent
    calls will produce "denied access" errors because once the module is
    already in memory "SOAP::Lite" will bypass dynamic deployment. To work
    around this, simply specify both the full PATH and MODULE name in
    "dispatch_to()" and the module will be loaded dynamically, but will then
    work as if under static deployment. See examples/server/soap.mod_cgi as
    an example.*

   SOAP::Transport::HTTP::Daemon
    Inherits from: SOAP::Transport::HTTP::Server.

    The SOAP::Transport::HTTP::Daemon class encapsulates a reference to an
    object of the HTTP::Daemon class (from the LWP package). The class
    catches methods that aren't provided locally or by the superclass and
    attempts to call them on the HTTP::Daemon object. Thus, all methods
    defined in the documentation for that class are available to this class
    as well. Any that conflict with methods in SOAP::Transport::HTTP::Server
    (such as product_tokens) go to the superclass. Additionally, the
    behavior of the handle method is specific to this class:

    handle
        When invoked, this method enters into the typical accept loop in
        which it waits for a request on the socket that the daemon object
        maintains and deals with the content of the request. When all
        requests from the connection returned by the accept method of the
        HTTP::Daemon object have been processed, this method returns.

   REUSING SOCKETS ON RESTART
    Often when implementing an HTTP daemon, sockets will get tied up when
    you try to restart the daemon server. This prevents the server from
    restarting. Often users will see an error like "Cannot start server:
    port already in use." To circumvent this, instruct SOAP::Lite to reuse
    open sockets using "Reuse => 1":

      my $daemon = SOAP::Transport::HTTP::Daemon
                      -> new (LocalPort => 80000, Reuse => 1)

   EXAMPLE DAEMON SERVER
      use SOAP::Transport::HTTP;
      # change LocalPort to 81 if you want to test it with soapmark.pl
      my $daemon = SOAP::Transport::HTTP::Daemon
        -> new (LocalAddr => 'localhost', LocalPort => 80)
        # specify list of objects-by-reference here
        -> objects_by_reference(qw(My::PersistentIterator My::SessionIterator My::Chat))
        # specify path to My/Examples.pm here
        -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
      ;
      print "Contact to SOAP server at ", $daemon->url, "\n";
      $daemon->handle;

   SOAP::Transport::HTTP::Apache
    Inherits from: SOAP::Transport::HTTP::Server.

    This class provides an integration of the SOAP::Server base class with
    the mod_perl extension for Apache. To work as a location handler, the
    package provides a method called handler, for which handle is made an
    alias. The new method isn't functionally different from the superclass.
    Here are the other methods provided by this class:

    handler(*Apache request*)
            $server->handler($r)

        Defines the basis for a location handler in the mod_perl fashion.
        The method expects an Apache request object as the parameter, from
        which it pulls the body of the request and calls the superclass
        handle method.

        Note that in this class, the local method named handle is aliased to
        this method.

    configure(*Apache request*)
            $server->configure(Apache->request);

        Per-location configuration information can be provided to the server
        object using the Apache DirConfig directive and calling this method
        on the object itself. When invoked, the method reads the directory
        configuration information from Apache and looks for lines of the
        form:

            method => param

        Each line that matches the pattern is regarded as a potential method
        to call on the server object, with the remaining token taken as the
        parameter to the method. Methods that take hash references as
        arguments may be specified as:

            method => key => param, key => param

        The key/value pairs will be made into a hash reference on demand. If
        the server object doesn't recognize the named method as valid, it
        ignores the line.

   EXAMPLE APACHE MOD_PERL SERVER
    See examples/server/Apache.pm and Apache::SOAP for more information.

    httpd.conf

      <Location /soap>
        SetHandler perl-script
        PerlHandler SOAP::Apache
        PerlSetVar options "compress_threshold => 10000"
      </Location>

    SOAP::Apache.pm

      package SOAP::Apache;
      use SOAP::Transport::HTTP;
      my $server = SOAP::Transport::HTTP::Apache
        ->dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method');
      sub handler { $server->handler(@_) }
      1;

    See also Apache::SOAP.

   SOAP::Transport::HTTP::FCGI
    Inherits from: SOAP::Transport::HTTP::CGI.

    This is an extension of the SOAP::Transport::HTTP::CGI that implements
    the differences needed for the FastCGI protocol. None of the methods are
    functionally different.

  SOAP::Transport::IO
    The SOAP::Transport::IO-based class allows for a sort of I/O proxying by
    allowing the application to configure what files or filehandles are
    used. This module supplies only a server class.

   SOAP::Transport::IO::Server
    Inherits from: SOAP::Server.

    The server class defined here inherits all methods from SOAP::Server,
    and adds two additional methods specific to the nature of the class:

    in
            $server->in(IO::File->new($file));

        Gets or sets the current filehandle being used as the input source.

    out
            $server->out(\*STDERR);

        Gets or sets the filehandle being used as the output destination.

  SOAP::Transport::LOCAL
    The SOAP::Transport::LOCAL module is designed to provide a no-transport
    client class for tracing and debugging communications traffic. It links
    SOAP::Client and SOAP::Server so that the same object that "sends" the
    request also "receives" it.

   SOAP::Transport::LOCAL::Client
    Inherits from: SOAP::Client, SOAP::Server. The implementations of the
    new and send_receive methods aren't noticeably different in their
    interface. Their behavior warrants description, however:

    new When the constructor creates a new object of this class, it sets up
        a few things beyond the usual SOAP::Client layout. The is_success
        method is set to a default value of 1. The dispatch_to method
        inherited from SOAP::Server is called with the current value of the
        global array @INC, allowing the client to call any methods that can
        be found in the current valid search path. And as with most of the
        constructors in this module, the optional key/value pairs are
        treated as method names and parameters.

    send_receive
        The implementation of this method simply passes the envelope portion
        of the input data to the handle method of SOAP::Server. While no
        network traffic results (directly) from this, it allows for debug
        signals to be sent through the SOAP::Trace facility.

  SOAP::Transport::MAILTO
    This transport class manages SMTP-based sending of messages from a
    client perspective. It doesn't provide a server class. The class gets
    selected when a client object passes a URI to proxy or endpoint that
    starts with the characters, mailto:.

   SOAP::Transport::MAILTO::Client
    Inherits from: SOAP::Client.

    The client class for this protocol doesn't define any new methods. The
    constructor functions in the same style as the others class
    constructors. The functionality of the send_receive method is slightly
    different from other classes, however.

    When invoked, the send_receive method uses the MIME::Lite package to
    encapsulate and transmit the message. Because mail messages are one-way
    communications (the reply being a separate process), there is no
    response message to be returned by the method. Instead, all the
    status-related attributes (code, message, status, is_success) are set,
    and no value is explicitly returned.

  SOAP::Transport::POP3
    POP3 support is limited to a server implementation. Just as the MAILTO
    class detailed earlier operates by sending requests without expecting to
    process a response, the server described here accepts request messages
    and dispatches them without regard for sending a response other than
    that which POP3 defines for successful delivery of a message.

   SOAP::Transport::POP3::Server
    Inherits from: SOAP::Server.

    The new method of this class creates an object of the Net::POP3 class to
    use internally for polling a specified POP3 server for incoming
    messages. When an object of this class is created, it expects an
    endpoint to be specified with a URI that begins with the characters
    pop:// and includes user ID and password information as well as the
    hostname itself.

    The handle method takes the messages present in the remote mailbox and
    passes them (one at a time) to the superclass handle method. Each
    message is deleted after being routed. All messages in the POP3 mailbox
    are presumed to be SOAP messages.

    Methods for the Net::POP3 object are detected and properly routed,
    allowing operations such as $server->ping( ).

    This means that the endpoint string doesn't need to provide the user ID
    and password because the login method from the POP3 API may be used
    directly.

ACKNOWLEDGEMENTS
    Special thanks to O'Reilly publishing which has graciously allowed
    SOAP::Lite to republish and redistribute large excerpts from
    *Programming Web Services with Perl*, mainly the SOAP::Lite reference
    found in Appendix B.

COPYRIGHT
    Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

AUTHORS
    Paul Kulchenko (paulclinger AT yahoo.com)

    Randy J. Ray (rjray AT blackperl.com)

    Byrne Reese (byrne AT majordojo.com)