Rose::DBx::Object::InternalPager 0.03

######################################################################
Rose::DBx::Object::InternalPager 0.03
######################################################################

NAME
Rose::DBx::Object::InternalPager - Throttle Rose DB Iterator Fetching

SYNOPSIS
use Rose::DBx::Object::InternalPager;

my $pager = Rose::DBx::Object::InternalPager->new(
class_name => "Namespace::Author",
manager_method => "get_authors",
manager_options => {
query => [ published => 'yes' ],
require_objects => [ 'city_of_birth' ],
sort_by => 'last_name',
},
);

while(my $author = $pager->next()) {
print $author->first_name(), " ",
$author->last_name(), " ",
$author->city_of_birth->string(), "\n";
}

DESCRIPTION
"Rose::DBx::Object::InternalPager" is a 3rd party module for "Rose::DB"
iterators to work around MySQL client's limited control over how many
rows are fetched from the database at a time.

"Rose::DBx::Object::InternalPager" provides a hack to limit the number
of fetched records and prevents programs from running out of memory.

The pager creates an iterator object, similar to the Rose "Manager"'s
"get_xxx_iterator()", method. Except, behind the scenes, the pager makes
sure to never fetch more than a preset number of records from the
database at a time. To accomplish this, it uses LIMIT to limit the
number of records retrieved, and OFFSET to fetch the next batch.

This approach might lead to anomalies when the database gets modified
while the pager is at work, and this is the reason why this module has
been released *outside* of the "Rose::DB" realm as a 3rd party module.

While normally, you would call

my $itr = Namespace::Author::Manager->get_authors_iterator(...);

to get an iterator object which offers a "next()" method to move from
one database record to the next. With
"Rose::DBx::Object::InternalPager", you call

my $pager = Rose::DBx::Object::InternalPager->new(
class_name => "Namespace::Author", # Note: no 'Manager'
manager_method => "get_authors", # Note: no 'iterator'
# ...
);

which returns a pager object that can be used to iterate over all
database records found via

while(my $author = $pager->next()) {
# ...
}

Just as the manager's "get_xxx_iterator()" method offers ways to modify
the query with "query", "sort_by" and other parameters, these parameters
can be set with the pager by using the "manager_options" parameter:

my $pager = Rose::DBx::Object::InternalPager->new(
class_name => "Namespace::Author", # Note: no 'Manager'
manager_method => "get_authors", # Note: no 'iterator'
manager_options => {
query => [ published => 'yes' ],
require_objects => [ 'city_of_birth' ],
sort_by => 'last_name',
},
);

By default, the pager fetches 50 records at a time. This value can be
modified by setting the "per_page" parameter in the optional
"pager_options" hash:

my $pager = Rose::DBx::Object::InternalPager->new(
# ...
pager_options => {
per_page => 100,
},
);

By default, the pager starts at page 1. This value can be modified by
setting the "start_page" parameter in the optional "pager_options" hash:

my $pager = Rose::DBx::Object::InternalPager->new(
# ...
pager_options => {
start_page => 17,
},
);

WHY THIS MODULE?
Even with "mysql_use_result" set, I've found that with large database
tables, clients run out of memory when they want to iterate over all
records of a table. At the cost of eventually creating anomalies, the
pager provides fine-grained control over the amount of memory used by
the database client application.

DISCLAIMER
Note that while this module uses "Rose::DB", it was released and will be
maintained *separately* from John Siracusa's project.

LEGALESE
Copyright 2007 by Mike Schilli, all rights reserved. This program is
free software, you can redistribute it and/or modify it under the same
terms as Perl itself.

AUTHOR
2007, Mike Schilli <[email protected]>