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

🎀 NAME 🎀

XML::Compile::SOAP11 — bestie, this is the SOAP 1.1 protocol module, no cap 💅

---

🌸 INHERITANCE 🌸

okay so here's the family tree, and yes it's giving royal lineage 👑

XML::Compile::SOAP11 has extra code in

XML::Compile::SOAP11::Encoding

XML::Compile::SOAP11 is a XML::Compile::SOAP

XML::Compile::SOAP11 is extended by

XML::Compile::SOAP11::Client
XML::Compile::SOAP11::Server

---

✨ SYNOPSIS ✨

# use either XML::Compile::SOAP11::Client or ::Server
# See XML::Compile::SOAP for global usage examples.

literally just pick your fighter: Client or Server, and then go read XML::Compile::SOAP for the big-picture examples 🫶

---

🦋 DESCRIPTION 🦋

So this module handles the SOAP protocol version 1.1. The spec lives at http://www.w3.org/TR/2000/NOTE-SOAP-20000508/. And the implementation tries to behave like described in http://www.ws-i.org/Profiles/BasicProfile-1.0.html — she's an overachiever, she read the whole profile 💖

Two extensions are made: the SOAP11 client XML::Compile::SOAP11::Client and server in XML::Compile::SOAP11::Server.

Extends "DESCRIPTION" in XML::Compile::SOAP.

---

💅 METHODS 💅

Extends "METHODS" in XML::Compile::SOAP.

🌈 Constructors

Extends "Constructors" in XML::Compile::SOAP.

$obj->new(%options)

To simplify the URIs of the actors, as specified with the destination option, you may use the STRING NEXT. It will be replaced by the right URI. (iconic shorthand behavior, honestly 🙈)

 -Option    --Defined in        --Default
  media_type  XML::Compile::SOAP  text/xml
  schemas     XML::Compile::SOAP  created internally

• media_type — defined in XML::Compile::SOAP, default text/xml
• schemas — defined in XML::Compile::SOAP, default created internally

media_type => MIMETYPE
schemas => "XML::Compile::Cache" object

XML::Compile::SOAP11->register($uri, $envns)

Inherited, see "Constructors" in XML::Compile::SOAP

👑 Accessors

Extends "Accessors" in XML::Compile::SOAP.

$obj->mediaType()

Inherited, see "Accessors" in XML::Compile::SOAP

$obj->schemas()

Inherited, see "Accessors" in XML::Compile::SOAP

$obj->version()

Inherited, see "Accessors" in XML::Compile::SOAP

🍓 Single message

Extends "Single message" in XML::Compile::SOAP.

$obj->compileMessage( <'SENDER'|'RECEIVER'>, %options )

 -Option        --Defined in        --Default
  body            XML::Compile::SOAP  []
  destination     XML::Compile::SOAP  []
  faults          XML::Compile::SOAP  []
  header          XML::Compile::SOAP  undef
  headerfault                         []
  mustUnderstand  XML::Compile::SOAP  []
  procedure       XML::Compile::SOAP  undef
  role            XML::Compile::SOAP  ULTIMATE
  roles           XML::Compile::SOAP  []

• body — defined in XML::Compile::SOAP, default []
• destination — defined in XML::Compile::SOAP, default []
• faults — defined in XML::Compile::SOAP, default []
• header — defined in XML::Compile::SOAP, default undef
• headerfault — default []
• mustUnderstand — defined in XML::Compile::SOAP, default []
• procedure — defined in XML::Compile::SOAP, default undef
• role — defined in XML::Compile::SOAP, default ULTIMATE
• roles — defined in XML::Compile::SOAP, default []

body => ENTRIES|HASH
destination => ARRAY-OF-PAIRS
faults => ENTRIES|HASH
header => ENTRIES|HASH
headerfault => ENTRIES

