;;;; 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
;;;;
;;;; (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
)
(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)
)
projects / clsql.git / blobdiff