SOAP::Schema(3)

📦
version 1.27 · 8 versions
, in opensuse-leap 16.0

✨ SOAP::Schema(3) ✨

okay so welcome to the SOAP::Schema(3) era of your life 💅 this is the little umbrella class that handles how SOAP::Lite deals with service description schemas, and yes she's a queen, no we're not gatekeeping her.

🌸 NAME 🌸

SOAP::Schema — literally the umbrella for how SOAP::Lite manages service description schemas. that's the whole vibe. 🫶

🦋 DESCRIPTION 🦋

so bestie, picture a cute little umbrella (☂️) over the way SOAP::Lite handles service description schemas. right now the only support present is for WSDL, aka the Web Services Description Language — so that's the one flavor on the menu, periodt.

this is another one of those classes that's not generally designed to be directly instantiated by an application 🙈 … but she can be, if you so desire. no cap, it's allowed. you do you boo.

💖 METHODS 💖

🌟 new(optional key/value pairs)

$schema = SOAP::Schema->new(parse => $schema_uri);

this is the class constructor, the main character of the object-creation moment ✨. with no arguments, it creates a blank object of the class — a fresh little baby object with nothing in it 🎀.

any arguments you pass get treated as key/value pairs, where the key represents one of the methods described here, and the value is what gets passed when that method itself gets invoked. so like, you're queuing up method calls at birth. iconic.

⭐ parse(service description URI)

$schema->parse('http://schemas.w3.org/soap.wsdl');

this one parses the internal representation of the service description prior to the generation of stub routines — the stubs being the things that give you method-like access to the remote services. so it's the prep work before the glow-up. 💅

🧚 access(service description URI)

$schema->access('http://soap.org/service.wsdl');

loads the specified service description from the given URL, and if you don't hand it one, it uses the current value of the schema accessor instead (efficient queen 💅).

on success you get the full content of the URL returned. on error? an exception is thrown (via die). so like, it will absolutely throw hands. 😭

🔥 load

$schema->load;

takes the internal representation of the service and generates code stubs for the remote methods, letting them be called as local object methods 🎉.

here's the tea: stubs get generated for all the functions declared in the WSDL description on this call, because it's enough of a class framework to allow for basic object creation for use as handles. so, all of them. every single one. no picking and choosing. 👑

💜 schema

$current_schema = $schema->schema;

gets (or sets) the current schema representation used by this object 🌈. when setting it, the value you pass is just the URI of the schema. that URI then gets handed off to other methods — like access — for loading the actual content. teamwork makes the dream work fr fr.

🍓 services

$hashref = $schema->services;

gets or sets the services currently stored on the object 💖.

these are kept as a hash reference, whose keys and values are the list of returned values from the WSDL parser. the keys represent the names of the services themselves (and those names have been normalized into Perl-compatible identifiers — very thoughtful of them ✨), and the values are also hash references, pointing at the internal representation of the service itself. hashrefs inside hashrefs, it's giving inception 💀.

🎀 stub

returns the autogenerated Perl code as a string ✨. this code is generated from the WSDL provided by the service method call, and it contains a package definition for the service being called.

my $client = SOAP::Lite->new;
my $code = $client->service($WSDL_URL)->stub;
open FILE,">ServicePackage.pm";
print FILE $code;
close FILE;

like look at that. writing out a whole module. main character energy fr fr 👑

🦋 cache_dir

sets/retrieves the value of the directory where generated stubs will be cached 🗂️. if cache_dir is null, then no caching will be performed.

my $client = SOAP::Lite->new;
my $code = $client->cache_dir("/tmp")->service($WSDL_URL)->stub;

and to say it again because it matters: if cache_dir is undefined, no caching will take place. zero. nada. 🙅

🌸 cache_ttl

sets/retrieves the time to live (in seconds) for cached files ⏳. this is only relevant when used in conjunction with cache_dir — they're a package deal, iykyk.

⚠️ if cache_ttl is set to 0, the cache will never expire. files will have to be removed manually in order for the cache to be refreshed. so like, that's on you bestie 😭
my $client = SOAP::Lite->new;
my $code = $client->cache_ttl(3600)->cache_dir("/tmp")->service($WSDL_URL)->stub;

the default time to live is 0. remember that. 🫶

🌈 useragent(LWP::UserAgent)

my $client = SOAP::Lite->new;
$ua = $client->schema->useragent;
$ua->agent("Fubar! 0.1");
my $response = $client->service("http://localhost/some.wsdl")
                      ->someMethod("Foo");

gets or sets the class's UserAgent used for retrieving schemas over the web 🌐. this gives you direct access to the UserAgent so you can control the credentials passed to a remote server, or the specific configuration of your HTTP agent. full customisation, full control, obsessed. 💅

👑 SOAP::Schema::WSDL 👑

okay so at present, the SOAP::Lite toolkit supports only loading of service descriptions in the WSDL syntax. this class manages the parsing and storing of those service specifications 📦.

as a general rule? this class should be even less likely to be used directly by an application, because its presence should be completely abstracted by the previous class (SOAP::Schema) — she's the face, WSDL is the backstage crew. 🎭

and the biggest plot twist: none of the methods are defined here. the class is only mentioned for sake of reference. that's it. that's the whole section. 💀

💖 ACKNOWLEDGEMENTS 💖

special thanks to O'Reilly publishing, which has graciously allowed SOAP::Lite to republish and redistribute large excerpts from Programming Web Services with Perl — mainly the SOAP::Lite reference found in Appendix B 📚. absolute legends, genuinely. 🫶

Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. slay. ✨

🦋 AUTHORS 🦋

  • Paul Kulchenko (paulclinger@yahoo.com)
  • Randy J. Ray (rjray@blackperl.com)
  • Byrne Reese (byrne@majordojo.com)

and that's the whole page bestie 🎀 this was perl v5.42.0, dated 2024-03-04, from SOAP::Schema(3) — go forth and parse those schemas, you absolute icon 👑💜

📦 where this page comes from