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