.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 .\" .\" Standard preamble: .\" ======================================================================== .de Sh \" Subsection heading .br .if t .Sp .ne 5 .PP \fB\\$1\fR .PP .. .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. | will give a .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' .\" expand to `' in nroff, nothing in troff, for use with C<>. .tr \(*W-|\(bv\*(Tr .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .\" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Gantry::Plugins::SOAP::Doc 3" .TH Gantry::Plugins::SOAP::Doc 3 "2008-01-18" "perl v5.8.8" "User Contributed Perl Documentation" .SH "NAME" Gantry::Plugins::SOAP::Doc \- document style SOAP support .SH "SYNOPSIS" .IX Header "SYNOPSIS" In a controller: .PP .Vb 8 \& use Your::App::BaseModule qw( \& -PluginNamespace=YourApp \& SOAP::Doc \& ); \& # This exports these into the site object: \& # soap_out \& # do_wsdl \& # return_error .Ve .PP .Vb 4 \& do_a_soap_action { \& my $self = shift; \& my $data = $self->get_post_body(); \& my $parsed_data = XMLin( $data ); .Ve .PP .Vb 2 \& # Use data to process the request, until you have a \& # structure like: .Ve .PP .Vb 12 \& my $ret_struct = [ \& { \& yourResponseType => [ \& { var => value }, \& { var2 => value2 }, \& { var3 => undef }, # for required empty tags \& { nesting_var => [ \& { subvar => value }, \& ] } \& ] \& } \& ] ); .Ve .PP .Vb 2 \& return $self->soap_out( $ret_struct, 'prefix', 'pretty' ); \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module supports document style \s-1SOAP\s0. If you need rpc style, see Gantry::Plugins::SOAP::RPC. .PP This module must be used as a plugin, so it can register a pre_init callback to take the POSTed body from the \s-1HTTP\s0 request before the engine can mangle it, in a vain attempt to make form parameters from it. .PP The document style \s-1SOAP\s0 request must find its way to your do_ method via its soap_action \s-1URL\s0 and Gantry's normal dispatching mechanism. Once the do_ method is called, your \s-1SOAP\s0 request is available via the \&\f(CW\*(C`get_post_body\*(C'\fR 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. .PP When you have finished processing the request, you have two choices. If it did not go well, call \f(CW\*(C`return_error\*(C'\fR to deliver a \s-1SOAP\s0 fault to client. Using die or croak is a bad idea as that will return a regular Gantry error message which is obviously not \s-1SOAP\s0 compliant. .PP If you succeeded in handling the request, return an array of hashes. Each hash is keyed by \s-1XML\s0 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 \f(CW\*(C`undef\*(C'\fR, an empty tag will be generated. .PP Generally, you need to take all of the exports from this module, unless you want to replace them with your own versions. .PP If you need to control the namespace of the returned parameters, call \&\f(CW\*(C`soap_namespace_set\*(C'\fR with the \s-1URL\s0 of the namespace before returning. If you don't do that the namespace will default to \&\f(CW\*(C`http://example.com/ns\*(C'\fR. .SH "METHODS" .IX Header "METHODS" .IP "new" 4 .IX Item "new" For use by non-web scripts. Call this with a hash of attributes. Currently only the \f(CW\*(C`target_namespace\*(C'\fR key is used. It sets the namespace. Once you get your object, you can call \f(CW\*(C`soap_out\*(C'\fR on it as you would in a Gantry conroller. .IP "get_callbacks" 4 .IX Item "get_callbacks" Only for use by Gantry.pm. .Sp This is used to register \f(CW\*(C`steal_post_body\*(C'\fR as a pre init callback with Gantry. .IP "steal_post_body" 4 .IX Item "steal_post_body" Not for external use. .Sp Just a carefully timed call to \f(CW\*(C`consume_post_body\*(C'\fR exported by each engine. This is registered as a pre_init callback, so it gets the body before normal form parameter parsing would. .Sp You may retrieve with the post body with \f(CW\*(C`get_post_body\*(C'\fR (also exported by each engine). No processing of the request is done. You will receive whatever the \s-1SOAP\s0 client generated. That should be \s-1XML\s0, but even that depends on the client. .IP "soap_current_time" 4 .IX Item "soap_current_time" Returns the \s-1UTC\s0 in \s-1SOAP\s0 format. .IP "soap_serialize_xml" 4 .IX Item "soap_serialize_xml" This method is registered as a callback. Durning the post_init phase it will create a hash from the \f(CW$self\fR\->\fIget_post_body()\fR and store the result in \&\f(CW$self\fR\->\fIparams()\fR; .IP "soap_namespace" 4 .IX Item "soap_namespace" Called internally to retrieve the namespace for the \s-1XML\s0 tags in your \&\s-1SOAP\s0 response. Call \f(CW\*(C`soap_namespace_set\*(C'\fR if you need to set a particular namespace (some clients will care). Otherwise, the default namespace \f(CW\*(C`http://example.com/ns\*(C'\fR will be used. .IP "soap_namespace_set" 4 .IX Item "soap_namespace_set" Use this to set the namespace for your the tags in your \s-1XML\s0 response. The default namespace is \f(CW\*(C`http://example.com/ns\*(C'\fR. .IP "soap_out" 4 .IX Item "soap_out" Parameters: .RS 4 .IP "structure" 4 .IX Item "structure" actual data to send to the client. See \s-1SYNOPSIS\s0 and \s-1DESCRIPTION\s0. .IP "namespace_style" 4 .IX Item "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. .Sp To set the value of the namespace, call \f(CW\*(C`soap_namespace_set\*(C'\fR before calling this method. .IP "pretty" 4 .IX Item "pretty" true if you want pretty printing, false if not .Sp By default returned \s-1XML\s0 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: .Sp .Vb 5 \& my $check_first = $self->soap_out( \& $structure, 'prefix', 'pretty_please' \& ); \& warn $check_first; \& return $check_first; .Ve .RE .RS 4 .Sp Call this with the data to return to the client. If that client cares about the namespace of the tags in the response, call \f(CW\*(C`soap_namespace_set\*(C'\fR first. See the \s-1SYNOPSIS\s0 for an example of the structure you must pass to this method. See the \s-1DESCRIPTION\s0 for an explanation of what you can put in the structure. .Sp You should return the value returned from this method directly. It turns off all templating and sets the content type to text/xml. .RE .IP "build_args" 4 .IX Item "build_args" Mostly for internal use. .Sp \&\f(CW\*(C`soap_out\*(C'\fR uses this to turn your structure of return values into an \s-1XML\s0 snippet. If you need to re-implement \f(CW\*(C`soap_out\*(C'\fR, you could call this directly. The initial call should pass the same structure \f(CW\*(C`soap_out\*(C'\fR expects and (optionally) a pretty print flag. The returned value is the snippet of return params only. You would then need to build the \s-1SOAP\s0 envelope, etc. .IP "return_error" 4 .IX Item "return_error" This method returns a fault \s-1XML\s0 packet for you. Use it instead of die or croak. .IP "do_wsdl" 4 .IX Item "do_wsdl" This method uses the \f(CW\*(C`wsdldoc.tt\*(C'\fR in your template path to return a \s-1WSDL\s0 file to your client. The view.data passed to that template comes directly from a call to \f(CW\*(C`get_soap_ops\*(C'\fR, which you must implement (even it it returns nothing). .IP "send_xml" 4 .IX Item "send_xml" For clients. Sends the xml to the \s-1SOAP\s0 server. You must have called new with \f(CW\*(C`action_url\*(C'\fR and \f(CW\*(C`post_to_url\*(C'\fR 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. .Sp Parameters: an object of this class, the xml to send (get it from calling \&\f(CW\*(C`soap_out\*(C'\fR). .Sp Returns: response from remote server (actually whatever request on the \&\s-1LWP\s0 user agent retruns, try calling content on that object) .SH "AUTHOR" .IX Header "AUTHOR" Phil Crow, Tim Keefer, .SH "COPYRIGHT and LICENSE" .IX Header "COPYRIGHT and LICENSE" Copyright (c) 2007, Phil Crow .PP 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.