← Back to branch summary

~ubuntu-branches/ubuntu/hardy/gnue-common/hardy

« back to all changes in this revision

Viewing changes to doc/technotes/00001.txt

  • Committer: Bazaar Package Importer
  • Author(s): Andrew Mitchell
  • Date: 2005-03-09 11:06:31 UTC
  • Revision ID: james.westby@ubuntu.com-20050309110631-8gvvn39q7tjz1kj6
Tags: upstream-0.5.14
Import upstream version 0.5.14

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/technotes/00001.txt
 
1
Title:   Overview of DataObjects/DataSources
 
2
Status:  Current
 
3
 
 
4
A DataSource corresponds to the datasource tag in client files (GFD and
 
5
GRD for forms and reports, respectively). The DataSource object acts as
 
6
a implementation buffer between vendor-specific DataObjects and vendor-
 
7
neutral datasource tags (explained further in the DataObject discussion).
 
8
In other words, a vendor-specific DataObject will be bound to the 
 
9
DataSource after the DataSource is initialized.
 
10
 
 
11
A DataObject is the highest level object in the Database Driver hierarchy. 
 
12
It basically maintains state information such as the database connection,
 
13
parent/child relationships, etc. It contains/generates ResultSets, but not 
 
14
actual data.  The client app will ask its DataObject for a ResultSet
 
15
using supplied conditions.  
 
16
 
 
17
Note that the implementation of DataObject is vendor-specific as well 
 
18
as DataSource-type dependent; e.g., there will be a PostgreSQL 
 
19
DataObject for "Object" type datasources (base tables, etc) and a 
 
20
separate PostgreSQL DataObject for "Raw SQL Queries" or for 
 
21
"XML-Queries" (once implemented).  The DataObject *interface*, however,
 
22
remains constant across the various implementations. It is because of 
 
23
the number of implementations of DataObjects that a separate DataSource
 
24
had to be created.
 
25
 
 
26
A ResultSet is a traversable set of RecordSets.  It has no GFD equivalent, 
 
27
although most of GFBlock's functionality may consist of calls to 
 
28
DataSets. It contains methods to load records, go to next/prev/first/last 
 
29
records, deleting/insert records, etc.
 
30
 
 
31
A RecordSet is a set of the fields contained in a record.  A RecordSet 
 
32
knows the current state of itself and all its fields. 
 
33
 
 
34
A ResultSet holds RecordSets.
 
35
 
 
36
A DataObject may hold several ResultSets (i.e., detail resultsets 
 
37
in a master/detail relationship). A master RecordSet contains 
 
38
a reference to its detail ResultSets. 
 
39
 
 
40
To commit all changes, you would first .post() all ResultSets (recursively)
 
41
and then do a transactional .commit(). This method allows for multiple
 
42
detail sets to be maintained at once.
 
43
 
 
44
***********
 
45
DataSource: 
 
46
  initialize()
 
47
    Called to initialize the datasource. Binds the 
 
48
    DataSource to a DataObject.
 
49
 
 
50
  getDataObject()
 
51
    Returns the bound DataObject
 
52
 
 
53
  referenceField(field)
 
54
    Used by the client app to notify that a certain field is being 
 
55
    referenced.  This will ensure that the DataObject includes this
 
56
    field in its query.
 
57
 
 
58
 
 
59
***********
 
60
DataObject:
 
61
  createResultSet(conditions={}, readOnly=0): 
 
62
    Creates and returns a resultset satisfying "conditions". conditions
 
63
    can either be a dictionary/hash of fieldname:value AND pairs, or, for
 
64
    more complex conditions, a GConditions object.
 
65
 
 
66
 
 
67
  addDetailDataObject(dataObject, handler=None): 
 
68
    Add a detail data object.  This dataobject will create a new resultset 
 
69
    everything this dataobject changes (new record, etc).  The optional 
 
70
    handler will be called after the detail dataobject is notified.  The 
 
71
    client application may with to add a handler to know when the detail
 
72
    has been requeried.  handler is a method that takes two arguments: 
 
73
    the master ResultSet and the detail ResultSet 
 
74
 
 
75
  getLoginFields()
 
76
  connect()
 
77
 
 
78
 
 
79
 
 
80
***********
 
81
ResultSet: 
 
82
  
 
83
  isFirstRecord() : Returns 1=At first record, 0=not at first record or no records loaded
 
84
  getRecordNumber()   : returns -1=No records in memory, #=Current record # (0-based)
 
85
  getRecord()   : return a specified record w/o changing 
 
86
                  current record (returns None if invalid #) (0-based)
 
87
  setRecord()   : move to record #, returns 1=New record loaded, 0=invalid # (0-based)
 
88
  nextRecord()  : returns 1=New record loaded, 0=No more records
 
89
  prevRecord()  : returns 1=New record loaded, 0=At first record
 
90
  firstRecord() : returns 1=at first record, 0=No records loaded
 
91
  lastRecord()  : returns 1=at last record, 0=No records loaded
 
92
  deleteRecord(): Marks the current record for deletion
 
93
  insertRecord(): Inserts a blank record after the current record
 
94
  isPending()   : Returns 1=DataSource has uncommitted changes 
 
95
 
 
96
  post()        : Post changes to the database
 
97
 
 
98
  current       : Link to current record (RecordSet)
 
99
 
 
100
 
 
101
 
 
102
***********
 
103
RecordSet:
 
104
  isPending()  : Returns 1=Record has uncommitted changes
 
105
  isDeleted()  : Returns 1=Record is pending a deletion
 
106
  isModified() : Returns 1=Record is pending an update
 
107
  isInserted() : Returns 1=Record is pending an insertion
 
108
  isEmpty()    : Returns 1=Record is is an empty record
 
109
  getField(f)         : Returns current value of "field"
 
110
  setField(f)         : Sets current value of "field"
 
111
  isFieldModified(f)  : Returns 1=Field has been modified
 
112
  addDetailResultSet(): Sets the dataSet associated with this master record
 
113
 
 
114
 
 
115
 
 
116
****************
 
117
Typical layout
 
118
 
 
119
DataObject contains link to ResultSet 
 
120
ResultSet contains link to RecordSet
 
121
 
 
122
On startup the DataSource asks the GConnection manager for a handle to a dataObject
 
123
the end result is that the DataSource is bound to a specifc database driver
 
124
 
 
125
From then on all access to the DataObject is hidden by wrapper functions in the
 
126
DataSource
 
127
 
 
128