Sav ZServer:

Web Developer's Guide

Sav ZServer is environment of Java servlets providing connection a lot of Internet clients with Z databases. Clients are end users receiving and sending data via the usual Web browser. Server supports navigation in database via Web browser; see 1. Basic Service section. Moreover Server may automatically create and change database (schema and contents) in accordance with input HTML-form data, it is considered in 2.DDHF Interface section. To develop specific database application, programmer can write Java servlets with Sav ZAPI database program interface, which is delivered with Sav ZServer (..\api\Sav\Z\package-summary.html) or separately (http://savtechno.com).

1. Basic Service

Consider steps that are needed to develop Web site exploring Z database.

1.1. Web server configuration

The Tomcat Web server in stand-alone mode is supposed; see another http://java.sun.com/products/servlet/industry.html supporting Java servlets. The savzs directory of Sav ZServer needs be placed in root directory, for stand-alone Tomcat it will be <tomcat>/webapps/ROOT .

tomcat.bat, Web server's main script (for win32).

...
set CLASSPATH=%CLASSPATH%;...\savzs\lib\savs.jar;...\savzs\lib\savza.jar
web.xml, configuration file initializing servlet parameters (servlets.properties in old versions of Java servlet engine). File is located in .../ROOT/WEB-INF. Following example may be omitted. It contents only initparameter's values that are presumed by default.
...
<web-app>
  <servlet>
    <servlet-name>navigate</servlet-name>
    <servlet-class>Sav.Server.Navigator</servlet-class>
    <init-param>
      <param-name>serverBase</param-name>
      <param-value>savzs</param-value>
    </init-param>
    <init-param>
      <param-name>outLimit</param-name>
      <param-value>100000</param-value>
    </init-param>
    <init-param>
      <param-name>debug</param-name>
      <param-value>true</param-value>
    </init-param>
  </servlet>
  <servlet>
    <servlet-name>import</servlet-name>
    <servlet-class>Sav.Server.Importer</servlet-class>
    <init-param>
      <param-name>serverBase</param-name>
      <param-value>savzs</param-value>
    </init-param>
    <init-param>
      <param-name>debug</param-name>
      <param-value>true</param-value>
    </init-param>
  </servlet>
  <servlet>
    <servlet-name>export</servlet-name>
    <servlet-class>Sav.Server.Exporter</servlet-class>
    <init-param>

      <param-name>serverBase</param-name>
      <param-value>savzs</param-value>
    </init-param>
    <init-param>
      <param-name>debug</param-name>
      <param-value>true</param-value>
    </init-param>
  </servlet>
  <servlet>
    <servlet-name>record</servlet-name>
    <servlet-class>Sav.Server.Recorder</servlet-class>
    <init-param>
      <param-name>serverBase</param-name>
      <param-value>savzs</param-value>
    </init-param>
    <init-param>
      <param-name>debug</param-name>
      <param-value>true</param-value>
    </init-param>
  </servlet>
</web-app>
The outLimit is byte limitation of data deduced from the database to the client. The serverBase parameter sets name of ZServer directory in the web pages root directory.

1.2. Preparing Web pages

Database may contain URL references to the html|gif|jpeg|text|... files. It enables to use ZServer as wizard for navigation in WWW. To prepare Web pages, outer tools are needed.

1.3. Creating tab files

The .tab files are table data importable in Z database and may be created by the simple text editor. Table's first line describes schema of the data. Only the semicolon separates fields. If field text has special symbols, particularly one from the $ * # " ' { [ ( } ] ) ^ : / | \ ~ = , ; < > , field text should be enclosed in the quotes, ' A: B ^ C '. It should be remembered that words started with # <digital>, or with $<letter> have specific use, that is, #<number> - numbered field, $<name> - specific field. The $<number> price may be without quotes, $10.2. Learning Z language will helpful for understanding of ZBase features and for farther database development.

Usually each table corresponds to the separate class level of the target objects. The tables of the whole class (all the class levels) may not exceed default outLimit parameter, 100000 bytes. It has to limit size of the data deduced via WWW. See savzs/demo/Common/*.tab examples.

1.4. Filling database

We need to run from Web browser the Sav.Server.Importer servlet to import the data tables' directory or .tab file in Z database. (Of course Web server must be started before).
http://<hostname>/servlet/Sav.Server.Importer?db=<database>&f=<file>
Where:
<file> = <directory> | <*.tab file>

Example:
http://localhost:8080/servlet/Sav.Server.Importer?db=demo/Common.ass&f=demo/Common
or
http://localhost/servlet/Sav.Server.Importer?db=demo/Common.ass&f=demo/Common/DS.tab

1.5. Database navigation

You need to see all the specific features in Navigation in Object-Relational Database article. To see database contents, Sav.Server.Navigator servlet will be suffice.
http://<hostname>/servlet/Sav.Server.Navigator?db=<database>
Example:
http://localhost:8080/servlet/Sav.Server.Navigator?db=demo/Common.ass

1.6. Archiving and database conversion

To keep database version, we can copy it, but better if it's data would be exported to a directory of tabular files.
http://<hostname>/servlet/Sav.Server.Exporter?db=<database>&f=<file>
Where:
<file> = <directory> | <*.tab file>

Example:
http://localhost:8080/servlet/Sav.Server.Exporter?db=demo/Common.ass&f=demo/Common1

2. DDHF Interface

We overpass at most important and interesting section that shows Sav Z Server as simplest tool for developers of Web database application. Sav ZServer technology, namely DDHF (Defining Database Html-Form) interface is based on input HTML-form. DDHF directs to do database structure dependent on HTML-form structure, instead of the usual HTML-form dependence upon database. Knowledge of HTML-form is enough to understand DDHF, and create remote Web database and client interface filling it!!!

2.1. DDHF outfit

All the specific field names of DDHF have to begin with '$'. Usually specific fields are hidden. Hidden specific field may point at another non-hidden data field name (as $Content, and $User in example below) or have final value (as $DataBase, $Service below). Non-hidden specific fields have final value (as $Password below).

The $DataBase specific field determines database of input data. The $Content object name (table name), and $Key key attributes (fields) are designed to point out key data fields. The $Content points at primary key for all the data (non-specific) fields. The $Key fields may be several or missing, its are useful only as additional to the $Content primary key.

The $Confirm hidden field is URL path which ZServer uses with the successful registration. The $Warning hidden field sets up URL path if recording is not successful. If $Confirm and $Warning are missing, Server send own messages. Be care with $Submit of "submit" type and $Reset of "reset" type input fields.

The $User user name, $Service accessible resources, $Password, and $Info supplementary information are specific words (see Zigzag Language documentation) providing login control to system services. These fields are needed only if DDHF is used for user registration. The $User is primary key for $Service, $Password, and $Info fields. The $Service fields may be several.

Value of $DataBase by default is either file kept by session in previous access or some temporary file. Either $Content or $User, or both fields must be placed in DDHF necessarily. If data field, the $Content point at, is missing in DDHF, then value of this data field is new number for each recording.

Let us look at demo/Record.html  DDHF HTML-form. It calls Sav.Server.Recorder servlet. Input data are controlled in client side (no server) over validate() Java script function.

<FORM name="form1" action="/servlet/Sav.Server.Recorder" 
method="post" onSubmit="return validate()">
...
</FORM>
We do not know final form view, it may be another at any time and therefore database must be changed with changing form immediately.  Now current input fields are User, Password, Name, Email, and Phone. For Z database the type and size of a field is not important. There is no need to create database schema, because it is formed automatically. The form below defines two schemas: 1. by $User, $User ($Service, $Password); and 2. by $Content, User (Name, Email, Phone). The $User ($Service, $Password) data are not accessible for navigation.
<FORM name="form1" action="/servlet/Sav.Server.Recorder" method="post" onSubmit="return validate()">
<INPUT type="hidden" name="$DataBase" value="demo/Account.ass" />
<INPUT type="hidden" name="$Content" value="User" />
<INPUT type="hidden" name="$User" value="User" />
<INPUT type="hidden" name="$Service" value="record" />
<INPUT type="hidden" name="$Service" value="navigate" />
<INPUT type="hidden" name="$Confirm" value="http://localhost:8080/savzs/demo/RecordConfirm.html" />
<INPUT type="hidden" name="$Warning" value="http://localhost:8080/savzs/demo/RecordWarning.html" />
Please fill up the form below. All fields with asterisk (*) are required. 
<TABLE>
  <TR>
    <TD>*</TD>
    <TD>User:</TD>
    <TD><INPUT type="text" name="User" size=32 maxlength=16 /></TD>
  </TR>
  <TR>
    <TD>*</TD>
    <TD>Password:</TD>
    <TD><INPUT type="password" name="$Password" size=32 maxlength=16 /></TD>
  </TR>
  <TR>
    <TD>*</TD>
    <TD>First Name:</TD>
    <TD><INPUT type="text" name="Name" size=32 maxlength=32 /></TD>
  </TR>
  <TR>
    <TD>*</TD>
    <TD>Email:</TD>
    <TD><INPUT type="text" name="Email" size=32 maxlength=32 /></TD>
  </TR>
  <TR>
    <TD></TD>
    <TD>Phone:</TD> 
    <TD><INPUT type="text" name="Phone" size=32 maxlength=16 /></TD>
  </TR>
  <TR>
    <TD colspan=3 align="center">
      <INPUT type="submit" name="$Submit" value="Submit Data" />
      <INPUT type="reset" name="$Reset" value="Reset Form" /> 
    </TD>
  </TR>
</TABLE>
</FORM>
Whole text of the form is here. To interact with Sav ZServer we need to open this form (and others of 2.2. section) over like http://<hostname>/savzs/demo/Record.html . Please notice that Record.html, Right.html, Profile.html, Product.html demo pages have localhost:8080 host reference for Tomcat in stand-alone mode, whereas default port of online Web servers, Apache and others, is 80 .

2.2. Objective examples

Apparently DDHF may be used jointly with JSP, Java Script and other Web technologies. Consider consequent steps of database development exclusively via DDHF. All the example forms are in the demo directory.

2.2.1. Access rights to system services

First and foremost administrator uses and adapts Right.html. Notice that data fields of this form are not viewed by Sav.Server.Navigator and Sav.Server.Exporter.
<FORM name="form1" action="/servlet/Sav.Server.Recorder" method="post" onSubmit="return validate()">
<INPUT type="hidden" name="$DataBase" value="demo/Account.ass" />
<INPUT type="hidden" name="$Confirm" value="http://localhost:8080/savzs/demo/Right.html" />
Please fill up the form below. All fields with asterisk (*) are required. 
<TABLE>
  <TR>
    <TD>*</TD>
    <TD>User:</TD>
    <TD><INPUT type="text" name="$User" size=32 maxlength=16 /></TD>
  </TR>
  <TR>
    <TD>*</TD>
    <TD>Password:</TD>
    <TD><INPUT type="password" name="$Password" size=32 maxlength=16 /></TD>
  </TR>
  <TR>
    <TD>*</TD>
    <TD>Service:</TD>
    <TD>
      <SELECT name="$Service" size="4" multiple>
         <OPTION>navigate</OPTION>
         <OPTION>import</OPTION>
         <OPTION>export</OPTION>
         <OPTION>record</OPTION>
      </SELECT>
    </TD>
  </TR>
  <TR>
    <TD></TD>
    <TD>Info:</TD>
    <TD><INPUT type="text" name="$Info" size=32 maxlength=256 /></TD>
  </TR>
  <TR>
    <TD colspan=3 align="center">
      <INPUT type="submit" name="$Submit" value="Submit Data">
      <INPUT type="reset" name="$Reset" value="Reset Form"> 
    </TD>
  </TR>
</TABLE>
</FORM>
First record, which needs to be entered, assigns rights to all the system services of ZServer for administrator himself.
$User:     Administrator
$Password: 123456
$Service:  navigate
           import
           export
           record
$Info:
If database permits any user to record data over Sav.Server.Recorder, next record may be such as below. Notice that "" value (two quote) of $User and $Password marks indefinite value and needs to be enter in input field.
$User:     ""
$Password: ""
$Service:  record
$Info:

2.2.2. Registration of out users

Following Profile.html HTML-form enters data of user profile. In correspondence with 2.2.1 section administrator can review contents of demo/Account.ass DB over Sav.Server.Navigator and copy database in sequent file over Sav.Server.Exporter.
<FORM name="form1" action="/servlet/Sav.Server.Recorder" method="post" onSubmit="return validate()">
<INPUT type="hidden" name="$DataBase" value="demo/Account.ass" />
<INPUT type="hidden" name="$Content" value="User" />
<INPUT type="hidden" name="$Confirm" value="http://localhost:8080/savzs/demo/Order.html" />
Please fill up the form below. All fields with asterisk (*) are required. 
<TABLE>
  <TR>
    <TD>*</TD>
    <TD>User:</TD>
    <TD><INPUT type="text" name="User" size=32 maxlength=16 /></TD>
  </TR>
  <TR>
    <TD>*</TD>
    <TD>Password:</TD>
    <TD><INPUT type="password" name="Password" size=32 maxlength=16 /></TD>
  </TR>
  <TR>
    <TD>*</TD>
    <TD>Name:</TD>
    <TD><INPUT type="text" name="Name" size=32 maxlength=32 /></TD>
  </TR>
  <TR>
    <TD>*</TD>
    <TD>Email:</TD>
    <TD><INPUT type="text" name="Email" size=32 maxlength=32 /></TD>
  </TR>
  <TR>
    <TD></TD>
    <TD>Phone:</TD> 
    <TD><INPUT type="text" name="Phone" size=32 maxlength=16 /></TD>
  </TR>
  <TR>
    <TD colspan=3 align="center">
      <INPUT type="submit" name="$Submit" value="Submit Data">
      <INPUT type="reset" name="$Reset" value="Reset Form"> 
    </TD>
  </TR>
</TABLE>
</FORM>

2.2.3. Forming order

This Order.html form enters data without key fields. Each record is numbered automatically in database.
<FORM name="form1" action="/servlet/Sav.Server.Recorder" method="post" onSubmit="return validate()">
<INPUT type="hidden" name="$DataBase" value="demo/Account.ass" />
<INPUT type="hidden" name="$Content" value="Order" />
Please fill up the form below. All fields with asterisk (*) are required. 
<TABLE>
  <TR>
    <TD>*</TD>
    <TD>Date:</TD>
    <TD><INPUT type="text" name="Date" size=32 maxlength=16 /></TD>
  </TR>
  <TR>
    <TD>*</TD>
    <TD>Name:</TD>
    <TD><INPUT type="text" name="Name" size=32 maxlength=32 /></TD>
  </TR>
  <TR>
    <TD>*</TD>
    <TD>Phone:</TD> 
    <TD><INPUT type="text" name="Phone" size=32 maxlength=16 /></TD>
  </TR>
  <TR>
    <TD></TD>
    <TD>Company:</TD>
    <TD><INPUT type="text" name="Company" size=32 maxlength=32 /></TD>
  </TR>
  <TR>
    <TD>*</TD>
    <TD>Product Type:</TD>
    <TD><INPUT type="text" name="Product Type" size=32 maxlength=32 /></TD>
  </TR>
  <TR>
    <TD>*</TD>
    <TD>Product Name:</TD>
    <TD><INPUT type="text" name="Product Name" size=32 maxlength=32 /></TD>
  </TR>
  <TR>
    <TD></TD>
    <TD>Quantity:</TD>
    <TD><INPUT type="text" name="Quantity" size=32 maxlength=16 /></TD>
  </TR>
  <TR>
    <TD colspan=3 align="center">
      <INPUT type="submit" name="$Submit" value="Submit Data">
      <INPUT type="reset" name="$Reset" value="Reset Form"> 
    </TD>
  </TR>
</TABLE>
</FORM>

2.2.4. Product accounting

This Product.html form is for input of many-keys data. Better if data about products and, for example, users would be located in diverse databases. Here is used one Account.ass database. The $Confirm form field calls Sav.Server.Navigator for testing contents after input. To navigate in Account.ass we need then to login as Administrator (with 123456 password that was input in 2.2.1 section).
<FORM name="form1" action="/servlet/Sav.Server.Recorder" method="post" onSubmit="return validate()">
<INPUT type="hidden" name="$DataBase" value="demo/Account.ass" />
<INPUT type="hidden" name="$Content" value="Product" />
<INPUT type="hidden" name="$Key" value="Product Type" />
<INPUT type="hidden" name="$Key" value="Product Name" />
<INPUT type="hidden" name="$Confirm" value="http://localhost:8080/servlet/Sav.Server.Navigator?db=demo/Account.ass" />
Please fill up the form below. All fields with asterisk (*) are required. 
<TABLE>
  <TR>
    <TD>*</TD>
    <TD>Product Type:</TD>
    <TD><INPUT type="text" name="Product Type" size=32 maxlength=32 /></TD>
  </TR>
  <TR>
    <TD>*</TD>
    <TD>Product Name:</TD>
    <TD><INPUT type="text" name="Product Name" size=32 maxlength=32 /></TD>
  </TR>
  <TR>
    <TD>*</TD>
    <TD>Quantity:</TD> 
    <TD><INPUT type="text" name="Quantity" size=32 maxlength=16 /></TD>
  </TR>
  <TR>
    <TD></TD>
    <TD>Price:</TD>
    <TD><INPUT type="text" name="Price" size=32 maxlength=16 /></TD>
  </TR>
  <TR>
    <TD colspan=3 align="center">
      <INPUT type="submit" name="$Submit" value="Submit Data">
      <INPUT type="reset" name="$Reset" value="Reset Form"> 
    </TD>
  </TR>
</TABLE>
</FORM>