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