Demaq EDU Manual
1. Introduction


Demaq is a system specification for "Declarative Messaging and Queuing". It was conceived by the Database Research Group of the University of Mannheim.
Demaq EDU is an early implementation of Demaq aimed at the use in research and educational environments.

2.Installation

Installation Guides are available for
Linux/ VMWare
Windows / Cygwin

3. Customizing DemaqEDU

3.1 Overview

The following chapter only applies if you want to use a nonstandard configuration for Demaq EDU, e.g. use a different XQuery or XSLT Processor.

The configuration of external tools is done using the extensions (ext) directory. The extensions are usually wrappers around the respective XQuery and XSLT processors.

3.2 XQuery / XSLT processor

Here are 2 simple examples for wrappers.

XSLT:
java net.sf.saxon.Transform $*

XQuery:
java net.sf.saxon.Query $*


As you can see, it just forwards all arguments to Saxon.  Saxon's calling convention (for XSL Transformations) is
java net.sf.saxon.Transform [options] style-doc {param=value}
for XQuery: java net.sf.saxon.Query [options] style-doc {param=value}


The following options are supported (and required)
  -s filename     Initial source document
  param=value     Set stylesheet string parameter
  +param=file     Set stylesheet document parameter
  !option=value   Set serialization option



A typical call could look like this.

    XSLT -s sourcedocument.xml stylesheet.xslt param1=foo +param2=somefile.xml


Therefore, if your XSLT processor has a different calling convention, you need to rearrange the parameters using e.g. getopts.


3.3 E-Mail

The calling convention for the "mailsend" - wrapper is
mailsend subject recipient messagefile

You may want to modify it to use a different mailer, as the standard mailsend wrapper uses heirloom mailx.

Note:
You also have to edit the standard mailsend (ext/mailsend) wrapper and enter your mail server details.

4.Demaq 


4.1. Basic concepts


Demaq is based on W3C standards XML, XPath and XQuery. WSDL is used for web service interface definition.

Demaq consists of 2 Languages:


Queue Definition Language (QDL)

Use the QDL to describe the system infrastructure, consisting of messages, message queues with attached properties, and slices. Slices are subsets of messages with a certain property value.

Examples:

create queue examplequeue kind basic mode persistent;

create property exampleproperty as xs:string queue examplequeue;

create slicing exampleslicing on exampleproperty;

Queue Rule Language (QRL)

Rules are basically XQuery scripts, extended by enqueue and reset commands.


Example:

create rule examplerule for examplequeue errorqueue exampleErrorQueue

let $value = "<xml>something</xml>"
return do enqueue {$value} into someotherqueue;


4.2 Further reading

At this time there is no complete language reference available, but you can find some basic information in this document:
http://db.informatik.uni-mannheim.de/publikationenDetails.html.de#ID525 (Demaq: A Foundation for Declarative XML Message Processing )


5.Using Demaq EDU

The easiest way to launch a Demaq Web Service is to put the corresponding .dql file in your Demaq EDU directory (or a subdirectory of the Demaq EDU directory) and run

sh startup name_of_dql_file_without_extension


If you need more control, use SetupFromDQL:

sh SetupFromDQL DQLFILE wse_name


To stop Demaq EDU, use CTRL-C. After that, you might have to press enter to get a command prompt.

Note: To get more information on your console from running demaq EDU system simply set the environmental variable LOGLEVEL to DEBUG (you could also set DEBUG, INFO, WARN, ERROR or FATAL to get more or less information).

LOGLEVEL=DEBUG
export LOGLEVEL

6.A simple application

6.1. Introduction

In this chapter, we will create a simple sample application to demonstrate the usage of Demaq EDU. We will use a simple HTML form to get the user input, query a remote web service and render the result as a HTML page. Please note that generating HTML is not the usual area of application of Demaq EDU. It is, however, supported, and well suited for demonstration and tutorial purposes.

6.2. Setting up the infrastructure

We start by creating a new .dql file in a text editor. To store logging messages, we create a new queue which we aptly call "logging":

create queue logging kind basic mode persistent;

This creates a standard queue. To communicate with the outside world, we have to create gateway queues. Since we want to offer a service, we have to create an incoming queue to receive requests.

create queue wse1_firstservice_in
  kind incoming
    interface "file://$XFROGGER_HOME/wse1.wsdl"
    port "wse1_default_http_in_port"
  response wse1_default_http_response
  mode persistent;

As you can see, we specify a WSDL file and the WSDL-port we want to use. The corresponding WSDL file looks like this:

<definitions name="wse1Service"
      xmlns="http://schemas.xmlsoap.org/wsdl/"
      xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
      targetNamespace="http://www.demaq.net/edu/wse1.wsdl"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema">

      <service name="wse1HTTPService">
        <documentation>Checks current high bid for an eBay auction</documentation>
        <port name="wse1_default_http_in_port" binding="tns:wse1Binding">
           <soap:address location="http://localhost:8080/firstservice"/>
        </port>
      </service>
