[WWcvs] webwork2: added comments about future exception handling scheme

[Sam H. v. a. <we...@ma...>]

Log Message:
-----------
added comments about future exception handling scheme

Modified Files:
--------------
    webwork2/lib/WeBWorK:
        DB.pm

Revision Data
-------------
Index: DB.pm
===================================================================
RCS file: /webwork/cvs/system/webwork2/lib/WeBWorK/DB.pm,v
retrieving revision 1.107
retrieving revision 1.108
diff -Llib/WeBWorK/DB.pm -Llib/WeBWorK/DB.pm -u -r1.107 -r1.108
--- lib/WeBWorK/DB.pm
+++ lib/WeBWorK/DB.pm
@@ -104,6 +104,55 @@
 use WeBWorK::Debug;
 use WeBWorK::Utils qw(runtime_use);
 
+=for comment
+
+These exceptions will replace the ones in WeBWorK::DB::Schema and will be
+allowed to propagate out to calling code. The following callers will have to be
+changed to catch these exceptions instead of doing string matching:
+
+lib/WebworkSOAP.pm:     if ($@ =~ m/user set exists/) {
+lib/WeBWorK/ContentGenerator/Instructor.pm:             if ($@ =~ m/user set exists/) {
+lib/WeBWorK/ContentGenerator/Instructor.pm:     if ( $@ =~ m/user set exists/ ) {
+lib/WeBWorK/ContentGenerator/Instructor.pm:             if ($@ =~ m/user problem exists/) {
+lib/WeBWorK/ContentGenerator/Instructor.pm:             if ($@ =~ m/user problem exists/) {
+lib/WeBWorK/ContentGenerator/Instructor.pm:                     next if $@ =~ m/user set exists/;
+lib/WeBWorK/Utils/DBImportExport.pm:                            if ($@ =~ m/exists/) {
+lib/WeBWorK/DB.pm:                              if ($@ and $@ !~ m/password exists/) {
+lib/WeBWorK/DB.pm:                              if ($@ and $@ !~ m/permission level exists/) {
+
+How these exceptions should be used:
+
+* RecordExists is thrown by the DBI error handler (handle_error in
+Schema::NewSQL::Std) when in INSERT fails because a record exists. Thus it can
+be thrown via addUser, addPassword, etc.
+
+* RecordNotFound should be thrown when we try to UPDATE and zero rows were
+affected. Problem: Frank Wolfs (UofR PAS) may have a MySQL server that returns 0
+when updating even when a record was modified. What's up with that? There's some
+question as to where we should throw this: in this file's put* methods? In
+Std.pm's put method? Or in update_fields and update_fields_i?
+
+* DependencyNotFound should be throws when we check for a record that is needed
+to insert another record (e.g. password depends on user). These checks are done
+in this file, so we'll throw this exception from there.
+
+=cut
+
+use Exception::Class (
+	'WeBWorK::DB::Ex' => {},
+	'WeBWorK::DB::Ex::RecordExists' => {
+		isa => 'WeBWorK::DB::Ex',
+		fields => ['type', 'key'],
+	},
+	'WeBWorK::DB::Ex::RecordNotFound' => {
+		isa => 'WeBWorK::DB::Ex',
+		fields => ['type', 'key'],
+	},
+	'WeBWorK::DB::Ex::DependencyNotFound' => {
+		isa => 'WeBWorK::DB::Ex::RecordNotFound',
+	},
+);
+
 ################################################################################
 # constructor
 ################################################################################
@@ -452,15 +501,6 @@
 	} elsif ($@) {
 		die $@;
 	}
-	# FIXME about these exceptions: eventually the exceptions should be part of
-	# WeBWorK::DB rather than WeBWorK::DB::Schema, and we should just let them
-	# through to the calling code. however, right now we have code that checks
-	# for the string "... exists" in the error message, so we need to convert
-	# here.
-	# 
-	# WeBWorK::DB::Ex::RecordExists
-	# WeBWorK::DB::Ex::DependencyNotFound - i.e. inserting a password for a nonexistent user
-	# ?
 }
 
 sub putUser {