Gantry::Plugins::SOAP::Doc - document style SOAP support

Gantry documentation Contained in the Gantry distribution.

Index

Code Index:

NAME

Top

Gantry::Plugins::SOAP::Doc - document style SOAP support

SYNOPSIS

Top

In a controller:

    use Your::App::BaseModule qw(
         -PluginNamespace=YourApp
         SOAP::Doc
    );
    # This exports these into the site object:
    #    soap_out
    #    do_wsdl
    #    return_error

    do_a_soap_action {
        my $self        = shift;
        my $data        = $self->get_post_body();
        my $parsed_data = XMLin( $data );

        # Use data to process the request, until you have a
        # structure like:

        my $ret_struct = [
            {
                yourResponseType => [
                    { var  => value  },
                    { var2 => value2 },
                    { var3 => undef  }, # for required empty tags
                    { nesting_var => [
                        { subvar => value },
                    ] }
                ]
            }
        ] );

        return $self->soap_out( $ret_struct, 'prefix', 'pretty' );
    }

DESCRIPTION

Top

This module supports document style SOAP. If you need rpc style, see Gantry::Plugins::SOAP::RPC.

This module must be used as a plugin, so it can register a pre_init callback to take the POSTed body from the HTTP request before the engine can mangle it, in a vain attempt to make form parameters from it.

The document style SOAP request must find its way to your do_ method via its soap_action URL and Gantry's normal dispatching mechanism. Once the do_ method is called, your SOAP request is available via the get_post_body accessor exported by each engine. That request is exactly as received. You probably want to use XML::Simple's XMLin function to extract your data. I would do that for you here, but you might need to set attributes of the parsing like ForceArray.

When you have finished processing the request, you have two choices. If it did not go well, call return_error to deliver a SOAP fault to client. Using die or croak is a bad idea as that will return a regular Gantry error message which is obviously not SOAP compliant.

If you succeeded in handling the request, return an array of hashes. Each hash is keyed by XML tag (not including namespace prefix). The value can be a scalar or an array of hashes like the top level one. If the value is undef, an empty tag will be generated.

Generally, you need to take all of the exports from this module, unless you want to replace them with your own versions.

If you need to control the namespace of the returned parameters, call soap_namespace_set with the URL of the namespace before returning. If you don't do that the namespace will default to http://example.com/ns.

METHODS

Top

new

For use by non-web scripts. Call this with a hash of attributes. Currently only the target_namespace key is used. It sets the namespace. Once you get your object, you can call soap_out on it as you would in a Gantry conroller.

get_callbacks

Only for use by Gantry.pm.

This is used to register steal_post_body as a pre init callback with Gantry.

steal_post_body

Not for external use.

Just a carefully timed call to consume_post_body exported by each engine. This is registered as a pre_init callback, so it gets the body before normal form parameter parsing would.

You may retrieve with the post body with get_post_body (also exported by each engine). No processing of the request is done. You will receive whatever the SOAP client generated. That should be XML, but even that depends on the client.

soap_current_time

Returns the UTC in SOAP format.

soap_serialize_xml

This method is registered as a callback. Durning the post_init phase it will create a hash from the $self->get_post_body() and store the result in $self->params();

soap_namespace

Called internally to retrieve the namespace for the XML tags in your SOAP response. Call soap_namespace_set if you need to set a particular namespace (some clients will care). Otherwise, the default namespace http://example.com/ns will be used.

soap_namespace_set

Use this to set the namespace for your the tags in your XML response. The default namespace is http://example.com/ns.

soap_out

Parameters:

structure

actual data to send to the client. See SYNOPSIS and DESCRIPTION.

namespace_style

prefix or internal. Use prefix to define the namespace in the soap:Envelope declaration and use it as a prefix on all the return parameter tags. Use internal if you want the prefix to be defined in the outer tag of the response parameters.

To set the value of the namespace, call soap_namespace_set before calling this method.

pretty

true if you want pretty printing, false if not

By default returned XML will be whitespace compressed. If you want it to be pretty printed for debugging, pass any true value to this method as the second parameter, in a scenario like this:

    my $check_first = $self->soap_out(
            $structure, 'prefix', 'pretty_please'
    );
    warn $check_first;
    return $check_first;

Call this with the data to return to the client. If that client cares about the namespace of the tags in the response, call soap_namespace_set first. See the SYNOPSIS for an example of the structure you must pass to this method. See the DESCRIPTION for an explanation of what you can put in the structure.

You should return the value returned from this method directly. It turns off all templating and sets the content type to text/xml.

build_args

Mostly for internal use.

