ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 9.0
Moderate update since 9.0 release.
8.2 version

A SOAP 1.1 API for Allegro CL

This document contains the following sections:

1.0 Preface
2.0 Introduction
3.0 A Simple Client Example
4.0 Components of the API
5.0 Element Definition
6.0 Type Definition
   6.1 Built-in Schema Types
7.0 Making a Client Call
8.0 SOAP Server Components
   8.1 The SOAP Network Server
   8.2 Exporting Methods
   8.3 Controlling Access to Methods
   8.4 Defining SOAP Methods
9.0 Programming Notes
   9.1 Multiple Threads
   9.2 Connector Class Hierarchy
   9.3 When things go wrong - debugging SOAP interfaces
   9.4 I18N Issues
10.0 WSDL Support
   10.1 Limitations in WSDL support
   10.2 WSDL Functions and Variables
   10.3 Namespaces and Packages
      10.3.1 Some important namespaces and packages
      10.3.2 Namespace Definition Operators
      10.3.3 Deducing the namespaces used in a WSDL file
   10.4 Mapping SOAP Structures to CLOS classes
      10.4.1 Generated Classes
      10.4.2 Generated Accessors
      10.4.3 Generated Constructors, Decoders, and Encoders
      10.4.4 Call Wrapper Methods
      10.4.5 Mapping SOAP Names to Lisp Names
   10.5 How to generate a SOAP client interface from a WSDL definition
      10.5.1 Combining Several WSDL Definitions in one Lisp Image
   10.6 Customizing Generated Code
11.0 Headers
12.0 Faults and Errors
13.0 Index


1.0 Preface

An update released in late February, 2006, makes minor changes and corrections to the update to 7.0 made earlier in the month and to the SOAP released with 8.0. One documentation correction should be noted: the default for the :nillable option (to operators like soap-message-client) is :ignore (making it compatible with earlier versions). The earlier documentation update incorrectly said the default was :accept.

This document describes an implementation of the Allegro CL SOAP API. There are still pieces of the Allegro CL/SOAP implementation to be completed. These will be released when they are ready.

The Implementation Plan for the Allegro/SOAP API is as follows.



2.0 Introduction

The Allegro CL SOAP module requires the SAX parser (:sax) and the AllegroServe (:aserve) modules. These modules are loaded automatically when the SOAP module is loaded.

You load the SOAP API into a running lisp with the following call to require:

(require :soap)

All the symbols in the SOAP API are exported from the net.xmp.soap package.

There is a SOAP client example in examples/soap/soapex.cl. There is a SOAP server example in examples/soap/soapval1.cl.

The letters xmp stand for XML Message Protocol. The XMP component implements a separately documented API that is used as a basis for the SOAP implementation and for other XML-based message protocols such as XMLRPC.

Users may find it more convenient to try the SOAP examples in a Modern (case-sensitive) Allegro CL image. Since case in SOAP symbols is significant, SOAP symbols typically have mixed case print names. Modern mode handles mixed case names without special effort. If you use an ANSI (case-insensitive) Allegro CL image, SOAP symbols need to be wrapped in vertical bar escapes (as is done in the Simple Example just below) in order to preserve their mixed-case print names.

There is another example in the file [Allegro directory]/examples/soap/bignum-server.cl.



3.0 A Simple Client Example

This simple example shows how to access a public SOAP server that returns currency conversion rates. (See also the file examples/soap/soapex.cl.)

This example accesses an external public SOAP server which was available at the time this document was written. This specific example may not produce the described result at other times and places.

The symbols in the "urn:xmethods-CurrencyExchange" namespace are exported from a Lisp package created for this purpose.


(require :soap)
(use-package :net.xmp.soap)

;;  This form ensures that XSD is a nickname of the NET.XMP.SCHEMA
;;  package:
(defpackage :net.xmp.schema (:use) (:nicknames :xs :xsd))

(defpackage :conv (:use) (:export "getRate"))

We define a function to send the message and decode the reply:

(defun convert (&optional (country1 "Canada") (country2 "USA"))
  (let ((conn (soap-message-client 
         :lisp-package :keyword
                :url "http://services.xmethods.net:80/soap")))
    (call-soap-method
     conn
     '(:element
       conv:|getRate|
       (:complex (:seq (:element "country1" xsd:|string|)
                       (:element "country2" xsd:|string|)
                       )
                :action ""
                :namespaces
                (nil (:conv "tns" "urn:xmethods-CurrencyExchange"))
                ))
     :|country1| country1 :|country2| country2
     )))

The main element of the message is defined (in line) as a complex type composed of a sequence of two elements "country1" and "country2". The content of each of these elements is declared to be a string. The information needed to create the element definitions must be obtained from the server documentation, often in the form of a WSDL file.

We try the function (we got the response indicated when this example was run but this is an external service and it may not work as indicated when you try it, either because of a temporary glitch or a permanent problem or change):

cl-user(4): (convert)
(conv::getRateResponse (:Result 0.8188))
nil

The result message is returned as a nested list of association lists where element name is the key and element content is the value.



4.0 Components of the API

The client API encodes Lisp data into a SOAP message and transmits the encoded HTTP message to the server. The reply from the server is another HTTP message that is decoded into Lisp data returned to the caller. SOAP messages may be exchanges with the HTTP protocol, or with the HTTPS protocol when SSL security is needed. We use the term HTTP protocol in this document to refer to both.

The server API defines Lisp functions that are called when specified messages are sent to the server. The messages arrive as encoded HTTP text and the value returned by the function is sent as an encoded HTTP reply message.

The XML elements in both outgoing and incoming messages must be defined in order to specify the required encoding and decoding behaviors.



5.0 Element Definition

An element definition specifies how an element should be encoded in a message to a server and how it can be decoded in a reply message.

An element definition can appear as a component in a Lisp list structure that describes a compound XML element:

element-def -> (:element elt-name-spec type-spec [:nillable t])

The nillable option, when non-nil, adds the "xsd:nillable='true'" attribute to the element.

An element definition can also be created with a call to define-soap-element:


define-soap-element

Generic Function

Package: net.xmp.soap

Arguments: conn elt-name-spec type-spec &rest def-options &key (redef :warn) nillable &allow-other-keys

After a call to define-soap-element, any of the names listed in the elt-name-spec may be used to denote the defined element.

The conn argument may be nil but can also be used to define behavior specific to a particular class of connections.

The elt-name-spec argument specifies one or more names by which the element can be identified. It is described below.

The type-spec argument may be the name of a separately defined SOAP type, the name of a built-in SOAP type or an anonymous type definition as defined in the next section. When type-spec is nil, the named definition is removed.

The redef option controls the behavior when a definition already exists. The possible values are:

The nillable option, when non-nil, marks the element as nillable. When an element is nillable, instances of the element may appear in a document with an empty content and a property "xsi:nil='true'" - in this case, treat the element as if it were not there.

When the element definition is output to a WSDL Schema definition, the element is tagged with the attribute "xsd:nillable='true'".

Additional keyword arguments are saved as options in the element definition.


An elt-name-spec is defined as follows:

elt-name-spec -> symbol | string 
              -> ( { symbol | string | (:any-case string) }... )

When a SOAP message is created, the first (or only) name in elt-name-spec determines the name included in the message. The components of an elt-name-spec are:

string --> unqualified QName
symbol --> 1. If the symbol-package of the symbol has been 
                 associated with a namespace
	        AND
	         the namespace is included in the current context,
	        THEN
	         the qualified QName is included in the message.
	  2. OTHERWISE the symbol name is included as an unqualified QName.
(:any-case string) --> treated like string above

When a SOAP message is decoded, any one of the names in the elt-name-spec is accepted as a name for this element.

string --> accept any string= QName in any namespace
symbol --> accept the EQ symbol
(:any-case string) --> accept any string-equal QName in any namespace


6.0 Type Definition

A type definition specifies the structure, content and attributes of an XML element. A type definition also specifies the encoding from Lisp to XML and the decoding from XML to Lisp.

A type definition can appear as a component in a Lisp list structure that describes a compound XML element:

type-def -> (:simple simple-type-spec simple-option... )
         -> (:array type-spec array-option... )
         -> (:complex complex-def complex-option... )

A type definition can also be created with a call to define-soap-type:


define-soap-type

Function

Package: net.xmp.soap

Arguments: conn name type-def &key (redef :warn) &allow-other-keys

