SOAP::Trace - phpMan

NAME
    SOAP::Trace - used only to manage and manipulate the runtime tracing of
    execution within the toolkit

DESCRIPTION
    This class has no methods or objects. It is used only to manage and
    manipulate the runtime tracing of execution within the toolkit. In
    absence of methods, this section reviews the events that may be
    configured and the ways of configuring them.

SYNOPSIS
    Tracing is enabled by the SOAP::Lite import method. This is usually done
    at compile-time, though it may be done explicitly by calling import
    directly. The commands for setting up tracing start with the keyword
    +trace. Alternately, +debug may be used; the two are interchangeable.
    After the initial keyword, one or more of the signals detailed here may
    be specified, optionally with a callback to handle them. When specifying
    multiple signals to be handled by a single callback, it is sufficient to
    list all of them first, followed finally by the callback, as in:

       use SOAP::Lite +trace =>
         method => fault => \&message_level,
         trace => objects => \&lower_level;

    In the fragment, the reference to message_level is installed as the
    callback for both method and fault signals, while lower_level is
    installed for trace and object events. If callbacks aren't explicitly
    provided, the default tracing action is to log a message to Perl's
    STDOUT file descriptor. Callbacks should expect a one or more arguments
    passed in, though the nature of the arguments varies based on the
    signal.

    Any signal can be disabled by prefacing the name with a hyphen, such as
    -result. This is useful with the pseudosignal "all," which is shorthand
    for the full list of signals. The following fragment disables only the
    two signals, while still enabling the rest:

        SOAP::Lite->import(+trace => all => -result => -parameters);

    If the keyword +trace (or +debug) is used without any signals specified,
    it enables all signals (as if all were implied).

    The signals and their meaning follow. Each also bears a note as to
    whether the signal is relevant to a server application, client
    application, or both.

TRACE SIGNALS
    transport *Client only*
        Triggered in the transport layer just before a request is sent and
        immediately after a response is received. Each time the signal is
        sent, the sole argument to the callback is the relevant object. On
        requests, this is a HTTP::Request object; for responses, it's a
        HTTP::Response object.

    dispatch *Server only*
        Triggered with the full name of the method being dispatched, just
        before execution is passed to it. It is currently disabled in
        SOAP::Lite 0.55.

    result *Server only*
        Triggered after the method has been dispatched and is passed the
        results returned from the method as a list. The result values have
        not yet been serialized when this signal is sent.

    parameters *Server only*
        Triggered before a method call is actually dispatched, with the data
        that is intended for the call itself. The parameters for the method
        call are passed in as a list, after having been deserialized into
        Perl data.

    headers *Server only*
        This signal should be for triggering on the headers of an incoming
        message, but it isn't implemented as of SOAP::Lite 0.55.

    objects *Client or server*
        Highlights when an object is instantiated or destroyed. It is
        triggered in the new and DESTROY methods of the various SOAP::Lite
        classes.

    method *Client or server*
        Triggered with the list of arguments whenever the envelope method of
        SOAP::Serializer is invoked with an initial argument of method. The
        initial string itself isn't passed to the callback.

    fault *Client or server*
        As with the method signal earlier, except that this signal is
        triggered when SOAP::Serializer::envelope is called with an initial
        argument of fault.

    freeform *Client or server*
        Like the two previous, this signal is triggered when the method
        SOAP::Serializer::envelope is called with an initial parameter of
        freeform. This syntax is used when the method is creating SOAP::Data
        objects from free-form input data.

    trace *Client or server*
        Triggered at the entry-point of many of the more-significant
        functions. Not all the functions within the SOAP::Lite classes
        trigger this signal. Those that do are primarily the highly visible
        functions described in the interface descriptions for the various
        classes.

    debug *Client or server*
        Used in the various transport modules to track the contents of
        requests and responses (as ordinary strings, not as objects) at
        different points along the way.

EXAMPLES
  SELECTING SIGNALS TO TRACE
    The following code snippet will enable tracing for all signals:

      use SOAP::Lite +trace => 'all';

    You can disable tracing for a set of signals by prefixing the signal
    name with a hyphen. Therefore, if you wish to enable tracing for every
    signal EXCEPT transport signals, then you would use the code below:

      use SOAP::Lite +trace => [ qw(all -transport) ];

  LOGGING SIGNALS TO A FILE
    You can optionally provide a subroutine or callback to each signal trace
    you declare. Each time a signal is received, it is passed to the
    corresponding subroutine. For example, the following code effectively
    logs all fault signals to a file called fault.log:

      use SOAP::Lite +trace => [ fault => \&log_faults ];

      sub log_faults {
        open LOGFILE,">fault.log";
        print LOGFILE, $_[0] . "\n";
        close LOGFILE;
      }

    You can also use a single callback for multiple signals using the code
    below:

      use SOAP::Lite +trace => [ method, fault => \&log ];

  LOGGING MESSAGE CONTENTS
    The transport signal is unique in the that the signal is not a text
    string, but the actually HTTP::Request being sent (just prior to be
    sent), or HTTP::Response object (immediately after it was received). The
    following code sample shows how to make use of this:

      use SOAP::Lite +trace => [ transport => \&log_message ];

      sub log_message {
        my ($in) = @_;
        if (class($in) eq "HTTP::Request") {
          # do something...
          print $in->contents; # ...for example
        } elsif (class($in) eq "HTTP::Response") {
          # do something
        }
      }

  ON_DEBUG
    The "on_debug" method is available, as in:

      use SOAP::Lite;
      my $client = SOAP::Lite
        ->uri($NS)
        ->proxy($HOST)
        ->on_debug( sub { print @_; } );

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)