SOAP::...Server(3pm)

📦
version 3.004 · 7 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

✨ NAME ✨

SOAP::WSDL::Server — it's the WSDL based SOAP server base class, aka the blueprint your server classes are gonna be built on top of (this is the SOAP::...Server(3pm) page from the User Contributed Perl Documentation, if you're keeping track 💅).

🌸 SYNOPSIS 🌸

okay so real talk:

Don't use directly, use the SOAP::WSDL::Server::* subclasses instead.

Like, don't romance the base class. She's the foundation, not the whole house 🏠✨

🦋 DESCRIPTION 🦋

SOAP::WSDL::Server basically follows the architecture sketched below (though lowkey the dispatcher classes are not implemented yet 🙈):

 SOAP Request           SOAP Response
       |                     ^
       V                     |
  ------------------------------------------
 |       SOAP::WSDL::Server                 |
 |  --------------------------------------  |
 | | Transport Class                      | |
 | |--------------------------------------| |
 | | Deserializer       | Serializer      | |
 | |--------------------------------------| |
 | | Dispatcher                           | |
 |  --------------------------------------  |
  ------------------------------------------
      | calls                 ^
      v                       | returns
   -------------------------------------
  |   Handler                           |
   -------------------------------------

All of the components — the Transport class, the deserializer, the dispatcher and the serializer — are implemented as plugins. periodt.

Now, the architecture is not implemented as planned yet 😭 but here's the tea on how it actually shakes out rn: the dispatcher is currently part of SOAP::WSDL::Server, which aggregates the serializer and deserializer, and is subclassed by the transport classes (of which SOAP::WSDL::Server::CGI is the only implemented one yet 👑).

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 ⚠️. So yeah, not it, but it's what we've got.

The final dispatcher will be based on wire signatures (i.e. the classes of the deserialized messages) — main character energy incoming ✨

And a hash-based dispatcher could be implemented by examining the top level hash keys. brain big 🧠💅

💖 EXCEPTION HANDLING 💖

😭 Builtin exceptions

SOAP::WSDL::Server handles the following errors itself:

In case of errors, a SOAP Fault containing an appropriate error message is returned. no cap.

  • XML parsing errors
  • Configuration errors

🪄 Throwing exceptions

The proper way to throw a exception is just to die — SOAP::WSDL::Server::CGI catches the exception and sends a SOAP Fault back to the client. simple as that 🎀

If you want more control over the SOAP 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:

my $soap = MyServer::SomeService->new();

die $soap->get_deserializer()->generate_fault({
   code => 'SOAP-ENV:Server',
   role => 'urn:localhost',
   message => "The error message to pas back",
   detail => "Some details on the error",
});
(yes, pas back — we keep it exactly how it is, bestie, no editing the lore 🫶)

You may use any other object as exception, provided it has a serialize() method which returns the object's XML representation. iconique.

🐣 Subclassing

To write a transport-specific SOAP Server, you should subclass SOAP::WSDL::Server. it's giving "inherit and glow up" ✨

See the SOAP::WSDL::Server::* modules for examples.

A SOAP Server must call the following method to actually handle the request:

handle

Handles the SOAP request.

Returns the response message as XML.

Expects a HTTP::Request object as only parameter.

You may use any other object as parameter, as long as it implements the following methods:

  • header

Called as header('SOAPAction'). Must return the corresponding HTTP header.

  • content

Returns the request message

Copyright 2004-2008 Martin Kutter.

This file is part of SOAP-WSDL. You may distribute/modify it under the same terms as perl itself

👑 AUTHOR 👑

Martin Kutter <martin.kutter fen-net.de>

🗂️ REPOSITORY INFORMATION 🗂️

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

and thaaat's the page, bestie 💅 this one shipped as part of perl v5.36.0, dated 2022-10-14, under the User Contributed Perl Documentation — stay slaying, and remember: subclass, don't call directly 🫶✨🎀

📦 where this page comes from