.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SOAP::Data 3pm"
.TH SOAP::Data 3pm "2023-03-01" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "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.
.SH "DESCRIPTION"
.IX Header "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 \s-1SOAP\s0 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.
.SH "METHODS"
.IX Header "METHODS"
.IP "new(optional key/value pairs)" 4
.IX Item "new(optional key/value pairs)"
.Vb 1
\&    $obj = SOAP::Data\->new(name => \*(Aqidx\*(Aq, value => 5);
.Ve
.Sp
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.
.IP "name(new name, optional value)" 4
.IX Item "name(new name, optional value)"
.Vb 1
\&    $obj\->name(\*(Aqindex\*(Aq);
.Ve
.Sp
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 \s-1XML\s0 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.
.IP "type(new type, optional value)" 4
.IX Item "type(new type, optional value)"
.Vb 1
\&    $obj\->type(\*(Aqint\*(Aq);
.Ve
.Sp
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.
.IP "uri(new uri, optional value)" 4
.IX Item "uri(new uri, optional value)"
.Vb 1
\&    $obj\->uri(\*(Aqhttp://www.perl.com/SOAP\*(Aq);
.Ve
.Sp
Gets or sets the \s-1URI\s0 that will be used as the namespace for the resulting \s-1XML\s0 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.
.IP "prefix(new prefix, optional value)" 4
.IX Item "prefix(new prefix, optional value)"
.Vb 1
\&    $obj\->prefix(\*(Aqperl\*(Aq);
.Ve
.Sp
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.
.IP "attr(hash reference of attributes, optional value)" 4
.IX Item "attr(hash reference of attributes, optional value)"
.Vb 1
\&    $obj\->attr({ attr1 => \*(Aqvalue\*(Aq });
.Ve
.Sp
Allows for the setting of arbitrary attributes on the data object. Keep in mind the requirement that any attributes not natively known to \s-1SOAP\s0 must be namespace-qualified. Also allows the setting of the object's value, if passed as a second argument to the method.
.IP "value(new value)" 4
.IX Item "value(new value)"
.Vb 1
\&    $obj\->value(10);
.Ve
.Sp
Fetches the current value encapsulated by the object, or explicitly sets it.
.PP
The last four methods are convenience shortcuts for the attributes that \s-1SOAP\s0 itself supports. Each also permits inclusion of a new value, as an optional second argument.
.IP "actor(new actor, optional value)" 4
.IX Item "actor(new actor, optional value)"
.Vb 1
\&    $obj\->actor($new_actor_name);
.Ve
.Sp
Gets or sets the value of the actor attribute; useful only when the object generates an entity for the message header.
.IP "mustUnderstand(boolean, optional value)" 4
.IX Item "mustUnderstand(boolean, optional value)"
.Vb 1
\&    $obj\->mustUnderstand(0);
.Ve
.Sp
Manipulates the mustUnderstand attribute, which tells the \s-1SOAP\s0 processor whether it is required to understand the entity in question.
.IP "encodingStyle(new encoding \s-1URN,\s0 optional value)" 4
.IX Item "encodingStyle(new encoding URN, optional value)"
.Vb 1
\&    $obj\->encodingStyle($soap_11_encoding);
.Ve
.Sp
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.
.IP "root(boolean, optional value)" 4
.IX Item "root(boolean, optional value)"
.Vb 1
\&    $obj\->root(1);
.Ve
.Sp
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.
.SH "TYPE DETECTION"
.IX Header "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:
.PP
.Vb 1
\&  $elem = SOAP::Data\->name(\*(Aqidx\*(Aq)\->value(5);
.Ve
.PP
If, however, you need to serialize this into a long, then the following code will do so:
.PP
.Vb 1
\&  $elem = SOAP::Data\->name(\*(Aqidx\*(Aq)\->value(5)\->type(\*(Aqlong\*(Aq);
.Ve
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "\s-1SIMPLE TYPES\s0"
.IX Subsection "SIMPLE TYPES"
The following example will all produce the same \s-1XML:\s0
.PP
.Vb 3
\&    $elem1 = SOAP::Data\->new(name => \*(Aqidx\*(Aq, value => 5);
\&    $elem2 = SOAP::Data\->name(\*(Aqidx\*(Aq => 5);
\&    $elem3 = SOAP::Data\->name(\*(Aqidx\*(Aq)\->value(5);
.Ve
.SS "\s-1COMPLEX TYPES\s0"
.IX Subsection "COMPLEX TYPES"
A common question is how to do you created nested \s-1XML\s0 elements using SOAP::Lite. The following example demonstrates how:
.PP
.Vb 2
\&    SOAP::Data\->name(\*(Aqfoo\*(Aq => \eSOAP::Data\->value(
\&        SOAP::Data\->name(\*(Aqbar\*(Aq => \*(Aq123\*(Aq)));
.Ve
.PP
The above code will produce the following \s-1XML:\s0
.PP
.Vb 3
\&    <foo>
\&      <bar>123</bar>
\&    </foo>
.Ve
.SS "\s-1ARRAYS\s0"
.IX Subsection "ARRAYS"
The following code:
.PP
.Vb 4
\&    $elem1 = SOAP::Data\->name(\*(Aqitem\*(Aq => 123)\->type(\*(AqSomeObject\*(Aq);
\&    $elem2 = SOAP::Data\->name(\*(Aqitem\*(Aq => 456)\->type(\*(AqSomeObject\*(Aq);
\&    push(@array,$elem1);
\&    push(@array,$elem2);
\&
\&    my $client = SOAP::Lite
\&        \->readable(1)
\&        \->uri($NS)
\&        \->proxy($HOST);
\&
\&    $temp_elements = SOAP::Data
\&        \->name("CallDetails" => \eSOAP::Data\->value(
\&              SOAP::Data\->name("elem1" => \*(Aqfoo\*(Aq),
\&              SOAP::Data\->name("elem2" => \*(Aqbaz\*(Aq),
\&              SOAP::Data\->name("someArray" => \eSOAP::Data\->value(
\&                  SOAP::Data\->name("someArrayItem" => @array)
\&                            \->type("SomeObject"))
\&                       )\->type("ArrayOf_SomeObject") ))
\&
\&    \->type("SomeObject");
\&
\&    $response = $client\->someMethod($temp_elements);
.Ve
.PP
Will produce the following \s-1XML:\s0
.PP
.Vb 10
\&    <?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>
.Ve
.PP
In the code above, the \f(CW@array\fR 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.
.SS "\s-1COMPOSING MESSAGES USING RAW XML\s0"
.IX Subsection "COMPOSING MESSAGES USING RAW XML"
In some circumstances you may need to encode a message using raw unserialized
\&\s-1XML\s0 text. To instantiate a SOAP::Data object using raw \s-1XML,\s0 do the following:
.PP
.Vb 2
\&    $xml_content = "<foo><bar>123</bar></foo>";
\&    $elem = SOAP::Data\->type(\*(Aqxml\*(Aq => $xml_content);
.Ve
.PP
SOAP::Lite's serializer simple takes whatever text is passed to it, and inserts
into the encoded SOAP::Data element \fIverbatim\fR. The text input is \s-1NOT\s0 validated to
ensure it is valid \s-1XML,\s0 nor is the resulting SOAP::Data element validated to
ensure that it will produce valid \s-1XML.\s0 Therefore, it is incumbent upon the
developer to ensure that any \s-1XML\s0 data used in this fashion is valid and will
result in a valid \s-1XML\s0 document.
.SS "\s-1MULTIPLE NAMESPACES\s0"
.IX Subsection "MULTIPLE NAMESPACES"
When working with complex types it may be necessary to declare multiple namespaces. The following code demonstrates how to do so:
.PP
.Vb 3
\&    $elem = SOAP::Data\->name("myElement" => "myValue")
\&                      \->attr( { \*(Aqxmlns:foo2\*(Aq => \*(Aqurn:Foo2\*(Aq,
\&                                \*(Aqxmlns:foo3\*(Aq => \*(Aqurn:Foo3\*(Aq } );
.Ve
.PP
This will produce the following \s-1XML:\s0
.PP
.Vb 1
\&    <myElement xmlns:foo2="urn:Foo2" xmlns:foo3="urn:Foo3">myValue</myElement>
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
SOAP::Header, \s-1SOAP::SOM\s0, SOAP::Serializer
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Special thanks to O'Reilly publishing which has graciously allowed SOAP::Lite to republish and redistribute large excerpts from \fIProgramming Web Services with Perl\fR, mainly the SOAP::Lite reference found in Appendix B.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2000\-2004 Paul Kulchenko. All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "AUTHORS"
.IX Header "AUTHORS"
Paul Kulchenko (paulclinger@yahoo.com)
.PP
Randy J. Ray (rjray@blackperl.com)
.PP
Byrne Reese (byrne@majordojo.com)