.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SOAP::Lite::Packager 3"
.TH SOAP::Lite::Packager 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
SOAP::Lite::Packager \- this class is an abstract class which allows for multiple types of packaging agents such as MIME and DIME.
.SH DESCRIPTION
.IX Header "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.
.SH METHODS
.IX Header "METHODS"
.IP new 4
.IX Item "new"
Instantiates a new instance of a SOAP::Lite::Packager.
.IP parts 4
.IX Item "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.
.IP push_part 4
.IX Item "push_part"
Adds a part to set of parts managed by the current instance of SOAP::Lite::Packager.
.IP parser 4
.IX Item "parser"
Returns the parser used to parse attachments out of a data stream.
.IP headers_http 4
.IX Item "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).
.SH "ABSTRACT METHODS"
.IX Header "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.
.IP \fBpackage()\fR 4
.IX Item "package()"
The \f(CW\*(C`package\*(C'\fR 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 \f(CW\*(C`parts\*(C'\fR and returns the properly
encapsulated envelope in string/SCALAR form.
.IP \fBunpackage()\fR 4
.IX Item "unpackage()"
The \f(CW\*(C`unpackage\*(C'\fR 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 \f(CW\*(C`parts\*(C'\fR 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.
.SH "SUPPORTED PACKAGING FORMATS"
.IX Header "SUPPORTED PACKAGING FORMATS"
.SS SOAP::Lite::Packager::MIME
.IX Subsection "SOAP::Lite::Packager::MIME"
\&\f(CW\*(C`SOAP::Lite::Packager::MIME\*(C'\fR utilizes MIME::Tools to provides the ability to send
and receive Multipart/Related and Multipart/Form\-Data formatted requests and
responses.
.PP
\fIMIME METHODS\fR
.IX Subsection "MIME METHODS"
.PP
The following methods are used when composing a MIME formatted message.
.IP transfer_encoding 4
.IX Item "transfer_encoding"
The value of the root part's Content-Transfer-Encoding MIME Header. Default is: 8bit.
.IP env_id 4
.IX Item "env_id"
The value of the root part's Content-Id MIME Header. Default is: <main_envelope>.
.IP env_location 4
.IX Item "env_location"
The value of the root part's Content-Location MIME Header. Default is: /main_envelope.
.IP env_type 4
.IX Item "env_type"
The value of the root part's Content-Type MIME Header. Default is: text/xml.
.PP
\fIOPTIMIZING THE MIME PARSER\fR
.IX Subsection "OPTIMIZING THE MIME PARSER"
.PP
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:
.PP
http://search.cpan.org/dist/MIME\-tools/lib/MIME/Parser.pm#OPTIMIZING_YOUR_PARSER
.PP
To modify the parser's configuration options consult the following code sample,
which incidentally shows how to minimize memory utilization:
.PP
.Vb 9
\&  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();
.Ve
.PP
\fICLIENT SIDE EXAMPLE\fR
.IX Subsection "CLIENT SIDE EXAMPLE"
.PP
The following code sample shows how to use attachments within the context of a
SOAP::Lite client.
.PP
.Vb 10
\&  #!/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" => \*(Aq100\*(Aq));
\&  print $response\->valueof(\*(Aq//c2fResponse/foo\*(Aq);
.Ve
.PP
\fISERVER SIDE EXAMPLE\fR
.IX Subsection "SERVER SIDE EXAMPLE"
.PP
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.
.PP
.Vb 7
\&  #!/usr/bin/perl \-w
\&  use SOAP::Transport::HTTP;
\&  use MIME::Entity;
\&  SOAP::Transport::HTTP::CGI
\&    \->packager(SOAP::Lite::Packager::MIME\->new)
\&    \->dispatch_with({\*(Aqurn:Majordojo:TemperatureService\*(Aq => \*(AqTemperatureService\*(Aq})
\&    \->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).")\en";
\&        print STDERR "soaplite.cgi: contents => ".$part\->stringify."\en";
\&      }
\&      # send attachments
\&      return SOAP::Data\->name(\*(AqconvertedTemp\*(Aq => (((9/5)*($temp\->value)) + 32)),
\&        $ent;
\&    }
\&  }
.Ve
.SS SOAP::Lite::Packager::DIME
.IX Subsection "SOAP::Lite::Packager::DIME"
TODO
.SH "SEE ALSO"
.IX Header "SEE ALSO"
MIME::Tools, DIME::Tools
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2000\-2007 Paul Kulchenko. All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH AUTHORS
.IX Header "AUTHORS"
Byrne Reese
.PP
Martin Kutter <martin.kutter fen\-net.de>