[Openinteract-dev] SOAP as a content generator

[Kutter M. <mar...@er...>]

Hi * !

On the Wiki, SOAP is mentioned as an alternative content generator in
Openinteract2Ideas.

I got an implementation ready for a SOAP Content generator, a SOAP Request &
Response handler and an apache1 content handler using SOAP::Lite (currently
based on OpenInteract-1.99_03, but porting to _04 shouldn't be much of an
issue). 

The basic layout is like this:

Apache Content handler takes request and

1 checks correctness (HTTP POST, encoding, compression etc.) and sends 
       back error message on error.
2 sets up response (the only change to OpenInteract2::Response::Apache is 
  setting the content type to text/xml ).
3 sets up request which
  3.1 parses SOAP document & calls oi2_error on error
  3.2 looks up SOAP namespace uri from SOAP request and 
      rewrites URL on base of the namespace uri
  3.3 returns request containing both apache and soap request 
             (soap request is a SOAP::SOM object)
4 calls controller (should be raw, i "accidentally" wrote a new one, too)
  4.1 controller executes action
      4.1.1 action calls content generator (SOAP) to create content
  4.2 controller sets up response
5 sends back content

Both apache content handler and the request module are somewhat more
complicated than the existing ones. This is due to the whole bunch of errors
that can appear when receiving SOAP messages, and the different levels of
errors (HTTP level, XML encoding level, content level).

There are some limitations in the current implementation:

1. Complex datatypes are not supported in SOAP requests. This is due to the
simple mapping of request parameters to OpenInteract actions - and a
similarity to WWW forms (have you ever seen a complex type in a HTML form
?). However, SOAP responses may be of arbitrary complexity.

2. Compression, XML encryption and SOAP authentication are currently not
supported. This may change for compression and XML encryption, but SOAP
authentication is not supported by SOAP::Lite and I don't feel like
implementing a new SOAP toolkit.

3. The URL rewrite requires SOAP clients to send appropriate namespace uris.
This is no major drawback - .NET does the same.

4. There currently is no WSDL support. 


The least obvious parts in this implementation are 3.3 (the URL rewrite for 
request-to-action mapping) and 4.1.1 (the content generation).


A look at URL rewriting:

URL rewrite seems desirable - this allows to set up a WebService in parallel
to a WWW frontend (e.g. http://www.myhost.org/OpenInteract/ for the WWW
frontend, http://www.myhost.org/OpenInteractWebService/ for the SOAP
frontend).
Moreover, it allows to map SOAP requests accepted at exactly _one_ URL to
different OpenInteract actions based on the namespace uri of the request.

The SOAP namespace URI seems to be a "usable" base for the URL rewrite: It
just identifies some (arbitrary) namespace, which does not need to refer to
an existing URL. Namespace URIs can be set to arbitrary values by (almost?)
all SOAP client packages, including SOAP::Lite (.NET supports and normally
even requires the use of namespace URIs).


A look at content generation:

The content generator currently takes the action return parameters and 
- creates a SOAP::Fault response if an error_msg is set
- encodes _all_ return parameters (aside from ACTION) into a SOAP response, 
automatically encoding SPOPS objects, hash and list references correctly.
Hereby SPOPS objects are transformed into Hash refs containing all fields 
of the object (nobody but a perl SOAP client could handle perl objects...).

Theres are some caveats in this kind of content generation:
1. The soap response may include more information than the WWW response -
this occurs if you filter your action response with the template.
2. Lists may be badly encoded if they contain data of more than one SOAP
datatype (number, string and ? I forgot about is...). This is a SOAP
limitation.


Interested ?

Martin Kutter