soap_out uses this to turn your structure of return values into an XML snippet. If you need to re-implement soap_out, you could call this directly. The initial call should pass the same structure soap_out expects and (optionally) a pretty print flag. The returned value is the snippet of return params only. You would then need to build the SOAP envelope, etc.

return_error

This method returns a fault XML packet for you. Use it instead of die or croak.

do_wsdl

This method uses the wsdldoc.tt in your template path to return a WSDL file to your client. The view.data passed to that template comes directly from a call to get_soap_ops, which you must implement (even it it returns nothing).

send_xml

For clients. Sends the xml to the SOAP server. You must have called new with action_url and post_to_url for this method to work. In particular, servers which use this as a plugin cannot normally call this method. First, they must call new to make an object of this class.

Parameters: an object of this class, the xml to send (get it from calling soap_out).

Returns: response from remote server (actually whatever request on the LWP user agent retruns, try calling content on that object)

AUTHOR

Top

Phil Crow, <crow.phil@gmail.com> Tim Keefer, <tim@timkeefer.com<gt>

COPYRIGHT and LICENSE

Top

Copyright (c) 2007, Phil Crow

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.

Gantry documentation Contained in the Gantry distribution. 
package Gantry::Plugins::SOAP::Doc;

use strict;

use base 'Exporter';

use XML::Simple;
use XML::LibXML;
use POSIX qw( strftime );

our @EXPORT = qw(
    soap_out
    do_wsdl
    return_error
    soap_namespace
    soap_namespace_set
    soap_current_time
);

my %registered_callbacks;

#-----------------------------------------------------------
# $class->get_callbacks( $namespace )
#-----------------------------------------------------------
sub get_callbacks {
    my ( $class, $namespace ) = @_;

    return if ( $registered_callbacks{ $namespace }++ );

    warn 'Use -PluginNamespace=something when you use '
        .   'Gantry::Plugins::SOAP::Doc' if ( $namespace eq 'Gantry' );

    return (
        { phase => 'pre_init', callback => \&steal_post_body },
        { phase => 'post_init', callback => \&soap_serialize_xml }
    );
}

#-----------------------------------------------------------
# $class->new( \%attrs )
#-----------------------------------------------------------
sub new {
    my $class = shift;
    my $attrs = shift;

    my $self  = {
        __SOAP_NAMESPACE__ => $attrs->{ target_namespace } || '',
        %{ $attrs }
    };

    return bless $self, $class;
}

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

    my %params;

    if ( $self->get_post_body() ) {

        my $xmlobj = XML::LibXML->new();    
        my $dom    = $xmlobj->parse_string( $self->get_post_body() ) 
            or die "parsing XML $!";

        my @bodyNodes = $dom->getElementsByLocalName( 'Body' );

        _serialize( \%params, $bodyNodes[0] );
    }


    if ( $ENV{QUERY_STRING} ) {
        foreach my $q_param ( split( '&', $ENV{QUERY_STRING} ) ) {
            my( $k, $v ) = split( '=', $q_param );
        
            $params{$k} = $v if defined $v; 
        }
    }
    
    $self->params( \%params ); 
}

#-----------------------------------------------------------
# _serialize( \%params, node )
#-----------------------------------------------------------
sub _serialize {
    my( $params, $node ) = @_;
    
    my @nodes = $node->childNodes();
    
    foreach my $cnode ( @nodes ) {    
        if ( $cnode->hasChildNodes() ) {
            _serialize( $params, $cnode );
        }
        elsif ( $cnode->textContent =~ /\S/ ) {
            $params->{$cnode->parentNode->localname} = $cnode->textContent;
        }             
    }

}

#-----------------------------------------------------------
# $self->steal_post_body( $r_or_cgi )
#-----------------------------------------------------------
sub steal_post_body {
    my $self     = shift;
    my $r_or_cgi = shift;

    $self->consume_post_body( $r_or_cgi );
}

#-----------------------------------------------------------
# $self->soap_namespace(  )
#-----------------------------------------------------------
sub soap_namespace {
    my $self = shift;

    return $self->{__SOAP_NAMESPACE__};
}

#-----------------------------------------------------------
# $self->soap_namespace_set(  )
#-----------------------------------------------------------
sub soap_namespace_set {
    my $self      = shift;
    my $new_value = shift;

    $self->{__SOAP_NAMESPACE__} = $new_value;
}

