Tutorial #3 - Introduction to webODRA2

webODRA2 is a new version of the framework for the object-oriented database management system ODRA. The framework allows using SBQL language for creating web sites.

Architecture

The core architecture of the framework is presented on the following image:

Routing Module

In the center of webODRA2 is a routing module which is responsible for a correct processing of incoming web requests. The module is driven by rules defined by a programmer. Each definition, written in SBQL (as an object with specific properties), contains the following information:

• Url. A regular expression which will be applied to the incoming request’s url. If there is a match, then the rule will be executed;
• Weight. It affects an order of the processing;
• Name. Human-readable name of the rule. It is especially useful during logging;
• Additional Data. The utilization of the additional data depends on rule’s kind;
• Rule’s Kind. The kind of the rule which affects processing:
  • Passthrough. The web framework ignores those rules and they are processed directly by a integrated web server. They serve static files like: pictures, css, Java script, etc., e.g.

    create permanent Routes(1 as weight, "Ignore some file types" as name, 1 as kind, "" as url, "jpg|JPG|png|PNG|css|CSS|ico|ICO|js|JS" as additionalData);

  • Data route. They contain a SBQL method’s name to execute. The method will get all HTML form parameters entered by a user which makes possible processing them by a SBQL code. The result of the method is transformed (see further) and returned to the browser, e.g.

    create permanent Routes(101 as weight, "Forums list" as name, 2 as kind, "/data/forums" as url, "admin.ForumDemoMod.webGetForums" as additionalData);

  • Page route. An HTML page which is post-processed by our templating engine (see further), e.g.

    create permanent Routes(20 as weight, "Page Forums" as name, 3 as kind, "/forums/" as url, "forums.html" as additionalData);

The Client GUI

webODRA uses a client-side GUI framework. The idea is based on embedding in a web page some (meta) information which will be used to present business data. We have chosen a framework called Knockout which utilizes new HTML5 data- attributes. They allow to create custom attributes and store any information. The process of showing a web page contains two steps:

• First, a HTML page is downloaded from a server, containing the markers.
• Then the library sends an AJAX request to asynchronously retrieve necessary data which are then “injected” into the page.

The user data submission is performed on a similar rules. An asynchronous request is send to the server, triggering a Data Rule which process the provided data.

Standard website navigation is performed using a regular hyperlinks (“outside” the framework).

Templating Module

The templating module is responsible for a coherent look and fill of the entire website. It operates on a single master page (default: layout.html) which has a dynamic area fulfilled with some functional pages, e.g. a document repository, a forum, news, etc. For instance, the master page can contain a header, a navigation panel and a footer.

The process is triggered by Page Route rule. When a particular page is requested by a browser, the master page is applied, or which is more correct, the requested page is embedded in the master page and then returned to the browser.

Data Transformation Module

When a Data Route rule executes a given SBQL method, the result could be any SBQL data type, e.g. a collection, a single object, a text. It needs to be processed to the format recognized by the Client GUI. The Data Transformation Module recursively converts the result into JSON string, sends it back to the web browser where it is further processed.

Installation

Download an archive from the http://www.mtrzaska.com/webodra (tested with the webODRA - Release 2013-08-29). Just unpack the archive – no installation is required. Make sure that you have a current edition of Java JDK installed properly.

Run samples

The release contains two samples. The bigger one (forum) has been created manually; the second one has been generated automatically by the ODRA eIDE2 using the scaffolding mechanism. To execute one of the samples follow the simple procedure:

• Start webODRA and ODRA.bat from a command line (cmd.exe);

• You will see console windows with:
  • ODRA DBMS (listening for requests),
  • ODRA CLI (Command Line Interpreter). Type (to execute one of two samples):
    • batch sample1-forum.cli or batch sample2-scaffolding.cli and press Enter;
    • quit press Enter;
    • the admin console will be closed and the webODRA server will be started (to stop it press: CTRL + C)

Run a web browser and navigate to: http://localhost:8080/ (sample #1) and click Forums link

or go to http://localhost:8080/products/ (sample #2)

Please note that all buttons are working and CRUD operations are available, e.g. editing a product:

Remarks

1. The \Logs folder contains two types of log files:
   1. webODRA.log with activities performed by webODRA,
   2. webODRA-<date>.request.log with typical web server information
   3. The \sample-… folders contain SBQL batch files creating routing rules and some data.
   4. The \WebRes folder contains static web files like HTML pages (including a template), graphics, CSS, etc.
   5. It is possible to pass two parameters for the webODRA server class:
      • webRoot which defines the web root folder; default value is the current folder with the name WebRes. Sample usage: webRoot="c:\my\web\folder\"
      • globalMod defines where is located a global module storing some important data, e.g. routing rules; default value is GlobalMod. Sample usage: globalMod=admin.GlobalMod
   6. There are some special admin urls:
      • /dev-reload - reloads all routing rules and shows them
   7. It is also possible to start only a webODRA - use the webODRA - only.bat. In such a case make sure that you have an ODRA DB server running and storing necessary information (e.g. routing rules).