1SOAP::Trace(3)        User Contributed Perl Documentation       SOAP::Trace(3)
2
3
4

NAME

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

DESCRIPTION

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

SYNOPSIS

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
26          use SOAP::Lite +trace =>
27            method => fault => \&message_level,
28            trace => objects => \&lower_level;
29
30       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
38       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
43           SOAP::Lite->import(+trace => all => -result => -parameters);
44
45       If the keyword +trace (or +debug) is used without any signals
46       specified, it enables all signals (as if all were implied).
47
48       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

TRACE SIGNALS

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
60       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
65       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
70       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
76       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
80       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
85       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
90       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
95       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
101       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
108       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

EXAMPLES

114   SELECTING SIGNALS TO TRACE
115       The following code snippet will enable tracing for all signals:
116
117         use SOAP::Lite +trace => 'all';
118
119       You can disable tracing for a set of signals by prefixing the signal
120       name with a hyphen. Therefore, if you wish to enable tracing for every
121       signal EXCEPT transport signals, then you would use the code below:
122
123         use SOAP::Lite +trace => [ qw(all -transport) ];
124
125   LOGGING SIGNALS TO A FILE
126       You can optionally provide a subroutine or callback to each signal
127       trace you declare. Each time a signal is received, it is passed to the
128       corresponding subroutine. For example, the following code effectively
129       logs all fault signals to a file called fault.log:
130
131         use SOAP::Lite +trace => [ fault => \&log_faults ];
132
133         sub log_faults {
134           open LOGFILE,">fault.log";
135           print LOGFILE, $_[0] . "\n";
136           close LOGFILE;
137         }
138
139       You can also use a single callback for multiple signals using the code
140       below:
141
142         use SOAP::Lite +trace => [ method, fault => \&log ];
143
144   LOGGING MESSAGE CONTENTS
145       The transport signal is unique in the that the signal is not a text
146       string, but the actually HTTP::Request being sent (just prior to be
147       sent), or HTTP::Response object (immediately after it was received).
148       The following code sample shows how to make use of this:
149
150         use SOAP::Lite +trace => [ transport => \&log_message ];
151
152         sub log_message {
153           my ($in) = @_;
154           if (class($in) eq "HTTP::Request") {
155             # do something...
156             print $in->contents; # ...for example
157           } elsif (class($in) eq "HTTP::Response") {
158             # do something
159           }
160         }
161
162   ON_DEBUG
163       The "on_debug" method is available, as in:
164
165         use SOAP::Lite;
166         my $client = SOAP::Lite
167           ->uri($NS)
168           ->proxy($HOST)
169           ->on_debug( sub { print @_; } );
170

ACKNOWLEDGEMENTS

172       Special thanks to O'Reilly publishing which has graciously allowed
173       SOAP::Lite to republish and redistribute large excerpts from
174       Programming Web Services with Perl, mainly the SOAP::Lite reference
175       found in Appendix B.
176
178       Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.
179
180       This library is free software; you can redistribute it and/or modify it
181       under the same terms as Perl itself.
182

AUTHORS

184       Paul Kulchenko (paulclinger@yahoo.com)
185
186       Randy J. Ray (rjray@blackperl.com)
187
188       Byrne Reese (byrne@majordojo.com)
189
190
191
192perl v5.36.0                      2023-01-20                    SOAP::Trace(3)
Impressum