Once defined, a type name may be used in other element or type definitions. When type-def is nil, the named definition is removed.

Additional keyword arguments are saved as options in the element definition.


simple-type-spec -> nil | type-name
       type-spec -> type-name | type-def 

 complex-def -> (collector complex-part ...)
   collector -> :seq    ;; zero or one of each part in specified sequence
             -> :seq*   ;; zero or more of each part in specified sequence
             -> :seq+   ;; one or more of each part in specified sequence
             -> :seq1   ;; exactly one of each part in specified sequence
             -> :set    ;; zero or one of each part in any sequence
             -> :set*  
             -> :set+  
             -> :set1  
             -> :or     ;; exactly one of the parts

The components of :seq :seq* :seq1 and :seq+ must be ordered as specified.

The components of :set :set* :set1 and :set+ may appear in any order.

When a complex element is encoded, the sub-elements are always encoded in the order listed in the definition.

complex-part -> element-spec | complex-def
element-spec -> element-name | (:any} | element-def

When a complex-part denotes a sequence of elements the sequence is spliced into the sequence containing the complex-part.

Sub-element definitions enter only through an element-def with a :complex or :array type-def.

Options on :complex type-def:

Options on any type-def:

Option Name Possible Values Description
:namespaces The name of a namespace map or a list containing an explicit namespace map. This option may be present on any element. The default-urn is encoded as the "xmlns=" attribute in the element and the other components are encoded as "xmlns:prefix=" attributes. Namespace definitions are inherited by nested sub-elements, and obey the namespace scoping and masking conventions of XML.

Symbols in the specified Lisp packages are encoded as qualified QName strings with the appropriate prefix.

:attributes A property list This option may be present on any element. When present, this option is encoded as a sequence of attributes "property-name=property-value".
:must-understand nil or non-nil This option is recognized only on the type-def of a top-level element sent as a Header element in a message. If non-nil then a "mustUnderstand" attribute with value "1" is included. If nil, then a "mustUnderstand" attribute with value "0" is included.
:encoding URLlist A string consisting of one or more URLs separated by spaces. Sent as the SOAP-ENV:encodingStyle attribute in the element.
:computed-attributes function-name The named function is called with two arguments (conn element-name) and is expected to return a property-list of the form (attr-name value ...) to be added to the attributes of the element.

When encoding a mesage sent with call-soap-method, the function is called in the dynamic environment of the call to call-soap-method. When encoding a message returned from a server method, there is no dynamic environment relevant to the application. When encoding a message with soap-encode-object, the function is called in the dynamic environment of the call to soap-encode-object. (Use soap-encode-object when computing a method return if dynamic environment is relevant.)

:send-type nil, t, or a string or symbol that names a Schema type This option may be present on any element. A non-nil value specifie that the "xsi:type" attribute should be added to the element instance in the SOAP message.

If the value of the :send-type option is t, then the type of the element must be a named type; the name of the element type is sent as the value of the "xsi:type" attribute.

If the value of the :send-type option is a string or a symbol other than t, then the value of the option is sent as the value of the "xsi:type" attribute.

If the value of the :send-type option is nil, then the "xsi:type" attribute is omitted from the outgoing message.

If the option is not specified, then the behavior is controlled by the value of the :send-type initarg to soap-message-client or soap-message-server.

Options on :array type-def:

Option Name Possible Values Description
:length A single integer or a list of integers This option specifies the dimensions of an array. A single integer denotes a 1-dimensional array of that length. A list of n integers denotes an n-dimensional array.
:send-atype A type name or a string of the form "type[]" or "type[15,17]". Send a enc:|arrayType| attribute with type-name as the value.
:send-asize nil, a number, some other value, t If non-nil, include an array size in arrayType. If the value is a number, send that number. If value is another non-nil value, then the length of the data determines the actual dimension sent in the message. If this option is non-nil, then the :send-atype option must not include any dimension values, i.e. in a form such as "type[15,17]". A list of integers should send that list as dimensions but that is NOT IMPLEMENTED.
:array-item A list like ([array-item-prop-name array-item-prop-val] ...) This option provides additional detail about how an array should be encoded. The possibilities for array-item-prop-name and array-item-prop-val are:
array-item-prop-name:   array-item-prop-val:

   :element                element-spec
   :send-type              boolean
   :attributes             property-list

   :argument               arg-spec
                    
                             This option specifies how array 
                             elements are passed to the encoding 
                             functions.  The argument is a list 
                             of element data items as follows:

                             arg-spec:              data item:

                             :element-and-arg       (element-spec data)
                             :type-and-arg          (type-spec data)
                             :attributes-and-arg    (property-list data)
                             :arg-only              data
                             nil                    data

6.1 Built-in Schema Types

The package qualifier xsd is a nickname for the net.xml.schema package. You must have evaluated (defpackage :net.xmp.schema (:use) (:nicknames :xs :xsd)) in order for the nickname to be valid. Otherwise, replace xsd with net.xmp.schema in the lists below.

The package qualifier enc is a nickname for the net.xml.soap.encoding package. You must have evaluated (defpackage :net.xmp.soap.encoding (:use) (:nicknames :enc)) in order for the nickname to be valid. Otherwise, replace enc with net.xmp.soap.encoding in the lists below.

The following Schema and SOAP Encoding types have definitions built into the SOAP module.

         Schema and
        SOAP Encoding        Decoded to            Encoded from
           Type              Lisp type              Lisp type 

      enc:|QName| 
      xsd:|QName|              symbol                  symbol

     enc:|decimal|
     xsd:|decimal|         integer or ratio            number

       enc:|long|
       xsd:|long|              integer                 number in range

  enc:|unsignedLong|
  xsd:|unsignedLong|           integer                 number in range

       enc:|int|
       xsd:|int|               integer                 number in range

   enc:|unsignedInt|
   xsd:|unsignedInt|           integer                 number in range

     enc:|integer|
     xsd:|integer|             integer                 number

  enc:|nonPositiveInteger|
  xsd:|nonPositiveInteger|     integer                 number in range

  enc:|nonNegativeInteger|
  xsd:|nonNegativeInteger|     integer                 number in range

  enc:|negativeInteger|
  xsd:|negativeInteger|        integer                 number in range

  enc:|positiveInteger|
  xsd:|positiveInteger|        integer                 number in range

       enc:|short|
       xsd:|short|             integer                 number in range

       enc:|byte| 
       xsd:|byte|              integer                 number in range

  enc:|unsignedShort|
  xsd:|unsignedShort|          integer                 number in range

  enc:|unsignedByte|
  xsd:|unsignedByte|           integer                 number in range

   enc:|boolean|
   xsd:|boolean|              t or nil                    any

      enc:|float| 
      xsd:|float|             double-float                 number

      enc:|double| 
      xsd:|double|            double-float                 number

    enc:|base64|
   enc:|base64Binary|
   xsd:|base64Binary|          string                      string

All the following types are decoded to a Lisp string and any Lisp value is encoded to a string in the outgoing message:

  enc:|string| enc:|duration| enc:|dateTime| enc:|time| enc:|date|
  enc:|gYearMonth| enc:|gYear| enc:|gMonthDay| enc:|gDay|
  enc:|gMonth| enc:|anyURI| enc:|NOTATION| enc:|token|
  enc:|language| enc:|IDREFS| enc:|ENTITIES| enc:|NMTOKEN|
  enc:|NMTOKENS| enc:|Name| enc:|NCName| enc:|ID| enc:|IDREF|
  enc:|ENTITY| enc:|normalizedString| xsd:|normalizedString|
  xsd:|duration| xsd:|dateTime| xsd:|time| xsd:|date|
  xsd:|gYearMonth| xsd:|gYear| xsd:|gMonthDay| xsd:|gDay|
  xsd:|gMonth| xsd:|anyURI| xsd:|NOTATION| xsd:|token|
  xsd:|language| xsd:|Name| xsd:|NMTOKEN| xsd:|NCName|
  xsd:|NMTOKENS| xsd:|ID| xsd:|IDREF| xsd:|ENTITY| xsd:|IDREFS|
  xsd:|ENTITIES|

  xsd:|string|


7.0 Making a Client Call

To make a client call, an application must create a connection instance with a call to soap-message-client.

A SOAP service available via HTTP is located with a URI that has several components:

A SOAP service that requires HTTPS is simply accessed with a URL that starts with "https://".

