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

NAME

6       SOAP::SOM - provides access to the values contained in SOAP Response
7

DESCRIPTION

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
13           $som = SOAP::SOM->new;
14
15       SOAP::SOM objects are returned by a SOAP::Lite call in a client
16       context. For example:
17
18           my $client = SOAP::Lite
19               ->readable(1)
20               ->uri($NS)
21               ->proxy($HOST)
22           $som = $client->someMethod();
23

METHODS

25       new(message)
26               $som = SOAP::SOM->new($message_as_xml);
27
28           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
33       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
38       match(path)
39               $som->match('/Envelope/Body/[1]');
40
41           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
54       valueof(node)
55               $res = $som->valueof('[1]');
56
57           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
67       dataof(node)
68               $resobj = $som->dataof('[1]');
69
70           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
76       headerof(node)
77               $resobj = $som->headerof('[1]');
78
79           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
84       namespaceuriof(node)
85               $ns = $som->namespaceof('[1]');
86
87           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
92       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
101       root
102               $root = $som->root;
103
104           Returns the value of the root element as a hash reference. It
105           behaves exactly as "$som-"valueof('/')> does.
106
107       envelope
108               $envelope = $som->envelope;
109
110           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
116       header
117               $header = $som->header;
118
119           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
124               $header = $som->match(SOAP::SOM::header)->dataof;
125
126       headers
127               @hdrs = $som->headers;
128
129           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
136               $header = ($som->headers)[0];
137               $header = $som->valueof(SOAP::SOM::header.'/[1]');
138
139       body
140               $body = $som->body;
141
142           Retrieves the message body as a hash reference. The entity tags act
143           as keys, with their deserialized content providing the values.
144
145       fault
146               if ($som->fault) { die $som->fault->faultstring }
147
148           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
157       faultcode
158               $code = $som->faultcode;
159
160           Returns the faultcode element of the fault if there is a fault;
161           undef otherwise.
162
163       faultstring
164               $string = $som->faultstring;
165
166           Returns the faultstring element of the fault if there is a fault;
167           undef otherwise.
168
169       faultactor
170               $actor = $som->faultactor;
171
172           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
177       faultdetail
178               $detail = $som->faultdetail;
179
180           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
191       method
192               $method = $som->method
193
194           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
199       result
200               $value = $som->result;
201
202           Returns the value that is the result of a SOAP response. The value
203           will be already deserialized into a native Perl datatype.
204
205       paramsin
206               @list = $som->paramsin;
207
208           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
214       paramsout
215               @list = $som->paramsout;
216
217           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
222       paramsall
223               @list = $som->paramsall;
224
225           Returns all parameters from a SOAP response, including the result
226           entity itself, as one array.
227
228       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
232       is_multipart()
233           Returns true if payload is MIME multipart, false otherwise.
234

EXAMPLES

236   ACCESSING ELEMENT VALUES
237       Suppose for the following SOAP Envelope:
238
239           <Envelope>
240             <Body>
241               <fooResponse>
242                 <bar>abcd</bar>
243               </fooResponse>
244             </Body>
245           </Envelope>
246
247       And suppose you wanted to access the value of the bar element, then use
248       the following code:
249
250           my $soap = SOAP::Lite
251               ->uri($SOME_NS)
252               ->proxy($SOME_HOST);
253           my $som = $soap->foo();
254           print $som->valueof('//fooResponse/bar');
255
256   ACCESSING ATTRIBUTE VALUES
257       Suppose the following SOAP Envelope:
258
259           <Envelope>
260             <Body>
261               <c2fResponse>
262                 <convertedTemp test="foo">98.6</convertedTemp>
263               </c2fResponse>
264             </Body>
265           </Envelope>
266
267       Then to print the attribute 'test' use the following code:
268
269           print "The attribute is: " .
270             $som->dataof('//c2fResponse/convertedTemp')->attr->{'test'};
271
272   ITERATING OVER AN ARRAY
273       Suppose for the following SOAP Envelope:
274
275           <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
290       If the SOAP Envelope returned contained an array, use the following
291       code to iterate over the array:
292
293           for my $t ($som->valueof('//catalog/product')) {
294             print $t->{title} . " - " . $t->{price} . "\n";
295           }
296
297   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
304           my $som = $client->someMethod(@parameters);
305
306           if ($som->fault) {
307             print $som->faultdetail;
308           } else {
309             # do something
310           }
311
312   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
317           $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
330           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

SEE ALSO

342       SOAP::Data, SOAP::Serializer
343

ACKNOWLEDGEMENTS

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
353       This library is free software; you can redistribute it and/or modify it
354       under the same terms as Perl itself.
355

AUTHORS

357       Paul Kulchenko (paulclinger@yahoo.com)
358
359       Randy J. Ray (rjray@blackperl.com)
360
361       Byrne Reese (byrne@majordojo.com)
362
363
364
365perl v5.12.3                      2010-06-03                      SOAP::SOM(3)
Impressum