SOAP::Packager (3)

Leading comments

Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/SOAP::Packager.3pm".)

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

The following methods are used when composing a

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.

The use of attachments can often result in a heavy drain on system resources depending upon how your

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 for optimization techniques and trade-offs:

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();

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";
  my $NS = "urn:Majordojo:TemperatureService";
  my $HOST = "http://localhost/cgi-bin/soaplite.cgi";
  my $client = SOAP::Lite
    ->packager(SOAP::Packager::MIME->new)
    ->parts([ $ent ])
    ->uri($NS)
    ->proxy($HOST);
  my $response = $client->c2f(SOAP::Data->name("temperature" => '100'));
  print $response->valueof('//c2fResponse/foo');

The following code shows how to use attachments within the context of a

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

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)