NAME

XML::Compile::SOAP::Daemon - base class for SOAP message servers

INHERITANCE

 XML::Compile::SOAP::Daemon is extended by
   XML::Compile::SOAP::HTTPDaemon

SYNOPSIS

 #### have a look in the examples directory!

 # Be warned that the daemon will be Net::Server based, which consumes
 # command-line arguments!
 my $deamon  = XML::Compile::SOAP::HTTPDaemon->new;

 # daemon definitions from WSDL
 my $wsdl    = XML::Compile::WSDL11->new(...);
 $wsdl->importDefinitions(...); # more schemas
 $deamon->operationsFromWSDL($wsdl, handlers => ...);

 # daemon definitions added manually
 my $soap11  = XML::Compile::SOAP11::Server->new(schemas => $wsdl->schemas);
 my $handler = $soap11->compileHandler(...);
 $deamon->addHandler('getInfo', $soap11, $handler);

 # see what is defined:
 $daemon->printIndex;

 # finally, run the server.  This never returns.
 $daemon->run(...daemon options...);

DESCRIPTION

This base class implements the common needs between various types of SOAP daemons. As daemon type, you can use any kind of Net::Server implementation.

The following extensions are implemented on the moment: (other are not yet planned to get implemented)

.

XML::Compile::SOAP::HTTPDaemon, for transport over HTTP.

The deamon can handle various kinds of SOAP protocols at the same time, when possible hidden from the user of this module.

If you have a WSDL describing your procedures, then the only thing you have to worry about is adding callbacks for each of the defined ports. Without WSDL, you will need to do more manually, but it is still relatively simple to achieve.

Do not forget to take a look at the extensive example, enclosed in the XML::Compile::SOAP::Daemon distribution package. It is really worth the time.

METHODS

Constructors

XML::Compile::SOAP::Daemon->new(OPTIONS)

Create the server handler, which extends some class which implements a Net::Server.

Any daemon configuration parameter should be passed with run(). This is a little tricky. Read below in the "Configuration options" section.

 Option        --Default
 based_on        <internal Net::Server::PreFork>
 output_charset  'UTF-8'
 support_soap    'ANY'

. based_on => 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 run(). You may also specify any Net::Server compatible CLASS name.

. output_charset => STRING

The character-set to be used for the output XML document.

. support_soap => 'SOAP11'|'SOAP12'|'ANY'|SOAP

Which versions of SOAP to support. Quite an amount of preparations must be made to start a server, which can be reduced by enforcing a single SOAP type, specified as version string or XML::Compile::SOAP object.

Attributes

$obj->isSupportedVersion(('SOAP11'|'SOAP12'))

Returns true if the soap version is supported, according to new(support_soap)).

$obj->outputCharset

The character-set to be used for output documents.

Running the server

$obj->process(CLIENT, XMLIN)

The parsed XMLIN SOAP-structured message (an XML::LibXML::Element or XML::LibXML::Document), was received from the CLIENT (some extension specific object). Returned is an XML document as answer.

$obj->run(OPTIONS)

See Net::Server subroutine run, but the OPTIONS are passed as list, not as HASH.

Preparations

$obj->addHandler(NAME, SOAP, CODE)

The SOAP value is SOAP11, SOAP12, or a SOAP server object. The CODE reference is called with the incoming document (an XML::LibXML::Document) of the received input message.

In case the handler does not understand the message, it should return undef. Otherwise, it must return a correct answer message as XML::LibXML::Document.

$obj->operationsFromWSDL(WSDL, OPTIONS)

Compile the operations found in the WSDL object (an XML::Compile::WSDL11). You can add the operations from many different WSDLs into one server, simply by calling this method repeatedly.

 Option          --Default
 callbacks         {}
 default_callback  <produces fault reply>

. callbacks => HASH

The keys are the port names, as defined in the WSDL. The values are CODE references which are called in case a message is received which seems to be addressing the port (this is a guess). See "Operation handlers"

. default_callback => CODE

When a message arrives which has no explicit handler attached to it, this handler will be called. By default, an "not implemented" fault will be returned. See "Operation handlers"

Helpers

$obj->acceptResponse(REQUEST, XML)

Returns an implementation dependent wrapper around a produced response.

$obj->faultMessageNotRecognized(SOAPVERSION, BODYELEMENT, DEFINED)

The SOAP VERSION, the type of the first BODY ELEMENT, and the ARRAY of DEFINED message names.

$obj->faultNotImplemented(NAME, XML, INFO)

Called as any handler, with the procedure NAME (probably the portType from the WSDL), the incoming XML message, and structural message INFO.

$obj->faultNotSoapMessage(NODETYPE)

$obj->faultTryOtherProtocol(SOAPVERSION, BODYELEMENT, OTHER)

The SOAP VERSION, the type of the first BODY ELEMENT, and an ARRAY of OTHER protocols are passed.

$obj->faultUnsupportedSoapVersion(ENV_NS)

$obj->handlers(('SOAP11'|'SOAP12'|SOAP))

Returns all the handler names for a certain soap version.

example:

 foreach my $version (sort $server->soapVersions)
 {   foreach my $action (sort $server->handlers($version))
     {  print "$version $action\n";
     }
 }

$obj->inputToXML(CLIENT, ACTION, XML-STRING-REF)

Translate a textual XML message into an XML::LibXML tree.

$obj->printIndex([FILEHANDLE])

Print a table which shows the messages that the server can handle, by default to STDOUT.

$obj->soapFault(SOAPVERSION, DATA, [RC, ABSTRACT])

Create the fault document. The error code (RC) is not always available, as is an ABSTRACT description of the problem.

$obj->soapVersions

DETAILS

Configuration options

This module will wrap any kind of Net::Server, for instance a Net::Server::PreFork. It depends on the type of Net::Server you specify (see new(based_on)) which conifguration options are available on the command-line, in a configuration file, or with run(). Each daemon extension implementation will add some configuration options as well.

Any XML::Compile::SOAP::Daemon object will have the following additional configuration options:

  Key          Value                            Default
  # there will be some, I am sure of it.

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

logging

An attempt is made to merge XML::Compile's Log::Report and Net::Server log configuration. By hijacking the 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 Sys::Syslog or a filename, default dispatchers of type SYSLOG resp FILE are created for you. When the log_file type is set to 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)

Operation handlers

SEE ALSO

This module is part of XML-Compile-SOAP-Daemon distribution version 0.11, built on June 06, 2008. Website: http://perl.overmeer.net/xml-compile/

All modules in this suite: "XML::Compile", "XML::Compile::SOAP", "XML::Compile::SOAP::Daemon", "XML::Compile::Tester", "XML::Compile::Cache", "XML::Compile::Dumper".

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

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 http://www.perl.com/perl/misc/Artistic.html

cpanm XML::Compile::SOAP::Daemon

perl -MCPAN -e shell
install XML::Compile::SOAP::Daemon