Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SOAP::Trace(3)	      User Contributed Perl Documentation	SOAP::Trace(3)

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

DESCRIPTION
       This 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.

SYNOPSIS
       Tracing 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:

	  use SOAP::Lite +trace	=>
	    method => fault => \&message_level,
	    trace => objects =>	\&lower_level;

       In 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.

       Any 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:

	   SOAP::Lite->import(+trace =>	all => -result => -parameters);

       If the keyword +trace (or +debug) is used without any signals
       specified, it enables all signals (as if	all were implied).

       The 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.

TRACE SIGNALS
       transport Client	only
	   Triggered 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 HTTP::Request object; for responses, it's a
	   HTTP::Response object.

       dispatch	Server only
	   Triggered 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.

       result Server only
	   Triggered 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.

       parameters Server only
	   Triggered 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.

       headers Server only
	   This	signal should be for triggering	on the headers of an incoming
	   message, but	it isn't implemented as	of SOAP::Lite 0.55.

       objects Client or server
	   Highlights when an object is	instantiated or	destroyed. It is
	   triggered in	the new	and DESTROY methods of the various SOAP::Lite
	   classes.

       method Client or	server
	   Triggered with the list of arguments	whenever the envelope method
	   of SOAP::Serializer is invoked with an initial argument of method.
	   The initial string itself isn't passed to the callback.

       fault Client or server
	   As with the method signal earlier, except that this signal is
	   triggered when SOAP::Serializer::envelope is	called with an initial
	   argument of fault.

       freeform	Client or server
	   Like	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.

       trace Client or server
	   Triggered 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.

       debug Client or server
	   Used	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.

EXAMPLES
   SELECTING SIGNALS TO	TRACE
       The following code snippet will enable tracing for all signals:

	 use SOAP::Lite	+trace => 'all';

       You 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:

	 use SOAP::Lite	+trace => [ qw(all -transport) ];

   LOGGING SIGNALS TO A	FILE
       You 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:

	 use SOAP::Lite	+trace => [ fault => \&log_faults ];

	 sub log_faults	{
	   open	LOGFILE,">fault.log";
	   print LOGFILE, $_[0]	. "\n";
	   close LOGFILE;
	 }

       You can also use	a single callback for multiple signals using the code
       below:

	 use SOAP::Lite	+trace => [ method, fault => \&log ];

   LOGGING MESSAGE CONTENTS
       The 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:

	 use SOAP::Lite	+trace => [ transport => \&log_message ];

	 sub log_message {
	   my ($in) = @_;
	   if (class($in) eq "HTTP::Request") {
	     # do something...
	     print $in->contents; # ...for example
	   } elsif (class($in) eq "HTTP::Response") {
	     # do something
	   }
	 }

   ON_DEBUG
       The "on_debug" method is	available, as in:

	 use SOAP::Lite;
	 my $client = SOAP::Lite
	   ->uri($NS)
	   ->proxy($HOST)
	   ->on_debug( sub { print @_; } );

ACKNOWLEDGEMENTS
       Special thanks to O'Reilly publishing which has graciously allowed
       SOAP::Lite to republish and redistribute	large excerpts from
       Programming Web Services	with Perl, mainly the SOAP::Lite reference
       found in	Appendix B.

COPYRIGHT
       Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

AUTHORS
       Paul Kulchenko (paulclinger@yahoo.com)

       Randy J.	Ray (rjray@blackperl.com)

       Byrne Reese (byrne@majordojo.com)

perl v5.32.0			  2018-05-14			SOAP::Trace(3)

NAME | DESCRIPTION | SYNOPSIS | TRACE SIGNALS | EXAMPLES | ACKNOWLEDGEMENTS | COPYRIGHT | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=SOAP::Trace&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help