The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
MARKOV / XML-Compile-SOAP-2.37 / lib / XML / Compile / SOAP11 / Operation.pod 
=encoding utf8

=head1 NAME

XML::Compile::SOAP11::Operation - defines a SOAP11 interaction

=head1 INHERITANCE

 XML::Compile::SOAP11::Operation
   is a XML::Compile::SOAP::Operation

=head1 SYNOPSIS

 # object created by XML::Compile::WSDL*
 my $op = $wsdl->operation('GetStockPrices');
 $op->explain($wsdl, PERL => 'INPUT', recurse => 1);

=head1 DESCRIPTION

Objects of this type define one possible SOAP11 interaction, either
client side or server side.

See L<documentation in base class|XML::Compile::SOAP::Operation/"DESCRIPTION">.
 
=head1 METHODS

See L<documentation in base class|XML::Compile::SOAP::Operation/"METHODS">.
 
=head2 Constructors

See L<documentation in base class|XML::Compile::SOAP::Operation/"Constructors">.
 
=over 4

=item XML::Compile::SOAP11::Operation-E<gt>B<new>(OPTIONS)

C<input_def>, C<output_def> and C<fault_def> are HASHes which contain
the input and output message header, body and fault-header definitions
in WSDL1.1 style.

 -Option    --Defined in                   --Default
  action      XML::Compile::SOAP::Operation  undef
  endpoints   XML::Compile::SOAP::Operation  []
  fault_def                                  <undef>
  input_def                                  <undef>
  kin         XML::Compile::SOAP::Operation  <required>
  nam         XML::Compile::SOAP::Operation  <required>
  output_def                                 <undef>
  schemas     XML::Compile::SOAP::Operation  <required>
  style                                      'document'
  transport   XML::Compile::SOAP::Operation  'HTTP'

=over 2

=item action => STRING

=item endpoints => ADDRESS|ARRAY

=item fault_def => HASH

=item input_def => HASH

=item kin => d

=item nam => e

=item output_def => HASH

=item schemas => XML::Compile::Cache

=item style => 'document'|'rpc'

=item transport => URI|'HTTP'

=back

=back

=head2 Accessors

See L<documentation in base class|XML::Compile::SOAP::Operation/"Accessors">.
 
=over 4

=item $obj-E<gt>B<bindingName>()

See L<XML::Compile::SOAP::Operation/"Accessors">

=item $obj-E<gt>B<clientClass>()

See L<XML::Compile::SOAP::Operation/"Accessors">

=item $obj-E<gt>B<endPoints>()

See L<XML::Compile::SOAP::Operation/"Accessors">

=item $obj-E<gt>B<kind>()

See L<XML::Compile::SOAP::Operation/"Accessors">

=item $obj-E<gt>B<name>()

See L<XML::Compile::SOAP::Operation/"Accessors">

=item $obj-E<gt>B<portName>()

See L<XML::Compile::SOAP::Operation/"Accessors">

=item $obj-E<gt>B<schemas>()

See L<XML::Compile::SOAP::Operation/"Accessors">

=item $obj-E<gt>B<serverClass>()

See L<XML::Compile::SOAP::Operation/"Accessors">

=item $obj-E<gt>B<serviceName>()

See L<XML::Compile::SOAP::Operation/"Accessors">

=item $obj-E<gt>B<soapAction>()

See L<XML::Compile::SOAP::Operation/"Accessors">

=item $obj-E<gt>B<style>()

=item $obj-E<gt>B<version>()

See L<XML::Compile::SOAP::Operation/"Accessors">

=item $obj-E<gt>B<wsaAction>('INPUT'|'OUTPUT')

See L<XML::Compile::SOAP::Operation/"Accessors">

=back

=head2 Modify

Operations are often modified by SOAP extensions.
See L<XML::Compile::SOAP::WSA|XML::Compile::SOAP::WSA>, for instance. Also demonstrated in
the FAQ, XML::Compile::SOAP::FAQ.

=over 4

=item $obj-E<gt>B<addHeader>(('INPUT'|'OUTPUT'|'FAULT'), LABEL, ELEMENT, OPTIONS)

Add a header definitions.  Many protocols on top of SOAP, like WSS, add
headers to the operations which are not specified in the WSDL.

[2.31] When you add a header with same LABEL again, it will get silently
ignored unless the ELEMENT type differs.

 -Option        --Default
  destination     undef
  mustUnderstand  undef

=over 2

=item destination => ROLE

[2.33] adds the destination attribute,

