NAME

       SOAP::Packager - this class is an abstract class which allows for multiple types of
       packaging agents such as MIME and DIME.

DESCRIPTION

       The SOAP::Packager class is responsible for managing a set of "parts." Parts are
       additional pieces of information, additional documents, or virtually anything that needs
       to be associated with the SOAP Envelope/payload. The packager then will take these parts
       and encode/decode or "package"/"unpackage" them as they come and go over the wire.

METHODS

       new Instantiates a new instance of a SOAP::Packager.

       parts
           Contains an array of parts. The contents of this array and their types are completely
           dependent upon the Packager being used. For example, when using MIME, the content of
           this array is MIME::Entity's.

       push_part
           Adds a part to set of parts managed by the current instance of SOAP::Packager.

       parser
           Returns the parser used to parse attachments out of a data stream.

       headers_http
           This is a hook into the HTTP layer. It provides a way for a packager to add and/or
           modify HTTP headers in a request/response. For example, most packaging layers will
           need to override the Content-Type (e.g. multipart/related, or application/dime).

ABSTRACT METHODS

       If you wish to implement your own SOAP::Packager, then the methods below must be
       implemented by you according to the prescribed input and output requirements.

       package()
           The "package" subroutine takes as input the SOAP envelope in string/SCALAR form.  This
           will serve as the content of the root part. The packager then encapsulates the
           envelope with the parts contained within "parts" and returns the properly encapsulated
           envelope in string/SCALAR form.

       unpackage()
           The "unpackage" subroutines takes as input raw data that needs to be parsed into a set
           of parts. It is responsible for extracting the envelope from the input, and populating
           "parts" with an ARRAY of parts extracted from the input. It then returns the SOAP
           Envelope in string/SCALAR form so that SOAP::Lite can parse it.

SUPPORTED PACKAGING FORMATS

   SOAP::Packager::MIME
       "SOAP::Packager::MIME" utilizes MIME::Tools to provides the ability to send and receive
       Multipart/Related and Multipart/Form-Data formatted requests and responses.

       MIME METHODS

       The following methods are used when composing a MIME formatted message.

       transfer_encoding
           The value of the root part's Content-Transfer-Encoding MIME Header. Default is: 8bit.

       env_id
           The value of the root part's Content-Id MIME Header. Default is: <main_envelope>.

       env_location
           The value of the root part's Content-Location MIME Header. Default is: /main_envelope.

       env_type
           The value of the root part's Content-Type MIME Header. Default is: text/xml.

       OPTIMIZING THE MIME PARSER

       The use of attachments can often result in a heavy drain on system resources depending
       upon how your MIME parser is configured. For example, you can instruct the parser to store
       attachments in memory, or to use temp files. Using one of the other can affect
       performance, disk utilization, and/or reliability. Therefore you should consult the
       following URL for optimization techniques and trade-offs:

       http://search.cpan.org/dist/MIME-tools/lib/MIME/Parser.pm#OPTIMIZING_YOUR_PARSER

       To modify the parser's configuration options consult the following code sample, which
       incidentally shows how to minimize memory utilization:

         my $packager = SOAP::Packager::MIME->new;
         # $packager->parser->decode_headers(1); # no difference
         # $packager->parser->extract_nested_messages(1); # no difference
         $packager->parser->output_to_core(0); # much less memory
         $packager->parser->tmp_to_core(0); # much less memory
         $packager->parser->tmp_recycling(0); # promotes faster garbage collection
         $packager->parser->use_inner_files(1); # no difference
         my $client = SOAP::Lite->uri($NS)->proxy($URL)->packager($packager);
         $client->someMethod();

       CLIENT SIDE EXAMPLE

       The following code sample shows how to use attachments within the context of a SOAP::Lite
       client.

         #!/usr/bin/perl
         use SOAP::Lite;
         use MIME::Entity;
         my $ent = build MIME::Entity
           Type        => "text/plain",
           Path        => "attachment.txt",
           Filename    => "attachment.txt",
           Disposition => "attachment";
         $NS = "urn:Majordojo:TemperatureService";
         $HOST = "http://localhost/cgi-bin/soaplite.cgi";
         my $client = SOAP::Lite
           ->packager(SOAP::Packager::MIME->new)
           ->parts([ $ent ])
           ->uri($NS)
           ->proxy($HOST);
         $response = $client->c2f(SOAP::Data->name("temperature" => '100'));
         print $response->valueof('//c2fResponse/foo');

       SERVER SIDE EXAMPLE

       The following code shows how to use attachments within the context of a CGI script. It
       shows how to read incoming attachments, and to return attachments to the client.

         #!/usr/bin/perl -w
         use SOAP::Transport::HTTP;
         use MIME::Entity;
         SOAP::Transport::HTTP::CGI
           ->packager(SOAP::Packager::MIME->new)
           ->dispatch_with({'urn:Majordojo:TemperatureService' => 'TemperatureService'})
           ->handle;

         BEGIN {
           package TemperatureService;
           use vars qw(@ISA);
           @ISA = qw(Exporter SOAP::Server::Parameters);
           use SOAP::Lite;
           sub c2f {
             my $self = shift;
             my $envelope = pop;
             my $temp = $envelope->dataof("//c2f/temperature");
             use MIME::Entity;
             my $ent = build MIME::Entity
               Type        => "text/plain",
               Path        => "printenv",
               Filename    => "printenv",
               Disposition => "attachment";
             # read attachments
             foreach my $part (@{$envelope->parts}) {
               print STDERR "soaplite.cgi: attachment found! (".ref($part).")\n";
               print STDERR "soaplite.cgi: contents => ".$part->stringify."\n";
             }
             # send attachments
             return SOAP::Data->name('convertedTemp' => (((9/5)*($temp->value)) + 32)),
               $ent;
           }
         }

   SOAP::Packager::DIME
       TODO

SEE ALSO

       MIME::Tools, DIME::Tools

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

       Byrne Reese (byrne@majordojo.com)