NAME
XML::Compile::SOAP11 - base class for SOAP1.1 implementation
INHERITANCE
XML::Compile::SOAP11
is a XML::Compile::SOAP
XML::Compile::SOAP11 is extended by
XML::Compile::SOAP11::Client
XML::Compile::SOAP11::ServerSYNOPSIS
# 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.
METHODS
Constructors
$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 application/soap+xml
schemas XML::Compile::SOAP created internally
version XML::Compile::SOAP <required>. media_type => MIMETYPE
. schemas => XML::Compile::Cache object
. version => STRING
Accessors
$obj->name
$obj->schemas
$obj->version
Single message
$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 []
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
. role => URI|ARRAY-OF-URI
. roles => ARRAY-OF-URI
$obj->messageStructure(XML)
XML::Compile::SOAP11->messageStructure(XML)
Helpers
Transcoding
$obj->replyMustUnderstandFault(TYPE)
$obj->roleAbbreviation(URI)
$obj->roleURI(URI|STRING)
DETAILS
SOAP introduction
Naming types and elements
Client, Proxy and Server implementations
Header and Body entries
You only call compileMessage() explicit if you do not have a WSDL file which contains this information. So, in the unlucky situation, you have to dig in 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 compile 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 Faults key in the data structure. So:
my $answer = $call->($question);
if($answer->{Faults}) { ... }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->{Faults})
{ 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 key body is used, and the detail will list the unparsed XMLNODEs. When there are no details, (according to the specs) the error must be caused by a header problem, so the header key is used.
SEE ALSO
This module is part of XML-Compile-SOAP distribution version 2.00_01, built on December 29, 2008. Website: http://perl.overmeer.net/xml-compile/
All modules in this suite: XML::Compile, XML::Compile::SOAP, XML::Compile::SOAP12, XML::Compile::SOAP::Daemon, XML::Compile::Tester, XML::Compile::Cache, XML::Compile::Dumper, XML::Rewrite, and XML::LibXML::Simple.
Please post questions or ideas to the mailinglist at http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile For life contact with other developers, visit the #xml-compile channel on irc.perl.org.
LICENSE
Copyrights 2007-2008 by Mark Overmeer. 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://www.perl.com/perl/misc/Artistic.html