View of /trunk/webwork2/doc/new-DB-architecture

    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* new* get* put* delete* \                   <- api
   14 +------------------------------------------------------------------+
   15 |                                DB                                |
   16 +------------------------------------------------------------------+
   17  \ password permission key user set set_user problem problem_user /  <- tables
   18 
   19 MIDDLE LAYER: SCHEMAS
   20 ---------------------
   21 
   22 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 WW1Hash schema, and the encoding scheme used.
   23 
   24 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, WW1Hash is a "hash" style schema. SQL is a "dbi" style schema.
   25 
   26 The null schema, "0", can handle all tables, but merely returns a false value for any method call. The null schema has no style.
   27 
   28 Both WeBWorK 1.x and 2.x courses use:
   29 
   30   / password \      / permission \	/ key \   <- tables
   31 +--------------+  +----------------+  +---------+
   32 | PasswordHash |  | PermissionHash |  | KeyHash |
   33 +--------------+  +----------------+  +---------+
   34     \ hash /	       \ hash / 	\ hash /  <- style
   35 
   36 WeBWorK 1.x courses also use:
   37 
   38  / set_user problem_user \    / * \ 
   39 +-------------------------+  +-----+
   40 |         WW1Hash         |  |  0  |
   41 +-------------------------+  +-----+
   42           \ hash /                  
   43 
   44 The null schema "0" provides the set and problem tables.
   45 
   46 WeBWorK 2.x courses also use:
   47 
   48  / set set_user problem problem_user \ 
   49 +-------------------------------------+
   50 |               WW2Hash               |
   51 +-------------------------------------+
   52                 \ hash /               
   53 
   54 Other drop-in schema modules could be:
   55 
   56   / * \      / password \  
   57 +-------+  +--------------+
   58 |  SQL  |  | PasswordLDAP |
   59 +-------+  +--------------+
   60  \ dbi /       \ ldap /    
   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 $handle = new($driver, $table)
   88 	creates a schema interface for $table, using the driver interface
   89 	provided by $driver. returns a false value if the $driver does not 
   90 	support the driver style needed by the schema.
   91 
   92 @keys = $handle->list()
   93 	returns a list containing the key of each record in the table. the
   94 	elements of @keys are \@keyparts.
   95 
   96 $result = $handle->new($record)
   97 	attempts to add $record to the table. returns a false value if a record
   98 	with the same key exists.
   99 
  100 $record = $handle->get(@keyparts)
  101 	attempts to retrieve the record matching @keyparts from the table.
  102 	returns a false value if no record matches.
  103 
  104 $result = $handle->put($record)
  105 	attempts to replace the record in the table that matches the key of
  106 	$record. returns a false value if no such record exists.
  107 
  108 $result = $handle->delete(@keyparts)
  109 	attempts to delete the record matching @keyparts from the table.
  110 	returns a false value if no such record exists.
  111 
  112 --------------------------------------------------------------------------------
  113 Driver API
  114 --------------------------------------------------------------------------------
  115 
  116 COMMON
  117 ------
  118 
  119 @styles = styles()
  120 	returns the styles supported by the driver.
  121 
  122 $handle = new($source)
  123 	creates a new interface to the data contained in $source. If $source is
  124 	malformed of can't be accessed, a false value is returned.
  125 
  126 $result = $handle->connect($mode)
  127 	connects to the data source with access mode $mode. returns a false
  128 	value if connecting fails.
  129 
  130 $result = $handle->disconnect()
  131 	disconnects from the data source. returns a false value if disconnecting
  132 	fails. this should never happen.
  133 
  134 STYLE: hash
  135 -----------
  136 
  137 $ref = $handle->hash()
  138 	returns a reference to the underlying tied hash. returns a false value
  139 	if the hash is not available (i.e. not connected).
  140 
  141 STYLE: dbi
  142 ----------
  143 
  144 $dbh = $handle->dbh()
  145 	returns a DBI database handle. returns a false value if the handle is
  146 	unavailable (i.e. not connected).