1SOAP::Packager(3) User Contributed Perl Documentation SOAP::Packager(3)
2
6 SOAP::Packager - this class is an abstract class which allows for
7 multiple 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
13 Envelope/payload. The packager then will take these parts and
14 encode/decode or "package"/"unpackage" them as they come and go over
15 the wire.
16
18 new Instantiates a new instance of a SOAP::Packager.
19 parts
21 Contains an array of parts. The contents of this array and their
22 types are completely dependent upon the Packager being used. For
23 example, when using MIME, the content of this array is
24 MIME::Entity's.
25 push_part
27 Adds a part to set of parts managed by the current instance of
28 SOAP::Packager.
29 parser
31 Returns the parser used to parse attachments out of a data stream.
32 headers_http
34 This is a hook into the HTTP layer. It provides a way for a
35 packager to add and/or modify HTTP headers in a request/response.
36 For example, most packaging layers will need to override the
37 Content-Type (e.g. multipart/related, or application/dime).
38
40 If you wish to implement your own SOAP::Packager, then the methods
41 below must be implemented by you according to the prescribed input and
42 output requirements.
43 package()
45 The "package" subroutine takes as input the SOAP envelope in
46 string/SCALAR form. This will serve as the content of the root
47 part. The packager then encapsulates the envelope with the parts
48 contained within "parts" and returns the properly encapsulated
49 envelope in string/SCALAR form.
50 unpackage()
52 The "unpackage" subroutines takes as input raw data that needs to
53 be parsed into a set of parts. It is responsible for extracting the
54 envelope from the input, and populating "parts" with an ARRAY of
55 parts extracted from the input. It then returns the SOAP Envelope
56 in string/SCALAR form so that SOAP::Lite can parse it.
57
59 SOAP::Packager::MIME
60 "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
88 example, you can instruct the parser to store attachments in memory, or
89 to use temp files. Using one of the other can affect performance, disk
90 utilization, and/or reliability. Therefore you should consult the
91 following URL for optimization techniques and trade-offs:
92 http://search.cpan.org/dist/MIME-tools/lib/MIME/Parser.pm#OPTIMIZING_YOUR_PARSER
94 To modify the parser's configuration options consult the following code
96 sample, which incidentally shows how to minimize memory utilization:
97 my $packager = SOAP::Packager::MIME->new;
99 # $packager->parser->decode_headers(1); # no difference
100 # $packager->parser->extract_nested_messages(1); # no difference
101 $packager->parser->output_to_core(0); # much less memory
102 $packager->parser->tmp_to_core(0); # much less memory
103 $packager->parser->tmp_recycling(0); # promotes faster garbage collection
104 $packager->parser->use_inner_files(1); # no difference
105 my $client = SOAP::Lite->uri($NS)->proxy($URL)->packager($packager);
106 $client->someMethod();
107 CLIENT SIDE EXAMPLE
109 The following code sample shows how to use attachments within the
111 context of a SOAP::Lite client.
112 #!/usr/bin/perl
114 use SOAP::Lite;
115 use MIME::Entity;
116 my $ent = build MIME::Entity
117 Type => "text/plain",
118 Path => "attachment.txt",
119 Filename => "attachment.txt",
120 Disposition => "attachment";
121 my $NS = "urn:Majordojo:TemperatureService";
122 my $HOST = "http://localhost/cgi-bin/soaplite.cgi";
123 my $client = SOAP::Lite
124 ->packager(SOAP::Packager::MIME->new)
125 ->parts([ $ent ])
126 ->uri($NS)
127 ->proxy($HOST);
128 my $response = $client->c2f(SOAP::Data->name("temperature" => '100'));
129 print $response->valueof('//c2fResponse/foo');
130 SERVER SIDE EXAMPLE
132 The following code shows how to use attachments within the context of a
134 CGI script. It shows how to read incoming attachments, and to return
135 attachments to the client.
136 #!/usr/bin/perl -w
138 use SOAP::Transport::HTTP;
139 use MIME::Entity;
140 SOAP::Transport::HTTP::CGI
141 ->packager(SOAP::Packager::MIME->new)
142 ->dispatch_with({'urn:Majordojo:TemperatureService' => 'TemperatureService'})
143 ->handle;
144 BEGIN {
146 package TemperatureService;
147 use vars qw(@ISA);
148 @ISA = qw(Exporter SOAP::Server::Parameters);
149 use SOAP::Lite;
150 sub c2f {
151 my $self = shift;
152 my $envelope = pop;
153 my $temp = $envelope->dataof("//c2f/temperature");
154 use MIME::Entity;
155 my $ent = build MIME::Entity
156 Type => "text/plain",
157 Path => "printenv",
158 Filename => "printenv",
159 Disposition => "attachment";
160 # read attachments
161 foreach my $part (@{$envelope->parts}) {
162 print STDERR "soaplite.cgi: attachment found! (".ref($part).")\n";
163 print STDERR "soaplite.cgi: contents => ".$part->stringify."\n";
164 }
165 # send attachments
166 return SOAP::Data->name('convertedTemp' => (((9/5)*($temp->value)) + 32)),
167 $ent;
168 }
169 }
170 SOAP::Packager::DIME
172 TODO
173
175 MIME::Tools, DIME::Tools
176
178 Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.
179 This library is free software; you can redistribute it and/or modify it
181 under the same terms as Perl itself.
182
184 Byrne Reese (byrne@majordojo.com)
185perl v5.38.0 2023-07-21 SOAP::Packager(3)