A client that logs in to the system passes an authentication procedure. The resulting authentication defines the privileges to execute functions or accessing resources (authorization). The chapter AAAA (Authentication,Authorization,Auditing and Accounting) will introduce the several aspects covered by Wolframe besides data processing.

A client that passed authentication can send application server requests to the server. A request consists of a command name plus a structured content also called document. The server returns a single document to the presentation tier as answer. Many different programming/scripting languages are supported to define the input/output mapping between the layers. Wolframe introduces three concepts as data processing building blocks for handling the server requests:

The chapter data processing will describe these building blocks.

Installing the packages via repositories is usually the prefered way.

First install the repository file for the corresponding distribution (as example we choose Centos 6):

	cd /etc/yum.repos.d
	wget http://sourceforge.net/projects/wolframe/files/repositories/CentOS-6/wolframe.repo
				

You can list all available Wolframe packages with:

	yum search wolframe
				

You install the main Wolframe package with:

	yum install wolframe
				

You have to accept the signing key:

	Retrieving key from http://sourceforge.net/projects/wolframe/files/repositories/CentOS-6/repodata/repomd.xml.key
	Importing GPG key 0x9D404026:
	Userid: "home:wolframe_user OBS Project <home:wolframe_user@build.opensuse.org>"
	From  : http://sourceforge.net/projects/wolframe/files/repositories/CentOS-6/repodata/repomd.xml.key
	Is this ok [y/N]: y
				

You can start the service with:

	service wolframed start
				

respectively

	systemctl start wolframed
				

on newer Fedora systems.

Installing the packages via repositories is usually the prefered way.

Note: Some older versions of Ubuntu (like Ubuntu 12.04 LTS, 10.04 LTS or Debian 6) have problems to download the metadata files from Sourceforge. If you get messages like:

	W: Failed to fetch http://sourceforge.net/projects/wolframe/files/repositories/Ubuntu-12.04_LTS/Release.gpg  Got a single header line over 360 chars
	Err http://sourceforge.net  Packages               
			

then you have to download the binaries manually.

Add a new repository file /etc/apt/sources.list.d/wolframe.list which contains:

	deb http://sourceforge.net/projects/wolframe/files/repositories/Ubuntu-14.04_LTS/ /
				

(as example we choose Ubuntu 14.04).

Download the signing key:

	wget http://wolframe.net/Release.key
				

Verify that the key then add it with:

	apt-key add - < Release.key
				

Update the repository with:

	apt-get update
				

You can list all available Wolframe packages with:

	apt-cache search wolframe
				

You install the main Wolframe package with:

	apt-get install wolframe
				

To start the Wolframe service you have to edit the file /etc/default/wolframe and enable the wolframe daemon there:

	RUN=yes
				

You can start the service now with:

	service wolframed start
				

Currently installing the packages directly is the prefered way.

Note: This is currently not working perfectly and some steps have to be done manually.

First we add the Wolframe repository for the corresponding distribution (as example we choose OpenSUSE 13.1):

	zypper addrepo http://sourceforge.net/projects/wolframe/files/repositories/openSUSE-13.1/wolframe.repo
				

You may get the following error:

	/var/adm/mount/AP_0xmiyYP3/projects/wolframe/files/repositories/openSUSE-13.1/wolframe.repo: Line 1 is missing '=' sign
	Is it a .repo file? See http://en.opensuse.org/Standards/RepoInfo for details.
				

Try to download the repo file by hand and install it by hand:

	wget http://sourceforge.net/projects/wolframe/files/repositories/openSUSE-13.1/wolframe.repo
	zypper addrepo wolframe.repo
				

Now refresh your repositories with:

	zypper refresh
				

If you get the following message

	File 'repomd.xml' from repository 'Wolframe Project (openSUSE-13.1)' is unsigned, continue? [yes/no] (no): yes
				

the signing key could not be downloaded from SourceForge. Accept it in this case anyway.

If you get the following message

	File './repodata/ea7cb8d9a0caa2c3d8977919be124accdf55c6b8952ddee72f1b48f4decb0644-primary.xml.gz' not found on medium 'http://sourceforge.net/projects/wolframe/files/repositories/openSUSE-13.1/'

	Abort, retry, ignore? [a/r/i/? shows all options] (a): u^H
	Invalid answer ''. [a/r/i/? shows all options] (a): ?

	a - Skip retrieval of the file and abort current operation.
	r - Try to retrieve the file again.
	i - Skip retrieval of the file and try to continue with the operation without the file.
	u - Change current base URI and try retrieving the file again.

	[a/r/i/? shows all options] (a): u				
				

the Sourceforge redirect didn't work and you have to force the baseURL to be a SourceForge mirror like:

	New URI: http://freefr.dl.sourceforge.net/project/wolframe/repositories/openSUSE-13.1/
				

You can list all available Wolframe packages with:

	zypper se wolframe
	zypper se wolfclient
				

You install the main Wolframe package with:

	zypper install wolframe
				

You can start the service with:

	service wolframed start
				

respectively

	systemctl start wolframed
				

on newer openSUSE systems.

