The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Rose-DB-Object-0.764
River stage two • 19 direct dependents • 19 total dependents
20 ++
/ Rose::DB::Object::Helpers

NAME

Rose::DB::Object::Helpers - A mix-in class containing convenience methods for Rose::DB::Object.

SYNOPSIS

  package MyDBObject;

  use Rose::DB::Object;
  our @ISA = qw(Rose::DB::Object);

  use Rose::DB::Object::Helpers 'clone', 
    { load_or_insert => 'find_or_create' };
  ...

  $obj = MyDBObject->new(id => 123);
  $obj->find_or_create();

  $obj2 = $obj->clone;

DESCRIPTION

Rose::DB::Object::Helpers provides convenience methods from use with Rose::DB::Object-derived classes. These methods do not exist in Rose::DB::Object in order to keep the method namespace clean. (Each method added to Rose::DB::Object is another potential naming conflict with a column accessor.)

This class inherits from Rose::DB::Object::MixIn. See the Rose::DB::Object::MixIn documentation for a full explanation of how to import methods from this class. The helper methods themselves are described below.

OBJECT METHODS

clone

Returns a new object initialized with the column values of the existing object. For example, imagine a Person class with three columns, id, name, and age.

    $a = Person->new(id => 123, name => 'John', age => 30);

This use of the clone() method:

    $b = $a->clone;

is equivalent to this:

    $b = Person->new(id => $a->id, name => $a->name, age => $a->age);
clone_and_reset

This is the same as the clone method described above, except that it also sets all of the primary and unique key columns to undef. If the cloned object has a db attribute, then it is copied to the clone object as well.

For example, imagine a Person class with three columns, id, name, and age, where id is the primary key and name is a unique key.

    $a = Person->new(id => 123, name => 'John', age => 30, db => $db);

This use of the clone_and_reset() method:

    $b = $a->clone_and_reset;

is equivalent to this:

    $b = Person->new(id => $a->id, name => $a->name, age => $a->age);
    $b->id(undef);   # reset primary key
    $b->name(undef); # reset unique key
    $b->db($a->db);  # copy db
column_values_as_json

Returns a string containing a JSON representation of the object's column values. You must have the JSON::Syck module installed in order to use this helper method.

column_values_as_yaml

Returns a string containing a YAML representation of the object's column values. You must have the YAML::Syck module installed in order to use this helper method.

column_accessor_value_pairs

Returns a hash (in list context) or reference to a hash (in scalar context) of column accessor method names and column values. The keys of the hash are the accessor method names for the columns. The values are retrieved by calling the accessor method for each column.

column_mutator_value_pairs

Returns a hash (in list context) or reference to a hash (in scalar context) of column mutator method names and column values. The keys of the hash are the mutator method names for the columns. The values are retrieved by calling the accessor method for each column.

column_value_pairs

Returns a hash (in list context) or reference to a hash (in scalar context) of column name and value pairs. The keys of the hash are the names of the columns. The values are retrieved by calling the accessor method for each column.

Given a foreign key or relationship name, return true if one or more related objects have been loaded into the current object, false otherwise.

If the name is passed as a plain string NAME, then a foreign key with that name is looked up. If no such foreign key exists, then a relationship with that name is looked up. If no such relationship or foreign key exists, a fatal error will occur. Example:

    $foo->has_loaded_related('bar');

It's generally not a good idea to add a foreign key and a relationship with the same name, but it is technically possible. To specify the domain of the name, pass the name as the value of a foreign_key or relationship parameter. Example:

    $foo->has_loaded_related(foreign_key => 'bar');
    $foo->has_loaded_related(relationship => 'bar');
init_with_column_value_pairs [ HASH | HASHREF ]

Initialize an object with a hash or reference to a hash of column/value pairs. This differs from the inherited init method in that it accepts column names rather than method names. A column name may not be the same as its mutator method name if the column is aliased, for example.

    $p = Person->new; # assume "type" column is aliased to "person_type"

    # init() takes method/value pairs
    $p->init(person_type => 'cool', age => 30);

    # Helper takes a hashref of column/value pairs
    $p->init_with_column_value_pairs({ type => 'cool', age => 30 });

    # ...or a hash of column/value pairs
    $p->init_with_column_value_pairs(type => 'cool', age => 30);
init_with_json JSON

Initialize the object with a JSON-formatted string. The JSON string must be in the format returned by the column_values_as_json method. Example:

    $p1 = Person->new(name => 'John', age => 30);
    $json = $p1->column_values_as_json;

    $p2 = Person->new;
    $p2->init_with_json($json);

    print $p2->name; # John
    print $p2->age;  # 30
init_with_yaml YAML

Initialize the object with a YAML-formatted string. The YAML string must be in the format returned by the column_values_as_yaml method. Example:

    $p1 = Person->new(name => 'John', age => 30);
    $yaml = $p1->column_values_as_yaml;

    $p2 = Person->new;
    $p2->init_with_yaml($yaml);

    print $p2->name; # John
    print $p2->age;  # 30
insert_or_update [PARAMS]

