LuaSOAP: SOAP interface to the Lua programming language

LuaSOAP
SOAP interface for the Lua programming language

## Introduction

LuaSOAP is a Lua library to ease the use of SOAP. It enables a Lua program to:

- Encode and decode SOAP messages without having to deal directly with XML code
- Invoke remote Web Services without having to deal directly with SOAP messages

LuaSOAP provides a very simple API and an abstraction layer over XML avoiding manipulation of string representation of data structures.

LuaSOAP is based on LuaExpat and on Lua 5.1. The abstraction layer over HTTP depends on LuaSocket 2.0. An optional layer over HTTPS depends on LuaSec 0.4.

## Installation

LuaSOAP is a Lua library composed by a main module (`soap.lua`) and some extensions: `client.lua` and `server.lua`. The main module must be copied to your `package.path` and the other two files to a `soap` directory in your `package.path`.

LuaSOAP can also be installed via LuaRocks with the command `luarocks install luasoap`. You can check the available rocks at LuaRocks' main repository.

## LuaSOAP elements

LuaSOAP elements are always represented by Lua tables except strings. A LuaSOAP element is a table of the form defined by the Lua Object Model from the LuaExpat library. The table has the following characteristics:

- a special field called `tag` with the element's name;
- a special optional field called `attr` with the element's attributes (see next section);
- the element's children are stored at the array-part of the table. A child could be an ordinary string or a LuaSOAP element (a Lua table following these same rules).

#### Attributes

The special field `attr` is a Lua table that stores the LuaSOAP element's attributes as pairs <key>=<value>. To assure an order (if necessary), the sequence of keys should be placed at the array-part of that table.

This documentation provides a detailed example which shows some common use cases.

#### Escaping and special characters

Since LuaSOAP 3.0, the library took the responsibility to escape data inside LuaSOAP elements (`entries` field of soap envelope; see function soap.encode below). Therefore, XML special characters such as `<` and `>` are automatically converted to the corresponding XML entities (`&lt;` and `&gt;`, respectively).

This documentation provides examples which show some common use cases.

## Basic support

The module `soap` implements all basic support for encoding and decoding SOAP messages. There are two functions:

- `encode(args) => envelope`
  Builds a SOAP document containing a `SOAP-Envelope` element. It receives a table with the following fields:
  - `namespace` a string with an URI indicating the namespace (`xmlns`) atribute of the request,
  - `method` a string with the method's name,
  - `entries` an array (a table with numeric keys) of LuaSOAP elements,
  - `header` (optional) a table of headers (`soap:Header` element; a LuaSOAP element too),
  - `soapversion` (optional; default = 1.1) a number with the SOAP version (currently supported versions are 1.1 and 1.2),
  - `internal_namespace` (optional; default = "") a string with the `internal' namespace (`xmlns:internal_namespace`)
  The result is always a string containing the SOAP document.
  The function can raise errors in case the `args` table is mal formed.
- `decode (method_response) => namespace, method_name, elements`
  Disassembles a SOAP document into Lua objects. It receives a string containing the SOAP document. The results are: the namespace (string), the SOAP-element method's name (string) and a table with the contents of the SOAP Body. Each element of the `elements` table can be a string or a LuaSOAP element.

## Client side

The module `soap.client` implements a stand-alone client which works over HTTP and is based on LuaSocket 2.0. The following function is provided:

- `call (args) => namespace, method_name, elements`
  It encapsulates the call of `encode` and `decode` over a connection to an HTTP server, thus the arguments are passed to the `encode` function and the results received from the `decode` function. It receives a table with the following fields:
  - `url` a string with the URL of the service (the protocol should be `http` or `https`, which requires the load of LuaSec's `ssl.https` module),
  - `soapaction` a string with the value of the `SOAPAction` header,
  - `encoding` (optional; default = "") a string with the text encoding (usually `"utf-8"` or `"iso-8859-1"`),
  - other arguments to the `encode` function
  The results are the same as the `decode` function: the namespace (string), the SOAP-element method's name (string) and a table with the contents of the SOAP Body.

#### HTTPS and SOAP over other transport layers

LuaSOAP client module was designed to work over HTTP (via LuaSocket's `socket.http` module) and HTTPS (via LuaSec's `ssl.https` module). In fact, it could be used over other protocols since they provide LuaSocket's `socket.http.request` function.

The `soap.client.call` function inspects the URL to check what protocol the SOAP message is supposed to be transfered upon. Then, it looks for a function called `request` at the `soap.client.protocol` (where protocol is a table which has an entry called `request` which is a function with the same signature of LuaSocket's `socket.http.request`. Thus, the support fot HTTPS can be enabled by a program with the following lines:

    local soap_client = require"soap.client"
    soap_client.https = require"ssl.https"

By following this approach, one could extend LuaSOAP to use another protocol by implementing a function equivalent to LuaSocket's `socket.http.request` or LuaSec's `ssl.https.request`.

## References

Here is a list of related documentation:

- http://www.w3.org/XML/

$Id: manual.html,v 1.10 2009/08/10 19:04:40 tomas Exp $