=item mustUnderstand => BOOLEAN

[2.33] adds the mustUnderstand attribute.

=back

=back

=head2 Handlers

See L<documentation in base class|XML::Compile::SOAP::Operation/"Handlers">.
 
=over 4

=item $obj-E<gt>B<compileClient>(OPTIONS)

Returns one CODE reference which handles the processing for this
operation. Options C<transporter>, C<transport_hook>, and
C<endpoint> are passed to L<compileTransporter()|XML::Compile::SOAP::Operation/"Handlers">.

You pass that CODE reference an input message of the correct
type, as pure Perl HASH structure.  An 'request-response' operation
will return then answer, or C<undef> in case of failure.  An 'one-way'
operation with return C<undef> in case of failure, and a true value
when successfull.

You B<cannot> pass options for L<XML::Compile::Schema::compile()|XML::Compile::Schema/"Compilers">, like
C<<sloppy_integers => 0>>, hooks or typemaps this way. Provide these to
the C<::WSDL> or other C<::Cache> object which defines the types, via
C<new> option C<opts_rw> and friends.

=item $obj-E<gt>B<compileHandler>(OPTIONS)

Prepare the routines which will decode the request and encode the answer,
as will be run on the server. The L<XML::Compile::SOAP::Server|XML::Compile::SOAP::Server> will
connect these. All OPTIONS will get passed to
L<XML::Compile::SOAP11::Server::compileHandler()|XML::Compile::SOAP::Server/"Actions">

 -Option  --Default
  callback  <required>
  selector  <from input def>

=over 2

=item callback => CODE

=item selector => CODE

Determines whether the handler belongs to a received message.

=back

=item $obj-E<gt>B<compileTransporter>(OPTIONS)

See L<XML::Compile::SOAP::Operation/"Handlers">

=back

=head2 Helpers

See L<documentation in base class|XML::Compile::SOAP::Operation/"Helpers">.
 
=over 4

=item $obj-E<gt>B<explain>(WSDL, FORMAT, DIRECTION, OPTIONS)

[since 2.13]

Dump an annotated structure showing how the operation works, helping
developers to understand the schema. FORMAT is C<PERL>.
(C<XML> is not yet supported)

The DIRECTION is C<INPUT>, it will return the message which the client
sends to the server (input for the server). The C<OUTPUT> message is
sent as response by the server.

All OPTIONS besides those described here are passed to
L<XML::Compile::Schema::template()|XML::Compile::Schema/"Compilers">, when C<recurse> is enabled.

 -Option     --Default
  recurse      <false>
  skip_header  <false>

=over 2

=item recurse => BOOLEAN

Append the templates of all the part structures.

=item skip_header => BOOLEAN

=back

=item $obj-E<gt>B<parsedWSDL>()

[2.29] For some purposes, it is useful to get access to the parsed WSDL
structure.

B<Be aware> that the structure returned is consided "internal"
and strongly influenced by behavior of L<XML::Compile|XML::Compile>; backwards
compatibility will not be maintained at all cost.

You can use L<XML::Compile::Schema::template()|XML::Compile::Schema/"Compilers"> format C<TREE> to get
more details about the element types mentioned in this structure.

example: 

  use Data::Dumper;
  $Data::Dumper::Indent    = 1;
  $Data::Dumper::Quotekeys = 0;

  print Dumper $op->parsedWSDL;

=item XML::Compile::SOAP11::Operation-E<gt>B<register>(URI, ENVNS)

See L<XML::Compile::SOAP::Operation/"Helpers">

=back

=head1 SEE ALSO

This module is part of XML-Compile-SOAP distribution version 2.37,
built on July 09, 2013. Website: F<http://perl.overmeer.net/xml-compile/>

Other distributions in this suite:
L<XML::Compile>,
L<XML::Compile::SOAP>,
L<XML::Compile::SOAP12>,
L<XML::Compile::SOAP::Daemon>,
L<XML::Compile::SOAP::WSA>,
L<XML::Compile::C14N>,
L<XML::Compile::WSS>,
L<XML::Compile::WSS::Signature>,
L<XML::Compile::Tester>,
L<XML::Compile::Cache>,
L<XML::Compile::Dumper>,
L<XML::Compile::RPC>,
L<XML::Rewrite>
and
L<XML::LibXML::Simple>.

Please post questions or ideas to the mailinglist at
F<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile> .
For live contact with other developers, visit the C<#xml-compile> channel
on C<irc.perl.org>.

=head1 LICENSE

Copyrights 2007-2013 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>