</definitions>


Demaq currently only supports a subset of WSDL. Everything but the "service" element is ignored. Next, we specify the queue that communicates with the external web service:

create queue outgoing_ebay
  kind outgoing
    interface "http://www.xmethods.net/sd/2001/EBayWatcherService.wsdl"
    port "eBayWatcherPort"
  response outgoing_ebay_response
  mode persistent;


The Service we are using is the (excellent;-)) EBay Watcher from xmethods.net. It can be used to retrieve the price of a Buy-Now auction on US-ebay (it returns -1 as price if it doesn't want to give you the price for whatever reason, and so it returns -1 nearly always; but this is quite enough for testing purposes).

To keep track of the auction-id, we use a property.

create property auctionid as xs:string queue outgoing_ebay, outgoing_ebay_response,logging inherited value /auction/text();

As a last step, we create a simple HTML page to test our service

<html>
  <body>
    <FORM type="form" action="http://localhost:8080/firstservice" method="post" enctype="text/plain">
      <p>Get information about auction (id):
        <textarea name="msg" cols="40" rows="1"><auction>230002320006</auction></textarea>
        <INPUT type="submit" value="Send"/> <INPUT type="reset"/>
      </p>
    </FORM>
  </body>
</html>

6.3 Programming the behaviour

In this section we describe how to program the web service's behavior. So we answer the question: What should happen when a message arrives in one of our created queues?

If we use our simple web form the following message will arrive in wse1_firstservice_in:

<auction>230002320006</auction>


In the first rule that we create, we pack this message in a SOAP envelope and forward it to the outgoing_ebay queue:

create rule move_to_ebay_out for wse1_firstservice_in
let $msg := ./auction/text()
return do enqueue <soap:Envelope xmlns:mrns0="urn:xmethods-EbayWatcher"
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <mrns0:getCurrentPrice>
        <auction_id xsi:type="xs:string">{$msg}</auction_id>
      </mrns0:getCurrentPrice>
    </soap:Body>
  </soap:Envelope> into outgoing_ebay ;

This generates a proper SOAP message for querying the ebay watcher web service and sends it to the outgoing_ebay queue we created in 6.2. The outgoing_ebay queue will handle the communication with ebay watcher web service and direct the response to our outgoing_ebay_response queue.

When the reply from the ebay watcher web service arrives in outgoing_ebay_response, we just have to generate a simple HTML page to display the result. Note how qs:property() is used to query a property value.

create rule move_to_http_def_resp for outgoing_ebay_response
do enqueue <html>
  <body>
  Current price of auction {qs:property("auctionid")} is
  <p>{./node()}</p>
  </body>
  </html> into wse1_default_http_response ;

Congratulations to your first Demaq web service !


7.Demaq EDU extended functionality

7.1. Sending mail


You can send mails over SMTP from within a Demaq EDU application. See Chapter 3.3 for details on setting up the mail service.
Create an outgoing queue with interface set to "SMTPMAILER" to use this feature.

Note: Some mailers do not support html mails.

create queue mailout
  kind outgoing
    interface "SMTPMAILER"
    port ""
  mode persistent;

Additionally, you have to create the "Subject" and "SendTo" (and optionally "ContentType") properties for this queue.

create property SendTo queue mailout fixed;
create property Subject queue mailout fixed;

create property ContentType queue mailout fixed;


To send a mail, enqueue the mail message body as the message, and set the "SendTo" (Recipient) and "Subject" properties.

do enqueue <html>
This is a test message!
</html>
into mailout with Subject value "Message Subject" with rcpt value "user@example.org";

7.2.Downloading XML files over HTTP/FTP


Demaq EDU includes a simple, easy to use feature to allow downloading of XML-formatted files from HTTP or FTP servers. Create an outgoing queue, set interface to "HTTPDOWNLOADER", port to "URL" .

create queue download_jobs
  kind outgoing
    interface "HTTPDOWNLOADER"
    port "URL"
  response downloaded_files
  mode persistent
  errorqueue errorQ;


Enqueue an (empty) message with the property "url" set to the url you want to download. The requested file will be enqueued as a message into the specified response queue (or into the error queue, if the download failed).

Note: Only XML-formatted files are supported.

8. FAQ


Q: Does Demaq EDU support XQuery update ?
A: No

9.Contact information, legal information, acknowledgments

9.1 Acknowledgments


Karl Steinbuch / MFG
Prof. Carl-Christian Kanne
Alexander Boehm

9.2 Legal information



Demaq EDU 1.0 is available under the GNU Lesser General Public License (see License Agreement).

9.3 Contact information

Homepage of the Demaq project : http://www.demaq.net

E-Mail (please replace "-at-" with "@")

Dennis Knochenwefel: demaq-at-knochenwefel.de
Martin Kremer: demaq-at-martin-kremer.de

V1.0

Mannheim, June 2007