Bug 329377: Bugzilla::Object base class for objects

Patch By Max Kanat-Alexander <mkanat@bugzilla.org> r=LpSolit, r=kevin.benton, a=justdave

3 files changed, 237 insertions, 129 deletions

diff --git a/Bugzilla/Keyword.pm b/Bugzilla/Keyword.pm
index 946d43c14..6ba72479c 100644
--- a/Bugzilla/Keyword.pm
+++ b/Bugzilla/Keyword.pm
@@ -18,8 +18,7 @@ use strict;
 
 package Bugzilla::Keyword;
 
-use Bugzilla::Util;
-use Bugzilla::Error;
+use base qw(Bugzilla::Object);
 
 ###############################
 ####    Initialization     ####
@@ -31,100 +30,18 @@ use constant DB_COLUMNS => qw(
    keyworddefs.description
 );
 
-my $columns = join(", ", DB_COLUMNS);
-
-sub new {
-    my $invocant = shift;
-    my $class = ref($invocant) || $invocant;
-    my $self = {};
-    bless($self, $class);
-    return $self->_init(@_);
-}
-
-sub _init {
-    my $self = shift;
-    my ($param) = @_;
-    my $dbh = Bugzilla->dbh;
-
-    my $id = $param unless (ref $param eq 'HASH');
-    my $keyword;
-
-    if (defined $id) {
-        detaint_natural($id)
-          || ThrowCodeError('param_must_be_numeric',
-                            {function => 'Bugzilla::Keyword::_init'});
-
-        $keyword = $dbh->selectrow_hashref(qq{
-            SELECT $columns FROM keyworddefs
-             WHERE id = ?}, undef, $id);
-    } elsif (defined $param->{'name'}) {
-        trick_taint($param->{'name'});
-        $keyword = $dbh->selectrow_hashref(qq{
-            SELECT $columns FROM keyworddefs
-             WHERE name = ?}, undef, $param->{'name'});
-    } else {
-        ThrowCodeError('bad_arg',
-            {argument => 'param',
-             function => 'Bugzilla::Keyword::_init'});
-    }
-
-    return undef unless (defined $keyword);
-
-    foreach my $field (keys %$keyword) {
-        $self->{$field} = $keyword->{$field};
-    }
-    return $self;
-}
-
-sub new_from_list {
-    my $class = shift;
-    my ($id_list) = @_;
-    my $dbh = Bugzilla->dbh;
-
-    my $keywords;
-    if (@$id_list) {
-        my @detainted_ids;
-        foreach my $id (@$id_list) {
-            detaint_natural($id) ||
-                ThrowCodeError('param_must_be_numeric',
-                              {function => 'Bugzilla::Keyword::new_from_list'});
-            push(@detainted_ids, $id);
-        }
-        $keywords = $dbh->selectall_arrayref(
-            "SELECT $columns FROM keyworddefs WHERE id IN (" 
-            . join(',', @detainted_ids) . ")", {Slice=>{}});
-    } else {
-        return [];
-    }
-
-    foreach my $keyword (@$keywords) {
-        bless($keyword, $class);
-    }
-    return $keywords;
-}
+use constant DB_TABLE => 'keyworddefs';
 
 ###############################
 ####      Accessors      ######
 ###############################
 
-sub id                { return $_[0]->{'id'};          }
-sub name              { return $_[0]->{'name'};        }
 sub description       { return $_[0]->{'description'}; }
 
 ###############################
 ####      Subroutines    ######
 ###############################
 
