Provided by: libxml-compile-soap-perl_3.22-2_all bug

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.22, built on June 30, 2017.
       Website: http://perl.overmeer.net/xml-compile/

       Please post questions or ideas to the mailinglist at
       http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile .  For live contact with
       other developers, visit the "#xml-compile" channel on "irc.perl.org".

LICENSE

       Copyrights 2007-2017 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://dev.perl.org/licenses/