view release on metacpan or  search on metacpan

lib/SOAP/Data.pod  view on Meta::CPAN

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 det...

  $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');

=head1 EXAMPLES

=head2 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);

=head2 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>

=head2 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.

=head2 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 I<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.

=head2 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>

=head1 SEE ALSO

L<SOAP::Header>, L<SOAP::SOM>, L<SOAP::Serializer>

=head1 ACKNOWLEDGEMENTS

Special thanks to O'Reilly publishing which has graciously allowed SOAP::Lite to republish and redistribute large excerpts from I<Programming Web Services with Perl>, mainly the SOAP::Lite reference found in Appendix B.