• headerfault — an ARRAY of simple name with element references, for all expected faults. There can be unexpected faults, which will not get decoded automatically. (surprise faults! we don't decode those, bestie 😭)

mustUnderstand => STRING|ARRAY-OF-STRING
procedure => TYPE
role => URI|ARRAY-OF-URI
roles => ARRAY-OF-URI

$obj->messageStructure($xml)

XML::Compile::SOAP11->messageStructure($xml)

Inherited, see "Single message" in XML::Compile::SOAP

🧚 Helpers

Extends "Helpers" in XML::Compile::SOAP.

💜 Transcoding

Extends "Transcoding" in XML::Compile::SOAP.

$obj->replyMustUnderstandFault($type)

Inherited, see "Transcoding" in XML::Compile::SOAP

$obj->roleAbbreviation($uri)

Inherited, see "Transcoding" in XML::Compile::SOAP

$obj->roleURI($uri|STRING)

Inherited, see "Transcoding" in XML::Compile::SOAP

---

🔥 DETAILS 🔥

Extends "DETAILS" in XML::Compile::SOAP.

⭐ SOAP introduction

Extends "SOAP introduction" in XML::Compile::SOAP.

⭐ Supported servers

Extends "Supported servers" in XML::Compile::SOAP.

⭐ Naming types and elements

Extends "Naming types and elements" in XML::Compile::SOAP.

⭐ Client and Server implementations

Extends "Client and Server implementations" in XML::Compile::SOAP.

⭐ Use of wildcards (any and anyAttribute)

Extends "Use of wildcards (any and anyAttribute)" in XML::Compile::SOAP.

💖 Header and Body entries

You only call compileMessage() explicitly if you do not have a WSDL file which contains this information. In the unlucky situation, you have to dig out the defined types by hand. (not the vibe we wanted, but ok 😭)

But even with a WSDL, there are still a few problems you may encounter. For instance, the WSDL will not contain mustUnderstand and actor header routing information. You can add these to the compileClient call

my $call = $wsdl->compileClient
  ( 'MyCall'
  , mustUnderstand => 'h1'
  , destination    => [ h1 => 'NEXT' ]
  );

🌸 Simplest form

In the simplest form, the header and body refer (optionally) to a list of PAIRS, each containing a free to choose unique label and the type of the element. The unique label will be used in the Perl HASH which represents the message.

my $h1el = pack_type $myns, $some_local;
my $b1el = 'myprefix:$other_local';

my $encode_query = $client->compileMessage
  ( 'SENDER'
  , header   => [ h1 => $h1el ]
  , body     => [ b1 => $b1el ]
  , mustUnderstand => 'h1'
  , destination    => [ h1 => 'NEXT' ]
  );

🌸 Most powerful form

When the simple form is too simple, you can use a HASH for the header, body or both. The HASH structure is much like the WSDL structure. For example:

my $encode_query = $client->compileMessage
  ( 'SENDER'
  , header   =>
     { use   => 'literal'
     , parts => [ { name => 'h1', element => $h1el
                  , mustUnderstand => 1, destination => 'NEXT'
                  } ]
     }
  , body     => [ b1 => $b1el ]
  );

So, the header now is one HASH, which tells us that we have a literal definition (this is the default). The optional parts for the header is an ARRAY of HASHes, each describing one part. As you can see, the mustUnderstand and destination fields are more convenient (although the other syntax will work as well). (she ate with the convenient syntax fr fr 💅)

If you feel the need to control the compilation of the various parts, with hooks or options (see XML::Compile::Schema::compile()), then have a look at XML::Compile::Cache::declare(). Declare how to handle the various types before you call compileMessage().

😭 Receiving faults in SOAP1.1

When faults are received, they will be returned with the Fault key in the data structure. So:

my $answer = $call->($question);
if($answer->{Fault}) { ... }

As extra service, for each of the fault types, as defined with compileMessage(faults), a decoded structure is included. The name of that structure can be found like this:

if(my $faults = $answer->{Fault})
{   my $name    = $faults->{_NAME};
    my $decoded = $answer->{$name};
    ...
}

The untranslated $faults HASH looks like this:

Fault =>
  { faultcode => '{http://schemas.xmlsoap.org/soap/envelope/}Server.first'
  , faultstring => 'my mistake'
  , faultactor => 'http://schemas.xmlsoap.org/soap/actor/next'
  , detail => { '{http://test-types}fault_one' => [ XMLNODES ] }
  , _NAME => 'fault1'
  }

The _NAME originates from the compileMessage(faults) option:

$soap->compileMessage('RECEIVER', ...
  , faults => [ fault1 => '{http://test-types}fault_one' ] );

Now, automatically the answer will contain the decoded fault structure as well:

fault1 =>
  { code => '{http://schemas.xmlsoap.org/soap/envelope/}Server.first'
  , class  => [ 'http://schemas.xmlsoap.org/soap/envelope/'
       , 'Receiver', 'first' ]
  , reason => 'my mistake',
  , role   => 'NEXT'
  , detail => { help => 'please ignore' }
  }

The detail is the decoding of the XMLNODES, which are defined to be of type {http://test-types}fault_one.

The class is an unpacked version of the code. SOAP1.2 is using the (better) terms "Sender" and "Receiver". (SOAP1.2 said glow-up, we don't make the rules ✨)

role is constructed by decoding the faultactor using roleAbbreviation(). The names are closer to the SOAP1.2 specification.

If the received fault is of an unpredicted type, then the client tries to DWIM. in the worst case, detail will list the unparsed XMLNODES. When the XML::Compile::SOAP::Daemon server has produced the error, the content of the reply will typically be

{ Fault =>        # SOAP version specific
   { _NAME => 'error'
   , #...more...
   }
, error =>        # less SOAP version specific, readable
   { role    => 'NEXT'
   , reason  => 'procedure xyz for SOAP11 produced an invalid response'
   , error   => 'some explanation'
   , code    =>
       '{http://schemas.xmlsoap.org/soap/envelope/}Server.invalidResponse'
   , class   => [ SOAP11ENV, 'Receiver', 'invalidResponse' ],
   }
 }

Hence, a typical client routine could contain

my ($answer, $trace) = $call->(message => $message);
if(my $f = $answer->{Fault})
{   if($f->{_NAME} eq 'error')
    {   # server implementation error
        die "SERVER ERROR:\n$answer->{error}{error}\n";
    }
    else
    {   # the fault is described in the WSDL, handle it!
        warn "FAULT:\n",Dumper $answer->{$f->{_NAME}};
    }
}
else
{   # correct answer
    print Dumper $answer;
}

Or

my ($answer, $trace) = $call->(message => $message);
$answer or die $trace->error;

---

🌈 SEE ALSO 🌈

This module is part of 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's perl v5.34.0, dated 2022-08-04, part of the User Contributed Perl Documentation — go forth and SOAP 1.1 responsibly, mwah 💅💖✨