=head1 NAME

XML::Compile::WSDL11::Operation - defines a possible SOAP interaction

=head1 INHERITANCE

=head1 SYNOPSIS

 # created by XML::Compile::WSDL11

=head1 DESCRIPTION

These objects are created by L<XML::Compile::WSDL11|XML::Compile::WSDL11>, grouping information
about a certain specific message interchange between a client and
a server. You can better (try to) create a WSDL file itself, then
attempt to instantiate these objects yourself... or even better: use
L<XML::Compile::SOAP11|XML::Compile::SOAP11> directly, and forget WSDL complexity.

There are three styles of SOAP: Document-style, RPC-literal and
RPC-encoded.  The first can be used directly, for the SOAP-RPC will
require you to specify more information about the expected message types.

=head1 METHODS

=head2 Constructors

$obj-E<gt>B<new>(OPTIONS)

=over 4

The OPTIONS are all collected from the WSDL description by
L<XML::Compile::WSDL11::operation()|XML::Compile::WSDL11/"Extension">.  End-users should not attempt to
initiate this object directly.

 Option  --Default
 action    <from wsdl>
 bind_op   undef
 binding   <required>
 name      <required>
 port      <required>
 portType  <required>
 port_op   <required>
 protocol  'HTTP'
 service   <required>
 style     <from wsdl operation style> | 'document'
 wsdl      <required>

. action => URI

. bind_op => HASH

. binding => HASH

. name => STRING

. port => HASH

. portType => HASH

. port_op => HASH

. protocol => URI|'HTTP'

=over 4

C<HTTP> is short for C<http://schemas.xmlsoap.org/soap/http/>, which
is a constant to indicate that transport should use the HyperText
Transfer Protocol.

=back

. service => HASH

. style => 'document'|'rpc'

. wsdl => XML::Compile::WSDL11 object

=back

=head2 Accessors

$obj-E<gt>B<bindOperation>

=over 4

=back

$obj-E<gt>B<bindings>

=over 4

=back

$obj-E<gt>B<name>

=over 4

=back

$obj-E<gt>B<port>

=over 4

=back

$obj-E<gt>B<portOperation>

=over 4

=back

$obj-E<gt>B<portType>

=over 4

=back

$obj-E<gt>B<schemas>

=over 4

=back

$obj-E<gt>B<service>

=over 4

=back

$obj-E<gt>B<wsdl>

=over 4

=back

=head2 Use

$obj-E<gt>B<endPointAddresses>

=over 4

Returns the list of alternative URLs for the end-point, which should
be defined within the service's port declaration.

=back

$obj-E<gt>B<kind>

=over 4

This returns the type of operation this is.  There are four kinds, which
are returned as strings C<one-way>, C<request-response>, C<sollicit-response>,
and C<notification>.  The latter two are initiated by a server, the former
two by a client.

=back

$obj-E<gt>B<soapAction>

=over 4

=back

$obj-E<gt>B<soapNameSpace>

=over 4

=back

$obj-E<gt>B<soapVersion>

=over 4

=back

=head2 Handlers

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

=over 4

Returns one CODE reference which handles the processing for this
operation.

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.

Besides the OPTIONS listed, you can also specify anything which is
accepted by L<XML::Compile::Schema::compile()|XML::Compile::Schema/"Compilers">, like
C<< sloppy_integers => 1 >> or hooks.

 Option          --Default
 endpoint_address  <from WSDL>
 protocol          new(protocol)|<from soapAction>
 rpcin             undef
 rpcout            undef
 style             new(style)|'document'
 transport         <created>
 transport_hook    undef
 use               'literal'

. endpoint_address => URI

=over 4

Overrule the destination address.

=back

. protocol => URI|'HTTP'

=over 4

Only the HTTP protocol is supported on the moment.  The URI is
the WSDL URI representation of the HTTP protocol.

=back

. rpcin => TYPE|CODE

=over 4

Decode some received (incoming) SOAP-RPC structure into Perl data structures.
See L<XML::Compile::SOAP::Client::compileClient(rpcin)|XML::Compile::SOAP::Client/"Handlers">.

=back

. rpcout => TYPE|CODE

=over 4

Pack user values into an outgoing SOAP-RPC structure.
See L<XML::Compile::SOAP::Client::compileClient(rpcout)|XML::Compile::SOAP::Client/"Handlers">.

=back

. style => 'document'|'rpc'

. transport => CODE

=over 4

The routine which will be used to exchange the
data with the server.  This code is usually created by
L<XML::Compile::Transport::SOAPHTTP::compileClient()|XML::Compile::Transport::SOAPHTTP/"Handlers"> By default, a
transporter compatible to the protocol is created.  However, in most
cases you want to reuse one (HTTP1.1) connection to a server.

=back

. transport_hook => CODE

=over 4

Passed to L<XML::Compile::Transport::compileClient(hook)|XML::Compile::Transport/"Handlers">.  Can be
used to create off-line tests and last resort work-arounds.  See the
DETAILs chapter in the L<XML::Compile::Transport|XML::Compile::Transport> manual page.

=back

. use => 'literal'|'encoded'

=back

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

=over 4

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.

 Option  --Default
 callback  <required>
 soap      <required>

. callback => CODE

. soap => XML::Compile::SOAP object

=back

=head2 Helpers

$obj-E<gt>B<canTransport>(PROTOCOL, STYLE)

=over 4

Returns a trueth value when the pair with URI of the PROTOCOL and
processing STYLE (either C<document> or C<rpc>) is provided as soap
binding.

=back

$obj-E<gt>B<collectFaultParts>(ARGS, PORT-OP, BIND-OP)

=over 4

=back

$obj-E<gt>B<collectMessageParts>(ARGS, PORT-OP, BIND-OP)

=over 4

Collect the components of the message which are actually being used.

=back

$obj-E<gt>B<compileMessages>(ARGS, 'CLIENT'|'SERVER', SOAP)

=over 4

The ARGS is a HASH which contains options for L<collectMessageParts()|XML::Compile::WSDL11::Operation/"Helpers">
and for L<XML::Compile::Schema::compile()|XML::Compile::Schema/"Compilers">.

=back

$obj-E<gt>B<messageSelectParts>(MESSAGE, [NAMES])

=over 4

Collect the named message parts.  If no names are specified, then
all are all returned.

=back

=head1 SEE ALSO

This module is part of XML-Compile-SOAP distribution version 0.77,
built on August 15, 2008. Website: F<http://perl.overmeer.net/xml-compile/>

All modules in this suite:
L<XML::Compile>,
L<XML::Compile::SOAP>,
L<XML::Compile::SOAP::Daemon>,
L<XML::Compile::Tester>,
L<XML::Compile::Cache>,
L<XML::Rewrite>,
L<XML::Compile::Dumper>.

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

=head1 LICENSE

Copyrights 2007-2008 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>