SOAP::Trace(3) User Contributed Perl Documentation SOAP::Trace(3)NAMESOAP::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 config-
ured 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 inter-
changeable. 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 call-
back, 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 STD-
OUT file descriptor. Callbacks should expect a one or more arguments
passed in, though the nature of the arguments varies based on the sig-
nal.
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 speci-
fied, 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 applica-
tion, 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 trig-
gered 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 trig-
gered 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 func-
tions. Not all the functions within the SOAP::Lite classes trigger
this signal. Those that do are primarily the highly visible func-
tions 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';
Or, the following will also do the trick:
use SOAP::Lite +trace;
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 Program-
ming 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@yahoo.com)
Randy J. Ray (rjray@blackperl.com)
Byrne Reese (byrne@majordojo.com)
perl v5.8.8 2006-08-16 SOAP::Trace(3)
