SOAP::Lite::Packager - phpMan

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

DESCRIPTION
    The SOAP::Lite::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::Lite::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::Lite::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::Lite::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::Lite::Packager::MIME
    "SOAP::Lite::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_YOU
    R_PARSER

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

      my $packager = SOAP::Lite::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::Lite::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::Lite::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::Lite::Packager::DIME
    TODO

SEE ALSO
    MIME::Tools, DIME::Tools

COPYRIGHT
    Copyright (C) 2000-2007 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

    Martin Kutter <martin.kutter fen-net.de>