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* exists* 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 $style = style()
   88 	returns the required driver style.
   89 
   90 $handle = new($driver, $table)
   91 	creates a schema interface for $table, using the driver interface
   92 	provided by $driver. returns a false value if the $driver does not 
   93 	support the driver style needed by the schema.
   94 
   95 @keys = $handle->list()
   96 	returns a list containing the key of each record in the table. the
   97 	elements of @keys are \@keyparts.
   98 
   99 $result = $handle->exists(@keyparts)
  100 	returns whether a record matching @keyparts exists in the table.
  101 
  102 $result = $handle->new($record)
  103 	attempts to add $record to the table. returns a false value if a record
  104 	with the same key exists.
  105 
  106 $record = $handle->get(@keyparts)
  107 	attempts to retrieve the record matching @keyparts from the table.
  108 	returns a false value if no record matches.
  109 
  110 $result = $handle->put($record)
  111 	attempts to replace the record in the table that matches the key of
  112 	$record. returns a false value if no such record exists.
  113 
  114 $result = $handle->delete(@keyparts)
  115 	attempts to delete the record matching @keyparts from the table.
  116 	returns a false value if no such record exists.
  117 
  118 --------------------------------------------------------------------------------
  119 Driver API
  120 --------------------------------------------------------------------------------
  121 
  122 COMMON
  123 ------
  124 
  125 $style = style()
  126 	returns the supported driver style.
  127 
  128 $handle = new($source)
  129 	creates a new interface to the data contained in $source.
  130 
  131 $result = $handle->connect($mode)
  132 	connects to the data source with access mode $mode. returns a false
  133 	value if connecting fails.
  134 
  135 $result = $handle->disconnect()
  136 	disconnects from the data source. returns a false value if disconnecting
  137 	fails. this should never happen.
  138 
  139 STYLE: hash
  140 -----------
  141 
  142 $ref = $handle->hash()
  143 	returns a reference to the underlying tied hash. returns a false value
  144 	if the hash is not available (i.e. not connected).
  145 
  146 STYLE: dbi
  147 ----------
  148 
  149 $dbh = $handle->dbh()
  150 	returns a DBI database handle. returns a false value if the handle is
  151 	unavailable (i.e. not connected).