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

NAME

6       SOAP::Server - provides the basic framework for the transport-specific
7       server classes to build upon
8

DESCRIPTION

10       The SOAP::Server class provides the basic framework for the transport-
11       specific server classes to build upon. Note that in none of the code
12       examples provided with SOAP::Lite is this class used directly. Instead,
13       it is designed to be a superclass within more specific implementation
14       classes. The methods provided by SOAP::Server itself are:
15

METHODS

17       new(optional key/value pairs)
18               $server = SOAP::Server->new(%options);
19
20           Creates a new object of the class. Various default instance values
21           are set up, and like many of the constructors in this module, most
22           of the class methods described here may be passed in the
23           construction call by giving the name followed by the parameter (or
24           an array reference if there are multiple parameters).
25
26       action(optional new value)
27               $action = $server->action
28
29           Retrieves or sets the value of the action attribute on the server
30           object. This attribute is used when mapping the request to an
31           appropriate namespace or routine. For example, the HTTP library
32           sets the attribute to the value of the SOAPAction header when
33           processing of the request begins, so that the find_target method
34           described later may retrieve the value to match it against the
35           server's configuration. Returns the object itself when setting the
36           attribute.
37
38       myuri(optional new value)
39               $server->myuri("http://localhost:9000/SOAP");
40
41           Gets or sets the myuri attribute. This specifies the specific URI
42           that the server is answering requests to (which may be different
43           from the value specified in action or in the SOAPAction header).
44
45       serializer(optional new value)
46       deserializer(optional new value)
47               $serializer = $server->serializer;
48               $server->deserializer($new_deser_obj);
49
50           As with the client objects, these methods provide direct access to
51           the serialization and deserialization objects the server object
52           uses to transform input and output from and to XML. There is
53           generally little or no need to explicitly set these to new values.
54
55       options(optional new value)
56               $server->options({compress_threshold => 10000});
57
58           Sets (or retrieves) the current server options as a hash-table
59           reference. At present, only one option is used within the
60           SOAP::Lite libraries themselves:
61
62           compress_threshold
63               The value of this option is expected to be a numerical value.
64               If set, and if the Compress::Zlib library is available to use,
65               messages whose size in bytes exceeds this value are compressed
66               for transmission. Both ends of the conversation have to support
67               this and have it enabled.
68
69           Other options may be defined and passed around using this
70           mechanism. Note that setting the options using this accessor
71           requires a full hash reference be passed. To set just one or a few
72           values, retrieve the current reference value and use it to set the
73           key(s).
74
75       dispatch_with(optional new value)
76               $server->dispatch_with($new_table);
77
78           Represents one of two ways in which a SOAP::Server (or derived)
79           object may specify mappings of incoming requests to server-side
80           subroutines or namespaces. The value of the attribute is a hash-
81           table reference. To set the attribute, you must pass a new hash
82           reference. The hash table's keys are URI strings (literal URIs or
83           the potential values of the SOAPAction header), and the
84           corresponding values are one of a class name or an object
85           reference. Requests that come in for a URI found in the table are
86           routed to the specified class or through the specified object.
87
88       dispatch_to(optional list of new values)
89               $server->dispatch_to($dir, 'Module', 'Mod::meth');
90
91           This is the more traditional way to specify modules and packages
92           for routing requests. This is also an accessor, but it returns a
93           list of values when called with no arguments (rather than a single
94           one). Each item in the list of values passed to this method is
95           expected to be one of four things:
96
97           Directory path
98               If the value is a directory path, all modules located in that
99               path are available for remote use.
100
101           Package name
102               When the value is a package name (without including a specific
103               method name), all routines within the package are available
104               remotely.
105
106           Fully qualified method name
107               Alternately, when the value is a package-qualified name of a
108               subroutine or method, that specific routine is made available.
109               This allows the server to make selected methods available
110               without opening the entire package.
111
112           Object reference
113               If the value is an object reference, the object itself routes
114               the request.
115
116               The list of values held by the dispatch_to table are compared
117               only after the URI mapping table from the dispatch_with
118               attribute has been consulted. If the request's URI or
119               SOAPAction header don't map to a specific configuration, the
120               path specified by the action header (or in absence, the URI) is
121               converted to a package name and compared against this set of
122               values.
123
124       objects_by_reference(optional list of new values)
125               $server->objects_by_reference(qw(My:: Class));
126
127           This also returns a list of values when retrieving the current
128           attribute value, as opposed to a single value.
129
130           This method doesn't directly specify classes for request routing so
131           much as it modifies the behavior of the routing for the specified
132           classes. The classes that are given as arguments to this method are
133           marked to be treated as producing persistent objects. The client is
134           given an object representation that contains just a handle on a
135           local object with a default persistence of 600 idle seconds.  Each
136           operation on the object resets the idle timer to zero. This
137           facility is considered experimental in the current version of
138           SOAP::Lite.
139
140           A global variable/"constant" allows developers to specify the
141           amount of time an object will be persisted. The default value is
142           600 idle seconds. This value can be changed using the following
143           code:
144
145             $SOAP::Constants::OBJS_BY_REF_KEEPALIVE = 1000;
146
147       on_action(optional new value)
148               $server->on_action(sub { ...new code });
149
150           Gets or sets the reference to a subroutine that is used for
151           executing the on_action hook. Where the client code uses this hook
152           to construct the action-request data (such as for a SOAPAction
153           header), the server uses the on_action hook to do any last-minute
154           tests on the request itself, before it gets routed to a final
155           destination. When called, the hook routine is passed three
156           arguments:
157
158           action
159               The action URI itself, retrieved from the action method
160               described earlier.
161
162           method_uri
163               The URI of the XML namespace the method name is labeled with.
164
165           method_name
166               The name of the method being called by the request.
167
168       on_dispatch(optional new value)
169               ($uri, $name) = $server->on_dispatch->($request);
170
171           Gets or sets the subroutine reference used for the on_dispatch
172           hook. This hook is called at the start of the request-routing phase
173           and is given a single argument when called:
174
175           request
176               An object of the SOAP::SOM class, containing the deserialized
177               request from the client.
178
179       find_target
180               ($class, $uri, $name) = $server->find_target($req)
181
182           Taking as its argument an object of the SOAP::SOM class that
183           contains the deserialized request, this method returns a three-
184           element list describing the method that is to be called. The
185           elements are:
186
187           class
188               The class into which the method call should be made. This may
189               come back as either a string or an objectreference, if the
190               dispatching is configured using an object instance.
191
192           uri The URN associated with the request method. This is the value
193               that was used when configuring the method routing on the server
194               object.
195
196           name
197               The name of the method to call.
198
199       handle
200               $server->handle($request_text);
201
202           Implements the main functionality of the serving process, in which
203           the server takes an incoming request and dispatches it to the
204           correct server-side subroutine. The parameter taken as input is
205           either plain XML or MIME-encoded content (if MIME-encoding support
206           is enabled).
207
208       make_fault
209               return $server->makefault($code, $message);
210
211           Creates a SOAP::Fault object from the data passed in. The order of
212           arguments is: code, message, detail, actor. The first two are
213           required (because they must be present in all faults), but the last
214           two may be omitted unless needed.
215
216   SOAP::Server::Parameters
217       This class provides two methods, but the primary purpose from the
218       developer's point of view is to allow classes that a SOAP server
219       exposes to inherit from it. When a class inherits from the
220       SOAP::Server::Parameters class, the list of parameters passed to a
221       called method includes the deserialized request in the form of a
222       SOAP::SOM object. This parameter is passed at the end of the arguments
223       list, giving methods the option of ignoring it unless it is needed.
224
225       The class provides two subroutines (not methods), for retrieving
226       parameters from the SOAP::SOM object. These are designed to be called
227       without an object reference in the parameter list, but with an array
228       reference instead (as the first parameter). The remainder of the
229       arguments list is expected to be the list from the method-call itself,
230       including the SOAP::SOM object at the end of the list. The routines may
231       be useful to understand if an application wishes to subclass
232       SOAP::Server::Parameters and inherit from the new class instead.
233
234       byNameOrOrder(order, parameter list, envelope)
235               @args = SOAP::Server::Parameters::byNameOrOrder ([qw(a b)], @_);
236
237           Using the list of argument names passed in the initial argument as
238           an array reference, this routine returns a list of the parameter
239           values for the parameters matching those names, in that order. If
240           none of the names given in the initial array-reference exist in the
241           parameter list, the values are returned in the order in which they
242           already appear within the list of parameters. In this case, the
243           number of returned values may differ from the length of the
244           requested-parameters list.
245
246       byName(order, parameter list, envelope)
247               @args = SOAP::Server::Parameters::byName ([qw(a b c)], @_);
248
249           Acts in a similar manner to the previous, with the difference that
250           it always returns as many values as requested, even if some (or
251           all) don't exist. Parameters that don't exist in the parameter list
252           are returned as undef values.
253
254       EXAMPLE
255
256       The following is an example CGI based Web Service that utilizes a Perl
257       module that inherits from the "SOAP::Server::Parameters" class. This
258       allows the methods of that class to access its input by name.
259
260           #!/usr/bin/perl
261           use SOAP::Transport::HTTP;
262           SOAP::Transport::HTTP::CGI
263             ->dispatch_to('C2FService')
264             ->handle;
265           BEGIN {
266             package C2FService;
267             use vars qw(@ISA);
268             @ISA = qw(Exporter SOAP::Server::Parameters);
269             use SOAP::Lite;
270             sub c2f {
271               my $self = shift;
272               my $envelope = pop;
273               my $temp = $envelope->dataof("//c2f/temperature");
274               return SOAP::Data->name('convertedTemp' => (((9/5)*($temp->value)) + 32));
275             }
276           }
277

SEE ALSO

279       SOAP::SOM, SOAP::Transport::HTTP
280

ACKNOWLEDGEMENTS

282       Special thanks to O'Reilly publishing which has graciously allowed
283       SOAP::Lite to republish and redistribute large excerpts from
284       Programming Web Services with Perl, mainly the SOAP::Lite reference
285       found in Appendix B.
286
288       Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.
289
290       This library is free software; you can redistribute it and/or modify it
291       under the same terms as Perl itself.
292

AUTHORS

294       Paul Kulchenko (paulclinger@yahoo.com)
295
296       Randy J. Ray (rjray@blackperl.com)
297
298       Byrne Reese (byrne@majordojo.com)
299
300
301
302perl v5.32.1                      2021-01-27                   SOAP::Server(3)
Impressum