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

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_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";
    }

AUTHOR

John C. Siracusa (siracusa@mindspring.com)

COPYRIGHT

Copyright (c) 2006 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.