Wolframe is currently only available as two monolithic packages:

You can use the packages from http://sourceforge.net/projects/wolframe/files/wolframe-binaries/ directly.

First add the following section to /etc/pacman.conf:

	[wolframe]
	SigLevel = Optional DatabaseRequired
	Server = http://sourceforge.net/projects/wolframe/files/repositories/ArchLinux/$arch
				

Fetch and verify the sigining key, import and locally sign the key:

	wget http://wolframe.net/Release.key
	pacman-key --add Release.key
	pacman-key --lsign 9D404026
				

Alternatively you can also disable the verification of the signature of the database by removing 'DatabaseRequired' from the 'SigLevel' option.

Update the repository data with:

	pacman -Syy
				

You can list all available Wolframe packages with:

	pacman -Sl wolframe
				

You install the main Wolframe package with:

	pacman -S wolframe
				

You can start the service with:

	systemctl start wolframed
				

You can also customize your build by downloading the build files from the AUR at https://aur.archlinux.org/packages/?O=0&K=wolframe and customize them to your needs.

For instance:

	yaourt -G wolframe
	cd wolframe
	makepkg 
				

Wolframe is currently only available as two monolithic packages:

Download the package file (we picked 64-bit Slackware 14 for example):

	wget http://sourceforge.net/projects/wolframe/files/wolframe-binaries/0.0.3
/Slackware-14/x86_64/wolframe-0.0.3
-x86_64.tgz
				

You install the Wolframe package with:

	installpkg wolframe-0.0.3
-x86_64.tgz 
				

You can start the service with:

	/etc/rc.d/rc.wolframed start
				

For defining the backend to log to console (stderr), we have to configure a subsection stderr of the Logging section. For console logging we just can define the logging level with level. Example configuration:

Logging
{
    Stderr {
        Level INFO
    }
}

For defining the backend to log to a file, we have to configure a subsection LogFile of the Logging section. For logging to file we can define the logging level with Level and the file name with Filename. Example configuration:

Logging
{
    LogFile {
        Filename /var/log/wolframed.log
        Level NOTICE
    }
}

For defining the backend to log to syslog, we have to configure a subsection Syslog of the Logging section. For logging to syslog we can define the logging level with Level, the syslog facility with Facility and the identifier with Ident. Example configuration:

Logging
{
    Syslog {
        Ident wolframed
        Facility LOCAL2
        Level INFO
    }
}

On Windows we can also log to eventlog. For defining the backend to log to eventlog, we have to configure a subsection Eventlog of the Logging section. For logging to eventlog we can define the logging level with Level, the eventlog source with Source and the identifier with Name. Example configuration:

Logging
{
    Eventlog {
        Name Wolframe
        Source wolframed
        Level WARNING
    }
}

In order to use a Postgres database in Wolframe you have to configure the loading of the module mod_db_postgresql in the LoadModules section of your configuration. The addressed Postgres database server must be running and the database and the user configured must have been created before.

The configuration settings for PostgreSQL are splitted in two parts: The database configuration settings and the SSL configuration settings. The following three tables show the PostgreSQL database configuration settings, the PostgreSQL SSL configuration settings and the table with configurable SSL modes:

Here follows an example PostgreSQL database configuration:

Database
{
    PostgreSQL
    {
        Identifier        pgdb
        Host              localhost
        Port              5432
        Database          wolframe
        User              wolfusr
        Password          wolfpwd
        ConnectionTimeout 10
        Connections       40
        AcquireTimeout    10
    }
}

In order to use an Sqlite3 database in Wolframe you have to configure the loading of the module mod_db_sqlite3 in the LoadModules section of your configuration. The database file configured must have been created before.

The following table shows the configuration settings for a Sqlite3 database in Wolframe.

Here follows an example Sqlite3 database configuration:

Database
{
    SQLite
    {
        Identifier    sqlitedb
        File          sqlite.db
        ForeignKeys   yes
        Profiling     no
        Connections   3
        Extension     sqlite_module.so
    }
}

In order to use an Oracle database in Wolframe you have to configure the loading of the module mod_db_oracle in the LoadModules section of your configuration. The addressed Oracle database server must be running and the database and the user configured must have been created before.

The following table shows the Oracle database configuration settings:

Here follows an example Oracle database configuration:

Database
{
    Oracle
    {
        Identifier        oradb
        Host              localhost
        Port              1521
        Database          orcl
        User              wolfusr
        Password          wolfpwd
        Connections       10
        AcquireTimeout    10
    }
}

The command execution authorization is not implemented yet completely. The idea is to have programs that map authorization function calls to Wolframe function calls. The language to describe these programs is not yet defined. The mechanism to map the authorize requests to the function calls already exists. Authorization based on command execution will be a subject of the next release.

The Wolframe standard command handler is called directmap and named so in the configuration because it only declares a redirection of the commands to functions based on the document type and the command identifier specified by the client in the request.

The declarations of the Wolframe Standard Command Handler (directmap) are specified in a program source file with the extension '.dmap' that is declared in the configuration.

