XML::C...Server(3pm)

💖 NAME 💖

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

bestie, this is the manual page for XML::C...Server(3pm), and yes we are about to make SOAP servers make sense. buckle up. ✨

---

🌸 INHERITANCE 🌸

• XML::Compile::SOAP::Server is extended by
  • XML::Compile::SOAP11::Server
  • XML::Compile::SOAP12::Server

it's giving base-class energy, and the two SOAP-flavoured children are the main characters. 💅

---

✨ SYNOPSIS ✨

# used by distribution 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);

look at that little pipeline. you compile the message in, you compile the message out, you wire up a handler with name, input, output and callback, and then your daemon picks it up with addHandler. no cap, that's the whole vibe. 🔥

---

🎀 DESCRIPTION 🎀

this class defines the methods that every server for the SOAP message exchange protocols has to implement. like, it's the group chat rules everyone agrees to before they're allowed to talk. 💬

---

👑 METHODS 👑

🧚 Instantiation

okay so plot twist: you can not actually instantiate this object. it only exists as a secondary base class. the primary class is the one that has to bring the new. 🙈

XML::Compile::SOAP::Server->new(%options)

-Option--Default
 role    'NEXT'

• role => URI — in SOAP1.1 the term for this is 'actor', but SOAP1.2 renamed it to 'role': it's the role [this daemon] plays in the transport protocol. please use the role abbreviations as provided by the protocol implementations when you can — they'll get translated into the right URI on time. see XML::Compile::SOAP::roleAbbreviation() and the constants defined in XML::Compile::SOAP::Util. ⭐

💅 Accessors

• $obj->role() — returns the URI of the role (actor) of this server. that's it, that's the accessor. 💖

🌈 Actions

• $obj->compileFilter(%options) — this routine returns a CODE reference which can be used for compileHandler(selector); so you can check whether a certain message has arrived. right now, only the first body element is used to figure that out. 🔍

-Option--Default
 body    []
 fault   <undef>
 header  <undef>
 style   'document'

• body => ARRAY-of-TYPES
• fault => ARRAY-of-TYPES
• header => ARRAY-of-TYPES
• style => 'rpc'|'document'

• $obj->compileHandler(%options) — returns an HTTP status code and an XML::LibXML::Document pair. iconic duo, honestly. 🫶

-Option  --Default
 callback  <fault: not implemented>
 decode    <undef>
 encode    <undef>
 name      <required>
 selector  sub {0}

• callback => CODE — as input, the SERVER object and the translated input message (the Perl version) are passed in. as output, you have to produce a suitable output structure. if the callback isn't set, then a fault message gets returned to the user. 😭
• decode => CODE — this CODE reference decodes the (parsed) XML input message into the pure Perl request. the reference is a READER, created with XML::Compile::Schema::compile(). if no input decoder is specified, then the callback handler gets called with the un-decoded XML::LibXML::Document node. raw. 💀
• encode => CODE — this CODE reference encodes the Perl answer structure into the output message. the reference is a WRITER, created with XML::Compile::Schema::compile(). if no output encoder is specified, then the callback must return an XML::LibXML::Document, or only produce error messages. no in-between, bestie.
• name => STRING — the identification for this action, used for logging and stuff. when the action is created via a WSDL, the portname gets used here. it's a pity that the portname is not passed in the SOAP message, because it's not so easy to detect which handler must be called. 😔
• selector => CODE — one way or the other, you have to figure out whether a message addresses a certain process. the callback only gets used if the CODE reference specified here returns a true value. the CODE reference gets called with the XML version of the message, and a HASH which contains the information about the XML collected with XML::Compile::SOAP::messageStructure() plus the soap_version entry. 🌸

• XML::Compile::SOAP::Server->faultWriter() — returns a CODE reference which can be used to produce faults. for when things go wrong and you need to say so politely. ✨

---

⭐ SEE ALSO ⭐

this module is part of the XML-Compile-SOAP distribution version 3.28, built on August 01, 2022. website: http://perl.overmeer.net/CPAN/ 🌐

---

💜 LICENSE 💜

copyrights 2007-2022 by [Mark Overmeer <markov@cpan.org>]. 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://dev.perl.org/licenses/ 📜

---

and that's the whole page, bestie 🎀 this one was written for perl v5.34.0 and landed on 2022-08-04 — go forth and serve some SOAP, you've absolutely got this. slay. 💖✨🦋