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
13 configured 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
20 interchangeable. 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
23 callback, it is sufficient to list all of them first, followed finally
24 by 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
34 STDOUT file descriptor. Callbacks should expect a one or more arguments
35 passed in, though the nature of the arguments varies based on the
36 signal.
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
46 specified, 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
50 application, 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
82 triggered 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
92 triggered 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
103 functions. Not all the functions within the SOAP::Lite classes
104 trigger this signal. Those that do are primarily the highly visible
105 functions 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:
116 use SOAP::Lite +trace => 'all';
118 Or, the following will also do the trick:
120 use SOAP::Lite +trace;
122 You can disable tracing for a set of signals by prefixing the signal
124 name with a hyphen. Therefore, if you wish to enable tracing for every
125 signal EXCEPT transport signals, then you would use the code below:
126 use SOAP::Lite +trace => [ qw(all -transport) ];
128 LOGGING SIGNALS TO A FILE
130 You can optionally provide a subroutine or callback to each signal
131 trace you declare. Each time a signal is received, it is passed to the
132 corresponding subroutine. For example, the following code effectively
133 logs all fault signals to a file called fault.log:
134 use SOAP::Lite +trace => [ fault => \&log_faults ];
136 sub log_faults {
138 open LOGFILE,">fault.log";
139 print LOGFILE, $_[0] . "\n";
140 close LOGFILE;
141 }
142 You can also use a single callback for multiple signals using the code
144 below:
145 use SOAP::Lite +trace => [ method, fault => \&log ];
147 LOGGING MESSAGE CONTENTS
149 The transport signal is unique in the that the signal is not a text
150 string, but the actually HTTP::Request being sent (just prior to be
151 sent), or HTTP::Response object (immediately after it was received).
152 The following code sample shows how to make use of this:
153 use SOAP::Lite +trace => [ transport => &log_message ];
155 sub log_message {
157 my ($in) = @_;
158 if (class($in) eq "HTTP::Request") {
159 # do something...
160 print $in->contents; # ...for example
161 } elsif (class($in) eq "HTTP::Response") {
162 # do something
163 }
164 }
165 ON_DEBUG
167 The "on_debug" method is available, as in:
168 use SOAP::Lite;
170 my $client = SOAP::Lite
171 ->uri($NS)
172 ->proxy($HOST)
173 ->on_debug( sub { print @_; } );
174
176 Special thanks to O'Reilly publishing which has graciously allowed
177 SOAP::Lite to republish and redistribute large excerpts from
178 Programming Web Services with Perl, mainly the SOAP::Lite reference
179 found in Appendix B.
180
182 Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.
183 This library is free software; you can redistribute it and/or modify it
185 under the same terms as Perl itself.
186
188 Paul Kulchenko (paulclinger@yahoo.com)
189 Randy J. Ray (rjray@blackperl.com)
191 Byrne Reese (byrne@majordojo.com)
193perl v5.12.3 2010-06-03 SOAP::Trace(3)