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