SOAP::Data(3pm)

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

NAME

6       SOAP::Data - this class provides the means by which to explicitly
7       manipulate and control all aspects of the way in which Perl data gets
8       expressed as SOAP data entities.
9

DESCRIPTION

11       The SOAP::Data class provides the means by which to explicitly manipu‐
12       late and control all aspects of the way in which Perl data gets
13       expressed as SOAP data entities. Most of the methods are accessors,
14       which like those in SOAP::Lite are designed to return the current value
15       if no new one is passed, while returning the object reference otherwise
16       (allowing for chained method calls). Note that most accessors (except
17       value) accept a new value for the data object as a second argument.
18

METHODS

20       new(optional key/value pairs)
21               $obj = SOAP::Data->new(name => 'idx', value => 5);
22
23           This is the class constructor. Almost all of the attributes related
24           to the class may be passed to the constructor as key/value pairs.
25           This method isn't often used directly because SOAP::Data objects
26           are generally created for temporary use. It is available for those
27           situations that require it.
28
29       name(new name, optional value)
30               $obj->name('index');
31
32           Gets or sets the current value of the name, as the object regards
33           it. The name is what the serializer will use for the tag when gen‐
34           erating the XML for this object. It is what will become the acces‐
35           sor for the data element. Optionally, the object's value may be
36           updated if passed as a second argument.
37
38       type(new type, optional value)
39               $obj->type('int');
40
41           Gets or sets the type associated with the current value in the
42           object. This is useful for those cases where the SOAP::Data object
43           is used to explicitly specify the type of data that would otherwise
44           be interpreted as a different type completely (such as perceiving
45           the string 123 as an integer, instead). Allows the setting of the
46           object's value, if passed as a second argument to the method.
47
48       uri(new uri, optional value)
49               $obj->uri('http://www.perl.com/SOAP');
50
51           Gets or sets the URI that will be used as the namespace for the
52           resulting XML entity, if one is desired. This doesn't set the label
53           for the namespace. If one isn't provided by means of the prefix
54           method, one is generated automatically when needed. Also allows the
55           setting of the object's value, if passed as a second argument to
56           the method.
57
58       prefix(new prefix, optional value)
59               $obj->prefix('perl');
60
61           Provides the prefix, or label, for use when associating the data
62           object with a specific namespace. Also allows the setting of the
63           object's value, if passed as a second argument to the method.
64
65       attr(hash reference of attributes, optional value)
66               $obj->attr({ attr1 => 'value' });
67
68           Allows for the setting of arbitrary attributes on the data object.
69           Keep in mind the requirement that any attributes not natively known
70           to SOAP must be namespace-qualified. Also allows the setting of the
71           object's value, if passed as a second argument to the method.
72
73       value(new value)
74               $obj->value(10);
75
76           Fetches the current value encapsulated by the object, or explicitly
77           sets it.
78
79       The last four methods are convenience shortcuts for the attributes that
80       SOAP itself supports. Each also permits inclusion of a new value, as an
81       optional second argument.
82
83       actor(new actor, optional value)
84               $obj->actor($new_actor_name);
85
86           Gets or sets the value of the actor attribute; useful only when the
87           object generates an entity for the message header.
88
89       mustUnderstand(boolean, optional value)
90               $obj->mustUnderstand(0);
91
92           Manipulates the mustUnderstand attribute, which tells the SOAP pro‐
93           cessor whether it is required to understand the entity in question.
94
95       encodingStyle(new encoding URN, optional value)
96               $obj->encodingStyle($soap_11_encoding);
97
98           This method is most likely to be used in places outside the header
99           creation. Sets encodingStyle, which specifies an encoding that dif‐
100           fers from the one that would otherwise be defaulted to.
101
102       root(boolean, optional value)
103               $obj->root(1);
104
105           When the application must explicitly specify which data element is
106           to be regarded as the root element for the sake of generating the
107           object model, this method provides the access to the root
108           attribute.
109

TYPE DETECTION

111       SOAP::Lite's serializer will detect the type of any scalar passed in as
112       a SOAP::Data object's value. Because Perl is loosely typed, the serial‐
113       izer is only able to detect types based upon a predetermined set of
114       regular expressions. Therefore, type detection is not always 100% accu‐
115       rate. In such a case you may need to explicitly set the type of the
116       element being encoded. For example, by default the following code will
117       be serialized as an integer:
118
119         $elem = SOAP::Data->name('idx')->value(5);
120
121       If, however, you need to serialize this into a long, then the following
122       code will do so:
123
124         $elem = SOAP::Data->name('idx')->value(5)->type('long');
125

EXAMPLES

