Provided by: libjifty-dbi-perl_0.78-2_all bug

NAME

       Jifty::DBI::Record - Superclass for records loaded by Jifty::DBI::Collection

SYNOPSIS

         package MyRecord;
         use base qw/Jifty::DBI::Record/;

DESCRIPTION

       Jifty::DBI::Record encapsulates records and tables as part of the Jifty::DBI object-
       relational mapper.

METHODS

   new ARGS
       Instantiate a new, empty record object.

       ARGS is a hash used to pass parameters to the "_init()" function.

       Unless it is overloaded, the _init() function expects one key of 'handle' with a value
       containing a reference to a Jifty::DBI::Handle object.

   id
       Returns this row's primary key.

   primary_keys
       Return a hash of the values of our primary keys for this function.

   _accessible COLUMN ATTRIBUTE
       Private method.

       DEPRECATED

       Returns undef unless "COLUMN" has a true value for "ATTRIBUTE".

       Otherwise returns "COLUMN"'s value for that attribute.

   _primary_keys
       Return our primary keys. (Subclasses should override this, but our default is that we have
       one primary key, named 'id'.)

   _init_columns
       Sets up the primary key columns.

   _init_methods_for_columns
       This is an internal method responsible for calling "_init_methods_for_column" for each
       column that has been configured.

   schema_version
       If present, this method must return a string in '1.2.3' format to be used to determine
       which columns are currently active in the schema. That is, this value is used to determine
       which columns are defined, based upon comparison to values set in "till" and "since".

       If no implementation is present, the "latest" schema version is assumed, meaning that any
       column defining a "till" is not active and all others are.

   _init_methods_for_column COLUMN
       This method is used internally to update the symbol table for the record class to include
       an accessor and mutator for each column based upon the column's name.

       In addition, if your record class defines the method "schema_version", it will
       automatically generate methods according to whether the column currently exists for the
       current application schema version returned by that method. The "schema_version" method
       must return a value in the same form used by "since" and "till".

       If the column doesn't currently exist, it will create the methods, but they will die with
       an error message stating that the column does not exist for the current version of the
       application. If it does exist, a normal accessor and mutator will be created.

       See also "active" in Jifty::DBI::Column, "since" in Jifty::DBI::Schema, "till" in
       Jifty::DBI::Schema for more information.

   null_reference
       By default, Jifty::DBI::Record will return "undef" for non-existent foreign references
       which don't exist.  That is, if each Employee "refers_to" a Department, but isn't required
       to, "<$model-"department>> will return "undef" for employees not in a department.

       Overriding this method to return 0 will cause it to return a record with no id.  That is,
       "<$model-"department>> will return a Department object, but "<$model-"department->id>>
       will be "undef".

   _to_record COLUMN VALUE
       This PRIVATE method takes a column name and a value for that column.

       It returns "undef" unless "COLUMN" is a valid column for this record that refers to
       another record class.

       If it is valid, this method returns a new record object with an id of "VALUE".

   prefetched NAME
       Returns the prefetched value for column of property "NAME", if it exists.

   add_column
   column
           my $column = $self->column($column_name);

       Returns the Jifty::DBI::Column object of the specified column name.

   columns
           my @columns = $record->columns;

       Returns a sorted list of a $record's @columns.

   all_columns
         my @all_columns = $record->all_columns;

       Returns all the columns for the table, even those that are inactive.

   readable_attributes
       Returns the list of this table's readable columns. They are first sorted so that primary
       keys come first, and then they are sorted in alphabetical order.

   serialize_metadata
       Returns a hash which describes how this class is stored in the database.  Right now, the
       keys are "class", "table", and "columns". "class" and "table" return simple scalars, but
       "columns" returns a hash of "name =&gt; value" pairs for all the columns in this model.
       See "Jifty::DBI::Column/serialize_metadata" for the format of that hash.

   writable_attributes
       Returns a list of this table's writable columns

   record values
       As you've probably already noticed, "Jifty::DBI::Record" automatically creates methods for
       your standard get/set accessors. It also provides you with some hooks to massage the
       values being loaded or stored.

       When you fetch a record value by calling "$my_record->some_field", "Jifty::DBI::Record"
       provides the following hook

       after_column_name
           This hook is called with a reference to the value returned by Jifty::DBI. Its return
           value is discarded.

       When you set a value, "Jifty::DBI" provides the following hooks

       before_set_column_name PARAMHASH
           "Jifty::DBI::Record" passes this function a reference to a paramhash composed of:

           column
               The name of the column we're updating.

           value
               The new value for column.

           is_sql_function
               A boolean that, if true, indicates that value is an SQL function, not just a
               value.

           If before_set_column_name returns false, the new value isn't set.

       before_set PARAMHASH
           This is identical to the "before_set_column_name", but is called for every column set.

       after_set_column_name PARAMHASH
           This hook will be called after a value is successfully set in the database. It will be
           called with a reference to a paramhash that contains "column", "value", and
           "old_value" keys. If "value" was a SQL function, it will now contain the actual value
           that was set. If "column" has filters on it, "value" will be the result of going
           through an encode and decode cycle.

           This hook's return value is ignored.

       after_set PARAMHASH
           This is identical to the "after_set_column_name", but is called for every column set.

       validate_column_name VALUE
           This hook is called just before updating the database. It expects the actual new value
           you're trying to set column_name to. It returns two values.  The first is a boolean
           with truth indicating success. The second is an optional message. Note that
           validate_column_name may be called outside the context of a set operation to validate
           a potential value. (The Jifty application framework uses this as part of its AJAX
           validation system.)

   _value
       _value takes a single column name and returns that column's value for this row.
       Subclasses can override _value to insert custom access control.

   __raw_value
       Takes a column name and returns that column's raw value.  Subclasses should never override
       __raw_value.

   resolve_column
       given a column name, resolve it, even if it's actually an alias return the column object.

   __value
       Takes a column name and returns that column's value. Subclasses should never override
       __value.

   as_hash
       Returns a version of this record's readable columns rendered as a hash of key => value
       pairs

   _set
       _set takes a single column name and a single unquoted value.  It updates both the in-
       memory value of this column and the in-database copy.  Subclasses can override _set to
       insert custom access control.

   load
       "load" can be called as a class or object method.

       Takes a single argument, $id. Calls load_by_cols to retrieve the row whose primary key is
       $id.

   load_by_cols
       "load_by_cols" can be called as a class or object method.

       Takes a hash of columns and values. Loads the first record that matches all keys.

       The hash's keys are the columns to look at.

       The hash's values are either: scalar values to look for OR hash references which contain
       'operator', 'value', 'case_sensitive' or 'function'

       To load something case sensitively on a case insensitive database, you can do:

         $record->load_by_cols( column => { operator => '=',
                                            value => 'Foo',
                                            case_sensitive => 1 } );

   load_by_primary_keys
       Loads records with a given set of primary keys.

   load_from_hash
       Takes a hashref, such as created by Jifty::DBI and populates this record's loaded values
       hash.

   _load_from_sql QUERYSTRING @BIND_VALUES
       Load a record as the result of an SQL statement

   create PARAMHASH
       "create" can be called as either a class or object method

       This method creates a new record with the values specified in the PARAMHASH.

       This method calls two hooks in your subclass:

       before_create
           When adding the "before_create" trigger, you can determine whether the trigger may
           cause an abort or not by passing the "abortable" parameter to the "add_trigger"
           method. If this is not set, then the return value is ignored regardless.

             sub before_create {
                 my $self = shift;
                 my $args = shift;

                 # Do any checks and changes on $args here.
                 $args->{first_name} = ucfirst $args->{first_name};

                 return;      # false return vallue will abort the create
                 return 1;    # true return value will allow create to continue
             }

           This method is called before trying to create our row in the database. It's handed a
           reference to your paramhash. (That means it can modify your parameters on the fly).
           "before_create" returns a true or false value. If it returns "undef" and the trigger
           has been added as "abortable", the create is aborted.

       after_create
           When adding the "after_create" trigger, you can determine whether the trigger may
           cause an abort or not by passing the "abortable" parameter to the "add_trigger"
           method. If this is not set, then the return value is ignored regardless.

             sub after_create {
                 my $self                    = shift;
                 my $insert_return_value_ref = shift;

                 return unless $$insert_return_value_ref;    # bail if insert failed
                 $self->load($$insert_return_value_ref);     # load ourselves from db

                 # Do whatever needs to be done here

                 return;   # aborts the create, possibly preventing a load
                 return 1; # continue normally
             }

           This method is called after attempting to insert the record into the database. It gets
           handed a reference to the return value of the insert. That will either be a true value
           or a Class::ReturnValue.

           Aborting the trigger merely causes "create" to return a false (undefined) value even
           thought he create may have succeeded. This prevents the loading of the record that
           would normally be returned.

   delete
       Delete this record from the database. On failure return a Class::ReturnValue with the
       error. On success, return 1;

       This method has two hooks:

       before_delete
           This method is called before the record deletion, if it exists. On failure it returns
           a Class::ReturnValue with the error.  On success it returns 1.

           If this method returns an error, it causes the delete to abort and return the return
           value from this hook.

       after_delete
           This method is called after deletion, with a reference to the return value from the
           delete operation.

   table
       This method returns this class's default table name. It uses Lingua::EN::Inflect to
       pluralize the class's name as we believe that class names for records should be in the
       singular and table names should be plural.

       If your class name is "My::App::Rhino", your table name will default to "rhinos". If your
       class name is "My::App::RhinoOctopus", your default table name will be "rhino_octopuses".
       Not perfect, but arguably correct.

   collection_class
       Returns the collection class which this record belongs to; override this to subclass.  If
       you haven't specified a collection class, this returns a best guess at the name of the
       collection class for this collection.

       It uses a simple heuristic to determine the collection class name -- It appends
       "Collection" to its own name. If you want to name your records and collections
       differently, go right ahead, but don't say we didn't warn you.

   _guess_table_name
       Guesses a table name based on the class's last part.

   _handle
       Returns or sets the current Jifty::DBI::Handle object

   PRIVATE refers_to
       used for the declarative syntax

   is_distinct COLUMN_NAME, VALUE
       Checks to see if there is already a record in the database where COLUMN_NAME equals VALUE.
       If no such record exists then the COLUMN_NAME and VALUE pair is considered distinct and it
       returns 1.  If a value is already present the test is considered to have failed and it
       returns a Class::ReturnValue with the error.

   run_canonicalization_for_column column => 'COLUMN', value => 'VALUE'
       Runs all canonicalizers for the specified column.

   has_canonicalizer_for_column COLUMN
       Returns true if COLUMN has a canonicalizer, otherwise returns undef.

   run_validation_for_column column => 'COLUMN', value => 'VALUE' [extra => \@ARGS]
       Runs all validators for the specified column.

   has_validator_for_column COLUMN
       Returns true if COLUMN has a validator, otherwise returns undef.

   unload_value COLUMN
       Purges the cached value of COLUMN from the object, forcing it to be fetched from the
       database next time it is queried.

AUTHOR

       Jesse Vincent <jesse@bestpractical.com>, Alex Vandiver <alexmv@bestpractical.com>, David
       Glasser <glasser@bestpractical.com>, Ruslan Zakirov <ruslan.zakirov@gmail.com>

       Based on DBIx::SearchBuilder::Record, whose credits read:

        Jesse Vincent, <jesse@fsck.com>
        Enhancements by Ivan Kohler, <ivan-rt@420.am>
        Docs by Matt Knopp <mhat@netlag.com>

SEE ALSO

       Jifty::DBI, Jifty::DBI::Handle, Jifty::DBI::Collection.