=head1 NAME

XML::Compile::SOAP11 - base class for SOAP1.1 implementation

=head1 INHERITANCE

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

 XML::Compile::SOAP11 is extended by
   XML::Compile::SOAP11::Client
   XML::Compile::SOAP11::Server

=head1 SYNOPSIS

=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
 encoding_ns         XML::Compile::SOAP  http://schemas.xmlsoap.org/soap/encoding/
 envelope_ns         XML::Compile::SOAP  http://schemas.xmlsoap.org/soap/envelope/
 media_type          XML::Compile::SOAP  application/soap+xml
 schema_instance_ns  XML::Compile::SOAP  $schema_ns . '-instance'
 schema_ns           XML::Compile::SOAP  http://www.w3.org/2001/XMLSchema
 schemas             XML::Compile::SOAP  created internally
 version             XML::Compile::SOAP  'SOAP11'

. encoding_ns => URI

. envelope_ns => URI

. media_type => MIMETYPE

. schema_instance_ns => URI

. schema_ns => URI

. schemas => C<XML::Compile::Schema> object

. version => STRING

=back

=head2 Accessors

$obj-E<gt>B<encodingNS>

=over 4

See L<XML::Compile::SOAP/"Accessors">

=back

$obj-E<gt>B<envelopeNS>

=over 4

See L<XML::Compile::SOAP/"Accessors">

=back

$obj-E<gt>B<prefixPreferences>(TABLE, NEW, [USED])

=over 4

See L<XML::Compile::SOAP/"Accessors">

=back

$obj-E<gt>B<schemaInstanceNS>(() {shift->{schemains}})

=over 4

See L<XML::Compile::SOAP/"Accessors">

=back

$obj-E<gt>B<schemaNS>

=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 messages

$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  []
 prefixes        XML::Compile::SOAP  {}
 role            XML::Compile::SOAP  ULTIMATE
 roles           XML::Compile::SOAP  []
 style           XML::Compile::SOAP  'document'

. body => ENTRIES

. destination => ARRAY

. faults => ENTRIES

. header => ENTRIES

. 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

. prefixes => HASH

. role => URI|ARRAY-OF-URI

. roles => ARRAY-OF-URI

. style => 'document'|'rpc-literal'|'rpc-encoded'

=back

$obj-E<gt>B<importDefinitions>(XMLDATA, OPTIONS)

=over 4

See L<XML::Compile::SOAP/"Single messages">

=back

$obj-E<gt>B<messageStructure>(XML)

XML::Compile::SOAP11-E<gt>B<messageStructure>(XML)

=over 4

See L<XML::Compile::SOAP/"Single messages">

=back

=head2 Sender (internals)

$obj-E<gt>B<sender>(ARGS)

=over 4

See L<XML::Compile::SOAP/"Sender (internals)">

=back

$obj-E<gt>B<writerCreateBody>(BODY-DEFS, NAMESPACE-TABLE, OPTS)

=over 4

See L<XML::Compile::SOAP/"Sender (internals)">

=back

$obj-E<gt>B<writerCreateFault>(FAULT-DEFS, NAMESPACE-TABLE, FAULTTYPE)

=over 4

See L<XML::Compile::SOAP/"Sender (internals)">

=back

$obj-E<gt>B<writerCreateHeader>(HEADER-DEFS, NS-TABLE, UNDERSTAND, DESTINATION, OPTS)

=over 4

See L<XML::Compile::SOAP/"Sender (internals)">

=back

$obj-E<gt>B<writerCreateRpcEncoded>(NAMESPACE-TABLE)

=over 4

See L<XML::Compile::SOAP/"Sender (internals)">

=back

$obj-E<gt>B<writerCreateRpcLiteral>(NAMESPACE-TABLE)

=over 4

See L<XML::Compile::SOAP/"Sender (internals)">

=back

$obj-E<gt>B<writerEncstyleHook>(NAMESPACE-TABLE)

=over 4

See L<XML::Compile::SOAP/"Sender (internals)">

=back

$obj-E<gt>B<writerHook>(NAMESPACE, LOCAL, ACTIONS)

=over 4

See L<XML::Compile::SOAP/"Sender (internals)">

=back

=head2 Receiver (internals)

$obj-E<gt>B<readerEncstyleHook>

=over 4

See L<XML::Compile::SOAP/"Receiver (internals)">

=back

$obj-E<gt>B<readerHook>(NAMESPACE, LOCAL, ACTIONS)

=over 4

See L<XML::Compile::SOAP/"Receiver (internals)">

=back

$obj-E<gt>B<readerParseBody>(BODYDEF, OPTS)

=over 4

See L<XML::Compile::SOAP/"Receiver (internals)">

=back

$obj-E<gt>B<readerParseFaults>(FAULTSDEF)

=over 4

The decoders for the possible "faults" are compiled.  Returned is a code
reference which can handle it.  See fault handler specifics in the
C<DETAILS> chapter below.

=back

$obj-E<gt>B<readerParseHeader>(HEADERDEF, OPTS)

=over 4

See L<XML::Compile::SOAP/"Receiver (internals)">

=back

$obj-E<gt>B<receiver>(ARGS)

=over 4

See L<XML::Compile::SOAP/"Receiver (internals)">

=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 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 messages">, 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 messages"> 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 0.77,
built on August 15, 2008. Website: F<http://perl.overmeer.net/xml-compile/>

All modules in this suite:
L<XML::Compile>,
L<XML::Compile::SOAP>,
L<XML::Compile::SOAP::Daemon>,
L<XML::Compile::Tester>,
L<XML::Compile::Cache>,
L<XML::Rewrite>,
L<XML::Compile::Dumper>.

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-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 F<http://www.perl.com/perl/misc/Artistic.html>