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 calling SUPER::DB_COLUMNS from within your own DB_COLUMNS subroutine in a subclass.)

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} to new(), this is the column that will be matched against in the DB.

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 the product field being set, you would do:

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, "create" in Bugzilla::Bug takes a product argument, but the column name in the bugs table is product_id.)

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 the bugs 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.

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 the name key is the case-insensitive name of the object (from "NAME_FIELD") in the DB. You can also pass in an id key which will be interpreted as the id of the object you want (overriding the name key).

Additional Parameters Available for Subclasses

If you are a subclass of Bugzilla::Object, you can pass condition and values 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 in condition, in order.

This is to allow subclasses to have complex parameters, and then to translate those parameters into condition and values when they call $self->SUPER::new (which is this function, usually).

If you try to call new outside of a subclass with the condition and values parameters, Bugzilla will throw an error. These parameters are intended only for use by subclasses.

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.

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 and NOT_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, and WHERE.

The value for the LIMIT key is expected to be an integer defining the number of objects to return, while the value for OFFSET defines the position, relative to the number of objects the query would normally return, at which to begin the result set. If OFFSET is defined without a corresponding LIMIT 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].

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".

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".

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 implementing update.)

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.

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.

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.