Changelog and minor cleanup of yesterdays patch

[clsql.git] / doc / ref-ooddl.xml

diff --git a/doc/ref-ooddl.xml b/doc/ref-ooddl.xml
index ee8f6011f8d5a4933e8061aa086eaf0546b83a79..4a2cffa140b4600703290805f4e6352301b5af1d 100644 (file)
--- a/doc/ref-ooddl.xml
+++ b/doc/ref-ooddl.xml
@@ -589,12 +589,16 @@
          </listitem>
          <listitem>
            <para>
          </listitem>
          <listitem>
            <para>

-             <parameter>:normalisedp</parameter> - specifies whether
-          this class uses normalised inheritance from parent classes.
-          Defaults to nil, i.e. non-normalised schemas. When true,
+             <parameter>:normalizedp</parameter> - specifies whether
+          this class uses normalized inheritance from parent classes.
+          Defaults to nil, i.e. non-normalized schemas. When true,

           SQL database tables that map to this class and parent
           classes are joined on their primary keys to get the full
           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.
+          set of database columns for this class.  This means that 
+          the primary key of the base class will be copied to all 
+          subclasses as we insert so that all parent classes of an 
+          instance will have the same value in their primary key slots
+          (see tests/ds-nodes.lisp and oodml.lisp)

            </para>
          </listitem>
        </itemizedlist>
            </para>
          </listitem>
        </itemizedlist>


@@ -616,15 +620,16 @@
        this class.
       </para>
 
        this class.
       </para>
 

-      <title>Normalised inheritance schemas</title>
+      <refsect2>
+      <title>Normalized inheritance schemas</title>

       <para>
       <para>

-    Specifying that <symbol>:normalisedp</symbol> is <symbol>T</symbol>
-    tells &clsql; to normalise the database schema for inheritance.
+    Specifying that <symbol>:normalizedp</symbol> is <symbol>T</symbol>
+    tells &clsql; to normalize the database schema for inheritance.

     What this means is shown in the examples below.
       </para>
 
       <para>
     What this means is shown in the examples below.
       </para>
 
       <para>

-    With <symbol>:normalisedp</symbol> equal to <symbol>NIL</symbol>
+    With <symbol>:normalizedp</symbol> equal to <symbol>NIL</symbol>

     (the default) the class inheritance would result in the following:
       </para>
       <screen>
     (the default) the class inheritance would result in the following:
       </para>
       <screen>


@@ -654,7 +659,7 @@ SQL table USER:
       </screen>
 
       <para>
       </screen>
 
       <para>

-    Using <symbol>:normalisedp</symbol> <symbol>T</symbol>, both
+    Using <symbol>:normalizedp</symbol> <symbol>T</symbol>, both

     view-classes need a primary key to join them on:
       </para>
       <screen>
     view-classes need a primary key to join them on:
       </para>
       <screen>


@@ -676,7 +681,7 @@ SQL table 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)))
   ((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))
+  (:normalizedp t))

 
 SQL table USER:
 +---------+-------------+------+-----+---------+-------+
 
 SQL table USER:
 +---------+-------------+------+-----+---------+-------+


@@ -690,20 +695,22 @@ SQL table USER:
       <para>
         In this second case, all slots of the view-class 'node
         are also available in view-class 'user, and can be used
       <para>
         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
+        as one would expect. For example, with the above normalized

         view-classes 'node and 'user, and SQL tracing turned on:
       </para>
       <screen>
 CLSQL> (setq test-user (make-instance 'user :node-id 1 :nick "test-user"
                                             :title "This is a test user"))
         view-classes 'node and 'user, and SQL tracing turned on:
       </para>
       <screen>
 CLSQL> (setq test-user (make-instance 'user :node-id 1 :nick "test-user"
                                             :title "This is a test user"))

-#<USER {1003B392E1}>
+<![CDATA[#<USER {1003B392E1}>]]>

 
 CLSQL> (update-records-from-instance test-user :database db)
 
 CLSQL> (update-records-from-instance test-user :database db)

+<![CDATA[

 ;; .. => 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
 ;; .. => 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> (node-id test-user)
 1


@@ -714,7 +721,26 @@ CLSQL> (title test-user)
 CLSQL> (nick test-user)
 "test-user"
       </screen>
 CLSQL> (nick test-user)
 "test-user"
       </screen>

+      <para>
+        Notes from a refactor of this code.
+
+        There are many assumptions that need to be met for normalized classes to work
+
+        * The each of the classes should have its own single key column (of a different name)
+          that will contain an identical value.  EG: node has a node-id, setting which
+          is a node has a node-id and a setting-id which must be equal.  You cannot use
+          node-id as the primary key on both tables (as I would have expected).  The exception
+          to this seems to be if your class has no slots at all, then you dont need to have a
+          single key column, because your class is fully represented in the db by its parent(s)

 
 

+        * more than one parent class per normalized class should be considered experimental
+          and untested (vaya con Dios)
+
+        * There are a few code paths that just dont pay any attention to normalized classes
+          eg: delete-records-for-instance
+
+      </para>
+      </refsect2>

     </refsect1>
     <refsect1>
       <title>Examples</title>
     </refsect1>
     <refsect1>
       <title>Examples</title>