From 24a02ebf00c318c3406fc4c4f38a8f93480b0548 Mon Sep 17 00:00:00 2001 From: "mkanat%bugzilla.org" <> Date: Thu, 1 Jun 2006 07:23:17 +0000 Subject: Bug 329377: Bugzilla::Object base class for objects Patch By Max Kanat-Alexander r=LpSolit, r=kevin.benton, a=justdave --- Bugzilla/Object.pm | 227 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 227 insertions(+) create mode 100644 Bugzilla/Object.pm (limited to 'Bugzilla/Object.pm') 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 + +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, C, +and sometimes C and you have a whole new object. + +You should also define accessors for any columns other than C +or C. + +=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 +and C are required. + +=over + +=item C + +The name of the table that these objects are stored in. For example, +for C this would be C. + +=item C + +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 + +The order that C and C should return objects +in. This should be the name of a database column. Defaults to +C. + +=back + +=head1 METHODS + +=over + +=item C + + 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 key, then the value of the name key + is the name of the object from the DB. + + Returns: A fully-initialized object. + +=item C + + 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 + + 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, Cget_all>. + C will not work. + +=back + +=cut -- cgit v1.2.3-24-g4f1b