#-----------------------------------------------------------
# $self->soap_out( $data )
#-----------------------------------------------------------
sub soap_out {
    my $self     = shift;
    my $data     = shift;
    my $ns_style = shift;
    my $pretty   = shift;

    my $ns     = $self->soap_namespace || 'http://example.com/ns';
    my $args   = build_args( {
        data     => $data,
        pretty   => $pretty,
        ns_style => $ns_style,
        ns       => $ns
    } );

    eval {
        $self->template_wrapper( 0 );
        $self->template_disable( 1 );
        $self->content_type( 'text/xml' );
    };
    # errors come from calling Gantry methods on instances of this class
    # used by client scripts

    my $prefix_ns = '';
    if ( $ns_style eq 'prefix' ) {
        $prefix_ns = qq!xmlns:tns="$ns"!;
    }

    return <<"EO_XML";
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               $prefix_ns
               xmlns:xs="http://www.w3.org/2001/XMLSchema" >
<soap:Body>
$args
</soap:Body>
</soap:Envelope>
EO_XML
}

#-----------------------------------------------------------------
# $self->soap_current_time(  )
# Thanks to Joe McMahon and his SOAP::DateTime module for
# the format below.
#-----------------------------------------------------------------
sub soap_current_time {
    my @time_pieces = gmtime;
    return strftime( '%Y-%m-%dT%H:%M:%SZ', @time_pieces );
} # END _get_current_time

#-----------------------------------------------------------
# build_args( $request_args, $pretty_flag, $depth )
# This is not a method, but it is RECURSIVE.  Initial
# callers need supply only the first argument.
#-----------------------------------------------------------
sub build_args { # recursive
    my $all_params   = shift;
    my $request_args = $all_params->{ data   };
    my $pretty       = $all_params->{ pretty };
    my $depth        = $all_params->{ depth  } || 0;
    my $retval       = '';

    my $ns_prefix    = '';
    my $internal_ns  = '';

    if ( $all_params->{ ns_style } eq 'prefix' ) {
        $ns_prefix = 'tns:';
    }
    elsif ( $all_params->{ ns } ) {
        $internal_ns  = qq!\n    xmlns="$all_params->{ ns }"!;
    }

    return $request_args unless ref( $request_args ) eq 'ARRAY';

    # pretty printed for debugging:
    my $indent       = ( $pretty ) ? ' ' x ( 2 * $depth ) : '';
    my $nl           = ( $pretty ) ? "\n"                 : '';
    
    foreach my $arg ( @{ $request_args } ) {
        my ( $key, $values ) = %{ $arg };
        
        if ( defined $values ) {
            my $start_tag    = "$indent<$ns_prefix$key$internal_ns>";
            my $child_output = build_args( {
                data     => $values,
                pretty   => $pretty,
                depth    => $depth + 1,
                ns_style => $all_params->{ ns_style },
            } );
            my $end_tag      = "</$ns_prefix$key>$nl";
            
            # now pretty print it pretty please
            if ( ref( $values ) eq 'ARRAY' ) {
                $start_tag = "$start_tag$nl";
                $end_tag   = "$indent$end_tag";
            }

            $retval       .= "$start_tag$child_output$end_tag";
        }
        else {  # values is undef or the empty string
            $retval .= "$indent<$ns_prefix$key/>$nl";
        }
    }

    return $retval;
} # end of build_args

#-----------------------------------------------------------
# $self->return_error( $error_text )
#-----------------------------------------------------------
sub return_error {
    my ( $self, $error ) = @_;

    return <<"EO_XML_FAULT";
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema" >
  <soap:Body>
    <soap:Fault>
    <faultcode>soap:Server</faultcode>
    <faultstring>$error</faultstring>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>
EO_XML_FAULT
}

#-----------------------------------------------------------------
# $self->do_wsdl
#-----------------------------------------------------------------
sub do_wsdl {
    my $self = shift;

    $self->stash->view->template( 'wsdldoc.tt' );

    $self->stash->view->data( $self->get_soap_ops );

    delete $self->{__TEMPLATE_WRAPPER__};
    my $wsdl = $self->do_process();

    $self->template_disable( 1 );
    $self->content_type( 'text/xml' );

    return $wsdl;
} # END do_wsdl

#-----------------------------------------------------------------
# $self->send_xml
#-----------------------------------------------------------------
sub send_xml {
    my $self        = shift;
    my $request_xml = shift;

    require LWP::UserAgent;

    my $user_agent = LWP::UserAgent->new();
    $user_agent->agent( 'Sunflower/1.0' );

    my $request = HTTP::Request->new(
        POST => $self->{ post_to_url }
    );

    $request->content_type( 'text/xml; charset=utf-8' );
    $request->content_length( length $request_xml );
    $request->header( 'Host' => $self->{ host } ) if $self->{ host };
    $request->header( 'SoapAction' => $self->{ action_url } );
    $request->content( $request_xml );

    return $user_agent->request( $request );
}

1;