-sub get_all_keywords {
-    my $dbh = Bugzilla->dbh;
-
-    my $ids = $dbh->selectcol_arrayref(q{
-        SELECT id FROM keyworddefs ORDER BY name});
-
-    my $keywords = Bugzilla::Keyword->new_from_list($ids);
-    return @$keywords;
-}
-
 sub keyword_count {
     my ($count) = 
         Bugzilla->dbh->selectrow_array('SELECT COUNT(*) FROM keyworddefs');
@@ -143,60 +60,24 @@ Bugzilla::Keyword - A Keyword that can be added to a bug.
 
  use Bugzilla::Keyword;
 
- my $keyword = new Bugzilla::Keyword(1);
- my $keyword = new Bugzilla::Keyword({name => 'perf'});
+ my $count = Bugzilla::Keyword::keyword_count;
 
- my $id          = $keyword->id;
- my $name        = $keyword->name;
  my $description = $keyword->description;
 
 =head1 DESCRIPTION
 
 Bugzilla::Keyword represents a keyword that can be added to a bug.
 
-=head1 METHODS
-
-=over
-
-=item C<new($param)>
-
- Description: The constructor is used to load an existing keyword
-              by passing a keyword id or a hash.
-
- Params:      $param - If you pass an integer, the integer is the
-                       keyword id from the database that we want to
-                       read in. If you pass in a hash with 'name' key,
-                       then the value of the name key is the name of a
-                       keyword from the DB.
-
- Returns:     A Bugzilla::Keyword object.
-
-=item C<new_from_list(\@id_list)>
-
- Description: Creates an array of Keyword objects, given an
-              array of ids.
-
- Params:      \@id_list - A reference to an array of numbers, keyword ids.
-                          If any of these are not numeric, the function
-                          will throw an error. If any of these are not
-                          valid keyword ids, they will simply be skipped.
-
- Returns:     A reference to an array of C<Bugzilla::Keyword> objects.
-
-=back
+This implements all standard C<Bugzilla::Object> methods. See 
+L<Bugzilla::Object> for more details.
 
 =head1 SUBROUTINES
 
-=over
-
-=item C<get_all_keywords()>
+This is only a list of subroutines specific to C<Bugzilla::Keyword>.
+See L<Bugzilla::Object> for more subroutines that this object 
+implements.
 
- Description: Returns all keywords from the database.
-
- Params:      none.
-
- Returns:     A list of C<Bugzilla::Keyword> objects,
-              or an empty list if there are none.
+=over
 
 =item C<keyword_count()> 
 
diff --git a/Bugzilla/Object.pm b/Bugzilla/Object.pm
new file mode 100644
index 000000000..56789f584
--- /dev/null
+++ b/Bugzilla/Object.pm
@@ -0,0 +1,227 @@
+# -*- Mode: perl; indent-tabs-mode: nil -*-
+#
+# The contents of this file are subject to the Mozilla Public
+# License Version 1.1 (the "License"); you may not use this file
+# except in compliance with the License. You may obtain a copy of
+# the License at http://www.mozilla.org/MPL/
+#
+# Software distributed under the License is distributed on an "AS
+# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# rights and limitations under the License.
+#
+# The Original Code is the Bugzilla Bug Tracking System.
+#
+# Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+
+use strict;
+
+package Bugzilla::Object;
+
+use Bugzilla::Util;
+use Bugzilla::Error;
+
+use constant LIST_ORDER => 'name';
+
+###############################
+####    Initialization     ####
+###############################
+
+sub new {
+    my $invocant = shift;
+    my $class    = ref($invocant) || $invocant;
+    my $object   = $class->_init(@_);
+    bless($object, $class) if $object;
+    return $object;
+}
+
+sub _init {
+    my $class = shift;
+    my ($param) = @_;
+    my $dbh = Bugzilla->dbh;
+    my $columns = join(',', $class->DB_COLUMNS);
+    my $table   = $class->DB_TABLE;
+
+    my $id = $param unless (ref $param eq 'HASH');
+    my $object;
+
+    if (defined $id) {
+        detaint_natural($id)
+          || ThrowCodeError('param_must_be_numeric',
+                            {function => $class . '::_init'});
+
+        $object = $dbh->selectrow_hashref(qq{
+            SELECT $columns FROM $table
+             WHERE id = ?}, undef, $id);
+    } elsif (defined $param->{'name'}) {
+        trick_taint($param->{'name'});
+        $object = $dbh->selectrow_hashref(qq{
+            SELECT $columns FROM $table
+             WHERE name = ?}, undef, $param->{'name'});
+    } else {
+        ThrowCodeError('bad_arg',
+            {argument => 'param',
+             function => $class . '::_init'});
+    }
+
+    return $object;
+}
+
+sub new_from_list {
+    my $class = shift;
+    my ($id_list) = @_;
+    my $dbh = Bugzilla->dbh;
+    my $columns = join(',', $class->DB_COLUMNS);
+    my $table   = $class->DB_TABLE;
+    my $order   = $class->LIST_ORDER;
+
+    my $objects;
+    if (@$id_list) {
+        my @detainted_ids;
+        foreach my $id (@$id_list) {
+            detaint_natural($id) ||
+                ThrowCodeError('param_must_be_numeric',
+                              {function => $class . '::new_from_list'});
+            push(@detainted_ids, $id);
+        }
+        $objects = $dbh->selectall_arrayref(
+            "SELECT $columns FROM $table WHERE id IN (" 
+            . join(',', @detainted_ids) . ") ORDER BY $order", {Slice=>{}});
+    } else {
+        return [];
+    }
+
+    foreach my $object (@$objects) {
+        bless($object, $class);
+    }
+    return $objects;
+}
+
+###############################
+####      Accessors      ######
+###############################
+
+sub id                { return $_[0]->{'id'};          }
+sub name              { return $_[0]->{'name'};        }
+
+###############################
+####      Subroutines    ######
+###############################
+
+sub get_all {
+    my $class = shift;
+    my $dbh = Bugzilla->dbh;
+    my $table = $class->DB_TABLE;
+    my $order = $class->LIST_ORDER;
+
+    my $ids = $dbh->selectcol_arrayref(qq{
+        SELECT id FROM $table ORDER BY $order});
+
+    my $objects = $class->new_from_list($ids);
+    return @$objects;
+}
+
+1;
+
+__END__
+
+=head1 NAME
+
+Bugzilla::Object - A base class for objects in Bugzilla.
+
+=head1 SYNOPSIS
+
+ my $object = new Bugzilla::Object(1);
+ my $object = new Bugzilla::Object({name => 'TestProduct'});
+
+ my $id          = $object->id;
+ my $name        = $object->name;
+
+=head1 DESCRIPTION
+
+Bugzilla::Object is a base class for Bugzilla objects. You never actually
+create a Bugzilla::Object directly, you only make subclasses of it.
+
+Basically, Bugzilla::Object exists to allow developers to create objects
+more easily. All you have to do is define C<DB_TABLE>, C<DB_COLUMNS>,
+and sometimes C<LIST_ORDER> and you have a whole new object.
+
+You should also define accessors for any columns other than C<name>
+or C<id>.
+
+=head1 CONSTANTS
+
+Frequently, these will be the only things you have to define in your
+subclass in order to have a fully-functioning object. C<DB_TABLE>
+and C<DB_COLUMNS> are required.
+
+=over
+
+=item C<DB_TABLE>
+
+The name of the table that these objects are stored in. For example,
+for C<Bugzilla::Keyword> this would be C<keyworddefs>.
+
+=item C<DB_COLUMNS>
+
+The names of the columns that you want to read out of the database
+and into this object. This should be an array.
+
+=item C<LIST_ORDER>
+
+The order that C<new_from_list> and C<get_all> should return objects
+in. This should be the name of a database column. Defaults to
+C<name>.
+
+=back
+
+=head1 METHODS
+
+=over
+
+=item C<new($param)>
+
+ Description: The constructor is used to load an existing object
+              from the database, by id or by name.
+
+ Params:      $param - If you pass an integer, the integer is the
+                       id of the object, from the database, that we 
+                       want to read in. If you pass in a hash with 
+                       C<name> key, then the value of the name key 
+                       is the name of the object from the DB.
+
+ Returns:     A fully-initialized object.
+
+=item C<new_from_list(\@id_list)>
+
+ Description: Creates an array of objects, given an array of ids.
+
+ Params:      \@id_list - A reference to an array of numbers, database ids.
+                          If any of these are not numeric, the function
+                          will throw an error. If any of these are not
+                          valid ids in the database, they will simply 
+                          be skipped.
+
+ Returns:     A reference to an array of objects.
+
+=back
+
+=head1 SUBROUTINES
+
+=over
+
+=item C<get_all>
+
+ Description: Returns all objects in this table from the database.
+
+ Params:      none.
+
+ Returns:     A list of objects, or an empty list if there are none.
+
+ Notes:       Note that you must call this as C<$class->get_all>. For 
+              example, C<Bugzilla::Keyword->get_all>. 
+              C<Bugzilla::Keyword::get_all> will not work.
+
+=back
+
+=cut
diff --git a/Bugzilla/Search/Quicksearch.pm b/Bugzilla/Search/Quicksearch.pm
index e4224b959..13c185d7d 100644
--- a/Bugzilla/Search/Quicksearch.pm
+++ b/Bugzilla/Search/Quicksearch.pm
@@ -326,7 +326,7 @@ sub quicksearch {
                                              $word, $negate);
                                 }
                                 if (grep({lc($word) eq $_}
-                                         map($_->name, Bugzilla::Keyword::get_all_keywords()))) {
+                                         map($_->name, Bugzilla::Keyword->get_all))) {
                                     addChart('keywords', 'substring',
                                              $word, $negate);
                                     if (length($word)>2) {