1 ;;;; -*- Mode: LISP; Syntax: ANSI-Common-Lisp; Base: 10 -*-
2 ;;;; *************************************************************************
3 ;;;; FILE IDENTIFICATION
5 ;;;; Name: generics.lisp
6 ;;;; Purpose: Generic function definitions for DB interfaces
7 ;;;; Author: Kevin M. Rosenberg
10 ;;;; This file, part of CLSQL, is Copyright (c) 2004-2010 by Kevin M. Rosenberg
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 ;;;; *************************************************************************
17 (in-package #:clsql-sys)
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*."))
27 (defgeneric execute-command (expression &key database)
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*."))
35 (defgeneric query (query-expression &key database result-types flatp field-names)
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."))
56 (defgeneric update-record-from-slot (object slot &key database)
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."))
68 (defgeneric update-record-from-slots (object slots &key database)
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."))
80 (defgeneric update-records-from-instance (object &key database this-class)
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."))
90 (defgeneric delete-instance-records (object &key database)
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."))
96 (defgeneric update-instance-from-records (object &key database this-class)
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."))
105 (defgeneric update-slot-from-record (object slot &key database)
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
115 (defgeneric instance-refreshed (object)
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."))
125 (defgeneric update-slot-with-null (instance slotname 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."))
131 (defgeneric database-pkey-constraint (class database)
133 (defgeneric %install-class (class database &key transactions)
135 (defgeneric database-generate-column-definition (class slotdef database)
137 (defgeneric update-slot-from-db (instance slotdef val)
139 (defgeneric key-value-from-db (slotdef value database)
141 (defgeneric get-slot-values-from-view (obj slotdeflist values)
143 (defgeneric database-output-sql-as-type (type val database db-type)
145 (defgeneric read-sql-value (val type database db-type)
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 "))
161 (defmethod auto-increment-sequence-name :around (class slot database)
162 (when (auto-increment-column-p slot database)
165 (defgeneric database-last-auto-increment-id (database table column)
170 ;; Generation of SQL strings from lisp expressions
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
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."))
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."))
191 (defgeneric collect-table-refs (sql)
194 (defgeneric database-constraint-statement (constraints database)