If the object already exists in the database, then update it. Otherwise, insert it. Any PARAMS are passed on to the calls to insert or update.

This method differs from the standard save method in that save decides to insert or update based solely on whether or not the object was previously loaded. This method will take the extra step of actually attempting to load the object to see whether or not it's in the database.

The return value of the insert or update method (whichever is called) is returned.

insert_or_update_on_duplicate_key [PARAMS]

Update or insert a row with a single SQL statement, depending on whether or not a row with the same primary or unique key already exists. Any PARAMS are passed on to the call to insert or update.

If the current database does not support the "ON DUPLICATE KEY UPDATE" SQL extension, then this method simply call the insert_or_update method, pasing all PARAMS.

Currently, the only database that supports "ON DUPLICATE KEY UPDATE" is MySQL, and only in version 4.1.0 or later. You can read more about the feature here:

http://dev.mysql.com/doc/refman/5.1/en/insert-on-duplicate.html

Here's a quick example of the SQL syntax:

    INSERT INTO table (a, b, c) VALUES (1, 2, 3) 
      ON DUPLICATE KEY UPDATE a = 1, b = 2, c = 3;

Note that there are two sets of columns and values in the statement. This presents a choice: which columns to put in the "INSERT" part, and which to put in the "UPDATE" part.

When using this method, if the object was previously loaded from the database, then values for all columns are put in both the "INSERT" and "UPDATE" portions of the statement.

Otherwise, all columns are included in both clauses except those belonging to primary keys or unique keys which have only undefined values. This is important because it allows objects to be updated based on a single primary or unique key, even if other possible keys exist, but do not have values set. For example, consider this table with the following data:

    CREATE TABLE parts
    (
      id      INT PRIMARY KEY,
      code    CHAR(3) NOT NULL,
      status  CHAR(1),

      UNIQUE(code)
    );

    INSERT INTO parts (id, code, status) VALUES (1, 'abc', 'x');

This code will update part id 1, setting its "status" column to "y".

    $p = Part->new(code => 'abc', status => 'y');
    $p->insert_or_update_on_duplicate_key;

The resulting SQL:

    INSERT INTO parts (code, status) VALUES ('abc', 'y') 
      ON DUPLICATE KEY UPDATE code = 'abc', status = 'y';

Note that the "id" column is omitted because it has an undefined value. The SQL statement will detect the duplicate value for the unique key "code" and then run the "UPDATE" portion of the query, setting "status" to "y".

This method returns true if the row was inserted or updated successfully, false otherwise. The true value returned on success will be the object itself. If the object overloads its boolean value such that it is not true, then a true value will be returned instead of the object itself.

Yes, this method name is very long. Remember that you can rename methods on import. It is expected that most people will want to rename this method to "insert_or_update", using it in place of the normal insert_or_update helper method:

    package My::DB::Object;
    ...
    use Rose::DB::Object::Helpers 
      { insert_or_update_on_duplicate_key => 'insert_or_update' };
load_or_insert [PARAMS]

Try to load the object, passing PARAMS to the call to the load() method. The parameter "speculative => 1" is automatically added to PARAMS. If no such object is found, then the object is inserted.

Example:

    # Get object id 123 if it exists, otherwise create it now.
    $obj = MyDBObject->new(id => 123)->load_or_insert;
load_or_save [PARAMS]

Try to load the object, passing PARAMS to the call to the load() method. The parameter "speculative => 1" is automatically added to PARAMS. If no such object is found, then the object is saved.

This methods differs from load_or_insert in that the save method will also save sub-objects. See the documentation for Rose::DB::Object's save method for more information.

Example:

    @perms = (Permission->new(...), Permission->new(...));

    # Get person id 123 if it exists, otherwise create it now
    # along with permission sub-objects.
    $person = Person->new(id    => 123, 
                          perms => \@perms)->load_or_insert;
load_speculative [PARAMS]

Try to load the object, passing PARAMS to the call to the load() method along with the "speculative => 1" parameter. See the documentation for Rose::DB::Object's load method for more information.

Example:

    $obj = MyDBObject->new(id => 123);

    if($obj->load_speculative)
    {
      print "Found object id 123\n";
    }
    else
    {
      print "Object id 123 not found\n";
    }
strip [PARAMS]

This method prepares an object for serialization by stripping out internal structures known to contain code references or other values that do not survive serialization. By default, the db object and all sub-objects (foreign keys or relationships) are removed. PARAMS are optional name/value pairs. Valid PARAMS are:

leave [NAME|ARRAYREF]

This parameter specifies which items to leave un-stripped. The value may be an item name or a reference to an array of item names. Valid names are:

db

Do not remove the db object. The db object will have its DBI database handle (dbh) removed, however.

foreign_keys

Do not removed sub-objects that have already been loaded by this object through foreign keys.

relationships

Do not removed sub-objects that have already been loaded by this object through relationships.

Do not remove any sub-objects (foreign keys or relationships) that have already been loaded by this object. This option is the same as specifying both the foreign_keys and <relationships> names.

AUTHOR

John C. Siracusa (siracusa@mindspring.com)

COPYRIGHT

Copyright (c) 2007 by John C. Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.