SOAP::L...ackager(3)

okay bestie, welcome to the SOAP::L...ackager(3) page from the User Contributed Perl Documentation collection. The actual class is SOAP::Lite::Packager, and this is its whole abstract-packaging era. 💅

💖 NAME 💖

SOAP::Lite::Packager — this class is an abstract class which allows for multiple types of packaging agents such as MIME and DIME. No cap, that's the whole name bit.

✨ DESCRIPTION ✨

So the SOAP::Lite::Packager class is the one managing a set of "parts." Parts are extra pieces of info, extra documents, or literally anything that needs to be associated with the SOAP Envelope/payload. Then the packager takes those parts and encodes/decodes them — aka "packages"/"unpackages" 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 the 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. Like, you can't just vibe your way through this part, bestie. 💀

• 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 subroutine 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 provide the ability to send and receive Multipart/Related and Multipart/Form-Data formatted requests and responses. Obsessed, honestly. 💖

✨ 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 or 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::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

That's it. The page literally just says TODO. Not me leaving you on read — that's the source. 💀

🍓 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>

xoxo, bestie — this page was served from perl v5.42.0, dated 2024-03-04, and the footer name is SOAP::L...ackager(3). 💖✨