X-Git-Url: http://git.kpe.io/?p=clsql.git;a=blobdiff_plain;f=doc%2Fref-ooddl.xml;h=ee8f6011f8d5a4933e8061aa086eaf0546b83a79;hp=e3ad2f38627990a2564e2410365c5a821c561ed3;hb=a244caf265fff60cc9d00083e15951762dd7f1ca;hpb=c81a9fe27ee259429b89ef680788abb8f8e1b26a diff --git a/doc/ref-ooddl.xml b/doc/ref-ooddl.xml index e3ad2f3..ee8f601 100644 --- a/doc/ref-ooddl.xml +++ b/doc/ref-ooddl.xml @@ -5,9 +5,9 @@ %myents; ]> - - - Object Oriented Data Definition Language (OODDL) + + + Object Oriented Data Definition Language (OODDL) The Object Oriented Data Definition Language (OODDL) provides @@ -15,7 +15,7 @@ (CLOS) objects. SQL tables are mapped to CLOS objects with the SQL columns being mapped to slots of the CLOS object. - + The mapping between SQL tables and CLOS objects is defined with the macro def-view-class. SQL @@ -59,11 +59,11 @@ Slots - + slot VIEW-DATABASE is of type (OR NULL DATABASE) which stores the associated database for the instance. - + @@ -78,14 +78,14 @@ Value Type Fixnum - + Initial Value 255 - Description + Description If a slot of a class defined by def-view-class is of the type @@ -105,9 +105,9 @@ (c :type varchar)))) => #<Standard-Db-Class S80 {480A431D}> -(create-view-from-class 's80) -=> -(table-exists-p [s80]) +(create-view-from-class 's80) +=> +(table-exists-p [s80]) => T @@ -193,7 +193,7 @@ (def-view-class foo () ((a :type (string 80)))) => #<Standard-Db-Class FOO {4807F7CD}> (create-view-from-class 'foo) -=> +=> (list-tables) => ("FOO") @@ -453,7 +453,7 @@ wide. [not supported by all database backends] - bigint - An integer column + bigint - An integer column 64-bits wide. [not supported by all database backends] @@ -495,7 +495,7 @@ keyword - stores a keyword - + symbol - stores a symbol list - stores a list by writing @@ -508,7 +508,7 @@ similarly to list - + @@ -587,6 +587,16 @@ are converted to underscore characters. + + + :normalisedp - specifies whether + this class uses normalised inheritance from parent classes. + Defaults to nil, i.e. non-normalised schemas. When true, + SQL database tables that map to this class and parent + classes are joined on their primary keys to get the full + set of database columns for this class. + + @@ -606,6 +616,105 @@ this class. + Normalised inheritance schemas + + Specifying that :normalisedp is T + tells &clsql; to normalise the database schema for inheritance. + What this means is shown in the examples below. + + + + With :normalisedp equal to NIL + (the default) the class inheritance would result in the following: + + +(def-view-class node () + ((title :accessor title :initarg :title :type (varchar 240)))) + +SQL table NODE: ++-------+--------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------+--------------+------+-----+---------+-------+ +| TITLE | varchar(240) | YES | | NULL | | ++-------+--------------+------+-----+---------+-------+ + +(def-view-class user (node) + ((user-id :accessor user-id :initarg :user-id + :type integer :db-kind :key :db-constraints (:not-null)) + (nick :accessor nick :initarg :nick :type (varchar 64)))) + +SQL table USER: ++---------+--------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++---------+--------------+------+-----+---------+-------+ +| USER_ID | int(11) | NO | PRI | | | +| NICK | varchar(64) | YES | | NULL | | +| TITLE | varchar(240) | YES | | NULL | | ++---------+--------------+------+-----+---------+-------+ + + + + Using :normalisedp T, both + view-classes need a primary key to join them on: + + +(def-view-class node () + ((node-id :accessor node-id :initarg :node-id + :type integer :db-kind :key + :db-constraints (:not-null)) + (title :accessor title :initarg :title :type (varchar 240)))) + +SQL table NODE: ++---------+--------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++---------+--------------+------+-----+---------+-------+ +| NODE_ID | int(11) | NO | PRI | | | +| TITLE | varchar(240) | YES | | NULL | | ++---------+--------------+------+-----+---------+-------+ + +(def-view-class user (node) + ((user-id :accessor user-id :initarg :user-id + :type integer :db-kind :key :db-constraints (:not-null)) + (nick :accessor nick :initarg :nick :type (varchar 64))) + (:normalisedp t)) + +SQL table USER: ++---------+-------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++---------+-------------+------+-----+---------+-------+ +| USER_ID | int(11) | NO | PRI | | | +| NICK | varchar(64) | YES | | NULL | | ++---------+-------------+------+-----+---------+-------+ + + + + In this second case, all slots of the view-class 'node + are also available in view-class 'user, and can be used + as one would expect. For example, with the above normalised + view-classes 'node and 'user, and SQL tracing turned on: + + +CLSQL> (setq test-user (make-instance 'user :node-id 1 :nick "test-user" + :title "This is a test user")) +# + +CLSQL> (update-records-from-instance test-user :database db) +;; .. => INSERT INTO NODE (NODE_ID,TITLE) VALUES (1,'This is a test user') +;; .. <= T +;; .. => INSERT INTO USER (USER_ID,NICK) VALUES (1,'test-user') +;; .. <= T +1 + +CLSQL> (node-id test-user) +1 + +CLSQL> (title test-user) +"This is a test user" + +CLSQL> (nick test-user) +"test-user" + + Examples @@ -621,7 +730,7 @@ (birthday :type clsql:wall-time :initarg :birthday) (bd-utime :type clsql:universal-time :initarg :bd-utime) (hobby :db-kind :virtual :initarg :hobby :initform nil))) - + (def-view-class employee (person) ((emplid :db-kind :key @@ -853,11 +962,11 @@ Examples (list-tables) -=> ("FOO" "BAR") +=> ("FOO" "BAR") (drop-view-from-class 'foo) -=> +=> (list-tables) -=> ("BAR") +=> ("BAR") @@ -892,7 +1001,7 @@ Notes - None. + None. @@ -965,7 +1074,7 @@ (list-classes) => (#<clsql-sys::standard-db-class big> #<clsql-sys::standard-db-class employee-address> - #<clsql-sys::standard-db-class address> #<clsql-sys::standard-db-class company> + #<clsql-sys::standard-db-class address> #<clsql-sys::standard-db-class company> #<clsql-sys::standard-db-class employee>) (list-classes :test #'(lambda (c) (> (length (symbol-name (class-name c))) 3))) @@ -1005,10 +1114,10 @@ Notes - None. + None. - +