OutputStream(3)

NAME

       SOAP::OutputStream - Writes SOAP fragments

SYNOPSIS

           # note that we need SOAP::Envelope to bootstrap
           use SOAP::Envelope;

           sub output_fcn {
               my $string = shift;
               print $string;
           }

           my $namespaces_to_preload = ["urn:foo", "urn:bar"];
           my $env = SOAP::Envelope->new(\&output_fcn,
                                         $namespaces_to_preload);
           my $body = $env->body();

           # here is where we actually use SOAP::OutputStream
           my $child = $body->compound_accessor("urn:quux", "reverse_string", undef, undef, 0);

           $child->simple_accessor(undef, "s", undef, undef, "dlrow olleH");

           $child->term();
           $body->term();
           $env->term();

       This creates the following XML:

       <s:Envelope xmlns:s="urn:schemas-xmlsoap-org:soap.v1"
                   xmlns:xsd="http://www.w3.org/1999/XMLSchema"
                   xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
                   xmlns:n1="urn:foo"
                   xmlns:n2="urn:bar">
         <s:Body>
           <n3:reverse_string xmlns:n3="urn:quux">
             <s>dlrow olle1
           </n3:reverse_string>
         </s:Body> </s:Envelope>

DESCRIPTION

       SOAP::OutputStream encapsulates the details of writing SOAP packets
       into a few easy to use functions. In order to bootstrap a SOAP stream
       (and get your first SOAP::OutputStream reference), you'll need to use
       SOAP::Envelope, as shown in the example above.

       The simple_accessor function

       This function writes a simple accessor (e.g., a string or number, as
       opposed to a compound type). It takes two sets of URI/typenames, one
       for the accessor and one for the optional xsi:type attribute. At a min-
       imum, you must specify the accessor_name and content.

       The compound_accessor function

       This function opens a new compound accessor (by writing an open XML
       tag), and returns a new SOAP::OutputStream that you should use to write
       the contents of that accessor. This function always creates nested ele-
       ments. If you want to create an independent element, call refer-
       ence_accessor instead. The is_package parameter allows you to open a
       new package at this node; the OutputStream will write all further inde-
       pendent elements at this level in the XML document, creating a stand-
       alone XML fragment within the SOAP envelope. The OutputStream will com-
       plain if all references within the package cannot be resolved when this
       node is closed.  See the SOAP spec for details on packages.

       NOTE NOTE NOTE: The SOAP "package" attribute was dropped when the SOAP
       spec
                       went from version 1.0 to version 1.1. Use package-
       related
                       functionality at your own risk - you may not interoper-
       ate
                       with other servers if you rely on it. I'll eventually
       remove
                       this feature if it doesn't reappear in the spec soon.

       The reference_accessor function

       This function creates a reference (SOAP:href) node, and stores the
       specified object until the current package is closed, at which time a
       serializer is obtained for the object (based on its type) and is asked
       to serialize itself to a new stream at the level of the package. Note
       that if you're not using packages explicitly, then the system will per-
       form this resolution and serialization when you switch from creating
       Headers to creating the Body, and once again when the Body is termi-
       nated. The object referenced is guaranteed to only be serialized once
       (assuming you've obeyed the SOAP rules for packages and Header/Body
       object reference sharing).

       The term function

       Call this function when you want to close the node you're working with.
       This does several things - it seals the package if the node you're
       using was created as a package, and it writes an end tag (along with
       doing some other internal bookeeping that's pretty important). Don't
       forget to call this function before opening a new sibling node.

DEPENDENCIES

       SOAP::Defs

AUTHOR

       Keith Brown

SEE ALSO

       SOAP::Envelope

perl v5.8.6                       2000-09-05             SOAP::OutputStream(3)