X-Git-Url: http://git.kpe.io/?p=clsql.git;a=blobdiff_plain;f=doc%2Fref-oodml.xml;h=094db326e23ce83d2140144294fd81326f03b30f;hp=76df3ec4db0f075f04561ec4a5f9f7ab45f6359f;hb=d0695ffb828519fade3aa5166236812e6144975b;hpb=4413405fd38eaba7ba6d6d8b844fef118e326c9a diff --git a/doc/ref-oodml.xml b/doc/ref-oodml.xml index 76df3ec..094db32 100644 --- a/doc/ref-oodml.xml +++ b/doc/ref-oodml.xml @@ -10,10 +10,11 @@ Object Oriented Data Manipulation Language (OODML) - Object Oriented Data Manipulation Language (OODML) provides a Common Lisp - Object System (CLOS) interface to SQL databases. View classes are defined with - the OODDL interface and objects are read and - written with the OODML. + Object Oriented Data Manipulation Language (OODML) provides a + Common Lisp Object System (CLOS) interface to SQL + databases. View classes are defined with the OODDL interface and objects are read + and written with the OODML. The main function for reading data with the OODML is the When this variable is &t; an instance is stored in the SQL database when the instance is created by - make-instance. When this variable is - &nil;, which is the default value, &clsql; behaves like - &commonsql;: instances of view classes are stored to the SQL - database only when update-record-from-slots - is called. + make-instance. Furthermore, the + appropriate database records are updated whenever the slots of + a View Class + instance are modified. + + + When this variable is &nil;, which is the default value, + &clsql; behaves like &commonsql;: instances of view classes + are stored or updated in the SQL database only when update-record-from-instance, + update-record-from-slot + or update-record-from-slots + are called. Examples (let ((instance (make-instance 'foo))) - (update-record-from-slots instance)) + (update-records-from-instance instance)) ;; is equivalent to (let ((*db-auto-sync* t)) (make-instance 'foo)) + + ;; and + + (progn + (setf (slot-value instance 'bar) "baz") + (update-record-from-slot instance 'bar)) + + ;; is equivalent to + + (let ((*db-auto-sync* t)) + (setf (slot-value instance 'bar) "baz")) @@ -92,12 +113,14 @@ See Also + update-records-from-instance + update-record-from-slot update-record-from-slots Notes - None. + This is a CLSQL extension to the CommonSQL API. @@ -147,89 +170,6 @@ - - - DELETE-INSTANCE-RECORDS - Delete SQL records represented by a view class - object. - Function - - - Syntax - - (delete-instance-records object) => - - - Arguments and Values - - - object - - - An instance of a view class. - - - - - - - Description - 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. - - - - Examples - - * (def-view-class tab () ((a :type integer :db-kind :key) (b :type string))) - #<clsql-sys::db-standard-class tab> - * (defvar obj (let ((*db-auto-sync* t)) - (make-instance 'tab :a 5 :b "the string"))) - * (start-sql-recording :type :both) - * (delete-instance-records obj) - - - - Side Effects - - Deletes data from the SQL database. - - - - Affected by - - Permissions granted by the SQL database to the user in the database connection. - - - - Exceptional Situations - - An exception may be signaled if the database connection user does not have - sufficient privileges to modify the database. - - - - See Also - - - update-records - update-records-from-instance - - - - - Notes - - Instances are referenced in the database by values stored in the key slots. If - delete-records-from-instance is called with an instance of a class that does - not contain any keys, then all records in that table will be deleted. - - - - INSTANCE-REFRESHED @@ -239,7 +179,7 @@ Syntax - (instance-refreshed object) => + instance-refreshed object => Arguments and Values @@ -248,7 +188,7 @@ object - The view class object which is being refreshed. + The View Class object which is being refreshed. @@ -258,7 +198,8 @@ Description 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 + 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 @@ -271,7 +212,29 @@ Examples - +(slot-value employee1 'email) +=> "lenin@soviet.org" +(defmethod instance-refreshed ((e employee)) + (format t "~&Details for ~A ~A have been updated from the database." + (slot-value e 'first-name) + (slot-value e 'last-name))) +=> #<Standard-Method INSTANCE-REFRESHED (EMPLOYEE) {48174D9D}> +(select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t) +=> (#<EMPLOYEE {48149995}>) +(slot-value (car *) 'email) +=> "lenin@soviet.org" +(update-records [employee] :av-pairs '(([email] "v.lenin@soviet.org")) + :where [= [emplid] 1]) +=> +(select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t) +=> (#<EMPLOYEE {48149995}>) +(slot-value (car *) 'email) +=> "lenin@soviet.org" +(select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t :refresh t) +Details for Vladamir Lenin have been updated from the database. +=> (#<EMPLOYEE {48149995}>) +(slot-value (car *) 'email) +=> "v.lenin@soviet.org" @@ -290,22 +253,29 @@ See Also - select + select + + Notes + + None. + + - + - UPDATE-INSTANCE-FROM-RECORDS - Update slot values from database. + DELETE-INSTANCE-RECORDS + Delete SQL records represented by a View Class + object. Function Syntax - (update-instance-from-records object &key database) => + delete-instance-records object => Arguments and Values @@ -314,15 +284,8 @@ object - An instance of a view class. - - - - - database - - - A database connection. + An instance of a View + Class. @@ -330,103 +293,106 @@ Description - 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. + 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. Examples - +(def-view-class tab () + ((a :initarg :a :type integer :db-kind :key) + (b :initarg :b :type string))) +=> #<Standard-Db-Class TAB {49B01845}> +(create-view-from-class 'tab) +=> +(defvar obj (let ((*db-auto-sync* t)) + (make-instance 'tab :a 5 :b "the string"))) +=> OBJ +(start-sql-recording :type :both) +=> +(delete-instance-records obj) +;; 2004-07-17 11:07:19 foo/bar/baz => DELETE FROM tab WHERE tab.a = 5 +;; 2004-07-17 11:07:19 foo/bar/baz <= T +=> Side Effects - Slot values of object may be modified. + Deletes data from the SQL database. Affected by - - Data in SQL database. - + Permissions granted by the SQL database to the user in the + database connection. Exceptional Situations - If database is not able to be read. + An exception may be signaled if the database connection user + does not have sufficient privileges to modify the database. An + error of type sql-database-error is signalled if + object is not associated with an + active database. See Also - - + + update-records + delete-records + update-records-from-instance + Notes - + Instances are referenced in the database by values stored in + the key slots. If + delete-records-from-instance is called + with an instance of a class that does not contain any keys, + then all records in that table will be deleted. - + - UPDATE-OBJECTS-JOINS - Updates joined slots of objects. + UPDATE-RECORDS-FROM-INSTANCE + Update database from view class object. Function Syntax - (update-objects-joins objects &key (slots t) (force-p t) class-name (max-len *default-update-objects-max-len*)) => + update-records-from-instance object &key database => Arguments and Values - objects - - - A list of instances of a view class. - - - - - slots - - - - - - - force-p - - - - - - - class-name + object - A list of instances of a view class. + An instance of a View + Class. - max-len + database + database + object. This will default to the value of + *default-database*. @@ -434,43 +400,46 @@ Description - Updates from the records of the appropriate database - tables the join slots specified by slots - in the supplied list of View Class instances - objects. slots - when &t; means that all join slots with :retrieval :immediate - are updated. class-name is used to - specify the View Class of all instance in - objects, when &nil; then the class of the - first instance in objects is - used. force-p when &t; means that all - join slots are updated whereas a value of &nil; means that only - unbound join slots are updated. max-len - when non-nil specifies that - update-object-joins may issue multiple - database queries with a maximum of - max-len instances updated in each query. + Using an instance of a View Class, + object, update the table that stores its + instance data. database 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. Examples - - +(select [email] :from [employee] :where [= [emplid] 1] :field-names nil :flatp t) +=> ("lenin@soviet.org") +(defvar *e1* (car (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t))) +=> *E1* +(slot-value *e1* 'email) +=> "lenin@soviet.org" +(setf (slot-value *e1* 'email) "v.lenin@soviet.org") +=> "v.lenin@soviet.org" +(update-records-from-instance *e1*) +=> +(select [email] :from [employee] :where [= [emplid] 1] :field-names nil :flatp t) +=> ("v.lenin@soviet.org") + Side Effects - + Modifies the database. Affected by - - *default-update-objects-max-len* - + Nothing. @@ -481,20 +450,19 @@ See Also - - - *default-update-objects-max-len* - - + + update-record-from-slot + update-record-from-slots + update-records + Notes - + None. - + @@ -505,7 +473,7 @@ Syntax - (update-record-from-slot object slot &key database) => + update-record-from-slot object slot &key database => Arguments and Values @@ -514,7 +482,7 @@ object - An instance of a view class. + An instance of a View Class. @@ -530,7 +498,9 @@ database - A database connection. + A database + object. This will default to the value of + *default-database*. @@ -540,7 +510,7 @@ Description Updates the value stored in the column represented by the slot, specified by the CLOS slot name - slot, of View Class instance + slot, of View Class instance object. database specifies the database in which the update is made only if object is not associated with a @@ -555,7 +525,18 @@ Examples - +(select [email] :from [employee] :where [= [emplid] 1] :field-names nil :flatp t) +=> ("lenin@soviet.org") +(defvar *e1* (car (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t))) +=> *E1* +(slot-value *e1* 'email) +=> "lenin@soviet.org" +(setf (slot-value *e1* 'email) "v.lenin@soviet.org") +=> "v.lenin@soviet.org" +(update-record-from-slot *e1* 'email) +=> +(select [email] :from [employee] :where [= [emplid] 1] :field-names nil :flatp t) +=> ("v.lenin@soviet.org") @@ -578,31 +559,29 @@ See Also - - - update-record-from-slots - update-records-from-instance - - + + update-record-from-slots + update-records-from-instance + - notes + Notes - + None. - update-record-from-slots - update database from slots of view class object. + UPDATE-RECORD-FROM-SLOTS + Update database from slots of view class object. function syntax - (update-record-from-slots object slots &key (database *default-database*)) => + update-record-from-slots object slots &key database => Arguments and Values @@ -611,7 +590,7 @@ object - An instance of a view class. + An instance of a View Class. @@ -627,7 +606,9 @@ database - A database connection. + A database + object. This will default to the value of + *default-database*. @@ -637,7 +618,7 @@ Description Updates the values stored in the columns represented by the slots, specified by the clos slot names - slots, of view class instance + slots, of View Class instance object. database specifies the database in which the update is made only if object is not associated with a @@ -652,7 +633,22 @@ Examples - +(select [last-name] [email] :from [employee] :where [= [emplid] 1] :field-names nil) +=> (("Lenin" "lenin@soviet.org")) +(defvar *e1* (car (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t))) +=> *E1* +(slot-value *e1* 'last-name) +=> "Lenin" +(slot-value *e1* 'email) +=> "lenin@soviet.org" +(setf (slot-value *e1* 'last-name) "Ivanovich") +=> "Ivanovich" +(setf (slot-value *e1* 'email) "v.ivanovich@soviet.org") +=> "v.ivanovich@soviet.org" +(update-record-from-slots *e1* '(email last-name)) +=> +(select [last-name] [email] :from [employee] :where [= [emplid] 1] :field-names nil) +=> (("Ivanovich" "v.ivanovich@soviet.org")) @@ -685,22 +681,21 @@ Notes - + None. - - + - UPDATE-RECORDS-FROM-INSTANCE - Update database from view class object. + UPDATE-INSTANCE-FROM-RECORDS + Update slot values from database. Function Syntax - (update-records-from-instance object &key (database *default-database*)) => + update-instance-from-records object &key database => object Arguments and Values @@ -709,7 +704,7 @@ object - An instance of a view class. + An instance of a View Class. @@ -717,7 +712,9 @@ database - A database connection. + A database + object. This will default to the value of + *default-database*. @@ -725,55 +722,66 @@ Description - Using an instance of a View Class, - object, update the table that stores its - instance data. database 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. + 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. Examples - +(defvar *e1* (car (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t))) +=> *E1* +(slot-value *e1* 'email) +=> "lenin@soviet.org" +(update-records [employee] + :av-pairs '(([email] "v.lenin@soviet.org")) + :where [= [emplid] 1]) +=> +(update-instance-from-records *e1*) +=> #<EMPLOYEE {4806B53D}> +(slot-value *e1* 'email) +=> "v.lenin@soviet.org" Side Effects - Modifies the database. + Slot values of object may be modified. Affected by - Nothing. + + Data in SQL database. + Exceptional Situations - Database errors. + If database is not able to be read. See Also - - - update-record-from-slot - update-record-from-slots - - + + update-slot-from-record + update-objects-joins + Notes - + None. @@ -787,7 +795,7 @@ Syntax - (update-slot-from-record object slot &key (database *default-database*)) => + update-slot-from-record object slot &key database => object Arguments and Values @@ -796,7 +804,7 @@ object - An instance of a view class. + An instance of a View Class. @@ -812,7 +820,9 @@ database - A database connection. + A database + object. This will default to the value of + *default-database*. @@ -821,7 +831,8 @@ Description Updates the slot value, specified by the CLOS slot name - slot, of the View Class instance + slot, of the View Class instance object using the attribute values of the appropriate table of database which defaults to the database associated with @@ -835,7 +846,18 @@ Examples - +(defvar *e1* (car (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t))) +=> *E1* +(slot-value *e1* 'email) +=> "lenin@soviet.org" +(update-records [employee] + :av-pairs '(([email] "v.lenin@soviet.org")) + :where [= [emplid] 1]) +=> +(update-slot-from-record *e1* 'email) +=> #<EMPLOYEE {4806B53D}> +(slot-value *e1* 'email) +=> "v.lenin@soviet.org" @@ -860,15 +882,151 @@ See Also + + update-instance-from-records + update-objects-joins + + + + Notes + None. + + + + + UPDATE-OBJECTS-JOINS + Updates joined slots of objects. + Function + + + Syntax + + update-objects-joins objects &key slots force-p class-name max-len => + + + Arguments and Values + + + objects + + + A list of instances of a View Class. + + + + + slots + + + A list of slot names in object or &t;. + + + + + force-p + + + A Boolean, defaulting to &t;. + + + + + class-name + + + A list of instances of a View Class. + + + + + max-len + + + A non-negative integer or &nil; defaulting to + *default-update-objects-max-len*. + + + + + + + Description + Updates from the records of the appropriate database + tables the join slots specified by slots + in the supplied list of View + Class instances + objects. slots + when &t; means that all join slots with + :retrieval :immediate are + updated. class-name is used to specify + the View Class of + all instance in objects, when &nil; then + the class of the first instance in + objects is + used. force-p when &t; means that all + join slots are updated whereas a value of &nil; means that only + unbound join slots are updated. max-len + when non-nil specifies that + update-object-joins may issue multiple + database queries with a maximum of + max-len instances updated in each query. + + + + Examples + +(defvar *addresses* (select 'deferred-employee-address :order-by [ea_join aaddressid] :flatp t)) +=> *ADDRESSES* +(slot-boundp (car *addresses*) 'address) +=> NIL +(update-objects-joins *addresses*) +=> +(slot-boundp (car *addresses*) 'address) +=> T +(slot-value (car *addresses*) 'address) +=> #<ADDRESS {480B0F1D}> + + + + Side Effects + + The slot values of objects are modified. + + + + Affected by + + + *default-update-objects-max-len* + + + + + Exceptional Situations + + Database errors. + + + + See Also + + *default-update-objects-max-len* + update-instance-from-records + update-slot-from-record + + Notes - + None. - +