1SOAP::Data(3) User Contributed Perl Documentation SOAP::Data(3)
2
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
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
20 new(optional key/value pairs)
21 $obj = SOAP::Data->new(name => 'idx', value => 5);
22 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 name(new name, optional value)
30 $obj->name('index');
31 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 type(new type, optional value)
39 $obj->type('int');
40 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 uri(new uri, optional value)
49 $obj->uri('http://www.perl.com/SOAP');
50 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 prefix(new prefix, optional value)
59 $obj->prefix('perl');
60 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 attr(hash reference of attributes, optional value)
66 $obj->attr({ attr1 => 'value' });
67 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 value(new value)
74 $obj->value(10);
75 Fetches the current value encapsulated by the object, or explicitly
77 sets it.
78 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 actor(new actor, optional value)
84 $obj->actor($new_actor_name);
85 Gets or sets the value of the actor attribute; useful only when the
87 object generates an entity for the message header.
88 mustUnderstand(boolean, optional value)
90 $obj->mustUnderstand(0);
91 Manipulates the mustUnderstand attribute, which tells the SOAP
93 processor whether it is required to understand the entity in
94 question.
95 encodingStyle(new encoding URN, optional value)
97 $obj->encodingStyle($soap_11_encoding);
98 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 root(boolean, optional value)
104 $obj->root(1);
105 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
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 $elem = SOAP::Data->name('idx')->value(5);
121 If, however, you need to serialize this into a long, then the following
123 code will do so:
124 $elem = SOAP::Data->name('idx')->value(5)->type('long');
126
128 SIMPLE TYPES
129 The following example will all produce the same XML:
130 $elem1 = SOAP::Data->new(name => 'idx', value => 5);
132 $elem2 = SOAP::Data->name('idx' => 5);
133 $elem3 = SOAP::Data->name('idx')->value(5);
134 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 SOAP::Data->name('foo' => \SOAP::Data->value(
140 SOAP::Data->name('bar' => '123')));
141 The above code will produce the following XML:
143 <foo>
145 <bar>123</bar>
146 </foo>
147 ARRAYS
149 The following code:
150 $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 my $client = SOAP::Lite
157 ->readable(1)
158 ->uri($NS)
159 ->proxy($HOST);
160 $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 ->type("SomeObject");
171 $response = $client->someMethod($temp_elements);
173 Will produce the following XML:
175 <?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 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 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 $xml_content = "<foo><bar>123</bar></foo>";
210 $elem = SOAP::Data->type('xml' => $xml_content);
211 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 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 $elem = SOAP::Data->name("myElement" => "myValue")
225 ->attr( { 'xmlns:foo2' => 'urn:Foo2',
226 'xmlns:foo3' => 'urn:Foo3' } );
227 This will produce the following XML:
229 <myElement xmlns:foo2="urn:Foo2" xmlns:foo3="urn:Foo3">myValue</myElement>
231
233 SOAP::Header, SOAP::SOM, SOAP::Serializer
234
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 This library is free software; you can redistribute it and/or modify it
245 under the same terms as Perl itself.
246
248 Paul Kulchenko (paulclinger@yahoo.com)
249 Randy J. Ray (rjray@blackperl.com)
251 Byrne Reese (byrne@majordojo.com)
253perl v5.12.3 2010-06-03 SOAP::Data(3)