Improved documentation of normalized classes and changelog entry
authorRuss Tyndall <russ@acceleration.net>
Sat, 24 Nov 2012 17:39:01 +0000 (12:39 -0500)
committerNathan Bird <nathan@acceleration.net>
Wed, 5 Dec 2012 23:00:23 +0000 (18:00 -0500)
ChangeLog
LATEST-TEST-RESULTS
doc/ref-ooddl.xml
sql/ooddl.lisp
sql/oodml.lisp
sql/utils.lisp

index f94cb36..afd21ed 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,42 @@
+2012-11-20 Russ Tyndall <russ@acceleration.net>
+       ## Large refactoring of sql/oodml.lisp and surrounding code
+       * cleaned up update-records-from-* to utilize a single codepath
+         previously there was much duplicate code
+       * tried to further unify direct/effective slot-defs
+       * cleaned up much of the normalized classes code to be more
+         consistent in how it operated, and the code it used (less
+         copy/paste more functions)
+       * tried to standardize iteration a bit, previously almost all
+         of the iteration constructs in CL were used. Tried to
+         standardize on loop for readability / cohesiveness
+       * made functions to more easily look up particular slots, since
+         this was being done differently in each function
+       * added more doc-strings and updated documentation about
+         normalized classes
+       * inner-joins that are referenced in where clauses are no longer
+         added to the select table list (since they are also referenced
+         in the join position and this led to sql errors)
+       * collect-table-references methods added for sql-ident-table and
+         list
+
+       ## Semantic changes
+       * disallow where-less updates from objects (ie cannot call
+          update-records-from* with a keyless object)
+       * ordered-class-direct-slots now returns direct-slot-definitions
+         instead of effective-slot-definitions (as per name)
+       * direct-slot-definitions now contain the db-info hash table (same
+         as effective slots)
+       * removed this-class arg from update-instance-from-records - used to
+         be used for normalized code, no longer needed for that.
+       * find-all - bug fixes in table references, previously where clauses
+         surrounded by a list would have none of their references added to
+         the select. This was being exploited by certain code paths.  Now
+         all where clauses are searched
+         - No longer includes order-by and distinct as columns in the select
+           list.  The values seemed to be ignored in every code path and distinct
+           seemed to be intended to be used as a boolean anyway
+
+
 2012-11-20  Nathan Bird  <nathan@acceleration.net>
 
        * update-objects-joins - changed the default of slot from t (which
index aa5c2cb..71b6115 100644 (file)
@@ -1,4 +1,4 @@
-Note from Russ Tyndall <russ@acceleration.net> 2012-09-04 :
+Note from Russ Tyndall <russ@acceleration.net> 2012-11-24 :
 
 This is the current results of running the test suite against all the database
 backends I have accessible, on SBCL / UBUNTU64bit.  It would be great to
@@ -35,11 +35,10 @@ or not correctly skipping those tests
    :TIME/PG/FDML/USEC, :FDML/SELECT/36, :FDDL/CACHE-TABLE-QUERIES/1.
 
 :sqlite3
-12 out of 267 total tests failed: :FDDL/CACHE-TABLE-QUERIES/1, :FDDL/INDEX/3, 
-   :FDDL/VIEW/2, :FDDL/ATTRIBUTES/8, :FDDL/ATTRIBUTES/7, :FDDL/ATTRIBUTES/6, 
+9 out of 267 total tests failed: :FDDL/CACHE-TABLE-QUERIES/1, :FDDL/INDEX/3, 
+   :FDDL/ATTRIBUTES/8, :FDDL/ATTRIBUTES/7, :FDDL/ATTRIBUTES/6, 
    :FDDL/ATTRIBUTES/5, :FDDL/ATTRIBUTES/4, :FDDL/ATTRIBUTES/3, 
-   :FDDL/ATTRIBUTES/2, :FDDL/ATTRIBUTES/1, :FDDL/TABLE/3.
-
+   :FDDL/ATTRIBUTES/2.
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
 Version 3.0.0 run on August 3, 2004 on x86, x86_64, and PowerPC platforms
index 03ab9aa..891e213 100644 (file)
@@ -717,6 +717,25 @@ CLSQL> (title test-user)
 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>
index bb2405b..50c37a6 100644 (file)
@@ -57,6 +57,7 @@
 
 (defmethod (setf slot-value-using-class) (new-value (class standard-db-class)
                                           instance slot-def)
+  "Handle auto syncing values to the database if *db-auto-sync* is t"
   (declare (ignore new-value))
   (let* ((slot-name (%svuc-slot-name slot-def))
          (slot-object (%svuc-slot-object slot-def class))
index 057031c..109fb4c 100644 (file)
   "Makes sure that if a class has unfilled slots that claim to have a default,
    that we retrieve those defaults from the database
 
-   TODO: use update slots-from-record instead to batch this!"
+   TODO: use update-slots-from-record (doesnt exist) instead to batch this!"
   (loop for class-and-slots in (listify classes-and-slots)
         do (loop for slot in (slot-defs class-and-slots)
                  do (when (and (slot-has-default-p slot)
index 3162a7d..39ee349 100644 (file)
@@ -17,6 +17,8 @@
 (in-package #:clsql-sys)
 
 (defmacro defaulting (&rest place-value-plist)
+  "for places and values (as an &rest plist)
+   if place-n is null set it to value-n"
   `(progn
     ,@(loop for (place value . rest) on place-value-plist by #'cddr
             collect `(unless ,place (setf ,place ,value)))))