gnue/gnue-common/doc DataObjects.txt

[Jason Cater]

CVSROOT:        /home/cvs
Module name:    gnue
Changes by:     Jason Cater <address@hidden>    01/07/17 12:06:19

Modified files:
        gnue-common/doc: DataObjects.txt 

Log message:
        Clarified DataObjects docs

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gnue/gnue-common/doc/DataObjects.txt.diff?cvsroot=OldCVS&tr1=1.1&tr2=1.2&r1=text&r2=text

Patches:
Index: gnue/gnue-common/doc/DataObjects.txt
diff -u gnue/gnue-common/doc/DataObjects.txt:1.1 
gnue/gnue-common/doc/DataObjects.txt:1.2
--- gnue/gnue-common/doc/DataObjects.txt:1.1    Wed Jul 11 22:11:06 2001
+++ gnue/gnue-common/doc/DataObjects.txt        Tue Jul 17 12:06:19 2001
@@ -1,21 +1,39 @@
 ***********
-A DataObject corresponds to the datasource tag in GFD files. It defines 
-a query or source.  It contains ResultSets, but not actual data. 
+A DataSource corresponds to the datasource tag in client files (GFD and
+GRD for forms and reports, respectively). The DataSource object acts as
+a implementation buffer between vendor-specific DataObjects and vendor-
+neutral datasource tags (explained further in the DataObject discussion).
+
+A DataObject is the highest level object in the Database Driver hierarchy. 
+It basically maintains state information such as the database connection,
+parent/child relationships, etc. It contains/generates ResultSets, but not 
+actual data.  The client app will ask its DataObject for a ResultSet
+using supplied conditions.  
+
+Note that the implementation of DataObject is vendor-specific as well 
+as DataSource-type dependent; e.g., there will be a PostgreSQL 
+DataObject for "Object" type datasources (base tables, etc) and a 
+separate PostgreSQL DataObject for "Raw SQL Queries" or for 
+"XML-Queries" (once implemented).  The DataObject *interface*, however,
+remains constant across the various implementations. It is because of 
+the number of implementations of DataObjects that a separate DataSource
+had to be created.
 
 A ResultSet is a traversable set of RecordSets.  It has no GFD equivalent, 
 although most of GFBlock's functionality may consist of calls to 
-DataSets.
+DataSets. It contains methods to load records, go to next/prev/first/last 
+records, deleting/insert records, etc.
 
 A RecordSet is a set of the fields contained in a record.  A RecordSet 
 knows the current state of itself and all its fields. 
 
 A ResultSet holds RecordSets.
 
-A DataSource may hold several DataSets (i.e., detail datasets 
+A DataObject may hold several ResultSets (i.e., detail resultsets 
 in a master/detail relationship). A master RecordSet contains 
-a reference to its detail DataSets. 
+a reference to its detail ResultSets. 
 
-To commit all changes, you would first .post() all DataSets (recursively)
+To commit all changes, you would first .post() all ResultSets (recursively)
 and then do a transactional .commit(). This method allows for multiple
 detail sets to be maintained at once.
 
@@ -31,13 +49,24 @@
 
 
 ***********
+DataObject:
+  createResultSet(self, conditions={}, readOnly=0): 
+    Creates and returns a resultset satisfying "conditions". conditions
+    can either be a dictionary/hash of fieldname:value AND pairs, or, for
+    more complex conditions, a GConditions object.
+
+
+  addDetailDataObject(self, dataObject, handler=None): 
+    Add a detail data object.  This dataobject will create a new resultset 
+    everything this dataobject changes (new record, etc).  The optional 
+    handler will be called after the detail dataobject is notified.  The 
+    client application may with to add a handler to know when the detail
+    has been requeried.  handler is a method that takes two arguments: 
+    the master ResultSet and the detail ResultSet 
+
+
+***********
 ResultSet: 
-  |
-  +-- DataSourceQuery extends DataSource
-  |
-  +-- DataSourceObject extends DataSource
-  |
-  +-- DataSourceSQL extends DataSource
   
   isFirstRecord() : Returns 1=At first record, 0=
   getRecord()   : returns 0=No records in memory, #=Current record #
@@ -46,8 +75,8 @@
   prevRecord()  : returns 1=New record loaded, 0=At first record
   firstRecord() : returns 1=at first record, 0=No records loaded
   lastRecord()  : returns 1=at last record, 0=No records loaded
-  deleteRecord():  
-  insertRecord(): 
+  deleteRecord(): Marks the current record for deletion
+  insertRecord(): Inserts a blank record after the current record
   isPending()   : Returns 1=DataSource has uncommitted changes 
 
   post()        : Post changes to the database
@@ -62,14 +91,11 @@
   isDeleted()  : Returns 1=Record is pending a deletion
   isModified() : Returns 1=Record is pending an update
   isInserted() : Returns 1=Record is pending an insertion
+  isEmpty()    : Returns 1=Record is is an empty record
   getField(f)         : Returns current value of "field"
   setField(f)         : Sets current value of "field"
   isFieldModified(f)  : Returns 1=Field has been modified
-  getUpdateDict()     : Returns a dict containing field->changes
-                        Will be used by the DBDriver to 
-                        generate insert or update statements.
-  dbIdentifier : Contains the identifier used by the DB drivers
-  setDetailDataSet() : Sets the dataSet associated with this master record
+  addDetailResultSet(): Sets the dataSet associated with this master record