CL-SOAP

An open-source (LLGPL) implementation of SOAP for Common Lisp.

Ultimately, this library will implement the full SOAP 1.1 spec ( http://www.w3.org/TR/2000/NOTE-SOAP-20000508 ), both the client and server parts, using both HTTP and HTTPS as transports as well as the WSDL 1.1 spec ( http://www.w3.org/TR/2001/NOTE-wsdl-20010315 ) and the XML Schema Definition spec ( http://www.w3.org/TR/xmlschema-1/ and http://www.w3.org/TR/xmlschema-2/ ) on as many CL implementations as possible. Interoperability with various other SOAP implementations and applications will be possible.

Phase 1 (First Delivery Target)

Setup of a public open source project (on common-lisp.net ).
- The official project home is http://common-lisp.net/project/cl-soap
- The CVS repository can be found at http://common-lisp.net/cgi-bin/viewcvs.cgi/?cvsroot=cl-soap
- To get the code through CVS:
```
$ cvs -d:pserver:anonymous@common-lisp.net:/project/cl-soap/cvsroot login
Logging in to :pserver:anonymous@common-lisp.net:2401/project/cl-soap/cvsroot
CVS password:
$ cvs -d:pserver:anonymous@common-lisp.net:/project/cl-soap/cvsroot co cl-soap
cvs server: Updating cl-soap
...
```
  Specifiy 'anonymous' as password. Afterwards, keep up to date by issuing cvs update in the cl-soap directory.
- The following mailing list are available: CL-SOAP-DEVEL as well as CL-SOAP-CVS
Implement as much of the general CL-SOAP framework to access the Google AdWords API ( http://www.google.com/apis/adwords/ ) from LispWorks ( http://www.lispworks.com ).
This means that we need to implement the client side of SOAP 1.1, but only the so called Document model. We need HTTPS (comes with LispWorks).
Without (dynamic) WSDL 1.1 support this would mean manual XML message (document) encoding and decoding - not very difficult but not elegant and tedious.
Therefore there will be support for WSDL, XSD and the dynammic usage of this meta data to access services and/or the dynamic generation of any necessary CL stub code (classes, methods) to access services.
Testing will occur against the live Google AdWords API and against local Apache Axis SOAP 1.1 (possibly 1.2) Java servers (these are used by Google) ( http://ws.apache.org/axis/ ).
Good debugging support as well as initial unit and functional tests will be added.

Installation Instructions

Get the source code for CL-SOAP through CVS as described above.
Get the source code for S-XML through CVS (do not use a released version).
Get a recent version of the PURI package.
Make sure ASDF works for you, add the *.asd files of the packages you just downloaded (see the asdf manual).
With all of the above done:
```
(asdf:oos 'asdf:load-op :cl-soap)
```
should load all code into your lisp image (and compile it if necessary).
Check out the example/test code in the test directory.
May the source be with you, always.

Status

Currently, phase 1 (and then some) has been implemented.

S-XML was extended to support XML Namespaces.

Basic, manual SOAP calls are now possible, for example (creating the package :ns1 if necessary):

(defun xmethods-get-quote (symbol)
  "Calling http://services.xmethods.net/soap/urn:xmethods-delayed-quotes.wsdl"
  (let ((ns "urn:xmethods-delayed-quotes"))
    (s-xml:register-namespace ns "ns1" :ns1)
    (let* ((xmethods (make-soap-end-point "http://64.124.140.30:9090/soap"))
           (result (soap-call xmethods 
                              '() 
                              `((ns1::|getQuote| 
                                 soapenv:|encodingStyle| ,+soap-enc-ns-uri+
                                 :|xmlns:ns1| ,ns) 
                                ((:|symbol| xsi::|type| "xsd:string") 
                                 ,symbol)) 
                              :soap-action "urn:xmethods-delayed-quotes#getQuote")))
      (if (eql (lxml-get-tag result) 'ns1::|getQuoteResponse|)
          (let ((contents (lxml-find-tag :|Result| (rest result))))
            (if contents
                (coerce (read-from-string (lxml-get-contents contents)) 'float)
              (error "Expected a <Result> element")))
        (error "Expected a <getQuoteResponse> element")))))

Check out the test/test-basic.lisp file for more examples.

WSDL with SOAP bindings in url/file/stream form can now be parsed into a Common Lisp representation. Use parse-wsdl, parse-wsdl-file and parse-wsdl-url.

The WSDL SOAP CL representation can be inspected and printed using describe-wsdl-soap. For example:

CL-SOAP> (describe-wsdl-soap (parse-wsdl-url "http://www.xmethods.net/sd/2001/CurrencyExchangeService.wsdl"))
WSDL Document Definitions named CurrencyExchangeService
  Service: CurrencyExchangeService
    Port: CurrencyExchangePort
    SOAP Address Location "http://services.xmethods.net:80/soap"
    Binding: tns:CurrencyExchangeBinding
      Operation: getRate
        Input: getRateRequest
          Part: country2 (type xsd:string)
          Part: country1 (type xsd:string)
        Output: getRateResponse
          Part: Result (type xsd:float)

There is a partial implementation for making SOAP calls with structured WSDL support, for example:

(defun xmethods-get-rate (country1 country2)
  (wsdl-soap-call "http://www.xmethods.net/sd/2001/CurrencyExchangeService.wsdl"
                  "getRate"
                  :input `("country1" ,country1 "country2" ,country2)))

Https support in http-client.lisp was added for LispWorks.
The general function soap-call was extended to handle headers (input and output headers).
The function wsdl-soap-call now handles document based SOAP calls too.
Partial support for XML Schema Defintion types definition in WSDL has been implemented. To simplify the general XSD spec (which we don't need, does anybody ?), we are using a simplified template representation internally.
The target of being able to talk to the Google AdWords API has been reached! A separate document, Google AdWords API describes this in more detail and with some verbose examples.
Lot's of work remains to be done! All help is welcome.

Debugging and Reporting Errors

Common Lisp is a way better environment to develop and experiment with something like SOAP than more mainstream languages like C, C++, Java or C#. The listener, debugger and inspector are your friends! To help in debugging, the following features were added to CL-SOAP. The global variable cl-soap:*debug-stream* is the main toggle to enable debugging. When NIL, debugging is disabled. Otherwise, set it to some stream where you want debugging output to be written to. For example, in a listener, do (setf *debug-stream* *standard-output*). This will result in the outgoing and incoming literal XML being written to that stream. Furthermore, on each call, two more globals will be assigned: cl-soap:*last-soap-call-xml* and cl-soap:*last-soap-result-xml* will contain the LXML DOM representation of the XML of the outgoing SOAP call envelope and of the incoming SOAP result envelope respectively. Since this is a DOM representation, it is actually equal to what CL-SOAP produced before handing it off to S-XML to be rendered and to what the S-XML parser produced (so it is already an interpretation) respectively. A little convenience function called (cl-soap:report-soap-call) will pretty print these last two variables.

When reporting problems with CL-SOAP, please include a listener transcript produced with debugging enabled, with a full backtrace (in LispWorks issue a :bb for example) and a call to (report-soap-call). Also, if you want the CL-SOAP team or community to be able to help you, it will help enormeously if the service that you are calling is available on the internet.

Next Phase(s) (Future)

Port to other Common Lisp implementations.
Test and (im)prove compatibility with other SOAP implementations and applications.
Implement server side SOAP (document model).
Define WSDL in Lisp (and autogenerate it).
Implement more of WSDL and XSD.
Implement more of the SOAP RPC model and encoding, both for client and server.

Technical Notes

This project depends on an XML parser. The S-XML parser ( http://common-lisp.net/project/s-xml) has been extended to support some necessary features (namespaces for now). The code for these additions to S-XML has not yet been released, and is only available in the CVS repository. Some documentation of the XML Namespace feature in S-XML can be found in this mailing list message.

HTTP client and server code will be abstracted out and be made pluggable as to avoid unnecessary dependencies on other (larger) projects. For now, a simple HTTP client has been added to the source code.

Organizational Notes

The project lead for CL-SOAP is Sven Van Caekenberghe ( http://homepage.mac.com/svc ). Initial financial backing will be provided by Memetrics Pty Limited, Australia ( http://www.memetrics.com ) and Beta Nine BVBA, Belgium ( http://www.betanine.be ). Initial development was done by Sven Van Caekenberghe (Beta Nine) with testing by Alain Picard (Memetrics).

$Id: index.html,v 1.11 2005/10/09 08:34:43 scaekenberghe Exp $