sql/generics.lisp

   1 ;;;; -*- Mode: LISP; Syntax: ANSI-Common-Lisp; Base: 10 -*-
   2 ;;;; *************************************************************************
   3 ;;;; FILE IDENTIFICATION
   4 ;;;;
   5 ;;;; Name:     generics.lisp
   6 ;;;; Purpose:  Generic function definitions for DB interfaces
   7 ;;;; Author:   Kevin M. Rosenberg
   8 ;;;; Created:  Apr 2004
   9 ;;;;
  10 ;;;; This file, part of CLSQL, is Copyright (c) 2004-2010 by Kevin M. Rosenberg
  11 ;;;;
  12 ;;;; CLSQL users are granted the rights to distribute and use this software
  13 ;;;; as governed by the terms of the Lisp Lesser GNU Public License
  14 ;;;; (http://opensource.franz.com/preamble.html), also known as the LLGPL.
  15 ;;;; *************************************************************************
  16
  17 (in-package #:clsql-sys)
  18
  19
  20 ;; FDML
  21 (defgeneric choose-database-for-instance (object &optional database)
  22   (:documentation "Used by the oodml functions to select which
  23  database object to use. Chooses the database associated with the
  24  object primarily, falls back to the database provided as an argument
  25  or the *DEFAULT-DATABASE*."))
  26
  27 (defgeneric execute-command (expression &key database)
  28   (:documentation
  29    "Executes the SQL command EXPRESSION, which may be an SQL
  30 expression or a string representing any SQL statement apart from
  31 a query, on the supplied DATABASE which defaults to
  32 *DEFAULT-DATABASE*."))
  33
  34
  35 (defgeneric query (query-expression &key database result-types flatp field-names)
  36   (:documentation
  37    "Executes the SQL query expression QUERY-EXPRESSION, which may
  38 be an SQL expression or a string, on the supplied DATABASE which
  39 defaults to *DEFAULT-DATABASE*. RESULT-TYPES is a list of symbols
  40 which specifies the lisp type for each field returned by
  41 QUERY-EXPRESSION. If RESULT-TYPES is nil all results are returned
  42 as strings whereas the default value of :auto means that the lisp
  43 types are automatically computed for each field. FIELD-NAMES is t
  44 by default which means that the second value returned is a list
  45 of strings representing the columns selected by
  46 QUERY-EXPRESSION. If FIELD-NAMES is nil, the list of column names
  47 is not returned as a second value. FLATP has a default value of
  48 nil which means that the results are returned as a list of
  49 lists. If FLATP is t and only one result is returned for each
  50 record selected by QUERY-EXPRESSION, the results are returned as
  51 elements of a list."))
  52
  53
  54 ;; OODML
  55
  56 (defgeneric update-record-from-slot (object slot &key database)
  57   (:documentation
  58    "Updates the value stored in the column represented by the
  59 slot, specified by the CLOS slot name SLOT, of View Class
  60 instance OBJECT. DATABASE defaults to *DEFAULT-DATABASE* and
  61 specifies the database in which the update is made only if OBJECT
  62 is not associated with a database. In this case, a record is
  63 created in DATABASE and the attribute represented by SLOT is
  64 initialised from the value of the supplied slots with other
  65 attributes having default values. Furthermore, OBJECT becomes
  66 associated with DATABASE."))
  67
  68 (defgeneric update-record-from-slots (object slots &key database)
  69   (:documentation
  70    "Updates the values stored in the columns represented by the
  71 slots, specified by the CLOS slot names SLOTS, of View Class
  72 instance OBJECT. DATABASE defaults to *DEFAULT-DATABASE* and
  73 specifies the database in which the update is made only if OBJECT
  74 is not associated with a database. In this case, a record is
  75 created in the appropriate table of DATABASE and the attributes
  76 represented by SLOTS are initialised from the values of the
  77 supplied slots with other attributes having default
  78 values. Furthermore, OBJECT becomes associated with DATABASE."))
  79
  80 (defgeneric update-records-from-instance (object &key database)
  81   (:documentation
  82    "Using an instance of a View Class, OBJECT, update the table
  83 that stores its instance data. DATABASE defaults to
  84 *DEFAULT-DATABASE* and specifies the database in which the update
  85 is made only if OBJECT is not associated with a database. In this
  86 case, a record is created in the appropriate table of DATABASE
  87 using values from the slot values of OBJECT, and OBJECT becomes
  88 associated with DATABASE."))
  89
  90 (defgeneric delete-instance-records (object &key database)
  91   (:documentation
  92    "Deletes the records represented by OBJECT in the appropriate
  93 table of the database associated with OBJECT. If OBJECT is not
  94 yet associated with a database, an error is signalled."))
  95
  96 (defgeneric update-instance-from-records (object &key database)
  97   (:documentation
  98    "Updates the slot values of the View Class instance OBJECT
  99 using the attribute values of the appropriate table of DATABASE
 100 which defaults to the database associated with OBJECT or, if
 101 OBJECT is not associated with a database, *DEFAULT-DATABASE*.
 102 Join slots are updated but instances of the class on which the
 103 join is made are not updated."))
 104
 105 (defgeneric update-slot-from-record (object slot &key database)
 106   (:documentation
 107    "Updates the slot value, specified by the CLOS slot name SLOT,
 108 of the View Class instance OBJECT using the attribute values of
 109 the appropriate table of DATABASE which defaults to the database
 110 associated with OBJECT or, if OBJECT is not associated with a
 111 database, *DEFAULT-DATABASE*.  Join slots are updated but
 112 instances of the class on which the join is made are not
 113 updated."))
 114
 115 (defgeneric instance-refreshed (object)
 116   (:documentation
 117    "Provides a hook which is called within an object oriented
 118 call to SELECT with a non-nil value of REFRESH when the View
 119 Class instance OBJECT has been updated from the database. A
 120 method specialised on STANDARD-DB-OBJECT is provided which has no
 121 effects. Methods specialised on particular View Classes can be
 122 used to specify any operations that need to be made on View
 123 Classes instances which have been updated in calls to SELECT."))
 124
 125 (defgeneric update-slot-with-null (instance slotdef)
 126   (:documentation "Called to update a slot when its column has a NULL
 127 value.  If nulls are allowed for the column, the slot's value will be
 128 nil, otherwise its value will be set to the result of calling
 129 DATABASE-NULL-VALUE on the type of the slot."))
 130
 131 (defgeneric database-pkey-constraint  (class database)
 132   )
 133 (defgeneric %install-class  (class database &key transactions)
 134   )
 135 (defgeneric database-generate-column-definition  (class slotdef database)
 136   )
 137 (defgeneric update-slot-from-db  (instance slotdef val)
 138   )
 139 (defgeneric key-value-from-db  (slotdef value database)
 140   )
 141 (defgeneric get-slot-values-from-view  (obj slotdeflist values)
 142   )
 143 (defgeneric database-output-sql-as-type  (type val database db-type)
 144   )
 145 (defgeneric read-sql-value  (val type database db-type)
 146   )
 147 (defgeneric database-add-autoincrement-sequence (class database)
 148   (:method (class database) nil)
 149   (:documentation "If a database needs to add a sequence for its
 150     autoincrement to work, this is where it should go.  Default is
 151     that it doesnt so just return nil"))
 152 (defgeneric database-remove-autoincrement-sequence (class database)
 153   (:method (class database) nil)
 154   (:documentation "If a database needs to add a sequence for its
 155     autoincrement to work, this is where it should go.  Default is
 156     that it doesnt so just return nil"))
 157 (defgeneric auto-increment-sequence-name (class slotdef database)
 158   (:documentation "The sequence name to create for this autoincremnt column on this class
 159    if returns nil, there is no associated sequence "))
 160
 161 (defmethod auto-increment-sequence-name :around (class slot database)
 162   (when (auto-increment-column-p slot database)
 163     (call-next-method)))
 164
 165 (defgeneric database-last-auto-increment-id (database table column)
 166   )
 167
 168
 169
 170 ;; Generation of SQL strings from lisp expressions
 171
 172 (defgeneric output-sql (expr database)
 173   (:documentation "Writes an SQL string appropriate for DATABASE
 174   and corresponding to the lisp expression EXPR to
 175   *SQL-STREAM*. The function SQL-OUTPUT is a top-level call for
 176   generating SQL strings which initialises *SQL-STREAM*, calls
 177   OUTPUT-SQL and reads the generated SQL string from
 178   *SQL-STREAM*."))
 179
 180 (defgeneric database-output-sql (expr database)
 181   (:documentation "Returns an SQL string appropriate for DATABASE
 182   and corresponding to the lisp expression
 183   EXPR. DATABASE-OUTPUT-SQL is called by OUTPUT-SQL when no more
 184   specific method exists for EXPR."))
 185
 186 (defgeneric output-sql-hash-key (expr database)
 187   (:documentation "Returns a list (or other object suitable for
 188 use as the key of an EQUAL hash table) which uniquely identifies
 189 the arguments EXPR and DATABASE."))
 190
 191 (defgeneric collect-table-refs (sql)
 192   )
 193
 194 (defgeneric database-constraint-statement  (constraints database)
 195   )
 196
 197 (defgeneric database-translate-constraint (constraint database)
 198   (:documentation "Given a column constraint returns its
 199 database-specific name. For example, auto-increment constraints can
 200 have different names in different database engines."))
 201
 202 (defgeneric filter-select-list ( view-class clsql-sys::select-list database)
 203   (:documentation
 204    "Gives fine grained control over sql to be executed and mapped to slots
 205     called with a dummy instance (so that class precedence can be used)")
 206   )