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 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::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.
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.
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::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::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::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¶
TODO
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)