Within the HTTP request that carries the SOAP message there are HTTP headers that can be treated as attributes of the HTTP request. The soapAction header may be used by a specific SOAP server to recognize or to dispatch a message.

The entire pattern used to identify a SOAP method to be called consists of these components:


soap-message-client

Function

Package: net.xmp.soap

Arguments: &rest options

The options (keywords) and their values are (note that a value must be supplied for :url):

The following keyword options have defaults which suffice in most normal situations, but different values may be specified in special situations:



call-soap-method

Generic Function

Package: net.xmp.soap

Arguments: conn method &rest args

The conn argument is an instance of soap-client-connector.

The method argument determines the form of the SOAP message, and the remaining arguments (args) supply the data for the content of the message.

The method argument may be a string or symbol that denotes a SOAP element defined with define-soap-element. In this case, the Schema type of the element determines how the remaining arguments are interpreted. The table below shows the possible cases. The top-level element in the message is the element specified in the method argument. The contained sub-elements are built from the remaining arguments.

The method argument may be a list containing an explicit element definition, In this case, again, the type of the element determines how the remaining arguments are interpreted. The table below shows the possible cases. The top-level element in the message is the element specified in the method argument. The contained sub-elements are built from the remaining arguments.

The method argument may also be a symbol that denotes a complex SOAP type defined with define-soap-type, or a list containing an explicit type-def. In this case, the specified type determines how the remaining arguments are interpreted. The table below shows the possible cases. The top-level elements in the SOAP message are the immediate components of the complex type.

Type in method argument

Suitable Lisp Value

:complex name value ... where each name occurs as a top-level element in the complex def.
:array A sequence of items, each suitable as an array element.
:simple A single value or a sequence of values.

The outgoing message includes any headers that have been added to the connector with soap-add-header (described below).

The function returns two values, the contents of the SOAP Body element, and a list of SOAP Header elements. The form of the body contents depends on the value of the :body-form option. If the option is :one, then the value is an LXML representation of the one and only element in the SOAP Body element. If the option is :many, then the value is a list of LXML forms that represent all the elements in the SOAP Body element.

If the call returns a SOAP Fault, then an error of type soap-client-fault or soap-server-fault is signaled.

Examples

Example 1

In this example, we call a method with one argument declared as a simple element containing a string value. We use strings for all the element names because the server does not expect qualified XML names.

(define-soap-element nil "simpleStructReturnTest"
  '(:complex (:seq (:element "myNumber" (:simple enc:|int|)))))

In the call to call-soap-method, the method argument is "simpleStructReturnTest". The remaining arguments are "myNumber", the name of the one element in the "simpleStructReturnTest" message; and 123, the value or content of the element.

Example 2

In this example, the SOAP method expects one argument declared as a complex element with 3 sub-elements.

;;  This example cannot be simply cut and pasted into a running 
;;  Lisp because the server for the service is imaginary. 
;;  Instead, this example is intended to show what
;;  a call might look like.
(define-soap-element nil "easyStructTest"
  '(:complex
    (:seq
     (:element
      "stooges"
      (:complex
       (:set
	(:element "moe" enc:|int|)
	(:element "larry" enc:|int|)
	(:element "curly" enc:|int|)))))))

(call-soap-method client "easyStructTest" "stooges" (list "moe" 1 "larry" 2 "curly" 3))

In the call to call-soap-method, the method argument is "easyStructTest". The remaining arguments are "stooges", the name of the one element in the "easyStructTest" message; and the list (list "moe" 1 "larry" 2 "curly" 3), the value or content of the element. The value in this case is a list because the "stooges" element has a complex content that consists of several elements. The list provides the names and values of the sub-elements.

Example 3

In this example, the SOAP method expects one argument declared as an array of elements. The Lisp argument corresponding to the "myArray" element is a list of strings. Each string in the list is encoded as an array element with the default element name "item".

;;  This example cannot be simply cut and pasted into a running 
;;  Lisp because the server for the service is imaginary. 
;;  Instead, this example is intended to show what
;;  a call might look like.
(define-soap-element nil "moderateSizeArrayCheck"
  '(:complex (:seq (:element "myArray" (:array xsd:|string|)))))

(call-soap-method client "myArray" (list "a" "b" "c" "d"))

To specify more precisely the layout of an array we could say

;;  This example cannot be simply cut and pasted into a running 
;;  Lisp because the server for the service is imaginary. 
;;  Instead, this example is intended to show what
;;  a call might look like.
(define-soap-element nil "moderateSizeArrayCheck"
  '(:complex (:seq (:element "myArray" (:array xsd:|ur-type|
                                               :array-item
                                               (:element "myArrayElement"
                                                :send-type t
                                                :argument :type-and-arg))))))

In this case each array element in Lisp must be specified as a list where the first element is the SOAP type of the encoding and the second is the Lisp value to be encoded. Each array element will be encoded as an element named "myArrayElement" and the type will be encoded as a xsd:|type| attribute. (xsd is a nickname for the net.xml.schema package. You must have evaluated (defpackage :net.xml.schema (:use) (:nicknames :xsd :xs)) for the nickname to be valid. Otherwise replace xsd with net.xml.schema in the example below.)

The method argument in this case is "moderateSizeArrayCheck". The remaining arguments are "myArray", the name of the one element in the "moderateSizeArrayCheck" message; and the list ((:xsd:|string| "a") (xsd:|int| 17)), which represents the two array elements. Each element in the list is represented by a list of the type and the value of the element.

Example 4

If the SOAP message must be composed of several top-level elements, then the method argument would be of the form:

  '(:complex (:seq element1 element2 element3))

and the remaining arguments would be

   'element1 data-for-element1 'element2 data-for-element2 
   'element3 data-for-element3

The format of each of the data arguments is determined by the type of the corresponding element.




8.0 SOAP Server Components

A SOAP server exports methods that may be called from remote clients through a network interface. The network interface in this implementation is an AllegroServe HTTP server. A method is exported by specifying a SOAP element pattern and a Lisp function. When the specified message is received by the network server, the Lisp function is called. The arguments to the Lisp function are the decoded sub-elements of the message. The result returned by the Lisp function is encoded and sent as the reply message.


8.1 The SOAP Network Server

A SOAP network interface is established with a call to soap-message-server.


soap-message-server

Function

Package: net.xmp.soap

Arguments: &key start enable publish class name service-name url port-name binding-name action lisp-package message-dns base-dns must-understand decode-flag encoding actor trim-whitespace body-form send-type nillable message-init &allow-other-keys

The function returns an instance of soap-server-connector. This instance is an argument to most of the other API functions.

The arguments are:

All other arguments are passed as initargs in a call to make-instance. Arguments recognized for the class soap-aserve-server-string-in-out-connector include:

The keyword arguments xml-leader, xml-encoding, http-method, http-protocol, content-type, http-agent, and :http-headers are described under soap-message-client.

If the SOAP server must use the HTTPS protocol with clients, then the start argument must include the :ssl and maybe the :ssl-password options (see aserve/aserve.html).



enable-soap-server

Generic Function

Package: net.xmp.soap

Arguments: server &key &allow-other-keys

This method enables the server to respond to SOAP method calls. The HTTP server is not affected by this call.



disable-soap-server

Generic Function

Package: net.xmp.soap

Arguments: server &key &allow-other-keys

This method disables the server for SOAP method calls. The HTTP server is not affected by this call.



start-soap-server

Function

Package: net.xmp.soap

Arguments: server &key new start enable &allow-other-keys

Start the HTTP server for this SOAP server. If new is non-nil, create a new HTTP server If start argument is specified, it overrides the start argument in call to soap-message-server If enable is non-nil, enable the soap server.



stop-soap-server

Function

Package: net.xmp.soap

Arguments: server &key disable &allow-other-keys

Stop the HTTP server for this SOAP server. If disable is non-nil disable the SOAP server as well.



8.2 Exporting Methods

A method must be exported to make it available to remote clients through the network server.


soap-export-method

Generic Function

Package: net.xmp.soap

Arguments: conn name signature &key lisp-name (enable t) return help action ordered exact &allow-other-keys

This function defines how a Lisp function will be invoked when a SOAP message arrives at the server. The arguments to the Lisp function are the names and content of the sub-elements in the message.

The arguments to soap-export-method are:



8.3 Controlling Access to Methods

