SOAP::Data(3) User Contributed Perl Documentation SOAP::Data(3)
NAME
SOAP::Data - this class provides the means by which to explicitly
manipulate and control all aspects of the way in which Perl data gets
expressed as SOAP data entities.
DESCRIPTION
The SOAP::Data class provides the means by which to explicitly
manipulate and control all aspects of the way in which Perl data gets
expressed as SOAP data entities. Most of the methods are accessors,
which like those in SOAP::Lite are designed to return the current value
if no new one is passed, while returning the object reference otherwise
(allowing for chained method calls). Note that most accessors (except
value) accept a new value for the data object as a second argument.
METHODS
new(optional key/value pairs)
$obj = SOAP::Data->new(name => 'idx', value => 5);
This is the class constructor. Almost all of the attributes related
to the class may be passed to the constructor as key/value pairs.
This method isn't often used directly because SOAP::Data objects
are generally created for temporary use. It is available for those
situations that require it.
name(new name, optional value)
$obj->name('index');
Gets or sets the current value of the name, as the object regards
it. The name is what the serializer will use for the tag when
generating the XML for this object. It is what will become the
accessor for the data element. Optionally, the object's value may
be updated if passed as a second argument.
type(new type, optional value)
$obj->type('int');
Gets or sets the type associated with the current value in the
object. This is useful for those cases where the SOAP::Data object
is used to explicitly specify the type of data that would otherwise
be interpreted as a different type completely (such as perceiving
the string 123 as an integer, instead). Allows the setting of the
object's value, if passed as a second argument to the method.
uri(new uri, optional value)
$obj->uri('http://www.perl.com/SOAP');
Gets or sets the URI that will be used as the namespace for the
resulting XML entity, if one is desired. This doesn't set the label
for the namespace. If one isn't provided by means of the prefix
method, one is generated automatically when needed. Also allows the
setting of the object's value, if passed as a second argument to
the method.
prefix(new prefix, optional value)
$obj->prefix('perl');
Provides the prefix, or label, for use when associating the data
object with a specific namespace. Also allows the setting of the
object's value, if passed as a second argument to the method.
attr(hash reference of attributes, optional value)
$obj->attr({ attr1 => 'value' });
Allows for the setting of arbitrary attributes on the data object.
Keep in mind the requirement that any attributes not natively known
to SOAP must be namespace-qualified. Also allows the setting of the
object's value, if passed as a second argument to the method.
value(new value)
$obj->value(10);
Fetches the current value encapsulated by the object, or explicitly
sets it.
The last four methods are convenience shortcuts for the attributes that
SOAP itself supports. Each also permits inclusion of a new value, as an
optional second argument.
actor(new actor, optional value)
$obj->actor($new_actor_name);
Gets or sets the value of the actor attribute; useful only when the
object generates an entity for the message header.
mustUnderstand(boolean, optional value)
$obj->mustUnderstand(0);
Manipulates the mustUnderstand attribute, which tells the SOAP
processor whether it is required to understand the entity in
question.
encodingStyle(new encoding URN, optional value)
$obj->encodingStyle($soap_11_encoding);
This method is most likely to be used in places outside the header
creation. Sets encodingStyle, which specifies an encoding that
differs from the one that would otherwise be defaulted to.
root(boolean, optional value)
$obj->root(1);
When the application must explicitly specify which data element is
to be regarded as the root element for the sake of generating the
object model, this method provides the access to the root
attribute.
TYPE DETECTION
SOAP::Lite's serializer will detect the type of any scalar passed in as
a SOAP::Data object's value. Because Perl is loosely typed, the
serializer is only able to detect types based upon a predetermined set
of regular expressions. Therefore, type detection is not always 100%
accurate. In such a case you may need to explicitly set the type of the
element being encoded. For example, by default the following code will
be serialized as an integer:
$elem = SOAP::Data->name('idx')->value(5);
If, however, you need to serialize this into a long, then the following
code will do so:
$elem = SOAP::Data->name('idx')->value(5)->type('long');
EXAMPLES
SIMPLE TYPES
The following example will all produce the same XML:
$elem1 = SOAP::Data->new(name => 'idx', value => 5);
$elem2 = SOAP::Data->name('idx' => 5);
$elem3 = SOAP::Data->name('idx')->value(5);
COMPLEX TYPES
A common question is how to do you created nested XML elements using
SOAP::Lite. The following example demonstrates how:
SOAP::Data->name('foo' => \SOAP::Data->value(
SOAP::Data->name('bar' => '123')));
The above code will produce the following XML:
<foo>
<bar>123</bar>
</foo>
ARRAYS
The following code:
$elem1 = SOAP::Data->name('item' => 123)->type('SomeObject');
$elem2 = SOAP::Data->name('item' => 456)->type('SomeObject');
push(@array,$elem1);
push(@array,$elem2);
my $client = SOAP::Lite
->readable(1)
->uri($NS)
->proxy($HOST);
$temp_elements = SOAP::Data
->name("CallDetails" => \SOAP::Data->value(
SOAP::Data->name("elem1" => 'foo'),
SOAP::Data->name("elem2" => 'baz'),
SOAP::Data->name("someArray" => \SOAP::Data->value(
SOAP::Data->name("someArrayItem" => @array)
->type("SomeObject"))
)->type("ArrayOf_SomeObject") ))
->type("SomeObject");
$response = $client->someMethod($temp_elements);
Will produce the following XML:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:namesp2="http://namespaces.soaplite.com/perl"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<namesp1:someMethod xmlns:namesp1="urn:TemperatureService">
<CallDetails xsi:type="namesp2:SomeObject">
<elem1 xsi:type="xsd:string">foo</elem1>
<elem2 xsi:type="xsd:string">baz</elem2>
<someArray xsi:type="namesp2:ArrayOf_SomeObject">
<item xsi:type="namesp2:SomeObject">123</bar>
<item xsi:type="namesp2:SomeObject">456</bar>
</someArray>
</CallDetails>
</namesp1:test>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
In the code above, the @array variable can be an array of anything. If
you pass in an array of numbers, then SOAP::Lite will properly
serialize that into such. If however you need to encode an array of
complex types, then simply pass in an array of other SOAP::Data objects
and you are all set.
COMPOSING MESSAGES USING RAW XML
In some circumstances you may need to encode a message using raw
unserialized XML text. To instantiate a SOAP::Data object using raw
XML, do the following:
$xml_content = "<foo><bar>123</bar></foo>";
$elem = SOAP::Data->type('xml' => $xml_content);
SOAP::Lite's serializer simple takes whatever text is passed to it, and
inserts into the encoded SOAP::Data element verbatim. The text input is
NOT validated to ensure it is valid XML, nor is the resulting
SOAP::Data element validated to ensure that it will produce valid XML.
Therefore, it is incumbent upon the developer to ensure that any XML
data used in this fashion is valid and will result in a valid XML
document.
MULTIPLE NAMESPACES
When working with complex types it may be necessary to declare multiple
namespaces. The following code demonstrates how to do so:
$elem = SOAP::Data->name("myElement" => "myValue")
->attr( { 'xmlns:foo2' => 'urn:Foo2',
'xmlns:foo3' => 'urn:Foo3' } );
This will produce the following XML:
<myElement xmlns:foo2="urn:Foo2" xmlns:foo3="urn:Foo3">myValue</myElement>
SEE ALSO
SOAP::Header(3), SOAP::SOM(3), SOAP::Serializer(3)
ACKNOWLEDGEMENTS
Special thanks to O'Reilly publishing which has graciously allowed
SOAP::Lite to republish and redistribute large excerpts from
Programming Web Services with Perl, mainly the SOAP::Lite reference
found in Appendix B.
COPYRIGHT
Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
AUTHORS
Paul Kulchenko (paulclinger@yahoo.com)
Randy J. Ray (rjray@blackperl.com)
Byrne Reese (byrne@majordojo.com)
perl v5.24.3 2017-12-30 SOAP::Data(3)
soap-lite 1.260.0 - Generated Fri Jan 5 17:47:46 CST 2018