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       Or, the following will also do the trick:
120
121         use SOAP::Lite +trace;
122
123       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
127         use SOAP::Lite +trace => [ qw(all -transport) ];
128
129   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
135         use SOAP::Lite +trace => [ fault => \&log_faults ];
136
137         sub log_faults {
138           open LOGFILE,">fault.log";
139           print LOGFILE, $_[0] . "\n";
140           close LOGFILE;
141         }
142
143       You can also use a single callback for multiple signals using the code
144       below:
145
146         use SOAP::Lite +trace => [ method, fault => \&log ];
147
148   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
154         use SOAP::Lite +trace => [ transport => &log_message ];
155
156         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
166   ON_DEBUG
167       The "on_debug" method is available, as in:
168
169         use SOAP::Lite;
170         my $client = SOAP::Lite
171           ->uri($NS)
172           ->proxy($HOST)
173           ->on_debug( sub { print @_; } );
174

ACKNOWLEDGEMENTS

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
184       This library is free software; you can redistribute it and/or modify it
185       under the same terms as Perl itself.
186

AUTHORS

188       Paul Kulchenko (paulclinger@yahoo.com)
189
190       Randy J. Ray (rjray@blackperl.com)
191
192       Byrne Reese (byrne@majordojo.com)
193
194
195
196perl v5.12.3                      2010-06-03                    SOAP::Trace(3)
Impressum