1SOAP::Trace(3) User Contributed Perl Documentation SOAP::Trace(3)
2
6 SOAP::Trace - used only to manage and manipulate the runtime tracing of
7 execution within the toolkit
8
10 This class has no methods or objects. It is used only to manage and
11 manipulate the runtime tracing of execution within the toolkit. In
12 absence of methods, this section reviews the events that may be config‐
13 ured and the ways of configuring them.
14
16 Tracing is enabled by the SOAP::Lite import method. This is usually
17 done at compile-time, though it may be done explicitly by calling
18 import directly. The commands for setting up tracing start with the
19 keyword +trace. Alternately, +debug may be used; the two are inter‐
20 changeable. After the initial keyword, one or more of the signals
21 detailed here may be specified, optionally with a callback to handle
22 them. When specifying multiple signals to be handled by a single call‐
23 back, it is sufficient to list all of them first, followed finally by
24 the callback, as in:
25 use SOAP::Lite +trace =>
27 method => fault => \&message_level,
28 trace => objects => \&lower_level;
29 In the fragment, the reference to message_level is installed as the
31 callback for both method and fault signals, while lower_level is
32 installed for trace and object events. If callbacks aren't explicitly
33 provided, the default tracing action is to log a message to Perl's STD‐
34 OUT file descriptor. Callbacks should expect a one or more arguments
35 passed in, though the nature of the arguments varies based on the sig‐
36 nal.
37 Any signal can be disabled by prefacing the name with a hyphen, such as
39 -result. This is useful with the pseudosignal "all," which is shorthand
40 for the full list of signals. The following fragment disables only the
41 two signals, while still enabling the rest:
42 SOAP::Lite->import(+trace => all => -result => -parameters);
44 If the keyword +trace (or +debug) is used without any signals speci‐
46 fied, it enables all signals (as if all were implied).
47 The signals and their meaning follow. Each also bears a note as to
49 whether the signal is relevant to a server application, client applica‐
50 tion, or both.
51
53 transport Client only
54 Triggered in the transport layer just before a request is sent and
55 immediately after a response is received. Each time the signal is
56 sent, the sole argument to the callback is the relevant object. On
57 requests, this is a HTTP::Request object; for responses, it's a
58 HTTP::Response object.
59 dispatch Server only
61 Triggered with the full name of the method being dispatched, just
62 before execution is passed to it. It is currently disabled in
63 SOAP::Lite 0.55.
64 result Server only
66 Triggered after the method has been dispatched and is passed the
67 results returned from the method as a list. The result values have
68 not yet been serialized when this signal is sent.
69 parameters Server only
71 Triggered before a method call is actually dispatched, with the
72 data that is intended for the call itself. The parameters for the
73 method call are passed in as a list, after having been deserialized
74 into Perl data.
75 headers Server only
77 This signal should be for triggering on the headers of an incoming
78 message, but it isn't implemented as of SOAP::Lite 0.55.
79 objects Client or server
81 Highlights when an object is instantiated or destroyed. It is trig‐
82 gered in the new and DESTROY methods of the various SOAP::Lite
83 classes.
84 method Client or server
86 Triggered with the list of arguments whenever the envelope method
87 of SOAP::Serializer is invoked with an initial argument of method.
88 The initial string itself isn't passed to the callback.
89 fault Client or server
91 As with the method signal earlier, except that this signal is trig‐
92 gered when SOAP::Serializer::envelope is called with an initial
93 argument of fault.
94 freeform Client or server
96 Like the two previous, this signal is triggered when the method
97 SOAP::Serializer::envelope is called with an initial parameter of
98 freeform. This syntax is used when the method is creating
99 SOAP::Data objects from free-form input data.
100 trace Client or server
102 Triggered at the entry-point of many of the more-significant func‐
103 tions. Not all the functions within the SOAP::Lite classes trigger
104 this signal. Those that do are primarily the highly visible func‐
105 tions described in the interface descriptions for the various
106 classes.
107 debug Client or server
109 Used in the various transport modules to track the contents of
110 requests and responses (as ordinary strings, not as objects) at
111 different points along the way.
112
114 SELECTING SIGNALS TO TRACE
115 The following code snippet will enable tracing for all signals:
117 use SOAP::Lite +trace => 'all';
119 Or, the following will also do the trick:
121 use SOAP::Lite +trace;
123 You can disable tracing for a set of signals by prefixing the signal
125 name with a hyphen. Therefore, if you wish to enable tracing for every
126 signal EXCEPT transport signals, then you would use the code below:
127 use SOAP::Lite +trace => [ qw(all -transport) ];
129 LOGGING SIGNALS TO A FILE
131 You can optionally provide a subroutine or callback to each signal
133 trace you declare. Each time a signal is received, it is passed to the
134 corresponding subroutine. For example, the following code effectively
135 logs all fault signals to a file called fault.log:
136 use SOAP::Lite +trace => [ fault => \&log_faults ];
138 sub log_faults {
140 open LOGFILE,">fault.log";
141 print LOGFILE, $_[0] . "\n";
142 close LOGFILE;
143 }
144 You can also use a single callback for multiple signals using the code
146 below:
147 use SOAP::Lite +trace => [ method, fault => \&log ];
149 LOGGING MESSAGE CONTENTS
151 The transport signal is unique in the that the signal is not a text
153 string, but the actually HTTP::Request being sent (just prior to be
154 sent), or HTTP::Response object (immediately after it was received).
155 The following code sample shows how to make use of this:
156 use SOAP::Lite +trace => [ transport => &log_message ];
158 sub log_message {
160 my ($in) = @_;
161 if (class($in) eq "HTTP::Request") {
162 # do something...
163 print $in->contents; # ...for example
164 } elsif (class($in) eq "HTTP::Response") {
165 # do something
166 }
167 }
168 ON_DEBUG
170 The "on_debug" method is available, as in:
172 use SOAP::Lite;
174 my $client = SOAP::Lite
175 ->uri($NS)
176 ->proxy($HOST)
177 ->on_debug( sub { print @_; } );
178
180 Special thanks to O'Reilly publishing which has graciously allowed
181 SOAP::Lite to republish and redistribute large excerpts from Program‐
182 ming Web Services with Perl, mainly the SOAP::Lite reference found in
183 Appendix B.
184
186 Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.
187 This library is free software; you can redistribute it and/or modify it
189 under the same terms as Perl itself.
190
192 Paul Kulchenko (paulclinger@yahoo.com)
193 Randy J. Ray (rjray@blackperl.com)
195 Byrne Reese (byrne@majordojo.com)
197perl v5.8.8 2006-06-15 SOAP::Trace(3)