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
16 context. 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
30 followed. The single argument to new must be a valid XML document
31 the 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
74 encoding.
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
89 relevant value, even if it derives from a parent or other ancestor
90 node.
91 The following methods provide more direct access to the message
93 envelope. All these methods return some form of a Perl value, most
94 often a hash reference, when called. Context is also relevant: in a
95 scalar context only the first matching node is returned, while in an
96 array context, all matching nodes are. When called as a static method
97 or as a regular function (such as "SOAP::SOM::envelope"), any of the
98 following methods returns the XPath string that is used with the match
99 method to 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
134 structure:
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
189 otherwise).
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
212 established 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:
238 <Envelope>
240 <Body>
241 <fooResponse>
242 <bar>abcd</bar>
243 </fooResponse>
244 </Body>
245 </Envelope>
246 And suppose you wanted to access the value of the bar element, then use
248 the following code:
249 my $soap = SOAP::Lite
251 ->uri($SOME_NS)
252 ->proxy($SOME_HOST);
253 my $som = $soap->foo();
254 print $som->valueof('//fooResponse/bar');
255 ACCESSING ATTRIBUTE VALUES
257 Suppose the following SOAP Envelope:
258 <Envelope>
260 <Body>
261 <c2fResponse>
262 <convertedTemp test="foo">98.6</convertedTemp>
263 </c2fResponse>
264 </Body>
265 </Envelope>
266 Then to print the attribute 'test' use the following code:
268 print "The attribute is: " .
270 $som->dataof('//c2fResponse/convertedTemp')->attr->{'test'};
271 ITERATING OVER AN ARRAY
273 Suppose for the following SOAP Envelope:
274 <Envelope>
276 <Body>
277 <catalog>
278 <product>
279 <title>Programming Web Service with Perl</title>
280 <price>$29.95</price>
281 </product>
282 <product>
283 <title>Perl Cookbook</title>
284 <price>$49.95</price>
285 </product>
286 </catalog>
287 </Body>
288 </Envelope>
289 If the SOAP Envelope returned contained an array, use the following
291 code to iterate over the array:
292 for my $t ($som->valueof('//catalog/product')) {
294 print $t->{title} . " - " . $t->{price} . "\n";
295 }
296 DETECTING A SOAP FAULT
298 A SOAP::SOM object is returned by a SOAP::Lite client regardless of
299 whether the call succeeded or not. Therefore, a SOAP Client is
300 responsible for determining if the returned value is a fault or not. To
301 do so, use the fault() method which returns 1 if the SOAP::SOM object
302 is a fault and 0 otherwise.
303 my $som = $client->someMethod(@parameters);
305 if ($som->fault) {
307 print $som->faultdetail;
308 } else {
309 # do something
310 }
311 PARSING ARRAYS OF ARRAYS
313 The most efficient way To parse and to extract data out of an array
314 containing another array encoded in a SOAP::SOM object is the
315 following:
316 $xml = <<END_XML;
318 <foo>
319 <person>
320 <foo>123</foo>
321 <foo>456</foo>
322 </person>
323 <person>
324 <foo>789</foo>
325 <foo>012</foo>
326 </person>
327 </foo>
328 END_XML
329 my $som = SOAP::Deserializer->deserialize($xml);
331 my $i = 0;
332 foreach my $a ($som->dataof("//person/*")) {
333 $i++;
334 my $j = 0;
335 foreach my $b ($som->dataof("//person/[$i]/*")) {
336 $j++;
337 # do something
338 }
339 }
340
342 SOAP::Data, SOAP::Serializer
343
345 Special thanks to O'Reilly publishing which has graciously allowed
346 SOAP::Lite to republish and redistribute large excerpts from
347 Programming Web Services with Perl, mainly the SOAP::Lite reference
348 found in Appendix B.
349
351 Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.
352 This library is free software; you can redistribute it and/or modify it
354 under the same terms as Perl itself.
355
357 Paul Kulchenko (paulclinger@yahoo.com)
358 Randy J. Ray (rjray@blackperl.com)
360 Byrne Reese (byrne@majordojo.com)
362perl v5.12.3 2010-06-03 SOAP::SOM(3)