The Lisp function associated with a SOAP message is called with the soap-invoke-method generic function. The SOAP API includes a method specialized on soap-server-connector. This method simply calls apply. Applications can add additional restrictions on how and when the function is called by implementing a more specific method on a sub-class of soap-server-connector.


soap-invoke-method

Generic Function

Package: net.xmp.soap

Arguments: server name arg-list &key headers

This function is called to invoke the Lisp function associated with a SOAP message. The default primary method simply calls apply. User methods can be defined for sub-classes of soap-server-connector to enforce more restrictive access rules.

The server argument is a fresh copy of a soap-server-connector instance. The name argument is the name of the Lisp function associated with the SOAP message. The arg-list argument is a list of arguments for the Lisp function; this is an alternating list of element names and element content values.

The headers argument is a list of LXML structures that represent the SOAP header elements that were included in the incoming message. The default method ignores these.

This function normally returns one value which is encoded as the content of the reply message. If zero values are returned, then a SOAP client fault with fault string "Call refused" is returned as the reply. Values other than the first are ignored.

An :around method specialized on soap-server-connector binds the variable *soap-server*. If more specific :around methods are defined, the body of these methods will not see this binding.



8.4 Defining SOAP Methods

The Lisp function defined as the SOAP method body is called with an &rest argument that consists of an alternating list of element names and element content values.

If the element names are Lisp keywords, the function may be defined with keyword arguments, otherwise the function must extract argument values by some other means such as getf.

When the incoming SOAP message body consists of multiple elements, only the first element is used to dispatch the method call. A list of body elements is obtained with the function soap-message-body.

If a method needs to return multiple body elements, the method return must be defined by a type-spec or a type-name that defines a sequence type. The value returned by the method must be a list of values suitable for encoding into that type.

Note that the returned value specified in soap-export-method may be an element name or a type name. If a type name is intended, then there must not be an element defined by the same name.

Named element content in message:

Lisp argument to method:

simple type corresponding Lisp value
complex type an association list in which the keys are sub-element names. The function soap-sub-element-content should be used to extract the content of a sub-element.
array type a Lisp array of t, each array element is the element content of the array elements in the message

*soap-server*

Variable

Package: net.xmp.soap

During the execution of a SOAP method call, this variable is bound to a copy of the server instance that received the message with the method call.



soap-message-body

Generic Function

Package: net.xmp.soap

Arguments: conn

When conn is an instance of soap-connector, this accessor method returns a list of all the body elements in the SOAP message.


The following accessor methods return the corresponding components of the incoming SOAP message. They take an instance of soap-server-connector as their argument.


soap-server-message-method

Generic Function

Package: net.xmp.soap

Arguments: conn

Accesses the method component of the incoming SOAP message associated with conn, which must be a soap-server-connector.



soap-server-message-return

Generic Function

Package: net.xmp.soap

Arguments: conn

Accesses the return component of the incoming SOAP message associated with conn, which must be a soap-server-connector.



soap-server-message-signature

Generic Function

Package: net.xmp.soap

Arguments: conn

Accesses the signature component of the incoming SOAP message associated with conn, which must be a soap-server-connector.



soap-server-message-action

Generic Function

Package: net.xmp.soap

Arguments: conn

Accesses the action component of the incoming SOAP message associated with conn, which must be a soap-server-connector.


Some convenience functions for writing method bodies:


soap-sub-element-content

Function

Package: net.xmp.soap

Arguments: element-item pattern &rest more-patterns

Use of this function is deprecated. Use soap-result-part instead.

This function is used to extract the sub-element content from an argument to a SOAP method. The sub-element-name must be the name of an immediate sub-element of the argument.

If the sub-element is a simple element, the value is a Lisp atom that represents the value of the element. If the sub-element is a complex element, the value is a Lisp association list that can be decomposed with additional calls to soap-sub-element-content.



soap-alist-to-plist

Function

Package: net.xmp.soap

Arguments: element-alist &optional recursive

Translate an association list into a property list. This is useful when turning an argument into a reply.



soap-encode-object

Generic Function

Package: net.xmp.soap

Arguments: conn name type-spec data

This function returns an instance of soap-element that contains an encoded form of the data argument using the type-spec to control the encoding. If the name argument is the name of an element previously defined with define-soap-element, then type-spec may be nil; in that case the definition of the element is used.

Once a value is encoded as a soap-element instance, it is not affected by other element or type specifications that may be applied to the value. This function may be used to specify the encoding of SOAP array elements when a uniform encoding rule cannot be specified.

The conn argument may be nil or a soap-connector instance. If nil, we use the value of *soap-server*; thus the first argument may be nil in the body of a SOAP server method.



soap-version

Function

Package: net.xmp.soap

Arguments: &optional v1 v2 v3 error-p

In its simplest form, with no arguments, this function returns a string containing the current version information.

If the first argument is t or a stream, the version string is written to the stream (t indicating *terminal-io*).

If the first argument is an integer, the function acts as a predicate that compares the integer arguments to the current version. If v2 or v3 are omitted, they default to zero.



soap-result-part

Generic Function

Package: net.xmp.soap

Arguments: conn result name &rest more-names

When the conn argument is a soap-connector instance, the primary method extracts the named components from the result returned by call-soap-method.

The result argument should be the value returned by call-soap-method, an intermediate result returned by soap-result-pair, the list returned by soap-message-body, or a top-level element in the list returned by soap-message-body.

