On Apache
Under GNU General Public License
2024-12-13 00:32 @3.149.228.18 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
SOAP::Trace(3pm) User Contributed Perl Documentation SOAP::Trace(3pm)
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)
perl v5.26.2 2018-05-18 SOAP::Trace(3pm)
Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2024-12-13 00:32 @3.149.228.18 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)