From c04dd2d342fb5088a840454c9830981f0948107c Mon Sep 17 00:00:00 2001 From: konrad Date: Sun, 8 Feb 2009 15:32:11 +0000 Subject: [PATCH] refined wobs & docu git-svn-id: https://silmor.de/svn/softmagic/smoke/trunk@267 6e3c4bff-ac9f-4ac1-96c5-d2ea494d3e33 --- doc/prog_woc.html | 119 +++++++++++++++++++++++++++++++++++++++++++++++++- wob/cart.wolf | 41 +++++++++++++++++ wob/magicsmoke.wolf | 3 +- wob/order.wolf | 99 ++++++++++++++++++++----------------------- 4 files changed, 205 insertions(+), 57 deletions(-) diff --git a/doc/prog_woc.html b/doc/prog_woc.html index ca6f426..4400156 100644 --- a/doc/prog_woc.html +++ b/doc/prog_woc.html @@ -20,15 +20,128 @@ The Web Object Compiler (woc) helps implementing these three-tier architecture i

Overall File Format

-Woc translates Web Object Language Files (*.wolf) into PHP or C++/Qt code. The wolf files are simple XML syntax. +Woc translates Web Object Language Files (*.wolf) into PHP or C++/Qt code. The wolf files are simple XML syntax.

+ +Each wolf file must be enclosed in the <Wolf> and </Wolf> tags. The first few statements inside must describe the project itself: + +

+<Wolf>
+  <Project baseDir=".." wobDir="wob"/>
+  <Version comm="0100" needcomm="0100" humanReadable="1.1 alpha" svnTarget="."/>
+</Wolf>
+
+ +Above the <Project> tag tells woc what the overall project directory is (relative to its current working directory) and where, relative to the baseDir, it will find all wolf files.

+ +The <Version> tag describes the communication protocol: + + + + + + + + +
AttributeDescription
commthe communication protocol described by this wolf file
needcommthe minimum communication protocol this wolf file is compatible with (attention: the processor uses ASCII string comparison, not int comparison)
humanReadablethe version number shown to the user
svnTargetif given: woc will call SVN to find out which repository revision was used
svnExeexecutable to call for subversion (default: svn)

+ +The Include tag can be used to include other wolf files in the processing: +

+<Include file="user.wolf"/>
+

+ +

Attribute Types

+ +Boolean attributes in wolf files allow integers (0 is false, non-zere is true) or the explicit strings "yes", "true", "on" for true and "no", "false", "off" for false.

+ +Integers can be entered in C notation - if it starts with 1 through 9 it is decimal, if it starts with 0 it is octal, if it starts with 0x it is hexadecimal. All integers are interpreted by woc - the generated source will always contain decimal numbers.

+ +Woc is case-sensitive. + +

Chosing Outputs

+ +Outputs should be declared after the basics have been declared, but before any tables, classes or transactions are declared. + +
+<QtClientOutput sourceDir="src" subDir="wob" priInclude="wob.pri"/>
+<PHPServerOutput sourceDir="www" subDir="inc/wob" extension=".php" clean="yes"/>
+<HtmlOutput sourceDir="doc" subDir="wob"/>
+
+ +The attribute "sourceDir" tells woc which directory (above baseDir) is the root source directory for each sub-project, the "subDir" attribute tells it which subdirectory below the sourceDir should be used for woc's generated output. The attribute "clean" tells woc to first delete all files from that sub-directory before starting the generator. Multiple generators of the same type can be used.

+ +The QtClientOutput tag tells woc to create a generator for a Qt based client - the priInclude attribute tells woc which name it should give to the QMake include for its generated output.

+ +The PHPServerOutput tag tells woc to create a generator for a PHP based server. The "extension" attribute tells woc which file extension to use for the generated files (default is .php). Woc will automatically create a "autoload" (plus extension) file that should be included from the main body of the PHP project to load the automatically generated classes.

+ +The HtmlOutput tag tells woc where to generate API documentation.

Database Abstraction Layer

-The Database Abstraction Layer is the servers lower bound towards the database. It is a simple translation of the database structure into usable PHP objects. +The Database Abstraction Layer is the servers lower bound towards the database. It is a simple translation of the database structure into usable PHP objects. The woc compiler generates one class per table.

+ +One of the first statements is the manifest for the database schema: + +