(See the note in the description of soap-result-pair about the eq'ness of suitable arguments to soap-result-pair and the return value of soap-result-pair.)

name may be nil to specify that the top-level element name in result is ignored. If not nil, name must be a string or symbol that is matched to the top-level element name in result or an integer that simply selects the sub-element by index.

more-names may be a list of nil, string, symbol or integer. Each item in the list is matched to the next level of nested sub-structure in result.

If the specified sub-element is found, the value returned is the sub-element content. Otherwise, the returned value is nil.

If multiRef references need to be followed, conn must be the soap-connector instance which received the result being examined. The table of reference definitions is saved in the soap-connector instance when the SOAP message is decoded.



soap-result-string

Generic Function

Package: net.xmp.soap

Arguments: conn result name &rest more-names

Like soap-result-part, but returns a single string if result is a list of strings.



soap-result-only

Generic Function

Package: net.xmp.soap

Arguments: conn result error-p name &rest more-names

Like soap-result-part, but behavior is controlled by error-p argument if the component is not found. The values of error-p can be:



soap-result-typed

Generic Function

Package: net.xmp.soap

Arguments: conn result type-spec error-p name &rest more-names

Like soap-result-only, but additional type conversions or tests may be done based on type-spec argument.

Current implementation looks for xsd:string only.



soap-result-pair

Generic Function

Package: net.xmp.soap

Arguments: conn result name &rest more-names

Like soap-result-part, but returns the cons that begins with the last named sub-element. This result is a suitable argument to soap-get-attributes and soap-get-attribute, or subsequent calls to soap-result-*.

Note that if x is a suitable argument to soap-result-pair, then (eq x (soap-result-pair conn x nil)) is always true. Thus to descend into the sub-elements of a result, the sub-element is passed as the second name in the argument list. The first name in the list must be nil or the name of the element represented by the result argument.



soap-get-attributes

Generic Function

Package: net.xmp.soap

Arguments: conn pair

pair is a SOAP message element as returned by call-soap-method or as extracted with soap-message-body or soap-result-pair.

Value is nil or property list of (name value ...) where both name and value are strings.



soap-get-attribute

Generic Function

Package: net.xmp.soap

Arguments: conn pair name &optional default

pair is a SOAP message element as returned by call-soap-method or as extracted with soap-message-body or soap-result-pair.

name may be a string to match any attribute namespace or a symbol for exact match.

Value is nil or value of attribute. If the attribute is not found, return the default value.




9.0 Programming Notes


9.1 Multiple Threads

A client connector instance should be used serially only. Only one thread should access the connector for the entire duration of a message round-trip.

When a server responds to an incoming message, a copy of the server connector instance is cloned for the duration of the message. The variable *soap-server* is bound in the thread that calls the Lisp function exported to handle the message. Message handling programs called by the server must take care to deal with shared resources with appropriate interlocks.


9.2 Connector Class Hierarchy

The complete class hierarchy for sub-classes of soap-connector includes all the following classes:

   soap-connector

   soap-client-connector
   soap-server-connector

   soap-string-out-connector
   soap-string-in-connector
   soap-string-in-out-connector
   
   soap-client-string-out-connector
   soap-client-string-in-connector
   soap-client-string-in-out-connector

   soap-server-string-out-connector
   soap-server-string-in-connector
   soap-server-string-in-out-connector

   soap-aserve-connector

   soap-aserve-client-connector
   soap-aserve-server-connector

   soap-aserve-string-out-connector
   soap-aserve-string-in-connector
   soap-aserve-string-in-out-connector
   
   soap-aserve-client-string-out-connector
   soap-aserve-client-string-in-connector
   soap-aserve-client-string-in-out-connector

   soap-aserve-server-string-out-connector
   soap-aserve-server-string-in-connector
   soap-aserve-server-string-in-out-connector

Methods in the API and internals methods are specialized on the least-specific method in this hierarchy, but only the classes

  soap-aserve-client-string-in-out-connector
  soap-aserve-server-string-in-out-connector

are actually instantiated in an application using this API. Thus, in order to provide behavior specific to a given application the programmer must create a sub-class of one or both of the above classes.

The following are accessors for soap-connector. Values are used by encode-wsdl-file.


soap-port-name

Generic Function

Package: net.xmp.soap

Arguments: soap-connector

Returns the port name.



soap-binding-name

Generic Function

Package: net.xmp.soap

Arguments: soap-connector

Returns the binding name.



soap-service-name

Generic Function

Package: net.xmp.soap

Arguments: soap-connector

Returns the service name.



9.3 When things go wrong - debugging SOAP interfaces

Sometimes, when a connection does not seem to be working, it is useful to see the actual XML message strings passed between client and server.

The variable *soap-client-debug* can be set to a non-nil value to cause a printout of the HTTP headers and the XML message text sent by the client. When the reply arrives, the HTTP headers and XML message text are printed as well.

If the variable is set to :stop, then the message is not sent to the server.

The variable *soap-server-debug* can be set to a non-nil value to cause a printout of the HTTP headers and the XML message text received by the server and sent as a reply.

The debug flag can also be associated with a single client or server connection by using the soap-debug keyword initarg in the call to soap-message-client or soap-message-server.

If the variables *soap-client-debug* or *soap-server-debug* are stack bound, the stack bound value takes precedence over the slot or the global value.

The formal definitions of these two variables are given below.

When creating a new SOAP server, it may be helpful to exercise the server code with sample data without writing a client program. There are two (internal) functions that may help:


*soap-server-debug*

Variable

Package: net.xmp.soap

When non-nil, causes the printing out of the HTTP headers and the XML message text received by the server and sent as a reply.



*soap-client-debug*

Variable

Package: net.xmp.soap

When non-nil, causes the printing out of the HTTP headers and the XML message text sent by the client. When the reply arrives, the HTTP headers and XML message text are printed as well.



9.4 I18N Issues

Character encoding is specified with the :xml-encoding option to soap-message-client and soap-message-server.

The Content-Type is specified with the :content-type option to soap-message-client and soap-message-server. The character encoding specified in the XML header must be consistent with the Content-Type specified in the HTTP header. Because of the wide range of possible encoding and conent types, it is impossible to give specific recoomendations for the settings of these parameters.

If additional HTTP headers are needed, they can be specified in the :http-headers option to soap-message-client and soap-message-server.



10.0 WSDL Support

Many web services are defined in an XML dialect known as WSDL. The WSDL definition specifies the element content and data types in the SOAP messages received and sent by the service.

Given a web service WSDL definition, we can generate the Lisp functions and definitions needed to send messages to the service and to receive and decode the replies.

We can also generate the server interface and skeleton definitions for the server methods. The only additional programming needed is to supply the body of the server functions.


10.1 Limitations in WSDL support

This early release of WSDL support implements most of the WSDL 1.1 specification. Any omissions are the result of oversight or for the benefit of an earlier release.

The known omissions include:


10.2 WSDL Functions and Variables

The packages net.xmp.wsdl and net.xmp.wsdl.soap hold the symbols in the WSDL namespaces.


wsdl-file-connector

Class

Package: net.xmp.soap

An instance of this class is created when a WSDL file is decoded.



wsdl-file-connector

Function

Package: net.xmp.soap

[Earlier releases of this document incorrently described a function of this name. There is no such function.]



decode-wsdl-file

Function

Package: net.xmp.soap

Arguments: file &key namespaces base lisp-package class init xml-syntax include import verbose

This function parses a file containing a WSDL specification and returns a wsdl-file-connector instance containing the parsed data.

The lisp-package argument is a package specifier. Unqualified WSDL names will be interned in this package.

The namespaces keyword argument may be nil, :decode, or a namespace map. The default is :decode.

The base keyword argument may be nil or a namespace map. The default is :wsdl1-prefix.

If a package-name occurs as an ex-ns-part, any unknown namespaces in the file are mapped to this package. Only one package-name should occur in the extended-namespace-spec.

If the form (:prefix symbol-or-string) occurs as an ex-ns-part, each unknown namespace is mapped to a different package named "prefixNN". Only one such form should occur in the extended-namespace-spec.

The ex-ns-tail component specifies how the standard namespaces should be identified in the file. If the package-name or :prefix forms occur as an ex-ns-part, or if the tail is :guess, then decode-wsdl-namespaces is called.

When the namespaces keyword argument is :decode, decode-wsdl-namespaces is called with the map argument set to base and if the namespaces can be decoded, the resulting namespace map is used. Otherwise an error is signaled.

The value of the class argument should be the name of a sub-class of wsdl-file-connector. The default is wsdl-file-connector.

The value of the init argument should be a list of initargs added to the call of make-instance of the class.

The value of the xml-syntax keyword argument can be :strict or nil (or any other value). A value of :strict forces strict interpretation of Schema definitions. Any other value relaxes XML Schema syntax to allow many ill-formed constructs that we have encountered in published Schema definitions. The default is nil.

The include keyword argument specifies how XML schema <include> elements should be handled in the WSDL Schema. A value of nil (the default) causes <include> elements to be ignored; this behavior may leave many types and elements undefined. A non-nil atomic value is assumed to be a function of two arguments: the wsdl-file-connector instance, and the value of the "schemaLocation" attribute in the <include> element. If the non-nil value is of the form (op . rest), op is assumed to be a function of 2+n arguments where the first two arguments are as above, and the remaining arguments are the items in rest. In both cases, the value returned by the function must be nil or a string. A nil indicates that the <include> element should be ignored. A string is assumed to be the XML content to be parsed as the included Schema.

The import keyword argument specifies how XML schema <import> elements should be handled in the WSDL Schema. The values and handling are like include.

If the value of the verbose keyword argument is non-nil, progress messages are printed. The default is nil.



decode-wsdl-string

Function

Package: net.xmp.soap

Arguments: string &key namespaces base lisp-package class init xml-syntax

This function is like decode-wsdl-file but the input is from the string argument instead of a file.



decode-wsdl-at-uri

Function

Package: net.xmp.soap

Arguments: uri &key namespaces base lisp-package class init xml-syntax

This function is like decode-wsdl-file but the input is from the specified uri argument instead of a file.



decode-wsdl-source

Function

Package: net.xmp.soap

Arguments: &key uri string file namespaces base lisp-package class init xml-syntax stream

This is the most general form of decode-wsdl-* functions. Only one of the keyword arguments uri, string, file, and stream should be specified. The specified argument determines the input source.

Those arguments are interpreted in this order:

  1. If uri is non-nil, the data at the URI is retrieved and treated as the WDSL source string.
  2. If string is non-nil, it is treated as the WDSL source string.
  3. If file is non-nil, the content of the file is treated as the WDSL source string.
  4. If stream is non-nil, it is assumed to be positioned at the first character of the WDSL source string.

If all the source arguments are nil, an error is signaled.

The other keyword arguments are like decode-wsdl-file with the following exception: the value of the namespaces argument cannot be :decode when the source is a stream. This is because when namespaces is :decode, the source is parsed twice, once to find all the namespace declarations, and again to decode the content. If the source is a stream, we do not attempt to reposition the stream; therefore only one pass is allowed.



soap-make-fault

Function

Package: net.xmp.soap

Arguments: server code string &key factor detail sub-code

This function creates an encoded fault instance.

The server argument must be an instance of a SOAP connector.

The code argument may be a keyword to specify one of the pre-defined SOAP Fault codes in the table below, or it must be a symbol in a namespace package.

   :server           "SOAP-ENV:Server"
   :client           "SOAP-ENV:Client"
   :version-mismatch "SOAP-ENV:VersionMismatch"
   :must-understand  "SOAP-ENV:MustUnderstand"

The sub-code if specified it is appended to the fault code and separated with a dot.

The string argument is encoded as the "faultstring" element content.

The factor argument is encoded as the "faultfactor" element content.

The detail argument is encoded as the "detail" element content.

If a SOAP method implementation throws an encoded fault instance, then the SOAP reply message consists of the contained fault message. If a SOAP method implementation throws any other value, it is encoded as a "Client.LispError" fault.



soap-new-environment

Function

Package: net.xmp.soap

Arguments:

This function resets the SOAP environment by removing all namespace, namespace map, element and type definitions from the Lisp environment and restores the initial definitions included in the SOAP module.



encode-wsdl-file

Function

Package: net.xmp.soap

Arguments: file &key namespaces base servers target target-package name (if-exists :supersede) types elements

Create a file with WSDL definitions of the specified servers. The definitions include exported methods and associated data types.

The arguments are:

The types and elements arguments may be used to add element and type declarations that are not mentioned in any SOAP messages, or with a null services argument to generate a WSDL output without any service definitions.



wsdl-service-names

Generic Function

Package: net.xmp.soap

Arguments: conn &optional and-ports

Returns a list of the names of all the services defined in the wsdl file. The order of the names is the order of the definitions in the file. If more than one service is defined, the index in the list may be used as the service argument to make-client-interface.

The optional and-ports argument determines the level of detail included in the returned value. If it is omitted or nil, the result will look like (service-name ... ). If it is t, the result will look like ((service-name port-name ...) ... ). If it is :verbose, the result will look like ((service-name (port-name binding url) ...) ... ).



make-client-interface

Generic Function

Package: net.xmp.soap

Arguments: conn service destination &key eval (lisp-package :keyword) (file-package :user) empty-element null-element expand-singleton prefix suffix port if-missing-package map compose text-file class-file post-file object-class action message-dns body-form message-method-prefix connect-class built-in-arrays defined-arrays sequence response redef object-access generate-comments

This function generates a source code file with type definitions, element definitions and function definitions derived from the WSDL definition in the conn argument. The client interface is intended to be a fully functional set of functions to access the web service described in the WSDL.

Some web service definitions may change over time, and therefore the interface code may need to be generated repeatedly. The many arguments to make-client-interface attempt to capture all the variations that may be needed to generate usable code so that the generated code will require little if any hand modifications.

The conn argument must be a wsdl-file-connector instance as returned by decode-wsdl-file.

The service argument can be

The destination argument can be

The keyword arguments

In order to define the generated interface, the generated interface file must be compiled and loaded.

To review, these arguments control the generated code:

Possible name conflicts

When generating Lisp code from a WSDL definition, there may be name conflicts or possible name conflicts when several different spellings are mapped to the same Lisp symbol. These conflicts are signaled as warnings of the form:

Possible name conflicts: (key (symbol from...)...)

where each from component is a string or a list of strings used to derive the name of the symbol.



make-server-interface

Generic Function

Package: net.xmp.soap

Arguments: conn service destination &key eval (lisp-package :keyword) (file-package :user) empty-element null-element expand-singleton prefix suffix action message-dns port if-missing-package map response redef object-access generate-comments

This method analyzes the data in the WSDL file to generate type definitions and server function skeletons.

Most of the arguments are as for make-client-interface. The eval argument, as in make-client-interface, is ignored.

The prefix argument is the leading component of the generated names of server functions. The argument must be a string or a symbol. The default is :server-.

The action argument is the default soapAction expected for all incoming messages.

The message-dns argument is used to initialize the namespace definitions of the server instance.

In order to define the generated interface, the generated interface file must be compiled and loaded.



wsdl-include-file

Function

Package: net.xmp.soap

Arguments: conn file-name

This function may be used as the value of the import or include keyword arguments to decode-wsdl-file. The returned value is nil or the contents of the specified file.



wsdl-include-url

Function

Package: net.xmp.soap

Arguments: conn url-string

This function may be used as the value of the import or include keyword arguments to decode-wsdl-file. The returned value is nil or the contents of the specified url.



10.3 Namespaces and Packages

The meaning of XML, SOAP, and WSDL texts depends in part on the correct identification of various namespaces.

XML namespaces are identified by a URI and URIs are considered distinct if they differ in any character position. The SOAP module considers two URIs equivalent if they only differ in a final slash character.


10.3.1 Some important namespaces and packages

XML Schema definition namespace

XML Schema instance namespace

SOAP message envelope namespace:

SOAP message encoding namespace

WSDL definition namespace

WSDL SOAP binding namespace


10.3.2 Namespace Definition Operators

A namespace declaration is a list of the form (package prefix uri).

One package may be linked to several URIs. One URI may be linked to several packages. The most recent definition is the first to be seen in a search. The primary-p argument to various operators allows some reordering.

One advantage of making a global namespace definition is that the package name may be used to denote the mapping. Also the entry will be found if :all is in namespace map.

Here is a recursive specification of the namespace maps:

namespace-map -> symbol-name-of-namespace-map |
                 (default-namespace [namespace-entry]... [namespace-tail])
default-namespace -> nil        ;; no default specified,
                                      ;; inherit the current default or continue
                                      ;;    the search for a default specification
                   -> ""         ;; the default is to have no default at all
                                       ;;   blocks any inherited default
                                       ;;   and stops the search for a default
                   -> symbol     ;; package name of defined namespace
                   -> string     ;; search in order
                                       ;;   1. package name of defined namespace
                                       ;;   2. uri 
                   -> uri instance ;; uri
namespace-entry -> (package-name) | (package-name prefix) |
		     namespace-declaration | namespace-declaration-instance
		     symbol-name-of-namespace-map |
		     :all
		     :stop
namespace-tail -> nil | (package nil :any) | (string nil :prefix)

xmp-namespace-map

Class

Package: net.xmp.soap

The Lisp class of a namespace map object.



define-namespace-map

Function

Package: net.xmp.soap

Arguments: name &rest namespace-map-parts

This function returns a xmp-namespace-map instance.

The name argument may be nil, to define an anonymous namespace map. The namespace-map-parts argument may be nil to define an empty namespace map. If the list is not nil, it must begin with a default namespace specification. The general format of the list is

  default-namespace [namespace-entry]... [namespace-tail]

Where the default-namespace component may be

The namespace-entry and namespace-tail components are described in Section 10.3.2 Namespace Definition Operators.


Defined namespace-map keywords (read-only):

 :wsdl-namespaces ->  ( :wsdl1.2 :wsdl1.1 :soap )
	 This definition recognizes both the WSDL 1.1
	 and the  WSDL 1.2 namespaces, and uses the WSDL 1.2 
	 namespaces for output, since they appear first.

 :wsdl1-namespaces -> ( :wsdl1.1 :wsdl1.2 :soap1 )
	 This definition uses the WSDL 1.1 
	 namespaces for output, since it appears first.

 :soap -> ( :soap1.2 :soap1.1 :schema )
 :soap1 -> ( :soap1.1 :soap1.2 :schema )

 :soap1.1
 :soap1.2  
 :wsdl1.1  
 :wsdl1.2

 :schema -> ( :schema2001 :schema1999 )
 :schema1 -> ( :schema1999 :schema2001 )

 :schema1999 :schema2001 

 :wsdl-combine ->  ( :wsdl-namespaces :all (:wsdl-data nil :any) )
	 This definition searches the :wsdl-namespaces first,
	 then any globally declared namespaces.
	 This definition maps any unmatched namespaces to the
	 :wsdl-data package.

 :wsdl-keyword ->  ( :wsdl-namespaces :all (:keyword nil :any) )
	 This definition maps any unmatched namespaces to the
	 keyword package.

 :wsdl-prefix  ->  ( :wsdl-namespaces :all ("wsdl-" nil :prefix) )
	 This definition maps each unmatched namespace to a new
	 package with a name of the form "wsdl-nnn"

 :wsdl1-combine -> ( :wsdl1-namespaces :all (:wsdl-data nil :any) )
 :wsdl1-keyword -> ( :wsdl1-namespaces :all (:keyword nil :any) )
 :wsdl1-prefix  -> ( :wsdl1-namespaces :all ("wsdl-" nil :prefix) )

The current namespace environment is defined as the current nesting of namespace declarations. It consists of nested :namespaces options and/or xmlns attributes, the :message-dns slot specification, the :base-dns slot specification, and finally the namespace-tail entry.

During input decoding, when the server is decoding a request or a client is decoding a reply, or when decoding a wsdl file, "xmlns" attributes cause a search of the current namespace environment for an exact match on the URI. If a match cannot be found, an error is signalled. If a match is found, the XML name is interned in the corresponding Lisp package.

During output encoding, when the server is encoding a reply, or a client is encoding a request, or when encoding a wsdl file, create a top-level xmlns attribute from the first occurrence of each explicit namespace declaration in the namespace environment. A symbol in a package present in the current namespace environment is encoded as a qualified name.


xmp-namespace-declaration

Class

Package: net.xmp.soap

The Lisp class of a namespace declaration object.



define-namespace

Function

Package: net.xmp.soap

Arguments: package prefix uri &optional primary-p

This function stores a namespace definition that will be used in decoding or encoding SOAP messages. These definitions are created by explicit calls to this function or by mentions of namespaces in calls to define-namespace-map.

If the package and uri arguments are specified (that is, given a non-nil value), then a new namespace declaration object is created if it does not already exist.

If only the package or the uri argument is specified (that is, given a non-nil value), then find a matching namespace declaration object, if one exists.

If both package and uri are nil, then do nothing and return nil.

This function returns a xmp-namespace-declaration instance or nil.

The prefix argument is ignored when decoding SOAP messages. When encoding SOAP messages, only namespace definitions that have a non-nil prefix are used, definitions with a nil prefix are ignored and symbols in that package are encoded as unqualified names. The defined prefix is used in the xmlns declaration of the namespace. The prefixes mentioned in a specific XML context must be distinct or an error is signaled.



delete-namespace

Function

Package: net.xmp.soap

Arguments: package prefix uri

This function deletes any namespace declarations matching the arguments. Either package or uri must be non-nil, or no namespaces are deleted. If one is nil while the other is non-nil, then all namespaces with the non-nil component are deleted, that is, nil works as a wildcard when the other component is specified. Nothing will be deleted if only prefix is non-nil.


Namespace variables, no longer supported

In an earlier version, the following variables had namespace specifications as values. All these variables are removed and namespaces are determined by the namespace operators described above.


10.3.3 Deducing the namespaces used in a WSDL file

The function decode-wsdl-namespaces returns information about the namespaces mentioned in a WSDL definition and it can generate a namespace specification based on some heuristic rules.


decode-wsdl-namespaces

Function

Package: net.xmp.soap

Arguments: &key file string uri map show

This function returns 4 values:

  1. A namespace specification acceptable as the :namespaces argument
  2. A list of unrecognized URIs
  3. A list of missing namespaces
  4. A list of ambiguous namespaces

file should be a string containing the path to a file. string should be a string containing a WSDL definition. uri should be the uri where a WSDL definition may be found. Only one of the above arguments should appear.

The map argument specifies a namespace map that determines the namespace mapping strategy. The default is :wsdl1-prefix defined as (nil :wsdl1.1-namespaces :all ("wsdl-" nil :prefix)). This definition searches in this order:

  1. :wsdl1.1, :wsdl1.2, :soap1.1, :soap1.2, :schema2001, :schema1999
  2. all namespace maps defined with define-namespace-map
  3. all namespaces defined with define-namespace unmatched namespaces are assigned to a new package named "wsdl-NNN"

If the value of the show keyword argument is non-nil, it must be t or a stream. Then a readable version of the namespaces is printed to *standard-output* (when t) or to the stream.

When decode-wsdl-file is called with a namespaces argument of :decode, the function decode-wsdl-namespaces is called and if values 2 3 and 4 are nil the decode operation proceeds with the resulting namespace specification. If any of the values 2 3 or 4 are non-nil, the function signals an error.



10.4 Mapping SOAP Structures to CLOS classes

When the :object-class argument is specified to make-client-interface, a set of classes are generated from the type and element definitions in the WSDL file. Constructor and accessor functions are also generated, as well as object-oriented methods for calling SOAP methods.


soap-object-class

Class

Package: net.xmp.soap

Application may define a subclass with different slot values for class slots:



10.4.1 Generated Classes

Each complex type definition in the WSDL is mapped to a sub-class of the user-defined sub-class of soap-object-class. The Lisp name of the Schema type is also the name of the corresponding CLOS class.


10.4.2 Generated Accessors

The slot readers in the generated classes have names of the form

<reader-prefix from object-class><converted SOAP sub-element name>

The slot writers in the generated classes have names of the form

<writer-prefix from object-class><converted SOAP sub-element name>

The arguments to the slot writer are the standard CLOS writer arguments: new slot value, and instance.


10.4.3 Generated Constructors, Decoders, and Encoders

new-<converted SOAP type name> is an ordinary function with keyword arguments. The keyword argument names are the converted sub-element names of the complex type.

decode-<converted SOAP type name> is an ordinary function of one argument, the value returned by call-soap-method.

<prefix>encode is a generic function of one argument specialized on the soap-object-class of the SOAP complex type.


10.4.4 Call Wrapper Methods

These wrapper functions are generated when the :message-method-prefix option is non-nil.

  <message-method-prefix><converted SOAP message name>

The method takes positional arguments specialized on the SOAP structure classes defined for the corresponding message components.


10.4.5 Mapping SOAP Names to Lisp Names

The conversion of SOAP Schema names to Lisp symbols is controlled by the :convert argument to make-client-interface. Its value can be:


10.5 How to generate a SOAP client interface from a WSDL definition

In this section, we go through the steps needed to generate a client interface from a WSDL definition obtained from some outside source. We use the files AmazonS3.wsdl and AmazonS3.xsd as examples. The files were obtained from the web but copies are included in the Allegro CL distribution in examples/soap/ (included in an update released in early September, 2006).

(The following steps could be applied to the web version but the results may differ if the service definition has changed.)

In order to run the example, be sure that the SOAP module is laoded and that the :net.xmp.soap is used (otherwise package-qualify the symbols as necessary in the example code).

(require :soap)
(use-package :net.xmp.soap)

Step 1: Determine the Namespace Requirements

(soap-new-environment)
(decode-wsdl-namespaces :file "AmazonS3.wsdl" :map nil :show t)

The first expression is optional. It may be a good idea to evaluate this expression if this example is repeated in the same Lisp invocation or if other WSDL files have been tried. The effect is to discard all SOAP definitions and start with a clean environment.

The second expressions parses the WSDL file and reports on the namespaces mentioned in the file. The show argument prints a readable summary of this information:

     #|
     Namespace map:
       (nil 
        ("net.xmp.wsdl" "wsdl" "http://schemas.xmlsoap.org/wsdl/")
         ("net.xmp.wsdl.soap" "wsdl-soap"
          "http://schemas.xmlsoap.org/wsdl/soap/")
         ("net.xmp.schema" "xsd" "https://www.w3.org/2001/XMLSchema"))
     Other namespaces:
         "http://s3.amazonaws.com/doc/2006-03-01/")
     |#

