1# ====================================================================== 2# 3# Copyright (C) 2000-2003 Paul Kulchenko (paulclinger@yahoo.com) 4# SOAP::Lite is free software; you can redistribute it 5# and/or modify it under the same terms as Perl itself. 6# 7# $Id: Trace.pm,v 1.1 2004/10/12 18:47:55 byrnereese Exp $ 8# 9# ====================================================================== 10 11=pod 12 13=head1 NAME 14 15SOAP::Trace - used only to manage and manipulate the runtime tracing of execution within the toolkit 16 17=head1 DESCRIPTION 18 19This 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 configured and the ways of configuring them. 20 21=head1 SYNOPSIS 22 23Tracing 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 interchangeable. 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 callback, it is sufficient to list all of them first, followed finally by the callback, as in: 24 25 use SOAP::Lite +trace => 26 method => fault => \&message_level, 27 trace => objects => \&lower_level; 28 29In 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 STDOUT file descriptor. Callbacks should expect a one or more arguments passed in, though the nature of the arguments varies based on the signal. 30 31Any 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: 32 33 SOAP::Lite->import(+trace => all => -result => -parameters); 34 35If the keyword +trace (or +debug) is used without any signals specified, it enables all signals (as if all were implied). 36 37The signals and their meaning follow. Each also bears a note as to whether the signal is relevant to a server application, client application, or both. 38 39=head1 TRACE SIGNALS 40 41=over 42 43=item transport I<Client only> 44 45Triggered 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 L<HTTP::Request> object; for responses, it's a L<HTTP::Response> object. 46 47=item dispatch I<Server only> 48 49Triggered 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. 50 51=item result I<Server only> 52 53Triggered 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. 54 55=item parameters I<Server only> 56 57Triggered 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. 58 59=item headers I<Server only> 60 61This signal should be for triggering on the headers of an incoming message, but it isn't implemented as of SOAP::Lite 0.55. 62 63=item objects I<Client or server> 64 65Highlights when an object is instantiated or destroyed. It is triggered in the new and DESTROY methods of the various SOAP::Lite classes. 66 67=item method I<Client or server> 68 69Triggered with the list of arguments whenever the envelope method of L<SOAP::Serializer> is invoked with an initial argument of method. The initial string itself isn't passed to the callback. 70 71=item fault I<Client or server> 72 73As with the method signal earlier, except that this signal is triggered when SOAP::Serializer::envelope is called with an initial argument of fault. 74 75=item freeform I<Client or server> 76 77Like 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. 78 79=item trace I<Client or server> 80 81Triggered at the entry-point of many of the more-significant functions. Not all the functions within the SOAP::Lite classes trigger this signal. Those that do are primarily the highly visible functions described in the interface descriptions for the various classes. 82 83=item debug I<Client or server> 84 85Used 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. 86 87=back 88 89=head1 EXAMPLES 90 91=head2 SELECTING SIGNALS TO TRACE 92 93The following code snippet will enable tracing for all signals: 94 95 use SOAP::Lite +trace => 'all'; 96 97Or, the following will also do the trick: 98 99 use SOAP::Lite +trace; 100 101You 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: 102 103 use SOAP::Lite +trace => [ qw(all -transport) ]; 104 105=head2 LOGGING SIGNALS TO A FILE 106 107You 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: 108 109 use SOAP::Lite +trace => [ fault => \&log_faults ]; 110 111 sub log_faults { 112 open LOGFILE,">fault.log"; 113 print LOGFILE, $_[0] . "\n"; 114 close LOGFILE; 115 } 116 117You can also use a single callback for multiple signals using the code below: 118 119 use SOAP::Lite +trace => [ method, fault => \&log ]; 120 121=head2 LOGGING MESSAGE CONTENTS 122 123The 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: 124 125 use SOAP::Lite +trace => [ transport => &log_message ]; 126 127 sub log_message { 128 my ($in) = @_; 129 if (class($in) eq "HTTP::Request") { 130 # do something... 131 print $in->contents; # ...for example 132 } elsif (class($in) eq "HTTP::Response") { 133 # do something 134 } 135 } 136 137=head2 ON_DEBUG 138 139The C<on_debug> method is available, as in: 140 141 use SOAP::Lite; 142 my $client = SOAP::Lite 143 ->uri($NS) 144 ->proxy($HOST) 145 ->on_debug( sub { print @_; } ); 146 147=head1 ACKNOWLEDGEMENTS 148 149Special thanks to O'Reilly publishing which has graciously allowed SOAP::Lite to republish and redistribute large excerpts from I<Programming Web Services with Perl>, mainly the SOAP::Lite reference found in Appendix B. 150 151=head1 COPYRIGHT 152 153Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved. 154 155This library is free software; you can redistribute it and/or modify 156it under the same terms as Perl itself. 157 158=head1 AUTHORS 159 160Paul Kulchenko (paulclinger@yahoo.com) 161 162Randy J. Ray (rjray@blackperl.com) 163 164Byrne Reese (byrne@majordojo.com) 165 166=cut 167