SOAP::EnvelopeMaker(3)User Contributed Perl DocumentatioSOAP::EnvelopeMaker(3)NAMESOAP::EnvelopeMaker - Creates SOAP envelopes
SYNOPSIS
use SOAP::EnvelopeMaker;
my $soap_request = ''; my $output_fcn = sub {
$soap_request .= shift; }; my $em = SOAP::EnvelopeMaker->new($out-
put_fcn);
my $body = SOAP::Struct->new(
origin => { x => 10, y => 20 },
corner => { x => 100, y => 200 }, );
$em->set_body("urn:com-develop-geometry", "calculateArea", 0, $body);
my $host = "soapl.develop.com"; my $port = 80; my $end-
point = "/soap?class=Geometry"; my $method_uri =
"urn:com-develop-geometry"; my $method_name = "calculateArea";
use SOAP::Transport::HTTP::Client;
my $soap_on_http = SOAP::Transport::HTTP::Client->new();
my $soap_response = $soap_on_http->send_receive($host, $port, $end-
point,
$method_uri,
$method_name,
$soap_request); use
SOAP::Parser; my $soap_parser = SOAP::Parser->new();
$soap_parser->parsestring($soap_response);
my $area = $soap_parser->get_body()->{result};
print "The area is: $area\n";
DESCRIPTION
The overall usage pattern of SOAP::EnvelopeMaker is as follows:
1) Determine what you want to do with the resulting SOAP packet
and create an output function that implements this policy.
2) Create an instance of SOAP::EnvelopeMaker, passing a reference
to your output function, or to a string if you were just planning
on buffering the output anyway (in this case, you'll get an output
function that looks like this: sub {$$r .= shift}
(note that somebody may already have done these first two steps
on your behalf and simply passed you a reference to a pre-initialized
EnvelopeMaker - see SOAP::Transport::HTTP::Server for an example)
3) (optional) Call add_header one or more times to specify headers.
4) (required) Call set_body to specify the body.
5) Throw away the EnvelopeMaker and do something with the envelope
that you've collected via your output function (assuming you've
not simply been piping the output somewhere as it's given to you).
EnvelopeMaker expects that you'll add *all* your headers *before* set-
ting the body - if you mess this up, the results are undefined.
By the time set_body returns, a complete SOAP envelope will have been
sent to your output function (in one or more chunks). You can
new(OutputFcn)
OutputFcn should accept a single scalar parameter, and will be called
multiple times with chunks of the SOAP envelope as it is constructed.
You can either append these chunks into a big string, waiting until the
entire envelope is constructed before you do something with it (like
calculate the content-length, for instance), or you can simply pipe
each chunk directly to somebody else.
As of version 0.25, you can now pass a string reference for OutputFcn
and the EnvelopeMaker will provide a very simple buffering output func-
tion (one that we all ended up writing anyway during testing): sub {$$r
.= shift}
add_header(AccessorUri, AccessorName, MustUnderstand, IsPackage,
Object)
The first two parameters allow you to specify a QName (qualified name)
for your header. Note that in SOAP, all headers MUST be namespace qual-
ified. MustUnderstand and IsPackage turn on SOAP features that are
explained in the SOAP spec; if you haven't yet grok'd SOAP packages,
just pass 0 for IsPackage. Finally, Object is whatever you'd like to
serialize into the header (see set_body for notes on what can go here;
headers can contain the same stuff as the body).
set_body(AccessorUri, AccessorName, IsPackage, Object)
The first two parameters allow you to specify a QName (qualified name)
for the body. The name of the accessor is the name of the SOAP method
call you're making. IsPackage says that the body will be a SOAP pack-
age; just pass 0 if you're not sure what this means. Object is whatever
you'd like to serialize. This can be one of the following things:
1) a scalar - the body will contain the scalar content.
2) a hash reference - the body will contain a SOAP serialized version
of the contents of the hash.
3) a SOAP::Struct reference - the body will contain a SOAP serialized
version of the struct, where the serial-
ized
contents of the struct will be in the
same
order in the SOAP bar as they appeared
in the SOAP::Struct constructor.
Note that the SOAP/Perl serialization architecture deals with refer-
ences very carefully, so it is possible to pass arbitrary object graphs
(although each "object reference" must currently be a non-blessed
scalar or hash reference).
In the future, expect to see support for passing blessed object refer-
ences (if you want to do this today, see the experimental
SOAP::TypeMapper). SOAP::Struct is an example of this.
One interesting thing SOAP (and SOAP/Perl) support is that the headers
and body can share references. They can point to the same stuff. Also,
cycle detection is a natural part of SOAP/Perl's serialization archi-
tecture, so you can pass linked lists, circular queues, etc. and they
will be rehydrated correctly.
DEPENDENCIES
SOAP::Envelope
AUTHOR
Keith Brown
SEE ALSO
SOAP::Envelope
perl v5.8.8 2000-09-05 SOAP::EnvelopeMaker(3)
