1SOAP::Server(3) User Contributed Perl Documentation SOAP::Server(3)
2
6 SOAP::Server - provides the basic framework for the transport-specific
7 server classes to build upon
8
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
17 new(optional key/value pairs)
18 $server = SOAP::Server->new(%options);
19 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 construc‐
23 tion call by giving the name followed by the parameter (or an array
24 reference if there are multiple parameters).
25 action(optional new value)
27 $action = $server->action
28 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 pro‐
33 cessing 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 myuri(optional new value)
39 $server->myuri("http://localhost:9000/SOAP");
40 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 serializer(optional new value)
46 deserializer(optional new value)
47 $serializer = $server->serializer;
48 $server->deserializer($new_deser_obj);
49 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 gener‐
53 ally little or no need to explicitly set these to new values.
54 options(optional new value)
56 $server->options({compress_threshold => 10000});
57 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 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 Other options may be defined and passed around using this mecha‐
70 nism. Note that setting the options using this accessor requires a
71 full hash reference be passed. To set just one or a few values,
72 retrieve the current reference value and use it to set the key(s).
73 dispatch_with(optional new value)
75 $server->dispatch_with($new_table);
76 Represents one of two ways in which a SOAP::Server (or derived)
78 object may specify mappings of incoming requests to server-side
79 subroutines or namespaces. The value of the attribute is a hash-ta‐
80 ble reference. To set the attribute, you must pass a new hash ref‐
81 erence. The hash table's keys are URI strings (literal URIs or the
82 potential values of the SOAPAction header), and the corresponding
83 values are one of a class name or an object reference. Requests
84 that come in for a URI found in the table are routed to the speci‐
85 fied class or through the specified object.
86 dispatch_to(optional list of new values)
88 $server->dispatch_to($dir, 'Module', 'Mod::meth');
89 This is the more traditional way to specify modules and packages
91 for routing requests. This is also an accessor, but it returns a
92 list of values when called with no arguments (rather than a single
93 one). Each item in the list of values passed to this method is
94 expected to be one of four things:
95 Directory path
97 If the value is a directory path, all modules located in that
98 path are available for remote use.
99 Package name
101 When the value is a package name (without including a specific
102 method name), all routines within the package are available
103 remotely.
104 Fully qualified method name
106 Alternately, when the value is a package-qualified name of a
107 subroutine or method, that specific routine is made available.
108 This allows the server to make selected methods available with‐
109 out opening the entire package.
110 Object reference
112 If the value is an object reference, the object itself routes
113 the request.
114 The list of values held by the dispatch_to table are compared
116 only after the URI mapping table from the dispatch_with
117 attribute has been consulted. If the request's URI or SOA‐
118 PAction header don't map to a specific configuration, the path
119 specified by the action header (or in absence, the URI) is con‐
120 verted to a package name and compared against this set of val‐
121 ues.
122 objects_by_reference(optional list of new values)
124 $server->objects_by_reference(qw(My:: Class));
125 This also returns a list of values when retrieving the current
127 attribute value, as opposed to a single value.
128 This method doesn't directly specify classes for request routing so
130 much as it modifies the behavior of the routing for the specified
131 classes. The classes that are given as arguments to this method are
132 marked to be treated as producing persistent objects. The client is
133 given an object representation that contains just a handle on a
134 local object with a default persistence of 600 idle seconds. Each
135 operation on the object resets the idle timer to zero. This facil‐
136 ity is considered experimental in the current version of
137 SOAP::Lite.
138 A global variable/"constant" allows developers to specify the
140 amount of time an object will be persisted. The default value is
141 600 idle seconds. This value can be changed using the following
142 code:
143 $SOAP::Constants::OBJS_BY_REF_KEEPALIVE = 1000;
145 on_action(optional new value)
147 $server->on_action(sub { ...new code });
148 Gets or sets the reference to a subroutine that is used for execut‐
150 ing the on_action hook. Where the client code uses this hook to
151 construct the action-request data (such as for a SOAPAction
152 header), the server uses the on_action hook to do any last-minute
153 tests on the request itself, before it gets routed to a final des‐
154 tination. When called, the hook routine is passed three arguments:
155 action
157 The action URI itself, retrieved from the action method
158 described earlier.
159 method_uri
161 The URI of the XML namespace the method name is labeled with.
162 method_name
164 The name of the method being called by the request.
165 on_dispatch(optional new value)
167 ($uri, $name) = $server->on_dispatch->($request);
168 Gets or sets the subroutine reference used for the on_dispatch
170 hook. This hook is called at the start of the request-routing phase
171 and is given a single argument when called:
172 request
174 An object of the SOAP::SOM class, containing the deserialized
175 request from the client.
176 find_target
178 ($class, $uri, $name) = $server->find_target($req)
179 Taking as its argument an object of the SOAP::SOM class that con‐
181 tains the deserialized request, this method returns a three-element
182 list describing the method that is to be called. The elements are:
183 class
185 The class into which the method call should be made. This may
186 come back as either a string or an objectreference, if the dis‐
187 patching is configured using an object instance.
188 uri The URN associated with the request method. This is the value
190 that was used when configuring the method routing on the server
191 object.
192 name
194 The name of the method to call.
195 handle
197 $server->handle($request_text);
198 Implements the main functionality of the serving process, in which
200 the server takes an incoming request and dispatches it to the cor‐
201 rect server-side subroutine. The parameter taken as input is either
202 plain XML or MIME-encoded content (if MIME-encoding support is
203 enabled).
204 make_fault
206 return $server->makefault($code, $message);
207 Creates a SOAP::Fault object from the data passed in. The order of
209 arguments is: code, message, detail, actor. The first two are
210 required (because they must be present in all faults), but the last
211 two may be omitted unless needed.
212 SOAP::Server::Parameters
214 This class provides two methods, but the primary purpose from the
216 developer's point of view is to allow classes that a SOAP server
217 exposes to inherit from it. When a class inherits from the
218 SOAP::Server::Parameters class, the list of parameters passed to a
219 called method includes the deserialized request in the form of a
220 SOAP::SOM object. This parameter is passed at the end of the arguments
221 list, giving methods the option of ignoring it unless it is needed.
222 The class provides two subroutines (not methods), for retrieving param‐
224 eters from the SOAP::SOM object. These are designed to be called with‐
225 out an object reference in the parameter list, but with an array refer‐
226 ence instead (as the first parameter). The remainder of the arguments
227 list is expected to be the list from the method-call itself, including
228 the SOAP::SOM object at the end of the list. The routines may be useful
229 to understand if an application wishes to subclass SOAP::Server::Param‐
230 eters and inherit from the new class instead.
231 byNameOrOrder(order, parameter list, envelope)
233 @args = SOAP::Server::Parameters::byNameOrOrder ([qw(a b)], @_);
234 Using the list of argument names passed in the initial argument as
236 an array reference, this routine returns a list of the parameter
237 values for the parameters matching those names, in that order. If
238 none of the names given in the initial array-reference exist in the
239 parameter list, the values are returned in the order in which they
240 already appear within the list of parameters. In this case, the
241 number of returned values may differ from the length of the
242 requested-parameters list.
243 byName(order, parameter list, envelope)
245 @args = SOAP::Server::Parameters::byName ([qw(a b c)], @_);
246 Acts in a similar manner to the previous, with the difference that
248 it always returns as many values as requested, even if some (or
249 all) don't exist. Parameters that don't exist in the parameter list
250 are returned as undef values.
251 EXAMPLE
253 The following is an example CGI based Web Service that utilizes a Perl
255 module that inherits from the "SOAP::Server::Parameters" class. This
256 allows the methods of that class to access its input by name.
257 #!/usr/bin/perl
259 use SOAP::Transport::HTTP;
260 SOAP::Transport::HTTP::CGI
261 ->dispatch_to('C2FService')
262 ->handle;
263 BEGIN {
264 package C2FService;
265 use vars qw(@ISA);
266 @ISA = qw(Exporter SOAP::Server::Parameters);
267 use SOAP::Lite;
268 sub c2f {
269 my $self = shift;
270 my $envelope = pop;
271 my $temp = $envelope->dataof("//c2f/temperature");
272 return SOAP::Data->name('convertedTemp' => (((9/5)*($temp->value)) + 32));
273 }
274 }
275
277 SOAP::SOM, SOAP::Transport::HTTP
278
280 Special thanks to O'Reilly publishing which has graciously allowed
281 SOAP::Lite to republish and redistribute large excerpts from Program‐
282 ming Web Services with Perl, mainly the SOAP::Lite reference found in
283 Appendix B.
284
286 Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.
287 This library is free software; you can redistribute it and/or modify it
289 under the same terms as Perl itself.
290
292 Paul Kulchenko (paulclinger@yahoo.com)
293 Randy J. Ray (rjray@blackperl.com)
295 Byrne Reese (byrne@majordojo.com)
297perl v5.8.8 2006-06-15 SOAP::Server(3)