The following annotated configuration example declares (1) a program example.tdl written in the transaction definition language (TDL) to contain the function declarations that can be called by the command handler. It (2) declares the database with name pgdb to be used as the database for transactions. It (3) loads a description example.dmap that will declare the mappings of commands to the filters used and functions called. It (4) specifies the filter with name libxml2 to be used for documents of format XML and (5) the filter with name cjson to be used for documents of format JSON, if not specified else in example.dmap.

; Simple Data Processing Configuration Example
Processor
{
    ; Programs to load:
    Program example.tdl            ; (1) a program with functions (in TDL)
    Database pgdb                  ; (2) references transaction database

    ; Command handlers to load:
    Cmdhandler
    {
        Directmap                  ; the standard command handler
        {
            Program example.dmap   ; (3) description of command mappings

            Filter XML=libxml2     ; (4) std filter for XML document format
            Filter JSON=cjson      ; (5) std filter for JSON document format
        }
    }
}


		

The following source example could be one of the example.dmap in the configuration example introduced above. It defines two commands. The first one links a command "insert" with document type "Customer" as content to a transaction function "doInsertCustomer". The content is validated automatically against a form named "Customer" if not explicitly defined else. The command has no result except that it succeeds or fails. The second example command links a command "get" with a document type "Employee" to a function "doSelectEmployee". The input is not validated and the transaction output is validated and mapped through the form "Employee".

COMMAND insert Customer CALL doInsertCustomer;
COMMAND get Employee SKIP CALL doSelectEmployee RETURN Employee;


		

A command map description file like our example shown consists of instructions started with COMMAND and terminated by semicolon ';'. The first argument after COMMAND is the name of the command followed by the name of the document type of the input document. The name of the command is optional. If not specified the first argument after COMMAND names the input document type.

COMMAND Document;

				

COMMAND insert Document;

				

COMMAND insert Document CALL doInsertDocument;

				

COMMAND process Document RETURN Document;

				

COMMAND process Document CALL doProcessDocument RETURN Document;

				

COMMAND process Document 
    CALL doProcessDocument
        RETURN Document { root = 'doc', schema = 'bla.com/schema' };

			

COMMAND process Document SKIP
	CALL doProcessDocument RETURN Document;

				

COMMAND process Document
	CALL doProcessDocument RETURN SKIP Document;

				

COMMAND process Document
	CALL doProcessDocument RETURN SKIP Document {root='list'};

				

COMMAND process Document
	CALL doProcessDocument
	RETURN SKIP {standalone='yes',root='list'};

				

COMMAND process Document FILTER INPUT myXsltInputFilter
    CALL doProcessDocument RETURN Document;

				

COMMAND insert UserData CONTEXT { uname = UserName }
    CALL doInsertUserData;

				

COMMAND ( process Document )
    FILTER INPUT myXsltInputFilter CALL doProcessDocument
    RETURN Document;

				

For the description of transactions Wolframe provides the transaction definition language (TDL) introduced here. Wolframe transactions in TDL are defined as functions in a transactional context. This means that whatever is executed in a transaction function belongs to a database transaction. The transaction commit is executed implicitely on function completion. Errors or a denied authorization or a failing audit operation lead to an abort of the database transaction.

A TDL transaction function takes a structure as input and returns a structure as output. The Wolframe database interface defines a transaction as object where the input is passed to as a structure and the output is fetched from it as a structure.

TDL is a language to describe the building of transaction input and the building of the result structure from the database output. It defines a transaction as a sequence of instructions on multiple data. An instruction is either described as a single embedded database command in the language of the underlying database or a TDL subroutine call working on multiple data.

Working on multiple data means that the instruction is executed for every item of its input set. This set can consist of the set of results of a previous instruction or a selection of the input of the transaction function. A "for each" selector defines the input set as part of the command.

Each instruction result can be declared as being part of the transaction result structure. The language has no flow control based on state variables other than input and results of previous commands and is therefore not a general purpose programming language. But because of this, the processing and termination of the program is absolutely predictable.

As possibility to convert the input data before passing it to the database, the transaction definition language defines a preprocessing section where globally defined Wolframe functions can be called for the selected input. To build an output structure that cannot be modeled with a language without control structures and recursion, TDL provides the possibility to define a function as filter for postprocessing of the result of the transaction function. This way it is for example possible to return a tree structure as TDL function result.

The TDL is - as most SQL databases - case insensitive. For clearness and better readability TDL keywords are written in uppercase here. We recommend in general to use uppercase letters for TDL keywords. It makes the source more readable.

TDL is compiled to a code for a virtual machine. Setting the log level to DATA will print the symbolic representation of the code as log output. The internals of the virtual machine will be discussed in a different chapter of this book.

Each TDL program source referenced has to be declared in the Processor section of the configuration with program <sourcefile>.

