=head1 NAME

XML::Compile::SOAP::Server - SOAP message handlers

=head1 INHERITANCE

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

=head1 SYNOPSIS

  # THIS CANNOT BE USED YET: Preparations for new module
  # named XML::Compile::SOAP::Daemon

  my $soap   = XML::Compile::SOAP11::Server->new;
  my $input  = $soap->compileMessage('RECEIVER', ...);
  my $output = $soap->compileMessage('SENDER', ...);

  $soap->compileHandler
    ( name => $name, input => $input, output => $output
    , callback => \$my_handler
    );

  my $daemon = XML::Compile::SOAP::HTTPDaemon->new(...);
  $daemon->addHandler($type => $daemon);

=head1 DESCRIPTION

This class defines methods that each server side of the SOAP
message exchange protocols must implement.

=head1 METHODS

=head2 Instantiation

This object can not be instantiated, but is only used as secundary
base class.  The primary must contain the C<new>.

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

=over 4

 Option  --Default
 action    <undef>
 callback  <fault: not implemented>
 decode    <undef>
 encode    <undef>
 name      <required>

. action => STRING

=over 4

A possible SOAPAction string from the HTTP header.  It might be used
to identify an incoming message (but probably not).

=back

. callback => CODE

=over 4

As input, the SERVER object and the translated input message (Perl version)
are passed in.  As output, a suitable output structure must be produced.
If the callback is not set, then a fault message will be returned to the
user.

=back

. decode => CODE

=over 4

The CODE reference is used to decode the (parsed) XML input message
into the pure Perl request.  The reference is a READER, created with
L<XML::Compile::Schema::compile()|XML::Compile::Schema/"Compilers">.  If no input decoder is specified,
then the handler will be called with the un-decoded XML::LibXML node
itself.

=back

. encode => CODE

=over 4

The CODE reference is used to encode the Perl answer structure
into the output message.  The reference is a WRITER.  created with
L<XML::Compile::Schema::compile()|XML::Compile::Schema/"Compilers">.  If no output encoder is specified,
then the handler must return an XML::LibXML document.

=back

. name => STRING

=over 4

The identification for this action, for instance used for logging.  When
the action is created via a WSDL, the portname will be used here.  It is
a pitty that the portname is not passed in the SOAP message.

=back

=back

=head1 SEE ALSO

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

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

