SOAP::Server(3) User Contributed Perl Documentation SOAP::Server(3)NAMESOAP::Server - provides the basic framework for the transport-specific
server classes to build upon
DESCRIPTION
The SOAP::Server class provides the basic framework for the transport-
specific server classes to build upon. Note that in none of the code
examples provided with SOAP::Lite is this class used directly. Instead,
it is designed to be a superclass within more specific implementation
classes. The methods provided by SOAP::Server itself are:
METHODS
new(optional key/value pairs)
$server = SOAP::Server->new(%options);
Creates a new object of the class. Various default instance values
are set up, and like many of the constructors in this module, most
of the class methods described here may be passed in the
construction call by giving the name followed by the parameter (or
an array reference if there are multiple parameters).
action(optional new value)
$action = $server->action
Retrieves or sets the value of the action attribute on the server
object. This attribute is used when mapping the request to an
appropriate namespace or routine. For example, the HTTP library
sets the attribute to the value of the SOAPAction header when
processing of the request begins, so that the find_target method
described later may retrieve the value to match it against the
server's configuration. Returns the object itself when setting the
attribute.
myuri(optional new value)
$server->myuri("http://localhost:9000/SOAP");
Gets or sets the myuri attribute. This specifies the specific URI
that the server is answering requests to (which may be different
from the value specified in action or in the SOAPAction header).
serializer(optional new value)
deserializer(optional new value)
$serializer = $server->serializer;
$server->deserializer($new_deser_obj);
As with the client objects, these methods provide direct access to
the serialization and deserialization objects the server object
uses to transform input and output from and to XML. There is
generally little or no need to explicitly set these to new values.
options(optional new value)
$server->options({compress_threshold => 10000});
Sets (or retrieves) the current server options as a hash-table
reference. At present, only one option is used within the
SOAP::Lite libraries themselves:
compress_threshold
The value of this option is expected to be a numerical value.
If set, and if the Compress::Zlib library is available to use,
messages whose size in bytes exceeds this value are compressed
for transmission. Both ends of the conversation have to support
this and have it enabled.
Other options may be defined and passed around using this
mechanism. Note that setting the options using this accessor
requires a full hash reference be passed. To set just one or a few
values, retrieve the current reference value and use it to set the
key(s).
dispatch_with(optional new value)
$server->dispatch_with($new_table);
Represents one of two ways in which a SOAP::Server (or derived)
object may specify mappings of incoming requests to server-side
subroutines or namespaces. The value of the attribute is a hash-
table reference. To set the attribute, you must pass a new hash
reference. The hash table's keys are URI strings (literal URIs or
the potential values of the SOAPAction header), and the
corresponding values are one of a class name or an object
reference. Requests that come in for a URI found in the table are
routed to the specified class or through the specified object.
dispatch_to(optional list of new values)
$server->dispatch_to($dir, 'Module', 'Mod::meth');
This is the more traditional way to specify modules and packages
for routing requests. This is also an accessor, but it returns a
list of values when called with no arguments (rather than a single
one). Each item in the list of values passed to this method is
expected to be one of four things:
Directory path
If the value is a directory path, all modules located in that
path are available for remote use.
Package name
When the value is a package name (without including a specific
method name), all routines within the package are available
remotely.
Fully qualified method name
Alternately, when the value is a package-qualified name of a
subroutine or method, that specific routine is made available.
This allows the server to make selected methods available
without opening the entire package.
Object reference
If the value is an object reference, the object itself routes
the request.
The list of values held by the dispatch_to table are compared
only after the URI mapping table from the dispatch_with
attribute has been consulted. If the request's URI or
SOAPAction header don't map to a specific configuration, the
path specified by the action header (or in absence, the URI) is
converted to a package name and compared against this set of
values.
objects_by_reference(optional list of new values)
$server->objects_by_reference(qw(My:: Class));
This also returns a list of values when retrieving the current
attribute value, as opposed to a single value.
This method doesn't directly specify classes for request routing so
much as it modifies the behavior of the routing for the specified
classes. The classes that are given as arguments to this method are
marked to be treated as producing persistent objects. The client is
given an object representation that contains just a handle on a
local object with a default persistence of 600 idle seconds. Each
operation on the object resets the idle timer to zero. This
facility is considered experimental in the current version of
SOAP::Lite.
A global variable/"constant" allows developers to specify the
amount of time an object will be persisted. The default value is
600 idle seconds. This value can be changed using the following
code:
$SOAP::Constants::OBJS_BY_REF_KEEPALIVE = 1000;
on_action(optional new value)
$server->on_action(sub { ...new code });
Gets or sets the reference to a subroutine that is used for
executing the on_action hook. Where the client code uses this hook
to construct the action-request data (such as for a SOAPAction
header), the server uses the on_action hook to do any last-minute
tests on the request itself, before it gets routed to a final
destination. When called, the hook routine is passed three
arguments:
action
The action URI itself, retrieved from the action method
described earlier.
method_uri
The URI of the XML namespace the method name is labeled with.
method_name
The name of the method being called by the request.
on_dispatch(optional new value)
($uri, $name) = $server->on_dispatch->($request);
Gets or sets the subroutine reference used for the on_dispatch
hook. This hook is called at the start of the request-routing phase
and is given a single argument when called:
request
An object of the SOAP::SOM class, containing the deserialized
request from the client.
find_target
($class, $uri, $name) = $server->find_target($req)
Taking as its argument an object of the SOAP::SOM class that
contains the deserialized request, this method returns a three-
element list describing the method that is to be called. The
elements are:
class
The class into which the method call should be made. This may
come back as either a string or an objectreference, if the
dispatching is configured using an object instance.
uri The URN associated with the request method. This is the value
that was used when configuring the method routing on the server
object.
name
The name of the method to call.
handle
$server->handle($request_text);
Implements the main functionality of the serving process, in which
the server takes an incoming request and dispatches it to the
correct server-side subroutine. The parameter taken as input is
either plain XML or MIME-encoded content (if MIME-encoding support
is enabled).
make_fault
return $server->makefault($code, $message);
Creates a SOAP::Fault object from the data passed in. The order of
arguments is: code, message, detail, actor. The first two are
required (because they must be present in all faults), but the last
two may be omitted unless needed.
SOAP::Server::Parameters
This class provides two methods, but the primary purpose from the
developer's point of view is to allow classes that a SOAP server
exposes to inherit from it. When a class inherits from the
SOAP::Server::Parameters class, the list of parameters passed to a
called method includes the deserialized request in the form of a
SOAP::SOM object. This parameter is passed at the end of the arguments
list, giving methods the option of ignoring it unless it is needed.
The class provides two subroutines (not methods), for retrieving
parameters from the SOAP::SOM object. These are designed to be called
without an object reference in the parameter list, but with an array
reference instead (as the first parameter). The remainder of the
arguments list is expected to be the list from the method-call itself,
including the SOAP::SOM object at the end of the list. The routines may
be useful to understand if an application wishes to subclass
SOAP::Server::Parameters and inherit from the new class instead.
byNameOrOrder(order, parameter list, envelope)
@args = SOAP::Server::Parameters::byNameOrOrder ([qw(a b)], @_);
Using the list of argument names passed in the initial argument as
an array reference, this routine returns a list of the parameter
values for the parameters matching those names, in that order. If
none of the names given in the initial array-reference exist in the
parameter list, the values are returned in the order in which they
already appear within the list of parameters. In this case, the
number of returned values may differ from the length of the
requested-parameters list.
byName(order, parameter list, envelope)
@args = SOAP::Server::Parameters::byName ([qw(a b c)], @_);
Acts in a similar manner to the previous, with the difference that
it always returns as many values as requested, even if some (or
all) don't exist. Parameters that don't exist in the parameter list
are returned as undef values.
EXAMPLE
The following is an example CGI based Web Service that utilizes a Perl
module that inherits from the "SOAP::Server::Parameters" class. This
allows the methods of that class to access its input by name.
#!/usr/bin/perl
use SOAP::Transport::HTTP;
SOAP::Transport::HTTP::CGI
->dispatch_to('C2FService')
->handle;
BEGIN {
package C2FService;
use vars qw(@ISA);
@ISA = qw(Exporter SOAP::Server::Parameters);
use SOAP::Lite;
sub c2f {
my $self = shift;
my $envelope = pop;
my $temp = $envelope->dataof("//c2f/temperature");
return SOAP::Data->name('convertedTemp' => (((9/5)*($temp->value)) + 32));
}
}
SEE ALSO
SOAP::SOM, SOAP::Transport::HTTP
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.14.1 2010-06-03 SOAP::Server(3)
