.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SOAP::WSDL::Server 3pm"
.TH SOAP::WSDL::Server 3pm "2022-10-14" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
SOAP::WSDL::Server \- WSDL based SOAP server base class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Don't use directly, use the SOAP::WSDL::Server::* subclasses
instead.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
SOAP::WSDL::Server basically follows the architecture sketched below
(though dispatcher classes are not implemented yet)
.PP
.Vb 10
\& SOAP Request           SOAP Response
\&       |                     ^
\&       V                     |
\&  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& |       SOAP::WSDL::Server                 |
\& |  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-  |
\& | | Transport Class                      | |
\& | |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-| |
\& | | Deserializer       | Serializer      | |
\& | |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-| |
\& | | Dispatcher                           | |
\& |  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-  |
\&  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&      | calls                 ^
\&      v                       | returns
\&   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&  |   Handler                           |
\&   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
.Ve
.PP
All of the components (Transport class, deserializer, dispatcher and
serializer) are implemented as plugins.
.PP
The architecture is not implemented as planned yet, but the dispatcher is
currently part of SOAP::WSDL::Server, which aggregates serializer and
deserializer, and is subclassed by transport classes (of which
SOAP::WSDL::Server::CGI is the only implemented one yet).
.PP
The dispatcher is currently based on the SOAPAction header. This does not
comply to the WS-I basic profile, which declares the SOAPAction as optional.
.PP
The final dispatcher will be based on wire signatures (i.e. the classes
of the deserialized messages).
.PP
A hash-based dispatcher could be implemented by examining the top level
hash keys.
.SH "EXCEPTION HANDLING"
.IX Header "EXCEPTION HANDLING"
.SS "Builtin exceptions"
.IX Subsection "Builtin exceptions"
SOAP::WSDL::Server handles the following errors itself:
.PP
In case of errors, a \s-1SOAP\s0 Fault containing an appropriate error message
is returned.
.IP "\(bu" 4
\&\s-1XML\s0 parsing errors
.IP "\(bu" 4
Configuration errors
.SS "Throwing exceptions"
.IX Subsection "Throwing exceptions"
The proper way to throw a exception is just to die \-
SOAP::WSDL::Server::CGI catches the exception and sends a \s-1SOAP\s0 Fault
back to the client.
.PP
If you want more control over the \s-1SOAP\s0 Fault sent to the client, you can
die with a SOAP::WSDL::SOAP::Fault11 object \- or just let the
SOAP::Server's deserializer create one for you:
.PP
.Vb 1
\& my $soap = MyServer::SomeService\->new();
\&
\& die $soap\->get_deserializer()\->generate_fault({
\&    code => \*(AqSOAP\-ENV:Server\*(Aq,
\&    role => \*(Aqurn:localhost\*(Aq,
\&    message => "The error message to pas back",
\&    detail => "Some details on the error",
\& });
.Ve
.PP
You may use any other object as exception, provided it has a
\&\fBserialize()\fR method which returns the object's \s-1XML\s0 representation.
.SS "Subclassing"
.IX Subsection "Subclassing"
To write a transport-specific \s-1SOAP\s0 Server, you should subclass
SOAP::WSDL::Server.
.PP
See the \f(CW\*(C`SOAP::WSDL::Server::*\*(C'\fR modules for examples.
.PP
A \s-1SOAP\s0 Server must call the following method to actually handle the request:
.PP
\fIhandle\fR
.IX Subsection "handle"
.PP
Handles the \s-1SOAP\s0 request.
.PP
Returns the response message as \s-1XML.\s0
.PP
Expects a \f(CW\*(C`HTTP::Request\*(C'\fR object as only parameter.
.PP
You may use any other object as parameter, as long as it implements the
following methods:
.IP "\(bu" 4
header
.Sp
Called as header('SOAPAction'). Must return the corresponding \s-1HTTP\s0 header.
.IP "\(bu" 4
content
.Sp
Returns the request message
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2004\-2008 Martin Kutter.
.PP
This file is part of SOAP-WSDL. You may distribute/modify it under the same
terms as perl itself
.SH "AUTHOR"
.IX Header "AUTHOR"
Martin Kutter <martin.kutter fen\-net.de>
.SH "REPOSITORY INFORMATION"
.IX Header "REPOSITORY INFORMATION"
.Vb 4
\& $Rev: 391 $
\& $LastChangedBy: kutterma $
\& $Id: Client.pm 391 2007\-11\-17 21:56:13Z kutterma $
\& $HeadURL: https://soap\-wsdl.svn.sourceforge.net/svnroot/soap\-wsdl/SOAP\-WSDL/trunk/lib/SOAP/WSDL/Client.pm $
.Ve