X-Git-Url: http://git.kpe.io/?p=clsql.git;a=blobdiff_plain;f=sql%2Fgenerics.lisp;h=d513bd34c1f27ab526d818279a185b5dc892e582;hp=0fa8abe68962a60287a2fd7c1d97669270b8f88a;hb=e622ee6f4bf2b9fe81af59d566e651c983a4833b;hpb=b43e20a168dae4ae9d176ebc0fbf18ea6e4517dc diff --git a/sql/generics.lisp b/sql/generics.lisp index 0fa8abe..d513bd3 100644 --- a/sql/generics.lisp +++ b/sql/generics.lisp @@ -7,7 +7,7 @@ ;;;; Author: Kevin M. Rosenberg based on ;;;; Created: Apr 2004 ;;;; -;;;; $Id: db-interface.lisp 9123 2004-04-21 20:34:42Z kevin $ +;;;; $Id$ ;;;; ;;;; This file, part of CLSQL, is Copyright (c) 2002-2004 by Kevin M. Rosenberg ;;;; @@ -16,105 +16,108 @@ ;;;; (http://opensource.franz.com/preamble.html), also known as the LLGPL. ;;;; ************************************************************************* -(in-package #:clsql) +(in-package #:clsql-sys) -(defgeneric select (&rest args) + +;; FDML + +(defgeneric execute-command (expression &key database) + (:documentation + "Executes the SQL command EXPRESSION, which may be an SQL +expression or a string representing any SQL statement apart from +a query, on the supplied DATABASE which defaults to +*DEFAULT-DATABASE*.")) + + +(defgeneric query (query-expression &key database result-types flatp field-names) (:documentation - "The function SELECT selects data from DATABASE, which has a -default value of *DEFAULT-DATABASE*, given the constraints -specified by the rest of the ARGS. It returns a list of objects -as specified by SELECTIONS. By default, the objects will each be -represented as lists of attribute values. The argument SELECTIONS -consists either of database identifiers, type-modified database -identifiers or literal strings. A type-modifed database -identifier is an expression such as [foo :string] which means -that the values in column foo are returned as Lisp strings. The -FLATP argument, which has a default value of nil, specifies if -full bracketed results should be returned for each matched -entry. If FLATP is nil, the results are returned as a list of -lists. If FLATP is t, the results are returned as elements of a -list, only if there is only one result per row. The arguments -ALL, SET-OPERATION, DISTINCT, FROM, WHERE, GROUP-BY, HAVING and -ORDER-by have the same function as the equivalent SQL expression. -The SELECT function is common across both the functional and -object-oriented SQL interfaces. If selections refers to View -Classes then the select operation becomes object-oriented. This -means that SELECT returns a list of View Class instances, and -SLOT-VALUE becomes a valid SQL operator for use within the where -clause. In the View Class case, a second equivalent select call -will return the same View Class instance objects. If REFRESH is -true, then existing instances are updated if necessary, and in -this case you might need to extend the hook INSTANCE-REFRESHED. -The default value of REFRESH is nil. SQL expressions used in the -SELECT function are specified using the square bracket syntax, -once this syntax has been enabled using -ENABLE-SQL-READER-SYNTAX.")) + "Executes the SQL query expression QUERY-EXPRESSION, which may +be an SQL expression or a string, on the supplied DATABASE which +defaults to *DEFAULT-DATABASE*. RESULT-TYPES is a list of symbols +which specifies the lisp type for each field returned by +QUERY-EXPRESSION. If RESULT-TYPES is nil all results are returned +as strings whereas the default value of :auto means that the lisp +types are automatically computed for each field. FIELD-NAMES is t +by default which means that the second value returned is a list +of strings representing the columns selected by +QUERY-EXPRESSION. If FIELD-NAMES is nil, the list of column names +is not returned as a second value. FLATP has a default value of +nil which means that the results are returned as a list of +lists. If FLATP is t and only one result is returned for each +record selected by QUERY-EXPRESSION, the results are returned as +elements of a list.")) + + +;; OODML (defgeneric update-record-from-slot (object slot &key database) (:documentation - "The generic function UPDATE-RECORD-FROM-SLOT updates an individual -data item in the column represented by SLOT. The DATABASE is only used -if OBJECT is not yet associated with any database, in which case a -record is created in DATABASE. Only SLOT is initialized in this case; -other columns in the underlying database receive default values. The -argument SLOT is the CLOS slot name; the corresponding column names -are derived from the View Class definition.")) + "Updates the value stored in the column represented by the +slot, specified by the CLOS slot name SLOT, of View Class +instance OBJECT. DATABASE defaults to *DEFAULT-DATABASE* and +specifies the database in which the update is made only if OBJECT +is not associated with a database. In this case, a record is +created in DATABASE and the attribute represented by SLOT is +initialised from the value of the supplied slots with other +attributes having default values. Furthermore, OBJECT becomes +associated with DATABASE.")) (defgeneric update-record-from-slots (object slots &key database) (:documentation - "The generic function UPDATE-RECORD-FROM-SLOTS updates data in the -columns represented by SLOTS. The DATABASE is only used if OBJECT is -not yet associated with any database, in which case a record is -created in DATABASE. Only slots are initialized in this case; other -columns in the underlying database receive default values. The -argument SLOTS contains the CLOS slot names; the corresponding column -names are derived from the view class definition.")) + "Updates the values stored in the columns represented by the +slots, specified by the CLOS slot names SLOTS, of View Class +instance OBJECT. DATABASE defaults to *DEFAULT-DATABASE* and +specifies the database in which the update is made only if OBJECT +is not associated with a database. In this case, a record is +created in the appropriate table of DATABASE and the attributes +represented by SLOTS are initialised from the values of the +supplied slots with other attributes having default +values. Furthermore, OBJECT becomes associated with DATABASE.")) (defgeneric update-records-from-instance (object &key database) (:documentation - "Using an instance of a view class, OBJECT, update the database -table that stores its instance data. If OBJECT is already associated -with a database, that database is used, and DATABASE is ignored. If -OBJECT is not yet associated with a database, a record is created for -instance in the appropriate table of DATABASE and the instance becomes -associated with that database.")) - -(defgeneric delete-instance-records (instance) + "Using an instance of a View Class, OBJECT, update the table +that stores its instance data. DATABASE defaults to +*DEFAULT-DATABASE* and specifies the database in which the update +is made only if OBJECT is not associated with a database. In this +case, a record is created in the appropriate table of DATABASE +using values from the slot values of OBJECT, and OBJECT becomes +associated with DATABASE.")) + +(defgeneric delete-instance-records (object) (:documentation - "Deletes the records represented by INSTANCE from the database -associated with it. If INSTANCE has no associated database, an error -is signalled.")) + "Deletes the records represented by OBJECT in the appropriate +table of the database associated with OBJECT. If OBJECT is not +yet associated with a database, an error is signalled.")) -(defgeneric update-instance-from-records (instance &key database) +(defgeneric update-instance-from-records (object &key database) (:documentation - "The generic function UPDATE-INSTANCE-FROM-RECORDS updates the -values in the slots of the View Class instance INSTANCE using the data -in the database DATABASE which defaults to the DATABASE that instance -is associated with, or the value of *DEFAULT-DATABASE*. If INSTANCE is -associated with a database, then DATABASE must be that same -database. The update is not recursive on joins. Join slots (that is, -slots with :db-kind :join ) are updated, but the joined objects are -not updated.")) - -(defgeneric update-slot-from-record (instance slot &key database) + "Updates the slot values of the View Class instance OBJECT +using the attribute values of the appropriate table of DATABASE +which defaults to the database associated with OBJECT or, if +OBJECT is not associated with a database, *DEFAULT-DATABASE*. +Join slots are updated but instances of the class on which the +join is made are not updated.")) + +(defgeneric update-slot-from-record (object slot &key database) (:documentation - "Updates the value in the slot SLOT of the View Class instance -INSTANCE using the data in the database DATABASE which defaults to the -database that INSTANCE is associated with, or the value of -*DEFAULT-DATABASE*. The argument SLOT is the CLOS slot name, the -corresponding column names are derived from the View Class -definition. The update is not recursive on joins. Join slots (that is, -slots with :db-kind :join) are updated, but the joined objects are not + "Updates the slot value, specified by the CLOS slot name SLOT, +of the View Class instance OBJECT using the attribute values of +the appropriate table of DATABASE which defaults to the database +associated with OBJECT or, if OBJECT is not associated with a +database, *DEFAULT-DATABASE*. Join slots are updated but +instances of the class on which the join is made are not updated.")) -(defgeneric instance-refreshed (instance) +(defgeneric instance-refreshed (object) (:documentation - "The function INSTANCE-REFRESHED is called inside SELECT when its -REFRESH argument is true and the instance INSTANCE has just been -updated. The supplied method on STANDARD-DB-OBJECT does nothing. If -your application needs to take action when a View Class instance has -been updated by (select ... :refresh t) then add an INSTANCE-REFRESH -method specializing on your subclass of STANDARD-DB-OBJECT.")) + "Provides a hook which is called within an object oriented +call to SELECT with a non-nil value of REFRESH when the View +Class instance OBJECT has been updated from the database. A +method specialised on STANDARD-DB-OBJECT is provided which has no +effects. Methods specialised on particular View Classes can be +used to specify any operations that need to be made on View +Classes instances which have been updated in calls to SELECT.")) (defgeneric update-slot-with-null (instance slotname slotdef) (:documentation "Called to update a slot when its column has a NULL @@ -148,12 +151,8 @@ DATABASE-NULL-VALUE on the type of the slot.")) ) (defgeneric get-slot-values-from-view (obj slotdeflist values) ) -(defgeneric database-output-sql-as-type (type val database) - ) -(defgeneric read-sql-value (val type database) - ) -(defgeneric add-to-relation (target slot-name value) +(defgeneric database-output-sql-as-type (type val database db-type) ) -(defgeneric remove-from-relation (target slot-name value) +(defgeneric read-sql-value (val type database db-type) )