1SOAP::SOM(3) User Contributed Perl Documentation SOAP::SOM(3)
2
6 SOAP::SOM - provides access to the values contained in SOAP Response
7
9 Objects from the SOAP::SOM class aren't generally instantiated directly
10 by an application. Rather, they are handed back by the deserialization
11 of a message. In other words, developers will almost never do this:
12 $som = SOAP::SOM->new;
14 SOAP::SOM objects are returned by a SOAP::Lite call in a client con‐
16 text. For example:
17 my $client = SOAP::Lite
19 ->readable(1)
20 ->uri($NS)
21 ->proxy($HOST)
22 $som = $client->someMethod();
23
25 new(message)
26 $som = SOAP::SOM->new($message_as_xml);
27 As said, the need to actually create an object of this class should
29 be very rare. However, if the need arises, the syntax must be fol‐
30 lowed. The single argument to new must be a valid XML document the
31 parser will understand as a SOAP response.
32 The following group of methods provide general data retrieval from the
34 SOAP::SOM object. The model for this is an abbreviated form of XPath.
35 Following this group are methods that are geared towards specific
36 retrieval of commonly requested elements.
37 match(path)
39 $som->match('/Envelope/Body/[1]');
40 This method sets the internal pointers within the data structure so
42 that the retrieval methods that follow will have access to the
43 desired data. In the example path, the match is being made against
44 the method entity, which is the first child tag of the body in a
45 SOAP response. The enumeration of container children starts at 1 in
46 this syntax, not 0. The returned value is dependent on the context
47 of the call. If the call is made in a boolean context (such as "if
48 ($som->match($path))"), the return value is a boolean indicating
49 whether the requested path matched at all. Otherwise, an object
50 reference is returned. The returned object is also a SOAP::SOM
51 instance but is smaller, containing the subset of the document tree
52 matched by the expression.
53 valueof(node)
55 $res = $som->valueof('[1]');
56 When the SOAP::SOM object has matched a path internally with the
58 match method, this method allows retrieval of the data within any
59 of the matched nodes. The data comes back as native Perl data, not
60 a class instance (see dataof). In a scalar context, this method
61 returns just the first element from a matched node set. In an array
62 context, all elements are returned. Assuming that the earlier call
63 happens after the earlier call to match, it retrieves the result
64 entity from the method response that is contained in $som, as this
65 is the first child element in a method-response tag.
66 dataof(node)
68 $resobj = $som->dataof('[1]');
69 Performs the same operation as the earlier valueof method, except
71 that the data is left in its SOAP::Data form, rather than being
72 deserialized. This allows full access to all the attributes that
73 were serialized along with the data, such as namespace and encod‐
74 ing.
75 headerof(node)
77 $resobj = $som->headerof('[1]');
78 Acts much like dataof, except that it returns an object of the
80 SOAP::Header class (covered later in this chapter), rather than
81 SOAP::Data. This is the preferred interface for manipulating the
82 header entities in a message.
83 namespaceuriof(node)
85 $ns = $som->namespaceof('[1]');
86 Retrieves the namespace URI that governs the requested node. Note
88 that namespaces are inherited, so this method will return the rele‐
89 vant value, even if it derives from a parent or other ancestor
90 node.
91 The following methods provide more direct access to the message enve‐
93 lope. All these methods return some form of a Perl value, most often a
94 hash reference, when called. Context is also relevant: in a scalar con‐
95 text only the first matching node is returned, while in an array con‐
96 text, all matching nodes are. When called as a static method or as a
97 regular function (such as "SOAP::SOM::envelope"), any of the following
98 methods returns the XPath string that is used with the match method to
99 retrieve the data.
100 root
102 $root = $som->root;
103 Returns the value of the root element as a hash reference. It
105 behaves exactly as "$som-"valueof('/')> does.
106 envelope
108 $envelope = $som->envelope;
109 Retrieves the "Envelope" element of the message, returning it and
111 its data as a hash reference. Keys in the hash will be Header and
112 Body (plus any optional elements that may be present in a SOAP 1.1
113 envelope), whose values will be the serialized header and body,
114 respectively.
115 header
117 $header = $som->header;
118 Retrieves the header portion of the envelope as a hash reference.
120 All data within it will have been deserialized. If the attributes
121 of the header are desired, the static form of the method can be
122 combined with match to fetch the header as a SOAP::Data object:
123 $header = $som->match(SOAP::SOM::header)->dataof;
125 headers
127 @hdrs = $som->headers;
128 Retrieves the node set of values with deserialized headers from
130 within the Header container. This is different from the earlier
131 header method in that it returns the whole header as a single
132 structure, and this returns the child elements as an array. In
133 other words, the following expressions yield the same data struc‐
134 ture:
135 $header = ($som->headers)[0];
137 $header = $som->valueof(SOAP::SOM::header.'/[1]');
138 body
140 $body = $som->body;
141 Retrieves the message body as a hash reference. The entity tags act
143 as keys, with their deserialized content providing the values.
144 fault
146 if ($som->fault) { die $som->fault->faultstring }
147 Acts both as a boolean test whether a fault occurred, and as a way
149 to retrieve the Fault entity itself from the message body as a hash
150 reference. If the message contains a fault, the next four methods
151 (faultcode, faultstring, faultactor, and faultdetail) may be used
152 to retrieve the respective parts of the fault (which are also
153 available on the hash reference as keys). If fault in a boolean
154 context is true, the "result", "paramsin", "paramsout", and
155 "method" methods all return "undef".
156 faultcode
158 $code = $som->faultcode;
159 Returns the faultcode element of the fault if there is a fault;
161 undef otherwise.
162 faultstring
164 $string = $som->faultstring;
165 Returns the faultstring element of the fault if there is a fault;
167 undef otherwise.
168 faultactor
170 $actor = $som->faultactor;
171 Returns the faultactor element of the fault, if there is a fault
173 and if the actor was specified within it. The faultactor element is
174 optional in the serialization of a fault, so it may not always be
175 present. This element is usually a string.
176 faultdetail
178 $detail = $som->faultdetail;
179 Returns the content of the detail element of the fault, if there is
181 a fault and if the detail element was provided. Note that the name
182 of the element isn't the same as the method, due to the possibility
183 for confusion had the method been called simply, detail. As with
184 the faultactor element, this isn't always a required component of a
185 fault, so it isn't guaranteed to be present. The specification for
186 the detail portion of a fault calls for it to contain a series of
187 element tags, so the application may expect a hash reference as a
188 return value when detail information is available (and undef other‐
189 wise).
190 method
192 $method = $som->method
193 Retrieves the "method" element of the message, as a hash reference.
195 This includes all input parameters when called on a request message
196 or all result/output parameters when called on a response message.
197 If there is a fault present in the message, it returns undef.
198 result
200 $value = $som->result;
201 Returns the value that is the result of a SOAP response. The value
203 will be already deserialized into a native Perl datatype.
204 paramsin
206 @list = $som->paramsin;
207 Retrieves the parameters being passed in on a SOAP request. If
209 called in a scalar context, the first parameter is returned. When
210 called in a list context, the full list of all parameters is
211 returned. Each parameter is a hash reference, following the estab‐
212 lished structure for such return values.
213 paramsout
215 @list = $som->paramsout;
216 Returns the output parameters from a SOAP response. These are the
218 named parameters that are returned in addition to the explicit
219 response entity itself. It shares the same scalar/list context
220 behavior as the paramsin method.
221 paramsall
223 @list = $som->paramsall;
224 Returns all parameters from a SOAP response, including the result
226 entity itself, as one array.
227 parts()
229 Return an array of "MIME::Entity"'s if the current payload contains
230 attachments, or returns undefined if payload is not MIME multipart.
231 is_multipart()
233 Returns true if payload is MIME multipart, false otherwise.
234
236 ACCESSING ELEMENT VALUES
237 Suppose for the following SOAP Envelope:
239 <Envelope>
241 <Body>
242 <fooResponse>
243 <bar>abcd</bar>
244 </fooResponse>
245 </Body>
246 </Envelope>
247 And suppose you wanted to access the value of the bar element, then use
249 the following code:
250 my $soap = SOAP::Lite
252 ->uri($SOME_NS)
253 ->proxy($SOME_HOST);
254 my $som = $soap->foo();
255 print $som->valueof('//fooResponse/bar');
256 ACCESSING ATTRIBUTE VALUES
258 Suppose the following SOAP Envelope:
260 <Envelope>
262 <Body>
263 <c2fResponse>
264 <convertedTemp test="foo">98.6</convertedTemp>
265 </c2fResponse>
266 </Body>
267 </Envelope>
268 Then to print the attribute 'test' use the following code:
270 print "The attribute is: " .
272 $som->dataof('//c2fResponse/convertedTemp')->attr->{'test'};
273 ITERATING OVER AN ARRAY
275 Suppose for the following SOAP Envelope:
277 <Envelope>
279 <Body>
280 <catalog>
281 <product>
282 <title>Programming Web Service with Perl</title>
283 <price>$29.95</price>
284 </product>
285 <product>
286 <title>Perl Cookbook</title>
287 <price>$49.95</price>
288 </product>
289 </catalog>
290 </Body>
291 </Envelope>
292 If the SOAP Envelope returned contained an array, use the following
294 code to iterate over the array:
295 for my $t ($som->valueof('//catalog/product')) {
297 print $t->{title} . " - " . $t->{price} . "\n";
298 }
299 DETECTING A SOAP FAULT
301 A SOAP::SOM object is returned by a SOAP::Lite client regardless of
303 whether the call succeeded or not. Therefore, a SOAP Client is respon‐
304 sible for determining if the returned value is a fault or not. To do
305 so, use the fault() method which returns 1 if the SOAP::SOM object is a
306 fault and 0 otherwise.
307 my $som = $client->someMethod(@parameters);
309 if ($som->fault) {
311 print $som->faultdetail;
312 } else {
313 # do something
314 }
315 PARSING ARRAYS OF ARRAYS
317 The most efficient way To parse and to extract data out of an array
319 containing another array encoded in a SOAP::SOM object is the follow‐
320 ing:
321 $xml = <<END_XML;
323 <foo>
324 <person>
325 <foo>123</foo>
326 <foo>456</foo>
327 </person>
328 <person>
329 <foo>789</foo>
330 <foo>012</foo>
331 </person>
332 </foo>
333 END_XML
334 my $som = SOAP::Deserializer->deserialize($xml);
336 my $i = 0;
337 foreach my $a ($som->dataof("//person/*")) {
338 $i++;
339 my $j = 0;
340 foreach my $b ($som->dataof("//person/[$i]/*")) {
341 $j++;
342 # do something
343 }
344 }
345
347 SOAP::Data, SOAP::Serializer
348
350 Special thanks to O'Reilly publishing which has graciously allowed
351 SOAP::Lite to republish and redistribute large excerpts from Program‐
352 ming Web Services with Perl, mainly the SOAP::Lite reference found in
353 Appendix B.
354
356 Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.
357 This library is free software; you can redistribute it and/or modify it
359 under the same terms as Perl itself.
360
362 Paul Kulchenko (paulclinger@yahoo.com)
363 Randy J. Ray (rjray@blackperl.com)
365 Byrne Reese (byrne@majordojo.com)
367perl v5.8.8 2006-06-15 SOAP::SOM(3)