A TDL program consists of subroutine declarations and exported transaction function declarations. Subroutines have the same structure as transaction function blocks but without pre- and postprocessing and authorization method declarations.

			SUBROUTINE <name> ( <parameter name list> )
			DATABASE <list of database names>
			BEGIN
				...<instructions>...
			END
			

	
			TRANSACTION <name>
			AUTHORIZE ( <auth-function>, <auth-resource> )
			DATABASE <list of database names>
			RESULT FILTER <post-filter-name>
			PREPROC
				...<preprocessing instructions>...
			ENDPROC
			BEGIN
				...<instructions>...
			END
			AUDIT CRITICAL <funcname> ( ...<parameter>... )

			

	
			TRANSACTION <name>
			BEGIN
				...<instructions>...
			END
			

				
TRANSACTION insertCustomerAddresses
BEGIN
    DO SELECT id FROM Customer
        WHERE name = $(customer/name);
    FOREACH /customer/address
        DO INSERT INTO Address (id,address)
        VALUES ($RESULT.id, $(address));
END

				

				
TRANSACTION insertPersonTerms
PREPROC
    FOREACH //address/* INTO normalized
        DO normalizeStructureElements(.);
    FOREACH //id INTO normalized
        DO normalizeNumber(.);
ENDPROC
BEGIN
    DO UNIQUE SELECT id FROM Person
        WHERE name = $(person/name);
    FOREACH //normalized DO
        INSERT INTO SearchTerm (id, value)
        VALUES ($RESULT.id, $(.));
END

				

			
TRANSACTION selectPerson
PREPROC
    FOREACH /person/name
        INTO normalized DO normalizeName( . );
    FOREACH /person
        INTO citycode DO getCityCode( city );
ENDPROC
BEGIN
    FOREACH person
        DO INSERT INTO Person (Name,NormalizedName,CityCode)
            VALUES ($(name),$(name/normalized),$(citycode));
END


			

			DO SELECT name FROM Company
			    WHERE id = $RESULT.id
			DO SELECT name FROM Company
			    WHERE id = $id
			

			FOREACH RESULT
			    DO SELECT name FROM Company
			        WHERE id = $RESULT.id
			FOREACH RESULT
			    DO SELECT name FROM Company
			        WHERE id = $id
			

			FOREACH ATTRIBUTES
			    DO SELECT name FROM Company
			        WHERE id = $ATTRIBUTES.id
			FOREACH ATTRIBUTES
			    DO SELECT name FROM Company
			        WHERE id = $id
			

TRANSACTION selectDevices
BEGIN
    DO SELECT id FROM DevIdMap
        WHERE name = $(device/name);
    KEEP AS dev;
    FOREACH dev
        DO SELECT key,name,registration
            FROM Devices WHERE sid=$id;
END


				

SUBROUTINE selectDevice( id)
BEGIN
    INTO device
        DO SELECT name FROM DevIdMap
            WHERE id = $PARAM.id;
END

TRANSACTION selectDevices
BEGIN
    DO selectDevice( id );
END

				

				
TRANSACTION selectCustomerAddress
BEGIN
    DO NONEMPTY UNIQUE SELECT id FROM Customer
        WHERE name = $(customer/name);
    INTO address
        DO NONEMPTY SELECT street,city,country
            FROM Address WHERE id = $id;
END


				

			
TRANSACTION insertCustomer
BEGIN
    DO INSERT INTO Customer (name) VALUES ($(name));
    ON ERROR CONSTRAINT
        HINT "Customers must have a unique name.";
END

			

			unique constaint violation in transaction 'insertCustomer'
			-- Customers must have a unique name.
			

				INTO <resulttag>
				BEGIN
					...<instruction list>...
				END
			

			
TRANSACTION doPrintX
BEGIN
  INTO person
  BEGIN
    INTO name PRINT 'jussi';
    INTO id PRINT '1';
  END
END


			

			
TRANSACTION getCustomer
DATABASE DB1,DBtest
BEGIN
    INTO customer
        DO SELECT * FROM CustomerData
            WHERE ID=$(id);
END


			

			
DATABASE DB1,DBtest

TRANSACTION getCustomer
BEGIN
    INTO customer DO SELECT *
        FROM CustomerData WHERE ID=$(id);
END


			

			
TEMPLATE <TreeTable>
SUBROUTINE insertIntoTree( parentID)
BEGIN
    DO NONEMPTY UNIQUE SELECT rgt FROM TreeTable
        WHERE ID = $PARAM.parentID;
    DO UPDATE TreeTable
        SET rgt = rgt + 2 WHERE rgt >= $1;
    DO UPDATE TreeTable
        SET lft = lft + 2 WHERE lft > $1;
    DO INSERT INTO TreeTable (parentID, lft, rgt)
        VALUES ( $PARAM.parentID, $1, $1+1);
    DO NONEMPTY UNIQUE SELECT ID AS "ID" from TreeTable
        WHERE lft = $1;
END

TRANSACTION addTag
BEGIN
    DO insertIntoTree<TagTable>( $(parentID) )
    DO UPDATE TagTable
        SET name=$(name),description=$(description)
            WHERE ID=$RESULT.id;
END


			

			
INCLUDE treeOperations

TRANSACTION addTag
BEGIN
    DO insertIntoTree<TagTable>( $(parentID) )
    DO UPDATE TagTable
        SET name=$(name),description=$(description)
            WHERE ID=$RESULT.id;
