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
.
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.
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 aSOAP-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),internal_namespace
(optional; default = "") a string with the `internal' namespace (xmlns:internal_namespace
)
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 this 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)
It encapsulates the call ofencode
anddecode
over a connection to an HTTP server, thus the arguments are passed to theencode
function and the results received from thedecode
function. It receives a table with the following fields:url
a string with the URL of the service (the protocol should behttp
orhttps
, which requires the load of theclient.https
module),soapaction
a string with the value of theSOAPAction
header,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),internal_namespace
(optional; default = "") a string with the `internal' namespace (xmlns:internal_namespace
)
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.