Rose::DB::Object::Manager - Fetch multiple Rose::DB::Object-derived objects from the database.
package Category; use Rose::DB::Object; our @ISA = qw(Rose::DB::Object); __PACKAGE__->meta->table('categories'); __PACKAGE__->meta->columns ( id => { type => 'int', primary_key => 1 }, name => { type => 'varchar', length => 255 }, description => { type => 'text' }, ); __PACKAGE__->meta->add_unique_key('name'); __PACKAGE__->meta->initialize; ... package Product; use Rose::DB::Object; our @ISA = qw(Rose::DB::Object); __PACKAGE__->meta->table('products'); __PACKAGE__->meta->columns ( id => { type => 'int', primary_key => 1 }, name => { type => 'varchar', length => 255 }, description => { type => 'text' }, category_id => { type => 'int' }, status => { type => 'varchar', check_in => [ 'active', 'inactive' ], default => 'inactive', }, start_date => { type => 'datetime' }, end_date => { type => 'datetime' }, date_created => { type => 'timestamp', default => 'now' }, last_modified => { type => 'timestamp', default => 'now' }, ); __PACKAGE__->meta->add_unique_key('name'); __PACKAGE__->meta->foreign_keys ( category => { class => 'Category', key_columns => { category_id => 'id', } }, ); __PACKAGE__->meta->initialize; ... package Product::Manager; use Rose::DB::Object::Manager; our @ISA = qw(Rose::DB::Object::Manager); sub get_products { my $class = shift; Rose::DB::Object::Manager->get_objects( object_class => 'Product', @_) } sub get_products_iterator { my $class = shift; Rose::DB::Object::Manager->get_objects_iterator( object_class => 'Product', @_) } sub get_products_count { my $class = shift; Rose::DB::Object::Manager->get_objects_count( object_class => 'Product', @_) } ... # # Get a reference to an array of objects # $products = Product::Manager->get_products ( query => [ category_id => [ 5, 7, 22 ], status => 'active', start_date => { lt => '15/12/2005 6:30 p.m.' }, name => { like => [ '%foo%', '%bar%' ] }, ], sort_by => 'category_id, start_date DESC', limit => 100 ) or die Product::Manager->error; foreach my $product (@$products) { print $product->id, ' ', $product->name, "\n"; } # # Get objects iterator # $iterator = Product::Manager->get_products_iterator ( query => [ category_id => [ 5, 7, 22 ], status => 'active', start_date => { lt => '15/12/2005 6:30 p.m.' }, name => { like => [ '%foo%', '%bar%' ] }, ], sort_by => 'category_id, start_date DESC', limit => 100 ) or die Product::Manager->error; while($product = $iterator->next) { print $product->id, ' ', $product->name, "\n"; } print $iterator->total; # # Get objects count # $count = Product::Manager->get_products_count ( query => [ category_id => [ 5, 7, 22 ], status => 'active', start_date => { lt => '15/12/2005 6:30 p.m.' }, name => { like => [ '%foo%', '%bar%' ] }, ], limit => 100 ); die Product::Manager->error unless(defined $count); print $count; # or Product::Manager->total() # # Get objects and sub-objects in a single query # $products = Product::Manager->get_products ( with_objects => [ 'category' ], query => [ category_id => [ 5, 7, 22 ], status => 'active', start_date => { lt => '15/12/2005 6:30 p.m.' }, name => { like => [ '%foo%', '%bar%' ] }, ], sort_by => 'category_id, start_date DESC', limit => 100 ) or die Product::Manager->error; foreach my $product (@$products) { print $product->name, ': ', $product->category->name, "\n"; }
Rose::DB::Object::Manager is a base class for classes that select rows from tables fronted by Rose::DB::Object-derived classes. Each row in the table(s) queried is converted into the equivalent Rose::DB::Object-derived object.
Rose::DB::Object::Manager
Rose::DB::Object
Class methods are provided for fetching objects all at once, one at a time through the use of an iterator, or just getting the object count. Subclasses are expected to create syntactically pleasing wrappers for Rose::DB::Object::Manager class methods. A very minimal example is shown in the synopsis above.
Returns the text message associated with the last error, or false if there was no error.
Get or set the error mode for this class. If the error mode is false, then it defaults to the return value of the init_error_mode() class method, which is "return" by default.
init_error_mode()
The error mode determines what happens when a method of this class encounters an error. The default mode, "return", causes the methods to behave as described in this documentation. All other error modes cause an action to be performed before returning as per the documentation.
Valid values of MODE are:
Call Carp::carp() with the value of the error() class method as an argument.
Carp::carp()
error()
Call Carp::cluck() with the value of the error() class method as an argument.
Carp::cluck()
Call Carp::confess() with the value of the error() class method as an argument. =item croak
Carp::confess()
Call Carp::croak() with the value of the error() class method as an argument.
Carp::croak()
An alias for the "croak" mode.
Return a value that indicates that an error has occurred, as described in the documentation for each method.
In all cases, the class's error attribute will also contain the error message.
error
Get Rose::DB::Object-derived objects based on PARAMS, where PARAMS are name/value pairs. Returns a reference to a (possibly empty) array in scalar context, a list of objects in list context, or undef if there was an error.
Note that naively calling this method in list context may result in a list containing a single undef element if there was an error. Example:
# If there is an error, you'll get: @objects = (undef) @objects = Rose::DB::Object::Manager->get_objects(...);
If you want to avoid this, feel free to change the behavior your wrapper method, or just call it in scalar context (which is more efficient anyway for long lists of objects).
Valid parameters are:
db DB
A Rose::DB-derived object used to access the database. If omitted, one will be created by calling the init_db() object method of the object_class.
Rose::DB
init_db()
object_class
object_args HASHREF
A reference to a hash of name/value pairs to be passed to the constructor of each object_class object fetched, in addition to the values from the database.
object_class CLASS
The class name of the Rose::DB::Object-derived objects to be fetched. This parameter is required; a fatal error will occur if it is omitted.
share_db BOOL
If true, db will be passed to each Rose::DB::Object-derived object when it is constructed. Defaults to true.
db
with_object OBJECTS
Also fetch sub-objects associated with foreign keys in the primary table, where OBJECTS is a reference to an array of foreign key names, as defined by the Rose::DB::Object::Metadata object for object_class.
Rose::DB::Object::Metadata
Another table will be added to the query for each foreign key listed. The "join" clauses will be added automatically based on the foreign key definitions. Note that (obviously) each foreign key table has to have a Rose::DB::Object-derived class fronting it. See the synopsis for a simple example.
Any parameter that can be passed to the build_select() function of the Rose::DB::Object::QueryBuilder module can also be passed to this method, which will then pass them on to build_select() to create the SQL query string used to fetch the objects.
build_select()
Rose::DB::Object::QueryBuilder
Accepts the same arguments as get_objects(), but just returns the number of rows that would have been fetched, or undef if there was an error.
get_objects()
Accepts any valid get_objects() argument, but return a Rose::DB::Objects::Iterator object which can be used to fetch the objects one at a time, or undef if there was an error.
Rose::DB::Objects::Iterator
Additional valid parameters are:
skip_first NUM
Skip the first NUM rows before returning the first object from the iterator. This is for databases that do not support an offset value in their SQL "LIMIT" clauses (e.g., Informix).
Accepts the same arguments as get_objects(), but return the SQL query string that would have been used to fetch the objects (in scalar context), or the SQL query string and a reference to an array of bind values (in list context).
John C. Siracusa (siracusa@mindspring.com)
Copyright (c) 2005 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.
To install Rose::DB::Object, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Rose::DB::Object
CPAN shell
perl -MCPAN -e shell install Rose::DB::Object
For more information on module installation, please visit the detailed CPAN module installation guide.