END



			

				
TRANSACTION doInsertUser
BEGIN
	DO INSERT INTO Users (name) values ($(name));
	DO SELECT id FROM Users WHERE name = $(name);
END
AUDIT CRITICAL auditUserInsert( $RESULT.id, $(name) )



				

				
TRANSACTION doInsertUser
BEGIN
	DO INSERT INTO Users (name) values ($(name));
	DO SELECT id FROM Users WHERE name = $(name);
END
AUDIT CRITICAL auditUserInsert WITH
BEGIN
	INTO id PRINT $RESULT.id;
	INTO name PRINT $(name);
END



				

You can write functions for the logic tier of Wolframe in languages based on .NET (http://www.microsoft.com/net) like for example C# and VB.NET. Because .NET based libraries can only be called by Wolframe as a compiled and not as an interpreted language, you have to build a .NET assembly out of a group of function implementations before using it. There are further restrictions on a .NET implementation. We will discuss all of them, so that you should be able to write and configure .NET assemblies for using in Wolframe on your own after reading this chapter.

For enabling .NET you have to declare the loading of the module 'mod_command_dotnet' in the main section of the server configuration file.

		
    Module mod_command_dotnet

		

For the configuration of the .NET assemblies to be loaded, see section 'Configure .NET Modules'.

Wolframe itself is not a .NET application. Therefore it has to call .NET functions via COM/.NET interop interface of a hosted CLR (Common Language Runtime). To make functions written in .NET callable by Wolframe, the following steps have to be performed:

		
using System;
using System.Runtime.InteropServices;

[ComVisible(true)]
[Guid("390E047F-36FD-4F23-8CE8-3A4C24B33AD3")]
public struct Address
{
    [MarshalAs(UnmanagedType.BStr)] public string street;
    [MarshalAs(UnmanagedType.BStr)] public string country;
};

[ComVisible(true)]
public interface FunctionInterface
{
    [ComVisible(true)]  Address GetAddress( [MarshalAs(UnmanagedType.BStr)] string street, [MarshalAs(UnmanagedType.BStr)] string country);
}

[ComVisible(true)]
[ClassInterface(ClassInterfaceType.None)]
public class Functions : FunctionInterface
{
    public Address GetAddress([MarshalAs(UnmanagedType.BStr)] string street, [MarshalAs(UnmanagedType.BStr)] string country)
    {
        Address rt = new Address();
        rt.street = street;
        rt.country = country;
        return rt;
    }
}


		

Wolframe functions in .NET calling globally defined Wolframe functions need to declare the processor provider interface as an additional parameter. The processor provider interface is defined as follows (example C#):

	
namespace Wolframe
{
    public interface ProcProvider
    {
        object call(
        [In] string funcname,
        [In] object argument,
        [In] Guid resulttype);
    }
}

	

To use it we have to include the reference to the assembly WolframeProcessorProvider.DLL.

The interface defined there has a method call taking 3 arguments: The name of the function to call, the object to pass as argument and the Guid of the object type to return. The returned object will be created with help of the registered Guid and can be casted to the type with this Guid.

The following example shows the usage of a Wolframe.ProcProvider call. The method GetUserObject is declared as Wolframe function requiring the processor provider context as additional argument and taking one object of type User as argument named usr. The example function implementation redirects the call to the global Wolframe function named GetAddress returning an object of type Address (example C#):

	
public Address GetUserAddress(
            Wolframe.ProcProvider provider,
            User usr
) {
    Address rt = (Address)provider.call(
                     "GetAddress", usr,
                     typeof(Address).GUID);
    return rt;
}

	

The objects involved in this example need no more tagging because the provider context and also structures (struct) need no additional mashalling tags.

.NET modules are grouped together in a configuration block that specifies the configuration of the Microsoft Common Language Runtime (CLR) used for .NET interop calls. The configuration block has the header runtimeEnv dotNET and configures the version of the runtime loaded (clrversion) and the path where the typelibraries (.tlb) files can be found (typelibpath).

With the assembly definitions you declare the registered assemblies to load.

	
RuntimeEnv dotNet
{
    clrversion   "v4.0.30319"
    typelibpath  programs/typelibrary
    assembly     "Functions, Version=1.0.0.30, Culture=neutral, PublicKeyToken=1c1d731dc6e1cbe1, processorArchitecture=MSIL"
    assembly     "Utilities, Version=1.0.0.27, Culture=neutral, PublicKeyToken=1c1f723cc51212ef, processorArchitecture=MSIL"
}

	

Languages of .NET called via the CLR are strongly typed languages. This means that the input of a function and the output is already validated to be of a strictly defined structure. So a validation by passing the input through a form might not be needed anymore. Validation with .NET data structures is weaker than for example XML validation with forms defined in a schema language. But only if distinguishing XML attributes from content elements is an issue. See in the documentation of the standard command handler how validation can be skipped with the attribute SKIP.

You can write functions for the logic tier of Wolframe in the Python programming language (http://www.python.org).

The implementation of Python calls is not yet available. But Wolframe will provide Python functions soon.

You can write functions for the logic tier of Wolframe with Lua. Lua is a scripting language designed, implemented, and maintained at PUC-Rio in Brazil by Roberto Ierusalimschy, Waldemar Celes and Luiz Henrique de Figueiredo (see http://www.lua.org/authors.html). A description of Lua is not provided here. For an introduction into programming with Lua see http://www.lua.org. The official manual which is also available as book is very good. Wolframe introduces some Lua interfaces to access input and output and to execute functions.

For enabling Lua you have to declare the loading of the module 'mod_command_lua' in the main section of the server configuration file.

		
    Module mod_command_lua

		

Each Lua script referenced has to be declared in the Processor section of the configuration with program <sourcefile>. The script is recognized as Lua script by the file extension ".lua". Files without this extension cannot be loaded as Lua scripts.

For Lua we do not have to declare anything in addition to the Lua script. If you configure a Lua script as program, all global functions declared in this script are declared as global form functions. For avoiding name conflicts you should declare private functions of the script as local.

Wolframe lets you access objects of the global context through a library called provider offering the following functions:

Wolframe lets us extend the type system consisting of Lua basic data types with our own. We can create atomic data types defined in a module or in a DDL datatype definition program (.wnmp file). For this you call the type method of the provider with the type name as first argument plus the type initializer argument list as additional parameters. The function returns a constructor function that can be called with the initialization value as argument to get a value instance of this type. The name of the type can refer to one of the following:

Lua provides an interface to the iterators internally used to couple objects and functions. They are accessible as iterator function closure in Lua. The look similar to Lua iterators but are not. You should not mix them with the standard Lua iterators though the semantic is similar. Filter interface iterators do not return nodes of the tree as subtree objects but only the node data in the order of a pre-order traversal. You can recursively iterate on the tree and build the object during traversal if you want. The returned elements of the Filter interface iterators are tuples with the following meaning:

Wolframe lets you access filter interface iterators through a library called iterator offering the following functions:

(*) See section "serialization iterator"

(**) If iterator.scope is called, all elements of the returned iterator has to be visited in order to continue iteration with the origin iterator on which iterator.scope was called.

Besides the provider library Wolframe defines the following objects global in the script execution context:

The provider function provider.form( ) with the name of the form as string as parameter returns an empty instance of a form. It takes the name of the form as string argument. If you for example have a form configured called "employee" and you want to create an employee object from a Lua table, you call

			
bcf = provider.form( "employee" )
bcf:fill( {surname='Hans', name='Muster', company='Wolframe'} )

			

The first line creates the data form object. The second line fills the data into the data form object.

The form method fill takes a second optional parameter. Passing "strict" as second parameter enforces a strict validation of the input against the form, meaning that attributes are checked to be attributes (when using XML serialization) and non optional elements are checked to be initialized. Passing "complete" as second parameter forces non optional elements to be checked for initialization but does not distinguish between attributes and content values. "relaxed" is the default and checks only the existence of filled-in values in the form.

Given the following validation form in simple form DDL syntax (see chapter "Forms"):

			
FORM Employee
	-root employee
{
    ID !@int                  ; Internal customer id (mandatory)
    name !string              ; Name of the customer (mandatory)
    company string            ; Company he is working for (optional)
}

			

the call of fill in the following piece of code will raise an error because some elements of the form ('ID' and 'name') are missing in the input:

			
bc = provider.form( "employee" ):fill( {company='Wolframe'}, "strict" )

			

To access the data in a form there are two form methods available. get() returns a filter interface iterator on the form data. There is also a method value() that returns the form data as Lua data structure (a Lua table or atomic value).

For calling transactions or built-in functions loaded as modules the Lua layer defines the concept of functions. The provider function provider.formfunction with the name of the function as argument returns a Lua function. This function takes a table or a filter interface iterator as argument and returns a data form structure. The data in the returned form data structure can be accessed with get() that returns a filter interface iterator on the content and value() that returns a Lua table or atomic value.

If you for example have a transaction called "insertEmployee" defined in a transaction description program file declared in the configuration called "insertEmployee" and you want to call it with the 'employee' object defined above as input, you do

			
f = provider.formfunction( "insertEmployee")
res = f ( {surname='Hans', name='Muster', company='Wolframe'} )
t = res:value()
output:print( t[ "id" ] )

			

The first line creates the function called "insertEmployee" as Lua function. The second calls the transaction, the third creates a Lua table out of the result and the fourth selects and prints the "id" element in the table.

This is a list of all objects and functions declared by Wolframe:

(*) See section "filter interface iterator"

(**) "strict" (full validation), "complete" (only check for all non optional elements initialization) or "relaxed" (no validation except matching of input to elements)

(*) See section "filter interface iterator"

(*) See section "filter interface iterator"

(*) See section "filter interface iterator "

(**) The filter interface iterator of a defined scope must be consumed completely before consuming anything of the parent iterator. Otherwise it may lead to unexpected results because they share some part of the iterator state.

You can write functions for the logic tier of Wolframe with C++. Because native C++ is by nature a compiled and not an interpreted language, you have to build a module out of your function implementation.

For native C++ you need a C++ build system with compiler and linker or an integrated development environment for C++.

Form functions declared in C++ have two arguments. The output structure to fill is passed by reference as first and the input structure passed is by value. The input structure copy should not be modified by the callee. This means in C++ that it is passed as const reference. The function returns an int that is 0 on success and any other value indicating an error code. The function may also throw a runtime error exception in case of an error. The following example shows a function declaration. The function declaration is not complete because the input output structures need to be declared with some additional attributes needed for introspection. We will explain this in the following section.

		
// ... PUT THE INCLUDES FOR THE "Customer" STRUCTURE DECLARATION HERE !

struct ProcessCustomer
{
    typedef Customer InputType; 
    typedef Customer OutputType; 
    static const char* name() {return "process_customer";}

    static int exec( const proc::ProcessorProvider* provider, InputType& res, const OutputType& param);
};


		

For defining input and output parameter structures in C++ you have to define the structure and its serialization description. The serialization description is a static function getStructDescription without arguments returning a const structure that describes what element names to bind to which structure elements.

The following example shows a form function parameter structure defined in C++.

		
#include "serialize/struct/structDescriptionBase.hpp"
#include <string>

namespace _Wolframe {
namespace example {

struct Customer
{
    int ID;                         // Internal customer id
    std::string name;               // Name of the customer
    std::string canonical_Name;     // Customer name in canonical form
    std::string country;            // Country
    std::string locality;           // Locality

    static const serialize::StructDescriptionBase* getStructDescription();
};

}}//namespace


		

		
#include "serialize/struct/structDescription.hpp"

using namespace _Wolframe;

namespace {
struct CustomerDescription :public serialize::StructDescription<Customer>
{
    CustomerDescription()
    {
        (*this)
        ("ID", &Customer::ID)
        --
        ("name", &Customer::name)
        ("canonical_Name", &Customer::canonical_Name)
        ("country", &Customer::country)
        ("locality", &Customer::locality)
        ;
    }
};

const serialize::StructDescriptionBase* Customer::getStructDescription()
{
    static CustomerDescription rt;
    return &rt;
}


		

Now we have all pieces together to build a loadable Wolframe module with our example C++ function. The following example shows what you have to declare in the main module source file.

		
#include "appDevel.hpp"
// ... PUT THE INCLUDES FOR THE "ProcessCustomer" FUNCTION DECLARATION HERE !

#include "customersFunction.hpp"

using namespace _Wolframe;

WF_MODULE_BEGIN( "ProcessCustomerFunction", "process customer function")
WF_FORM_FUNCTION("process_customer",ProcessCustomer::exec,Customer,Customer)
WF_MODULE_END


		

For building the module we have to include all modules introduced here and to link at against the wolframe serialization library (wolframe_serialize) and the wolframe core library (wolframe).

The module built can be loaded as the other modules by declaring it in the wolframe LoadModules section of the configuration. Simply list it there with module <yourModuleName> with <yourModuleName> being the name or path to your module.

C++ is a strongly typed language. This means that the input of a function and the output is already validated to be of a strictly defined structure. So a validation by passing the input through a form might not be needed anymore. The constructs used to describe structures of Wolframe in native C++ are even capable of describing attributes like used in XML (section 'Input/Output Data Structures' above). See in the documentation of the standard command handler how validation can be skipped with the attribute SKIP.

Form data structures can be defined in a DDL (Data Definition Language). It depends very much on the application what DDL is best to use. Users may already have their data definitions defined in a certain way. The form DDL can be defined in the way you want. Wolframe offers a plugin mechanism for DDL compilers and provides examples of such compilers. You configure the DDL sources to load and the compiler to use.

With the DDL form description we get a deserialization of some content into a structure and a serialization for the output. We get also a validation and normalization procedure of the content by assigning types to atomic form elements that validate and normalize the data elements. Most of the business transactions should be doable as input form description, output form description and a transaction that maps input to output without control flow aware programming.

All types of data forms introduced here are equivalent in use for all programs.

As example of a form DDL we provide the simpleform DDL. In simple form we forms, subtructures for reuse inside structures and forms and includes that help you to organize your code.

STRUCT myStructure
{
}
	

FORM myDocumentSchema
{
}
	

{
    number int
    name string
    id int
}
		

{
    number int, name string, id int
}
		

{
    number int
    name string
    address {
        street string, country string
    }
}
		

{
    number int = 1
    name string
}
		

id ?@int = 1
		

STRUCT content
{
    name string
    birth string
}

FORM insertedContent
{
    id int
    _ content
}
		

FORM myDoc
    -root = 'doc', -schemaLocation = 'http://bla.com/schema'
{
}
		

FORM myDoc
    -root = 'doc'
    -schemaLocation = 'http://bla.com/schema'
{
}
		

		
FORM Customer
	-root customer
{
    ID !@int                  ; Internal customer id (mandatory)
    name string               ; Name of the customer
    canonical_Name string     ; Customer name in canonical form
    country string            ; Country
    locality ?string          ; Locality (optional)
}

		

The basic elements to build atomic data types in Wolframe are normalization functions. Basic normalization functions are written in C++ and loadable as modules.

As we already mentioned are atomic elements in forms typed. With each type a function is associated to validate and normalize the atomic element of that type. There is only one predefined type called 'string'. strings are neither validated nor transformed for processing in any way. The others are defined in files with the extension .wnmp that are referenced as programs in the configuration.

A .wnmp file contains assignments of a type name to sequences of basic normalization function calls where the first takes the initial input. A normalization function call can either be a normalizer function or a custom data type defined in a module or a method of the predecessing custom data type in the sequence of the normalization function calls. The output of a function in the sequence gets the input of the next one and the final output for the last one. Each normalization step validates the input as atomic type (arithmetic,string,etc.) and transforms it to another atomic type.

The example defines 3 numeric types including trimming of the input string for mode tolerant parsing and a string type that is converted to lowercase as normalization.

		
int=trim,integer(5);
uint=trim,unsigned;
currency=trim,fixedpoint( 13, 2);
name=trim,lcname;

		

For declaring and using a .wnmp file in our example above, we have to load the module 'mod_normalize_string' and the module 'mod_normalize_number'. For this we add the following two lines to the LoadModules section of our Wolframe configuration:

		
    Module mod_normalize_number
    Module mod_normalize_string


		

We also have to add the declaration of the program "example.wnmp" (listing example above) to the Processor section of the configuration.

	
    Program example.wnmp

	

You can use XML for data filters in the logic tier of Wolframe. There are the following variants of XML filters available:

The libxml2 and the textwolf filter support at least the following character set encodings. For character set encodings that are not in the list, please ask the Wolframe team.

For using an XML filter based libxml2, you have to load the modules mod_filter_libxml2 and mod_doctype_xml. For this you add the two following lines to the LoadModules section of your Wolframe configuration:

		
    Module mod_doctype_xml
    Module mod_filter_libxml2


		

For using an XML filter based textwolf, you have to load the modules mod_filter_textwolf and mod_doctype_xml. For this you add the following two lines to the LoadModules section of your Wolframe configuration:

		
    Module mod_doctype_xml
    Module mod_filter_textwolf

		

You can use JSON for data filters in the logic tier of Wolframe. The standard JSON filter of Wolframe is called cjson and based on the library cJSON (http://sourceforge.net/projects/cjson) from Dave Gamble.

Without explicitly specified, the cjson filter support the following character set encodings. For character set encodings that are not in the list, please ask the Wolframe team.

For using the JSON filter based cJSON, you have to load the module 'mod_filter_cjson'. For this you add the following line to the LoadModules section of your Wolframe configuration:

		
    Module mod_doctype_json
    Module mod_filter_cjson

		

You can use XSLT for data filters in the logic tier of Wolframe. The XSLT filter of Wolframe for is based on libxml2 (http://www.xmlsoft.org).

Without explicitly specified, the XSLT filter support the following character set encodings. For character set encodings that are not in the list, please ask the Wolframe team.

For using an XSLT filter based libxml2, you have to load the modules mod_filter_libxml2 and mod_doctype_xml. For this you add the following 2 lines to the LoadModules section of your Wolframe configuration:

		
    Module mod_doctype_xml
    Module mod_filter_libxml2


		

You also have to add the program of the XSLT filter into the Processor section of the configuration. The name of the filter is the filename of the XSLT filter program without path and extension. In our example the filter would be named invoice_ISOxxxx:

	
    Program invoice_ISOxxxx.xslt

	

For the examples needing a configuration, we prepare the following simple configuration, just declaring the processing stuff, we need. Of course wolfilter can also work with any wolframe server configuration. The configuration will be referenced as 'test.conf'.

LoadModules
{
    module mod_command_lua
    module mod_doctype_xml
    module mod_filter_libxml2
    module mod_filter_json
    module mod_filter_token
}
Processor
{
    program test.lua
    program myfilter.xslt
    program myform.sfrm
}
		

The following example shows the mapping through a libxml2 filter. Filters are tested by passing a dash '-' command to execute. Because we do not need to load programs, we can call wolfilter without a test configuration.

cat in.xml | wolfilter -e libxml2 -m mod_filter_libxml2 - > out.xml
		

The following example shows the processing of the input through an xslt filter and mapping the output through a token filter that shows the tokenization of the input by the input filter. Because the referenced XSLT filter is defined as source in a program, we have to specify a configuration (test.conf) that declares the programs to load.

cat in.xml | wolfilter -i myfilter -o token -c test.conf - > out.xml
		

The following example shows the mapping through a form defined with simpleform DDL. Mapping through forms is tested by passing the name of the form as command to execute. Because forms have to be loaded as programs, we have to specify a configuration (test.conf) too.

cat in.xml | wolfilter -e libxml2 -c test.conf MyForm > out.xml
		

we assume here that the form to use is defined in myform.sfrm that is declared as program in the configuration and that the form is called MyForm.

The following example shows the execution of a function written in Lua. A JSON filter is used for input and output.

cat in.xml | wolfilter -e cjson -c test.conf MyFunc > out.json
		

we assume here that the exported function to call defined in myfunc.lua declared in test.conf and is called MyFunc.