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: db-interface.lisp 9123 2004-04-21 20:34:42Z kevin $
  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)
  20
  21 (defgeneric select (&rest args)
  22   (:documentation
  23    "The function SELECT selects data from DATABASE, which has a
  24 default value of *DEFAULT-DATABASE*, given the constraints
  25 specified by the rest of the ARGS. It returns a list of objects
  26 as specified by SELECTIONS. By default, the objects will each be
  27 represented as lists of attribute values. The argument SELECTIONS
  28 consists either of database identifiers, type-modified database
  29 identifiers or literal strings. A type-modifed database
  30 identifier is an expression such as [foo :string] which means
  31 that the values in column foo are returned as Lisp strings.  The
  32 FLATP argument, which has a default value of nil, specifies if
  33 full bracketed results should be returned for each matched
  34 entry. If FLATP is nil, the results are returned as a list of
  35 lists. If FLATP is t, the results are returned as elements of a
  36 list, only if there is only one result per row. The arguments
  37 ALL, SET-OPERATION, DISTINCT, FROM, WHERE, GROUP-BY, HAVING and
  38 ORDER-by have the same function as the equivalent SQL expression.
  39 The SELECT function is common across both the functional and
  40 object-oriented SQL interfaces. If selections refers to View
  41 Classes then the select operation becomes object-oriented. This
  42 means that SELECT returns a list of View Class instances, and
  43 SLOT-VALUE becomes a valid SQL operator for use within the where
  44 clause. In the View Class case, a second equivalent select call
  45 will return the same View Class instance objects. If REFRESH is
  46 true, then existing instances are updated if necessary, and in
  47 this case you might need to extend the hook INSTANCE-REFRESHED.
  48 The default value of REFRESH is nil. SQL expressions used in the
  49 SELECT function are specified using the square bracket syntax,
  50 once this syntax has been enabled using
  51 ENABLE-SQL-READER-SYNTAX."))
  52
  53 (defgeneric update-record-from-slot (object slot &key database)
  54   (:documentation
  55    "The generic function UPDATE-RECORD-FROM-SLOT updates an individual
  56 data item in the column represented by SLOT. The DATABASE is only used
  57 if OBJECT is not yet associated with any database, in which case a
  58 record is created in DATABASE. Only SLOT is initialized in this case;
  59 other columns in the underlying database receive default values. The
  60 argument SLOT is the CLOS slot name; the corresponding column names
  61 are derived from the View Class definition."))
  62
  63 (defgeneric update-record-from-slots (object slots &key database)
  64   (:documentation
  65    "The generic function UPDATE-RECORD-FROM-SLOTS updates data in the
  66 columns represented by SLOTS. The DATABASE is only used if OBJECT is
  67 not yet associated with any database, in which case a record is
  68 created in DATABASE. Only slots are initialized in this case; other
  69 columns in the underlying database receive default values. The
  70 argument SLOTS contains the CLOS slot names; the corresponding column
  71 names are derived from the view class definition."))
  72
  73 (defgeneric update-records-from-instance (object &key database)
  74   (:documentation
  75    "Using an instance of a view class, OBJECT, update the database
  76 table that stores its instance data. If OBJECT is already associated
  77 with a database, that database is used, and DATABASE is ignored. If
  78 OBJECT is not yet associated with a database, a record is created for
  79 instance in the appropriate table of DATABASE and the instance becomes
  80 associated with that database."))
  81
  82 (defgeneric delete-instance-records (instance)
  83   (:documentation
  84    "Deletes the records represented by INSTANCE from the database
  85 associated with it. If INSTANCE has no associated database, an error
  86 is signalled."))
  87
  88 (defgeneric update-instance-from-records (instance &key database)
  89   (:documentation
  90    "The generic function UPDATE-INSTANCE-FROM-RECORDS updates the
  91 values in the slots of the View Class instance INSTANCE using the data
  92 in the database DATABASE which defaults to the DATABASE that instance
  93 is associated with, or the value of *DEFAULT-DATABASE*. If INSTANCE is
  94 associated with a database, then DATABASE must be that same
  95 database. The update is not recursive on joins. Join slots (that is,
  96 slots with :db-kind :join ) are updated, but the joined objects are
  97 not updated."))
  98
  99 (defgeneric update-slot-from-record (instance slot &key database)
 100   (:documentation
 101    "Updates the value in the slot SLOT of the View Class instance
 102 INSTANCE using the data in the database DATABASE which defaults to the
 103 database that INSTANCE is associated with, or the value of
 104 *DEFAULT-DATABASE*. The argument SLOT is the CLOS slot name, the
 105 corresponding column names are derived from the View Class
 106 definition. The update is not recursive on joins. Join slots (that is,
 107 slots with :db-kind :join) are updated, but the joined objects are not
 108 updated."))
 109
 110 (defgeneric instance-refreshed (instance)
 111   (:documentation
 112    "The function INSTANCE-REFRESHED is called inside SELECT when its
 113 REFRESH argument is true and the instance INSTANCE has just been
 114 updated. The supplied method on STANDARD-DB-OBJECT does nothing. If
 115 your application needs to take action when a View Class instance has
 116 been updated by (select ... :refresh t) then add an INSTANCE-REFRESH
 117 method specializing on your subclass of STANDARD-DB-OBJECT."))
 118
 119 (defgeneric update-slot-with-null (instance slotname slotdef)
 120   (:documentation "Called to update a slot when its column has a NULL
 121 value.  If nulls are allowed for the column, the slot's value will be
 122 nil, otherwise its value will be set to the result of calling
 123 DATABASE-NULL-VALUE on the type of the slot."))
 124
 125 (defgeneric output-sql (expr database)
 126   )
 127
 128 (defgeneric output-sql-hash-key (arg database)
 129   )
 130
 131 (defgeneric collect-table-refs (sql)
 132   )
 133 (defgeneric database-output-sql (arg database)
 134   )
 135 (defgeneric database-constraint-description  (constraint database)
 136   )
 137 (defgeneric database-pkey-constraint  (class database)
 138   )
 139 (defgeneric database-constraint-statement  (constraints database)
 140   )
 141 (defgeneric %install-class  (class database)
 142   )
 143 (defgeneric database-generate-column-definition  (class slotdef database)
 144   )
 145 (defgeneric update-slot-from-db  (instance slotdef val)
 146   )
 147 (defgeneric key-value-from-db  (slotdef value database)
 148   )
 149 (defgeneric get-slot-values-from-view  (obj slotdeflist values)
 150   )
 151 (defgeneric database-output-sql-as-type  (type val database)
 152   )
 153 (defgeneric read-sql-value  (val type database)
 154   )
 155 (defgeneric add-to-relation  (target slot-name value)
 156   )
 157 (defgeneric remove-from-relation  (target slot-name value)
 158   )
 159