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
12       manipulate 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
34           generating the XML for this object. It is what will become the
35           accessor for the data element. Optionally, the object's value may
36           be 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
93           processor whether it is required to understand the entity in
94           question.
95
96       encodingStyle(new encoding URN, optional value)
97               $obj->encodingStyle($soap_11_encoding);
98
99           This method is most likely to be used in places outside the header
100           creation. Sets encodingStyle, which specifies an encoding that
101           differs from the one that would otherwise be defaulted to.
102
103       root(boolean, optional value)
104               $obj->root(1);
105
106           When the application must explicitly specify which data element is
107           to be regarded as the root element for the sake of generating the
108           object model, this method provides the access to the root
109           attribute.
110

TYPE DETECTION

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

EXAMPLES

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

SEE ALSO

233       SOAP::Header, SOAP::SOM, SOAP::Serializer
234

ACKNOWLEDGEMENTS

236       Special thanks to O'Reilly publishing which has graciously allowed
237       SOAP::Lite to republish and redistribute large excerpts from
238       Programming Web Services with Perl, mainly the SOAP::Lite reference
239       found in Appendix B.
240
242       Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.
243
244       This library is free software; you can redistribute it and/or modify it
245       under the same terms as Perl itself.
246

AUTHORS

248       Paul Kulchenko (paulclinger@yahoo.com)
249
250       Randy J. Ray (rjray@blackperl.com)
251
252       Byrne Reese (byrne@majordojo.com)
253
254
255
256perl v5.12.3                      2010-06-03                     SOAP::Data(3)
Impressum