<<

# Bugzilla::Object

- NAME
- SYNOPSIS
- DESCRIPTION
- CONSTANTS
- METHODS
  - Constructors
  - Database Manipulation
  - Subclass Helpers
- CLASS FUNCTIONS

# NAME

Bugzilla::Object - A base class for objects in Bugzilla.

# SYNOPSIS

     my $object = new Bugzilla::Object(1);
     my $object = new Bugzilla::Object({name => 'TestProduct'});

     my $id          = $object->id;
     my $name        = $object->name;

# 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`.

# 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, for `Bugzilla::Keyword` this would be `keyworddefs`.

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

`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}> to `new()`, 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 that `new_from_list` and `get_all` should return objects in. This should be the name of a database column. Defaults to "NAME_FIELD".

`REQUIRED_CREATE_FIELDS`

  The list of fields that must be specified when the user calls `create()`. This should be an array.

`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 "ThrowUserError" in Bugzilla::Error if they fail.

  The validator must return the validated value.

`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.)

# METHODS

## Constructors

`new($param)`
  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 hash, 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.

    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.

  Returns

    A fully-initialized object.

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

## 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. Certain values must be set (the ones specified in "REQUIRED_CREATE_FIELDS"), and the function will throw a Code Error if you don't set them.

  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. Your subclass also must define "REQUIRED_CREATE_FIELDS" and "VALIDATORS".

                   Subclass Implementors: This function basically just
                   calls L</check_required_create_fields>, then
                   L</run_create_validators>, and then finally
                   L</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 C<SUPER::create>.

`check_required_create_fields`
  Description

    Part of "create". Throws an error if any of the "REQUIRED_CREATE_FIELDS" have not been specified in `$params`

  Params
    `$params` - The same as `$params` from "create".
  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: The same as "create".

  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

    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.

## Subclass Helpers

These functions are intended only for use by subclasses. If you call them from anywhere else, they will throw a `CodeError`.

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

    See "VALIDATORS" for more information.

  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)

# CLASS FUNCTIONS

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

<<