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