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