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::Server

SYNOPSIS

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
 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 => XML::Compile::Schema object

. version => STRING

Accessors

$obj->encodingNS

See "Accessors" in XML::Compile::SOAP

$obj->envelopeNS

See "Accessors" in XML::Compile::SOAP

$obj->prefixPreferences(TABLE, NEW, [USED])

See "Accessors" in XML::Compile::SOAP

$obj->schemaInstanceNS(() {shift->{schemains}})

See "Accessors" in XML::Compile::SOAP

$obj->schemaNS

See "Accessors" in XML::Compile::SOAP

$obj->schemas

See "Accessors" in XML::Compile::SOAP

$obj->version

See "Accessors" in XML::Compile::SOAP

Single messages

$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  []
 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

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

. prefixes => HASH

. role => URI|ARRAY-OF-URI

. roles => ARRAY-OF-URI

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

$obj->importDefinitions(XMLDATA, OPTIONS)

See "Single messages" in XML::Compile::SOAP

$obj->messageStructure(XML)

XML::Compile::SOAP11->messageStructure(XML)

See "Single messages" in XML::Compile::SOAP

Sender (internals)

$obj->sender(ARGS)

See "Sender (internals)" in XML::Compile::SOAP

$obj->writerCreateBody(BODY-DEFS, NAMESPACE-TABLE, OPTS)

See "Sender (internals)" in XML::Compile::SOAP

$obj->writerCreateFault(FAULT-DEFS, NAMESPACE-TABLE, FAULTTYPE)

See "Sender (internals)" in XML::Compile::SOAP

$obj->writerCreateHeader(HEADER-DEFS, NS-TABLE, UNDERSTAND, DESTINATION, OPTS)

See "Sender (internals)" in XML::Compile::SOAP

$obj->writerCreateRpcEncoded(NAMESPACE-TABLE)

See "Sender (internals)" in XML::Compile::SOAP

$obj->writerCreateRpcLiteral(NAMESPACE-TABLE)

See "Sender (internals)" in XML::Compile::SOAP

$obj->writerEncstyleHook(NAMESPACE-TABLE)

See "Sender (internals)" in XML::Compile::SOAP

$obj->writerHook(NAMESPACE, LOCAL, ACTIONS)

See "Sender (internals)" in XML::Compile::SOAP

Receiver (internals)

$obj->readerEncstyleHook

See "Receiver (internals)" in XML::Compile::SOAP

$obj->readerHook(NAMESPACE, LOCAL, ACTIONS)

See "Receiver (internals)" in XML::Compile::SOAP

$obj->readerParseBody(BODYDEF, OPTS)

See "Receiver (internals)" in XML::Compile::SOAP

$obj->readerParseFaults(FAULTSDEF)

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

$obj->readerParseHeader(HEADERDEF, OPTS)

See "Receiver (internals)" in XML::Compile::SOAP

$obj->receiver(ARGS)

See "Receiver (internals)" in XML::Compile::SOAP

Helpers

Transcoding

$obj->replyMustUnderstandFault(TYPE)

See "Transcoding" in XML::Compile::SOAP

$obj->roleAbbreviation(URI)

See "Transcoding" in XML::Compile::SOAP

$obj->roleURI(URI|STRING)

See "Transcoding" in XML::Compile::SOAP

DETAILS

SOAP introduction

Naming types and elements

Client, Proxy and Server implementations

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

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

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