=head1 NAME

XML::Compile::SOAP::Operation - base-class for possible interactions

=head1 INHERITANCE

 XML::Compile::SOAP::Operation is extended by
   XML::Compile::SOAP11::Operation
   XML::Compile::SOAP12::Operation

=head1 SYNOPSIS

 # created by XML::Compile::WSDL11
 my $op = $wsdl->operation('GetStockPrices');

=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.

=head1 METHODS

=head2 Constructors

=over 4

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

 -Option   --Default
  action     undef
  endpoints  []
  kin        <required>
  nam        <required>
  schemas    <required>
  transport  'HTTP'

=over 2

=item action => STRING

Some string which is refering to the action which is taken.  For SOAP
protocols, this defines the soapAction header.

=item endpoints => ADDRESS|ARRAY

Where to contact the server.

=item kin => d

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.

=item nam => e

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

=item transport => URI|'HTTP'

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

=back

=head2 Accessors

=over 4

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

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

Returns the class name which implements the Client side for this protocol.

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

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

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

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

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

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

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

Returns the class name which implements the Server side for this protocol.

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

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

Used for the C<soapAction> header in HTTP transport, for routing
messages through firewalls.

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

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

Only available when C<XML::Compile::SOAP::WSA> is loaded. It specifies
the name of the operation in the WSA header.  With C<INPUT>, it is the
Action to be used with a message sent to the server (input to the
server). The C<OUTPUT> is used by the server in its message back.

=back

=head2 Handlers

=over 4

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

Returns one CODE reference which handles the conversion from a perl
data-structure into a request message, the transmission of the
request, the receipt of the answer, and the decoding of that answer
into a Perl data-structure.

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

Returns a code reference which translates in incoming XML message
into Perl a data-structure, then calls the callback.  The result of
the callback is encoded from Perl into XML and returned.

 -Option  --Default
  callback  <required>

=over 2

=item callback => CODE

=back

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

Create the transporter code for a certain specific target.

 -Option        --Default
  endpoint        <from WSDL>
  server          undef
  transport_hook  undef
  transporter     <created>

=over 2

=item endpoint => URI|ARRAY-of-URI

Overrule the destination address(es).

=item server => URI-HOST

Overrule only the server part in the endpoint, not the whole endpoint.
This could be a string like C<username:password@myhost:4711>.  Only
used when no explicit C<endpoint> is provided.

=item transport_hook => CODE

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.

=item transporter => CODE

The routine which will be used to exchange the data with the server.
This code is created by an L<XML::Compile::Transport::compileClient()|XML::Compile::Transport/"Handlers">
extension. 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

=back

=head2 Helpers

=over 4

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

Dump an annotated structure showing how the operation works, helping
developers to understand the schema. FORMAT is C<PERL> or C<XML>.

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.

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

Declare an operation type, but WSDL specific URI and envelope namespace.

=back

=head1 SEE ALSO

This module is part of XML-Compile-SOAP distribution version 2.32,
built on October 22, 2012. 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::Tester>,
L<XML::Compile::Cache>,
L<XML::Compile::Dumper>,
L<XML::Compile::RPC>,
L<XML::Rewrite>,
L<XML::eXistDB>,
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-2012 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>