View of /branches/rel-2-4-patches/webwork-modperl/lib/WeBWorK/DB/Schema.pm

    1 ################################################################################
    2 # WeBWorK mod_perl (c) 2000-2002 WeBWorK Project
    3 # $Id$
    4 ################################################################################
    5 
    6 package WeBWorK::DB::Schema;
    7 
    8 =head1 NAME
    9 
   10 WeBWorK::DB::Schema - schema superclass (to hold documentation)
   11 
   12 =head1 SYNOPSIS
   13 
   14 FIXME: write synopsis
   15 
   16 =head1 DESCRIPTION
   17 
   18 FIXME: write description
   19 
   20 =head2 Record Identifiers and Keys
   21 
   22 Several of the tables used in the WeBWorK database have records that are
   23 identified by the values of a set of fields, rather than by the value of a
   24 single field. Because of this, when identifying a record (in calls to the
   25 C<list>, C<exists>, C<get>, and C<delete> methods), one must specify a list of
   26 values rather than a single value. This is represented in the documentation for
   27 these methods by the expression C<@keyparts>. The values in C<@keyparts>
   28 correspond to the fields returned by the C<KEYFIELDS> method of the table's
   29 record class. If an element of C<@keyparts> is undefined, then the
   30 corresponding field is not used in the match. Some methods require all elements
   31 of C<@keyparts> to be defined. This is noted below.
   32 
   33 A "record key", as in the C<list> method, is a reference to a list containing
   34 values which correspond to the the fields returned by the C<KEYFIELDS> method
   35 of the table's record class.
   36 
   37 =head1 CONSTRUCTOR
   38 
   39 =over
   40 
   41 =item new($db, $driver, $table, $record, $params)
   42 
   43 Creates a schema interface for C<$table>, using the driver interface provided
   44 by C<$driver> and using the record class named in C<$record>. If the C<$driver>
   45 does not support the driver style needed by the schema, an exception is thrown.
   46 C<$params> contains extra information needed by the schema and is schema
   47 dependent. C<$db> is provided so that schemas can query other schemas.
   48 
   49 =back
   50 
   51 =head1 REQUIRED METHODS
   52 
   53 =over
   54 
   55 =item list(@keyparts)
   56 
   57 Returns a list containing the key of each record in the table that matches the
   58 values in C<@keyparts>. Elements of C<@keyparts> may be undefined.
   59 
   60 =item exists(@keyparts)
   61 
   62 Returns a boolean value representing whether a record that matches the values
   63 in C<@keyparts> exists in the table. All elements of keyparts must be defined.
   64 
   65 =item add($Record)
   66 
   67 Attempts to add C<$Record> to the table. C<$Record> must be an instance of the
   68 table's record class. Returns true on success and false on failure (for
   69 example, if the database couldn't be contacted). If a record with the same key
   70 exists, an exception is thrown.
   71 
   72 =item get(@keyparts)
   73 
   74 Attempts to retrieve the record matching C<@keyparts> from the table. Returns
   75 an instance of the table's record class if there is a match. Returns undef if
   76 no record matches. All elements of C<@keyparts> must be defined.
   77 
   78 =item put($Record)
   79 
   80 Attempts to replace the record in the table that matches the key of $Record.
   81 Returns true on success and false on failure (for example, if the database
   82 couldn't be contacted). If no such record exists, an exception is thrown.
   83 
   84 =item delete(@keyparts)
   85 
   86 Attempts to delete the record in the table that matches C<@keyparts>. Returns
   87 true if the record was successfully deleted or did not exist, and false if
   88 deletion failed. Elements of C<@keyparts> may be undefined.
   89 
   90 =back
   91 
   92 =cut
   93 
   94 1;