1SOAP::Packager(3) User Contributed Perl Documentation SOAP::Packager(3)
2
6 SOAP::Packager - this class is an abstract class which allows for mul‐
7 tiple types of packaging agents such as MIME and DIME.
8
10 The SOAP::Packager class is responsible for managing a set of "parts."
11 Parts are additional pieces of information, additional documents, or
12 virtually anything that needs to be associated with the SOAP Enve‐
13 lope/payload. The packager then will take these parts and encode/decode
14 or "package"/"unpackage" them as they come and go over the wire.
15
17 new Instantiates a new instance of a SOAP::Packager.
18 parts
20 Contains an array of parts. The contents of this array and their
21 types are completely dependant upon the Packager being used. For
22 example, when using MIME, the content of this array is
23 MIME::Entity's.
24 push_part
26 Adds a part to set of parts managed by the current instance of
27 SOAP::Packager.
28 parser
30 Returns the parser used to parse attachments out of a data stream.
31 headers_http
33 This is a hook into the HTTP layer. It provides a way for a pack‐
34 ager to add and/or modify HTTP headers in a request/response. For
35 example, most packaging layers will need to override the Content-
36 Type (e.g. multipart/related, or application/dime).
37
39 If you wish to implement your own SOAP::Packager, then the methods
40 below must be implemented by you according to the prescribed input and
41 output requirements.
42 package()
44 The "package" subroutine takes as input the SOAP envelope in
45 string/SCALAR form. This will serve as the content of the root
46 part. The packager then encapsulates the envelope with the parts
47 contained within "parts" and returns the properly encapsulated
48 envelope in string/SCALAR form.
49 unpackage()
51 The "unpackage" subroutines takes as input raw data that needs to
52 be parsed into a set of parts. It is responsible for extracting the
53 envelope from the input, and populating "parts" with an ARRAY of
54 parts extracted from the input. It then returns the SOAP Envelope
55 in string/SCALAR form so that SOAP::Lite can parse it.
56
58 SOAP::Packager::MIME
59 "SOAP::Packager::MIME" utilizes MIME::Tools to provides the ability to
61 send and receive Multipart/Related and Multipart/Form-Data formatted
62 requests and responses.
63 MIME METHODS
65 The following methods are used when composing a MIME formatted message.
67 transfer_encoding
69 The value of the root part's Content-Transfer-Encoding MIME Header.
70 Default is: 8bit.
71 env_id
73 The value of the root part's Content-Id MIME Header. Default is:
74 <main_envelope>.
75 env_location
77 The value of the root part's Content-Location MIME Header. Default
78 is: /main_envelope.
79 env_type
81 The value of the root part's Content-Type MIME Header. Default is:
82 text/xml.
83 OPTIMIZING THE MIME PARSER
85 The use of attachments can often result in a heavy drain on system
87 resources depending upon how your MIME parser is configured. For exam‐
88 ple, you can instruct the parser to store attachments in memory, or to
89 use temp files. Using one of the other can affect performance, disk
90 utilization, and/or reliability. Therefore you should consult the fol‐
91 lowing URL for optimization techniques and trade-offs:
92 http://search.cpan.org/dist/MIME-tools/lib/MIME/Parser.pm#OPTIMIZ‐
94 ING_YOUR_PARSER
95 To modify the parser's configuration options consult the following code
97 sample, which incidentally shows how to minimize memory utilization:
98 my $packager = SOAP::Packager::MIME->new;
100 # $packager->parser->decode_headers(1); # no difference
101 # $packager->parser->extract_nested_messages(1); # no difference
102 $packager->parser->output_to_core(0); # much less memory
103 $packager->parser->tmp_to_core(0); # much less memory
104 $packager->parser->tmp_recycling(0); # promotes faster garbage collection
105 $packager->parser->use_inner_files(1); # no difference
106 my $client = SOAP::Lite->uri($NS)->proxy($URL)->packager($packager);
107 $client->someMethod();
108 CLIENT SIDE EXAMPLE
110 The following code sample shows how to use attachments within the con‐
112 text of a SOAP::Lite client.
113 #!/usr/bin/perl
115 use SOAP::Lite;
116 use MIME::Entity;
117 my $ent = build MIME::Entity
118 Type => "text/plain",
119 Path => "attachment.txt",
120 Filename => "attachment.txt",
121 Disposition => "attachment";
122 $NS = "urn:Majordojo:TemperatureService";
123 $HOST = "http://localhost/cgi-bin/soaplite.cgi";
124 my $client = SOAP::Lite
125 ->packager(SOAP::Packager::MIME->new)
126 ->parts([ $ent ])
127 ->uri($NS)
128 ->proxy($HOST);
129 $response = $client->c2f(SOAP::Data->name("temperature" => '100'));
130 print $response->valueof('//c2fResponse/foo');
131 SERVER SIDE EXAMPLE
133 The following code shows how to use attachments within the context of a
135 CGI script. It shows how to read incoming attachments, and to return
136 attachments to the client.
137 #!/usr/bin/perl -w
139 use SOAP::Transport::HTTP;
140 use MIME::Entity;
141 SOAP::Transport::HTTP::CGI
142 ->packager(SOAP::Packager::MIME->new)
143 ->dispatch_with({'urn:Majordojo:TemperatureService' => 'TemperatureService'})
144 ->handle;
145 BEGIN {
147 package TemperatureService;
148 use vars qw(@ISA);
149 @ISA = qw(Exporter SOAP::Server::Parameters);
150 use SOAP::Lite;
151 sub c2f {
152 my $self = shift;
153 my $envelope = pop;
154 my $temp = $envelope->dataof("//c2f/temperature");
155 use MIME::Entity;
156 my $ent = build MIME::Entity
157 Type => "text/plain",
158 Path => "printenv",
159 Filename => "printenv",
160 Disposition => "attachment";
161 # read attachments
162 foreach my $part (@{$envelope->parts}) {
163 print STDERR "soaplite.cgi: attachment found! (".ref($part).")\n";
164 print STDERR "soaplite.cgi: contents => ".$part->stringify."\n";
165 }
166 # send attachments
167 return SOAP::Data->name('convertedTemp' => (((9/5)*($temp->value)) + 32)),
168 $ent;
169 }
170 }
171 SOAP::Packager::DIME
173 TODO
175
177 MIME::Tools, DIME::Tools
178
180 Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.
181 This library is free software; you can redistribute it and/or modify it
183 under the same terms as Perl itself.
184
186 Byrne Reese (byrne@majordojo.com)
187perl v5.8.8 2006-06-15 SOAP::Packager(3)