view release on metacpan or  search on metacpan

lib/Gantry/Docs/Cookbook.pod  view on Meta::CPAN

    controller SOAP {
        rel_location GantrySoapService;
        skip_test 1;
        plugins SOAP::Doc;
        method do_f2c is stub {
        }
    }

When you regenerate, you'll have a new SOAP.pm in which to place your
code.  It will inherit from a GEN module that uses the document style
SOAP plugin.  Then you'll have to fill in the code for the do_f2c routine.
Bigtop made this stub:

    #-----------------------------------------------------------------
    # $self->do_f2c(  )
    #-----------------------------------------------------------------
    sub do_f2c {
        my ( $self ) = @_;
    }

All we need to do is fill it in.

If all the SOAP request parameters are at the same level in their packet
(a fairly common case), you can take advantage of the plugin's automated
conversion of the SOAP packet into form parameters.  If your SOAP packet
has nested tags, you'll need to parse the XML with a module like
C<XML::LibXML> or C<XML::Twig>.  The sample's packets are simple.

Here is the finished routine (less comments offering advice on XML::LibXML):

  1   sub do_f2c {
  2     my ( $self ) = @_;
  3     my $time     = $self->soap_current_time();
  4     my $params   = $self->params();  # easy way
  5
  6     my $f_temp   = $params->{ farenheit };
  7     my $celcius  = 5.0 * ( $f_temp - 32 ) / 9.0;
  8
  9     my $ret_struct = [
 10         {
 11             GantrySoapServiceResponse => [
 12                 { currentUTCTime => $time },
 13                 { celcius        => $celcius },
 14             ]
 15         }
 16     ];
 17
 18     $self->soap_namespace_set(
 19         'http://usegantry.org/soapservice'
 20     );
 21
 22     return $self->soap_out( $ret_struct, 'internal', 'pretty' );
 23 } # END do_f2c

If you need to tell your client the UTC time of your response in valid
SOAP time format, call C<soap_current_time>, as I did on line 3.

Since my server's SOAP requests are simple, I can call C<params>
on line 5, just as I would to handle form parameters.  The input
parameter is in the C<farenheit> key (line 6).  A grade school formula
does the conversion on line 8.

Lines 9-16 build the structure of the return packet.  The top level
tag is C<GantrySoapServiceResponse>.  Inside it will be a list of tags
(order often matters to DTDs), one for the time, the other for the
converted temperature.

To control the namespace of C<GantrySoapServiceResponse> and its children,
I called C<soap_namespace_set> (line 18).

Finally, line 22 uses C<soap_out> to send the packet back to the client.
It expects:

=over 4

=item return structure

See the example above.  If you need a empty tag like <empty />, use

    { empty => undef }

=item namespace position

This must be a string chosen from 'prefix' or 'internal'.  The default
is prefix.  This governs where the namespace is defined, and therefore
has a cosmetic effect on the SOAP packet.  A prefix namespace is
defined in the SOAP Envelope tag where it is given the prefix tns.
That prefix appears on all tags in the returned packet.

If you use internal instead, the namespace is defined in the top level tag:

    <GantrySoapServiceResponse
        xmlns="http://usegantry.org/soapservice">

Then the elements in the body of the response have no explicit namespace
prefix.

=item pretty print

If this has a true value, the resulting XML packet will have various
whitespace added to it to improve human readability.  No whitespace will
be added anywhere that would affect parsing the result.

=back

That's all there is to a document style SOAP server in Gantry.

=head1 How do I use Gantry to build a SOAP client?

There is a sample SOAP client in samples/bin/soapclient.  There are three
parts to a SOAP client: build the XML for the request, send that XML to
the proper URL, parse the response (this list leaves out coming up with
the data for the request).  Gantry can help with the first one, but you
need LWP or something similar for the other two.

Here is commentary on the soapclient sample.

    se strict; use warnings;

    use lib qw( lib ../lib );