=encoding utf8
=head1 NAME
XML::Compile::SOAP::Daemon::NetServer - SOAP server based on Net::Server
=head1 INHERITANCE
XML::Compile::SOAP::Daemon::NetServer
is a XML::Compile::SOAP::Daemon
=head1 SYNOPSIS
#### have a look in the examples directory!
use XML::Compile::SOAP::Daemon::NetServer;
use XML::Compile::SOAP11;
use XML::Compile::SOAP::WSA; # optional
# Be warned that the daemon will be Net::Server based, which
# consumes command-line arguments! "local @ARGV;" maybe useful
my $daemon = XML::Compile::SOAP::Daemon::NetServer->new;
# daemon definitions from WSDL
my $wsdl = XML::Compile::WSDL11->new(...);
$wsdl->importDefinitions(...); # more schemas
$daemon->operationsFromWSDL($wsdl, callbacks => ...);
# daemon definitions added manually (when no WSDL)
my $soap11 = XML::Compile::SOAP11::Server->new(schemas => $wsdl->schemas);
my $handler = $soap11->compileHandler(...);
$daemon->addHandler('getInfo', $soap11, $handler);
# see what is defined:
$daemon->printIndex;
# finally, run the server. This never returns.
$daemon->run(@daemon_options);
=head1 DESCRIPTION
This module handles the exchange of SOAP messages over HTTP with
Net::Server as daemon implementation, It uses HTTP::Request and
HTTP::Response object provided by LWP, via functions provided by
L<XML::Compile::SOAP::Daemon::LWPutil|XML::Compile::SOAP::Daemon::LWPutil>.
This abstraction level of the object (code in this pm file) is not
concerned with parsing or composing XML, but only worries about the
HTTP transport specifics of SOAP messages. The processing of the SOAP
message is handled by the L<XML::Compile::SOAP::Daemon|XML::Compile::SOAP::Daemon> base-class.
The server is as flexible as possible: accept M-POST (HTTP Extension
Framework) and POST (standard HTTP) for any message. It can be used
for any SOAP1.1 and SOAP1.2 mixture. Although SOAP1.2 itself is
not implemented yet.
See L<documentation in base class|XML::Compile::SOAP::Daemon/"DESCRIPTION">.
=head1 METHODS
See L<documentation in base class|XML::Compile::SOAP::Daemon/"METHODS">.
=head2 Constructors
See L<documentation in base class|XML::Compile::SOAP::Daemon/"Constructors">.
=over 4
=item XML::Compile::SOAP::Daemon::NetServer-E<gt>B<new>(OPTIONS)
Create the server handler, which extends some class which implements
a Net::Server daemon. Any daemon configuration parameter should
be passed with L<run()|XML::Compile::SOAP::Daemon::NetServer/"Running the server">. This is a little tricky. Read below in the
L</Configuration options> section.
-Option --Defined in --Default
accept_slow_select XML::Compile::SOAP::Daemon <true>
based_on Net::Server::PreFork
output_charset XML::Compile::SOAP::Daemon 'UTF-8'
soap_action_input XML::Compile::SOAP::Daemon {}
wsa_action_input XML::Compile::SOAP::Daemon {}
wsa_action_output XML::Compile::SOAP::Daemon {}
=over 2
=item accept_slow_select => BOOLEAN
=item based_on => any Net::Server OBJECT|CLASS
You may pass your own Net::Server compatible daemon, if you feel a need
to initialize it or prefer an other one. Preferrably, pass configuration
settings to L<run()|XML::Compile::SOAP::Daemon::NetServer/"Running the server">. You may also specify any Net::Server compatible
CLASS name.
=item output_charset => STRING
=item soap_action_input => HASH|ARRAY
=item wsa_action_input => HASH|ARRAY
=item wsa_action_output => HASH|ARRAY
=back
=back
=head2 Attributes
See L<documentation in base class|XML::Compile::SOAP::Daemon/"Attributes">.
=over 4
=item $obj-E<gt>B<addSoapAction>(HASH|PAIRS)
See L<XML::Compile::SOAP::Daemon/"Attributes">
=item $obj-E<gt>B<addWsaTable>(('INPUT'|'OUTPUT'), [HASH|PAIRS])
See L<XML::Compile::SOAP::Daemon/"Attributes">
=item $obj-E<gt>B<outputCharset>()
See L<XML::Compile::SOAP::Daemon/"Attributes">
=back
=head2 Running the server
See L<documentation in base class|XML::Compile::SOAP::Daemon/"Running the server">.
=over 4
=item $obj-E<gt>B<process>(CLIENT, XMLIN, REQUEST, ACTION)
See L<XML::Compile::SOAP::Daemon/"Running the server">
=item $obj-E<gt>B<run>(OPTIONS)
See Net::Server subroutine run, but the OPTIONS are passed as list, not
as HASH. You may pass any option to which accepted by the Net::Server
extension you are using.
-Option --Default
postprocess undef
=over 2
=item postprocess => CODE
See the section about this option in the DETAILS chapter of the
L<XML::Compile::SOAP::Daemon::LWPutil|XML::Compile::SOAP::Daemon::LWPutil> manual-page.
=back
=back
=head2 Preparations
See L<documentation in base class|XML::Compile::SOAP::Daemon/"Preparations">.
=over 4
=item $obj-E<gt>B<addHandler>(NAME, SOAP, CODE)
See L<XML::Compile::SOAP::Daemon/"Preparations">
=item $obj-E<gt>B<operationsFromWSDL>(WSDL, OPTIONS)
See L<XML::Compile::SOAP::Daemon/"Preparations">
=item $obj-E<gt>B<setWsdlResponse>(FILENAME)
See L<XML::Compile::SOAP::Daemon/"Preparations">
=back
=head2 Helpers
See L<documentation in base class|XML::Compile::SOAP::Daemon/"Helpers">.
=over 4
=item $obj-E<gt>B<faultInvalidXML>(ERROR)
See L<XML::Compile::SOAP::Daemon/"Helpers">
=item $obj-E<gt>B<faultNotSoapMessage>(NODETYPE)
See L<XML::Compile::SOAP::Daemon/"Helpers">
=item $obj-E<gt>B<faultUnsupportedSoapVersion>(ENV_NS)
See L<XML::Compile::SOAP::Daemon/"Helpers">
=item $obj-E<gt>B<handlers>(('SOAP11'|'SOAP12'|SOAP))
See L<XML::Compile::SOAP::Daemon/"Helpers">
=item $obj-E<gt>B<printIndex>([FILEHANDLE])
See L<XML::Compile::SOAP::Daemon/"Helpers">
=item $obj-E<gt>B<soapVersions>()
See L<XML::Compile::SOAP::Daemon/"Helpers">
=back
=head1 DETAILS
See L<documentation in base class|XML::Compile::SOAP::Daemon/"DETAILS">.
=head2 Operation handlers
See L<documentation in base class|XML::Compile::SOAP::Daemon/"Operation handlers">.
=head2 Returning errors
See L<documentation in base class|XML::Compile::SOAP::Daemon/"Returning errors">.
=head2 Configuration options
This module will wrap any kind of Net::Server, for instance a
Net::Server::PreFork. It depends on the type of C<Net::Server>
you specify (see L<new(based_on)|XML::Compile::SOAP::Daemon::NetServer/"METHODS">) which configuration options are
available on the command-line, in a configuration file, or with L<run()|XML::Compile::SOAP::Daemon::NetServer/"Running the server">.
Each daemon extension implementation will add some configuration options
as well.
Any C<XML::Compile::SOAP::Daemon::NetServer> object will have the following
additional configuration options:
Key Value Default
client_timeout integer seconds 30
client_maxreq integer 100
client_reqbonus integer seconds 0
name string "soap daemon"
Some general configuration options of Net::Server have a
different default. See also the next section about logging.
Key Value New default
setsid boolean true
background boolean true
For each client, we like to have a reset of the connection after some
time, for two reasons: perl processes are usually leaking memory a bit
so should not live for ever, and you can experience denial of service
attacks. The C<client_timeout> value details the number of seconds
a connection may live, but that will be increase by C<client_reqbonus>
for every received message. In any case, after C<client_maxreq> messages
were handled, the connection will be terminated.
The C<name> is included in the reply messages.
=head3 logging
An attempt is made to merge XML::Compile's Log::Report and Net::Server
log configuration. By hijacking the C<log()> method, all Net::Server
internal errors are dispatched over the Log::Report framework. Log levels
are translated into report reasons: 0=ERROR, 1=WARNING, 2=NOTICE, 3=INFO,
4=TRACE.
When you specify C<Sys::Syslog> or a filename, default dispatchers of type
SYSLOG resp FILE are created for you. When the C<log_file> type is set to
C<Log::Report>, you have much more control over the process, but all log
related configuration options will get ignored. In that case, you must
have initialized the dispatcher framework the way Log::Report is doing
it: before the daemon is initiated. See Log::Report subroutine dispatcher.
Key Value Default
log_file filename|Sys::Syslog|Log::Report Log::Report
log_level 0..4 | REASON 2 (NOTICE)
=head1 SEE ALSO
This module is part of XML-Compile-SOAP-Daemon distribution version 3.06,
built on May 03, 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>,
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-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>