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
23 construction call by giving the name followed by the parameter (or
24 an array 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
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 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
53 generally 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
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 dispatch_with(optional new value)
76 $server->dispatch_with($new_table);
77 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 dispatch_to(optional list of new values)
89 $server->dispatch_to($dir, 'Module', 'Mod::meth');
90 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 Directory path
98 If the value is a directory path, all modules located in that
99 path are available for remote use.
100 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 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 Object reference
113 If the value is an object reference, the object itself routes
114 the request.
115 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 objects_by_reference(optional list of new values)
125 $server->objects_by_reference(qw(My:: Class));
126 This also returns a list of values when retrieving the current
128 attribute value, as opposed to a single value.
129 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 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 $SOAP::Constants::OBJS_BY_REF_KEEPALIVE = 1000;
146 on_action(optional new value)
148 $server->on_action(sub { ...new code });
149 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 action
159 The action URI itself, retrieved from the action method
160 described earlier.
161 method_uri
163 The URI of the XML namespace the method name is labeled with.
164 method_name
166 The name of the method being called by the request.
167 on_dispatch(optional new value)
169 ($uri, $name) = $server->on_dispatch->($request);
170 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 request
176 An object of the SOAP::SOM class, containing the deserialized
177 request from the client.
178 find_target
180 ($class, $uri, $name) = $server->find_target($req)
181 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 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 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 name
197 The name of the method to call.
198 handle
200 $server->handle($request_text);
201 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 make_fault
209 return $server->makefault($code, $message);
210 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 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 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 byNameOrOrder(order, parameter list, envelope)
235 @args = SOAP::Server::Parameters::byNameOrOrder ([qw(a b)], @_);
236 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 byName(order, parameter list, envelope)
247 @args = SOAP::Server::Parameters::byName ([qw(a b c)], @_);
248 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 EXAMPLE
255 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 #!/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
279 SOAP::SOM, SOAP::Transport::HTTP
280
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 This library is free software; you can redistribute it and/or modify it
291 under the same terms as Perl itself.
292
294 Paul Kulchenko (paulclinger@yahoo.com)
295 Randy J. Ray (rjray@blackperl.com)
297 Byrne Reese (byrne@majordojo.com)
299perl v5.34.0 2022-01-21 SOAP::Server(3)