+<DataBase instance="dbInst" schema="dbSchema" version="00.01"/>
+
+ +The attribute "instance" tells woc what variable name it should use for the database connection instance, likewise "schema" tells woc which variable represents the database schema (usually an instance of WobSchema, which is generated by woc). The "version" attribute tells woc which database schema version is described in this wolf file.

+ +For each database table woc needs a description of that table: + +

+<Table name="ticket" backup="yes" base="BarcodeTable">
+  <Column name="ticketid" type="string:32" primarykey="yes"/>
+  <Column name="eventid" type="int32" foreignkey="event:eventid"/>
+  <Column name="price" type="int32" notnull="yes"/>
+  <Column name="status" type="enum32" notnull="yes">
+    <Value name="Reserved" value="0x301"/> <!--dec: 769-->
+    <Value name="Cancelled" value="0x4"/> <!--dec: 4-->
+    <Value name="MaskUsable" value="0x300"/> <!--dec: 768-->
+  </Column>
+  <Column name="orderid" type="int32" foreignkey="order:orderid" notnull="yes"/>
+</Table>
+
+ +Table attributes: + + + + + +
AttributeDescription
namethe name of the table, the generated class will be Wttablename
backupbool, contains whether the table is in the backup routine (default: false)
baseoptional, contains the class that this tables class is derived from, the base class must be derived from WobTable (default is to derive from WobTable directly)

+ +Column attributes: + + + + + + + + + +
AttributeDescription
namethe name of the column in the database
typethe type of the column, this must be a woc type which is then translated into SQL by woc
notnull, nullbool, marks the column to (not) allow NULL values, only one of the two attributes is allowed, currently the default is to allow NULL, but this may change in the future
foreignkeydeclares a reference to a foreign key column, the syntax is "foreigntablename:column" - the table that is referenced must be declared before the current one
uniquebool, declares the column UNIQUE
primarykeybool, tells woc that this column is part of the primary key (multiple columns may be part of the primary key)
defaultdeclares a default value for the column (currently defaults for enums must be given as integer)

+ +Column Types: + + + + + + + + + +
AttributeDescription
string:int, stringa string column (SQL: VARCHAR), if the :int is given the column will have that maximum length assigned, if it is not given the database maximum is used; most databases support VARCHARs up to 255 characters
int32, int64a 32-bit/64-bit integer type
enum, enum32, enum64a 32bit/64bit (enum=enum32) integer interpreted as enumeration, the column must contain "Value" tags to declare the valid values
boola boolean column (the SQL representation may vary per database system)
seq32, seq64a 32bit/64bit integer that counts up automatically (ie. that has a sequence attached to it) - this is usually only used for primary keys
texta large text field
blobbinary large object

+ +All names in table descriptions must follow a very strict syntax in order to be compatible with as many database systems as possible. Woc allows names that start with letters and contain only letters, underscored and digits.

+ +The Value tags for enum types function similar to enums in C++. If a value attribute is given that value is assigned to the enum symbol, if no value is given the previous one is increased by one (the first value is 0).

Communication Abstraction Layer

-The Communication Abstraction Layer is the servers upper bound towards the client. It hides the complexities of serializing data onto the network transport protocol by providing communication classes that do this automatically. +The Communication Abstraction Layer is the servers upper bound towards the client. It hides the complexities of serializing data onto the network transport protocol by providing communication classes that do this automatically. The configuration of this layer is split into two major components: communication classes and transactions. While the communication classes describe what data can be transported over the connection, the transactions describe what operations can be performed.

Business Logic: Mapping - the Trivial Case

diff --git a/wob/cart.wolf b/wob/cart.wolf index e36da7e..2e2a190 100644 --- a/wob/cart.wolf +++ b/wob/cart.wolf @@ -37,4 +37,45 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/wob/magicsmoke.wolf b/wob/magicsmoke.wolf index 4641462..389cf08 100644 --- a/wob/magicsmoke.wolf +++ b/wob/magicsmoke.wolf @@ -14,7 +14,8 @@ - + + diff --git a/wob/order.wolf b/wob/order.wolf index b6a9194..cfed4b6 100644 --- a/wob/order.wolf +++ b/wob/order.wolf @@ -26,12 +26,12 @@ - - - - - - + + + + + + @@ -55,7 +55,17 @@ - + + + + + + + + + + + @@ -73,72 +83,55 @@ - - - - - - - - + + + - - - - + + + + + ticketid eventid price status + + + + + + + + + + + + - - + + + + - - - - - - - - - - - - - - - - - - - - - - - - + + - - - + + - + orderid customerid seller amountpaid state amountdue -- 1.7.2.5