=head1 NAME

XML::Compile::SOAP::Server - server-side SOAP message processing

=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 for 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, because it is against
the official intent of the header field which is routing only).

=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  callbackhandler will be called with the un-decoded
XML::LibXML::Document node.

=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 callback must return an XML::LibXML::Document, or only
produce error messages.

=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,
because it is not so easy to detect which handler must be called.

=back

=back

=head1 SEE ALSO

This module is part of XML-Compile-SOAP distribution version 0.68,
built on March 14, 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>

