SOAP::Lite::Packager(3User Contributed Perl DocumentaSOAP::Lite::Packager(3pm)
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_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
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>
perl v5.36.0 2023-03-01 SOAP::Lite::Packager(3pm)
Generated by dwww version 1.15 on Wed Jun 26 00:55:02 CEST 2024.