=head1 NAME XML::Compile::SOAP11 - base for SOAP1.1 implementation =head1 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 =head1 SYNOPSIS # use either XML::Compile::SOAP11::Client or ::Server # See XML::Compile::SOAP for global usage examples. =head1 DESCRIPTION This module handles the SOAP protocol version 1.1. See F<http://www.w3.org/TR/2000/NOTE-SOAP-20000508/>). The implementation tries to behave like described in F<http://www.ws-i.org/Profiles/BasicProfile-1.0.html> Two extensions are made: the SOAP11 client L<XML::Compile::SOAP11::Client|XML::Compile::SOAP11::Client>. and server in L<XML::Compile::SOAP11::Server|XML::Compile::SOAP11::Server>. =head1 METHODS =head2 Constructors $obj-E<gt>B<new>(OPTIONS) =over 4 To simplify the URIs of the actors, as specified with the C<destination> option, you may use the STRING C<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 . media_type => MIMETYPE . schemas => C<XML::Compile::Cache> object =back =head2 Accessors $obj-E<gt>B<name> =over 4 See L<XML::Compile::SOAP/"Accessors"> =back $obj-E<gt>B<schemas> =over 4 See L<XML::Compile::SOAP/"Accessors"> =back $obj-E<gt>B<version> =over 4 See L<XML::Compile::SOAP/"Accessors"> =back =head2 Single message $obj-E<gt>B<compileMessage>(('SENDER'|'RECEIVER'), OPTIONS) =over 4 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 =over 4 ARRAY of simple name with element references, for all expected faults. There can be unexpected faults, which will not get decoded automatically. =back . mustUnderstand => STRING|ARRAY-OF-STRING . role => URI|ARRAY-OF-URI . roles => ARRAY-OF-URI =back $obj-E<gt>B<messageStructure>(XML) XML::Compile::SOAP11-E<gt>B<messageStructure>(XML) =over 4 See L<XML::Compile::SOAP/"Single message"> =back =head2 Helpers =head2 Transcoding $obj-E<gt>B<replyMustUnderstandFault>(TYPE) =over 4 See L<XML::Compile::SOAP/"Transcoding"> =back $obj-E<gt>B<roleAbbreviation>(URI) =over 4 See L<XML::Compile::SOAP/"Transcoding"> =back $obj-E<gt>B<roleURI>(URI|STRING) =over 4 See L<XML::Compile::SOAP/"Transcoding"> =back =head1 DETAILS =head2 SOAP introduction =head2 Naming types and elements =head2 Client, Proxy and Server implementations =head2 Header and Body entries You only call L<compileMessage()|XML::Compile::SOAP11/"Single message"> 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 C<mustUnderstand> and C<actor> header routing information. You can add these to the compile call my $call = $wsdl->compileClient ( 'MyCall' , mustUnderstand => 'h1' , destination => [ h1 => 'NEXT' ] ); =head3 Simplest form In the simplest form, the C<header> and C<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' ] ); =head3 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 L<XML::Compile::Schema::compile()|XML::Compile::Schema/"Compilers">), then have a look at L<XML::Compile::Cache::declare()|XML::Compile::Cache/"Administration">. Declare how to handle the various types before you call L<compileMessage()|XML::Compile::SOAP11/"Single message">. =head2 Receiving faults in SOAP1.1 When faults are received, they will be returned with the C<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 L<compileMessage(faults)|XML::Compile::SOAP/"Single message">, 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 C<$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 C<_NAME> originates from the L<compileMessage(faults)|XML::Compile::SOAP/"Single message"> 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 C<detail> is the decoding of the XMLNODES, which are defined to be of type C<< {http://test-types}fault_one >>. The C<class> is an unpacked version of the code. SOAP1.2 is using the (better) terms C<Sender> and C<Receiver>. C<role> is constructed by decoding the C<faultactor> using L<roleAbbreviation()|XML::Compile::SOAP/"Transcoding">. The names are closer to the SOAP1.2 specification. If the received fault is of an unpredicted type, then key C<body> is used, and the C<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 C<header> key is used. =head1 SEE ALSO This module is part of XML-Compile-SOAP distribution version 2.09, built on January 28, 2010. Website: F<http://perl.overmeer.net/xml-compile/> All modules in this suite: L<XML::Compile>, L<XML::Compile::SOAP>, L<XML::Compile::SOAP12>, L<XML::Compile::SOAP::Daemon>, L<XML::Compile::Tester>, L<XML::Compile::Cache>, L<XML::Compile::Dumper>, L<XML::Compile::RPC>, and L<XML::Rewrite>, L<XML::ExistDB>, L<XML::LibXML::Simple>. Please post questions or ideas to the mailinglist at F<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile> For life contact with other developers, visit the C<#xml-compile> channel on C<irc.perl.org>. =head1 LICENSE Copyrights 2007-2010 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 F<http://www.perl.com/perl/misc/Artistic.html>