SOAP::Lite::Packager(3pm)

1SOAP::Lite::Packager(3)User Contributed Perl DocumentatioSnOAP::Lite::Packager(3)
2
3
4

NAME

6       SOAP::Lite::Packager - this class is an abstract class which allows for
7       multiple types of packaging agents such as MIME and DIME.
8

DESCRIPTION

10       The SOAP::Lite::Packager class is responsible for managing a set of
11       "parts." Parts are additional pieces of information, additional
12       documents, or virtually anything that needs to be associated with the
13       SOAP 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

METHODS

18       new Instantiates a new instance of a SOAP::Lite::Packager.
19
20       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
26       push_part
27           Adds a part to set of parts managed by the current instance of
28           SOAP::Lite::Packager.
29
30       parser
31           Returns the parser used to parse attachments out of a data stream.
32
33       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

ABSTRACT METHODS

40       If you wish to implement your own SOAP::Lite::Packager, then the
41       methods below must be implemented by you according to the prescribed
42       input and output requirements.
43
44       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
51       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

SUPPORTED PACKAGING FORMATS

59   SOAP::Lite::Packager::MIME
60       "SOAP::Lite::Packager::MIME" utilizes MIME::Tools to provides the
61       ability to send and receive Multipart/Related and Multipart/Form-Data
62       formatted requests and responses.
63
64       MIME METHODS
65
66       The following methods are used when composing a MIME formatted message.
67
68       transfer_encoding
69           The value of the root part's Content-Transfer-Encoding MIME Header.
70           Default is: 8bit.
71
72       env_id
73           The value of the root part's Content-Id MIME Header. Default is:
74           <main_envelope>.
75
76       env_location
77           The value of the root part's Content-Location MIME Header. Default
78           is: /main_envelope.
79
80       env_type
81           The value of the root part's Content-Type MIME Header. Default is:
82           text/xml.
83
84       OPTIMIZING THE MIME PARSER
85
86       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
93       http://search.cpan.org/dist/MIME-tools/lib/MIME/Parser.pm#OPTIMIZING_YOUR_PARSER
94
95       To modify the parser's configuration options consult the following code
96       sample, which incidentally shows how to minimize memory utilization:
97
98         my $packager = SOAP::Lite::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
108       CLIENT SIDE EXAMPLE
109
110       The following code sample shows how to use attachments within the
111       context of a SOAP::Lite client.
112
113         #!/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         $NS = "urn:Majordojo:TemperatureService";
122         $HOST = "http://localhost/cgi-bin/soaplite.cgi";
123         my $client = SOAP::Lite
124           ->packager(SOAP::Lite::Packager::MIME->new)
125           ->parts([ $ent ])
126           ->uri($NS)
127           ->proxy($HOST);
128         $response = $client->c2f(SOAP::Data->name("temperature" => '100'));
129         print $response->valueof('//c2fResponse/foo');
130
131       SERVER SIDE EXAMPLE
132
133       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
137         #!/usr/bin/perl -w
138         use SOAP::Transport::HTTP;
139         use MIME::Entity;
140         SOAP::Transport::HTTP::CGI
141           ->packager(SOAP::Lite::Packager::MIME->new)
142           ->dispatch_with({'urn:Majordojo:TemperatureService' => 'TemperatureService'})
143           ->handle;
144
145         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
171   SOAP::Lite::Packager::DIME
172       TODO
173

COPYRIGHT

178       Copyright (C) 2000-2007 Paul Kulchenko. All rights reserved.
179
180       This library is free software; you can redistribute it and/or modify it
181       under the same terms as Perl itself.
182

AUTHORS

184       Byrne Reese
185
186       Martin Kutter <martin.kutter fen-net.de>
187
188
189
190perl v5.12.3                      2010-06-03           SOAP::Lite::Packager(3)