127       SIMPLE TYPES
128
129       The following example will all produce the same XML:
130
131           $elem1 = SOAP::Data->new(name => 'idx', value => 5);
132           $elem2 = SOAP::Data->name('idx' => 5);
133           $elem3 = SOAP::Data->name('idx')->value(5);
134
135       COMPLEX TYPES
136
137       A common question is how to do you created nested XML elements using
138       SOAP::Lite. The following example demonstrates how:
139
140           SOAP::Data->name('foo' => \SOAP::Data->value(
141               SOAP::Data->name('bar' => '123')));
142
143       The above code will produce the following XML:
144
145           <foo>
146             <bar>123</bar>
147           </foo>
148
149       ARRAYS
150
151       The following code:
152
153           $elem1 = SOAP::Data->name('item' => 123)->type('SomeObject');
154           $elem2 = SOAP::Data->name('item' => 456)->type('SomeObject');
155           push(@array,$elem1);
156           push(@array,$elem2);
157
158           my $client = SOAP::Lite
159               ->readable(1)
160               ->uri($NS)
161               ->proxy($HOST);
162
163           $temp_elements = SOAP::Data
164               ->name("CallDetails" => \SOAP::Data->value(
165                     SOAP::Data->name("elem1" => 'foo'),
166                     SOAP::Data->name("elem2" => 'baz'),
167                     SOAP::Data->name("someArray" => \SOAP::Data->value(
168                         SOAP::Data->name("someArrayItem" => @array)
169                                   ->type("SomeObject"))
170                              )->type("ArrayOf_SomeObject") ))
171
172               ->type("SomeObject");
173
174           $response = $client->someMethod($temp_elements);
175
176       Will produce the following XML:
177
178           <?xml version="1.0" encoding="UTF-8"?>
179           <SOAP-ENV:Envelope
180               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
181               xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
182               xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
183               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
184               xmlns:namesp2="http://namespaces.soaplite.com/perl"
185               SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
186             <SOAP-ENV:Body>
187               <namesp1:someMethod xmlns:namesp1="urn:TemperatureService">
188                 <CallDetails xsi:type="namesp2:SomeObject">
189                   <elem1 xsi:type="xsd:string">foo</elem1>
190                   <elem2 xsi:type="xsd:string">baz</elem2>
191                   <someArray xsi:type="namesp2:ArrayOf_SomeObject">
192                     <item xsi:type="namesp2:SomeObject">123</bar>
193                     <item xsi:type="namesp2:SomeObject">456</bar>
194                   </someArray>
195                 </CallDetails>
196               </namesp1:test>
197             </SOAP-ENV:Body>
198           </SOAP-ENV:Envelope>
199
200       In the code above, the @array variable can be an array of anything. If
201       you pass in an array of numbers, then SOAP::Lite will properly serial‐
202       ize that into such.  If however you need to encode an array of complex
203       types, then simply pass in an array of other SOAP::Data objects and you
204       are all set.
205
206       COMPOSING MESSAGES USING RAW XML
207
208       In some circumstances you may need to encode a message using raw unse‐
209       rialized XML text. To instantiate a SOAP::Data object using raw XML, do
210       the following:
211
212           $xml_content = "<foo><bar>123</bar></foo>";
213           $elem = SOAP::Data->type('xml' => $xml_content);
214
215       SOAP::Lite's serializer simple takes whatever text is passed to it, and
216       inserts into the encoded SOAP::Data element verbatim. The text input is
217       NOT validated to ensure it is valid XML, nor is the resulting
218       SOAP::Data element validated to ensure that it will produce valid XML.
219       Therefore, it is incumbent upon the developer to ensure that any XML
220       data used in this fashion is valid and will result in a valid XML docu‐
221       ment.
222
223       MULTIPLE NAMESPACES
224
225       When working with complex types it may be necessary to declare multiple
226       namespaces. The following code demonstrates how to do so:
227
228           $elem = SOAP::Data->name("myElement" => "myValue")
229                             ->attr( { 'xmlns:foo2' => 'urn:Foo2',
230                                       'xmlns:foo3' => 'urn:Foo3' } );
231
232       This will produce the following XML:
233
234           <myElement xmlns:foo2="urn:Foo2" xmlns:foo3="urn:Foo3">myValue</myElement>
235

ACKNOWLEDGEMENTS

240       Special thanks to O'Reilly publishing which has graciously allowed
241       SOAP::Lite to republish and redistribute large excerpts from Program‐
242       ming Web Services with Perl, mainly the SOAP::Lite reference found in
243       Appendix B.
244

COPYRIGHT

246       Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.
247
248       This library is free software; you can redistribute it and/or modify it
249       under the same terms as Perl itself.
250

AUTHORS

252       Paul Kulchenko (paulclinger@yahoo.com)
253
254       Randy J. Ray (rjray@blackperl.com)
255
256       Byrne Reese (byrne@majordojo.com)
257
258
259
260perl v5.8.8                       2006-06-15                     SOAP::Data(3)