Provided by: libxml-compile-soap-perl_3.28+ds-1_all 
NAME
XML::Compile::SOAP11 - SOAP 1.1 protocol
INHERITANCE
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.
DESCRIPTION
This module handles the SOAP protocol version 1.1. See
http://www.w3.org/TR/2000/NOTE-SOAP-20000508/). The implementation tries to behave like
described in http://www.ws-i.org/Profiles/BasicProfile-1.0.html
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.
-Option --Defined in --Default
media_type XML::Compile::SOAP text/xml
schemas XML::Compile::SOAP 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 => ENTRIES|HASH
destination => ARRAY-OF-PAIRS
faults => ENTRIES|HASH
header => ENTRIES|HASH
headerfault => ENTRIES
ARRAY of simple name with element references, for all expected faults. There can be
unexpected faults, which will not get decoded automatically.
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.
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).
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".
"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/