SOAP interface for the Lua programming language

LuaSOAP

• Home
  • Overview
  • Status
  • Download
  • History
  • Credits
  • Contact us
• Manual
  • Introduction
  • Installation
  • SOAP elements
  • Basic support
    • encode
    • decode
  • Client side
    • call
  • References
• Examples
  • SOAP elements
  • Escaping example
  • Client example
• License

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. The file https.lua is an optional module which should be installed in a soap/client directory in your package.path.

LuaSOAP is also distributed via LuaRocks. There are two rocks: the main luasoap and the optional luasoap-https. You can check the available rocks in the main repository.

SOAP elements

SOAP elements are always represented by Lua tables except strings. A SOAP 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 SOAP element (a Lua table following these same rules).

Attributes

The special field attr is a Lua table that stores the SOAP 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.

Encoding and special characters

It is the programmer's responsibility to provide valid data to represent SOAP elements. Therefore, XML special characters such as < and > must be converted to the corresponding XML entities (< and >, respectively).

This documentation provides a detailed example which shows 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 SOAP elements,
  • header (optional) a table of headers (soap:Header element; a SOAP 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 SOAP 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 the client.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 others transport layers

An additional optional module soap.client.https provides the hability to send and receive SOAP messages over an HTTPS connection. There is no need to use another call function, since it is encapsulated into the client implementation. In fact, the call function inspects the url argument to check over what protocol the SOAP message should be transfered. This protocol should be supported through a function soap.client.protocol, where protocol is a function with the same signature of LuaSocket's http.request function. The soap.client.http is this exact function and the soap.client.https is LuaSec's https.request function which wraps LuaSocket's http.request over an HTTPS connection (this function is available since LuaSec version 0.4).

soap.client.https module depends of LuaSec.

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

References

Here is a list of related documentation:

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