forked from openwebwork/webwork2
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathnew-DB-architecture
165 lines (122 loc) · 5.92 KB
/
new-DB-architecture
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
--------------------------------------------------------------------------------
Architecture
--------------------------------------------------------------------------------
The new database system uses a three-tier architecture to insulate each layer from the adjacent layers.
TOP LAYER: DB
-------------
The top layer of the architecture is the DB module. It provides the methods
listed in doc/new-DB-API, and uses schema modules (via tables) to implement those methods.
/ list* exists* add* get* put* delete* \ <- api
+------------------------------------------------------------------+
| DB |
+------------------------------------------------------------------+
\ password permission key user set set_user problem problem_user / <- tables
MIDDLE LAYER: SCHEMAS
---------------------
The middle layer of the architecture is provided by one or more schema modules. They are called "schema" modules because they control the structure of the data for a table. This includes odd things like the way multiple tables are encoded in a single hash in the WWHash schema, and the encoding scheme used.
The schema modules provide an API that matches the requirements of the DB layer, on a per-table basis. Each schema module has a style that determines which drivers it can interface with. For example, WWHash is a "hash" style schema. SQL is a "dbi" style schema.
Both WeBWorK 1.x and 2.x courses use:
/ password permission key \ / user \ <- tables
+-----------------------------+ +----------------+
| Auth1Hash | | Classlist1Hash |
+-----------------------------+ +----------------+
\ hash / \ hash / <- style
WeBWorK 1.x courses also use:
/ set_user problem_user \ / set problem \
+-------------------------+ +---------------------+
| WW1Hash | | GlobalTableEmulator |
+-------------------------+ +---------------------+
\ hash / \ null /
The GlobalTableEmulator schema emulates the global set and problem tables using data from the set_user and problem_user tables.
WeBWorK 2.x courses also use:
/ set set_user problem problem_user \
+-------------------------------------+
| WW2Hash |
+-------------------------------------+
\ hash /
Other drop-in schema modules could be:
/ * \ / password \
+-------+ +--------------+
| SQL | | PasswordLDAP |
+-------+ +--------------+
\ dbi / \ ldap /
BOTTOM LAYER: DRIVERS
---------------------
Driver modules implement a style for a schema. They provide physical access to a data source containing the data for a table. Some driver modules are as follows:
/ hash \ / hash \ / hash \ <- style
+--------+ +--------+ +--------+
| DB | | GDBM | | DB3 |
+--------+ +--------+ +--------+
/ dbi \ / ldap \
+-------+ +--------+
| DBI | | LDAP |
+-------+ +--------+
--------------------------------------------------------------------------------
Schema API
--------------------------------------------------------------------------------
$record - an object representing a record in the table
@keyparts - values for fields that make up the table's key
@tables = tables()
returns list of tables supported.
$style = style()
returns the required driver style.
$handle = new($db, $driver, $table, $record, $params)
creates a schema interface for $table, using the driver interface
provided by $driver and using the record class named in $record. dies
if the $driver does not support the driver style needed by the schema.
$params contains extra information needed by the schema. $db is provided
so that schemas can query other schemas. (This is used by the
GlobalTableEmulator schema.)
@keys = $handle->list(@keyparts)
returns a list containing the key of each record in the table that
matches the values in @keyparts. (i.e. [$userID, undef] will return all
of the records with the specified user_id.) the elements of @keys are
\@keyparts. if no matching records exist, an empty list is returned.
$result = $handle->exists(@keyparts)
returns whether a record matching @keyparts exists in the table.
$result = $handle->add($record)
attempts to add $record to the table. die if a record with the same key
exists.
$record = $handle->get(@keyparts)
attempts to retrieve the record matching @keyparts from the table.
returns undef if no record matches.
$result = $handle->put($record)
attempts to replace the record in the table that matches the key of
$record. dies if no such record exists.
$result = $handle->delete(@keyparts)
attempts to delete the record matching @keyparts from the table. returns
true if the record was successfully deleted, or false if it did not
exist.
--------------------------------------------------------------------------------
Driver API
--------------------------------------------------------------------------------
COMMON
------
$style = style()
returns the supported driver style.
$handle = new($source, $params)
creates a new interface to the data contained in $source. $params
contains extra information needed by the schema.
$result = $handle->connect($mode)
connects to the data source with access mode $mode. dies if connection
fails.
$result = $handle->disconnect()
disconnects from the data source. dies if disconnection fails.
STYLE: hash
-----------
$ref = $handle->hash()
returns a reference to the underlying tied hash. dies if the hash is
not available (i.e. not connected).
--------------------------------------------------------------------------------
@keyparts key order
--------------------------------------------------------------------------------
table keyparts
----- --------
password user_id
permission user_id
key user_id
user user_id
set set_id
set_user user_id, set_id
problem set_id, problem_id
problem_user user_id, set_id, problem_id