5.7.55. Bugzilla::Object¶
5.7.55.1. NAME¶
Bugzilla::Object - A base class for objects in Bugzilla.
5.7.55.2. SYNOPSIS¶
my $object = new Bugzilla::Object(1);
my $object = new Bugzilla::Object({name => 'TestProduct'});
my $id = $object->id;
my $name = $object->name;
5.7.55.3. 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 DB_TABLE
, DB_COLUMNS
,
and sometimes LIST_ORDER
and you have a whole new object.
You should also define accessors for any columns other than name
or id
.
5.7.55.4. CONSTANTS¶
Frequently, these will be the only things you have to define in your
subclass in order to have a fully-functioning object. DB_TABLE
and DB_COLUMNS
are required.
DB_TABLE
The name of the table that these objects are stored in. For example, forBugzilla::Keyword
this would bekeyworddefs
.
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.
Note: Though normally you will never need to access this constant's data directly in your subclass, if you do, you should access it by calling the
_get_db_columns
method instead of accessing the constant directly. (The only exception to this rule is callingSUPER::DB_COLUMNS
from within your ownDB_COLUMNS
subroutine in a subclass.)
NAME_FIELD
The name of the column that should be considered to be the unique "name" of this object. The 'name' is a string that uniquely identifies this Object in the database. Defaults to 'name'. When you specify{name => $name}
tonew()
, this is the column that will be matched against in the DB.
ID_FIELD
The name of the column that represents the unique integer ID of this object in the database. Defaults to 'id'.
LIST_ORDER
The order thatnew_from_list
andget_all
should return objects in. This should be the name of a database column. Defaults to `NAME_FIELD`_.
VALIDATORS
A hashref that points to a function that will validate each param to `create`_.
Validators are called both by `create`_ and `set`_. When they are called by `create`_, the first argument will be the name of the class (what we normally call
$class
).When they are called by `set`_, the first argument will be a reference to the current object (what we normally call
$self
).The second argument will be the value passed to `create`_ or `set`_for that field.
The third argument will be the name of the field being validated. This may be required by validators which validate several distinct fields.
These functions should call Bugzilla::Error/ThrowUserError if they fail.
The validator must return the validated value.
UPDATE_VALIDATORS
This is just like `VALIDATORS`_, but these validators are called only when updating an object, not when creating it. Any validator that appears here must not appear in `VALIDATORS`_.
Bugzilla::Bug has good examples in its code of when to use this.
VALIDATOR_DEPENDENCIES
During `create`_ and `set_all`_, validators are normally called in a somewhat-random order. If you need one field to be validated and set before another field, this constant is how you do it, by saying that one field "depends" on the value of other fields.
This is a hashref, where the keys are field names and the values are arrayrefs of field names. You specify what fields a field depends on using the arrayrefs. So, for example, to say that a
component
field depends on theproduct
field being set, you would do:component => ['product']
UPDATE_COLUMNS
A list of columns to update when `update`_ is called. If a field can't be changed, it shouldn't be listed here. (For example, the `ID_FIELD`_ usually can't be updated.)
REQUIRED_FIELD_MAP
This is a hashref that maps database column names to `create`_ argument names. You only need to specify values for fields where the argument passed to `create`_ has a different name in the database than it does in the `create`_ arguments. (For example, Bugzilla::Bug/create takes aproduct
argument, but the column name in thebugs
table isproduct_id
.)
EXTRA_REQUIRED_FIELDS
Normally, Bugzilla::Object automatically figures out which fields are required for `create`_. It then always runs those fields' validators, even if those fields weren't passed as arguments to `create`_. That way, any default values or required checks can be done for those fields by the validators.
`create`_ figures out which fields are required by looking for database columns in the `DB_TABLE`_ that are NOT NULL and have no DEFAULT set. However, there are some fields that this check doesn't work for:
*
Fields that have database defaults (or are marked NULL in the database) but actually have different defaults specified by validators. (For example, the qa_contact field in thebugs
table can be NULL, so it won't be caught as being required. However, in reality it defaults to the component's initial_qa_contact.)*
Fields that have defaults that should be set by validators, but are actually stored in a table different from `DB_TABLE`_ (like the "cc" field for bugs, which defaults to the "initialcc" of the Component, but won't be caught as a normal required field because it's in a separate table.)Any field matching the above criteria needs to have its name listed in this constant. For an example of use, see the code of Bugzilla::Bug.
NUMERIC_COLUMNS
When `update`_ is called, it compares each column in the object to its current value in the database. It only updates columns that have changed.
Any column listed in NUMERIC_COLUMNS is treated as a number, not as a string, during these comparisons.
DATE_COLUMNS
This is much like `NUMERIC_COLUMNS`_, except that it treats strings as dates when being compared. So, for example,2007-01-01
would be equal to2007-01-01 00:00:00
.
5.7.55.5. METHODS¶
Constructors¶
new
Description
The constructor is used to load an existing object from the database, by id or by name.Params
If you pass an integer, the integer is the id of the object, from the database, that we want to read in. (id is defined as the value in the `ID_FIELD`_ column).
If you pass in a hashref, you can pass a
name
key. The value of thename
key is the case-insensitive name of the object (from `NAME_FIELD`_) in the DB. You can also pass in anid
key which will be interpreted as the id of the object you want (overriding thename
key).Additional Parameters Available for Subclasses
If you are a subclass of
Bugzilla::Object
, you can passcondition
andvalues
as hash keys, instead of the above.
condition
is a set of SQL conditions for the WHERE clause, which contain placeholders.
values
is a reference to an array. The array contains the values for each placeholder incondition
, in order.This is to allow subclasses to have complex parameters, and then to translate those parameters into
condition
andvalues
when they call$self->SUPER::new
(which is this function, usually).If you try to call
new
outside of a subclass with thecondition
andvalues
parameters, Bugzilla will throw an error. These parameters are intended only for use by subclasses.Returns
A fully-initialized object, orundef
if there is no object in the database matching the parameters you passed in.
initialize
Description
Abstract method to allow subclasses to perform initialization tasks after an object has been created.
check
Description
Checks if there is an object in the database with the specified name, and throws an error if you specified an empty name, or if there is no object in the database with that name.Params
The parameters are the same as for `new`_, except that if you don't pass a hashref, the single argument is the name of the object, not the id.Returns
A fully initialized object, guaranteed.Notes For Implementors
If you implement this in your subclass, make sure that you also update theobject_name
block at the bottom of the global/user-error.html.tmpltemplate.
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.
new_from_hash($hashref)
Description: Create an object from the given hash. Params: $hashref - A reference to a hash which was created by flatten_to_hash.
match
Description
Gets a list of objects from the database based on certain criteria.
Basically, a simple way of doing a sort of "SELECT" statement (like SQL) to get objects.
All criteria are joined by
AND
, so adding more criteria will give you a smaller set of results, not a larger set.Params
A hashref, where the keys are column names of the table, pointing to the value that you want to match against for that column.
There are two special values, the constants
NULL
andNOT_NULL
, which means "give me objects where this field is NULL or NOT NULL, respectively."In addition to the column keys, there are a few special keys that can be used to rig the underlying database queries. These are
LIMIT
,OFFSET
, andWHERE
.The value for the
LIMIT
key is expected to be an integer defining the number of objects to return, while the value forOFFSET
defines the position, relative to the number of objects the query would normally return, at which to begin the result set. IfOFFSET
is defined without a correspondingLIMIT
it is silently ignored.The
WHERE
key provides a mechanism for adding arbitrary WHERE clauses to the underlying query. Its value is expected to a hash reference whose keys are the columns, operators and placeholders, and the values are the placeholders' bind value. For example:WHERE => { 'some_column >= ?' => $some_value }would constrain the query to only those objects in the table whose 'some_column' column has a value greater than or equal to $some_value.
If you don't specify any criteria, calling this function is the same as doing
[$class->get_all]
.Returns
An arrayref of objects, or an empty arrayref if there are no matches.
Database Manipulation¶
create
- Description: Creates a new item in the database.
- Throws a User Error if any of the passed-in params are invalid.
- Params:
$params
- hashref - A value to put in each database- field for this object.
Returns: The Object just created in the database.
- Notes: In order for this function to work in your subclass,
- your subclass's `ID_FIELD`_ must be of
SERIAL
type in the database.- Subclass Implementors:
- This function basically just calls `check_required_create_fields`_, then `run_create_validators`_, and then finally `insert_create_data`_. So if you have a complex system that you need to implement, you can do it by calling these three functions instead of
SUPER::create
.
check_required_create_fields
Description
Part of `create`_. Modifies the incoming$params
argument so that any field that does not have a database default will be checked later by `run_create_validators`_, even if that field wasn't specified as an argument to `create`_.Params
Returns (nothing)
run_create_validators
- Description: Runs the validation of input parameters for `create`_.
- This subroutine exists so that it can be overridden by subclasses who need to do special validations of their input parameters. This method is only called by `create`_.
- Params:
$params
- hashref - A value to put in each database- field for this object.
$options
- hashref - Processing options. Currently the only option supported is skip, which can be used to specify a list of fields to not validate.- Returns: A hash, in a similar format as
$params
, except that- these are the values to be inserted into the database, not the values that were input to `create`_.
insert_create_data
Part of `create`_.
Takes the return value from `run_create_validators`_ and inserts the data into the database. Returns a newly created object.
update
Description
Saves the values currently in this object to the database. Only the fields specified in `UPDATE_COLUMNS`_ will be updated, and they will only be updated if their values have changed.Params (none)
Returns
In scalar context:
A hashref showing what changed during the update. The keys are the column names from `UPDATE_COLUMNS`_. If a field was not changed, it will not be in the hash at all. If the field was changed, the key will point to an arrayref. The first item of the arrayref will be the old value, and the second item will be the new value.
If there were no changes, we return a reference to an empty hash.
In array context:
Returns a list, where the first item is the above hashref. The second item is the object as it was in the database before update() was called. (This is mostly useful to subclasses of
Bugzilla::Object
that are implementingupdate
.)
remove_from_db
Removes this object from the database. Will throw an error if you can't remove it for some reason. The object will then be destroyed, as it is not safe to use the object after it has been removed from the database.
Mutators¶
These are used for updating the values in objects, before calling
update
.
set
Description
Sets a certain hash member of this class to a certain value. Used for updating fields. Calls the validator for this field, if it exists. Subclasses should use this function to implement the various
set_
mutators for their different fields.If your class defines a method called
_set_global_validator
,set
will call it with($value, $field)
as arguments, after running the validator for this particular field._set_global_validator
does not return anything.See `VALIDATORS`_ for more information.
NOTE: This function is intended only for use by subclasses. If you call it from anywhere else, it will throw a
CodeError
.Params
$field
- The name of the hash member to update. This should be the same as the name of the field in `VALIDATORS`_, if it exists there.
$value
- The value that you're setting the field to.Returns (nothing)
set_all
Description
This is a convenience function which is simpler than calling many differentset_
functions in a row. You pass a hashref of parameters and it callsset_$key($value)
for every item in the hashref.Params
Takes a hashref of the fields that need to be set, pointing to the value that should be passed to theset_
function that is called.Returns (nothing)
Simple Methods¶
flatten_to_hash
Returns a hashref suitable for serialisation and re-inflation withnew_from_hash
.
Simple Validators¶
You can use these in your subclass `VALIDATORS`_ or `UPDATE_VALIDATORS`_.
Note that you have to reference them like \&Bugzilla::Object::check_boolean
,
you can't just write \&check_boolean
.
check_boolean
Returns1
if the passed-in value is true,0
otherwise.
CACHE FUNCTIONS¶
object_cache_get
Description
Class function which returns an object from the object-cache for the provided$id
.Params
Takes an integer$id
of the object to retrieve.Returns
Returns the object from the cache if found, otherwise returnsundef
.Example
my $bug_from_cache = Bugzilla::Bug->object_cache_get(35);
object_cache_set
Description
Object function which injects the object into the object-cache, using the object'sid
as the key.Params
(none)Returns
(nothing)Example
$bug->object_cache_set();
5.7.55.6. CLASS FUNCTIONS¶
any_exist
Returns1
if there are any of these objects in the database,0
otherwise.
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 $class->get_all. For example, Bugzilla::Keyword->get_all. Bugzilla::Keyword::get_all will not work.