The first section of the output labelled "Namespace map:" lists the namespaces that were recognized and are already mapped to Lisp packages because of built-in definitions or previous user definitions.

The next section labelled "Other namespaces:" lists the URLs of other namespaces mentioned in the WSDL. These will be mapped to generated packages by default, but it is good practice to define a fixed package for each namespace. This makes generated code more readable and gives consistent and comparable results from one run to the next.

Sometimes additional sections are listed to show ambiguous or unrecognizable namespaces. These situations may indicate an ill-formed WSDL. In most cases, if these sections appear customer service may need to intervene.

Step 2: Define Application Namespaces

In this example, there is one namespace specific to this application.

(define-namespace :aws "aws" "http://s3.amazonaws.com/doc/2006-03-01/")
(define-namespace-map :awsmap nil '(:aws))

The first expression defines one namespace. The second expression defines a namespace map which is used to hold all the namespaces in the configuration of an application.

Step 3: Decode the WSDL definition

(setf def 
    (decode-wsdl-file "AmazonS3.wsdl" :namespaces :awsmap :verbose t))

The above expression decodes the WSDL file and returns a wsdl-file-connector instance. We assign this to a variable since it will be needed in subsequent expressions.

; schemaLocation=AmazonS3.xsd was not included.

The above message indicates that something was not quite right during the decoding, but we forge ahead hoping for the best.

Step 4: First Pass at Client Interface

(make-client-interface def 0 t)

This expression generates a client definition for the first (zeroth) service definition in the previously decoded file. The generated code is directed to *standard-output*.

Error: Cannot determine message type in (...)
   - type may be defined in included Schema.

But we cannot generate code because there is some missing information.

Step 5: Decode the WSDL definition again

The included file appears to be necessary in order to decode and analyze the WSDL definition fully. We need to tell the decoder how to find the included text.

(setf def (decode-wsdl-file "AmazonS3.wsdl" :namespaces :awsmap
                            :verbose t :include 'wsdl-include-file))

The above expression specifies the function wsdl-include-file to map the schemaLocation attribute to a file in the local file system.

; schemaLocation=AmazonS3.xsd included with wsdl-include-file

This time the message confirms that a second Schema was included.

Step 6: Second Pass at Client Interface

(make-client-interface def 0 "a-client.cl")

This time, we direct the output of the generated code to a file. The returned value is a summary of the generated definitions.

     ((("Output in file:" :key :file) "a-client.cl")
      (("Defined functions:" :key defun)
       (client-18 "Send client message ListAllMyBuckets "
        aws:ListAllMyBuckets)
       (client-17 "Send client message ListBucket " aws:ListBucket)
       (client-25 "Send client message DeleteObject " aws:DeleteObject)
       (client-14 "Send client message PutObjectInline "
        aws:PutObjectInline)
       (client-1 "Send client message PutObject " aws:PutObject)
       (client-12 "Send client message GetObjectExtended "
        aws:GetObjectExtended)
       (client-5 "Send client message GetObject " aws:GetObject)
       (client-9 "Send client message SetBucketAccessControlPolicy "
        aws:SetBucketAccessControlPolicy)
       (client-8 "Send client message SetObjectAccessControlPolicy "
        aws:SetObjectAccessControlPolicy)
       ...)
      (("Defined SOAP elements:" :key define-soap-element)
       aws:ListAllMyBucketsResponse aws:ListAllMyBuckets
       aws:ListBucketResponse aws:ListBucket aws:DeleteObjectResponse
       aws:DeleteObject aws:PutObjectInlineResponse aws:PutObjectInline
       aws:PutObjectResponse ...)
      (("Defined SOAP types:" :key define-soap-type)
       aws:ListAllMyBucketsList aws:ListAllMyBucketsResult
       aws:ListAllMyBucketsEntry aws:ListBucketResult aws:ListEntry
       aws:PutObjectResult aws:GetObjectResult aws:AccessControlPolicy
       aws:AccessControlList ...)
      (("Defined packages:" :key defpackage) :keyword :common-lisp-user :aws
       #:aws #:common-lisp-user)
      (("Lisp package of generated file:" :key in-package)
       #:common-lisp-user)
      (("Other entries:" :key define-namespace-map) :client-namespaces)
      (("Other entries:" :key defvar) *client-service-url*))

Step 7: Try the Interface

In order to try the interface, we need to compile and load the generated code.

(load (compile-file "a-client.cl"))
(setf *soap-client-debug* :stop)
(client-7 :Bucket "bbb" :AWSAccessKeyId "id" :Timestamp 123)

The first expression compiles and loads the generated code. It is not necessary to compile, but the compiler does identify many problems in code before it is run.

The second expression informs the SOAP runtime to stop before actually sending a message to the server, and print a formatted version of the SOAP message for review.

Refine the Interface

At this point, the generated code may be tweaked in various ways by generating the code again with additional parameters to make-client-interface:


10.5.1 Combining Several WSDL Definitions in one Lisp Image

When several WSDL definitions must be combined into one Lisp image, there may be several issues that must be resolved before a working application is generated:

The distinct WSDL definitions may use identical names to denote distinct types or methods. This situation may be corrected by decoding the files into distinct Lisp packages and mapping namespaces appropriately. The prefix and suffix options may also be useful in keeping names distinct.

The distinct WSDL definitions may duplicate Schema elements by explicit repetition or by including identical definitions. The :redef argument to make-client-interface provides several strategies for handling this situation.


10.6 Customizing Generated Code


wsdl-generate-code

Generic Function

Package: net.xmp.soap

Arguments: conn mode info op &rest args

This method may be used to modify the code generated by make-client-interface and make-server-interface.

The default method specialized on (wsdl-file-connector t t t) simply emits the cons of op and args.

If the op argument is null and there is only exactly one element in args, then the entire form is that single element.

The method may return two values when it is called for a top-level form. In that case the second value may be a string or a list of strings. The strings are emitted as comments before the form.

An application may define a sub-class of wsdl-file-connector and some more specific methods to alter the generated code. The application class is specified in the call to decode-wsdl-file.

The method is called with the following arguments during code generation:

mode info operator comments
:client :top-level defun client message function
:client nil soap-message-client
:server :top-level defun new server function
:server :top-body defun method definition skeleton
:server nil soap-message-server
:object-class :top-level defclass
:object-new :top-level defun
:object-decoder :top-level defmethod
:object-encoder :top-level defmethod
:object-type :top-level defclass
:object-wrapper :top-level defmethod
:sever :method-body --- called to emit default comment "INSERT BODY HERE"


wsdl-post-process

Generic Function

Package: net.xmp.soap

Arguments: conn defs

This function is called after all the types, elements, and message functions have been generated, but not yet written to the output file. The built-in method is specialized on (t t) and does nothing.

The defs argument is a list of items of the form (form comment ...). The order of the items in the list is the order in which the forms will be written into the output file.

An application may add a primary or an :around method to manipulate the definitions or to add additional code to the output file.

To add a form to the output, call the function: wsdl-add-form with arguments conn form &rest comments.



wsdl-maybe-conflicts

Generic Function

Package: net.xmp.soap

Arguments: conn

The value returned by this function is one of the following:



wsdl-add-form

Generic Function

Package: net.xmp.soap

Arguments: conn form &rest comments

The form is added at the end of the code generated by make-client-interface or make-server-interface. If comments are specified, they must be strings. Comments are inserted before the form in the generated file.

Code can only be added at the end of the generated file. If it is necessary to modify code at the beginning of the file, it must be done by adding a wsdl-generate-code method that modifies one of the forms emitted at the beginning of the file.




11.0 Headers

If a client message must be sent with one or more SOAP header elements, the elements must be built with make-soap-header and saved in the connection instance created with soap-message-client. Every time a SOAP message is sent, the current collection of headers is included in the message as a single SOAP Header element.

If a SOAP server method must examine the content of SOAP header elements when handling a SOAP message, the accessor soap-message-headers may be used to extract the list of header elements.


make-soap-header

Generic Function

Package: net.xmp.soap

Arguments: conn element-spec &rest args

The arguments are as for call-soap-method, but instead of sending a message, this method returns an object of class soap-header which contains an encoded representation of the header element.

If the header element must have a "mustUnderstand" attribute, the attribute may be specified as a :must-understand option or included in the :attributes option of the element definition.



soap-add-header

Generic Function

Package: net.xmp.soap

Arguments: conn header &key after before reset

The header argument must be an instance of the class soap-header. The method adds the header to the list of headers that will be sent with the next message.

The before and after arguments may be nil or headers previously added.

If reset is non-nil, then any previously added headers are discarded.



soap-must-understand

Generic Function

Package: net.xmp.soap

Arguments: conn element-name

When a reply message is decoded, and a "mustUnderstand" attribute with value "1" is present, then this method is called.

The default method behavior depends on the setting of the :must-understand flag in the connection instance. The following settings produce the indicated behavior:



soap-message-headers

Generic Function

Package: net.xmp.soap

Arguments: conn

When conn is an instance of soap-connector, this accessor method returns a list of all the header elements in the SOAP message.




12.0 Faults and Errors

All the warnings and errors signalled by the SOAP module are described by the following hierarchy:

   xmp-warning hierarchy:

            simple-warning 
                   xmp-warning  
                             xmp-syntax
                             xmp-redefinition
                             soap-decode-warning
                                
   xmp-condition hierarchy: 

            error   
               xmp-condition
                     xmp-client-condition
                         soap-client-error
                              soap-client-fault
                     xmp-server-condition
                         soap-server-error
                              soap-server-fault
                     soap-mismatch
                     soap-must-understand


13.0 Index


Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.

ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 9.0
Moderate update since 9.0 release.
8.2 version